caspo’s documentation

Install

In what follows we describe three alternative ways to install caspo:

Note that using pip requires the user to install all dependencies manually. Since installing such dependecies requires basic skills on how to compile and deploy third-party python packages it is only recommended for experienced users. Therefore, we recommend less experienced users to use either Docker or Anaconda.

Using Docker

Follow the instructions to install Docker at http://docs.docker.com. Once you have installed Docker on your computer, you can use the caspo docker image as follows. First you need to pull the image with:

$ docker pull bioasp/caspo

That’s it. Now, you should be able to run caspo with docker. Usually, caspo will need to read and writes files to do their work. A possible way to this using docker is as follows. For safety, we recommend to use an empty directory:

$ mkdir caspo-wd && cd caspo-wd

Next, let’s take a look to the command needed to run docker, mount the current directory (caspo-wd) into the docker container, and use it as the working directory for running caspo:

$ docker run --rm -v $PWD:/caspo-wd -w /caspo-wd bioasp/caspo

If you don’t want to write the full docker command every time you run caspo, you may want to create a shell script or alias as a shortcut. For example, you may want to create a file in your working directory named caspo and with the following content:

#!/bin/sh
docker run --rm -v $PWD:/caspo-wd -w /caspo-wd bioasp/caspo $@

Next, make the file executable:

$ chmod a+x caspo

Now you can run caspo with just:

$ ./caspo

Next, go to Testing your installation.

Using Anaconda

NOTE: In order for this method to work, the standard C/C++ libraries must be installed in your system. In Linux you need to have gcc >= 4.9 while in OS X 10.9+ you need to install Xcode and the command line tools.

Follow the instructions to install Anaconda at https://www.continuum.io/downloads. Next, download the file environment.yml and use it to create a conda environment where caspo will be installed:

$ conda env create --file environment.yml
Using Anaconda Cloud api site https://api.anaconda.org
Fetching package metadata ...............
Solving package specifications: ..........
...
Linking packages ...
[      COMPLETE      ]|####################################################| 100%
#
# To activate this environment, use:
# $ source activate caspo-env
#
# To deactivate this environment, use:
# $ source deactivate
#

That’s it. Now, you should be able to run caspo within the created environment. Note that you need to activate the environment every time you open a new terminal.

Next, go to Testing your installation.

Using pip

NOTE: Depending on your platform and whether you decide to use the system’s python or a virtual environment, this method may require you to install additional compilers and libraries beforehand.

Essentially, you will need to have python 2.7.x and some of the standard scientific python packages installed. Download the file requirements.txt and install caspo by running:

$ pip install -r requirements.txt

Alternatively, you could download caspo sources and after unpacking run:

$ python setup.py install

Note that installing caspo in this way does not force the installation of any of the runtime dependencies. In other words, you take full responsibility of installing all required packages to run caspo successfully.

Also, the python module of the answer set programming solver clingo must be available in the PYTHONPATH. After unpacking clingo sources, you will find detailed instructions about how to compile and build the python module in the INSTALL file.

Next, go to Testing your installation.

Testing your installation

Once caspo is installed you can test the installation as follows. To start with, you can ask for help:

$ caspo --help
usage: caspo [-h] [--quiet] [--out O] [--version]
             {learn,classify,predict,design,control,visualize,test} ...

Reasoning on the response of logical signaling networks with ASP

optional arguments:
  -h, --help            show this help message and exit
  --quiet               do not print anything to standard output
  --out O               output directory path (Default to './out')
  --version             show program's version number and exit

caspo subcommands:
  for specific help on each subcommand use: caspo {cmd} --help

  {learn,classify,predict,design,control,visualize,test}

A more interesting test is to run caspo test to make sure all subcommands are working:

$ caspo test --help
usage: caspo test [-h] [--threads T] [--conf C]
                  [--testcase {Toy,LiverToy,LiverDREAM,ExtLiver}]

optional arguments:
  -h, --help            show this help message and exit
  --threads T           run clingo with given number of threads
  --conf C              threads configurations (Default to many)
  --testcase {Toy,LiverToy,LiverDREAM,ExtLiver}
                        testcase name

This subcommand will run all subcommands in caspo using different testcases (see --testcase argument):

$ caspo test

Testing caspo subcommands using test case Toy.

Copying files for running tests:
  Prior knowledge network: pkn.sif
  Phospho-proteomics dataset: dataset.csv
  Experimental setup: setup.json
  Intervention scenarios: scenarios.csv

$ caspo --out out learn out/pkn.sif out/dataset.csv 10 --fit 0.1 --size 5

Optimum logical network learned in 0.0183s
Optimum logical networks has MSE 0.1100 and size 7
5 (nearly) optimal logical networks learned in 0.0082s
Weighted MSE: 0.1100

$ caspo --out out classify out/networks.csv out/setup.json out/dataset.csv 10

Classifying 5 logical networks...
3 input-output logical behaviors found in 0.2029s
Weighted MSE: 0.1100

$ caspo --out out design out/behaviors.csv out/setup.json

1 optimal experimental designs in 0.0043s

$ caspo --out out predict out/behaviors.csv out/setup.json

Computing all predictions and their variance for 3 logical networks...

$ caspo --out out control out/networks.csv out/scenarios.csv

3 optimal intervention strategies found in 0.0047s

$ caspo --out out visualize --pkn out/pkn.sif --setup out/setup.json
        --networks out/networks.csv --midas out/dataset.csv 10
        --stats-networks=out/stats-networks.csv --behaviors out/behaviors.csv
        --designs=out/designs.csv --predictions=out/predictions.csv
        --strategies=out/strategies.csv --stats-strategies=out/stats-strategies.csv

If everything works as expected, you should find a directory named out in the current directory having all the output files generated by caspo.

Usage

Input/Output files

Input and output files in caspo are mostly comma separated values (csv) files. Next, we describe all files either consumed or produced when running caspo subcommands.

Prior knowledge network

A prior knowledge network (PKN) is given using the simple interaction format (SIF). Lines in the SIF file must specify a source node, an edge sign (1 or -1), and one target node. Note that SIF format specification also consider several target nodes per line but this is not supported in caspo at the moment. In the example shown below we would say that a and b have a positive influence over d while c has a negative influence over d.

a 1 d
b 1 d
c -1 d
b 1 e
c 1 e

Experimental setup

An experimental setup is given using the JSON format. The JSON file must specify three list of node names, namely, stimuli, inhibitors, and readouts. In the following example, a, b, and c are stimuli, d is an inhibitor while f and g are readouts.

{
  "stimuli": ["a", "b", "c"],
  "inhibitors": ["d"],
  "readouts": ["f", "g"]
}

Experimental dataset

A phospho-proteomics dataset is given using the MIDAS format. Notably, MIDAS format considers time-series data but as we will see later, caspo always requires the user to define the time-point of interest when reading a MIDAS file (see Learn). Different time-points of data acquisition are specified in columns with prefix DA:.

In the example shown below, looking at the third row we would say that, when a and c are present, i.e. stimulated, and d is not inhibited, i.e., the inhibitor of d is not present, readouts for f and g at time-point 10 are 0.9 and 0, respectively. Meanwhile, looking at the four row we would say that when a and c are present and d is inhibited (the inhibitor of d it is present), readouts for f and g at time-point 10 are 0.1 and 0.9, respectively.

TR:Toy:CellLine TR:a TR:b TR:c TR:di DA:f DA:g DV:f DV:g
1 1 0 1 0 0 0 0 0
1 1 0 1 1 0 0 0 0
1 1 0 1 0 10 10 0.9 0
1 1 0 1 1 10 10 0.1 0.9

