{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# BioLQM tutorial\n", "\n", "This notebook illustrates the main features of the python API of the `biolqm` toolkit. We will show how to load a model, perform simple dynamical analysis (simulation and identification of attractors) and apply perturbations.\n", "\n", "The code from this tutorial can be executed on the standard python interpreter, the IPython shell or the Jupyter notebook web interface." ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [ { "data": { "text/markdown": [ "This notebook has been executed using the docker image `colomoto/colomoto-docker` built on `2018-12-22`" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "import pandas as pd # for the visualization of lists of states\n", "import biolqm" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Load a model\n", "\n", "\n", "The `biolqm.load` function allows to load a model froma file given as parameter. It can be a local file or a web URL to downloadit. bioLQM will use the file extension to guess the format.\n", "See https://github.com/colomoto/bioLQM#how-to-use-it for a list of supported formats, notably GINsim (`.zginml` or `.ginml` files) and SBML qual (`.sbml` files).\n", "\n", "When using the web interface, calling the load function without specifying the parameter enables to pick and upload a local file.\n", "\n", "Here we load a published model of the mammalian cell cycle." ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [ { "data": { "text/markdown": [ "Downloading 'http://ginsim.org/sites/default/files/boolean_cell_cycle.zginml'" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "lqm = biolqm.load(\"http://ginsim.org/sites/default/files/boolean_cell_cycle.zginml\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# Deterministic simulations\n", "\n", "Starting with an initial state (by default where all components are inactive), we can compute the evolution of all components over time by evaluating the logical functions of the model. The `biolqm.trace` function returns an iterator from which we can obtain a list of successive states.\n", "\n", "These simulations are limited to *deterministic* updating modes, where each state has a single successor.\n", "The simulation stops when reaching a stable state or a maximal number of steps (1000 by default)." ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
Cdc20CycACycBCycDCycEE2FRbUbcH10cdh1p27
00000000000
10010011111
21000000100
30000011111
40000001011
\n", "
" ], "text/plain": [ " Cdc20 CycA CycB CycD CycE E2F Rb UbcH10 cdh1 p27\n", "0 0 0 0 0 0 0 0 0 0 0\n", "1 0 0 1 0 0 1 1 1 1 1\n", "2 1 0 0 0 0 0 0 1 0 0\n", "3 0 0 0 0 0 1 1 1 1 1\n", "4 0 0 0 0 0 0 1 0 1 1" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "trace = biolqm.trace(lqm)\n", "pd.DataFrame( [s for s in trace] )" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The `biolqm.trace` function can take an additional argument to specify simulation parameters. These parameters are specified in a single string and identified by the following flags:\n", "* `-u` for the updating mode (synchronous by default, can also be sequential)\n", "* `-i` for the initial state (following the internal component ordering)\n", "* `-m` for the maximal number of steps." ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
Cdc20CycACycBCycDCycEE2FRbUbcH10cdh1p27
00000010000
10110111111
21000000100
30000011111
40000001011
\n", "
" ], "text/plain": [ " Cdc20 CycA CycB CycD CycE E2F Rb UbcH10 cdh1 p27\n", "0 0 0 0 0 0 1 0 0 0 0\n", "1 0 1 1 0 1 1 1 1 1 1\n", "2 1 0 0 0 0 0 0 1 0 0\n", "3 0 0 0 0 0 1 1 1 1 1\n", "4 0 0 0 0 0 0 1 0 1 1" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "trace = biolqm.trace(lqm, \"-u synchronous -i 0010000000 -m 50\")\n", "pd.DataFrame( [s for s in trace] )" ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [], "source": [ "tracer = biolqm.trace.getTask(lqm)" ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [], "source": [ "state = tracer._task.state" ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\n" ] } ], "source": [ "print( state )" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# Random walk in non-deterministic simulations\n", "\n", "Logical models can also be updated in a *non-deterministic* mode, where each state can have many alternative successors.\n", "The `biolqm.random` function allows to perform a random walk in the complex dynamics obtained with non-deterministic updating modes.\n", "\n", "Like `biolqm.trace`, the `biolqm.random` function takes an additional argument for simulation parameters:\n", "* `-u` for the updating mode (asynchronous by default, can also be complete)\n", "* `-i` for the initial state (following the internal component ordering)\n", "* `-m` for the maximal number of steps." ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
Cdc20CycACycBCycDCycEE2FRbUbcH10cdh1p27
00000010000
10000010100
20000010101
30000010111
40000010011
50000011011
60000001011
\n", "
" ], "text/plain": [ " Cdc20 CycA CycB CycD CycE E2F Rb UbcH10 cdh1 p27\n", "0 0 0 0 0 0 1 0 0 0 0\n", "1 0 0 0 0 0 1 0 1 0 0\n", "2 0 0 0 0 0 1 0 1 0 1\n", "3 0 0 0 0 0 1 0 1 1 1\n", "4 0 0 0 0 0 1 0 0 1 1\n", "5 0 0 0 0 0 1 1 0 1 1\n", "6 0 0 0 0 0 0 1 0 1 1" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "random = biolqm.random(lqm, \"-i 0010000000 -m 50\")\n", "pd.DataFrame( [s for s in random] )" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As this type of simulation is a random walk, successive calls often yield different trajectories." ] }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
Cdc20CycACycBCycDCycEE2FRbUbcH10cdh1p27
00000010000
10000010001
20000010101
30100010101
40100110101
50100111101
60100111111
70100011111
80100001111
90000001111
100000001011
\n", "
" ], "text/plain": [ " Cdc20 CycA CycB CycD CycE E2F Rb UbcH10 cdh1 p27\n", "0 0 0 0 0 0 1 0 0 0 0\n", "1 0 0 0 0 0 1 0 0 0 1\n", "2 0 0 0 0 0 1 0 1 0 1\n", "3 0 1 0 0 0 1 0 1 0 1\n", "4 0 1 0 0 1 1 0 1 0 1\n", "5 0 1 0 0 1 1 1 1 0 1\n", "6 0 1 0 0 1 1 1 1 1 1\n", "7 0 1 0 0 0 1 1 1 1 1\n", "8 0 1 0 0 0 0 1 1 1 1\n", "9 0 0 0 0 0 0 1 1 1 1\n", "10 0 0 0 0 0 0 1 0 1 1" ] }, "execution_count": 9, "metadata": {}, "output_type": "execute_result" } ], "source": [ "pd.DataFrame( [s for s in random] )" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "While bioLQM implements non-deterministic updating modes, their simulation requires a more complex engine and data structure which are beyond the scope of bioLQM: use other tools such as GINsim or (py)boolnet to perform non-deterministic simulations." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Identification of stable states (fixed points)\n", "\n", "The `biolqm.fixpoints` functions implements a constraint-solving method (based on decision diagrams) for the efficient identification of the stable states of a model without performing simulation." ] }, { "cell_type": "code", "execution_count": 10, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
Cdc20CycACycBCycDCycEE2FRbUbcH10cdh1p27
00000001011
\n", "
" ], "text/plain": [ " Cdc20 CycA CycB CycD CycE E2F Rb UbcH10 cdh1 p27\n", "0 0 0 0 0 0 0 1 0 1 1" ] }, "execution_count": 10, "metadata": {}, "output_type": "execute_result" } ], "source": [ "fps = biolqm.fixpoints(lqm)\n", "pd.DataFrame(fps)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Identification of stable motifs (trapspaces)\n", "\n", "A stable motif (also called symbolic steady state) is a partially assigned state such that all possible successors of all states which belong to the motif also belong to the motif. Like stable states, these stable motifs can be identified efficiently using constraint-solving methods.\n", "\n", "Following this definition, all stable motifs contain at least an attractor. The stable states and the full state space are trivially identified stable motifs. Note that some stable motifs are embded inside others (in particular, they are all part of the full state space). The stable motifs which do not contain such smaller sub-motifs are called *terminal* and provide a good approximation of the attractors of the model (yet some attractors may be missed by this approximation).\n", "\n", "The `biolqm.trapspace` function computes these stable motifs. An additional argument allows to show only the terminal ones.\n", "\n", "In the output below, the non-assigned components in each motif are denoted by the joker value `254`." ] }, { "cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
Cdc20CycACycBCycDCycEE2FRbUbcH10cdh1p27
00000001011
1254254254125425402542540
\n", "
" ], "text/plain": [ " Cdc20 CycA CycB CycD CycE E2F Rb UbcH10 cdh1 p27\n", "0 0 0 0 0 0 0 1 0 1 1\n", "1 254 254 254 1 254 254 0 254 254 0" ] }, "execution_count": 11, "metadata": {}, "output_type": "execute_result" } ], "source": [ "traps = biolqm.trapspace(lqm)\n", "pd.DataFrame(traps)" ] }, { "cell_type": "code", "execution_count": 12, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
Cdc20CycACycBCycDCycEE2FRbUbcH10cdh1p27
00000001011
1254254254125425402542540
\n", "
" ], "text/plain": [ " Cdc20 CycA CycB CycD CycE E2F Rb UbcH10 cdh1 p27\n", "0 0 0 0 0 0 0 1 0 1 1\n", "1 254 254 254 1 254 254 0 254 254 0" ] }, "execution_count": 12, "metadata": {}, "output_type": "execute_result" } ], "source": [ "traps = biolqm.trapspace(lqm, \"terminal\")\n", "pd.DataFrame(traps)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Model perturbation\n", "\n", "the `biolqm.perturbation` function enables the construction of a variant of the model, where the logical function of one (or several) component has been modified. A textual parameter describes the modification:\n", "\n", "* `component%0` defines a knockout of a component\n", "* `component%1` defines an ectopic expression\n", "* `component%1-2` restricts the range of values for multi-valued components\n", "* `component:regulator%0` allows to remove a regulator\n", "\n", "In the following, we show the impact of the ectopic expression of the `CycD` component on the stable states and trapspaces on the model." ] }, { "cell_type": "code", "execution_count": 13, "metadata": {}, "outputs": [], "source": [ "pert = biolqm.perturbation(lqm, \"CycD%1\")" ] }, { "cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
\n", "
" ], "text/plain": [ "Empty DataFrame\n", "Columns: []\n", "Index: []" ] }, "execution_count": 14, "metadata": {}, "output_type": "execute_result" } ], "source": [ "fps = biolqm.fixpoints(pert)\n", "pd.DataFrame(fps)" ] }, { "cell_type": "code", "execution_count": 15, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
Cdc20CycACycBCycDCycEE2FRbUbcH10cdh1p27
0254254254125425402542540
\n", "
" ], "text/plain": [ " Cdc20 CycA CycB CycD CycE E2F Rb UbcH10 cdh1 p27\n", "0 254 254 254 1 254 254 0 254 254 0" ] }, "execution_count": 15, "metadata": {}, "output_type": "execute_result" } ], "source": [ "traps = biolqm.trapspace(pert, \"terminal\")\n", "pd.DataFrame(traps)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Multiple perturbations are comma-separated. Here we show the effect of the ectopic expression of both `CycD` and `Rb`." ] }, { "cell_type": "code", "execution_count": 16, "metadata": {}, "outputs": [], "source": [ "pert = biolqm.perturbation(lqm, \"CycD%1,Rb%1\")" ] }, { "cell_type": "code", "execution_count": 17, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
Cdc20CycACycBCycDCycEE2FRbUbcH10cdh1p27
00000001011
\n", "
" ], "text/plain": [ " Cdc20 CycA CycB CycD CycE E2F Rb UbcH10 cdh1 p27\n", "0 0 0 0 0 0 0 1 0 1 1" ] }, "execution_count": 17, "metadata": {}, "output_type": "execute_result" } ], "source": [ "fps = biolqm.fixpoints(pert)\n", "pd.DataFrame(fps)" ] }, { "cell_type": "code", "execution_count": 18, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
Cdc20CycACycBCycDCycEE2FRbUbcH10cdh1p27
00000001011
1254254254125425402542540
\n", "
" ], "text/plain": [ " Cdc20 CycA CycB CycD CycE E2F Rb UbcH10 cdh1 p27\n", "0 0 0 0 0 0 0 1 0 1 1\n", "1 254 254 254 1 254 254 0 254 254 0" ] }, "execution_count": 18, "metadata": {}, "output_type": "execute_result" } ], "source": [ "traps = biolqm.trapspace(pert, \"terminal\")\n", "pd.DataFrame(traps)" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.6.6" } }, "nbformat": 4, "nbformat_minor": 2 }