Skip to content

preprocessing

Preprocessing utilities for AnnData objects.

AnnDataStandardScaler

Standardize numerical columns of adata.obs using sklearn's StandardScaler.

Categorical and object-typed columns are detected automatically and left unchanged. The API mirrors the familiar sklearn fit / transform pattern.

Parameters:

Name Type Description Default
**scaler_kwargs

Keyword arguments forwarded to :class:sklearn.preprocessing.StandardScaler (e.g. with_mean, with_std).

{}

Attributes:

Name Type Description
numeric_cols_ list[str]

Names of adata.obs columns that were identified as numerical and will be (or have been) scaled.

categorical_cols_ list[str]

Names of adata.obs columns that are categorical / non-numeric and are left unchanged.

scaler_ StandardScaler

The fitted scaler instance.

Examples:

>>> scaler = AnnDataStandardScaler()
>>> adata_scaled = scaler.fit_transform(adata)          # returns a copy
>>> scaler.fit_transform(adata, inplace=True)            # modifies in place
Source code in scdesigner/src/scdesigner/data/preprocessing.py
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
class AnnDataStandardScaler:
    """Standardize numerical columns of ``adata.obs`` using sklearn's StandardScaler.

    Categorical and object-typed columns are detected automatically and left
    unchanged.  The API mirrors the familiar sklearn fit / transform pattern.

    Parameters
    ----------
    **scaler_kwargs
        Keyword arguments forwarded to :class:`sklearn.preprocessing.StandardScaler`
        (e.g. ``with_mean``, ``with_std``).

    Attributes
    ----------
    numeric_cols_ : list[str]
        Names of ``adata.obs`` columns that were identified as numerical and
        will be (or have been) scaled.
    categorical_cols_ : list[str]
        Names of ``adata.obs`` columns that are categorical / non-numeric and
        are left unchanged.
    scaler_ : sklearn.preprocessing.StandardScaler
        The fitted scaler instance.

    Examples
    --------
    >>> scaler = AnnDataStandardScaler()
    >>> adata_scaled = scaler.fit_transform(adata)          # returns a copy
    >>> scaler.fit_transform(adata, inplace=True)            # modifies in place
    """

    def __init__(self, **scaler_kwargs):
        self._scaler_kwargs = scaler_kwargs

    def fit(self, adata: AnnData) -> "AnnDataStandardScaler":
        """Fit the scaler on the numerical columns of ``adata.obs``.

        Parameters
        ----------
        adata : AnnData
            Annotated data matrix whose ``.obs`` DataFrame is inspected.

        Returns
        -------
        self
        """
        obs = adata.obs
        self.numeric_cols_ = [
            c for c in obs.columns if pd.api.types.is_numeric_dtype(obs[c])
        ]
        self.categorical_cols_ = [
            c for c in obs.columns if c not in self.numeric_cols_
        ]
        self.scaler_ = StandardScaler(**self._scaler_kwargs).fit(
            obs[self.numeric_cols_]
        )
        return self

    def transform(self, adata: AnnData, inplace: bool = False) -> Optional[AnnData]:
        """Scale the numerical columns of ``adata.obs``.

        Parameters
        ----------
        adata : AnnData
            Annotated data matrix to transform.
        inplace : bool, optional
            If ``True``, modify ``adata.obs`` directly and return ``None``.
            If ``False`` (default), return a copy of ``adata`` with scaled
            ``.obs``.

        Returns
        -------
        AnnData or None
            Modified copy when ``inplace=False``; ``None`` when ``inplace=True``.
        """
        if not hasattr(self, "scaler_"):
            raise RuntimeError(
                "This AnnDataStandardScaler instance is not fitted yet. "
                "Call fit() before transform()."
            )

        print(
            f"Scaled numerical variables     : "
            f"{', '.join(self.numeric_cols_) if self.numeric_cols_ else '(none)'}"
        )
        print(
            f"Unchanged categorical variables: "
            f"{', '.join(self.categorical_cols_) if self.categorical_cols_ else '(none)'}"
        )

        scaled_values = self.scaler_.transform(adata.obs[self.numeric_cols_])
        scaled_df = pd.DataFrame(
            scaled_values,
            index=adata.obs.index,
            columns=self.numeric_cols_,
        )

        if inplace:
            adata.obs[self.numeric_cols_] = scaled_df
            return None

        new_obs = adata.obs.copy()
        new_obs[self.numeric_cols_] = scaled_df
        result = adata.copy()
        result.obs = new_obs
        return result

    def fit_transform(self, adata: AnnData, inplace: bool = False) -> Optional[AnnData]:
        """Fit the scaler and transform ``adata.obs`` in one step.

        Parameters
        ----------
        adata : AnnData
            Annotated data matrix to fit and transform.
        inplace : bool, optional
            Passed through to :meth:`transform`.

        Returns
        -------
        AnnData or None
            See :meth:`transform`.
        """
        return self.fit(adata).transform(adata, inplace=inplace)

