exprmat 0.2.79__tar.gz → 0.2.81__tar.gz

{exprmat-0.2.79 → exprmat-0.2.81}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: exprmat
-Version: 0.2.79
+Version: 0.2.81
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy

{exprmat-0.2.79 → exprmat-0.2.81}/exprmat/__init__.py

@@ -106,6 +106,9 @@ default_finders = [
     'exprmat.config',
     '.exprmat.config',
     '.exprmatrc',
+    _os.path.join(str(_os.environ.get("CONDA_PREFIX") or ''), 'exprmat.config'),
+    _os.path.join(str(_os.environ.get("CONDA_PREFIX") or ''), '.exprmat.config'),
+    _os.path.join(str(_os.environ.get("CONDA_PREFIX") or ''), '.exprmatrc'),
     _os.path.join(str(_pathlib.Path.home()), 'exprmat.config'),
     _os.path.join(str(_pathlib.Path.home()), '.exprmat.config'),
     _os.path.join(str(_pathlib.Path.home()), '.exprmatrc')

exprmat-0.2.81/exprmat/data/malig.py

@@ -0,0 +1,16 @@
+
+from pandas import read_table, isnull
+import pandas as pd
+from numpy import unique
+import numpy as np
+import os
+import itertools
+from pandas import DataFrame
+
+from exprmat.ansi import error, warning, info
+from exprmat.data.finders import basepath
+
+
+def get_malignancy_model_folder(taxa) -> DataFrame:
+    resource_path = os.path.join(basepath, taxa, 'malig')
+    return resource_path

{exprmat-0.2.79 → exprmat-0.2.81}/exprmat/data/signature.py

@@ -25,7 +25,10 @@ def convert(genes):
         return frozendict(zip(genes, repeat(1.0)))
 
 
-@attr.s()
+# `signature` must be hashable because `genes` and `weights` are memoized
+# properties (`cytoolz.memoize` caches on the instance itself). without a
+# generated `__hash__` any access to `signature.genes` raised a `TypeError`.
+@attr.s(hash = True)
 class signature():
     """
     Gene signatures, i.e. a set of genes that are biologically related.

exprmat-0.2.81/exprmat/malig/__init__.py

@@ -0,0 +1,45 @@
+"""
+malignancy inference.
+
+Malignant cells are distinguished from their normal counterparts using a
+pretrained pan-cancer classifier, ported from `scMalignantFinder`
+(https://github.com/Jonyyqn/scMalignantFinder, Yu et al., Commun Biol 2025).
+Only human cancers can be predicted.
+
+Only the inference part of the upstream package is included:
+
+* :mod:`.classifier` -- pretrained cell-level (gross) malignancy inference.
+* :mod:`.scoring` -- AUCell gene set scoring backed by the in-package
+  implementation in :mod:`exprmat.descriptive.aucell`.
+
+Model training, scATOMIC cell type annotation (R) and spatial region
+identification are not included, and no R, `scAtomic`, `pyscenic` or `ctxcore`
+dependency is required.
+
+The pretrained model (``model.joblib``) and its ordered feature list
+(``ordered_feature.tsv``) are distributed separately by the upstream authors at
+https://zenodo.org/records/17888140. Place both files in one directory and pass
+it as ``pretrain_dir``.
+
+Examples
+--------
+>>> from exprmat.malig import predict_malignancy
+>>> adata = predict_malignancy(adata, pretrain_dir = 'pretrained_model')
+>>> adata.obs[['malig', 'prob.malig']].head()
+"""
+
+from exprmat.malig.classifier import (
+    malignancy_inference,
+    predict_malignancy,
+    load_ordered_features,
+)
+
+from exprmat.malig.scoring import aucell_score
+
+
+__all__ = [
+    'malignancy_inference',
+    'predict_malignancy',
+    'load_ordered_features',
+    'aucell_score',
+]

exprmat-0.2.81/exprmat/malig/classifier.py

@@ -0,0 +1,439 @@
+"""
+cell-level (gross) malignancy inference with a pretrained model.
+
+This module ports the inference half of `scMalignantFinder`
+(https://github.com/Jonyyqn/scMalignantFinder, Yu et al., Commun Biol 2025).
+Only the pretrained malignancy classifier is implemented. model training,
+scATOMIC cell type annotation (which requires R) and spatial region
+identification are intentionally left out, so this module has no dependency on
+R, `scAtomic`, `pyscenic` or `ctxcore`.
+
+.. warning::
+   The released model was trained on human pan-cancer signatures and is only
+   suitable for **human** data. Running it on mouse data, including after any
+   ortholog conversion, is strongly discouraged: malignant versus normal
+   expression programs are very unlikely to be conserved between species.
+"""
+
+import os
+from typing import Iterable
+
+import joblib
+import numpy as np
+import pandas as pd
+import scipy.sparse as sp
+from anndata import AnnData
+
+from exprmat.ansi import error, info, warning
+
+
+MODEL_FILENAME = 'model.joblib'
+FEATURE_FILENAME = 'ordered_feature.tsv'
+
+NORMAL = 'Normal'
+MALIGNANT = 'Malignant'
+
+DEFAULT_TARGET_SUM = 1e4
+
+
+def load_ordered_features(feature_path: str) -> list[str]:
+    """
+    Load an ordered feature list, one gene symbol per line.
+
+    The pretrained model expects the expression matrix to be arranged in exactly
+    this order. Duplicated entries are kept as they are, since the model was fit
+    on this exact layout.
+
+    Parameters
+    ----------
+    feature_path
+        Path to the feature list, usually ``ordered_feature.tsv``.
+
+    Returns
+    -------
+    The ordered list of feature (gene) names.
+    """
+
+    if not os.path.isfile(feature_path):
+        error(f'feature list not found: {feature_path}')
+
+    with open(feature_path, 'r') as f:
+        features = [line.strip() for line in f if line.strip()]
+
+    if len(features) == 0:
+        error(f'feature list is empty: {feature_path}')
+
+    return features
+
+
+def _resolve_pretrain_files(
+    pretrain_dir: str | None = None,
+    model_path: str | None = None,
+    feature_path: str | None = None,
+) -> tuple[str, str]:
+
+    if pretrain_dir is not None:
+        if model_path is None:
+            model_path = os.path.join(pretrain_dir, MODEL_FILENAME)
+        if feature_path is None:
+            feature_path = os.path.join(pretrain_dir, FEATURE_FILENAME)
+
+    if model_path is None or feature_path is None:
+        error(
+            'a pretrained model is required for inference. provide `pretrain_dir` '
+            f'(a directory containing `{MODEL_FILENAME}` and `{FEATURE_FILENAME}`), '
+            'or provide both `model_path` and `feature_path`.'
+        )
+
+    return model_path, feature_path
+
+
+def _expression_matrix(
+    adata: AnnData,
+    use_raw: bool = False,
+    layer: str | None = None,
+):
+
+    if use_raw and layer is not None:
+        error('`use_raw = True` and `layer` cannot be used together.')
+
+    if use_raw:
+        if adata.raw is None:
+            error('`use_raw = True`, but `adata.raw` is not available.')
+        X = adata.raw.X
+        var_names = adata.raw.var_names
+    elif layer is not None:
+        if layer not in adata.layers:
+            error(f'layer `{layer}` not found in `adata.layers`.')
+        X = adata.layers[layer]
+        var_names = adata.var_names
+    else:
+        X = adata.X
+        var_names = adata.var_names
+
+    if X is None:
+        error('the expression matrix is empty.')
+    if X.shape[0] != adata.n_obs:
+        error('the expression matrix does not match `adata.n_obs`.')
+
+    return X, var_names
+
+
+def _feature_positions(
+    features: Iterable[str],
+    var_names: Iterable[str],
+) -> tuple[np.ndarray, np.ndarray, list[str]]:
+    """
+    Match the ordered model features against the variables of the expression
+    matrix. Returns the column positions in the output matrix, the corresponding
+    column indices in the expression matrix, and the missing feature names.
+    """
+
+    lookup: dict[str, int] = {}
+    for i, name in enumerate(var_names):
+        # keep the first occurrence, as `var_names_make_unique` does upstream.
+        lookup.setdefault(str(name), i)
+
+    cols: list[int] = []
+    idx: list[int] = []
+    missing: list[str] = []
+    for j, name in enumerate(features):
+        i = lookup.get(str(name))
+        if i is None:
+            missing.append(name)
+        else:
+            cols.append(j)
+            idx.append(i)
+
+    return (
+        np.asarray(cols, dtype = np.intp),
+        np.asarray(idx, dtype = np.intp),
+        missing,
+    )
+
+
+class malignancy_inference():
+    """
+    Pretrained cell-level (gross) malignancy inference.
+
+    The classifier is trained on pan-cancer signatures by the
+    `scMalignantFinder` authors. This class only performs inference with the
+    released pretrained model: model training is not supported.
+
+    Parameters
+    ----------
+    pretrain_dir
+        Directory containing ``model.joblib`` and ``ordered_feature.tsv``.
+    model_path
+        Explicit path to a pretrained ``model.joblib``. Overrides
+        ``pretrain_dir`` when given.
+    feature_path
+        Explicit path to the ordered feature list. Overrides ``pretrain_dir``
+        when given.
+    normalize
+        Whether to apply library size normalization (to ``target_sum``) before
+        prediction. No log transformation is applied, as in the upstream
+        package. Set to ``False`` if the data are already normalized.
+    use_raw
+        Use ``adata.raw.X`` instead of ``adata.X``.
+    target_sum
+        Target total count per cell when ``normalize = True``.
+    verbose
+        Print information about the loaded model and missing features.
+
+    Examples
+    --------
+    >>> from exprmat.malig import malignancy_inference
+    >>> model = malignancy_inference(pretrain_dir = 'pretrained_model')
+    >>> model.load()
+    >>> adata = model.predict(adata)
+    """
+
+    def __init__(
+        self,
+        pretrain_dir: str | None = None,
+        model_path: str | None = None,
+        feature_path: str | None = None,
+        normalize: bool = True,
+        use_raw: bool = False,
+        target_sum: float = DEFAULT_TARGET_SUM,
+        verbose: bool = True,
+    ):
+
+        self.pretrain_dir = pretrain_dir
+        self.model_path = model_path
+        self.feature_path = feature_path
+
+        self.normalize = normalize
+        self.use_raw = use_raw
+        self.target_sum = float(target_sum)
+        self.verbose = verbose
+
+        self.model = None
+        self.features: list[str] | None = None
+        self.missing_features: list[str] = []
+
+    def load(self) -> 'malignancy_inference':
+        """
+        Load the pretrained model and the ordered feature list.
+        """
+
+        model_path, feature_path = _resolve_pretrain_files(
+            self.pretrain_dir, self.model_path, self.feature_path,
+        )
+
+        self.model_path = model_path
+        self.feature_path = feature_path
+
+        if not os.path.isfile(model_path):
+            error(f'pretrained model not found: {model_path}')
+
+        try:
+            self.model = joblib.load(model_path)
+        except ImportError as e:
+            error(
+                'failed to load the pretrained model. the model may depend on a '
+                'package that is not installed (for example `xgboost`).',
+                error = e,
+            )
+
+        if not hasattr(self.model, 'predict_proba'):
+            error('the loaded model does not provide `predict_proba`.')
+
+        self.features = load_ordered_features(feature_path)
+
+        n_expected = getattr(self.model, 'n_features_in_', None)
+        if n_expected is not None and int(n_expected) != len(self.features):
+            warning(
+                f'the model expects {int(n_expected)} features, but the feature '
+                f'list contains {len(self.features)} entries.'
+            )
+
+        if self.verbose:
+            info(
+                'loaded pretrained malignancy model '
+                f'({type(self.model).__name__}, {len(self.features)} features).'
+            )
+
+        return self
+
+    def predict(
+        self,
+        adata: AnnData,
+        layer: str | None = None,
+        copy: bool = False,
+        key_prediction: str = 'malig',
+        key_probability: str = 'prob.malig',
+    ) -> AnnData:
+        """
+        Predict malignancy for each observation.
+
+        Parameters
+        ----------
+        adata
+            Annotated data matrix with genes as variables and cells as
+            observations.
+        layer
+            Use ``adata.layers[layer]`` as the expression matrix. Cannot be
+            combined with ``use_raw = True``.
+        copy
+            Return a copy instead of writing to ``adata`` in place.
+        key_prediction
+            ``adata.obs`` key for the predicted label, either ``Normal`` or
+            ``Malignant``. Default ``'malig'``.
+        key_probability
+            ``adata.obs`` key for the probability of being malignant.
+            Default ``'prob.malig'``.
+
+        Returns
+        -------
+        The ``AnnData`` object with predictions added to ``.obs``.
+        """
+
+        if not isinstance(adata, AnnData):
+            error(f'`adata` must be an AnnData object, got {type(adata).__name__}.')
+
+        if self.model is None or self.features is None:
+            self.load()
+
+        X, var_names = _expression_matrix(
+            adata, use_raw = self.use_raw, layer = layer,
+        )
+
+        n_features = len(self.features)
+        cols, idx, missing = _feature_positions(self.features, var_names)
+        self.missing_features = missing
+
+        if self.verbose and len(missing) > 0:
+            pct = 100.0 * len(missing) / n_features
+            warning(
+                f'{len(missing)} of {n_features} model features ({pct:.2f}%) are '
+                'absent from the data and are imputed as zero.'
+            )
+            if pct > 20:
+                warning(
+                    'more than 20% of the model features are missing. '
+                    'prediction quality may be compromised.'
+                )
+
+        # build the feature matrix in the exact order expected by the model.
+        if len(idx) > 0:
+            sub = X[:, idx]
+            if sp.issparse(sub): sub = sub.toarray()
+            sub = np.asarray(sub)
+            dtype = np.result_type(sub.dtype, np.float32)
+        else:
+            sub = None
+            dtype = np.float64
+
+        dense = np.zeros((adata.n_obs, n_features), dtype = dtype)
+        if sub is not None:
+            dense[:, cols] = sub
+        del sub
+
+        # per-cell library size normalization. because the scaling factor is
+        # constant per cell it is equivalent to normalizing the full matrix
+        # first, but much cheaper.
+        if self.normalize:
+            totals = np.asarray(X.sum(axis = 1)).ravel()
+            scale = np.zeros(totals.shape, dtype = np.float64)
+            np.divide(self.target_sum, totals, out = scale, where = totals > 0)
+            dense *= scale[:, None]
+
+        proba = np.asarray(self.model.predict_proba(dense))
+        column = self._positive_index()
+
+        probability = proba.ravel() if proba.ndim == 1 else proba[:, column]
+        labels = np.asarray(self.model.predict(dense)).ravel()
+
+        classes = list(getattr(self.model, 'classes_', [0, 1]))
+        positive = classes[column] if column < len(classes) else 1
+        malignant = labels == positive
+
+        out = adata.copy() if copy else adata
+        out.obs[key_prediction] = pd.Categorical(
+            np.where(malignant, MALIGNANT, NORMAL),
+            categories = [NORMAL, MALIGNANT],
+        )
+        out.obs[key_probability] = probability.astype(np.float64)
+
+        return out
+
+    def _positive_index(self) -> int:
+        """
+        Column of ``predict_proba`` corresponding to the malignant class (label 1).
+        """
+
+        classes = list(getattr(self.model, 'classes_', [0, 1]))
+        if 1 in classes: return classes.index(1)
+        return len(classes) - 1
+
+
+def predict_malignancy(
+    adata: AnnData,
+    pretrain_dir: str | None = None,
+    model_path: str | None = None,
+    feature_path: str | None = None,
+    normalize: bool = True,
+    use_raw: bool = False,
+    layer: str | None = None,
+    target_sum: float = DEFAULT_TARGET_SUM,
+    copy: bool = False,
+    key_prediction: str = 'malig',
+    key_probability: str = 'prob.malig',
+    verbose: bool = True,
+) -> AnnData:
+    """
+    Predict cell-level malignancy with a pretrained `scMalignantFinder` model.
+
+    This is a convenience wrapper around :class:`malignancy_inference`. Use the
+    class directly if you want to reuse the loaded model for several datasets.
+
+    Parameters
+    ----------
+    adata
+        Annotated data matrix with genes as variables and cells as observations.
+    pretrain_dir
+        Directory containing ``model.joblib`` and ``ordered_feature.tsv``.
+    model_path
+        Explicit path to a pretrained ``model.joblib``.
+    feature_path
+        Explicit path to the ordered feature list.
+    normalize
+        Apply library size normalization to ``target_sum`` before prediction.
+    use_raw
+        Use ``adata.raw.X`` instead of ``adata.X``.
+    layer
+        Use ``adata.layers[layer]`` instead of ``adata.X``.
+    target_sum
+        Target total count per cell when ``normalize = True``.
+    copy
+        Return a copy instead of writing to ``adata`` in place.
+    key_prediction
+        ``adata.obs`` key for the predicted label. Default ``'malig'``.
+    key_probability
+        ``adata.obs`` key for the malignancy probability. Default ``'prob.malig'``.
+    verbose
+        Print information about the loaded model and missing features.
+
+    Returns
+    -------
+    The ``AnnData`` object with predictions added to ``.obs``.
+    """
+
+    model = malignancy_inference(
+        pretrain_dir = pretrain_dir,
+        model_path = model_path,
+        feature_path = feature_path,
+        normalize = normalize,
+        use_raw = use_raw,
+        target_sum = target_sum,
+        verbose = verbose,
+    )
+
+    model.load()
+    return model.predict(
+        adata, layer = layer, copy = copy,
+        key_prediction = key_prediction,
+        key_probability = key_probability,
+    )

exprmat-0.2.81/exprmat/malig/scoring.py

@@ -0,0 +1,156 @@
+"""
+gene set scoring utilities for malignant signatures.
+
+The upstream `scMalignantFinder` implements its AUCell helper on top of
+`pyscenic.aucell` and `ctxcore.genesig.GeneSignature`. This module uses the
+in-package AUCell implementation (:mod:`exprmat.descriptive.aucell`) and the
+in-package signature type (:class:`exprmat.data.signature.signature`) instead,
+so neither `pyscenic` nor `ctxcore` is required.
+"""
+
+import numpy as np
+from anndata import AnnData
+
+from exprmat.ansi import error, warning
+from exprmat.data.signature import signature
+from exprmat.descriptive.aucell import aucell, derive_auc_threshold
+
+
+def aucell_score(
+    adata: AnnData,
+    gmt: str,
+    layer: str | None = None,
+    normalize_total: bool = False,
+    target_sum: float = 1e4,
+    adapt_signatures: bool = True,
+    min_overlap: float = 0.5,
+    auc_threshold: float | None = None,
+    seed: int | None = 2,
+    num_workers: int = 1,
+    key_added: str | None = None,
+    copy: bool = False,
+) -> AnnData:
+    """
+    Calculate per-observation AUCell scores for the gene sets in a gmt file.
+
+    This mirrors ``scMalignantFinder.utils.aucell_cal`` but is backed by the
+    in-package AUCell implementation. Scores are normalized to a maximum of 1.0
+    per gene set, as upstream.
+
+    .. note::
+       The expression matrix is densified internally, so this helper is intended
+       for a biologically relevant subset of cells.
+
+    Parameters
+    ----------
+    adata
+        Annotated data matrix with genes as variables and cells as observations.
+    gmt
+        Path to a gene set file in gmt format.
+    layer
+        Use ``adata.layers[layer]`` as the expression matrix. Defaults to
+        ``adata.X``.
+    normalize_total
+        Normalize total counts to ``target_sum`` per cell before scoring. The
+        input ``adata`` is not modified.
+    target_sum
+        Target total count per cell when ``normalize_total = True``.
+    adapt_signatures
+        Drop gene sets whose overlap with the variables of the data is below
+        ``min_overlap``. Without this, sets composed mostly of absent genes
+        would be scored as (near) zero.
+    min_overlap
+        Minimum fraction of genes of a set that must be present in the data.
+    auc_threshold
+        Fraction of the ranked genome to use for the AUC. Defaults to the 1%
+        quantile of detected genes, as derived by
+        :func:`exprmat.descriptive.aucell.derive_auc_threshold`.
+    seed
+        Seed used when shuffling the expression matrix before ranking.
+    num_workers
+        Number of worker processes used for the AUC computation.
+    key_added
+        If ``None`` (default), one column per gene set is added to ``adata.obs``.
+        Otherwise, scores are stored in ``adata.obsm[key_added]`` and the gene
+        set names in ``adata.uns['{key_added}.genesets']``.
+    copy
+        Return a copy instead of writing to ``adata`` in place.
+
+    Returns
+    -------
+    The ``AnnData`` object with the scores added.
+    """
+
+    if not isinstance(adata, AnnData):
+        error(f'`adata` must be an AnnData object, got {type(adata).__name__}.')
+
+    if not isinstance(gmt, str):
+        error('`gmt` must be a path to a gmt file.')
+
+    signatures = signature.from_gmt(
+        gmt, field_separator = '\t', gene_separator = '\t',
+    )
+
+    gene_names = set(map(str, adata.var_names))
+
+    if adapt_signatures:
+        kept = []
+        for s in signatures:
+            overlap = len(set(map(str, s.gene2weight)) & gene_names) / len(s)
+            if overlap >= min_overlap: kept.append(s)
+
+        if len(kept) == 0:
+            error(
+                f'none of the {len(signatures)} gene sets in `{gmt}` overlap with '
+                f'at least {min_overlap:.0%} of the variables of the data.'
+            )
+
+        if len(kept) < len(signatures):
+            warning(
+                f'{len(signatures) - len(kept)} of {len(signatures)} gene sets '
+                f'were dropped (< {min_overlap:.0%} overlap with the data).'
+            )
+
+        signatures = kept
+
+    if len(signatures) == 0:
+        error(f'no usable gene sets found in `{gmt}`.')
+
+    names = [str(s.name) for s in signatures]
+    if len(set(names)) != len(names):
+        warning('duplicated gene set names in the gmt file; scores will collide.')
+
+    # the expression matrix as a dense (cell x gene) dataframe, which is what
+    # the ranking based AUCell implementation expects.
+    df = adata.to_df(layer = layer)
+
+    if normalize_total:
+        totals = df.sum(axis = 1).to_numpy(dtype = np.float64)
+        scale = np.zeros(totals.shape, dtype = np.float64)
+        np.divide(float(target_sum), totals, out = scale, where = totals > 0)
+        df = df.mul(scale, axis = 0)
+
+    if auc_threshold is None:
+        auc_threshold = float(derive_auc_threshold(df)[0.01])
+
+    scores = aucell(
+        df, signatures,
+        auc_threshold = auc_threshold,
+        normalize = True,
+        seed = seed,
+        num_workers = num_workers,
+    )
+
+    # keep the original observation order.
+    scores = scores.reindex(adata.obs_names)
+
+    out = adata.copy() if copy else adata
+
+    if key_added is None:
+        for i, name in enumerate(scores.columns):
+            out.obs[str(name)] = scores.iloc[:, i].to_numpy()
+    else:
+        out.obsm[key_added] = scores.to_numpy()
+        out.uns[f'{key_added}.genesets'] = list(map(str, scores.columns))
+
+    return out