Commit 95a81fbc authored by VIGNET Pierre's avatar VIGNET Pierre
Browse files

Update documentation

parent 61d1eae9
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = CADBIOM
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
.wy-table-responsive table td {
white-space: normal !important;
}
.wy-table-responsive {
overflow: visible !important;
}
*******************************************
Documentation of the package for developers
*******************************************
Tools
=====
Models
------
.. automodule:: cadbiom_cmd.tools.models
:members:
Solutions
---------
.. automodule:: cadbiom_cmd.tools.solutions
:members:
Display, compare, and query models
==================================
.. automodule:: cadbiom_cmd.solution_repr
:members:
Merge Minimal Accessibility Conditions
======================================
.. automodule:: cadbiom_cmd.solution_merge
:members:
Sorting solutions in the results files
======================================
.. automodule:: cadbiom_cmd.solution_sort
:members:
Search Minimal Accessibility Conditions
=======================================
.. automodule:: cadbiom_cmd.solution_search
:members:
# Installation
This program is tested on python 2.7
(Indeed, the GUI is based on GTK2, and sadly, can not be easily ported to GTK3 with Python 3).
Please check the system requirements on the
[Main website](http://cadbiom.genouest.org/download.html) or [Gitlab](https://gitlab.inria.fr/pvignet/cadbiom).
As always, the use of a Python virtual environment
(via [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/)) is **strongly advised**.
## From PyPI
pip install cadbiom_cmd
## From sources for developers
cd command_line/
python2.7 setup.py develop
python2.7 setup.py develop --uninstall
********************
Command line package
********************
.. toctree::
command_line_install
command_line_usage
command_line_doc
\ No newline at end of file
*****
Usage
*****
.. argparse::
:filename: ../command_line/cadbiom_cmd/cadbiom_cmd.py
:func: main
:prog: cadbiom_cmd
# -*- coding: utf-8 -*-
#
# CADBIOM documentation build configuration file, created by
# sphinx-quickstart on Fri Mar 23 18:00:42 2018.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.viewcode',
'markdown.extensions.abbr']
extensions += ['sphinxarg.ext']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
from recommonmark.parser import CommonMarkParser
from recommonmark.transform import AutoStructify
source_parsers = {
'.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']
# app setup hook
# Activation of settings for recommonmark : rst code in markdown
def setup(app):
app.add_config_value('recommonmark_config', {
'enable_eval_rst': True,
}, True)
app.add_transform(AutoStructify)
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'CADBIOM'
copyright = u'2018, Pierre Vignet, Geoffroy Andrieux, Michel Le Borgne, Nolwenn Le Meur'
author = u'Pierre Vignet, Geoffroy Andrieux, Michel Le Borgne, Nolwenn Le Meur'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'0.1.7'
# The full version, including alpha/beta/rc tags.
release = u'0.1.7'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = []
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
html_context = {
'css_files': [
'_static/patch.css', # override wide tables in RTD theme
],
}
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# This is required for the alabaster theme
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
html_sidebars = {
'**': [
'relations.html', # needs 'show_related': True theme option to display
'searchbox.html',
]
}
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'CADBIOMdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'CADBIOM.tex', u'CADBIOM Documentation',
u'Pierre Vignet, Geoffroy Andrieux, Michel Le Borgne, Nolwenn Le Meur', 'manual'),
]
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'cadbiom', u'CADBIOM Documentation',
[author], 1)
]
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'CADBIOM', u'CADBIOM Documentation',
author, 'CADBIOM', 'One line description of project.',
'Miscellaneous'),
]
autodoc_mock_imports = [
'_cadbiom',
]
\ No newline at end of file
# Examples: Workflow overview
## Creation of a Cadbiom model from BioPAX data
`biopax2cadbiom` is a standalone module also integrated in the Cadbiom GUI that
converts BioPAX ontologies to Cabiom models.
You will find a full help about the installation and usage at [biopax2cadbiom](http://cadbiom.genouest.org/doc/biopax2cadbiom/index.html).
Do not miss the chapter [Which graphs can be queried on a server?](http://cadbiom.genouest.org/doc/biopax2cadbiom/examples.html#which-graphs-can-be-queried-on-an-endpoint-like-pathway-commons).
Let's take the example of a [PID database (Pathway Interaction Database)](https://github.com/NCIP/pathway-interaction-database) conversion.
```eval_rst
.. code-block:: bash
$ biopax2cadbiom model \
--listOfGraphUri http://pathwaycommons.org \
--provenanceUri http://pathwaycommons.org/pc2/pid \
--triplestore http://rdf.pathwaycommons.org/sparql/ \
--fullCompartmentsNames
**Arguments:**
The parameter ``--listOfGraphUri`` provides the URI of the graphs queried (and optionally
of the BioPAX ontology if it is hosted separately).
It is thus necessary to filter the RDF triples according to their origin.
This is why the optional parameter ``--provenanceURI`` has been introduced.
By setting it, the program will filter entities, reactions, pathways, etc. on their ``dataSource`` BioPAX attribute.
The URL of the endpoint is specified with ``--triplestore``.
```
Arguments:
- `--listOfGraphUri`: List of RDF graph to be queried on the triplestore.
You **have to** specify the biopax ontology store on your triplestore (`http://biopax.org/lvl3`),
and the name of the queried graph (`http://www.pathwaycommons.org/v9/pid`).
- `--fullCompartmentsNames`: This flag allows compartments to be named on the base of their real names in the BioPAX file.
```eval_rst
.. figure:: _static/gui_biopax_import.jpg
:scale: 65 %
:alt: Cadbiom GUI import BioPAX
:align: center
Small graphs can be queried and converted from the GUI of Cadbiom.
```
## How to query the Cadbiom model
### What is in the model ?
#### Get model information
To get information about the model, the subcommand `model_info`
([doc](./command_line_usage.html#model_info)) can be used:
```bash
$ cadbiom_cmd model_info model.bcx --json --all_entities
```
Arguments:
```eval_rst
- ``--json``: Dump all data in a file formated in JSON.
:Example of file:
.. code-block:: javascript
{
'model_file': '',
'model_name': '',
'events': 0,
'places': 0,
'frontier_places': 0,
'transitions': 0,
'locations': {
'loc1': 0,
'loc2': 0
},
'entity_types': {
'type1': 0,
'type2': 0
},
'places_data': {
'cadbiom_name': '',
'uri': '',
'entityType': '',
'entityRef': '',
'location': '',
'names': []
}
}
- ``--all_places``:
Create a CSV file with the filtered places of the model (here, the option 'all_places'
was selected among 'frontier_places' and 'genes').
:Example of CSV file:
.. csv-table::
:header: cadbiom_name, names, uri, entityType, entityRef, location
HDAC5_nucleus, HDAC5, http://pathwaycommons.org/pc2/Protein_1cac564f64b0e2a8f5ac650e72db85b8, Protein, http://identifiers.org/uniprot/Q9UQL6, nucleus
NRAMP1_gene, NRAMP1, http://pathwaycommons.org/pc2/TemplateReaction_90f4476ae5c45145f122c732535883b7, Protein, http://identifiers.org/uniprot/P49279,
LC20_1o_1O, LC20, http://pathwaycommons.org/pc2/Protein_94f4460ceaa0fdbfa2ea164574a72d01, Protein, http://identifiers.org/uniprot/P24844,
```
#### Get informations and graph based on the model
To get quick informations and make a graph based on the model, the subcommand `model_graph`
([doc](./command_line_usage.html#model_graph)) can be used:
```bash
$ cadbiom_cmd model_graph ../cadbiom/bio_models/mini_test_publi.bcx --graph --advanced --json
```
Arguments:
```eval_rst
- ``--advanced``: Compute centralities for each node (degree, in_degree, out_degree, closeness, betweenness).
- ``--graph``: Make a graphml file based on the graph maked from the model.
- ``--json``: Dump all data in a file formated in JSON.
:Example of file:
.. code-block:: javascript
{
'model_file': '',
'model_name': '',
'events': 0,
'places': 0,
'frontier_places': 0,
'transitions': 0,
'graph_nodes': 0,
'graph_edges': 0,
'advanced': {
'degree': {
'Ax': 0.0,
'Bx': 0.0
},
'in_degree': {
'Ax': 0.0,
'Bx': 0.0
},
'out_degree': {
'Ax': 0.0,
'Bx': 0.0
},
'betweenness': {
'Ax': 0.0,
'Bx': 0.0
},
'closeness': {
'Ax': 0.0,
'Bx': 0.0
},
}
}
```
### Search for molecules of interest
Cadbiom allows to explain how to obtain an entity or a set of entities of interest from the elements
at the periphery of the model. These sets are called Minimal Activation Conditions (MAC).
Ultimately, the software answers to the question: *"Is it possible to find an initialization
such that the given state/property happens ?"*
The subcommand `compute_macs` ([doc](./command_line_usage.html#compute_macs)) is designed to compute MACs.
Example:
$ cadbiom_cmd compute_macs model.bcx SRP9 --all_macs --steps 7 --continue
The program produces produces 2 types of files:
- *\*cam.txt files*: Each line contains a MAC solution.
Ex: XXXX
- *\*cam_complete.txt files*: MAC solutions are written with the successions of events
fired at each step to obtain them.
Ex: XXXX
#### Quick search
1 molec
#### Advanced search
A complex property to search must be expressed as a boolean formula with the names of the entities as variables.
The logical operators available are `OR`, `AND`, `NOT`.
Most of the time, the number of steps to reach a solution is significant.
Therefore, it can be limited with `--steps`.
Example:
$ cadbiom_cmd compute_macs model.bcx SRP9 --all_macs --steps 7 --continue
Arguments:
- `--all_macs`: Solver will try to search all macs with 0 to the maximum of allowed steps.
- `--steps`: Maximum of allowed steps to find macs.
- `--continue`: Resume previous computations; if there is a mac file
from a previous work, last frontier entities will be reloaded.
<!--## Processing of the results files
After depositing the [BioPAX level 3 ontology](http://www.biopax.org/release/)
and the `owl` file of PID from the [GitHub repository](https://github.com/NCIP/pathway-interaction-database/blob/master/download/)
or from [PathwayCommons](http://www.pathwaycommons.org/archives/PC2/) on a triplestore like virtuoso,
the query and conversion command to the Cadbiom format is as follows:
Tri
affichage graphique génération des matrices-->
*[RDF]: Resource Description Framework
*[URI]: Uniform Resource Identifier
*[OWL]: Web Ontology Language
*[BioPAX]: Biological Pathway Exchange
\ No newline at end of file
# GUI package
## Installation
This program is tested on python 2.7
(Indeed, the GUI is based on GTK2, and sadly, can not be easily ported to GTK3 with Python 3).
Please check the system requirements on the
[Main website](http://cadbiom.genouest.org/download.html) or [Gitlab](https://gitlab.inria.fr/pvignet/cadbiom).
As always, the use of a Python virtual environment
(via [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/)) is **strongly advised**.
### From PyPI
pip install cadbiom_gui
### From sources for developers
cd gui/
python2.7 setup.py develop
python2.7 setup.py develop --uninstall
## Usage
Just type:
$ cadbiom
.. CADBIOM documentation master file, created by
sphinx-quickstart on Fri Mar 23 18:00:42 2018.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to CADBIOM's documentation!
===================================
.. toctree::
:maxdepth: 2
:caption: Contents:
command_line_package
library_package
gui_package
examples
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
# Library package
## Installation
```eval_rst
.. note:: The library is installed when the gui or the command line is installed via pip.
```
This program is tested on python 2.7
(Indeed, the GUI is based on GTK2, and sadly, can not be easily ported to GTK3 with Python 3).
Please check the system requirements on the
[Main website](http://cadbiom.genouest.org/download.html) or [Gitlab](https://gitlab.inria.fr/pvignet/cadbiom).
As always, the use of a Python virtual environment
(via [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/en/latest/)) is **strongly advised**.
### From PyPI
pip install cadbiom
### From sources for developers
cd library/
python2.7 setup.py develop
python2.7 setup.py develop --uninstall
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment