pertpy 0.9.3__py3-none-any.whl → 0.9.5__py3-none-any.whl

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/_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/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/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/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/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/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/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/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)

pertpy/tools/_augur.py

@@ -15,7 +15,6 @@ import statsmodels.api as sm
 from anndata import AnnData
 from joblib import Parallel, delayed
 from lamin_utils import logger
-from rich import print
 from rich.progress import track
 from scipy import sparse, stats
 from sklearn.base import is_classifier, is_regressor
@@ -26,17 +25,19 @@ from sklearn.metrics import (
     explained_variance_score,
     f1_score,
     make_scorer,
-    mean_squared_error,
     precision_score,
     r2_score,
     recall_score,
     roc_auc_score,
+    root_mean_squared_error,
 )
 from sklearn.model_selection import StratifiedKFold, cross_validate
 from sklearn.preprocessing import LabelEncoder
 from skmisc.loess import loess
 from statsmodels.stats.multitest import fdrcorrection
 
+from pertpy._doc import _doc_params, doc_common_plot_args
+
 if TYPE_CHECKING:
     from matplotlib.axes import Axes
     from matplotlib.figure import Figure
@@ -439,7 +440,7 @@ class Augur:
                 "augur_score": make_scorer(self.ccc_score),
                 "r2": make_scorer(r2_score),
                 "ccc": make_scorer(self.ccc_score),
-                "neg_mean_squared_error": make_scorer(mean_squared_error),
+                "neg_mean_squared_error": make_scorer(root_mean_squared_error),
                 "explained_variance": make_scorer(explained_variance_score),
             }
         )
@@ -974,24 +975,26 @@ class Augur:
 
         return delta
 
+    @_doc_params(common_plot_args=doc_common_plot_args)
     def plot_dp_scatter(
         self,
         results: pd.DataFrame,
+        *,
         top_n: int = None,
-        return_fig: bool | None = None,
         ax: Axes = None,
-        show: bool | None = None,
-        save: str | bool | None = None,
-    ) -> Axes | Figure | None:
+        show: bool = True,
+        return_fig: bool = False,
+    ) -> Figure | None:
         """Plot scatterplot of differential prioritization.
 
         Args:
             results: Results after running differential prioritization.
             top_n: optionally, the number of top prioritized cell types to label in the plot
             ax: optionally, axes used to draw plot
+            {common_plot_args}
 
         Returns:
-            Axes of the plot.
+            If `return_fig` is `True`, returns the figure, otherwise `None`.
 
         Examples:
             >>> import pertpy as pt
@@ -1038,37 +1041,34 @@ class Augur:
         legend1 = ax.legend(*scatter.legend_elements(), loc="center left", title="z-scores", bbox_to_anchor=(1, 0.5))
         ax.add_artist(legend1)
 
-        if save:
-            plt.savefig(save, bbox_inches="tight")
         if show:
             plt.show()
         if return_fig:
             return plt.gcf()
-        if not (show or save):
-            return ax
         return None
 
+    @_doc_params(common_plot_args=doc_common_plot_args)
     def plot_important_features(
         self,
         data: dict[str, Any],
+        *,
         key: str = "augurpy_results",
         top_n: int = 10,
-        return_fig: bool | None = None,
         ax: Axes = None,
-        show: bool | None = None,
-        save: str | bool | None = None,
-    ) -> Axes | None:
+        show: bool = True,
+        return_fig: bool = False,
+    ) -> Figure | None:
         """Plot a lollipop plot of the n features with largest feature importances.
 
         Args:
-            results: results after running `predict()` as dictionary or the AnnData object.
+            data: results after running `predict()` as dictionary or the AnnData object.
             key: Key in the AnnData object of the results
             top_n: n number feature importance values to plot. Default is 10.
             ax: optionally, axes used to draw plot
-            return_figure: if `True` returns figure of the plot, default is `False`
+            {common_plot_args}
 
         Returns:
