Skip to content

spatial

Spatial basis columns for marginal-parameter formulas.

:class:SpatialDesign fits spatial bases for parameters with :class:SpatialTerms, appends the K bases columns to the .obs as sp_<parameter>_0, ..., sp_<parameter>_<K-1>, and adds them to the parameter's formula. Basis columns are generated for the current chunk, so we don't have to create it on the entire (potentially large, backed) dataset. For penalization, we add :class:~scdesigner.distributions.penalties.CoefficientPenalty to those columns with d = basis.penalty_diag.

SpatialDesign

Extend .obs to include spatial basis columns.

Parameters:

Name Type Description Default
base_formula mapping of str to str

Formula per marginal parameter, before spatial columns.

required
terms mapping of str to SpatialTerm

Term per parameter. Parameters without one are unchanged.

required
spatial_cols tuple of str

Coordinate columns of the observations.

('spatial1', 'spatial2')

Attributes:

Name Type Description
formula dict of str to str

base_formula with the generated columns of each fitted term appended.

penalties tuple of CoefficientPenalty

One per penalized term.

bases dict of str to SpatialBasis

Fitted basis per term.

Source code in scdesigner/src/scdesigner/data/spatial.py
 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
class SpatialDesign:
    """Extend .obs to include spatial basis columns.

    Parameters
    ----------
    base_formula : mapping of str to str
        Formula per marginal parameter, before spatial columns.
    terms : mapping of str to SpatialTerm
        Term per parameter. Parameters without one are unchanged.
    spatial_cols : tuple of str
        Coordinate columns of the observations.

    Attributes
    ----------
    formula : dict of str to str
        ``base_formula`` with the generated columns of each fitted term appended.
    penalties : tuple of CoefficientPenalty
        One per penalized term.
    bases : dict of str to SpatialBasis
        Fitted basis per term.
    """

    def __init__(
        self,
        base_formula: Mapping[str, str],
        terms: Mapping[str, SpatialTerm],
        spatial_cols: Tuple[str, str] = ("spatial1", "spatial2"),
    ):
        self.base_formula = dict(base_formula)
        self.terms = copy.deepcopy(dict(terms))
        self.spatial_cols = tuple(spatial_cols)
        self.formula = dict(self.base_formula)
        self.penalties = ()
        self.bases = {}
        self._columns = None

    @property
    def is_fitted(self) -> bool:
        return self._columns is not None

    def fit(self, obs: pd.DataFrame, chunk_size: Optional[int] = None) -> "SpatialDesign":
        """Fit the spatial bases on coordinates in ``obs``.

        ``chunk_size`` control the number of considered per kernel evaluation.
        See :meth:`~scdesigner.data.basis.SpatialBasis.fit`.
        """
        bases = {name: copy.deepcopy(term.basis) for name, term in self.terms.items()}
        if bases:
            coords = self._coords(obs)
            for basis in bases.values():
                basis.fit(coords, chunk_size)

        # get the new column names
        columns = {
            name: tuple(f"sp_{name}_{k}" for k in range(len(basis.penalty_diag)))
            for name, basis in bases.items()
        }

        # create the formula
        formula = dict(self.base_formula)
        for name, generated in columns.items():
            formula[name] = " + ".join([formula[name], *generated])

        # build the penalty
        self.formula = formula
        self.penalties = tuple(
            CoefficientPenalty(name, columns[name], bases[name].penalty_diag, term.penalty)
            for name, term in self.terms.items()
            if term.penalty is not None
        )
        self.bases, self._columns = bases, columns
        return self

    def transform(self, obs: pd.DataFrame) -> pd.DataFrame:
        """Copy of ``obs`` with the fitted basis columns appended."""
        if not self.is_fitted:
            raise RuntimeError("SpatialDesign.transform requires a successful fit.")
        if not self.bases:
            return obs.copy()
        coords = self._coords(obs)
        generated = {}
        for name, basis in self.bases.items():
            generated.update(zip(self._columns[name], basis.transform(coords).T))
        return obs.assign(**generated)

    def _coords(self, obs: pd.DataFrame) -> np.ndarray:
        return obs[list(self.spatial_cols)].to_numpy(dtype=np.float64)

fit(obs, chunk_size=None)

Fit the spatial bases on coordinates in obs.

chunk_size control the number of considered per kernel evaluation. See :meth:~scdesigner.data.basis.SpatialBasis.fit.

Source code in scdesigner/src/scdesigner/data/spatial.py
 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
def fit(self, obs: pd.DataFrame, chunk_size: Optional[int] = None) -> "SpatialDesign":
    """Fit the spatial bases on coordinates in ``obs``.

    ``chunk_size`` control the number of considered per kernel evaluation.
    See :meth:`~scdesigner.data.basis.SpatialBasis.fit`.
    """
    bases = {name: copy.deepcopy(term.basis) for name, term in self.terms.items()}
    if bases:
        coords = self._coords(obs)
        for basis in bases.values():
            basis.fit(coords, chunk_size)

    # get the new column names
    columns = {
        name: tuple(f"sp_{name}_{k}" for k in range(len(basis.penalty_diag)))
        for name, basis in bases.items()
    }

    # create the formula
    formula = dict(self.base_formula)
    for name, generated in columns.items():
        formula[name] = " + ".join([formula[name], *generated])

    # build the penalty
    self.formula = formula
    self.penalties = tuple(
        CoefficientPenalty(name, columns[name], bases[name].penalty_diag, term.penalty)
        for name, term in self.terms.items()
        if term.penalty is not None
    )
    self.bases, self._columns = bases, columns
    return self

transform(obs)

Copy of obs with the fitted basis columns appended.

Source code in scdesigner/src/scdesigner/data/spatial.py
113
114
115
116
117
118
119
120
121
122
123
def transform(self, obs: pd.DataFrame) -> pd.DataFrame:
    """Copy of ``obs`` with the fitted basis columns appended."""
    if not self.is_fitted:
        raise RuntimeError("SpatialDesign.transform requires a successful fit.")
    if not self.bases:
        return obs.copy()
    coords = self._coords(obs)
    generated = {}
    for name, basis in self.bases.items():
        generated.update(zip(self._columns[name], basis.transform(coords).T))
    return obs.assign(**generated)

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