Logical networks

Logical networks are given using a csv file as follows. We assume that every logical mapping in a given network is in disjunctive normal form (DNF). Thus, columns header specify all possible conjunctions targeting any given node, e.g. d<-a+!c (d equals a AND NOT c). Then, each row describes a logical network by specifying which conjunctions are present (1) in the network or not (0). Whenever, two conjunctions targeting the same node are present in a given network they are connected using OR. For example, if we look at the first row in the example below, since d<-a and d<-b+!c are both present, the complete logical mapping for d would be: d equals a OR (b AND NOT c).

Additional columns could be included to give more details related to each network, e.g., MSE, size, or the number of networks having the same input-output behavior. See the output csv files in subcommands Learn (networks.csv) or Classify (behaviors.csv). However, when parsing a csv file of logical networks, caspo ignores columns that cannot be parsed as logical mappings except for a column named networks which is interpreted as the number of networks exhibiting the same input-output behavior (including the representative network being parsed). In particular, such a column will be relevant when computing weighted average predictions (see Predict).

e<-c e<-b d<-a d<-!c d<-b d<-a+!c d<-b+!c f<-d+e
1 1 1 0 0 0 1 0
1 1 1 1 0 0 0 0
1 1 1 0 1 0 1 0
1 1 1 1 1 0 0 0
1 1 1 0 0 0 1 0

Basic statistics over a family of logical networks are described using a csv file as follows. For each logical mapping conjunction we compute its frequency of occurrence over all logical networks in the family. Also, mutually exclusive/inclusive pairs of mapping conjunctions are identified.

mapping frequency exclusive inclusive
e<-c 1.0000    
e<-b 1.0000    
d<-a 1.0000    
d<-b+!c 0.6000 d<-!c  
d<-!c 0.4000 d<-b+!c  
d<-b 0.4000    

Experimental designs

An experimental design is essentially a set of experimental perturbations, i.e., various combinations of stimuli and inhibitors. But also, we describe an experimental design by how its perturbations discriminate the family of input-output behaviors (see Design for an example visualization). Experimental designs are given using a csv file as shown below. A column named id is used to identify rows corresponding to the same experimental design. Next, columns with prefix TR: correspond to experimental perturbations in the same way as in MIDAS format. Finally, for each combination of stimuli and inhibitors in a given experimental design, we count pairwise differences generated over specific readouts (columns with prefix DIF:) and pairs of behaviors being discriminated by at least one readout (column named pairs).

In the example below we show one experimental design made of two experimental perturbations. The first perturbation requires b and c to be stimulated, it generates 2 pairwise differences over f, and it discriminates 2 pairs of behaviors. The second perturbation requires b to be stimulated and d to be inhibited, it generates 1 pairwise difference over f, 1 pairwise difference over g, and it discriminates 1 pair of behaviors.

id TR:a TR:b TR:c TR:di DIF:f DIF:g pairs
0 0 1 1 0 2 0 2
0 0 1 0 1 1 1 1

Logical predictions

Based on the input-output classification (see Classify), we can compute the response of the system for every possible perturbation by combining the ensemble of predictions from all input-output behaviors. Thus, predictions of a logical networks family are given using a csv file as the (incomplete) example below. For each possible combination of stimuli and inhibitors (columns with prefix TR:), the prediction for any readout node will be the weighted average (columns with prefix AVG:) over the predictions from all input-output behaviors and where each weight corresponds to the number of networks exhibiting the corresponding behavior. Also, the mean variance over all predictions is computed (columns with prefix VAR:). See Predict for an example visualization of readout mean variances.

TR:a TR:c TR:b TR:di AVG:g AVG:f VAR:g VAR:f
1 0 0 0 0.0 0.0 0.0 0.0
0 1 0 0 0.0 0.0 0.0 0.0
0 0 1 0 1.0 0.8 0.0 0.16
0 1 1 0 0.0 0.4 0.0 0.24

Intervention scenarios

An intervention scenario is simply a pair of constraints and goals over nodes in a logical network. Thus, intervention scenarios are given using a csv file as shown below. Each column specifies either a scenario constraint (SC:) or a scenario goal (SG:) over any node in the network. Next, each row in the file describes a different intervention scenario. Values can be either 1 for active, -1 for inactive, or 0 for neither active nor inactive. That is, a 0 means there are no constraint nor expectation over that node in the corresponding scenario.

In the example below, we show two intervention scenarios. The first scenario requires that both, f and g to reach the inactive state under the constraint of a being active. The second scenario required only f to reach the active state under no constraints.

SC:a SG:f SG:g
1 -1 -1
0 1 0

Intervention strategies

An intervention strategy is a set of Boolean interventions over nodes in a logical network. Thus, intervention strategies are given using a csv file as shown below. Each column specifies a Boolean intervention over a given node (prefix TR: is used for consistency with MIDAS and other csv files). Next, each row in the file describes a different intervention strategy. Values can be either 1 for active, -1 for inactive, or 0 for neither active nor inactive. That is, a 0 means there is no intervention over that node in the corresponding strategy.

TR:c TR:b TR:e TR:d
0 0 -1 0
-1 -1 0 0
1 0 0 -1

Basic statistics over a set of intervention strategies are described using a csv file as follows. For each Boolean intervention we compute its frequency of occurrence over all strategies in the set. Also, mutually exclusive/inclusive pairs of interventions are identified.

intervention frequency exclusive inclusive
c=-1 0.3333   b=-1
c=1 0.3333   d=-1
b=-1 0.3333   c=-1
e=-1 0.3333    
d=-1 0.3333   c=1

Command Line Interface

The command line interface (CLI) of caspo offers various subcommands:

  • learn: for learning a family of (nearly) optimal logical networks
  • classify: for classifying a family of networks wrt their I/O behaviors
  • design: for designing experiments to discriminate a family of I/O behaviors
  • predict: for predicting based on a family of networks and I/O behaviors
  • control: for controlling a family of logical networks in several intervention scenarios
  • visualize: for basic visualization of the subcommands outputs
  • test: for running all subcommands using various examples

Next, we will see how to run each subcommand and describe their outputs.

If you haven’t done it yet, start by asking caspo for help:

$ caspo --help
usage: caspo [-h] [--quiet] [--out O] [--version]
             {learn,classify,predict,design,control,visualize,test} ...

Reasoning on the response of logical signaling networks with ASP

optional arguments:
  -h, --help            show this help message and exit
  --quiet               do not print anything to standard output
  --out O               output directory path (Default to './out')
  --version             show program's version number and exit

caspo subcommands:
  for specific help on each subcommand use: caspo {cmd} --help

  {learn,classify,predict,design,control,visualize,test}

Learn

This subcommand implements the learning of logical networks given a prior knowledge network and a phospho-proteomics dataset [1, 2]. In order to account for the noise in experimental data, a percentage of tolerance with respect to the maximum fitness can be used, e.g., we use 4% in the example below. Analogously, in order to relax the parsimonious principle a tolerance with respect to the minimum size (networks complexity) can be used as well. Further, other arguments allow for controlling the data discretization or the maximum number of inputs per AND gate.

Help on caspo learn:

$ caspo learn --help
usage: caspo learn [-h] [--threads T] [--conf C] [--fit F] [--size S]
                   [--factor D] [--discretization T] [--length L]
                   pkn midas time

positional arguments:
  pkn                 prior knowledge network in SIF format
  midas               experimental dataset in MIDAS file
  time                time-point to be used in MIDAS