-            Axes of the plot.
+            If `return_fig` is `True`, returns the figure, otherwise `None`.
 
         Examples:
             >>> import pertpy as pt
@@ -1109,35 +1109,32 @@ class Augur:
         plt.ylabel("Gene")
         plt.yticks(y_axes_range, n_features["genes"])
 
-        if save:
-            plt.savefig(save, bbox_inches="tight")
         if show:
             plt.show()
         if return_fig:
             return plt.gcf()
-        if not (show or save):
-            return ax
         return None
 
+    @_doc_params(common_plot_args=doc_common_plot_args)
     def plot_lollipop(
         self,
-        data: dict[str, Any],
+        data: dict[str, Any] | AnnData,
+        *,
         key: str = "augurpy_results",
-        return_fig: bool | None = None,
         ax: Axes = None,
-        show: bool | None = None,
-        save: str | bool | None = None,
-    ) -> Axes | Figure | None:
+        show: bool = True,
+        return_fig: bool = False,
+    ) -> Figure | None:
         """Plot a lollipop plot of the mean augur values.
 
         Args:
-            results: results after running `predict()` as dictionary or the AnnData object.
-            key: Key in the AnnData object of the results
-            ax: optionally, axes used to draw plot
-            return_figure: if `True` returns figure of the plot
+            data: results after running `predict()` as dictionary or the AnnData object.
+            key: .uns key in the results AnnData object.
+            ax: optionally, axes used to draw plot.
+            {common_plot_args}
 
         Returns:
-            Axes of the plot.
+            If `return_fig` is `True`, returns the figure, otherwise `None`.
 
         Examples:
             >>> import pertpy as pt
@@ -1175,32 +1172,29 @@ class Augur:
         plt.ylabel("Cell Type")
         plt.yticks(y_axes_range, results["summary_metrics"].sort_values("mean_augur_score", axis=1).columns)
 
-        if save:
-            plt.savefig(save, bbox_inches="tight")
         if show:
             plt.show()
         if return_fig:
             return plt.gcf()
-        if not (show or save):
-            return ax
         return None
 
+    @_doc_params(common_plot_args=doc_common_plot_args)
     def plot_scatterplot(
         self,
         results1: dict[str, Any],
         results2: dict[str, Any],
+        *,
         top_n: int = None,
-        return_fig: bool | None = None,
-        show: bool | None = None,
-        save: str | bool | None = None,
-    ) -> Axes | Figure | None:
+        show: bool = True,
+        return_fig: bool = False,
+    ) -> Figure | None:
         """Create scatterplot with two augur results.
 
         Args:
             results1: results after running `predict()`
             results2: results after running `predict()`
             top_n: optionally, the number of top prioritized cell types to label in the plot
-            return_figure: if `True` returns figure of the plot
+            {common_plot_args}
 
         Returns:
             Axes of the plot.
@@ -1249,12 +1243,8 @@ class Augur:
         plt.xlabel("Augur scores 1")
         plt.ylabel("Augur scores 2")
 
-        if save:
-            plt.savefig(save, bbox_inches="tight")
         if show:
             plt.show()
         if return_fig:
             return plt.gcf()
-        if not (show or save):
-            return ax
         return None

pertpy/tools/_cinemaot.py

@@ -18,9 +18,12 @@ from sklearn.decomposition import FastICA
 from sklearn.linear_model import LinearRegression
 from sklearn.neighbors import NearestNeighbors
 
+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
     from statsmodels.tools.typing import ArrayLike
 
 
@@ -88,7 +91,7 @@ class Cinemaot:
             dim = self.get_dim(adata, use_rep=use_rep)
 
         transformer = FastICA(n_components=dim, random_state=0, whiten="arbitrary-variance")
-        X_transformed = transformer.fit_transform(adata.obsm[use_rep][:, :dim])
+        X_transformed = np.array(transformer.fit_transform(adata.obsm[use_rep][:, :dim]), dtype=np.float64)
         groupvec = (adata.obs[pert_key] == control * 1).values  # control
         xi = np.zeros(dim)
         j = 0
