decoupler 2.3.0__tar.gz → 2.3.1__tar.gz

{decoupler-2.3.0 → decoupler-2.3.1}/.editorconfig

@@ -8,7 +8,7 @@ charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
 
-[{*.{yml,yaml,toml},.cruft.json}]
+[{*.yml,*.yaml,*.toml,.cruft.json}]
 indent_size = 2
 
 [Makefile]

decoupler-2.3.1/.github/workflows/notebooks.yaml

@@ -0,0 +1,62 @@
+name: Test notebooks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        # to fail on error in multiline statements (-e), in pipes (-o pipefail), and on unset variables (-u).
+        shell: bash -euo pipefail {0}
+
+    env:
+      NOTEBOOK_PATH: docs/notebooks
+
+    strategy:
+      fail-fast: false
+      matrix:
+        notebook:
+          [
+            "example.ipynb",
+            "bench/rna.ipynb",
+            "bulk/rna.ipynb",
+            "omnipath/licenses.ipynb",
+            "omnipath/orthologs.ipynb",
+            "scell/rna_psbk.ipynb",
+            "scell/rna_pstime.ipynb",
+            "scell/rna_sc.ipynb",
+            "spatial/rna_visium.ipynb",
+          ]
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          filter: blob:none
+          fetch-depth: 0
+          submodules: "true"
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.13"
+      - name: Install uv
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+      - name: Install dependencies
+        run: |
+          uv pip install --system .
+          uv pip install --system --group dev --group test
+          uv pip install --system nbconvert ipykernel
+      - name: Run ${{ matrix.notebook }} Notebook
+        run: jupyter nbconvert --to notebook --execute ${{ env.NOTEBOOK_PATH }}/${{ matrix.notebook }}

{decoupler-2.3.0 → decoupler-2.3.1}/.github/workflows/test.yaml

@@ -54,8 +54,8 @@ jobs:
   test:
     needs: get-environments
     permissions:
-       id-token: write  # for codecov OIDC
-       contents: read
+      id-token: write # for codecov OIDC
+      contents: read
 
     strategy:
       fail-fast: false
@@ -65,7 +65,7 @@ jobs:
 
     name: ${{ matrix.env.label }}
     runs-on: ${{ matrix.os }}
-    continue-on-error: ${{ contains(matrix.env.name, 'pre') }}  # make "all-green" pass even if pre-release job fails
+    continue-on-error: ${{ contains(matrix.env.name, 'pre') }} # make "all-green" pass even if pre-release job fails
 
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -109,7 +109,7 @@ jobs:
       - test
     runs-on: ubuntu-latest
     steps:
-        - uses: re-actors/alls-green@b5b5b37504aa4183270bd3d855c52a67f212be35 # v1.3.0
-          with:
-            allowed-failures: ${{ needs.get-environments.outputs.allowed-failures }}
-            jobs: ${{ toJSON(needs) }}
+      - uses: re-actors/alls-green@b5b5b37504aa4183270bd3d855c52a67f212be35 # v1.3.0
+        with:
+          allowed-failures: ${{ needs.get-environments.outputs.allowed-failures }}
+          jobs: ${{ toJSON(needs) }}

{decoupler-2.3.0 → decoupler-2.3.1}/.pre-commit-config.yaml

@@ -7,7 +7,7 @@ default_stages:
 minimum_pre_commit_version: 2.16.0
 repos:
   - repo: https://github.com/biomejs/pre-commit
-    rev: v2.5.15
+    rev: v2.6.3
     hooks:
       - id: biome-format
         exclude: ^\.cruft\.json$ # inconsistent indentation with cruft - file never to be modified manually.
@@ -16,7 +16,7 @@ repos:
     hooks:
       - id: pyproject-fmt
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.17.1
+    rev: v0.17.2
     hooks:
       - id: ruff-check
         types_or: [python, pyi, jupyter]
@@ -38,7 +38,7 @@ repos:
         args: [--assume-in-merge]
 
   - repo: https://github.com/zizmorcore/zizmor-pre-commit