optional arguments:
  -h, --help          show this help message and exit
  --threads T         run clingo with given number of threads
  --conf C            threads configurations (Default to many)
  --optimum O         logical network in CSV format. If many networks are
                      given, the first network is used (If given, avoids
                      learning the optimum and go directly to enumeration)
  --fit F             tolerance over fitness (Default to 0)
  --size S            tolerance over size (Default to 0)
  --factor D          discretization over [0,D] (Default to 100)
  --discretization T  discretization function: round, floor, ceil (Default to
                      round)
  --length L          max conjunctions length (sources per hyperedges)
                      (Default to 0; unbounded)

Run caspo learn:

$ caspo learn pkn.sif dataset.csv 30 --fit 0.04

Running caspo learn...
Number of hyperedges (possible logical mappings) derived from the compressed PKN: 130
Optimum logical network learned in 1.0537s
Optimum logical networks has MSE 0.0499 and size 28
2150 (nearly) optimal logical networks learned in 2.6850s
Weighted MSE: 0.0513

The output of caspo learn will be two csv files, namely, networks.csv and stats-networks.csv. The file networks.csv describes all logical networks found with their corresponding MSE and size. The file stats-networks.csv describes the frequency of each logical mapping conjunction over all networks together with pairs of mutually inclusive/exclusive mappings. The weighted MSE combining all networks is also computed and printed in the standard output.

In addition, the following default visualizations are provided describing the family of logical networks. At the top, we show two alternative ways of describing the distribution of logical networks with respect to MSE and size. At the bottom, we show the (sorted) frequencies for all logical mapping conjunctions.

_images/learn.png

Classify

This subcommand implements the classification of a given family of logical networks with respect to their input-output behaviors [1]. Notably, the list of networks generated by caspo learn can be used directly as the input for caspo classify.

Help on caspo classify:

$ caspo classify --help
usage: caspo classify [-h] [--threads T] [--conf C] [--midas M T]
                      networks setup

positional arguments:
  networks     logical networks in CSV format
  setup        experimental setup in JSON format

optional arguments:
  -h, --help   show this help message and exit
  --threads T  run clingo with given number of threads
  --conf C     threads configurations (Default to many)
  --midas M T  experimental dataset in MIDAS file and time-point to be used

Run caspo classify:

$ caspo classify networks.csv setup.json --midas dataset.csv 30

Running caspo classify...
Classifying 2150 logical networks...
31 input-output logical behaviors found in 156.9032s
Weighted MSE: 0.0513

The output of caspo classify will be a csv file named behaviors.csv describing one representative logical network for each input-output behavior found among given networks. For each representative network, the number of networks having the same behavior is also given. Further, if a dataset is given, the weighted MSE is computed.

Also, one of the following visualizations is provided depending on whether the dataset was given as an argument or not. If the a dataset is given, the figure at the top is generated where I/O behaviors are grouped by MSE to the given dataset. Otherwise, the figure at the bottom is generated.

_images/classify.png

Design

This subcommands implements the design of novel experiments in order discriminate a given family of input-output behaviors [3]. Notably, the list of input-output behaviors generated by caspo classify can be used directly as the input for caspo design. Further, other arguments allow for controlling the maximum number of stimuli and inhibitors used per experimental condition, or the maximum number of experiments allowed.

Help on caspo design:

$ caspo design --help
usage: caspo design [-h] [--threads T] [--conf C] [--stimuli S]
                    [--inhibitors I] [--nexp E] [--list L] [--relax]
                    networks setup

positional arguments:
  networks        logical networks in CSV format
  setup           experimental setup in JSON format

optional arguments:
  -h, --help      show this help message and exit
  --threads T     run clingo with given number of threads
  --conf C        threads configurations (Default to many)
  --stimuli S     maximum number of stimuli per experiment
  --inhibitors I  maximum number of inhibitors per experiment
  --nexp E        maximum number of experiments (Default to 10)
  --list L        list of possible experiments
  --relax         relax full pairwise discrimination (Default to False)

Run caspo design:

$ caspo design behaviors.csv setup.json

Running caspo design...
1 optimal experimental designs found in 219.5648s

The output of caspo design will be one csv file, namely, designs.csv, describing all optimal experimental designs. In addition, the following visualizations are provided for each experimental design in such a file. At the left we show all experimental conditions for each experimental design. At the top right we show the number of pairs of I/O behaviors discriminated by each experimental condition. At the bottom right we show the number of pairwise differences over specific readouts by each experimental condition.

_images/design.png

Predict

This subcommands implements the prediction of all possible experimental condition using the ensemble of predictions from a given family of logical networks. Since predictions are based on a weighted average, a variance can also be computed to investigate the variability on every prediction. Again, the list of input-output behaviors generated by caspo classify can be used directly as the input for caspo predict. In fact, any list of logical networks could be used. However, it is recommended to use a list of representative logical networks (with their corresponding number of represented networks) for better performance.

Help on caspo predict:

$ caspo predict --help
usage: caspo predict [-h] networks setup

positional arguments:
  networks    logical networks in CSV format.
  setup       experimental setup in JSON format

optional arguments:
  -h, --help  show this help message and exit

Run caspo predict:

$ caspo predict behaviors.csv setup.json

Running caspo predict...
Computing all predictions and their variance for 31 logical networks...

The output of caspo predict will be a csv file named predictions.csv describing for each possible experimental perturbation, the corresponding weighted average prediction and its variance for each readout. Also, the following visualization is provided showing the mean prediction variance for each readout over all possible experimental perturbations.

_images/predict.png

Control

This subcommand implements the control of a family of logical networks in terms of satisfying several intervention scenarios [4]. That is, it will find all intervention strategies for the given scenarios which are valid in every logical network in the family. Notably, the list of logical networks generated by caspo learn can be used directly as the input for caspo control. Further, other arguments allow for controlling the maximum number of interventions per strategy or whether interventions are allowed over constraints or goals.

Help on caspo control:

$ caspo control -h
usage: caspo control [-h] [--threads T] [--conf C] [--size M]
                     [--allow-constraints] [--allow-goals]
                     networks scenarios

positional arguments:
  networks             logical networks in CSV format
  scenarios            intervention scenarios in CSV format

optional arguments:
  -h, --help           show this help message and exit
  --threads T          run clingo with given number of threads
  --conf C             threads configurations (Default to many)
  --size M             maximum size for interventions strategies (Default to 0
                       (no limit))
  --allow-constraints  allow intervention over side constraints (Default to
                       False)
  --allow-goals        allow intervention over goals (Default to False)

Run caspo control:

$ caspo control networks.csv scenarios.csv

Running caspo control...
30 optimal intervention strategies found in 9.2413s

The output of caspo control will be two csv files, namely, strategies.csv and stats-strategies.csv. The file strategies.csv describes all intervention strategies found. The file stats-strategies.csv describes the frequency of each intervention over all strategies together with pairs of mutually inclusive/exclusive interventions. In addition, the following default visualizations are provided describing all intervention strategies:

_images/control.png

Visualize

This subcommand implements all visualizations generated in other subcommands but to be run independently from the subcommand generating the data. This could be useful to visualize logical networks, experimental designs or intervention strategies not necessarily generated by caspo.

Help on caspo visualize:

$ caspo visualize --help
usage: caspo visualize [-h] [--pkn P] [--setup S] [--networks N] [--midas M T]
                       [--sample R] [--stats-networks F] [--behaviors B]
                       [--designs D] [--predictions P] [--strategies S]
                       [--stats-strategies F]