@@ -97,9 +100,9 @@ class Cinemaot:
             xi[j] = xi_obj.correlation
             j = j + 1
 
-        cf = X_transformed[:, xi < thres]
-        cf1 = cf[adata.obs[pert_key] == control, :]
-        cf2 = cf[adata.obs[pert_key] != control, :]
+        cf = np.array(X_transformed[:, xi < thres], np.float64)
+        cf1 = np.array(cf[adata.obs[pert_key] == control, :], np.float64)
+        cf2 = np.array(cf[adata.obs[pert_key] != control, :], np.float64)
         if sum(xi < thres) == 1:
             sklearn.metrics.pairwise_distances(cf1.reshape(-1, 1), cf2.reshape(-1, 1))
         elif sum(xi < thres) == 0:
@@ -167,7 +170,7 @@ class Cinemaot:
         else:
             _solver = sinkhorn.Sinkhorn(threshold=eps)
             ot_sink = _solver(ot_prob)
-            ot_matrix = ot_sink.matrix.T
+            ot_matrix = np.array(ot_sink.matrix.T, dtype=np.float64)
             embedding = X_transformed[adata.obs[pert_key] != control, :] - np.matmul(
                 ot_matrix / np.sum(ot_matrix, axis=1)[:, None], X_transformed[adata.obs[pert_key] == control, :]
             )
@@ -190,7 +193,7 @@ class Cinemaot:
         TE.obsm["X_embedding"] = embedding
 
         if return_matching:
-            TE.obsm["ot"] = ot_sink.matrix.T
+            TE.obsm["ot"] = np.asarray(ot_sink.matrix.T)
             return TE
         else:
             return TE
@@ -639,6 +642,7 @@ class Cinemaot:
         s_effect = (np.linalg.norm(e1, axis=0) + 1e-6) / (np.linalg.norm(e0, axis=0) + 1e-6)
         return c_effect, s_effect
 
+    @_doc_params(common_plot_args=doc_common_plot_args)
     def plot_vis_matching(
         self,
         adata: AnnData,
@@ -647,16 +651,17 @@ class Cinemaot:
         control: str,
         de_label: str,
         source_label: str,
+        *,
         matching_rep: str = "ot",
         resolution: float = 0.5,
         normalize: str = "col",
         title: str = "CINEMA-OT matching matrix",
         min_val: float = 0.01,
-        show: bool = True,
-        save: str | None = None,
         ax: Axes | None = None,
+        show: bool = True,
+        return_fig: bool = False,
         **kwargs,
-    ) -> None:
+    ) -> Figure | None:
         """Visualize the CINEMA-OT matching matrix.
 
         Args:
@@ -670,11 +675,12 @@ class Cinemaot:
             normalize: normalize the coarse-grained matching matrix by row / column.
             title: the title for the figure.
             min_val: The min value to truncate the matching matrix.
-            show: Show the plot, do not return axis.
-            save: If `True` or a `str`, save the figure. A string is appended to the default filename.
-                Infer the filetype if ending on {`'.pdf'`, `'.png'`, `'.svg'`}.
+            {common_plot_args}
             **kwargs: Other parameters to input for seaborn.heatmap.
 
+        Returns:
+            If `return_fig` is `True`, returns the figure, otherwise `None`.
+
         Examples:
             >>> import pertpy as pt
             >>> adata = pt.dt.cinemaot_example()
@@ -710,12 +716,12 @@ class Cinemaot:
 
         g = sns.heatmap(df, annot=True, ax=ax, **kwargs)
         plt.title(title)
-        _utils.savefig_or_show("matching_heatmap", show=show, save=save)
-        if not show:
-            if ax is not None:
-                return ax
-            else:
-                return g
+
+        if show:
+            plt.show()
+        if return_fig:
+            return g
+        return None
 
 
 class Xi: