Skip to content

Index

Data loading and formula utilities.

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

GPBasis

Bases: SpatialBasis

Gaussian-process basis with an RBF kernel (Nystrom).

Regularizes the landmark kernel with eps * I before SVD.

Parameters:

Name Type Description Default
length_scale float

RBF length scale :math:\ell in coordinate units, in the kernel

.. math::

k(x, x') = \exp\!\left(-\frac{\lVert x - x' \rVert^2}{2\ell^2}\right).

Smaller values allow more rapidly varying functions. If None, fit sets :math:\ell = c\,e, where :math:c is length_fraction and :math:e is the extent, so the basis does not depend on coordinate units.

None
length_fraction float

Fraction :math:c of the extent, used only when length_scale is None. The extent is

.. math::

e = \max_{d} \left( \max_{i} x_{id} - \min_{i} x_{id} \right),

taken over the fitted coordinates :math:x_i.

0.17
**kwargs

Forwarded to :class:SpatialBasis.

{}

Attributes:

Name Type Description
length_scale_ float

Length scale of the fitted basis. Set by :meth:fit.

Source code in scdesigner/src/scdesigner/data/basis.py
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
class GPBasis(SpatialBasis):
    r"""Gaussian-process basis with an RBF kernel (Nystrom).

    Regularizes the landmark kernel with ``eps * I`` before SVD.

    Parameters
    ----------
    length_scale : float, optional
        RBF length scale :math:`\ell` in coordinate units, in the kernel

        .. math::

            k(x, x') = \exp\!\left(-\frac{\lVert x - x' \rVert^2}{2\ell^2}\right).

        Smaller values allow more rapidly varying functions. If ``None``,
        ``fit`` sets :math:`\ell = c\,e`, where :math:`c` is ``length_fraction``
        and :math:`e` is the extent, so the basis does not depend on coordinate
        units.
    length_fraction : float
        Fraction :math:`c` of the extent, used only when ``length_scale`` is
        ``None``. The extent is

        .. math::

            e = \max_{d} \left( \max_{i} x_{id} - \min_{i} x_{id} \right),

        taken over the fitted coordinates :math:`x_i`.
    **kwargs
        Forwarded to :class:`SpatialBasis`.

    Attributes
    ----------
    length_scale_ : float
        Length scale of the fitted basis. Set by :meth:`fit`.
    """

    def __init__(self, length_scale=None, length_fraction=0.17, **kwargs):
        super().__init__(**kwargs)
        self.length_scale = length_scale
        self.length_fraction = length_fraction
        self.length_scale_ = None

    def fit(self, coords, chunk_size=None):
        coords = np.asarray(coords)
        if self.length_scale is not None:
            self.length_scale_ = self.length_scale
        else:
            extent = float(np.ptp(coords, axis=0).max())
            self.length_scale_ = self.length_fraction * extent
        return super().fit(coords, chunk_size)

    def _kernel(self, A, B):
        return rbf_kernel(A, B, self.length_scale_)

    def _regularize(self, K_mm, landmarks):
        return K_mm + self.eps * np.eye(len(landmarks))

SpatialBasis

Bases: ABC

Low-rank 2D spatial basis with stateful fit / transform.

Subclasses define _kernel and _regularize (applied to the landmark kernel before SVD). fit picks landmarks, stores the projection U_m[:, :df] / s_m[:df], training column std (if standardize), and the penalty diagonal s_0 / s_j (capped). transform reuses that state on new coordinates. fit evaluates the kernel on at most chunk_size coordinates at a time.

Parameters:

Name Type Description Default
df int

Basis columns to retain.

15
n_landmarks int

Landmark count for the Nystrom approximation.

200
eps float

Numerical floor for kernel and column-std.

1e-06
max_penalty_ratio float

Cap on penalty_diag[j].

1000.0
standardize bool

Divide columns by training std.

False

Attributes:

Name Type Description
landmarks_, projection_, col_sd_, penalty_diag

Set by :meth:fit. Shapes (m, 2), (m, df), (df,), (df,).

