Installation

MaBoSS can be used in three ways (see How To). The installation depends on which one you choose.

conda install -c colomoto pymaboss

pip install maboss
python -m maboss_setup

conda install -c colomoto maboss

git clone https://github.com/sysbio-curie/MaBoSS
cd MaBoSS
cmake -B build -S . -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=$HOME/.local
cmake --build build --parallel
cmake --install build --component executables

git clone https://github.com/sysbio-curie/MaBoSS
cd MaBoSS
cmake -B build -S . -G Ninja -DCMAKE_BUILD_TYPE=Release -DSTD_THREAD=1 `
  -DCMAKE_INSTALL_PREFIX=C:/MaBoSS
cmake --build build --parallel
cmake --install build --component executables

cmake -B build -S . -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=$HOME/.local -DMAXNODES=256 -DSBML=ON
cmake --build build --parallel
cmake --install build --component executables

How to use MaBoSS

There are three main ways of using MaBoSS. All of them rely on the same simulation engine and the same model format (a .bnd file describing the network and a .cfg file describing the simulation parameters).

pyMaBoSS is the Python interface of MaBoSS, and the most common way of using it. It allows to load, modify, simulate and analyse models from Python scripts or Jupyter notebooks, and is part of the CoLoMoTo Interactive Notebook.

To install pyMaBoSS, see Installation.

Example

This example uses the p53/Mdm2 model of the MaBoSS 2.0 tutorial. Download its bnd file and cfg file, then in Python:

import maboss

# Load the model
sim = maboss.load("example.bnd", "example.cfg")

# Set the initial condition: p53 and Mdm2 inactive, DNA damage with probability 0.6
sim.network.set_istate(["p53_b1", "p53_b2"], {(0, 0): 1, (1, 0): 0, (1, 1): 0})
sim.network.set_istate("Mdm2cyt", [1, 0])
sim.network.set_istate("Mdm2nuc", [1, 0])
sim.network.set_istate("DNAdam", [0.4, 0.6])

# Set the simulation parameters
sim.update_parameters(max_time=4, sample_count=10000)

# Run the simulation
res = sim.run()

The probability of each node to be active, as a function of time:

res.plot_node_trajectory()

The probabilities of the network states (each state is the list of its active nodes):

res.plot_trajectory()

The distribution of the states at the last time point:

res.plot_piechart()

All these results can also be obtained as pandas dataframes, for further analysis:

res.get_nodes_probtraj()

Time	p53_b1	p53_b2	Mdm2cyt	Mdm2nuc	DNAdam
0.0	0.0482	0.0019	0.0000	0.0196	0.6020
0.1	0.1369	0.0108	0.0006	0.0515	0.5978
0.2	0.2150	0.0251	0.0021	0.0774	0.5877
0.3	0.2796	0.0438	0.0047	0.0995	0.5740
0.4	0.3385	0.0674	0.0096	0.1189	0.5563

res.get_states_probtraj()

Time	<nil>	DNAdam	Mdm2nuc	Mdm2nuc -- DNAdam	…
0.0	0.3579	0.5743	0.0196	0.0000	…
0.1	0.2927	0.5190	0.0515	0.0000	…
0.2	0.2403	0.4675	0.0772	0.0000	…
0.3	0.1981	0.4234	0.0989	0.0000	…
0.4	0.1595	0.3843	0.1177	0.0000	…

Mutants are simulated by copying the simulation and forcing a node ON or OFF. Here, when nuclear Mdm2 is always active, p53 is no longer activated:

mutant = maboss.copy_and_mutate(sim, ["Mdm2nuc"], "ON")
mutant_res = mutant.run()
mutant_res.plot_piechart()

Models in SBML-qual format can be loaded with maboss.loadSBML("model.sbml", "model.cfg").

pyMaBoSS also provides sensitivity analysis, ensemble simulations and UPMaBoSS. See the pyMaBoSS documentation for the full API and more tutorials.

MaBoSS -c myfile.cfg -o myfile_out myfile.bnd

mpirun -np 2 MaBoSS_256n.MPI -c myfile.cfg -o myfile_out myfile.sbml

The tutorial shows how to simulate a large (133 nodes) prostate cancer model with each of these three tools.

Toy Model

Model description

This toy model is a simple example consisting of three nodes: A, B and C. A is activated by C and inhibited by B, B is activated by A, and C can only be degraded, when both A and B are inactive. This example illustrates the case of a simple loop in the transition graph. We study two cases, with two different rates for one of the transitions: fast and slow.

Influence graph

Transition graph

Since the model is small enough, we first ran it with an asynchronous updating strategy in GINsim, to visualize the transition graph. It shows the fixed point [ABC] = [000], and a cycle [101] → [111] → [011] → [001]. At [001], the system can either continue to cycle, or escape the cycle and reach the fixed point [000]. We explore the dynamics when this escape rate is slow or fast.

Model

Node A {
  rate_up = (C AND (NOT B)) ? $Au : 0.0;
  rate_down = B ? $Ad : 0.0;
}

Node B {
  rate_up = A ? $Au : 0.0;
  rate_down = A ? 0.0 : $Ad;
}

Node C {
  rate_up = 0.0;
  rate_down = ((NOT A) AND (NOT B)) ? $escape : 0.0;
}

The parameter $escape corresponds to the degradation of C: it is set to 10 in the fast case, and to 0.00001 in the slow case. All the nodes are initially active.

• BND file
• Configuration file, fast escape
• Configuration file, slow escape
• Configuration file, slow escape, long trajectories

MaBoSS -c Four_cycle_FEscape.cfg -o Four_cycle_FEscape Four_cycle.bnd
MaBoSS -c Four_cycle_SEscape.cfg -o Four_cycle_SEscape Four_cycle.bnd
MaBoSS -c Four_cycle_SEscape_long.cfg -o Four_cycle_SEscape_long Four_cycle.bnd

Results

We follow the probabilities of the states [1**] (A is active) and [000] (the fixed point), and the entropy and transition entropy, as functions of time.

With a fast escape, the probability to reach the fixed point tends to 1, and both entropies tend to 0.

With a slow escape, the early response does not show the fixed point: the system seems stuck in a limit cycle.

It is only after a long time that the system reaches the fixed point, and that the entropies reach 0. The two simulations show both the transient and the asymptotic behaviours.

Cell Cycle

Model description

The model is based on a published Boolean model of the mammalian cell cycle (Fauré et al., 2006). It describes the signaling network that controls the mammalian cell cycle.

Influence graph

Model

The model includes the possibility to simulate mutants: in the rates, the parameters $gene_del are set to 0 for the wild type, and to 1 to simulate a deletion. Two configuration files are provided: one with an initial condition corresponding to the start of the cell cycle, and one with a random initial condition, to study the stationary distributions.

• BND file
• Configuration file, start of the cell cycle
• Configuration file, random initial condition

MaBoSS -c cellcycle_runcfg.cfg -o cellcycle_runcfg cellcycle.bnd
MaBoSS -c cellcycle_runcfg_randinit.cfg -o cellcycle_runcfg_randinit cellcycle.bnd

Results

Probabilities of the active cyclins, and entropies, from the start of the cell cycle:

From a random initial condition, the simulation produces two clusters, which represent two indecomposable stationary distributions:

One cluster can be interpreted as a desynchronized proliferating cell population, and the other one is a fixed point, representing the G1 phase.

Cell Fate

Model description

The cell fate decision example is based on a published Boolean model (Calzone et al., 2010). It describes how the cell chooses between three different fates, apoptosis, survival (NFκB activation) and necroptosis (non-apoptotic cell death, NonACD), in response to the engagement of death receptors (through Fas and TNFR).

Influence graph

Model

The model includes the possibility to simulate mutants: in the rates, the parameters $gene_del (deletion) and $gene_oe (over-expression) are set to 0 for the wild type, and to 1 to simulate the mutant.

• BND file
• Configuration file (wild type)

MaBoSS -c CellFateModel.cfg -o CellFateOut_wt CellFateModel.bnd

Results

In the wild type, survival is transiently activated, before most of the cells die by apoptosis:

The three phenotypes are reachable, as in the published model, which showed the following phenotypes (A: apoptosis, N: necrosis, S: survival). The probabilities are not absolute values: they depend on the computation and on the details of the model (in the published model, the trajectories were computed over the transition graph).

The deletion of CASP8 leads to the disappearance of apoptosis, in accordance with published experiments:

p53 / MDM2

Model description

We consider a published model of the p53 response to DNA damage (Abou-Jaoudé et al., 2009). p53 interacts with Mdm2, which appears in two forms, cytoplasmic and nuclear. On one hand, p53 upregulates the level of cytoplasmic Mdm2, which is then transported into the nucleus. On the other hand, nuclear Mdm2 facilitates the degradation of p53. DNA damage participates in the degradation of Mdm2, and p53 inhibits the DNA damage signal by promoting DNA repair. p53 has three levels, encoded with two nodes: p53 (level at least 1) and p53_h (level 2).

Influence graph

Transition graph

The transition graph contains two cycles and a fixed point [p53 Mdm2C Mdm2N Dam] = [0 0 1 0], where nuclear Mdm2 is active and the rest is inactive.

Model

• BND file
• Configuration file

MaBoSS -c p53_Mdm2_runcfg.cfg -o p53_Mdm2 p53_Mdm2.bnd

Results

Probabilities of the levels 1 and 2 of p53, from the initial condition [p53 Mdm2C Mdm2N Dam] = [0 * 1 1]:

And the entropies:

Drosophila Patterning

Model description

The model of the segment polarity genes is based on a published model (Sánchez and Thieffry, 2003), and the analysis on another publication (Chaves and Albert, 2008), which studied the effect of random noise on this network. It represents the last step of Drosophila segmentation: a finer spatial patterning, driven by the segment polarity genes.

Influence graph

Model

The model consists of four identical signaling pathways, one for each of four adjacent cells. mRNA and proteins are considered separately: for instance, en is the mRNA of the protein EN. Cell-cell interactions are represented by connections between adjacent cells: for example, EN is transcriptionally activated by WG through the membrane, with the connections WG4→en1, WG2→en1, WG1→en2, WG3→en2, WG2→en3, WG4→en3, WG3→en4 and WG1→en4. The model is periodic: cell 1 is adjacent to cell 4.

Two transition rates are used: $rate_RNA = 1 for transcriptional influences, and $rate_protein = 10 for post-transcriptional influences. Random noise on every node is tuned by the parameter $noise. The model should produce the expected patterning (the reference state, in which none of the four cells are identical) from the initial state below, when the pair rule gene SLP has the pattern SLP1,2 = 0 and SLP3,4 = 1. Two cases are considered: no noise ($noise = 0) and low noise ($noise = 0.01).

• BND file
• Configuration file, no noise
• Configuration file, with noise
• Configuration file, with noise, for the stationary distribution

With noise, there is only one indecomposable stationary distribution, in which all the network states have a non-zero probability: the clustering of stationary distributions would artificially separate the estimates. A specific configuration file is provided to compute it, with a longer maximum time, fewer trajectories, and a clustering threshold set to 0.

MaBoSS -c D_Pattern_ContT_noIntNode.cfg -o D_Pattern_ContT_noIntNode D_Pattern_ContT.bnd
MaBoSS -c D_Pattern_ContT_noIntNode_noise.cfg -o D_Pattern_ContT_noIntNode_noise D_Pattern_ContT.bnd
MaBoSS -c D_Pattern_ContT_noIntNode_noise_4statdist.cfg -o D_Pattern_ContT_noIntNode_noise_4statdist D_Pattern_ContT.bnd

Results

Without noise, the expected patterning is reached, as shown by the trajectories of the Hamming distance distribution (HD), with the expected patterning as the reference state:

The asymptotic behavior consists of fixed points. The most probable one is the expected patterning:

With noise, the expected patterning is no longer stable:

The asymptotic behavior is then a single stationary distribution. Its most probable state corresponds to a "broad type" patterning, as defined in the publications above: two adjacent cells have identical node states.

EGF-TNF Signaling

Model description

This model was used as an example for the SBML-qual standard format, published by Chaouiya et al. (2013). It can be found in the BioModels database (BIOMD0000000562).

Influence graph

The model can be visualized with GINsim. In GINsim, set egf and tnfa as inputs (tick the box "Input" in the Modeling Attributes panel).

Model

The bnd and cfg files were exported from GINsim. In the configuration file, the initial state of every node is random, and ras, egf and akt are the output nodes. The simulations below are done without TNFα (tnfa initially inactive), until time 50.

• BND file
• Configuration file

MaBoSS -c chaouiya_maboss.cfg -e 'tnfa.istate = 0; max_time = 50; time_tick = 0.1' -o chaouiya chaouiya_maboss.bnd

A tutorial using this model in SBML-qual format is available here.

Results

The simulation reaches three fixed points:

They correspond to the stable states of the published model for the wild type:

The activities of ERK and RAS are transient, while AKT remains active when EGF is present:

And the corresponding results in the initial publication:

Reference

Chaouiya C, Bérenguier D, Keating SM, Naldi A, Van Iersel MP, Rodriguez N, Dräger A, Büchel F, Cokelaer T, Kowal B, et al. SBML qualitative models: a model representation format and infrastructure to foster interactions between qualitative modelling formalisms and tools. BMC Systems Biology. 2013;7:135. doi:10.1186/1752-0509-7-135

Prostate Cancer

Model description

This model, published by Montagud et al. (eLife, 2022), describes the signaling pathways involved in prostate cancer. Without any mutation, it can be considered as a model of healthy prostate cells. It was then personalized to the data of patients (TCGA) and cell lines, to study their response to treatments.

Influence graph

Model

With 133 nodes, it is a large model, which requires an executable of MaBoSS supporting more than 128 nodes, such as MaBoSS_256n (see Installation). The model files are provided with the article (PROFILE_v2 repository).

• BND file
• Configuration file
• SBML-qual file
• Ten personalized patient models, included in the archive below

MaBoSS_256n -c Montagud2022_Prostate_Cancer.cfg -o results Montagud2022_Prostate_Cancer.bnd

The tutorial shows how to simulate this model with pyMaBoSS, WebMaBoSS and the command line.

Results

With random inputs, the simulation explores all the possible phenotypes:

Healthy cells mostly exhibit quiescence (neither proliferation nor apoptosis) in the absence of any input (Figure 3A of the article):

When nutrients and growth factors (EGF) are present, proliferation is activated. The inhibition of MYC_MAX blocks it (Appendix 1, figure 34):

Among several candidate nodes, the inhibition of AKT, EGFR or MYC_MAX blocks proliferation in the growth condition:

The personalized models of patients show very different phenotypes:

And they respond differently to the inhibition of MYC_MAX, in the growth condition: proliferation is reduced below 10% only for some of them.

Sizek Cell Cycle

Model description

This model, published by Sizek et al. (PLoS Comput Biol, 2019), integrates growth signaling, the regulatory network controlling the mammalian cell cycle, and apoptosis. With 87 nodes, it describes how a generic human cell regulates proliferation and apoptosis.

The simulations below are adapted from the tutorial of the CoLoMoTo software suite (Noël et al., Interface Focus, 2025). Its complete notebook also analyses this model with other tools of the suite (GINsim, bioLQM, BNS...).

Influence graph

Model

The model is available in the GINsim model repository. The MaBoSS files were obtained by converting it with bioLQM. As the model has 87 nodes, it requires an executable of MaBoSS supporting more than 64 nodes, such as MaBoSS_128n (see Installation).

• BND file
• Configuration file (all initial values set to 0)
• SBML-qual file and GINsim file

Results

The simulations start from the initial state defined by Sizek et al. (their figure 6), with 5000 trajectories up to time 200. In the wild type, a transient cyclic-like behaviour is eventually lost due to the spontaneous activation of Casp3: the apoptotic stable state progressively dominates. The entropy rises abruptly then slowly decreases, while the transition entropy stays close to zero after a small peak, suggesting a transient periodic behaviour.

With the death signal TRAIL active at the initial state, Casp3, and thus apoptosis, rise much faster, and the system reaches a stable state:

The ectopic activity of Casp8 drives the cells into apoptosis faster. When Casp8 is knocked down, Casp3 is still ultimately activated, as in the wild type: in this model, apoptosis can occur even without Casp8.

Screening the loss-of-function and ectopic activation of five nodes, we look for mutants blocking apoptosis (Casp3 below 1%) while keeping the cell cycle active (CyclinE above 15%):

Both the sustained activations of p110 and FoxO3 turn off Casp3 while maintaining the cell cycle:

In the wild type, the cyclins show the expected sequence of peaks: CyclinE, then CyclinA, then CyclinB. As MaBoSS reports mean probabilities over many trajectories, these oscillations are rapidly damped.

MaBoSS can also estimate the frequencies of the transitions between the activity patterns of selected nodes, over all the individual trajectories: a compressed state transition graph, where darker arrows are more probable transitions. Starting from the state without active cyclin (G0), the most probable sequence activates CyclinE, then CyclinA, inactivates CyclinE, activates CyclinB, then inactivates CyclinA and finally CyclinB, completing the cycle.

Adding Casp3 to the observed nodes shows two main ways to trigger apoptosis: from the state without active cyclin (G0), and from the state where only CyclinB is active (G2/M).

The ectopic activity of p110_H completely disables the activation of apoptosis, and maintains the oscillatory behaviour:

UPMaBoSS Cell Fate

Model description

UPMaBoSS simulates the dynamics of a population of cells, taking into account both their intracellular and intercellular regulations. The logical model of an individual cell is a MaBoSS model. At regular intervals, the simulation is stopped, and the population is updated according to the nodes representing cell death and division, and to the nodes accounting for signals coming from other cells.

This example is a modified version of the cell fate model: it accounts for the activation of TNFα by NFκB, which acts on the other cells (a paracrine loop), and includes two output nodes, Division and Death.

Model

UPMaBoSS needs three files: the model (bnd), the configuration (cfg), and the update file (upp), which describes the population updates. In the update file, $TNF_induc is updated at each step with the proportion of living cells in which NFκB is active, and the population is updated 48 times, every hour.

• BND file
• Configuration file
• Update file

death = Death;
division = Division;
$TNF_induc u= $ProdTNF_NFkB*p[(NFkB,Death) = (1,0)];
steps = 48;

Results

A MaBoSS simulation of a single cell over 48 hours, after a pulse of TNF, shows the first transient effects during the first hours: updating the population every hour captures them.

The paracrine TNF loop leads to a significant decrease of the population size:

With two successive treatments, the population that received an initial pulse of TNF is resistant to the second, constant TNF treatment: its size does not decrease, while the population that did not receive the pulse is strongly reduced:

Simulating the deletion of each internal node shows which mutations abolish this resistance. The relative change is the population ratio with the second TNF treatment, divided by the one without it: the treatment has an effect when it is below 1 (in blue).

For some mutants (the deletions of IKK, NFκB, cIAP or RIP1ub), the TNF treatment reduces the population size, whether the cells received a pulse of TNF or not: there is no resistance. For others, including the wild type (and for instance the BCL2 or XIAP deletions), this effect disappears when the cells received a pulse of TNF. The deletion of TNFR leads to insensitive cells.

Sensitivity to the update time

The population dynamics are robust to the update time: updating the population every hour or every 15 minutes gives almost identical results.

PROFILE

PROFILE is a methodology to personalize logical models with the omics data of patients or cell lines (mutations, copy number alterations, RNA and protein levels), and to simulate the personalized models with MaBoSS. The data are mapped on the nodes of a generic model, which is then personalized either by fixing the activity of nodes (for instance for mutations), or by tuning their initial states and transition rates according to continuous data. The simulations of the personalized models can then be compared to the clinical features of the patients, or to the response of cell lines to drugs.

PROFILE was used to stratify breast cancer patients (Béal et al., 2019), to study the response of melanoma and colorectal cancer cell lines to BRAF inhibitors (Béal et al., 2021), and to build patient-specific models of prostate cancer that guide personalized treatments (Montagud et al., 2022). Some of these personalized models are simulated in the prostate cancer example of the repository of models.

PhysiBoSS

PhysiBoSS is a multiscale modelling framework, which integrates the intracellular Boolean models simulated by MaBoSS into the agent-based framework PhysiCell. Each cell of the simulation is an agent with its own MaBoSS model, whose nodes are connected to the behaviour of the cell (division, death, migration, secretion...) and to its environment (substrates, contacts with other cells). PhysiBoSS thus allows to study how intracellular signaling shapes the behaviour of a whole population of cells in its physical environment.

PhysiBoSS 2.0 is a redesign of the original PhysiBoSS as an add-on of PhysiCell, keeping a decoupled, maintainable and model-agnostic design. It is developed by Institut Curie and the Barcelona Supercomputing Center, and is open source (BSD 3-Clause license). A step-by-step tutorial shows how to build multiscale models with PhysiBoSS.

UPMaBoSS

UPMaBoSS (Update Population MaBoSS) simulates the dynamics of a population of interacting cells. The behaviour of each cell is described by a MaBoSS model. At regular intervals, the simulation is stopped, and the population is updated according to the nodes representing cell death and cell division, and to the nodes accounting for signals coming from other cells. The simulation then continues with the updated conditions. UPMaBoSS requires only moderate computational power, and is easy to use with an existing MaBoSS model.

UPMaBoSS is part of pyMaBoSS. Besides the model (bnd) and configuration (cfg) files, it uses an update file (upp), which describes the population updates:

import maboss

model = maboss.load("model.bnd", "model.cfg")
upp = maboss.UpdatePopulation(model, "model.upp")
result = upp.run("results")
result.get_population_ratios()

The UPMaBoSS cell fate example of the repository of models reproduces the analyses of the UPMaBoSS article, with downloadable notebooks.

EnsembleMaBoSS

The available data are often not sufficient to determine a single logical model: tools such as BoNesis can instead synthesize an ensemble of models, all compatible with the data. EnsembleMaBoSS simulates such ensembles of models with MaBoSS: it computes the probability trajectories over the whole ensemble, and can also keep the results of each individual model, to compare them or to cluster the models according to their behaviour.

With the MaBoSS command line, the models of the ensemble are simulated with a common configuration file:

MaBoSS --ensemble -c ensemble.cfg -o results model_1.bnet model_2.bnet ...

The option --save-individual also writes the results of each model, and --random-sampling randomly selects the model simulated for each trajectory. With pyMaBoSS, an ensemble is loaded from a folder (or a zip archive) of models in BoolNet format:

import maboss

ensemble = maboss.Ensemble("models", sample_count=10000, max_time=50)
result = ensemble.run()
result.plot_piechart()

The BoolNet files must not contain the optional header line targets, factors.

AstroLogics builds on these simulations to cluster the models of an ensemble according to their dynamics, and to identify the logical rules that differentiate them.

ExaStoLog

MaBoSS estimates the probabilities of the states of a model by simulating many stochastic trajectories. For small models, ExaStoLog (EXAct solving of STOchastic LOGical models) computes instead the exact stationary probabilities of the continuous-time Markov chain defined by the model, without sampling. Being fast and exact, it allows to perform parameter sensitivity analyses, and to fit the transition rates of a model to data.

ExaStoLog is a MATLAB toolbox (MATLAB 2015b or later), developed in the Computational Systems Biology of Cancer group at Institut Curie. Models are given in the BoolNet format, or as logical formulas written in MATLAB. As the exact method requires exploring the state space, it is currently limited to models of up to about twenty nodes.

Publications

Documentation

The rest of this page describes MaBoSS itself. The model files and the results are the same whichever way MaBoSS is used, so this information is also useful with pyMaBoSS and WebMaBoSS.

Network file (.bnd)

The network file describes the nodes of the network, their logic and their transition rates. Each node is described as follows:

node NODE_NAME {
  node_var1 = expr1;
  node_var2 = expr2;
  ...
}

Comments are written as in C++ or Java (// or /* */). An expression is an arithmetic and logical combination of node names (denoting the node states), external variables (defined in the configuration file), node variables, and integer or double literals.

Node variables

Any node variable can be defined and used, but three of them have a special meaning:

Lexical units

Operators

In decreasing order of priority (same precedence as in C, C++ and Java):

The built-in functions exp(value[, base]) and log(value[, base]) can also be used in expressions.

Example

// Basic network example

node A {
  rate_up = 1.1;
  rate_down = $A_rate_down * 10.2;
  // $A_rate_down must be defined in the configuration file
}

node B {
  // tmp is a node variable introduced for convenience,
  // to define rate_up and rate_down without code duplication
  tmp = NOT A OR C;
  rate_up = @tmp;
  rate_down = NOT @tmp ? $B_var * 12. : 0.;
}

node C {
  rate_up = $var2 < 10 ? NOT B : A OR B;
  rate_down = A AND B;
}

node D {
  logic = A OR (NOT B XOR C);
}

Since version 2.4, MaBoSS can also read networks in the SBML-qual format: the SBML file is then given instead of the .bnd file.

Configuration file (.cfg)

The configuration file defines the initial conditions, the values of the external variables, the output nodes and the simulation parameters. Each parameter is assigned as follows:

parameter = value;

where value may be a boolean (TRUE or FALSE), an integer, a double, or an expression. Comments are written as in C++ or Java.

Node parameters

Simulation parameters

Example

// External variables used in the network file
$A_rate_down = 0.1;
$B_var = 2;
$var2 = 23;

// Initial conditions
A.istate = 0;
$p0 = 1;
$p1 = 2;
$p2 = 1;
$p3 = 4;
[B, C].istate = $p0 [0, 0], $p1 [0, 1], $p2 [1, 0], $p3 [1, 1];
[D].istate = $p0 [0], ($p1*2) [1];

// Outputs
B.is_internal = 1;
C.is_internal = 1;
C.refstate = 1;

// Simulation parameters
sample_count = 1000;
max_time = 100;
time_tick = 0.5;
discrete_time = 0;
use_physrandgen = FALSE;
seed_pseudorandom = 100;
statdist_traj_count = 100;
thread_count = 4;

Command line

Running a simulation

MaBoSS -c CONFIG_FILE -o OUTPUT_PREFIX NETWORK_FILE

The network file can be a .bnd file or an SBML-qual file. The -c option can be given several times: the configuration files are then read in the given order.

Main options

For instance, to run a simulation with a modified parameter and variable, without editing the configuration file:

MaBoSS -c model.cfg -e 'max_time = 50' -v '$var2=5' -o results model.bnd

To start a new model, generate a configuration template from the network file, then edit it:

MaBoSS -t model.bnd > model.cfg

The executable MaBoSS supports networks of up to 64 nodes. For larger networks, use an executable built for more nodes, such as MaBoSS_128n or MaBoSS_256n (see Installation).

Output files

The output files are tab-separated tables (or JSON files with --format json), named after the output prefix:

These files can be analysed with pyMaBoSS, or with your own scripts.

Reference cards

PDF versions of this documentation: MaBoSS 2.0 reference card, description of the output files, MaBoSS 1.3.8 reference card.

Tutorials

Simulating a prostate cancer model

This tutorial, written for MaBoSS 2.5.0, shows how to simulate a published model with each of the three ways of using MaBoSS. The model, by Montagud et al. (eLife, 2022), describes the pathways involved in prostate cancer. With 133 nodes, it is a large model. More analyses of this model are available in the repository of models.

Download the model files, provided with the article (PROFILE_v2 repository): bnd file, cfg file and SBML-qual file.

First, install pyMaBoSS. Then, in Python, import maboss and load the model:

import maboss

model = maboss.load("Montagud2022_Prostate_Cancer.bnd", "Montagud2022_Prostate_Cancer.cfg")

The model can also be loaded from its SBML-qual file:

model = maboss.loadSBML("Montagud2022_Prostate_Cancer.sbml", "Montagud2022_Prostate_Cancer.cfg")

Once loaded, the model is simulated with:

result = model.run()

We can then plot the distribution of the final states (the last time point of the probability trajectories). Only the output nodes, i.e. the nodes that are not declared as internal, appear in the states.

result.plot_piechart()

We can also plot the complete trajectories:

result.plot_trajectory()

Finally, the probability trajectories can be obtained as a pandas dataframe, for further analysis:

data = result.get_states_probtraj()

pyMaBoSS offers many more possibilities (mutants, parameter changes, sensitivity analysis...): see the pyMaBoSS documentation, and the notebook reproducing the results of the article.

Open WebMaBoSS, and create a new project or use an existing one. In the project, open the Load model interface: give the model a name, choose MaBoSS as the model type, select the bnd and cfg files of the model, and load it into the project.

Once loaded, click on the model, open the Simulation menu and create a new simulation. The simulation settings can be changed, or the default ones kept: click Submit to run the simulation.

The results are displayed as soon as the simulation finishes. The first view shows the distribution of the final states:

Dedicated tabs show the trajectories of the state probabilities, the trajectories of the node probabilities, and the fixed points:

First, install MaBoSS. As the model has 133 nodes, we need an executable supporting at least 133 nodes, such as MaBoSS_256n, provided by the conda package, or compiled from source with the CMake option -DMAXNODES=256.

Then, simulate the model:

MaBoSS_256n -c Montagud2022_Prostate_Cancer.cfg -o results Montagud2022_Prostate_Cancer.bnd

The SBML-qual file can also be used instead of the bnd file:

MaBoSS_256n -c Montagud2022_Prostate_Cancer.cfg -o results Montagud2022_Prostate_Cancer.sbml

With MaBoSS compiled with MPI, the simulation can be distributed, for instance on two MPI nodes:

mpirun -np 2 MaBoSS_256n.MPI -c Montagud2022_Prostate_Cancer.cfg -o results Montagud2022_Prostate_Cancer.sbml

Result files

The simulation produces several result files (see Documentation). The first one, results_fp.csv, lists the fixed points reached during the simulation. This model has a very large number of them (1758). The file starts with the number of fixed points, then lists each fixed point with its probability, the full description of its state, and the value of each node.

The second file, results_probtraj.csv, contains the probability trajectories. As most nodes of this model are declared as internal, the states are only made of a few output nodes. Each line contains the time, the transition entropy and its error, the entropy, and the Hamming distance distribution, followed by the probability and error of each state reached at this time.

These raw files can be analysed with your own scripts. A simpler solution is to use pyMaBoSS, which runs the simulations and makes it easy to visualize the results.

Source: MaBoSS 2.5.0 tutorial on GitHub.

More tutorials

The Team

MaBoSS is developed by the Computational Systems Biology of Cancer group at Institut Curie.

Gautier Stoll

The BoSS of MaBoSS

Laurence Calzone

MaBoSS Muse

Eric Viara

MaBoSS Old Bearbed

Vincent Noël

MaBoSS Magic

Contact

Email

For any question about MaBoSS, write to maboss.bkmc@gmail.com.

Bug reports and feature requests

To report a bug or suggest a new feature, please open an issue on GitHub, in the repository of the corresponding tool:

• MaBoSS (simulation engine and command-line tool);
• pyMaBoSS (Python interface);
• WebMaBoSS (web interface).