powergrasp 0.3.4

Graph compression with Answer Set Programming

# PowerGrASP
The Python Powergraph analysis tool, based on Answer Set Programming solving and formal concept analysis.
More documentation about PowerGrASP can be found in the [documentation file](https://github.com/Aluriak/PowerGrASP/blob/master/doc/documentation.mkd).


## Requirements
A simple `pip install powergrasp` is theorically sufficient.

However, because of the pyasp module, a file manipulation must be realised :
- get compatible versions of [gringo](http://sourceforge.net/projects/potassco/files/gringo/4.5.3/) and [clasp](http://sourceforge.net/projects/potassco/files/clasp/3.1.3/) on the [potassco website](http://sourceforge.net/projects/potassco/files);
- put the retrieved executables __gringo__ and __clasp__ in __/usr/lib/python3.5/site-packages/pyasp/bin__ (see table below for details), with names __gringo4__ and __clasp__, respectively;

This manipulation is necessary while the *pyasp* module doesn't get the used version of gringo and clasp. (4.5.3 and 3.1.3)
PowerGrASP was tested with gringo 4.5.1 and 4.5.3, and not compliant with versions 4.4.x, because of some known bugs.
Note that, if you use a virtualenv, the directories where executables should be put are in the lib directory create by virtualenv.

A more complex but more useful `pip install --user powergrasp` performs the installation in the user level.
This allows powergrasp to store all its logs, data results,… without problems in its self data and logs directories.


installation | directory where __gringo__ and __clasp__ should be put (likely)
------------------|-------------------
system (pip) | __/usr/lib/python3.5/site-packages/pyasp/bin
user (pip --user) | ~/.local/lib/python3.5/site-packages/pyasp/bin
virtualenv + pip | path/to/virtualenv/lib/python3.5/site-packages/pyasp/bin



## Basic use
PowerGrASP can be used as a script:

python3 powergrasp --graph-data=human_proteom.lp --output-file=for_cytoscape.bbl

Or can be embedded in any python program:

import powergrasp

powergrasp.compress('human_proteom.lp', 'for_cytoscape.bbl')


## Help & Details
### General overview
The compression is configurable through command line arguments or compress function parameters.
Used ASP source code can be changed, interactive mode can be set,… Please look at help and docstring:

# in terminal
python3 powergrasp --help
# in python
>>> help(powergrasp)
# or, in terminal with make
make help


### Standard output management
By default, PowerGrASP generates lots of outputs in stdout, essentially for debugging and compression tracking.
With the option *loglevel*, its possible to control this behavior:

python3 powergrasp --graph-data=tests/proteome_yeast_2.lp --loglevel=warning

This will block all outputs with a strictly lesser priority than warning.
Available levels comes from logging API:

log level | PowerGrASP
-----------------|-------------------
critical | totally silencious
error | very rarely disturbing
warning | rarely disturbing
info | trackable
debug | trackable with __high__ verbosity
notset | kraken released

Please note that some options (notabily *count-models*) are completely independant of this logging management.


### Statistics
The compression compute some statistics about itself, and generate the final results
at the end of the compression in the standard output.
With some arguments, you can also show a colored graphic :

python3 powergrasp --graph-data=tests/proteome_yeast_2.lp --stats-file=data/statistics.csv --plot-stats

Instead of show it, powergrasp can save it in png (note that the *--plot-stats* flag is not necessary when *plot-file* option is given):

python3 powergrasp --graph-data=tests/proteome_yeast_2.lp --stats-file=data/statistics.csv --plot-file=data/statistics.png


### Answer Set Programming
ASP is a declarative and logic language, designed for the treatment of combinatorial problems (like graph compression).
The implementation used in this project is the [*Potsdam Answer Set Solving Collection*](http://potassco.sourceforge.net/index.html).

All ASP source codes necessary for the PowerGrASP program can be found in *powergrasp/ASPsources/* directory.


### I/O

#### Input file
PowerGrASP doesn't generate logging for pleasure : it actually perform a treatment on input data, if provided.
The supported input file formats are currently :
- ASP: atoms edge/2, with edge(X,Y) describing a link between nodes X and Y.
- SBML: a regular SBML file, when species and reactions will be treated as nodes.
- GML: a regular Graph Modeling Language file, readable by networkx python module.

Other formats will be supported in the future.

#### Output file
While the only way to print a power graph is provided by the [CyOog](http://www.biotec.tu-dresden.de/research/schroeder/powergraphs/) plugin of Cytoscape, output format is limited to *Bubble*, which seems to be an endemic format.
Another output format support is possible by create a new Converter class (see *powergrasp/converter/*).
Cytoscape, for using the CyOog plugin, must be in version __[2.x](http://www.cytoscape.org/download_old_versions.html)__.



### Interests & References

The Power Graph approach for graph compression allows a lossless compression with an emphasis on biological meaning.
In fact, formal concepts used by Power Graph analysis have a sens in biology, especially in the case of proteomes.

All graphs can be compressed through Power Graph, and will be more readable once compressed,
but interactomes, at least, also gain in interpretability.

The main inspiration of PowerGrASP : PowerGraph Analysis:

Loïc Royer, Matthias Reimann, Bill Andreopoulos, and Michael Schroeder.
Unraveling Protein Networks with Power Graph Analysis.
PLoS Comput Biol, 4(7):e1000108, July 2008.

Usage of the PowerGraph Analysis :

Loic Royer, Matthias Reimann, A. Francis Stewart, and Michael Schroeder.
Network Compression as a Quality Measure for Protein Interaction Networks.
PLoS ONE, 7(6):e35729, June 2012.

Yun Zhang, Charles A Phillips, Gary L Rogers, Erich J Baker, Elissa J Chesler, and Michael A Langston.
On finding bicliques in bipartite graphs: a novel algorithm and
its application to the integration of diverse biological data types.
BMC Bioinformatics, 15(1):110, 2014.

ASP through Potassco implementation :

M. Gebser, R. Kaminski, B. Kaufmann, M. Ostrowski, T. Schaub, and M. Schneider.
Potassco: The Potsdam answer set solving collection.
AI Communications, 24(2):107–124, 2011.