fit(adata)

Fit the scaler on the numerical columns of adata.obs.

Parameters:

Name Type Description Default
adata AnnData

Annotated data matrix whose .obs DataFrame is inspected.

required

Returns:

Type Description
self
Source code in scdesigner/src/scdesigner/data/preprocessing.py
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
def fit(self, adata: AnnData) -> "AnnDataStandardScaler":
    """Fit the scaler on the numerical columns of ``adata.obs``.

    Parameters
    ----------
    adata : AnnData
        Annotated data matrix whose ``.obs`` DataFrame is inspected.

    Returns
    -------
    self
    """
    obs = adata.obs
    self.numeric_cols_ = [
        c for c in obs.columns if pd.api.types.is_numeric_dtype(obs[c])
    ]
    self.categorical_cols_ = [
        c for c in obs.columns if c not in self.numeric_cols_
    ]
    self.scaler_ = StandardScaler(**self._scaler_kwargs).fit(
        obs[self.numeric_cols_]
    )
    return self

fit_transform(adata, inplace=False)

Fit the scaler and transform adata.obs in one step.

Parameters:

Name Type Description Default
adata AnnData

Annotated data matrix to fit and transform.

required
inplace bool

Passed through to :meth:transform.

False

Returns:

Type Description
AnnData or None

See :meth:transform.

Source code in scdesigner/src/scdesigner/data/preprocessing.py
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
def fit_transform(self, adata: AnnData, inplace: bool = False) -> Optional[AnnData]:
    """Fit the scaler and transform ``adata.obs`` in one step.

    Parameters
    ----------
    adata : AnnData
        Annotated data matrix to fit and transform.
    inplace : bool, optional
        Passed through to :meth:`transform`.

    Returns
    -------
    AnnData or None
        See :meth:`transform`.
    """
    return self.fit(adata).transform(adata, inplace=inplace)

transform(adata, inplace=False)

Scale the numerical columns of adata.obs.

Parameters:

Name Type Description Default
adata AnnData

Annotated data matrix to transform.

required
inplace bool

If True, modify adata.obs directly and return None. If False (default), return a copy of adata with scaled .obs.

False

Returns:

Type Description
AnnData or None

Modified copy when inplace=False; None when inplace=True.

Source code in scdesigner/src/scdesigner/data/preprocessing.py
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
def transform(self, adata: AnnData, inplace: bool = False) -> Optional[AnnData]:
    """Scale the numerical columns of ``adata.obs``.

    Parameters
    ----------
    adata : AnnData
        Annotated data matrix to transform.
    inplace : bool, optional
        If ``True``, modify ``adata.obs`` directly and return ``None``.
        If ``False`` (default), return a copy of ``adata`` with scaled
        ``.obs``.

    Returns
    -------
    AnnData or None
        Modified copy when ``inplace=False``; ``None`` when ``inplace=True``.
    """
    if not hasattr(self, "scaler_"):
        raise RuntimeError(
            "This AnnDataStandardScaler instance is not fitted yet. "
            "Call fit() before transform()."
        )

    print(
        f"Scaled numerical variables     : "
        f"{', '.join(self.numeric_cols_) if self.numeric_cols_ else '(none)'}"
    )
    print(
        f"Unchanged categorical variables: "
        f"{', '.join(self.categorical_cols_) if self.categorical_cols_ else '(none)'}"
    )

    scaled_values = self.scaler_.transform(adata.obs[self.numeric_cols_])
    scaled_df = pd.DataFrame(
        scaled_values,
        index=adata.obs.index,
        columns=self.numeric_cols_,
    )

    if inplace:
        adata.obs[self.numeric_cols_] = scaled_df
        return None

    new_obs = adata.obs.copy()
    new_obs[self.numeric_cols_] = scaled_df
    result = adata.copy()
    result.obs = new_obs
    return result