-    rev: v1.24.1
+    rev: v1.31.1
     hooks:
       - id: zizmor
         args: [--no-progress, --fix]

{decoupler-2.3.0 → decoupler-2.3.1}/CHANGELOG.md

@@ -8,9 +8,18 @@ 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
 
+## 2.3.1
+
+### Bugfixes
+
+- Fixed `mt.zscore` swapping the `KSEA` and `RoKAI` flavors, restoring the behaviour of `decoupler<2`. Scores from the default `RoKAI` flavor change (#382)
+- Fixed `mt.gsea` giving p-values of 0 when no permutation reached the observed score. The observed score is now counted as one of the permutations, as in `mt.waggr` (#383)
+- Fixed `mt.waggr` aborting the Python process with numba's `workqueue` threading layer (default when TBB/OpenMP are unavailable, e.g. macOS arm64) due to nested parallel regions
+
 ## 2.3.0
 
 ### Changes
+
 - Updated the bundled decoupler Agent Skill, and `decoupler-install-skills` now supports multiple agent frameworks
 - `pp.filter_by_prop` now defaults to `min_prop=0.1` (was `0.2`) to match the value used in the vignettes
 - `ds.msvisium` now returns log-normalized data (`sc.pp.normalize_total` + `sc.pp.log1p`), with the log-normalized matrix also stored in `adata.layers["norm"]`, instead of raw counts
@@ -18,6 +27,7 @@ and this project adheres to [Semantic Versioning][].
 - Updated to the scverse cookiecutter template v0.8.0 (hash-pinned GitHub Actions checked by zizmor, `prek` instead of `pre-commit`, `sphinx-design` instead of `sphinx-tabs`, shared Sphinx extensions from `scverse-misc`)
 
 ### Bugfixes
+
 - Fixed `mt.ora` selecting the bottom `nvar - n_up` features instead of the top `n_up` ones. Ranks are ascending, so the threshold is now `nvar - n_up`, restoring the behaviour of `decoupler<2`. With the default `n_up` (top 5%) this selected 95% of the features as observed, which also made `mt.ora` fail with `invalid contingency table` whenever `nvar - n_up` exceeded `n_bg` (#346)
 - Fixed `n_bm` in `mt.ora` selecting the bottom `n_bm - 1` features instead of `n_bm`
 - `mt.ora` now validates that `n_up` and `n_bm` do not overlap and that `n_bg` is large enough for the number of selected features, instead of failing inside the Fisher exact test
@@ -30,12 +40,14 @@ and this project adheres to [Semantic Versioning][].
 ## 2.2.0
 
 ### Added
+
 - Bundled a Claude Code [Agent Skill](https://docs.claude.com/en/docs/claude-code/skills) that teaches coding agents to use decoupler correctly (method selection, calling conventions, output locations, priors, datasets, and benchmarking)
 - Added the `decoupler-install-skills` console script to install the skill into `~/.claude/skills/decoupler/` (use `--force` to refresh after upgrading, or `--print-path` to point `CLAUDE_SKILLS_PATH` at the bundled copy in place)
 
 ## 2.1.6
 
 ### Bugfixes
+
 - Fixed `op.translate` (and every `op.resource` call for non-human organisms) failing with HTTP 404 after HGNC dropped the `genenames/` subtree from the EBI FTP mirror; the HCOP fifteen-column files are now fetched from the new HGNC Google Cloud Storage bucket (#303)
 - Removed a redundant `pd.read_csv` call in `op.translate` that re-downloaded the HCOP file a second time and bypassed the retry logic in `_download`
 - Fixed `bm.benchmark` ground-truth matrix row order not matching score matrix after `pivot`, which silently misaligned perturbation labels when obs names sort differently from their original order (#302)
@@ -43,29 +55,35 @@ and this project adheres to [Semantic Versioning][].
 ## 2.1.5
 
 ### Added
+
 - `pl.volcano` now accepts a gene name (`str`) or list of gene names (`list[str]`) for the `top` parameter to annotate specific features on volcano plots
 
 ### Changes
+
 - Refactored `ds.ensmbl_to_symbol` to reuse `_download` and fixed mirror fallback to actually switch between Ensembl mirrors
 - Made `tqdm` progress bar compact in `_download`
 
 ### Bugfixes
+
 - Fixed `pl.dotplot` ignoring `vcenter=0` due to falsy check (#293)
 - Fixed `_log` setting the root logging level to INFO for all packages (#296)
 
 ## 2.1.4
 
 ### Changes
+
 - Added `alternative` argument to `decoupler.mt.query_set`. By default `'greater'`, before it was `'two-sided'`
 - Unpinned `scipy` version limit
 
 ### Bugfixes
+
 - Fixed missing progressbar for `decoupler._download._download`
 - Added missing `decoupler.mt.query_set` documentation
 
 ## 2.1.3
 
 ### Changes
+
 - `pp.adjmat` now returns the same features as used as input instead of the subset of `net`
 - `pp.pseudobulk` now returns the same order features as used as input instead of shuffling them
 - Added a dedicated header and 5 attemps to `_download` to mitigate 429 Client Error from Zenodo downloads
@@ -73,6 +91,7 @@ and this project adheres to [Semantic Versioning][].
 ## 2.1.2
 
 ### Added
+
 - `pp.query_set` to test overlap between a given feature set against a database of sets
 
 ### Changes
@@ -84,10 +103,12 @@ and this project adheres to [Semantic Versioning][].
 ## 2.1.1
 
 ### Added
+
 - mypy checks in CI
 - notebook checks in CI
 
 ### Bugfixes
+
 - Fixed error in `decoupler.pp.pseudobulk` when `adata.obs_names` were not unique, now throws verbose error
 - Fixed corner case in `decoupler.mt.gsea` when p-values were infitite and could not be corrected
 
@@ -100,41 +121,49 @@ and this project adheres to [Semantic Versioning][].
 - Enrichment methods and pseudobulking now work with backed AnnData objects, useful when working with big datasets and memory is limited
 
 ### Bugfixes
+
 - Fixed error in `pl.obsm` where default value of `cmap_obs` was not properly set.
 
 ## 2.0.7
 
 ### Changes
+
 - Added `pre-commit` functionality to the repository
 
 ## 2.0.6
 
 ### Changes
+
 - Modified links and paths to follow scverse's repository
 
 ## 2.0.5
 
 ### Bugfixes
+
 - Fixed error message when extra dependencies where not installed
 
 ## 2.0.4
 
 ### Bugfixes
+
 - Fixed `dcor` import bug as an external dependency
 
 ## 2.0.3
 
 ### Bugfixes
+
 - Fixed error in `pp.pseudobulk` when obs columns were not categorical
 
 ## 2.0.2
 
 ### Changes
+
 - Allowed ordering functions (`pp.bin_order`, `pl.order` and `pl.order_targets`) not to be bound between 0 and 1
 - Added ipywidgets as dependency
 - Silenced xgboost warnings
 
 ### Bugfixes
+
 - Handled corner case in `bm.metric.auc` when scores are all 0
 - Fixed error in `bm.metric.hmean` when metrics were str instead of list
 - Fixed error when `obs` column is a list in `pp.pseudobulk`
@@ -142,6 +171,7 @@ and this project adheres to [Semantic Versioning][].
 ## 2.0.1
 
 ### Bugfixes
+
 - Fixed an error in `pp.pseudobulk` when handling empty samples or features
 
 ## 2.0.0
@@ -168,7 +198,7 @@ All functions have been rewritten to follow the new API, errors when running pre
   - 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
+  - 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
@@ -188,7 +218,7 @@ All functions have been rewritten to follow the new API, errors when running pre
 ### Added
 
 - `ds` module with functions to download several datasets at different resolutions
-    - Bulk: `hsctgfb` and `knocktf`
+  - Bulk: `hsctgfb` and `knocktf`
     - Single-cell: `pbmc3k`, `covid5k` and `erygast1k`
     - Spatial: `msvisium`
     - Toy data: `toy` and `toy_bench`

{decoupler-2.3.0 → decoupler-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: decoupler
-Version: 2.3.0
+Version: 2.3.1
 Summary: Python package to perform enrichment analysis from omics data.
 Project-URL: Documentation, https://decoupler.scverse.org/
 Project-URL: Homepage, https://github.com/scverse/decoupler
@@ -56,6 +56,7 @@ Requires-Dist: tqdm
 Description-Content-Type: text/markdown
 
 # decoupler - Ensemble of methods to infer enrichment scores
+
 <img src="https://raw.githubusercontent.com/scverse/decoupler/refs/heads/main/docs/_static/images/logo.svg" align="right" width="120" class="no-scaled-link" />
 
 [![Tests][badge-tests]][tests]
@@ -86,7 +87,7 @@ Description-Content-Type: text/markdown
 `decoupler` is a python package containing different enrichment statistical methods to extract biologically driven scores from omics data within a unified framework.
 This is its faster and memory efficient Python implementation, a deprecated version in R can be found [here](https://github.com/saezlab/decoupler).
 
-[//]: # (numfocus-fiscal-sponsor-attribution)
+[//]: # "numfocus-fiscal-sponsor-attribution"
 
 decoupler is part of the scverse® project ([website](https://scverse.org), [governance](https://scverse.org/about/roles)) and is fiscally sponsored by [NumFOCUS](https://numfocus.org/).
 If you like scverse® and want to support our mission, please consider making a tax-deductible [donation](https://numfocus.org/donate-to-scverse) to help the project pay for developer time, professional services, travel, workshops, and a variety of other needs.
@@ -156,6 +157,7 @@ For questions and help requests, you can reach out in the [scverse discourse][].
 If you found a bug, please use the [issue tracker][].
 
 ## License
+
 Enrichment methods inside decoupler can be used for academic or commercial purposes, except `viper` which holds a non-commercial license.
 
 The data redistributed by OmniPath does not have a single license, each original resource has its own. By default, `decoupler`
@@ -165,10 +167,10 @@ assumes an academic license, but commercial or nonprofit licenses can be specifi
 ## Citation
 
 > Badia-i-Mompel P., Vélez Santiago J., Braunger J., Geiss C., Dimitrov D.,
-Müller-Dott S., Taus P., Dugourd A., Holland C.H., Ramirez Flores R.O.
-and Saez-Rodriguez J. 2022. decoupleR: Ensemble of computational methods
-to infer biological activities from omics data. Bioinformatics Advances.
-<https://doi.org/10.1093/bioadv/vbac016>
+> Müller-Dott S., Taus P., Dugourd A., Holland C.H., Ramirez Flores R.O.
+> and Saez-Rodriguez J. 2022. decoupleR: Ensemble of computational methods
+> to infer biological activities from omics data. Bioinformatics Advances.
+> <https://doi.org/10.1093/bioadv/vbac016>
 
 [uv]: https://github.com/astral-sh/uv
 [scverse discourse]: https://discourse.scverse.org/

{decoupler-2.3.0 → decoupler-2.3.1}/README.md

@@ -1,4 +1,5 @@
 # decoupler - Ensemble of methods to infer enrichment scores
+
 <img src="https://raw.githubusercontent.com/scverse/decoupler/refs/heads/main/docs/_static/images/logo.svg" align="right" width="120" class="no-scaled-link" />
 
 [![Tests][badge-tests]][tests]
@@ -29,7 +30,7 @@
 `decoupler` is a python package containing different enrichment statistical methods to extract biologically driven scores from omics data within a unified framework.
 This is its faster and memory efficient Python implementation, a deprecated version in R can be found [here](https://github.com/saezlab/decoupler).
 
-[//]: # (numfocus-fiscal-sponsor-attribution)
+[//]: # "numfocus-fiscal-sponsor-attribution"
 
 decoupler is part of the scverse® project ([website](https://scverse.org), [governance](https://scverse.org/about/roles)) and is fiscally sponsored by [NumFOCUS](https://numfocus.org/).
 If you like scverse® and want to support our mission, please consider making a tax-deductible [donation](https://numfocus.org/donate-to-scverse) to help the project pay for developer time, professional services, travel, workshops, and a variety of other needs.
@@ -99,6 +100,7 @@ For questions and help requests, you can reach out in the [scverse discourse][].
 If you found a bug, please use the [issue tracker][].
 
 ## License
+
 Enrichment methods inside decoupler can be used for academic or commercial purposes, except `viper` which holds a non-commercial license.
 
 The data redistributed by OmniPath does not have a single license, each original resource has its own. By default, `decoupler`
@@ -108,10 +110,10 @@ assumes an academic license, but commercial or nonprofit licenses can be specifi
 ## Citation
 
 > Badia-i-Mompel P., Vélez Santiago J., Braunger J., Geiss C., Dimitrov D.,
-Müller-Dott S., Taus P., Dugourd A., Holland C.H., Ramirez Flores R.O.
-and Saez-Rodriguez J. 2022. decoupleR: Ensemble of computational methods
-to infer biological activities from omics data. Bioinformatics Advances.
-<https://doi.org/10.1093/bioadv/vbac016>
+> Müller-Dott S., Taus P., Dugourd A., Holland C.H., Ramirez Flores R.O.
+> and Saez-Rodriguez J. 2022. decoupleR: Ensemble of computational methods
+> to infer biological activities from omics data. Bioinformatics Advances.
+> <https://doi.org/10.1093/bioadv/vbac016>
 
 [uv]: https://github.com/astral-sh/uv
 [scverse discourse]: https://discourse.scverse.org/

{decoupler-2.3.0 → decoupler-2.3.1}/docs/api/ds.md

@@ -1,6 +1,7 @@
 # Datasets
 
 ## Bulk
+
 ```{eval-rst}
 .. module:: decoupler.ds
 .. currentmodule:: decoupler
@@ -13,6 +14,7 @@
 ```
 
 ## Single-cell
+
 ```{eval-rst}
 .. autosummary::
     :toctree: generated
@@ -23,6 +25,7 @@
 ```
 
 ## Spatial
+
 ```{eval-rst}
 .. autosummary::
     :toctree: generated
@@ -31,6 +34,7 @@
 ```
 
 ## Toy
+
 ```{eval-rst}
 .. autosummary::
     :toctree: generated
@@ -40,6 +44,7 @@
 ```
 
 ## Utils
+
 ```{eval-rst}
 .. autosummary::
     :toctree: generated

{decoupler-2.3.0 → decoupler-2.3.1}/docs/api/pp.md

@@ -1,6 +1,7 @@
 # Preprocessing
 
 ## Data
+
 ```{eval-rst}
 .. module:: decoupler.pp
 .. currentmodule:: decoupler
@@ -12,6 +13,7 @@
 ```
 
 ## Network
+
 ```{eval-rst}
 .. autosummary::
     :toctree: generated
@@ -25,6 +27,7 @@
 ```
 
 ## AnnData
+
 ```{eval-rst}
 .. autosummary::
     :toctree: generated

{decoupler-2.3.0 → decoupler-2.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ requires = [ "hatchling" ]
 
 [project]
 name = "decoupler"
-version = "2.3.0"
+version = "2.3.1"
 description = "Python package to perform enrichment analysis from omics data."
 readme = "README.md"
 license = { file = "LICENSE" }

{decoupler-2.3.0 → decoupler-2.3.1}/src/decoupler/_skills/data/SKILL.md

@@ -1,4 +1,5 @@
 ---
+
 name: decoupler
 description: Read before any task that mentions decoupler, one of its bundled example datasets, or asks which transcription factors (TFs), pathways, or gene sets are most active, enriched, up or down in expression data - bulk RNA-seq treated vs control, single-cell cell types or clusters, condition contrasts across donors (pseudobulk), spatial transcriptomics regions or niches, and pseudotime or differentiation trajectories - with the exact 2.x workflow (dc.op networks, dc.pp preprocessing, dc.mt scoring, dc.tl ranking) that reproduces the documented results. Also covers decoupler's networks (CollecTRI, PROGENy, DoRothEA, MSigDB), supported organisms/species and ortholog translation, resource licenses, and the conventions for plotting or visualizing its results. Also read for conceptual, best-practice or multiple-choice questions about how an agent should work with decoupler.
 ---
@@ -48,15 +49,15 @@ columns `source`, `target`, and optionally `weight`. The 2.x API is `dc.pp` (pre
 
 ## Pick the recipe from the goal
 
-| Goal | Recipe |
-|---|---|
-| Activity per cell, cluster or cell type, then "which sources mark group X" | **Per-observation** below |
-| Activity per spatial spot, region vs rest | **Spatial** below (smooth first) |
-| Sources that change along a trajectory or pseudotime | **Trajectory** below |
-| Condition A vs B in bulk RNA-seq (samples) | **Contrast** in `references/contrast.md` |
-| Condition A vs B in single-cell with several donors or samples | **Pseudobulk contrast** in `references/contrast.md` |
-| Networks, organisms, orthologs, licenses, what resources exist | `references/resources.md` |
-| Plotting results | Use `dc.pl.*` or scanpy plotting on the `get_obsm` AnnData, see `references/resources.md` |
+| Goal                                                                       | Recipe                                                                                    |
+| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Activity per cell, cluster or cell type, then "which sources mark group X" | **Per-observation** below                                                                 |
+| Activity per spatial spot, region vs rest                                  | **Spatial** below (smooth first)                                                          |
+| Sources that change along a trajectory or pseudotime                       | **Trajectory** below                                                                      |
+| Condition A vs B in bulk RNA-seq (samples)                                 | **Contrast** in `references/contrast.md`                                                  |
+| Condition A vs B in single-cell with several donors or samples             | **Pseudobulk contrast** in `references/contrast.md`                                       |
+| Networks, organisms, orthologs, licenses, what resources exist             | `references/resources.md`                                                                 |
+| Plotting results                                                           | Use `dc.pl.*` or scanpy plotting on the `get_obsm` AnnData, see `references/resources.md` |
 
 "Most active TFs in condition X vs Y" with replicate samples or donors means the contrast recipe
 (differential expression statistic → `ulm`), **not** per-cell scores averaged by condition and

{decoupler-2.3.0 → decoupler-2.3.1}/src/decoupler/_skills/data/references/resources.md

@@ -5,14 +5,14 @@
 All return a long DataFrame with `source`, `target`, and `weight` (plus extra metadata columns
 that `dc.mt.*` ignores). Verify by running; downloads come from OmniPath and need network access.
 
-| Function | What | Notes |
-|---|---|---|
-| `dc.op.collectri(organism="human", remove_complexes=False)` | TF → target regulons (CollecTRI), signed weights | Default TF network in all 2.x vignettes |
-| `dc.op.dorothea(organism="human", levels=None)` | Older TF regulons with confidence levels A–E | Only when the user asks for DoRothEA |
-| `dc.op.progeny(organism="human", top=inf, thr_padj=0.05)` | 14 signalling pathways, weighted footprint genes | `top` defaults to all significant targets; do not add `top=500` |
-| `dc.op.hallmark(organism="human")` | MSigDB hallmark gene sets, unweighted | |
-| `dc.op.resource(name, organism="human")` | Any OmniPath annotation resource (e.g. `"PanglaoDB"`, `"SIGNOR"`, `"MSigDB"`) | You must rename columns to `source` and `target` yourself |
-| `dc.op.show_resources()` | DataFrame `name, license` of every resource | |
+| Function                                                    | What                                                                          | Notes                                                           |
+| ----------------------------------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `dc.op.collectri(organism="human", remove_complexes=False)` | TF → target regulons (CollecTRI), signed weights                              | Default TF network in all 2.x vignettes                         |
+| `dc.op.dorothea(organism="human", levels=None)`             | Older TF regulons with confidence levels A–E                                  | Only when the user asks for DoRothEA                            |
+| `dc.op.progeny(organism="human", top=inf, thr_padj=0.05)`   | 14 signalling pathways, weighted footprint genes                              | `top` defaults to all significant targets; do not add `top=500` |
+| `dc.op.hallmark(organism="human")`                          | MSigDB hallmark gene sets, unweighted                                         |                                                                 |
+| `dc.op.resource(name, organism="human")`                    | Any OmniPath annotation resource (e.g. `"PanglaoDB"`, `"SIGNOR"`, `"MSigDB"`) | You must rename columns to `source` and `target` yourself       |
+| `dc.op.show_resources()`                                    | DataFrame `name, license` of every resource                                   |                                                                 |
 
 Custom gene sets: `dc.pp.read_gmt(path)` → `source, target` DataFrame. Any DataFrame with
 those columns works as `net`.

{decoupler-2.3.0 → decoupler-2.3.1}/src/decoupler/mt/_gsea.py

@@ -102,11 +102,11 @@ def _nesrank(
     pos_null_sum = pos_null_msk.sum()
     neg_null_sum = neg_null_msk.sum()
     if (es >= 0) and (pos_null_sum > 0):
-        pval = (null[pos_null_msk] >= es).sum() / pos_null_sum
+        pval = ((null[pos_null_msk] >= es).sum() + 1) / (pos_null_sum + 1)
         pos_null_mean = null[pos_null_msk].mean()
         nes = es / pos_null_mean
     elif (es < 0) and (neg_null_sum > 0):
-        pval = (null[neg_null_msk] <= es).sum() / neg_null_sum
+        pval = ((null[neg_null_msk] <= es).sum() + 1) / (neg_null_sum + 1)
         neg_null_mean = null[neg_null_msk].mean()
         nes = -es / neg_null_mean
     else:
@@ -199,12 +199,14 @@ def _func_gsea(
 
     .. math::
 
-        p_{value}=\frac{ES_{rand} \geq ES}{P}
+        p_{value} = \begin{cases} \frac{1 + \#\{ES_{rand} \geq ES\}}{1 + P_{+}} & \text{if } ES \geq 0 \\ \frac{1 + \#\{ES_{rand} \leq ES\}}{1 + P_{-}} & \text{if } ES < 0 \end{cases}
 
     Where:
 
-    - :math:`ES_{rand}` are the enrichment scores of the random permutations
-    - :math:`P` is the total number of permutations
+    - :math:`ES_{rand}` are the enrichment scores of the random permutations with the same sign as :math:`ES`
+    - :math:`P_{+}` and :math:`P_{-}` are the numbers of random permutations with positive and negative scores
+
+    The observed score is counted as one of the permutations, so that :math:`p_{value}` is never 0 :cite:`phipson2010`.
 
     Additionaly, :math:`ES` is updated to a normalized enrichment score :math:`NES`.
 

{decoupler-2.3.0 → decoupler-2.3.1}/src/decoupler/mt/_waggr.py

@@ -33,7 +33,7 @@ def _fun(
     verbose: bool = False,
 ):
     @nb.njit(parallel=True, cache=True)
-    def _f(mat, adj):
+    def _fp(mat, adj):
         nobs, nvar = mat.shape
         nvar, nsrc = adj.shape
         es = np.zeros((nobs, nsrc))
@@ -44,10 +44,22 @@ def _fun(
                 es[i, j] = f(x, w)
         return es
 
-    _f.__name__ = f.__name__
-    if _f.__name__ not in _cfuncs:
-        _cfuncs[f.__name__] = _f
-        m = f"waggr - using {_f.__name__} for the first time, will need to be compiled"
+    # Serial version to be called inside parallel regions (e.g. _perm), nested parallelism crashes workqueue
+    @nb.njit(cache=True)
+    def _fs(mat, adj):
+        nobs, nvar = mat.shape
+        nvar, nsrc = adj.shape
+        es = np.zeros((nobs, nsrc))
+        for i in range(nobs):
+            x = mat[i]
+            for j in range(nsrc):
+                w = adj[:, j]
+                es[i, j] = f(x, w)
+        return es
+
+    if f.__name__ not in _cfuncs:
+        _cfuncs[f.__name__] = (_fp, _fs)
+        m = f"waggr - using {f.__name__} for the first time, will need to be compiled"
         _log(m, level="info", verbose=verbose)
 
 
@@ -223,7 +235,7 @@ def _func_waggr(
     else:
         f_fun = fun
     _validate_func(f_fun, verbose=verbose)
-    vfun = _cfuncs[f_fun.__name__]
+    pfun, sfun = _cfuncs[f_fun.__name__]
     assert isinstance(times, int | float) and times >= 0, "times must be numeric and >= 0"
     assert isinstance(seed, int | float) and seed >= 0, "seed must be numeric and >= 0"
     times, seed = int(times), int(seed)
@@ -231,12 +243,12 @@ def _func_waggr(
     nvar, nsrc = adj.shape
     m = f"waggr - calculating scores for {nsrc} sources across {nobs} observations"
     _log(m, level="info", verbose=verbose)
-    es = vfun(mat, adj)
+    es = pfun(mat, adj)
     if times > 1:
         m = f"waggr - comparing estimates against {times} random permutations"
         _log(m, level="info", verbose=verbose)
         idx = _ridx(times=times, nvar=nvar, seed=seed)
-        es, pv = _perm(fun=vfun, es=es, mat=mat, adj=adj, idx=idx)
+        es, pv = _perm(fun=sfun, es=es, mat=mat, adj=adj, idx=idx)
     else:
         pv = np.ones(es.shape)
     return es, pv

{decoupler-2.3.0 → decoupler-2.3.1}/src/decoupler/mt/_zscore.py

@@ -72,9 +72,9 @@ def _func_zscore(
     m = f"zscore - calculating {nsrc} scores with flavor={flavor}"
     _log(m, level="info", verbose=verbose)
     stds = np.std(mat, axis=1, ddof=1)
-    if flavor == "RoKAI":
+    if flavor == "KSEA":
         mean_all = np.mean(mat, axis=1)
-    elif flavor == "KSEA":
+    elif flavor == "RoKAI":
         mean_all = np.zeros(stds.shape)
     n = np.sqrt(np.count_nonzero(adj, axis=0))
     mean = mat.dot(adj) / np.sum(np.abs(adj), axis=0)

{decoupler-2.3.0 → decoupler-2.3.1}/tests/mt/test_gsea.py

@@ -59,6 +59,34 @@ def test_nesrank(
     nes, pval = dc.mt._gsea._nesrank.py_func(ridx=ridx, row=row, rnks=rnks, set_msk=set_msk, dec=dec, es=es)
     assert isinstance(nes, float)
     assert isinstance(pval, float)
+    # Two of the six permuted scores (0.9, 0, 0, 0, 0, 0.9) reach the observed score
+    assert np.isclose(pval, (2 + 1) / (6 + 1))
+
+
+def test_gsea_pvalues_not_zero():
+    rng = np.random.default_rng(0)
+    nvar, times = 500, 100
+    row = rng.normal(size=nvar)
+    row[:20] += 5.0
+    cnct = np.arange(20)
+    starts, offsets = np.array([0]), np.array([20])
+    ridx = dc.mt._gsea._ridx(times=times, nvar=nvar, seed=42)
+    es, nes, pv = dc.mt._gsea._stsgsea.py_func(row=row, cnct=cnct, starts=starts, offsets=offsets, ridx=ridx)
+    assert es[0] > 0
+    # No permutation reaches the observed score, so the p-value is the smallest one the permutations support
+    order = np.argsort(-row)
+    set_msk = np.zeros(nvar, dtype=bool)
+    set_msk[cnct] = True
+    set_msk = set_msk[order]
+    dec = 1 / (nvar - 20)
+    null = np.array(
+        [
+            dc.mt._gsea._esrank.py_func(row=row[order], rnks=np.arange(nvar), set_msk=set_msk[i], dec=dec)[0]
+            for i in ridx
+        ]
+    )
+    assert (null < es[0]).all()
+    assert np.isclose(pv[0], 1 / ((null >= 0).sum() + 1))
 
 
 def test_stsgsea(