pertpy 0.9.3__tar.gz → 0.9.5__tar.gz

{pertpy-0.9.3 → pertpy-0.9.5}/.github/release-drafter.yml

@@ -1,5 +1,5 @@
-name-template: "0.9.3 🌈"
-tag-template: 0.9.3
+name-template: "0.9.5 🌈"
+tag-template: 0.9.5
 exclude-labels:
     - "skip-changelog"
 

{pertpy-0.9.3 → pertpy-0.9.5}/.github/workflows/release.yml

@@ -13,10 +13,10 @@ jobs:
             - name: Checkout code
               uses: actions/checkout@v4
 
-            - name: Set up Python 3.11
+            - name: Set up Python 3.12
               uses: actions/setup-python@v5
               with:
-                  python-version: "3.11"
+                  python-version: "3.12"
 
             - name: Install hatch
               run: pip install hatch

{pertpy-0.9.3 → pertpy-0.9.5}/.github/workflows/test.yml

@@ -27,13 +27,13 @@ jobs:
                     - os: ubuntu-latest
                       python: "3.12"
                       run_mode: "slow"
-                    - os: ubuntu-latest
-                      python: "3.12"
-                      run_mode: "fast"
-                    - os: ubuntu-latest
-                      python: "3.12"
-                      run_mode: slow
-                      pip-flags: "--pre"
+                    # - os: ubuntu-latest
+                    #   python: "3.12"
+                    #   run_mode: "fast"
+                    # - os: ubuntu-latest
+                    #   python: "3.12"
+                    #   run_mode: slow
+                    #   pip-flags: "--pre"
 
         env:
             OS: ${{ matrix.os }}

{pertpy-0.9.3 → pertpy-0.9.5}/.gitignore

@@ -137,6 +137,9 @@ dmypy.json
 # Jetbrains IDE
 .idea/
 
+# VSCode
+.vscode
+
 # Coala
 *.orig
 
