Basic Simulation

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

Installation

Install the released package with pip:

pip install KGBN

For development from a local checkout, navigate to the repository and run:

cd KGBN
pip install -e .

Dependencies

Core KGBN installs its runtime dependencies automatically:

  • numpy

  • pandas

  • scipy

  • networkx

  • igraph

  • pyvis

  • matplotlib

  • boolean.py

  • pyswarms

Sensitivity analysis additionally uses SALib and tqdm; install those with pip install "KGBN[sensitivity]" or pip install "KGBN[all]".

Quick Start

Loading a Network

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

import KGBN

# From a text file
network = KGBN.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 = KGBN.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 = KGBN.load_network_from_string(
    network_string,
    initial_state=[0, 1, 0, 1, 0, 0]
)

Dictionary format (explicit gene names):

network = KGBN.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 KGBN 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
KGBN.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 = KGBN.load_network("pbn_network.txt")

# Or from string
pbn_string = """
Gene1 = Gene2 & Gene3, 0.6
Gene1 = Gene4, 0.4
Gene2 = !Gene1
"""
pbn = KGBN.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 = KGBN.load_network("network1.txt")
network2 = KGBN.load_network("network2.txt")

# Merge into a Boolean Network using Inhibitor Wins
merged_bn_string = KGBN.merge_networks([network1, network2], method='Inhibitor Wins')
merged_bn = KGBN.load_network(merged_bn_string, network_type='bn')

# Merge into a PBN (creates alternative rules with probability 0.9)
merged_pbn_string = KGBN.merge_networks([network1, network2], method='PBN', prob=0.9)
merged_pbn = KGBN.load_network(merged_pbn_string, network_type='pbn')

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 Examples/KGBN_workflow_toy.ipynb for a compact workflow example.