Skip to content

basis

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

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]

rbf_kernel(A, B, length_scale)

Radial basis function kernel: K[i,j] = exp(-||A_i - B_j||^2 / (2 * length_scale^2)).

Parameters:

Name Type Description Default
A ndarray of shape (n, d)

First set of points.

required
B ndarray of shape (m, d)

Second set of points.

required
length_scale float

Controls the spatial range of correlation; larger values give smoother functions.

required

Returns:

Name Type Description
K ndarray of shape (n, m)

Examples:

>>> K = rbf_kernel(np.array([[0.0, 0.0]]), np.array([[1.0, 0.0]]), length_scale=1.0)
>>> float(K[0, 0])
Source code in scdesigner/src/scdesigner/data/basis.py
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def rbf_kernel(A, B, length_scale):
    """Radial basis function kernel: K[i,j] = exp(-||A_i - B_j||^2 / (2 * length_scale^2)).

    Parameters
    ----------
    A : ndarray of shape (n, d)
        First set of points.
    B : ndarray of shape (m, d)
        Second set of points.
    length_scale : float
        Controls the spatial range of correlation; larger values give smoother functions.

    Returns
    -------
    K : ndarray of shape (n, m)

    Examples
    --------
    >>> K = rbf_kernel(np.array([[0.0, 0.0]]), np.array([[1.0, 0.0]]), length_scale=1.0)
    >>> float(K[0, 0])  # doctest: +SKIP
    """
    D = cdist(A, B)
    return np.exp(-0.5 * (D / length_scale) ** 2)

tps_kernel(A, B, eps)

Thin-plate spline kernel: K[i,j] = ||A_i - B_j||^2 log ||A_i - B_j||.

Parameters:

Name Type Description Default
A ndarray of shape (n, d)

First set of points.

required
B ndarray of shape (m, d)

Second set of points.

required
eps float

Epsilon parameter, preventing log(0).

required

Returns:

Name Type Description
K ndarray of shape (n, m)

Examples:

>>> K = tps_kernel(np.array([[0.0, 0.0]]), np.array([[1.0, 0.0]]), eps=1e-6)
>>> K
Source code in scdesigner/src/scdesigner/data/basis.py
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
def tps_kernel(A, B, eps):
    """Thin-plate spline kernel: K[i,j] = ||A_i - B_j||^2 log ||A_i - B_j||.

    Parameters
    ----------
    A : ndarray of shape (n, d)
        First set of points.
    B : ndarray of shape (m, d)
        Second set of points.
    eps : float
        Epsilon parameter, preventing log(0).

    Returns
    -------
    K : ndarray of shape (n, m)

    Examples
    --------
    >>> K = tps_kernel(np.array([[0.0, 0.0]]), np.array([[1.0, 0.0]]), eps=1e-6)
    >>> K  # doctest: +SKIP
    """
    D = cdist(A, B)
    D = np.maximum(D, eps)
    K = D**2 * np.log(D)
    return K