Updated docs

Author: PauBadiaM

CHANGELOG.md

@@ -8,8 +8,69 @@ and this project adheres to [Semantic Versioning][].
 [keep a changelog]: https://keepachangelog.com/en/1.0.0/
 [semantic versioning]: https://semver.org/spec/v2.0.0.html
 
-## [Unreleased]
+## 2.0.0
+
+Major update to accomodate the scverse :cite:`scverse` template.
+
+All functions have been rewritten to follow the new API, errors when running previous versions (`1.X.X`) are expected if `decoupler >= 2.0.0` is installed.
+
+### Changes
+
+- Methods are now in the `mt` module and are built from shared class `Method`
+  - Use `decoupler.mt.<method_name>` to call a method
+  - `min_n` argument has been renamed `tmin`
+  - New argument `bsize` allows to run a method with batches in case excessive memory usage is an issue
+  - :math:`p_{values}` of the enrichment scores are now corrected by Benjamini-Hochberg
+  - `mdt` and `udt` are now based on `xgboost` instead of `sklearn` for better scalability. `udt` statistic is now the coefficient of determination :math:`R^2` instead of the importance of a single decision tree.
+  - `ora` now returns the odds ratio of the contingency table as a statistic, and computes a two-sided Fisher exact test instead of a one-sided one
+  - `viper` now correctly estimates shadow regulons when network weights are values other than -1 or +1
+  - `wsum` and `wmean` are deprecated, instead now the method `waggr` allows to run both methods and any custom function. This makes it easier to quickly test new enrichment methods without having to deal with `decoupler`'s implementation
+- Databases from Omnipath can now be accessed through the new `op` module
+  - Use `decoupler.op.<resource_name>` to access a database  
+  - Removed the `omnipath` package as a dependancy
+  - Fixed `collectri` to the publication version instead of the OmniPath one
+  - Made `progeny` only return significant genes by default instead of the top N genes per pathway
+- Plots are now in a new `pl` module
+    - Use `decoupler.pl.<plot_name>` to call a plot
+    - They use a common class `Plotter` to make it easier to share arguments between them
+    - `plot_violins` has been deprecated
+    - Names that have changed
+      - `plot_psbulk_samples` to `filter_samples`
+      - `plot_running_score` to `leading_edge`
+      - `plot_associations` to `obsm`
+      - `plot_targets` to `source_targets`
+- Preprocessing functions are now in the new `pp` module
+  - Renamed `check_corr` to `net_corr`, now also returns adjusted :math:`p_{values}`
+  - Renamed `get_acts` to `get_obsm`
+  - Renamed `get_pseudobulk` to `pseudobulk`. Now it does not automatically remove low quality samples, this is now done with the function `filter_samples`
+  - Deprecated `get_contrast`, `get_top_targets` and `format_contrast_results`. `PyDESeq2` should be used instead
+  - Moved `rank_sources_groups` to the new `tl` module as `rankby_group`
+  - Moved `get_metadata_associations` to the new `tl` module as `rankby_obsm`
+- Moved the benchmarking pipeline inside a new `bm` module, with its metrics and plotting functions in further submodules (`bm.metric` and `bm.pl`)
 
 ### Added
 
