Skip to content

Commit d6cf694

Browse files
ddomingofddomingof
committed
Add documentation
1 parent 0d45d93 commit d6cf694

7 files changed

Lines changed: 148 additions & 5 deletions

File tree

‎docs/source/cli.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Command Line Interface
2+
======================
3+
DiffuPy Command Line Interface
4+
5+
.. automodule:: diffupy.cli
6+
:members:

‎docs/source/constants.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Constants
2+
=========
3+
Constants at DiffuPy.
4+
5+
.. automodule:: diffupy.constants
6+
:members:

‎docs/source/diffusion.rst‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
Diffusion
2+
=========
3+
The methods in this modules manage the treatment of the different score diffusion methods applied of/from an path set of
4+
labels/scores of/on a certain network (as a graph format or a graph kernel matrix stemming from a graph).
5+
6+
Diffusion methods procedures provided in this package differ on:
7+
(a) How to distinguish positives, negatives and unlabelled examples.
8+
(b) Their statistical normalisation.
9+
10+
Input scores can be specified in three formats:
11+
1. A named numeric vector, whereas if several of these vectors that share the node names need to be smoothed.
12+
2. A column-wise matrix. However, if the unlabelled entities are not the same from one case to another.
13+
2. A named list of such score matrices can be passed to this function. The path format will be kept in the output.
14+
15+
If the path labels are not quantitative, i.e. positive(1), negative(0) and possibly unlabelled, all the scores raw, gm,
16+
ml, z, mc, ber_s, ber_p can be used.
17+
18+
Methods
19+
-------
20+
21+
Methods without statistical normalisation
22+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
23+
- **raw**: positive nodes introduce unitary flow {y_raw[i] = 1} to the network, whereas either negative and unlabelled
24+
nodes introduce null diffusion {y_raw[j] = 0}. [Vandin, 2011]. They are computed as: f_{raw} = K · y_{raw}. Where K is
25+
a graph kernel, see :doc:`kernel <kernel>`. These scores treat negative and unlabelled nodes equivalently.
26+
27+
- **ml**: Same as raw, but negative nodes introduce a negative unit of flow. Therefore not equivalent to unlabelled
28+
nodes. [Zoidi, 2015]
29+
30+
- **gl**: Same as ml, but the unlabelled nodes are assigned a (generally non-null) bias term based on the total number
31+
of positives, negatives and unlabelled nodes [Mostafavi, 2008].
32+
33+
- **ber_s**: A quantification of the relative change in the node score before and after the network smoothing. The score
34+
for a particular node i can be written as f_{ber_s}[i] = f_{raw}[i] / (y_{raw}[i] + eps). Where eps is a parameter
35+
controlling the importance of the relative change.
36+
37+
Methods with statistical normalisation
38+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
39+
- **z**: a parametric alternative to the raw score of node is subtracted its mean value and divided by its standard
40+
deviation. Differential trait of this package. The statistical moments have a closed analytical form and are inspired
41+
in [Harchaoui, 2013].
42+
43+
- **mc**: the score of node code {i} is based on its empirical p-value, computed by permuting the path {n.perm} times.
44+
It is roughly the proportion of path permutations that led to a diffusion score as high or higher than the original
45+
diffusion score.
46+
47+
- **ber_p**: A used in [Bersanelli, 2016], this score combines raw and mc, in order to take into account both the
48+
magnitude of the {raw} scores and the effect of the network topology: this is a quantification of the relative change
49+
in the node score before and after the network smoothing.
50+
51+
Summary Table
52+
-------------
53+
| Scores | y+ | y- | yn | Normalized | Stochastic | Quantitative | Reference
54+
Unnormalized
55+
| raw | 1 | 0 | 0 | No | No | Yes | Vandin (2010) |
56+
57+
| ml | 1 | -1 | 0 | No | No | No | Tsuda (2010) |
58+
59+
| gm | 1 | -1 | k | No | No | No | Mostafavi (2008) |
60+
61+
| ber_s | 1 | 0 | 0 | No | No | Yes | Bersanelli (2016)|
62+
63+
Normalized
64+
65+
| ber_p | 1 | 0 | 0* | Yes | Yes | Yes | Bersanelli (2016)|
66+
67+
| mc | 1 | 0 | 0* | Yes | Yes | Yes | Bersanelli (2016)|
68+
69+
| z | 1 | 0 | 0* | Yes | No | Yes | Harchaoui (2013) |
70+
71+
72+
.. automodule:: diffupy.diffusion
73+
:members:
74+
75+
.. automodule:: diffupy.diffusion_raw
76+
:members:

‎docs/source/index.rst‎

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,38 @@
1-
DiffuPy
2-
=======
1+
DiffuPy |release| Documentation
2+
===============================
3+
DiffuPy is a generalizable Python implementation of the numerous label propagation algorithms inspired by the diffuStats
4+
R package [1]. DiffuPy supports generic graph formats such as JSON, CSV, GraphML, or GML.
5+
6+
Installation is as easy as getting the code from `PyPI <https://pypi.python.org/pypi/diffupy>`_ with
7+
:code:`python3 -m pip install diffupy`. See the :doc:`installation <installation>` documentation.
8+
9+
.. seealso::
10+
11+
- Documented on `Read the Docs <http://diffupy.readthedocs.io/>`_
12+
- Versioned on `GitHub <https://github.com/multipaths/diffupy>`_
13+
- Tested on `Travis CI <https://travis-ci.org/multipaths/diffupy>`_
14+
- Distributed by `PyPI <https://pypi.python.org/pypi/diffupy>`_
15+
316
.. automodule:: diffupy
417

518
.. toctree::
619
:maxdepth: 2
720
:caption: Contents:
821

22+
installation
23+
cli
924
kernel
25+
diffusion
26+
constants
27+
matrix
28+
29+
References
30+
----------
31+
.. [1] Picart-Armada, S., *et al.* (2017). `Null diffusion-based enrichment for metabolomics data
32+
<https://doi.org/10.1371/journal.pone.0189012>`_. *PloS one* 12.12.
33+
34+
Disclaimer
35+
----------
36+
DiffuPy is a scientific software that has been developed in an academic capacity, and thus comes with no warranty or
37+
guarantee of maintenance, support, or back-up of data.
1038

11-
Index
12-
=====
13-
* :ref:`genindex`

‎docs/source/installation.rst‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
Installation
2+
============
3+
The latest stable code can be installed from `PyPI <https://pypi.python.org/pypi/pybel>`_ with:
4+
5+
.. code-block:: sh
6+
7+
$ python3 -m pip install diffupy
8+
9+
The most recent code can be installed from the source on `GitHub <https://github.com/diffupy/diffupy>`_ with:
10+
11+
.. code-block:: sh
12+
13+
$ python3 -m pip install git+https://github.com/diffupy/diffupy.git
14+
15+
For developers, the repository can be cloned from `GitHub <https://github.com/diffupy/diffupy>`_ and installed in
16+
editable mode with:
17+
18+
.. code-block:: sh
19+
20+
$ git clone https://github.com/diffupy/diffupy.git
21+
$ cd diffupy
22+
$ python3 -m pip install -e .

‎docs/source/kernel.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
Kernel
22
======
3+
Pool of kernels available at DiffuPy.
4+
35
.. automodule:: diffupy.kernel
46
:members:

‎docs/source/matrix.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Matrix
2+
======
3+
Matrix class
4+
5+
.. automodule:: diffupy.matrix
6+
:members:

0 commit comments

Comments
 (0)