added bonobo to docs and small readme fix. Added LIONESS examples (#337)

Co-authored-by: violafanfani <[email protected]>

Author: violafanfani

README.md

@@ -14,7 +14,7 @@ netZooPy is tested on: (OS: Ubuntu + Macos) X (Language: Python v3.7 + Python v3
 
 ## Description
 
-netZooPy is an R package to reconstruct, analyse, and plot biological networks.
+netZooPy is a python package to reconstruct, analyse, and plot biological networks.
 
 ## Features
 
@@ -36,12 +36,6 @@ netZooPy currently integrates
 * **COBRA** (Co-expression Batch Reduction Adjustment). Batch effects and other covariates are known to induce spurious associations in co-expression networks and confound differential gene expression analyses. These effects are corrected for using various methods prior to downstream analyses such as the inference of co-expression networks and computing differences between them. In differential co-expression analysis, the pairwise joint distribution of genes is considered rather than independently analyzing the distribution of expression levels for each individual gene. Computing co-expression matrices after standard batch correction on gene expression data is not sufficient to account for the possibility of batch-induced changes in the correlation between genes as existing batch correction methods act solely on the marginal distribution of each gene. Consequently, uncorrected, artifactual differential co-expression can skew the correlation structure such that network-based methods that use gene co-expression can produce false, nonbiological associations even using data corrected using standard batch correction. Co-expression Batch Reduction Adjustment (COBRA) addresses this question by computing a batch-corrected gene co-expression matrix based on estimating a conditional covariance matrix. COBRA estimates a reduced set of parameters that express the co-expression matrix as a function of the sample covariates and can be used to control for continuous and categorical covariates. The method is computationally fast and makes use of the inherently modular structure of genomic data to estimate accurate gene regulatory associations and enable functional analysis for high-dimensional genomic data.
 
 
-
-
-
-
-
-
 * **BONOBO** (Bayesian Optimized Networks Obtained By assimilating Omics data) is a scalable Bayesian model for deriving individual sample-specific co-expression networks by recognizing variations in molecular interactions across individuals. For every sample, BONOBO assumes a Gaussian distribution on the log-transformed centered gene expression and a conjugate prior distribution on the sample-specific co-expression matrix constructed from all other samples in the data. Combining the sample-specific gene expression with the prior distribution, BONOBO yields a closed-form solution for the posterior distribution of the sample-specific co-expression matrices
 
 

docs/changelog.rst

@@ -2,6 +2,12 @@
 Changelog
 ==========
 
+0.10.1
+-------------------------
+
+- Added BONOBO to docs.
+- Added LIONESS examples to docs.
+- Fixed mistake in README.
 
 0.10.0
 -------------------------

docs/functions/api.rst

@@ -1,22 +1,35 @@
 The Animals (API)
 -------------------
 
+Animals listed in alphabetical order.
 
-Panda
+BONOBO
 ======
 
-.. autoclass:: netZooPy.panda.panda.Panda
+To run BONOBO you can first initialize the class with the expression data, 
+and then run the compute_bonobo function to get the results: 
+
+.. code-block:: 
+
+   bonobo_obj_sparse = Bonobo(expression_file)
+   bonobo_obj_sparse.run_bonobo(keep_in_memory=True, output_fmt='.hdf', sparsify=True, output_folder='../data/processed/bonobo_sparse_pvals/', save_pvals=False)
+
+Here are the main functions and classes in the BONOBO module:
+
+.. autoclass:: netZooPy.ligress.bonobo.Bonobo
    :members:
    :undoc-members:
    :inherited-members:
    :private-members:
 
-.. autoclass:: netZooPy.panda.analyze_panda.AnalyzePanda
-   :members:
-   :undoc-members:
-   :private-members:
+Other functions
+~~~~~~~~~~~~~~~
+
+.. autofunction:: netZooPy.ligress.bonobo.compute_bonobo
+
+.. autofunction:: netZooPy.ligress.io.prepare_expression
 
-Condor
+CONDOR
 ======
 
 .. autoclass:: netZooPy.condor.condor.condor_object
@@ -29,7 +42,7 @@ Other function
 ~~~~~~~~~~~~~~~
 .. autofunction:: netZooPy.condor.run_condor
 
-Lioness
+LIONESS
 =========
 
 
@@ -44,7 +57,26 @@ Lioness
    :undoc-members:
    :private-members:
 
-Puma
+
+
+
+
+PANDA
+======
+
+.. autoclass:: netZooPy.panda.panda.Panda
+   :members:
+   :undoc-members:
+   :inherited-members:
+   :private-members:
+
+.. autoclass:: netZooPy.panda.analyze_panda.AnalyzePanda
+   :members:
+   :undoc-members:
+   :private-members:
+
+
+PUMA
 =====
 
 .. autoclass:: netZooPy.puma.puma.Puma
@@ -53,7 +85,7 @@ Puma
    :inherited-members:
    :private-members:
 
-Sambar
+SAMBAR
 ======
 
 .. autofunction:: netZooPy.sambar.sambar
@@ -70,4 +102,3 @@ Extra sambar functions
 .. autofunction:: netZooPy.sambar.binomial_dist
 
 .. autofunction:: netZooPy.sambar.clustering
-

docs/functions/cli.rst

@@ -39,3 +39,5 @@ Lioness
 ~~~~~~~~~
 
 .. autofunction:: netZooPy.lioness.run_lioness.main
+
+Common usage

netZooPy/command_line.py

@@ -167,6 +167,22 @@ def lioness(expression, motif, ppi, output_panda, output_lioness, el, fmt, compu
 
             netzoopy lioness -e tests/puma/ToyData/ToyExpressionData.txt -m tests/puma/ToyData/ToyMotifData.txt -p tests/puma/ToyData/ToyPPIData.txt -op test_panda.txt -ol lioness/
     
+    **Example for GPU computing**. Here the biggest limitation is GPU size, hence we need to optimize the precision and make
+    sure we don't use all genes, but only the intersection with the PANDA priors. We also save the single lioness
+    networks as they are computed:
+    
+        netzoopy lioness -e <expression_file> -m <motif_file> -p <ppi_file> -op output_panda.txt -ol output_lioness_folder/ --computing gpu --precision single --mode_process intersection --save_single_lioness --ignore_final
+
+    **LIONESS on a subset of samples**. This is especially useful if you need to test whether your data is suitable for
+    LIONESS/you have enough resources. By specifying --panda_start and --panda_end the number of samples are restricted
+    and only the samples in the subset are used for LIONESS. The background is the one specified by panda_start and
+    panda_end. Alternatively you can use the --subset_numbers and --subset_names flags to specify the samples to use. In this case
+    the PANDA will be computed on all samples, but then LIONESS will be computed and saved only for a subset of samples:
+    
+        netzoopy lioness -e <expression_file> -m <motif_file> -p <ppi_file> -op output_panda.txt -ol output_lioness_folder/ --computing <gpu|cpu> --panda_start 1 --panda_end 5 --precision single --mode_process intersection --save_single_lioness --ignore_final
+    
+
+
     Reference:
         Kuijjer, Marieke Lydia, et al. "Estimating sample-specific regulatory networks." Iscience 14 (2019): 226-240.