-- Basic tool, preprocessing and plotting functions
+- `ds` module with functions to download several datasets at different resolutions
+    - Bulk: `hsctgfb` and `knocktf`
+    - Single-cell: `pbmc3k`, `covid5k` and `erygast1k`
+    - Spatial: `msvisium`
+    - Toy data: `toy` and `toy_bench`
+    - Utils: `ensmbl_to_symbol`
+- New database functions in the `op` module
+  - Added `hallmark` as a custom resource
+- New plotting funcitons in the `pl` module
+  - Added `obsbar` to plot size of metadata columns in `anndata.AnnData.obs`
+  - Added `order` to plot sources or features along a continous process such as a trajectory
+  - Added `order_targets` to plot the targets of a given source along a continous process
+  - 
+- New preprocessing functions in the `pp` module
+  - Added two functions to format networks, `adjmat` to return an adjacency matrix, and `idxmax` to return a list of sets
+  - Added `filter_samples` to filter pseudobulk profiles after running `pseudobulk`
+  - Added `knn` to calculate K-Nearest Neighbors similarities based on spatial distances
+  - Added `bin_order` to bin features across a continous process
+- `tl` module with functions to perform statistical tests
+  - Added `rankby_order` to test for non-linear associations of features with a continous process
+- New benchmarking metrics and plotting related functions in the `bm` module
+  - Added two more metrics, `F-score` and `qrank`
+  - Added shared plots for metrics, `bm.pl.auc`, `bm.pl.fscore` and `bm.pl.qrank`
+  - Added a summary plot across metrics `bm.pl.summary`

README.md

@@ -1,4 +1,6 @@
-# decoupler - Ensemble of methods to infer enrichment scores <img src="https://github.com/saezlab/decoupleR/blob/master/inst/figures/logo.svg?raw=1" align="right" width="120" class="no-scaled-link" />
+# decoupler - Ensemble of methods to infer enrichment scores
+<img src="https://github.com/saezlab/decoupleR/blob/master/inst/figures/logo.svg?raw=1" align="right" width="120" class="no-scaled-link" />
+   
 
 [![Tests][badge-tests]][tests]
 [![Documentation][badge-docs]][documentation]

docs/_static/css/custom.css

@@ -2,3 +2,13 @@
 div.cell_output table.dataframe {
     font-size: 0.8em;
 }
+
+/* Adjust the logo size */
+.logo img {
+    width: 50%;   /* or any percentage you want */
+    height: auto; /* maintain aspect ratio */
+}
+
+img.no-scaled-link {
+    background: transparent !important;
+}

docs/_static/images/logo.png

@@ -97,6 +97,7 @@
     "scanpy": ("https://scanpy.readthedocs.io/en/stable/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "matplotlib": ("https://matplotlib.org/stable/", None),
+    'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
 }
 
 # List of patterns, relative to source directory, that match files and
@@ -113,8 +114,9 @@
 html_theme = "sphinx_book_theme"
 html_static_path = ["_static"]
 html_css_files = ["css/custom.css"]