Source code in scdesigner/src/scdesigner/data/basis.py
 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
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
class SpatialBasis(ABC):
    """Low-rank 2D spatial basis with stateful fit / transform.

    Subclasses define ``_kernel`` and ``_regularize`` (applied to the
    landmark kernel before SVD). ``fit`` picks landmarks, stores the
    projection ``U_m[:, :df] / s_m[:df]``, training column std (if
    ``standardize``), and the penalty diagonal ``s_0 / s_j`` (capped).
    ``transform`` reuses that state on new coordinates. ``fit`` evaluates the
    kernel on at most ``chunk_size`` coordinates at a time.

    Parameters
    ----------
    df : int
        Basis columns to retain.
    n_landmarks : int
        Landmark count for the Nystrom approximation.
    eps : float
        Numerical floor for kernel and column-std.
    max_penalty_ratio : float
        Cap on ``penalty_diag[j]``.
    standardize : bool
        Divide columns by training std.

    Attributes
    ----------
    landmarks_, projection_, col_sd_, penalty_diag
        Set by :meth:`fit`. Shapes ``(m, 2)``, ``(m, df)``, ``(df,)``, ``(df,)``.
    """

    def __init__(self, df=15, n_landmarks=200, eps=1e-6,
                 max_penalty_ratio=1e3, standardize=False):
        self.df = df
        self.n_landmarks = n_landmarks
        self.eps = eps
        self.max_penalty_ratio = max_penalty_ratio
        self.standardize = standardize

        self.landmarks_ = None
        self.projection_ = None
        self.col_sd_ = None
        self.penalty_diag = None

    @abstractmethod
    def _kernel(self, A, B):
        """Kernel matrix between rows of ``A`` and rows of ``B``."""

    @abstractmethod
    def _regularize(self, K_mm, landmarks):
        """Transform the landmark kernel before SVD."""

    def _truncate_singular(self, U_m, s_m):
        """Drop near-zero singular values before truncating to ``df``."""
        return U_m, s_m

    def fit(self, coords, chunk_size=None):
        """Fit on ``coords``; ``chunk_size=None`` evaluates all rows at once."""
        coords = np.asarray(coords)
        n = coords.shape[0]
        idx = np.random.choice(n, size=min(self.n_landmarks, n), replace=False)
        landmarks = coords[idx]

        K_mm = self._kernel(landmarks, landmarks)
        K_mm = self._regularize(K_mm, landmarks)
        U_m, s_m, _ = svd(K_mm, full_matrices=False)
        U_m, s_m = self._truncate_singular(U_m, s_m)

        df = self.df
        self.landmarks_ = landmarks
        self.projection_ = U_m[:, :df] / s_m[:df]

        s_trunc = s_m[:df]
        self.penalty_diag = np.minimum(
            s_trunc[0] / s_trunc, self.max_penalty_ratio
        )

        if self.standardize:
            self.col_sd_ = np.maximum(self._column_sd(coords, chunk_size or n), self.eps)
        return self

    def _column_sd(self, coords, chunk_size):
        """Population standard deviation of the basis columns over ``coords``.

        Merges per-chunk counts, means and squared deviations ``m2``. For one
        chunk this is just ``basis.std(axis=0)``.
        """
        n, mean, m2 = 0, 0.0, 0.0
        for start in range(0, len(coords), chunk_size):
            basis = self._kernel(coords[start:start + chunk_size], self.landmarks_) @ self.projection_
            k, chunk_mean = len(basis), basis.mean(axis=0)
            delta = chunk_mean - mean
            mean = mean + delta * (k / (n + k))
            m2 = m2 + ((basis - chunk_mean) ** 2).sum(axis=0) + delta ** 2 * (n * k / (n + k))
            n += k
        return np.sqrt(m2 / n)

    def transform(self, coords):
        if self.landmarks_ is None:
            raise RuntimeError("SpatialBasis.transform called before fit.")
        coords = np.asarray(coords)
        basis = self._kernel(coords, self.landmarks_) @ self.projection_
        if self.standardize:
            basis = basis / self.col_sd_
        return basis

    def fit_transform(self, coords):
        return self.fit(coords).transform(coords)

fit(coords, chunk_size=None)

Fit on coords; chunk_size=None evaluates all rows at once.

