Basic Simulation

Welcome to BNMPy! This guide will help you get started with Boolean Network and Probabilistic Boolean Network modeling.

Installation

To install BNMPy, navigate to the BNMPy directory and run:

cd BNMPy
pip install -e .

Dependencies

BNMPy requires the following packages:

  • pandas

  • numpy

  • typing

  • dataclasses

  • networkx

  • scipy == 1.15.2

  • pyswarms == 1.3.0

These will be installed automatically when you install BNMPy using the command above.

Quick Start

Loading a Network

BNMPy provides a unified function to load networks from files or strings. The function automatically detects the format (Boolean Network or Probabilistic Boolean Network):

import BNMPy

# From a text file
network = BNMPy.load_network("network.txt")

# Or from a string
network_string = """
A = A
B = C
C = !E
D = A | B
E = C & D
F = !A & B
"""
network = BNMPy.load_network(
    network_string,
    initial_state=[0, 0, 0, 0, 0, 0]
)

Network File Format

Network files use Boolean logic syntax:

# Example network file
Gene1 = Gene2 & Gene3
Gene2 = !Gene4
Gene3 = Gene1 | Gene5
Gene4 = Gene4
Gene5 = !Gene1 & Gene2

Supported operators:

  • & : AND

  • | : OR

  • ! : NOT

  • ( ) : Grouping

Initial States

You can specify initial states in two ways:

Array format (order matches gene order in network, can be obtained from network.nodeDict):

network = BNMPy.load_network_from_string(
    network_string,
    initial_state=[0, 1, 0, 1, 0, 0]
)

Dictionary format (explicit gene names):

network = BNMPy.load_network_from_string(
    network_string,
    initial_state={'A': 0, 'B': 1, 'C': 0, 'D': 1, 'E': 0, 'F': 0}
)

Gene order can be obtained from network.nodeDict.

Basic Simulation

Deterministic Update

Synchronous update (all nodes update simultaneously):

# Run for 10 steps, the trajectory will be printed
network.update(iterations=10)

# Access current state
print(network.nodes)

Stochastic Update

Add noise to represent biological uncertainty:

# Update with 5% flip probability
network.update_noise(p=0.05, iterations=10)

Steady State Analysis

Find stable states:

from BNMPy import SteadyStateCalculator

calc = SteadyStateCalculator(network)

# Monte Carlo method (more accurate)
steady_state = calc.compute_steady_state(
    method='monte_carlo',
    n_runs=20,
    n_steps=10000
)

# TSMC method (faster)
steady_state = calc.compute_steady_state(
    method='tsmc',
    epsilon=0.001
)

print(f"Steady state probabilities: {steady_state}")

Network Visualization

Create interactive network visualizations:

# Create visualization
BNMPy.vis_network(
    network,
    output_html="network.html",
    interactive=True
)

# Open network.html in a browser to view

Probabilistic Boolean Networks

Loading a PBN

PBNs are loaded using the same load_network() function. The function automatically detects the PBN format based on probabilities:

# From file
pbn = BNMPy.load_network("pbn_network.txt")

# Or from string
pbn_string = """
Gene1 = Gene2 & Gene3, 0.6
Gene1 = Gene4, 0.4
Gene2 = !Gene1
"""
pbn = BNMPy.load_network(pbn_string)

PBN Format

Each gene can have multiple rules with probabilities (format: gene = expression, probability):

# Gene with two alternative rules
GeneA = GeneB & GeneC, 0.7
GeneA = !GeneD, 0.3

# Gene with single rule (probability defaults to 1.0)
GeneB = GeneA

Probabilities must sum to 1.0 for each gene with multiple rules.

PBN Simulation

# Stochastic update (probabilistic rule selection)
pbn.update_noise(p=0.01, iterations=100)

# Calculate steady state
calc = SteadyStateCalculator(pbn)
steady_state = calc.compute_steady_state(
    method='monte_carlo',
    n_runs=20,
    n_steps=5000
)

Network Manipulation

Knockout/Knockdown

Fix specific nodes to certain values:

# Knockout (set to 0)
network.knockout('Gene1', value=0)

# Stimulate (set to 1)
network.knockout('Gene2', value=1)

# Undo knockouts
network.undoKnockouts()

Merging Networks

Combine multiple networks:

# Load networks
network1 = BNMPy.load_network("network1.txt")
network2 = BNMPy.load_network("network2.txt")

# Merge into Boolean Network using Inhibitor Wins method
merged_bn = BNMPy.merge_networks([network1, network2], method='Inhibitor Wins')

# Merge into PBN (creates alternative rules with probability 0.9)
merged_pbn = BNMPy.merge_networks([network1, network2], method='PBN', prob=0.9)

More Information

Examples

Check the Examples/ directory for Jupyter notebooks:

  • BN_simulation.ipynb - Basic Boolean network simulation

  • PBN_simulation.ipynb - Probabilistic Boolean network simulation

  • BN_PBN_steady_state.ipynb - Steady state analysis

  • knowledge_graph.ipynb - Knowledge graph integration

  • Optimization.ipynb - Parameter optimization

  • workflow_example.ipynb - Complete workflow

  • BN_compression.ipynb - Boolean network compression

Applications

See the pancreatic_cancer_simulation/ directory for real-world application examples on pancreatic cancer models.