decoupler 2.0.0__tar.gz → 2.0.2__tar.gz

{decoupler-2.0.0 → decoupler-2.0.2}/.github/workflows/test.yaml

@@ -78,11 +78,14 @@ jobs:
           MPLBACKEND: agg
           PLATFORM: ${{ matrix.os }}
           DISPLAY: :42
+          NUMBA_JIT_COVERAGE: "1"
         run: uvx hatch run ${{ matrix.env.name }}:run-cov
       - name: generate coverage report
         run: uvx hatch run ${{ matrix.env.name }}:coverage xml
       - name: Upload coverage
         uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
 
   # Check that all tests defined above pass. This makes it easy to set a single "required" test in branch
   # protection instead of having to update it frequently. See https://github.com/re-actors/alls-green#why.

{decoupler-2.0.0 → decoupler-2.0.2}/CHANGELOG.md

@@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning][].
 
 ## 2.0.0
 
-Major update to accomodate the scverse :cite:`scverse` template.
+Major update to accomodate the scverse template {cite}`scverse`.
 
 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.
 
@@ -20,8 +20,8 @@ All functions have been rewritten to follow the new API, errors when running pre
   - 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.
+  - $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 $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
@@ -40,7 +40,7 @@ All functions have been rewritten to follow the new API, errors when running pre
       - `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 `check_corr` to `net_corr`, now also returns adjusted $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

{decoupler-2.0.0 → decoupler-2.0.2}/LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2025, Pau Badia i Mompel
+Copyright (c) 2025, Pau Badia i Mompel, Saez lab
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

{decoupler-2.0.0 → decoupler-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: decoupler
-Version: 2.0.0
+Version: 2.0.2
 Summary: Python package to perform enrichment analysis from omics data.
 Project-URL: Documentation, https://decoupler.readthedocs.io/
 Project-URL: Homepage, https://github.com/PauBadiaM/decoupler
@@ -9,7 +9,7 @@ Author: Pau Badia i Mompel
 Maintainer-email: Pau Badia i Mompel <pau.badia@uni-heidelberg.de>
 License: BSD 3-Clause License
         
-        Copyright (c) 2025, Pau Badia i Mompel
+        Copyright (c) 2025, Pau Badia i Mompel, Saez lab
         All rights reserved.
         
         Redistribution and use in source and binary forms, with or without
@@ -47,6 +47,7 @@ Requires-Dist: adjusttext
 Requires-Dist: anndata
 Requires-Dist: docrep
 Requires-Dist: igraph
+Requires-Dist: ipywidgets
 Requires-Dist: marsilea
 Requires-Dist: numba
 Requires-Dist: requests
@@ -134,7 +135,7 @@ There are several alternative options to install decoupler:
 pip install decoupler
 ```
 
-2. Install the latest stable version from [conda-forge][conda] using mamba or conda:
+2. Install the latest stable version from [conda-forge][conda] using mamba or conda (pay attention to the `-py` suffix at the end):
 
 ```bash
 mamba create -n=dcp conda-forge::decoupler-py

{decoupler-2.0.0 → decoupler-2.0.2}/README.md

@@ -53,7 +53,7 @@ There are several alternative options to install decoupler:
 pip install decoupler
 ```
 
-2. Install the latest stable version from [conda-forge][conda] using mamba or conda:
+2. Install the latest stable version from [conda-forge][conda] using mamba or conda (pay attention to the `-py` suffix at the end):
 
 ```bash
 mamba create -n=dcp conda-forge::decoupler-py

decoupler-2.0.2/docs/api/bm.md

@@ -0,0 +1,44 @@
+# Benchmark
+
+
+## Pipeline
+```{eval-rst}
+.. module:: decoupler.bm
+.. currentmodule:: decoupler
+
+.. autosummary::
+    :toctree: generated
+
+    bm.benchmark
+```
+
+## Metrics
+
+```{eval-rst}
+.. module:: decoupler.bm.metric
+.. currentmodule:: decoupler
+
+.. autosummary::
+    :toctree: generated
+
+    bm.metric.auc
+    bm.metric.fscore
+    bm.metric.qrank
+    bm.metric.hmean
+```
+
+## Plotting
+
+```{eval-rst}
+.. module:: decoupler.bm.pl
+.. currentmodule:: decoupler
+
+.. autosummary::
+    :toctree: generated
+
+    bm.pl.auc
+    bm.pl.fscore
+    bm.pl.qrank
+    bm.pl.bar
+    bm.pl.summary
+```

decoupler-2.0.2/docs/api/ds.md

@@ -0,0 +1,48 @@
+# Datasets
+
+## Bulk
+```{eval-rst}
+.. module:: decoupler.ds
+.. currentmodule:: decoupler
+
+.. autosummary::
+    :toctree: generated
+
+    ds.hsctgfb
+    ds.knocktf
+```
+
+## Single-cell
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+
+    ds.covid5k
+    ds.erygast1k
+    ds.pbmc3k
+```
+
+## Spatial
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+
+    ds.msvisium
+```
+
+## Toy
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+
+    ds.toy
+    ds.toy_bench
+```
+
+## Utils
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+
+    ds.ensmbl_to_symbol
+```

decoupler-2.0.2/docs/api/index.md

@@ -0,0 +1,24 @@
+# API
+
+Import decoupler as:
+
+```
+import decoupler as dc
+```
+
+```{toctree}
+:maxdepth: 2
+
+bm
+ds
+mt
+op
+pp
+```
+
+```{toctree}
+:maxdepth: 1
+
+pl
+tl
+```

decoupler-2.0.2/docs/api/mt.md

@@ -0,0 +1,34 @@
+# Methods
+
+## Single methods
+
+```{eval-rst}
+.. module:: decoupler.mt
+.. currentmodule:: decoupler
+
+.. autosummary::
+    :toctree: generated
+
+    mt.aucell
+    mt.gsea
+    mt.gsva
+    mt.mdt
+    mt.mlm
+    mt.ora
+    mt.udt
+    mt.udt
+    mt.ulm
+    mt.viper
+    mt.waggr
+    mt.zscore
+```
+
+## Multiple methods
+
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+
+    mt.decouple
+    mt.consensus
+```

decoupler-2.0.2/docs/api/op.md

@@ -0,0 +1,28 @@
+# OmniPath
+
+## Resources
+
+```{eval-rst}
+.. module:: decoupler.op
+.. currentmodule:: decoupler
+
+.. autosummary::
+    :toctree: generated
+
+    op.collectri
+    op.dorothea
+    op.hallmark
+    op.progeny
+    op.resource
+```
+
+## Utils
+
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+
+    op.show_resources
+    op.show_organisms
+    op.translate
+```

decoupler-2.0.2/docs/api/pl.md

@@ -0,0 +1,23 @@
+# Plotting
+
+```{eval-rst}
+.. module:: decoupler.pl
+.. currentmodule:: decoupler
+
+.. autosummary::
+    :toctree: generated
+
+    pl.barplot
+    pl.dotplot
+    pl.filter_by_expr
+    pl.filter_by_prop
+    pl.filter_samples
+    pl.leading_edge
+    pl.network
+    pl.obsbar
+    pl.obsm
+    pl.order_targets
+    pl.order
+    pl.source_targets
+    pl.volcano
+```

decoupler-2.0.2/docs/api/pp.md

@@ -0,0 +1,40 @@
+# Preprocessing
+
+## Data
+```{eval-rst}
+.. module:: decoupler.pp
+.. currentmodule:: decoupler
+
+.. autosummary::
+    :toctree: generated
+
+    pp.extract
+```
+
+## Network
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+
+    pp.read_gmt
+    pp.prune
+    pp.adjmat
+    pp.idxmat
+    pp.shuffle_net
+    pp.net_corr
+```
+
+## AnnData
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+
+    pp.get_obsm
+    pp.swap_layer
+    pp.pseudobulk
+    pp.filter_samples
+    pp.filter_by_expr
+    pp.filter_by_prop
+    pp.knn
+    pp.bin_order
+```

decoupler-2.0.2/docs/api/tl.md

@@ -0,0 +1,13 @@
+# Tools
+
+```{eval-rst}
+.. module:: decoupler.tl
+.. currentmodule:: decoupler
+
+.. autosummary::
+    :toctree: generated
+
+    tl.rankby_group
+    tl.rankby_obsm
+    tl.rankby_order
+```

{decoupler-2.0.0 → decoupler-2.0.2}/docs/index.md

@@ -6,7 +6,7 @@
 :maxdepth: 1
 :hidden: true
 
-api
+api/index
 notebooks/index
 changelog
 references

{decoupler-2.0.0 → decoupler-2.0.2}/docs/notebooks/bench/index.md

@@ -1,4 +1,6 @@
 # Benchmark
 ```{toctree}