Source code in scdesigner/src/scdesigner/data/basis.py
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
def fit(self, coords, chunk_size=None):
    """Fit on ``coords``; ``chunk_size=None`` evaluates all rows at once."""
    coords = np.asarray(coords)
    n = coords.shape[0]
    idx = np.random.choice(n, size=min(self.n_landmarks, n), replace=False)
    landmarks = coords[idx]

    K_mm = self._kernel(landmarks, landmarks)
    K_mm = self._regularize(K_mm, landmarks)
    U_m, s_m, _ = svd(K_mm, full_matrices=False)
    U_m, s_m = self._truncate_singular(U_m, s_m)

    df = self.df
    self.landmarks_ = landmarks
    self.projection_ = U_m[:, :df] / s_m[:df]

    s_trunc = s_m[:df]
    self.penalty_diag = np.minimum(
        s_trunc[0] / s_trunc, self.max_penalty_ratio
    )

    if self.standardize:
        self.col_sd_ = np.maximum(self._column_sd(coords, chunk_size or n), self.eps)
    return self

SpatialTerm dataclass

Unfitted spatial basis and optional penalty on its coefficients.

Parameters:

Name Type Description Default
basis SpatialBasis

Template

required
penalty QuadraticPenalty

None leaves the basis coefficients unpenalized.

None
Source code in scdesigner/src/scdesigner/data/spatial.py
24
25
26
27
28
29
30
31
32
33
34
35
36
37
@dataclass(frozen=True)
class SpatialTerm:
    """Unfitted spatial basis and optional penalty on its coefficients.

    Parameters
    ----------
    basis : SpatialBasis
        Template
    penalty : QuadraticPenalty, optional
        ``None`` leaves the basis coefficients unpenalized.
    """

    basis: SpatialBasis
    penalty: Optional[QuadraticPenalty] = None

TPSBasis

Bases: SpatialBasis

Thin-plate spline basis (Nystrom).

Projects out the TPS penalty null space (intercept + linear terms over landmarks) before SVD; drops singular values below eps.

Source code in scdesigner/src/scdesigner/data/basis.py
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
class TPSBasis(SpatialBasis):
    """Thin-plate spline basis (Nystrom).

    Projects out the TPS penalty null space (intercept + linear terms over
    landmarks) before SVD; drops singular values below ``eps``.
    """

    def _kernel(self, A, B):
        return tps_kernel(A, B, self.eps)

    def _regularize(self, K_mm, landmarks):
        P = np.column_stack([np.ones(len(landmarks)), landmarks])
        Q, _ = np.linalg.qr(P, mode="reduced")
        proj = np.eye(len(landmarks)) - Q @ Q.T
        return proj @ K_mm @ proj

    def _truncate_singular(self, U_m, s_m):
        keep = s_m > self.eps
        return U_m[:, keep], s_m[keep]

adata_loader(adata, formula, chunk_size=None, batch_size=1024, shuffle=False, num_workers=0, device=None, partition_keys=None, **kwargs)

Create a :class:~torch.utils.data.DataLoader over an AnnData dataset.

The resulting loader yields tuples (X_batch, obs_batch) where:

  • X_batch is a float tensor of shape (batch_size, n_genes)
  • obs_batch is a dict mapping each formula key to a float tensor of shape (batch_size, n_covariates) for that key's design matrix

For backed AnnData objects, the underlying dataset uses chunk caching to limit memory usage. Chunks are read in the order stored on disk.

Parameters:

Name Type Description Default
adata AnnData

Input AnnData object.

required
formula dict[str, str] or Design

A fitted :class:~scdesigner.data.design.Design, or associated formulas, fitted on adata.obs with :func:~scdesigner.data.design.fit_design.

required
chunk_size int

Rows per chunked read. None preloads in-memory data and reads backed data in DEFAULT_CHUNK_SIZE-row chunks.

None
batch_size int

Mini-batch size returned by the loader.

1024
shuffle bool

Whether to shuffle observations each epoch. Not allowed for backed reads.

False
num_workers int

Number of DataLoader workers.

0
partition_keys set of str

Formula used to partition observations, usually used for copula covariance groups. Ignored when formula is a Design. See :func:~scdesigner.data.formula.partition_formula.

None
**kwargs

Additional keyword arguments filtered via DEFAULT_ALLOWED_KWARGS["data"] and forwarded to :class:~torch.utils.data.DataLoader.

{}

Returns:

Type Description
DataLoader

DataLoader over the dataset.