optional arguments:
  -h, --help            show this help message and exit
  --pkn P               prior knowledge network in SIF format
  --setup S             experimental setup in JSON format
  --networks N          logical networks in CSV format
  --midas M T           experimental dataset in MIDAS file and time-point
  --sample R            visualize a sample of R logical networks or 0 for all
                        (Default to -1 (none))
  --stats-networks F    logical mappings frequencies in CSV format
  --behaviors B         logical networks in CSV format
  --designs D           experimental designs in CSV format
  --predictions P       logical predictions in CSV format
  --strategies S        intervention strategies in CSV format
  --stats-strategies F  intervention frequencies in CSV format

Run caspo visualize:

$ caspo visualize --pkn pkn.sif --networks networks.csv --setup setup.json

The output of caspo visualize will depend on the given arguments. Apart from the visualizations already shown when we described previous subcommands, it also provides visualization for a given PKN or a list of logical networks. Below we show an original PKN in the left, a compressed PKN in the top right, and the union of logical networks in the bottom right. Either all or a sample of logical networks can also be visualized individually using the --sample argument.

_images/visualize.png

Note that PKNs and logical networks visualizations are generated as DOT files which can be either opened using a dot viewer or converted to different formats (pdf, ps, png, among others) using Graphviz. For example, you can convert from dot to pdf by running:

$ dot pkn.dot -Tpdf -o pkn.pdf

Test

Help on caspo test:

$ caspo test --help
usage: caspo test [-h] [--threads T] [--conf C]
                  [--testcase {Toy,LiverToy,LiverDREAM,ExtLiver}]

optional arguments:
  -h, --help            show this help message and exit
  --threads T           run clingo with given number of threads
  --conf C              threads configurations (Default to many)
  --testcase {Toy,LiverToy,LiverDREAM,ExtLiver}
                        testcase name

Run caspo test:

$ caspo test

Testing caspo subcommands using test case Toy.

Copying files for running tests:
    Prior knowledge network: pkn.sif
    Phospho-proteomics dataset: dataset.csv
    Experimental setup: setup.json
    Intervention scenarios: scenarios.csv

$ caspo --out out learn out/pkn.sif out/dataset.csv 10 --fit 0.1 --size 5

Optimum logical network learned in 0.0066s
Optimum logical networks has MSE 0.1100 and size 7
5 (nearly) optimal logical networks learned in 0.0075s
Weighted MSE: 0.1100

$ caspo --out out classify out/networks.csv out/setup.json out/dataset.csv 10

Classifying 5 logical networks...
3 input-output logical behaviors found in 0.2029s
Weighted MSE: 0.1100

$ caspo --out out design out/behaviors.csv out/setup.json

1 optimal experimental designs found in 0.0047s

$ caspo --out out predict out/behaviors.csv out/setup.json

Computing all predictions and their variance for 3 logical networks...

$ caspo --out out control out/networks.csv out/scenarios.csv

3 optimal intervention strategies found in 0.0043s

$ caspo --out out visualize --pkn out/pkn.sif --setup out/setup.json \
        --networks out/networks.csv --midas out/dataset.csv 10 \
        --stats-networks=out/stats-networks.csv --behaviors out/behaviors.csv \
        --designs=out/designs.csv --predictions=out/predictions.csv \
        --strategies=out/strategies.csv --stats-strategies=out/stats-strategies.csv

References

  • [1] Exhaustively characterizing feasible logic models of a signaling network using Answer Set Programming. (2013). Bioinformatics.
  • [2] Learning Boolean logic models of signaling networks with ASP. (2015). Theoretical Computer Science.
  • [3] Designing experiments to discriminate families of logic models. (2015). Frontiers in Bioengineering and Biotechnology 3:131.
  • [4] Minimal intervention strategies in logical signaling networks with ASP. (2013). Theory and Practice of Logic Programming.

API Reference

Core

caspo.core.setup

class caspo.core.setup.Setup(stimuli, inhibitors, readouts)

Experimental setup describing stimuli, inhibitors and readouts species names

Parameters:
  • stimuli (list[str]) – List of stimuli species
  • inhibitors (list[str]) – List of inhibitors species
  • readouts (list[str]) – List of readouts species
stimuli

list[str]

inhibitors

list[str]

readouts

list[str]

__len__()

Returns the sum of stimuli, inhibitors, and readouts

Returns:Sum of stimuli, inhibitors, and readouts
Return type:int
clampings_iter(cues=None)

Iterates over all possible clampings of this experimental setup

Parameters:cues (Optional[iterable]) – If given, restricts clampings over given species names
Yields:caspo.core.clamping.Clamping – The next clamping with respect to the experimental setup
cues(rename_inhibitors=False)

Returns stimuli and inhibitors species of this experimental setup

Parameters:rename_inhibitors (boolean) – If True, rename inhibitors with an ending ‘i’ as in MIDAS files.
Returns:List of species names in order: first stimuli followed by inhibitors
Return type:list
filter(networks)

Returns a new experimental setup restricted to species present in the given list of networks

Parameters:networks (caspo.core.logicalnetwork.LogicalNetworkList) – List of logical networks
Returns:The restricted experimental setup
Return type:caspo.core.setup.Setup
classmethod from_json(klass, filename)

Creates an experimental setup from a JSON file

Parameters:filename (str) – Absolute path to JSON file
Returns:Created object instance
Return type:caspo.core.setup.Setup
nodes

frozenset: unique species names in the experimental setup

to_funset()

Converts the experimental setup to a set of gringo.Fun object instances

Returns:The set of gringo.Fun object instances
Return type:set
to_json(filename)

Writes the experimental setup to a JSON file

Parameters:filename (str) – Absolute path where to write the JSON file

caspo.core.literal

class caspo.core.literal.Literal

A literal is a variable or its negation

variable

str

signature

int (either 1 or -1)

__str__()

Returns the string representation of the literal

Returns:String representation of the literal
Return type:str
classmethod from_str(klass, string)

Creates a literal from a string

Parameters:string (str) – If the string starts with ‘!’, it’s interpreted as a negated variable
Returns:Created object instance
Return type:caspo.core.literal.Literal

caspo.core.clamping

class caspo.core.clamping.Clamping

A clamping is a frozenset of caspo.core.literal.Literal object instances where each literal describes a clamped variable

bool(variable)

Returns whether the given variable is positively clamped

Parameters:variable (str) – The variable name
Returns:True if the given variable is positively clamped, False otherwise
Return type:boolean
drop_literals(literals)

Returns a new clamping without the given literals

Parameters:literals (iterable[caspo.core.literal.Literal]) – Iterable of literals to be removed
Returns:A new clamping without the given literals
Return type:caspo.core.clamping.Clamping
classmethod from_tuples(klass, tuples)

Creates a clamping from tuples of the form (variable, sign)

Parameters:tuples (iterable[(str,int)]) – An iterable of tuples describing clamped variables
Returns:Created object instance
Return type:caspo.core.clamping.Clamping
has_variable(variable)

Returns whether the given variable is present in the clamping

Parameters:variable (str) – The variable name
Returns:True if the given variable is present in the clamping, False otherwise
Return type:boolean
to_array(variables)

Converts the clamping to a 1-D array with respect to the given variables

Parameters:variables (list[str]) – List of variables names
Returns:1-D array where position i correspond to the sign of the clamped variable at position i in the given list of variables
Return type:numpy.ndarray
to_funset(index, name='clamped')

Converts the clamping to a set of gringo.Fun object instances

Parameters:
  • index (int) – An external identifier to associate several clampings together in ASP
  • name (str) – A function name for the clamping
Returns:

The set of gringo.Fun object instances
Return type:

set
class caspo.core.clamping.ClampingList

A list of caspo.core.clamping.Clamping object instances

combinatorics()

Returns mutually exclusive/inclusive clampings

Returns:A tuple of 2 dictionaries. For each literal key, the first dict has as value the set of mutually exclusive clampings while the second dict has as value the set of mutually inclusive clampings.
Return type:(dict,dict)
differences(networks, readouts, prepend='')