+:maxdepth: 1
+
 rna
 ```

{decoupler-2.0.0 → decoupler-2.0.2}/docs/notebooks/bulk/index.md

@@ -1,4 +1,6 @@
 # Bulk
 ```{toctree}
+:maxdepth: 1
+
 rna
 ```

{decoupler-2.0.0 → decoupler-2.0.2}/docs/notebooks/index.md

@@ -1,5 +1,7 @@
 # Tutorials
 ```{toctree}
+:maxdepth: 1
+
 example
 scell/index
 spatial/index

{decoupler-2.0.0 → decoupler-2.0.2}/docs/notebooks/omnipath/index.md

@@ -1,5 +1,7 @@
 # OmniPath
 ```{toctree}
+:maxdepth: 1
+
 licenses
 orthologs
 ```

{decoupler-2.0.0 → decoupler-2.0.2}/docs/notebooks/scell/index.md

@@ -1,5 +1,7 @@
 # Single-cell
 ```{toctree}
+:maxdepth: 1
+
 rna_sc
 rna_psbk
 rna_pstime

{decoupler-2.0.0 → decoupler-2.0.2}/docs/notebooks/spatial/index.md

@@ -1,4 +1,6 @@
 # Spatial
 ```{toctree}
+:maxdepth: 1
+
 rna_visium
 ```

{decoupler-2.0.0 → decoupler-2.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ requires = [ "hatchling" ]
 
 [project]
 name = "decoupler"
-version = "2.0.0"
+version = "2.0.2"
 description = "Python package to perform enrichment analysis from omics data."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -27,6 +27,7 @@ dependencies = [
   "numba",
   "docrep",
   "tqdm",
+  "ipywidgets",
   "xgboost",
   "seaborn",
   "requests",

{decoupler-2.0.0 → decoupler-2.0.2}/src/decoupler/bm/_run.py

@@ -4,6 +4,7 @@ import pandas as pd
 import numpy as np
 from anndata import AnnData
 
+from decoupler._docs import docs
 from decoupler._log import _log
 from decoupler.pp.net import prune
 from decoupler.mt._methods import _methods
@@ -151,6 +152,9 @@ def _metric_scores(
     verbose: bool,
     **kwargs
 ) -> None:
+    assert isinstance(metrics, (str, list)), 'metrics must be str or list'
+    if isinstance(metrics, str):
+        metrics = [metrics]
     if runby == 'expr':
         m = ('benchmark - evaluating by experiment on:\n' +
         f'n_expr={score.shape[0]}, n_sources={score.shape[1]} across metrics={metrics}')
@@ -277,6 +281,7 @@ def _eval_scores(
     return df
 
 
+@docs.dedent
 def benchmark(
     adata: AnnData,
     net: pd.DataFrame | dict,
@@ -295,6 +300,24 @@ def benchmark(
 
     Parameters
     ----------
+    %(adata)s
+    %(net)s
+    metrics
+        Which metrics to use to evaluate classification performance.
+    groupby
+        Whether to group experiments by a metadata column in ``anndata.AnnData.obs``.
+    runby
+        Whether to evaluate performances at the experiment (``"expr"``) or at the source (``"source"``) level.
+    sfilt
+        Whether to fitler out sources in net for which there are not perturbation data.
+    thr
+        Threshold of significance.
+        Methods that generate no p-value will be consider significant if the ``thr`` > :math:`1 - quantile`
+    emin
+        Minimum number of experiments per group.
+    %(verbose)s
+    kws_decouple
+        Keyword arguments to pass to ``decoupler.mt.decouple``.
 
     Returns
     -------

{decoupler-2.0.0 → decoupler-2.0.2}/src/decoupler/bm/metric/_auc.py

@@ -63,16 +63,13 @@ def auprc(
     # Compute prc
     ps = tps + fps
     msk = ps != 0
-    if pi0 > 0 and pi0 < 1:
-        # Siblini W., Fréry J., He-Guelton L., Oblé F., Wang YQ. (2020) Master
-        # Your Metrics with Calibration. In: Berthold M., Feelders A., Krempl G.
-        # (eds) Advances in Intelligent Data Analysis XVIII. IDA 2020. Lecture
-        # Notes in Computer Science, vol 12080. Springer, Cham
-        pi = np.sum(y_true) / y_true.size
-        ratio = pi * (1 - pi0) / (pi0 * (1 - pi))
-        prc = tps[msk] / (tps[msk] + ratio * fps[msk])
-    else:
-        prc = np.divide(tps[msk], ps[msk])
+    # Siblini W., Fréry J., He-Guelton L., Oblé F., Wang YQ. (2020) Master
+    # Your Metrics with Calibration. In: Berthold M., Feelders A., Krempl G.
+    # (eds) Advances in Intelligent Data Analysis XVIII. IDA 2020. Lecture
+    # Notes in Computer Science, vol 12080. Springer, Cham
+    pi = np.sum(y_true) / y_true.size
+    ratio = pi * (1 - pi0) / (pi0 * (1 - pi))
+    prc = tps[msk] / (tps[msk] + ratio * fps[msk])
     # Compute rcl
     rcl = tps / tps[-1]
     # Flip and add limits
@@ -94,6 +91,8 @@ def auc(
     """
     # Normalize to make comparable
     norm = np.nanmax(np.abs(y_score), axis=1)
+    msk = norm == 0.
+    norm[msk] = 1.
     y_score = y_score / norm.reshape(-1, 1)
     assert ((-1. <= y_score) & (y_score <= 1.)).all()
     # Flatten and remove nans

{decoupler-2.0.0 → decoupler-2.0.2}/src/decoupler/bm/metric/_hmean.py

@@ -1,6 +1,7 @@
 import pandas as pd
 import numpy as np
 
+from decoupler._docs import docs
 from decoupler.bm.pl._format import _format
 
 
@@ -17,6 +18,7 @@ def _hmean(
     return h
 
 
+@docs.dedent
 def hmean(
     df: pd.DataFrame,
     metrics: str | list = ['auc', 'fscore', 'qrank'],
@@ -38,6 +40,12 @@ def hmean(
     -------
     Dataframe containing the harmonic mean per metric.
     """
+    # Validate
+    assert isinstance(df, pd.DataFrame), 'df must be pandas.DataFrame'
+    assert isinstance(metrics, (str, list)), 'metrics must be str or list'
+    if isinstance(metrics, str):
+        metrics = [metrics]
+    # Run
     d_metrics = {
         'auc': {
             'name': 'H(auroc, auprc)',
@@ -61,7 +69,6 @@ def hmean(
         # Compute harmonic mean
         name = d_metrics[metric]['name']
         tmp[name] = _hmean(tmp[cols[0]], tmp[cols[1]], beta=beta)
-        #tmp = tmp.drop(columns=cols)
         if i == 0:
             hdf.append(tmp)
         else:

{decoupler-2.0.0 → decoupler-2.0.2}/src/decoupler/mt/_aucell.py

@@ -64,7 +64,7 @@ def _func_aucell(
     n_up: int | float | None = None,
     verbose: bool = False,
 ) -> Tuple[np.ndarray, None]:
-    """
+    r"""
     Area Under the Curve for set enrichment within single cells (AUCell) :cite:`aucell`.
 
     Given a ranked list of features per observation, AUCell calculates the AUC by measuring how early the features in

{decoupler-2.0.0 → decoupler-2.0.2}/src/decoupler/mt/_consensus.py

@@ -60,13 +60,45 @@ def _mean_zscores(
     return cons
 
 
+@docs.dedent
 def consensus(
     result: dict | AnnData,
     verbose: bool = False,
 ) -> Tuple[pd.DataFrame, pd.DataFrame] | None:
-    """
+    r"""
     Consensus score across methods.
 
+    For each method, enrichment scores are split into positive and negative subsets
+    and transformed independently into z-scores.
+    
+    1. Subset values based on sign (direction).
+    2. Mirror each subset into positive and negative values with the same magnitude.
+    3. Compute z-scores for each subset: :math:`z_i = \frac{x_i - \mu}{\sigma}`.
+    4. Restore the original signs to the z-scored values
+
+    This transformation ensures comparability across methods while preserving the
+    biological interpretation of activation (positive) and inhibition (negative).
+    The final consensus enrichment score :math:`ES` is computed as the mean of
+    these signed z-scores across methods.
+
+    .. math::
+
+        ES = \frac{\sum_{m=1}^{M} z_{i}^{(m)}}{M} 
+
+    Where:
+
+    - :math:`M` is the number of methods
+    - :math:`z_{i}^{(m)}` is the z-score from method :math:`m`.
+
+    A two-sided :math:`p_{value}` is then calculated from the consensus score using
+    the survival function :math:`sf` of the standard normal distribution.
+
+    .. math::
+
+        p = 2 \times \mathrm{sf}\bigl(\lvert \mathrm{ES} \rvert \bigr)
+
+    %(yestest)s
+
     Parameters
     ----------
     result

{decoupler-2.0.0 → decoupler-2.0.2}/src/decoupler/mt/_gsea.py

@@ -198,7 +198,7 @@ def _func_gsea(
 
         ES = L_{arg max |L|}
 
-    When multiple random permutations are done, statistical significance is assessed via empirical testing.
+    When multiple random permutations are done (``times > 1``), statistical significance is assessed via empirical testing.
 
     .. math::
 
@@ -220,7 +220,7 @@ def _func_gsea(
     - :math:`\mu{+}` is the mean of positive values in :math:`ES_{rand}`
     - :math:`\mu{-}` is the mean of negative values in :math:`ES_{rand}`
 
-    Finally, the obtained math:`p_value` are adjusted by Benjamini-Hochberg correction. 
+    %(yestest)s
 
     %(params)s
     %(times)s

{decoupler-2.0.0 → decoupler-2.0.2}/src/decoupler/mt/_mdt.py

@@ -1,9 +1,12 @@
+import warnings
 from typing import Tuple
 
 import numpy as np
 import scipy.sparse as sps
 from tqdm.auto import tqdm
-from xgboost import XGBRegressor
+with warnings.catch_warnings():
+    warnings.filterwarnings("ignore", category=FutureWarning, module="xgboost")
+    from xgboost import XGBRegressor
 
 from decoupler._docs import docs
 from decoupler._log import _log

{decoupler-2.0.0 → decoupler-2.0.2}/src/decoupler/mt/_ora.py

@@ -176,7 +176,7 @@ def _func_ora(
     .. figure:: /_static/images/ora.png
        :alt: Over Representation Analysis (ORA) schematic.
        :align: center
-       :width: 75%
+       :width: 100%
 
        Over Representation Analysis (ORA) scheme.
     

{decoupler-2.0.0 → decoupler-2.0.2}/src/decoupler/mt/_udt.py

@@ -1,9 +1,12 @@
+import warnings
 from typing import Tuple
 
 import numpy as np
 import scipy.sparse as sps
 from tqdm.auto import tqdm
-from xgboost import XGBRegressor
+with warnings.catch_warnings():
+    warnings.filterwarnings("ignore", category=FutureWarning, module="xgboost")
+    from xgboost import XGBRegressor
 
 from decoupler._docs import docs
 from decoupler._log import _log