Source code in scdesigner/src/scdesigner/data/loader.py
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
def adata_loader(
    adata: AnnData,
    formula: Union[Dict[str, str], Design],
    chunk_size: int = None,
    batch_size: int = 1024,
    shuffle: bool = False,
    num_workers: int = 0,
    device=None,
    partition_keys: Optional[Set[str]] = None,
    **kwargs
) -> DataLoader:
    """Create a :class:`~torch.utils.data.DataLoader` over an AnnData dataset.

    The resulting loader yields tuples ``(X_batch, obs_batch)`` where:

    - ``X_batch`` is a float tensor of shape (batch_size, n_genes)
    - ``obs_batch`` is a dict mapping each formula key to a float tensor
      of shape (batch_size, n_covariates) for that key's design matrix

    For backed AnnData objects, the underlying dataset uses chunk caching to
    limit memory usage. Chunks are read in the order stored on disk.

    Parameters
    ----------
    adata : AnnData
        Input AnnData object.
    formula : dict[str, str] or Design
        A fitted :class:`~scdesigner.data.design.Design`, or associated formulas,
        fitted on ``adata.obs`` with :func:`~scdesigner.data.design.fit_design`.
    chunk_size : int, optional
        Rows per chunked read. ``None`` preloads in-memory data and reads
        backed data in ``DEFAULT_CHUNK_SIZE``-row chunks.
    batch_size : int, optional
        Mini-batch size returned by the loader.
    shuffle : bool, optional
        Whether to shuffle observations each epoch. Not allowed for backed
        reads.
    num_workers : int, optional
        Number of DataLoader workers.
    partition_keys : set of str, optional
        Formula used to partition observations, usually used for copula
        covariance groups. Ignored when ``formula`` is a Design. See
        :func:`~scdesigner.data.formula.partition_formula`.
    **kwargs
        Additional keyword arguments filtered via ``DEFAULT_ALLOWED_KWARGS["data"]``
        and forwarded to :class:`~torch.utils.data.DataLoader`.

    Returns
    -------
    torch.utils.data.DataLoader
        DataLoader over the dataset.
    """
    data_kwargs = _filter_kwargs(kwargs, DEFAULT_ALLOWED_KWARGS['data'])
    device = get_device(device)
    chunk_size = resolve_chunk_size(adata, chunk_size)
    design = formula if isinstance(formula, Design) else fit_design(
        adata.obs, formula, partition_keys=partition_keys or set(),
        chunked=chunk_size is not None,
    )

    if chunk_size is None:
        dataset = _preloaded_adata(adata, design, device)
    else:
        if shuffle:
            raise ValueError(
                """Chunked loading does not support shuffle=True. We read chunks
                consecutively and train in that order. If the data have sorted
                rows, we recommend an initial permutation step."""
            )
        dataset = AnnDataDataset(adata, design, chunk_size, device)

    return DataLoader(
        dataset,
        batch_size=batch_size,
        shuffle=shuffle,
        num_workers=num_workers,
        collate_fn=dict_collate_fn,
        **data_kwargs
    )

obs_loader(obs, formula, **kwargs)

Create a loader that yields design matrices for an observation table.

This is a convenience wrapper for prediction-time batching: it creates a dummy AnnData with a placeholder X and uses :func:adata_loader to construct batches of covariates derived from obs.

Parameters:

Name Type Description Default
obs DataFrame

Observation metadata used to build design matrices.

required
formula dict[str, str] or Design

See :func:adata_loader. Using a Design from the training data ensures that the same state (e.g., spline knots) is used across batches.

required
**kwargs

Forwarded to :func:adata_loader (e.g. batch_size, device options).

{}

Returns:

Type Description
DataLoader

Loader yielding (X_batch, obs_batch) where X_batch is dummy.

Source code in scdesigner/src/scdesigner/data/loader.py
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
def obs_loader(obs: pd.DataFrame, formula: Union[Dict[str, str], Design], **kwargs):
    """Create a loader that yields design matrices for an observation table.

    This is a convenience wrapper for prediction-time batching: it creates a
    dummy AnnData with a placeholder ``X`` and uses :func:`adata_loader` to
    construct batches of covariates derived from ``obs``.

    Parameters
    ----------
    obs : pandas.DataFrame
        Observation metadata used to build design matrices.
    formula : dict[str, str] or Design
        See :func:`adata_loader`. Using a Design from the training data ensures
        that the same state (e.g., spline knots) is used across batches.
    **kwargs
        Forwarded to :func:`adata_loader` (e.g. ``batch_size``, device options).

    Returns
    -------
    torch.utils.data.DataLoader
        Loader yielding ``(X_batch, obs_batch)`` where ``X_batch`` is dummy.
    """
    adata = AnnData(X=np.zeros((len(obs), 1)), obs=obs)
    return adata_loader(adata, formula, **kwargs)