Returns the total number of pairwise differences over the given readouts for the given networks

Parameters:
  • networks (iterable[caspo.core.logicalnetwork.LogicalNetwork]) – Iterable of logical networks to compute pairwise differences
  • readouts (list[str]) – List of readouts species names
  • prepend (str) – Columns are renamed using the given string at the beginning
Returns:

Total number of pairwise differences for each clamping over each readout
Return type:

pandas.DataFrame
drop_literals(literals)

Returns a new list of clampings without the given literals

Parameters:literals (iterable[caspo.core.literal.Literal]) – Iterable of literals to be removed from each clamping
Returns:The new list of clampings
Return type:caspo.core.clamping.ClampingList
frequencies_iter()

Iterates over the frequencies of all clamped variables

Yields:tuple[ caspo.core.literal.Literal, float ] – The next tuple of the form (literal, frequency)
frequency(literal)

Returns the frequency of a clamped variable

Parameters:literal (caspo.core.literal.Literal) – The clamped variable
Returns:The frequency of the given literal
Return type:float
Raises:ValueError – If the variable is not present in any of the clampings
classmethod from_csv(klass, filename, inhibitors=[])

Creates a list of clampings from a CSV file. Column names are expected to be of the form TR:species_name

Parameters:
  • filename (str) – Absolute path to a CSV file to be loaded with pandas.read_csv. The resulting DataFrame is passed to from_dataframe().
  • inhibitors (Optional[list[str]]) –

    If given, species names ending with i and found in the list (without the i) will be interpreted as inhibitors. That is, if they are set to 1, the corresponding species is inhibited and therefore its negatively clamped. Apart from that, all 1s (resp. 0s) are interpreted as positively (resp. negatively) clamped.

    Otherwise (if inhibitors=[]), all 1s (resp. -1s) are interpreted as positively (resp. negatively) clamped.
Returns:

Created object instance
Return type:

caspo.core.clamping.ClampingList
classmethod from_dataframe(klass, df, inhibitors=[])

Creates a list of clampings from a pandas.DataFrame object instance. Column names are expected to be of the form TR:species_name

Parameters:
  • df (pandas.DataFrame) – Columns and rows correspond to species names and individual clampings, respectively.
  • inhibitors (Optional[list[str]]) –

    If given, species names ending with i and found in the list (without the i) will be interpreted as inhibitors. That is, if they are set to 1, the corresponding species is inhibited and therefore its negatively clamped. Apart from that, all 1s (resp. 0s) are interpreted as positively (resp. negatively) clamped.

    Otherwise (if inhibitors=[]), all 1s (resp. -1s) are interpreted as positively (resp. negatively) clamped.
Returns:

Created object instance
Return type:

caspo.core.ClampingList
to_csv(filename, stimuli=[], inhibitors=[], prepend='')

Writes the list of clampings to a CSV file

Parameters:
  • filename (str) – Absolute path where to write the CSV file
  • stimuli (Optional[list[str]]) – List of stimuli names. If given, stimuli are converted to {0,1} instead of {-1,1}.
  • inhibitors (Optional[list[str]]) – List of inhibitors names. If given, inhibitors are renamed and converted to {0,1} instead of {-1,1}.
  • prepend (str) – Columns are renamed using the given string at the beginning
to_dataframe(stimuli=[], inhibitors=[], prepend='')

Converts the list of clampigns to a pandas.DataFrame object instance

Parameters:
  • stimuli (Optional[list[str]]) – List of stimuli names. If given, stimuli are converted to {0,1} instead of {-1,1}.
  • inhibitors (Optional[list[str]]) – List of inhibitors names. If given, inhibitors are renamed and converted to {0,1} instead of {-1,1}.
  • prepend (str) – Columns are renamed using the given string at the beginning
Returns:

DataFrame representation of the list of clampings
Return type:

pandas.DataFrame
to_funset(lname='clamping', cname='clamped')

Converts the list of clampings to a set of gringo.Fun instances

Parameters:
  • lname (str) – Predicate name for the clamping id
  • cname (str) – Predicate name for the clamped variable
Returns:

Representation of all clampings as a set of gringo.Fun instances
Return type:

set

caspo.core.dataset

class caspo.core.dataset.Dataset(midas, time)

An experimental phospho-proteomics dataset extending pandas.DataFrame

Parameters:
  • midas (Absolute PATH to a MIDAS file) –
  • time (Data acquisition time-point for the early response) –
setup

caspo.core.setup.Setup

clampings

caspo.core.clamping.ClampingList

readouts

pandas.DataFrame

is_inhibitor(name)

Returns if the given species name is a inhibitor or not

Parameters:name (str) –
Returns:True if the given name is a inhibitor, False otherwise.
Return type:boolean
is_readout(name)

Returns if the given species name is a readout or not

Parameters:name (str) –
Returns:True if the given name is a readout, False otherwise.
Return type:boolean
is_stimulus(name)

Returns if the given species name is a stimulus or not

Parameters:name (str) –
Returns:True if the given name is a stimulus, False otherwise.
Return type:boolean
to_funset(discrete)

Converts the dataset to a set of gringo.Fun instances

Parameters:discrete (callable) – A discretization function
Returns:Representation of the dataset as a set of gringo.Fun instances
Return type:set

caspo.core.graph

class caspo.core.graph.Graph

Prior knowledge network (aka interaction graph) extending networkx.MultiDiGraph

__plot__()

Returns a copy of this graph ready for plotting

Returns:A copy of the object instance
Return type:caspo.core.graph.Graph
compress(setup)

Returns the compressed graph according to the given experimental setup

Parameters:setup (caspo.core.setup.Setup) – Experimental setup used to compress the graph
Returns:Compressed graph
Return type:caspo.core.graph.Graph
classmethod from_tuples(klass, tuples)

Creates a graph from an iterable of tuples describing edges like (source, target, sign)

Parameters:tuples (iterable[(str,str,int))]) – Tuples describing signed and directed edges
Returns:Created object instance
Return type:caspo.core.graph.Graph
predecessors(node, exclude_compressed=True)

Returns the list of predecessors of a given node

Parameters:
  • node (str) – The target node
  • exclude_compressed (boolean) – If true, compressed nodes are excluded from the predecessors list
Returns:

List of predecessors nodes
Return type:

list
classmethod read_sif(klass, path)

Creates a graph from a simple interaction format (SIF) file

Parameters:path (str) – Absolute path to a SIF file
Returns:Created object instance
Return type:caspo.core.graph.Graph
successors(node, exclude_compressed=True)

Returns the list of successors of a given node

Parameters:
  • node (str) – The target node
  • exclude_compressed (boolean) – If true, compressed nodes are excluded from the successors list
Returns:

List of successors nodes
Return type:

list

caspo.core.hypergraph

class caspo.core.hypergraph.HyperGraph(nodes, hyper, edges)

Signed and directed hypergraph representation providing the link between logical networks and the corresponding expanded prior knowledge network.

Parameters:
  • nodes (pandas.Series) – Values in the Series correspond to variables names
  • hyper (pandas.Series) – Values in the Series correspond to the index in attribute nodes (interpreted as the target node)
  • edges (pandas.DataFrame) – Hyperedges details as a DataFrame with columns hyper_idx (corresponds to the index in attribute hyper), name (interpreted as a source node), and sign (1 or -1)
nodes

pandas.Series

hyper

pandas.Series

edges

pandas.DataFrame

clauses

dict

A mapping from an hyperedge id (hyper_idx) to a caspo.core.clause.Clause object instance

clauses_idx

