From 02600568758a0d74e14e9091e461c076b56ac252 Mon Sep 17 00:00:00 2001 From: john Date: Thu, 16 Apr 2020 23:16:57 +0200 Subject: [PATCH] refined text + add info for the random model generator --- README.md | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index d68dd50..7f3b6ed 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,12 @@ This module's name is an acronym for: *All possible boolean models link operator The only required input is a **single interactions file** which describes the network topology. Using that file, we build a boolean model whose equations are based on the following format: -`A *= ( B ) or ... ) and not ( C ) or ... )`, translating thus lines from the *sif* file like: `B -> A` and `C -| A`). +`A *= ( B or C or ... ) and not ( D or E or ... )`, translating thus lines from the *sif* file like e.g. `B -> A` and `D -| A`. Then we generate every possible boolean model out of the initial one, by changing the *link operator* (`and not` or `or not`) between the activator and inhibitor regulators in every possible permutation. +For models that have a large number of equations with a link operator, making thus the generation of all possible link operator models infeasible/untractable, we provide a *random* model generator. + # Install First, [install Gitsbe](https://druglogics.github.io/druglogics-doc/gitsbe-install.html). @@ -21,28 +23,38 @@ mvn clean install # Examples Get the list of all **provided user options**: -```shell script -java -cp target/abmlog-1.4.0-jar-with-dependencies.jar eu.druglogics.abmlog.BooleanModelGenerator +``` +java -cp target/abmlog-1.5.0-jar-with-dependencies.jar eu.druglogics.abmlog.BooleanModelGenerator ``` The example below will generate all the possible boolean models and export them with **no calculation of attractors**: ``` -java -cp target/abmlog-1.4.0-jar-with-dependencies.jar eu.druglogics.abmlog.BooleanModelGenerator --file=test/test.sif +java -cp target/abmlog-1.5.0-jar-with-dependencies.jar eu.druglogics.abmlog.BooleanModelGenerator --file=test/test.sif ``` The next example will generate the models and also calculate the **fixpoints (stable states)**: ``` -java -cp target/abmlog-1.4.0-jar-with-dependencies.jar eu.druglogics.abmlog.BooleanModelGenerator --file=test/test.sif --attractors=fixpoints +java -cp target/abmlog-1.5.0-jar-with-dependencies.jar eu.druglogics.abmlog.BooleanModelGenerator --file=test/test.sif --attractors=fixpoints ``` The examples above **use only 1 core** to generate the models, but this job can be **parallelized** by giving an extra parameter `--parallel` (so that all available cores are used): ``` -java -cp target/abmlog-1.4.0-jar-with-dependencies.jar eu.druglogics.abmlog.BooleanModelGenerator --file=test/test.sif --attractors=fixpoints --parallel +java -cp target/abmlog-1.5.0-jar-with-dependencies.jar eu.druglogics.abmlog.BooleanModelGenerator --file=test/test.sif --attractors=fixpoints --parallel ``` The example below will generate the models and also calculate the **minimal trapspaces**: ``` -java -cp target/abmlog-1.4.0-jar-with-dependencies.jar eu.druglogics.abmlog.BooleanModelGenerator --file=test/test.sif --attractors=trapspaces +java -cp target/abmlog-1.5.0-jar-with-dependencies.jar eu.druglogics.abmlog.BooleanModelGenerator --file=test/test.sif --attractors=trapspaces +``` + +--- + +For a boolean model that has e.g. 23 boolean equations with a link operator, generating all *2^23* possible link operator permutated models might be very challenging task (time-wise, space-wise, etc.). +Another case is that we may just want a *sample* out of the pool of all possible models. +These user cases are covered by a simple a random boolean model generator that produces structurally different models based on link operator mutations: + +``` +java -cp target/abmlog-1.5.0-jar-with-dependencies.jar eu.druglogics.abmlog.RandomBooleanModelGenerator --file=test/test.sif --num=100 ``` All attractors are calculated using the [BioLQM](https://github.com/colomoto/bioLQM) library. @@ -50,5 +62,8 @@ The result models are saved in both **BoolNet** (.bnet) and **Gitsbe** (.gitsbe) ## Output -The output consists of a `results__` directory which holds the `log` files and a `models` directory where the models are saved. Note that we split the `models` directory to several **if the amount of models exceeds 100000** thus avoiding filesystem issues that may arise. For large models, always try to use a machine with as many cores as possible (and the `--parallel` option of course) as well as check that the number of *inodes* (for Linux systems) is enough to store the total amount of models that will be generated (this information is outputed on the first lines of the main `log` file). +For both generators, the output consists of a `results__` directory which holds the `log` file(s) and a `models` directory where the models are saved. + +In the case of the `BooleanModelGenerator`, we split the `models` directory to several **if the amount of models exceeds 100000** thus avoiding filesystem issues that may arise. +For large models, always try to use a machine with as many cores as possible (and the `--parallel` option of course) as well as check that the number of *inodes* (for Linux systems) is enough to store the total amount of models that will be generated (this information is outputed on the first lines of the main `log` file).