-
-html_title = project_name
+html_logo = '_static/images/logo.png'
+html_favicon = '_static/images/logo.png'
+#html_title = project_name
 
 html_theme_options = {
     "repository_url": repository_url,

docs/_static/images/mlm.png

@@ -3,10 +3,11 @@
 ```
 
 ```{toctree}
-:maxdepth: 2
+:maxdepth: 1
+:hidden: true
 
-api.md
+api
 notebooks/index
-changelog.md
-references.md
+changelog
+references
 ```

docs/_static/images/ora.png

@@ -369,4 +369,106 @@ @article{pax5
   year = {2007},
   month = apr,
   pages = {463–470}
-}
+}
+
+@article{aucell,
+  title = {SCENIC: single-cell regulatory network inference and clustering},
+  volume = {14},
+  ISSN = {1548-7105},
+  url = {http://dx.doi.org/10.1038/nmeth.4463},
+  DOI = {10.1038/nmeth.4463},
+  number = {11},
+  journal = {Nature Methods},
+  publisher = {Springer Science and Business Media LLC},
+  author = {Aibar,  Sara and González-Blas,  Carmen Bravo and Moerman,  Thomas and Huynh-Thu,  V\^an Anh and Imrichova,  Hana and Hulselmans,  Gert and Rambow,  Florian and Marine,  Jean-Christophe and Geurts,  Pierre and Aerts,  Jan and van den Oord,  Joost and Atak,  Zeynep Kalender and Wouters,  Jasper and Aerts,  Stein},
+  year = {2017},
+  month = oct,
+  pages = {1083–1086}
+}
+
+@article{gsea,
+  title = {Gene set enrichment analysis: A knowledge-based approach for interpreting genome-wide expression profiles},
+  volume = {102},
+  ISSN = {1091-6490},
+  url = {http://dx.doi.org/10.1073/pnas.0506580102},
+  DOI = {10.1073/pnas.0506580102},
+  number = {43},
+  journal = {Proceedings of the National Academy of Sciences},
+  publisher = {Proceedings of the National Academy of Sciences},
+  author = {Subramanian,  Aravind and Tamayo,  Pablo and Mootha,  Vamsi K. and Mukherjee,  Sayan and Ebert,  Benjamin L. and Gillette,  Michael A. and Paulovich,  Amanda and Pomeroy,  Scott L. and Golub,  Todd R. and Lander,  Eric S. and Mesirov,  Jill P.},
+  year = {2005},
+  month = sep,
+  pages = {15545–15550}
+}
+
+@article{gsva,
+  title = {GSVA: gene set variation analysis for microarray and RNA-Seq data},
+  volume = {14},
+  ISSN = {1471-2105},
+  url = {http://dx.doi.org/10.1186/1471-2105-14-7},
+  DOI = {10.1186/1471-2105-14-7},
+  number = {1},
+  journal = {BMC Bioinformatics},
+  publisher = {Springer Science and Business Media LLC},
+  author = {H\"{a}nzelmann,  Sonja and Castelo,  Robert and Guinney,  Justin},
+  year = {2013},
+  month = jan 
+}
+
+@inproceedings{xgboost,
+  series = {KDD ’16},
+  title = {XGBoost: A Scalable Tree Boosting System},
+  url = {http://dx.doi.org/10.1145/2939672.2939785},
+  DOI = {10.1145/2939672.2939785},
+  booktitle = {Proceedings of the 22nd ACM SIGKDD International Conference on Knowledge Discovery and Data Mining},
+  publisher = {ACM},
+  author = {Chen,  Tianqi and Guestrin,  Carlos},
+  year = {2016},
+  month = aug,
+  pages = {785–794},
+  collection = {KDD ’16}
+}
+
+@article{ora,
+  title = {On the Interpretation of χ 2 from Contingency Tables,  and the Calculation of P},
+  volume = {85},
+  ISSN = {0952-8385},
+  url = {http://dx.doi.org/10.2307/2340521},
+  DOI = {10.2307/2340521},
+  number = {1},
+  journal = {Journal of the Royal Statistical Society},
+  publisher = {JSTOR},
+  author = {Fisher,  R. A.},
+  year = {1922},
+  month = jan,
+  pages = {87}
+}
+
+@article{viper,
+  title = {Functional characterization of somatic mutations in cancer using network-based inference of protein activity},
+  volume = {48},
+  ISSN = {1546-1718},
+  url = {http://dx.doi.org/10.1038/ng.3593},
+  DOI = {10.1038/ng.3593},
+  number = {8},
+  journal = {Nature Genetics},
+  publisher = {Springer Science and Business Media LLC},
+  author = {Alvarez,  Mariano J and Shen,  Yao and Giorgi,  Federico M and Lachmann,  Alexander and Ding,  B Belinda and Ye,  B Hilda and Califano,  Andrea},
+  year = {2016},
+  month = jun,
+  pages = {838–847}
+}
+
+@article{zscore,
+  title = {Robust inference of kinase activity using functional networks},
+  volume = {12},
+  ISSN = {2041-1723},
+  url = {http://dx.doi.org/10.1038/s41467-021-21211-6},
+  DOI = {10.1038/s41467-021-21211-6},
+  number = {1},
+  journal = {Nature Communications},
+  publisher = {Springer Science and Business Media LLC},
+  author = {Yılmaz,  Serhan and Ayati,  Marzieh and Schlatzer,  Daniela and undefinedi\c{c}ek,  A. Erc\"{u}ment and Chance,  Mark R. and Koyut\"{u}rk,  Mehmet},
+  year = {2021},
+  month = feb 
+}