dict

The inverse mappings of those in attribute clauses

mappings

caspo.core.mapping.MappingList

The list of all possible caspo.core.mapping.Mapping for this hypergraph

classmethod from_graph(klass, graph, length=0)

Creates a hypergraph (expanded graph) from a caspo.core.graph.Graph object instance

Parameters:
  • graph (caspo.core.graph.Graph) – The base interaction graph to be expanded
  • length (int) – Maximum length for hyperedges source sets. If 0, use maximum possible in each case.
Returns:

Created object instance
Return type:

caspo.core.hypergraph.HyperGraph
to_funset()

Converts the hypergraph to a set of gringo.Fun instances

Returns:Representation of the hypergraph as a set of gringo.Fun instances
Return type:set
variable(index)

Returns the variable name for a given variable id

Parameters:index (int) – Variable id
Returns:Variable name
Return type:str

caspo.core.mapping

class caspo.core.mapping.Mapping

A logical conjunction mapping as a tuple made of a caspo.core.clause.Clause and a target

clause

caspo.core.clause.Clause

target

str

__str__()

Returns the string representation of the mapping

Returns:String representation of the mapping as target<=clause
Return type:str
classmethod from_str(klass, string)

Creates a mapping from a string

Parameters:string (str) – String of the form target<-clause where clause is a valid string for caspo.core.clause.Clause
Returns:Created object instance
Return type:caspo.core.mapping.Mapping
class caspo.core.mapping.MappingList(mappings, indexes=None)

A list of indexed caspo.core.mapping.Mapping objects.

Parameters:
  • mappings ([caspo.core.mapping.Mapping]) – The list of logical mappings
  • indexes ([int]) – An optional list of integers to use as indexes
__getitem__(index)

A list of mappings can be indexed by:

  1. a tuple caspo.core.mapping.Mapping to get its corresponding index
  2. a list of integers to get all the corresponding mappings objects
  3. a single integer to get its corresponding mapping object
Returns:An integer, a MappingList or a single mapping
Return type:object
__iter__()

Iterates over mappings

Yields:caspo.core.mapping.Mapping – The next logical mapping
__len__()

Returns the number of mappings

Returns:Number of mappings
Return type:int
iteritems()

Iterates over all mappings

Yields:(int,Mapping) – The next pair (index, mapping)

caspo.core.clause

class caspo.core.clause.Clause

A conjunction clause is a frozenset of caspo.core.literal.Literal object instances

__str__()

Returns the string representation of the clause

bool(state)

Returns the Boolean evaluation of the clause with respect to a given state

Parameters:state (dict) – Key-value mapping describing a Boolean state or assignment
Returns:The evaluation of the clause with respect to the given state or assignment
Return type:boolean
classmethod from_str(klass, string)

Creates a clause from a given string.

Parameters:string (str) – A string of the form a+!b which translates to a AND NOT b.
Returns:Created object instance
Return type:caspo.core.clause.Clause

caspo.core.logicalnetwork

class caspo.core.logicalnetwork.LogicalNetwork

Logical network class extends networkx.DiGraph with nodes being, either caspo.core.clause.Clause object instances or species names (str).

networks

int

Number of networks having the same behavior (including this network as the representative network)

__plot__()

Returns a networkx.MultiDiGraph ready for plotting.

Returns:Network object instance ready for plotting
Return type:networkx.MultiDiGraph
fixpoint(clamping, steps=0)

Computes the fixpoint with respect to a given caspo.core.clamping.Clamping

Parameters:
  • clamping (caspo.core.clamping.Clamping) – The clamping with respect to the fixpoint is computed
  • steps (int) – If greater than zero, a maximum number of steps is performed. Otherwise it continues until reaching a fixpoint. Note that if no fixpoint exists, e.g. a network with a negative feedback-loop, this will never end unless you provide a maximum number of steps.
Returns:

The key-value mapping describing the state of the logical network
Return type:

dict
formulas_iter()

Iterates over all variable-clauses in the logical network

Yields:tuple[str,frozenset[caspo.core.clause.Clause]] – The next tuple of the form (variable, set of clauses) in the logical network.
classmethod from_hypertuples(klass, hg, tuples)

Creates a logical network from an iterable of integer tuples matching mappings in the given caspo.core.hypergraph.HyperGraph

Parameters:
Returns:

Created object instance
Return type:

caspo.core.logicalnetwork.LogicalNetwork
predictions(clampings, readouts, stimuli=[], inhibitors=[], nclampings=-1)

Computes network predictions for the given iterable of clampings

Parameters:
  • clampings (iterable) – Iterable over clampings
  • readouts (list[str]) – List of readouts names
  • stimuli (Optional[list[str]]) – List of stimuli names
  • inhibitors (Optional[list[str]]) – List of inhibitors names
  • nclampings (Optional[int]) – If greater than zero, it must be the number of clampings in the iterable. Otherwise, clampings must implement the special method __len__()
Returns:

DataFrame with network predictions for each clamping. If stimuli and inhibitors are given, columns are included describing each clamping. Otherwise, columns correspond to readouts only.
Return type:

pandas.DataFrame
size

int: The size (complexity) of this logical network as the sum of clauses’ length

step(state, clamping)

Performs a simulation step from the given state and with respect to the given clamping

Parameters:
  • state (dict) – The key-value mapping describing the current state of the logical network
  • clamping (caspo.core.clamping.Clamping) – A clamping over variables in the logical network
Returns:

The key-value mapping describing the next state of the logical network
Return type:

dict
to_array(mappings)

Converts the logical network to a binary array with respect to the given mappings from a caspo.core.hypergraph.HyperGraph object instance.

Parameters:mappings (caspo.core.mapping.MappingList) – Mappings to create the binary array
Returns:Binary array with respect to the given mappings describing the logical network. Position i in the array will be 1 if the network has the mapping at position i in the given list of mappings.
Return type:numpy.ndarray
to_graph()

Converts the logical network to its underlying interaction graph

Returns:The underlying interaction graph
Return type:caspo.core.graph.Graph
variables()

Returns variables in the logical network

Returns:Unique variables names
Return type:set[str]
class caspo.core.logicalnetwork.LogicalNetworkList(hg, matrix=None, networks=None)

List of caspo.core.logicalnetwork.LogicalNetwork object instances

Parameters:
  • hg (caspo.core.hypergraph.HyperGraph) – Underlying hypergraph of all logical networks.
  • matrix (Optional[numpy.ndarray]) – 2-D binary array representation of all logical networks. If None, an empty array is initialised
  • networks (Optional[numpy.ndarray]) – For each network in the list, it gives the number of networks having the same behavior. If None, an array of ones is initialised with the same length as the number of networks in the list.
__getitem__(index)

Returns logical network(s) at the given index

Parameters:index (object) – It can be an int or an iterable of int
Returns:Either a caspo.core.logicalnetwork.LogicalNetwork or a caspo.core.logicalnetwork.LogicalNetworkList object
Return type:object
__iter__()

Iterates over all logical networks in the list

Yields:caspo.core.logicalnetwork.LogicalNetwork – The next logical network in the list
__len__()

Returns the number of logical networks

Returns:Number of logical networks
Return type:int
__plot__()

Returns a networkx.MultiDiGraph ready for plotting. Edges weights correspond to mappings frequencies.

Returns:Network object instance ready for plotting
Return type:networkx.MultiDiGraph
add_network(pos, network)

Adds a network to the logical network at the given position

append(network)

Append a caspo.core.logicalnetwork.LogicalNetwork to the list

Parameters:network (caspo.core.logicalnetwork.LogicalNetwork) – The network to append
combinatorics()