@@ -155,3 +158,11 @@ lightning_logs/*
 */lightning_logs/*
 
 node_modules
+
+# lamindb
+test.ipynb
+test-perturbation
+test-bug
+
+# uv
+uv.lock

{pertpy-0.9.3 → pertpy-0.9.5}/.pre-commit-config.yaml

@@ -32,7 +32,7 @@ repos:
           - id: mypy
             args: [--no-strict-optional, --ignore-missing-imports]
             additional_dependencies:
-                ["types-pkg-resources", "types-requests", "types-attrs"]
+                ["types-setuptools", "types-requests", "types-attrs"]
     - repo: local
       hooks:
           - id: forbid-to-commit

pertpy-0.9.5/.readthedocs.yml

@@ -0,0 +1,18 @@
+version: 2
+build:
+    os: ubuntu-24.04
+    tools:
+        python: "3.12"
+    commands:
+        - asdf plugin add uv
+        - asdf install uv latest
+        - asdf global uv latest
+        - uv venv
+        - uv pip install .[doc,coda,de]
+        - .venv/bin/python -m sphinx -T -b html -d docs/_build/doctrees -D language=en docs $READTHEDOCS_OUTPUT/html
+sphinx:
+    configuration: docs/conf.py
+    fail_on_warning: false
+
+submodules:
+    include: all

{pertpy-0.9.3 → pertpy-0.9.5}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: pertpy
-Version: 0.9.3
+Version: 0.9.5
 Summary: Perturbation Analysis in the scverse ecosystem.
 Project-URL: Documentation, https://pertpy.readthedocs.io
 Project-URL: Source, https://github.com/scverse/pertpy
@@ -44,7 +44,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Classifier: Topic :: Scientific/Engineering :: Visualization
-Requires-Python: >=3.10
+Requires-Python: <3.13,>=3.10
 Requires-Dist: adjusttext
 Requires-Dist: blitzgsea
 Requires-Dist: decoupler
@@ -68,7 +68,8 @@ Requires-Dist: pyqt5; extra == 'coda'
 Requires-Dist: toytree; extra == 'coda'
 Provides-Extra: de
 Requires-Dist: formulaic; extra == 'de'
-Requires-Dist: pydeseq2; extra == 'de'
+Requires-Dist: formulaic-contrasts>=0.2.0; extra == 'de'
+Requires-Dist: pydeseq2>=v0.5.0pre1; extra == 'de'
 Provides-Extra: dev
 Requires-Dist: pre-commit; extra == 'dev'
 Provides-Extra: doc

{pertpy-0.9.3 → pertpy-0.9.5}/docs/conf.py

@@ -195,4 +195,7 @@ nbsphinx_thumbnails = {
     "tutorials/notebooks/differential_gene_expression": "_static/tutorials/dge.png",
     "tutorials/notebooks/metadata_annotation": "_static/tutorials/metadata.png",
     "tutorials/notebooks/ontology_mapping": "_static/tutorials/ontology.png",
+    "tutorials/notebooks/norman_use_case": "_static/tutorials/norman.png",
+    "tutorials/notebooks/mcfarland_use_case": "_static/tutorials/mcfarland.png",
+    "tutorials/notebooks/zhang_use_case": "_static/tutorials/zhang.png",
 }

{pertpy-0.9.3 → pertpy-0.9.5}/docs/installation.md

@@ -78,10 +78,10 @@ Follow these steps to install pertpy on an Apple Silicon machine (tested on a Ma
     brew install --cask mambaforge
     ```
 
-3. Create a new environment using mamba (here with python 3.10) and activate it
+3. Create a new environment using mamba and activate it
 
     ```console
-    mamba create -n pertpy-env python=3.11
+    mamba create -n pertpy-env
     mamba activate pertpy-env
     ```
 

{pertpy-0.9.3 → pertpy-0.9.5}/docs/tutorials/index.md

@@ -11,13 +11,25 @@ Many are also designed to work seamlessly in Google colab.
 For questions about the usage of pertpy use the [scverse discourse](https://discourse.scverse.org/).
 :::
 
-## Quick start
+## Quick start: Tool specific tutorials
+
+### Data transformation
 
 ```{eval-rst}
 .. nbgallery::
 
    notebooks/guide_rna_assignment
    notebooks/mixscape
+   notebooks/perturbation_space
+   notebooks/metadata_annotation
+   notebooks/ontology_mapping
+```
+
+### Knowledge inference
+
+```{eval-rst}
+.. nbgallery::
+
    notebooks/augur
    notebooks/sccoda
    notebooks/sccoda_extended
@@ -29,13 +41,24 @@ For questions about the usage of pertpy use the [scverse discourse](https://disc
    notebooks/distance_tests
    notebooks/cinemaot
    notebooks/scgen_perturbation_prediction
-   notebooks/perturbation_space
    notebooks/differential_gene_expression
-   notebooks/metadata_annotation
-   notebooks/ontology_mapping
 ```
 
-### Glossary
+## Use cases
+
+Our use cases showcase a variety of pertpy tools applied to one dataset.
+They are designed to give you a sense of how to use pertpy in a real-world scenario.
+The use cases featured here are those we present in the pertpy [preprint](https://www.biorxiv.org/content/10.1101/2024.08.04.606516v1).
+
+```{eval-rst}
+.. nbgallery::
+
+   notebooks/norman_use_case
+   notebooks/mcfarland_use_case
+   notebooks/zhang_use_case
+```
+
+## Glossary
 
 ```{eval-rst}
 .. tab-set::

{pertpy-0.9.3 → pertpy-0.9.5}/docs/usage/usage.md

@@ -450,7 +450,7 @@ See [scGen predicts single-cell perturbation responses](https://www.nature.com/a
 .. autosummary::
     :toctree: tools
 
-    tools.SCGEN
+    tools.Scgen
 ```
 
 Example implementation:

{pertpy-0.9.3 → pertpy-0.9.5}/pertpy/__init__.py

@@ -2,7 +2,7 @@
 
 __author__ = "Lukas Heumos"
 __email__ = "lukas.heumos@posteo.net"
-__version__ = "0.9.3"
+__version__ = "0.9.5"
 
 import warnings
 

pertpy-0.9.5/pertpy/_doc.py

@@ -0,0 +1,20 @@
+from textwrap import dedent
+
+
+def _doc_params(**kwds):  # pragma: no cover
+    """\
+    Docstrings should start with "\" in the first line for proper formatting.
+    """
+
+    def dec(obj):
+        obj.__orig_doc__ = obj.__doc__
+        obj.__doc__ = dedent(obj.__doc__.format_map(kwds))
+        return obj
+
+    return dec
+
+
+doc_common_plot_args = """\
+show: if `True`, shows the plot.
+            return_fig: if `True`, returns figure of the plot.\
+"""

{pertpy-0.9.3 → pertpy-0.9.5}/pertpy/data/_dataloader.py

@@ -23,10 +23,10 @@ def _download(  # pragma: no cover
     Args:
         url: URL to download
         output_file_name: Name of the downloaded file
-        output_path: Path to download/extract the files to (default: OS tmpdir)
-        block_size: Block size for downloads in bytes (default: 1024)
-        overwrite: Whether to overwrite existing files (default: False)
-        is_zip: Whether the downloaded file needs to be unzipped (default: False)
+        output_path: Path to download/extract the files to.
+        block_size: Block size for downloads in bytes.
+        overwrite: Whether to overwrite existing files.
+        is_zip: Whether the downloaded file needs to be unzipped.
     """
     if output_file_name is None:
         letters = ascii_lowercase

{pertpy-0.9.3 → pertpy-0.9.5}/pertpy/data/_datasets.py

@@ -66,7 +66,7 @@ def sc_sim_augur() -> AnnData:  # pragma: no cover
     output_file_path = settings.datasetdir / output_file_name
     if not Path(output_file_path).exists():
         _download(
-            url="https://figshare.com/ndownloader/files/31645886",
+            url="https://figshare.com/ndownloader/files/49828902",
             output_file_name=output_file_name,
             output_path=settings.datasetdir,
             is_zip=False,
@@ -1100,7 +1100,7 @@ def shifrut_2018() -> AnnData:  # pragma: no cover
     output_file_path = settings.datasetdir / output_file_name
     if not Path(output_file_path).exists():
         _download(
-            url="https://zenodo.org/record/10044268/files/ShifrutMarson2018.h5ad?download=1",
+            url="https://zenodo.org/record/13350497/files/ShifrutMarson2018.h5ad?download=1",
             output_file_name=output_file_name,
             output_path=settings.datasetdir,
             is_zip=False,
@@ -1160,7 +1160,7 @@ def srivatsan_2020_sciplex3() -> AnnData:  # pragma: no cover
     output_file_path = settings.datasetdir / output_file_name
     if not Path(output_file_path).exists():
         _download(
-            url="https://zenodo.org/records/10044268/files/SrivatsanTrapnell2020_sciplex3.h5ad?download=1",
+            url="https://zenodo.org/records/13350497/files/SrivatsanTrapnell2020_sciplex3.h5ad?download=1",
             output_file_name=output_file_name,
             output_path=settings.datasetdir,
             is_zip=False,

{pertpy-0.9.3 → pertpy-0.9.5}/pertpy/metadata/_cell_line.py

@@ -8,12 +8,15 @@ from lamin_utils import logger
 if TYPE_CHECKING:
     from collections.abc import Iterable
 
+    from matplotlib.pyplot import Figure
+
 import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
 from scanpy import settings
 from scipy import stats
 
+from pertpy._doc import _doc_params, doc_common_plot_args
 from pertpy.data._dataloader import _download
 
 from ._look_up import LookUp
@@ -338,8 +341,8 @@ class CellLine(MetaData):
         # then we can compare these keys and fetch the corresponding metadata.
         if query_id not in adata.obs.columns:
             raise ValueError(
-                f"The specified `query_id` {query_id} can't be found in the `adata.obs`.\n"
-                "Ensure that you are using one of the available query IDs present in the adata.obs for the annotation.\n"
+                f"The specified `query_id` {query_id} can't be found in the `adata.obs`. \n"
+                "Ensure that you are using one of the available query IDs present in the adata.obs for the annotation."
                 "If the desired query ID is not available, you can fetch the cell line metadata "
                 "using the `annotate()` function before calling 'annotate_bulk_rna()'. "
                 "This ensures that the required query ID is included in your data, e.g. stripped_cell_line_name, DepMap ID."
@@ -356,9 +359,8 @@ class CellLine(MetaData):
         else:
             reference_id = "DepMap_ID"
             logger.warning(
-                "To annotate bulk RNA data from Broad Institue, `DepMap_ID` is used as default reference and query identifier if no `reference_id` is given.\n"
-                "Ensure that `DepMap_ID` is available in 'adata.obs'.\n"
-                "Alternatively, use `annotate()` to annotate the cell line first "
+                "To annotate bulk RNA data from Broad Institue, `DepMap_ID` is used as default reference and query identifier if no `reference_id` is given."
+                "If `DepMap_ID` isn't available in 'adata.obs', use `annotate()` to annotate the cell line first."
             )
             if self.bulk_rna_broad is None:
                 self._download_bulk_rna(cell_line_source="broad")
@@ -690,6 +692,7 @@ class CellLine(MetaData):
 
         return corr, pvals, new_corr, new_pvals
 
+    @_doc_params(common_plot_args=doc_common_plot_args)
     def plot_correlation(
         self,
         adata: AnnData,
@@ -700,7 +703,9 @@ class CellLine(MetaData):
         metadata_key: str = "bulk_rna_broad",
         category: str = "cell line",
         subset_identifier: str | int | Iterable[str] | Iterable[int] | None = None,
-    ) -> None:
+        show: bool = True,
+        return_fig: bool = False,
+    ) -> Figure | None:
         """Visualise the correlation of cell lines with annotated metadata.
 
         Args:
@@ -713,6 +718,8 @@ class CellLine(MetaData):
             subset_identifier: Selected identifiers for scatter plot visualization between the X matrix and `metadata_key`.
                               If not None, only the chosen cell line will be plotted, either specified as a value in `identifier` (string) or as an index number.
                               If None, all cell lines will be plotted.
+            {common_plot_args}
+
         Returns:
             Pearson correlation coefficients and their corresponding p-values for matched and unmatched cell lines separately.
         """
@@ -790,6 +797,11 @@ class CellLine(MetaData):
                     "edgecolor": "black",
                 },
             )
-            plt.show()
+
+            if show:
+                plt.show()
+            if return_fig:
+                return plt.gcf()
+            return None
         else:
             raise NotImplementedError

{pertpy-0.9.3 → pertpy-0.9.5}/pertpy/metadata/_compound.py

@@ -42,7 +42,7 @@ class Compound(MetaData):
             adata = adata.copy()
 
         if query_id not in adata.obs.columns:
-            raise ValueError(f"The requested query_id {query_id} is not in `adata.obs`.\n" f"Please check again. ")
+            raise ValueError(f"The requested query_id {query_id} is not in `adata.obs`.\n Please check again.")
 
         query_dict = {}
         not_matched_identifiers = []
@@ -84,7 +84,7 @@ class Compound(MetaData):
         query_df = pd.DataFrame.from_dict(query_dict, orient="index", columns=["pubchem_name", "pubchem_ID", "smiles"])
         # Merge and remove duplicate columns
         # Column is converted to float after merging due to unmatches
-        # Convert back to integers
+        # Convert back to integers afterwards
         if query_id_type == "cid":
             query_df.pubchem_ID = query_df.pubchem_ID.astype("Int64")
             adata.obs = (
@@ -119,8 +119,7 @@ class Compound(MetaData):
 
         The LookUp object provides an overview of the metadata to annotate.
         Each annotate_{metadata} function has a corresponding lookup function in the LookUp object,
-        where users can search the reference_id in the metadata and
-        compare with the query_id in their own data.
+        where users can search the reference_id in the metadata and compare with the query_id in their own data.
 
         Returns:
             Returns a LookUp object specific for compound annotation.

{pertpy-0.9.3 → pertpy-0.9.5}/pertpy/metadata/_metadata.py

@@ -62,7 +62,7 @@ class MetaData:
             if verbosity > 0:
                 logger.info(
                     f"There are {total_identifiers} identifiers in `adata.obs`."
-                    f"However, {len(unmatched_identifiers)} identifiers can't be found in the {metadata_type} annotation,"
+                    f"However, {len(unmatched_identifiers)} identifiers can't be found in the {metadata_type} annotation, "
                     "leading to the presence of NA values for their respective metadata.\n"
                     f"Please check again: *unmatched_identifiers[:verbosity]..."
                 )

{pertpy-0.9.3 → pertpy-0.9.5}/pertpy/preprocessing/_guide_rna.py

@@ -3,14 +3,17 @@ from __future__ import annotations
 import uuid
 from typing import TYPE_CHECKING
 
+import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
 import scanpy as sc
 import scipy
 
+from pertpy._doc import _doc_params, doc_common_plot_args
+
 if TYPE_CHECKING:
     from anndata import AnnData
-    from matplotlib.axes import Axes
+    from matplotlib.pyplot import Figure
 
 
 class GuideAssignment:
@@ -106,14 +109,18 @@ class GuideAssignment:
 
         return None
 
+    @_doc_params(common_plot_args=doc_common_plot_args)
     def plot_heatmap(
         self,
         adata: AnnData,
+        *,
         layer: str | None = None,
         order_by: np.ndarray | str | None = None,
         key_to_save_order: str = None,
+        show: bool = True,
+        return_fig: bool = False,
         **kwargs,
-    ) -> list[Axes]:
+    ) -> Figure | None:
         """Heatmap plotting of guide RNA expression matrix.
 
         Assuming guides have sparse expression, this function reorders cells
@@ -131,11 +138,12 @@ class GuideAssignment:
                       If a string is provided, adata.obs[order_by] will be used as the order.
                       If a numpy array is provided, the array will be used for ordering.
             key_to_save_order: The obs key to save cell orders in the current plot. Only saves if not None.
+            {common_plot_args}
             kwargs: Are passed to sc.pl.heatmap.
 
         Returns:
-            List of Axes. Alternatively you can pass save or show parameters as they will be passed to sc.pl.heatmap.
-            Order of cells in the y-axis will be saved on adata.obs[key_to_save_order] if provided.
+            If `return_fig` is `True`, returns the figure, otherwise `None`.
+            Order of cells in the y-axis will be saved on `adata.obs[key_to_save_order]` if provided.
 
         Examples:
             Each cell is assigned to gRNA that occurs at least 5 times in the respective cell, which is then
@@ -172,7 +180,7 @@ class GuideAssignment:
             adata.obs[key_to_save_order] = pd.Categorical(order)
 
         try:
-            axis_group = sc.pl.heatmap(
+            fig = sc.pl.heatmap(
                 adata[order, :],
                 var_names=adata.var.index.tolist(),
                 groupby=temp_col_name,
@@ -180,9 +188,14 @@ class GuideAssignment:
                 use_raw=False,
                 dendrogram=False,
                 layer=layer,
+                show=False,
                 **kwargs,
             )
         finally:
             del adata.obs[temp_col_name]
 
-        return axis_group
+        if show:
+            plt.show()
+        if return_fig:
+            return fig
+        return None

{pertpy-0.9.3 → pertpy-0.9.5}/pertpy/tools/__init__.py

@@ -1,25 +1,22 @@
-from functools import wraps
 from importlib import import_module
 
 
 def lazy_import(module_path, class_name, extras):
-    def _import():
-        try:
-            for extra in extras:
-                import_module(extra)
-        except ImportError as e:
-            raise ImportError(
-                f"Extra dependencies required: {', '.join(extras)}. "
-                f"Please install with: pip install {' '.join(extras)}"
-            ) from e
+    try:
+        for extra in extras:
+            import_module(extra)
         module = import_module(module_path)
         return getattr(module, class_name)
+    except ImportError:
 
-    @wraps(_import)
-    def wrapper(*args, **kwargs):
-        return _import()(*args, **kwargs)
+        class Placeholder:
+            def __init__(self, *args, **kwargs):
+                raise ImportError(
+                    f"Extra dependencies required: {', '.join(extras)}. "
+                    f"Please install with: pip install {' '.join(extras)}"
+                )
 
-    return wrapper
+        return Placeholder
 
 
 from pertpy.tools._augur import Augur
@@ -49,7 +46,7 @@ Sccoda = lazy_import("pertpy.tools._coda._sccoda", "Sccoda", CODA_EXTRAS)
 Tasccoda = lazy_import("pertpy.tools._coda._tasccoda", "Tasccoda", CODA_EXTRAS)
 
 DE_EXTRAS = ["formulaic", "pydeseq2"]
-EdgeR = lazy_import("pertpy.tools._differential_gene_expression", "EdgeR", DE_EXTRAS + ["edger"])
+EdgeR = lazy_import("pertpy.tools._differential_gene_expression", "EdgeR", DE_EXTRAS)  # edgeR will be imported via rpy2
 PyDESeq2 = lazy_import("pertpy.tools._differential_gene_expression", "PyDESeq2", DE_EXTRAS)
 Statsmodels = lazy_import("pertpy.tools._differential_gene_expression", "Statsmodels", DE_EXTRAS + ["statsmodels"])
 TTest = lazy_import("pertpy.tools._differential_gene_expression", "TTest", DE_EXTRAS)