Returns mutually exclusive/inclusive mappings

Returns:A tuple of 2 dictionaries. For each mapping key, the first dict has as value the set of mutually exclusive mappings while the second dict has as value the set of mutually inclusive mappings.
Return type:(dict,dict)
concat(other)

Returns the concatenation with another caspo.core.logicalnetwork.LogicalNetworkList object instance. It is assumed (not checked) that both have the same underlying hypergraph.

Parameters:other (caspo.core.logicalnetwork.LogicalNetworkList) – The list to concatenate
Returns:If other is empty returns self, if self is empty returns other, otherwise a new caspo.core.LogicalNetworkList is created by concatenating self and other.
Return type:caspo.core.logicalnetwork.LogicalNetworkList
frequencies_iter()

Iterates over all non-zero frequencies of logical conjunction mappings in this list

Yields:tuple[caspo.core.mapping.Mapping, float] – The next pair (mapping,frequency)
frequency(mapping)

Returns frequency of a given caspo.core.mapping.Mapping

Parameters:mapping (caspo.core.mapping.Mapping) – A logical conjuntion mapping
Returns:Frequency of the given mapping over all logical networks
Return type:float
Raises:ValueError – If the given mapping is not found in the mappings of the underlying hypergraph of this list
classmethod from_csv(klass, filename)

Creates a list of logical networks from a CSV file. Columns that cannot be parsed as a caspo.core.mapping.Mapping are ignored except for a column named networks which (if present) is interpreted as the number of logical networks having the same input-output behavior.

Parameters:filename (str) – Absolute path to CSV file
Returns:Created object instance
Return type:caspo.core.logicalnetwork.LogicalNetworkList
classmethod from_hypergraph(klass, hypergraph, networks=[])

Creates a list of logical networks from a given hypergraph and an optional list of caspo.core.logicalnetwork.LogicalNetwork object instances

Parameters:
Returns:

Created object instance
Return type:

caspo.core.logicalnetwork.LogicalNetworkList
mappings

caspo.core.mapping.MappingList: the list of mappings present in at least one logical network in this list

predictions(setup, n_jobs=-1)

Returns a pandas.DataFrame with the weighted average predictions and variance of all readouts for each possible clampings in the given experimental setup. For each logical network the weight corresponds to the number of networks having the same behavior.

Parameters:
  • setup (caspo.core.setup.Setup) – Experimental setup
  • n_jobs (int) – Number of jobs to run in parallel. Default to -1 (all cores available)
Returns:

DataFrame with the weighted average predictions and variance of all readouts for each possible clamping
Return type:

pandas.DataFrame

See also

Wikipedia: Weighted sample variance

reset()

Drop all networks in the list

split(indices)

Splits logical networks according to given indices

Parameters:indices (list) – 1-D array of sorted integers, the entries indicate where the array is split
Returns:List of caspo.core.logicalnetwork.LogicalNetworkList object instances
Return type:list

See also

numpy.split

to_csv(filename, networks=False, dataset=None, size=False, n_jobs=-1)

Writes the list of logical networks to a CSV file

Parameters:
  • filename (str) – Absolute path where to write the CSV file
  • networks (boolean) – If True, a column with number of networks having the same behavior is included in the file
  • dataset (Optional[caspo.core.dataset.Dataset]) – If not None, a column with the MSE with respect to the given dataset is included
  • size (boolean) – If True, a column with the size of each logical network is included
  • n_jobs (int) – Number of jobs to run in parallel. Default to -1 (all cores available)
to_dataframe(networks=False, dataset=None, size=False, n_jobs=-1)

Converts the list of logical networks to a pandas.DataFrame object instance

Parameters:
  • networks (boolean) – If True, a column with number of networks having the same behavior is included in the DataFrame
  • dataset (Optional[caspo.core.dataset.Dataset]) – If not None, a column with the MSE with respect to the given dataset is included in the DataFrame
  • size (boolean) – If True, a column with the size of each logical network is included in the DataFrame
  • n_jobs (int) – Number of jobs to run in parallel. Default to -1 (all cores available)
Returns:

DataFrame representation of the list of logical networks.
Return type:

pandas.DataFrame
to_funset()

Converts the list of logical networks to a set of gringo.Fun instances

Returns:Representation of all networks as a set of gringo.Fun instances
Return type:set
weighted_mse(dataset, n_jobs=-1)

Returns the weighted MSE over all logical networks with respect to the given caspo.core.dataset.Dataset object instance. For each logical network the weight corresponds to the number of networks having the same behavior.

Parameters:
  • dataset (caspo.core.dataset.Dataset) – Dataset to compute MSE
  • n_jobs (int) – Number of jobs to run in parallel. Default to -1 (all cores available)
Returns:

Weighted MSE
Return type:

float

Modules

Learn

class caspo.learn.Learner(graph, dataset, length, discrete, factor)

Learner of (nearly) optimal logical networks with respect to a given prior knownledge network and a phospho-proteomics dataset.

Parameters:
  • graph (caspo.core.graph.Graph) – Prior knowledge network
  • dataset (caspo.core.dataset.Dataset) – Experimental dataset
  • length (int) – Maximum length for conjunction clauses
  • discrete (str) – Discretization function: round, ceil, or floor
  • factor (int) – Discretization factor, e.g. 10, 100, 1000
graph

caspo.core.graph.Graph

dataset

caspo.core.dataset.Dataset

length

int

factor

int

discrete

str

hypergraph

caspo.core.hypergraph.HyperGraph

instance

str

optimum

caspo.core.logicalnetwork.LogicalNetwork

networks

caspo.core.logicalnetwork.LogicalNetworkList

encodings

dict

stats

dict

ceil(factor, value)

Discretize a given value using a given factor and the ceil integer function

Parameters:
  • factor (int) – The factor to be used for the discretization
  • value (float) – The value to be discretized
Returns:

The discretized value
Return type:

int
floor(factor, value)

Discretize a given value using a given factor and the floor integer function

Parameters:
  • factor (int) – The factor to be used for the discretization
  • value (float) – The value to be discretized
Returns:

The discretized value
Return type:

int
learn(fit=0, size=0, configure=None)

Learns all (nearly) optimal logical networks with give fitness and size tolerance. The first optimum logical network found is saved in the attribute optimum while all enumerated logical networks are saved in the attribute networks.

Example:

>>> from caspo import core, learn

>>> graph = core.Graph.read_sif('pkn.sif')
>>> dataset = core.Dataset('dataset.csv', 30)
>>> zipped = graph.compress(dataset.setup)

>>> learner = learn.Learner(zipped, dataset, 2, 'round', 100)
>>> learner.learn(0.02, 1)

>>> learner.networks.to_csv('networks.csv')
Parameters:
  • fit (float) – Fitness tolerance, e.g., use 0.1 for 10% tolerance with respect to the optimum
  • size (int) – Size tolerance with respect to the optimum
  • configure (callable) – Callable object responsible of setting a custom clingo configuration
random(size, n_and, max_in, n=1)

Generates n random logical networks with given size range, number of AND gates and maximum input signals for AND gates. Logical networks are saved in the attribute networks.

Parameters:
  • n (int) – Number of random logical networks to be generated
  • size ((int,int)) – Minimum and maximum sizes
  • n_and ((int,int)) – Minimum and maximum AND gates
  • max_in (int) – Maximum input signals for AND gates
round(factor, value)

Discretize a given value using a given factor and the closest integer function

Parameters:
  • factor (int) – The factor to be used for the discretization
  • value (float) – The value to be discretized
Returns:

The discretized value
Return type:

int

Classify

class caspo.classify.Classifier(networks, setup)

Classifier of given list of logical networks with respect to a given experimental setup.

Parameters:
networks

caspo.core.logicalnetwork.LogicalNetworkList

setup

caspo.core.setup.Setup

stats

dict

classify(n_jobs=-1, configure=None)

Returns input-output behaviors for the list of logical networks in the attribute networks

Example:

>>> from caspo import core, classify

>>> networks = core.LogicalNetworkList.from_csv('networks.csv')
>>> setup = core.Setup.from_json('setup.json')

>>> classifier = classify.Classifier(networks, setup)
>>> behaviors = classifier.classify()

>>> behaviors.to_csv('behaviors.csv', networks=True)
n_jobs : int
Number of jobs to run in parallel. Default to -1 (all cores available)
configure : callable
Callable object responsible of setting clingo configuration
Returns:The list of networks with one representative for each behavior
Return type:caspo.core.logicalnetwork.LogicalNetworkList

Design

class caspo.design.Designer(networks, setup, candidates=None)

Experimental designer to discriminate among a list of logical networks (input-output behaviors representatives)

Parameters:
networks

caspo.core.logicalnetwork.LogicalNetworkList

setup

caspo.core.setup.Setup

candidates

caspo.core.clamping.ClampingList

designs

list[caspo.core.clamping.ClampingList]

instance

str

encodings

dict

stats

dict

design(max_stimuli=-1, max_inhibitors=-1, max_experiments=10, relax=False, configure=None)

Finds all optimal experimental designs using up to max_experiments experiments, such that each experiment has up to max_stimuli stimuli and max_inhibitors inhibitors. Each optimal experimental design is appended in the attribute designs as an instance of caspo.core.clamping.ClampingList.

Example:

>>> from caspo import core, design
>>> networks = core.LogicalNetworkList.from_csv('behaviors.csv')
>>> setup = core.Setup.from_json('setup.json')

>>> designer = design.Designer(networks, setup)
>>> designer.design(3, 2)

>>> for i,d in enumerate(designer.designs):
...     f = 'design-%s' % i
...     d.to_csv(f, stimuli=self.setup.stimuli, inhibitors=self.setup.inhibitors)
Parameters:
  • max_stimuli (int) – Maximum number of stimuli per experiment
  • max_inhibitors (int) – Maximum number of inhibitors per experiment
  • max_experiments (int) – Maximum number of experiments per design
  • relax (boolean) – Whether to relax the full-pairwise networks discrimination (True) or not (False). If relax equals True, the number of experiments per design is fixed to max_experiments
  • configure (callable) – Callable object responsible of setting clingo configuration

Predict

class caspo.predict.Predictor(networks, setup)

Predictor of all possible experimental conditions over a given experimental setup using a given list of logical networks.

Parameters:
networks

caspo.core.logicalnetwork.LogicalNetworkList

setup

caspo.core.setup.Setup

predict()

Computes all possible weighted average predictions and their variances

Example:

>>> from caspo import core, predict

>>> networks = core.LogicalNetworkList.from_csv('behaviors.csv')
>>> setup = core.Setup.from_json('setup.json')

>>> predictor = predict.Predictor(networks, setup)
>>> df = predictor.predict()

>>> df.to_csv('predictions.csv'), index=False)
Returns:DataFrame with the weighted average predictions and variance of all readouts for each possible clamping
Return type:pandas.DataFrame

Control

class caspo.control.Controller(networks, scenarios)

Controller of logical networks family for various intervention scenarios

Parameters:
networks

caspo.core.logicalnetwork.LogicalNetworkList

scenarios

caspo.control.ScenarioList

strategies

caspo.core.clamping.ClampingList

instance

str

encodings

dict

stats

dict

control(size=0, configure=None)

Finds all inclusion-minimal intervention strategies up to the given size. Intervention strategies found are saved in the attribute strategies as a caspo.core.clamping.ClampingList object instance.

Example:

>>> from caspo import core, control

>>> networks = core.LogicalNetworkList.from_csv('networks.csv')
>>> scenarios = control.ScenarioList('scenarios.csv')

>>> controller = control.Controller(networks, scenarios)
>>> controller.control()

>>> controller.strategies.to_csv('strategies.csv')
Parameters:
  • size (int) – Maximum number of intervention per intervention strategy
  • configure (callable) – Callable object responsible of setting clingo configuration
class caspo.control.ScenarioList(filename, allow_constraints=False, allow_goals=False)

List of intervention scenarios

Parameters:
  • filename (str) – Absolute PATH to a CSV file specifying several intervention scenarios
  • allow_constraints (boolean) – Either to allow intervention over constraints or not
  • allow_goals (boolean) – Either to allow intervention over goals or not
constraints

caspo.core.clamping.ClampingList

goals

caspo.core.clamping.ClampingList

to_funset()

Converts the intervention scenarios to a set of gringo.Fun instances

Returns:Representation of the intervention scenarios as a set of gringo.Fun instances
Return type:set

Visualize

caspo.visualize.behaviors_distribution(df, filepath=None)

Plots the distribution of logical networks across input-output behaviors. Optionally, input-output behaviors can be grouped by MSE.

Parameters:
  • df (pandas.DataFrame) – DataFrame with columns networks and optionally mse
  • filepath (str) – Absolute path to a folder where to write the plot
Returns:

Generated plot
Return type:

plot
caspo.visualize.coloured_network(network, setup, filename)

Plots a coloured (hyper-)graph to a dot file

Parameters:
caspo.visualize.differences_distribution(df, filepath=None)

For each experimental design it plot all the corresponding generated differences in different plots

Parameters:
  • df (pandas.DataFrame) – DataFrame with columns id, pairs, and starting with DIF:
  • filepath (str) – Absolute path to a folder where to write the plots
Returns:

Generated plots
Return type:

list
caspo.visualize.experimental_designs(df, filepath=None)

For each experimental design it plot all the corresponding experimental conditions in a different plot

Parameters:
  • df (pandas.DataFrame) – DataFrame with columns id and starting with TR:
  • filepath (str) – Absolute path to a folder where to write the plot
Returns:

Generated plots
Return type:

list
caspo.visualize.intervention_strategies(df, filepath=None)

Plots all intervention strategies

Parameters:
  • df (pandas.DataFrame) – DataFrame with columns starting with TR:
  • filepath (str) – Absolute path to a folder where to write the plot
Returns:

Generated plot
Return type:

plot
caspo.visualize.interventions_frequency(df, filepath=None)

Plots the frequency of occurrence for each intervention

Parameters:
  • df (pandas.DataFrame) – DataFrame with columns frequency and intervention
  • filepath (str) – Absolute path to a folder where to write the plot
Returns:

Generated plot
Return type:

plot
caspo.visualize.mappings_frequency(df, filepath=None)

Plots the frequency of logical conjunction mappings

Parameters:
  • df (pandas.DataFrame) – DataFrame with columns frequency and mapping
  • filepath (str) – Absolute path to a folder where to write the plot
Returns:

Generated plot
Return type:

plot
caspo.visualize.networks_distribution(df, filepath=None)

Generates two alternative plots describing the distribution of variables mse and size. It is intended to be used over a list of logical networks.

Parameters:
  • df (pandas.DataFrame) – DataFrame with columns mse and size
  • filepath (str) – Absolute path to a folder where to write the plots
Returns:

Generated plots
Return type:

tuple
caspo.visualize.predictions_variance(df, filepath=None)

Plots the mean variance prediction for each readout

Parameters:
  • df (pandas.DataFrame) – DataFrame with columns starting with VAR:
  • filepath (str) – Absolute path to a folder where to write the plots
Returns:

Generated plot
Return type:

plot

Indices and tables