Skip to content

penalties

Quadratic penalties on named rows of marginal coefficient matrices.

These helper functions help regularize high-dimensional parameter functions (e.g., when derived from a large spatial basis). For coefficients B (design columns x features), rows r_k selected by name, and diagonal d,

P(B) = lam * sum_j w_j * sum_k d_k * B[r_k, j]**2,

where w_j = 1 / max(m_j, 0.01) for feature means m under "inverse_mean" weighting, and w_j = 1 under "none".

BoundCoefficientPenalty dataclass

Bind a penaltyP`` to a coefficient tensor by reference.

Source code in scdesigner/src/scdesigner/distributions/penalties.py
114
115
116
117
118
119
120
121
122
123
124
125
126
127
@dataclass(frozen=True, eq=False)
class BoundCoefficientPenalty:
    """`Bind a penalty `P`` to a coefficient tensor by reference."""

    coefficient: torch.Tensor
    rows: torch.Tensor
    diagonal: torch.Tensor
    weights: torch.Tensor
    lam: float

    def value(self) -> torch.Tensor:
        """``P`` at the current coefficients"""
        selected = self.coefficient[self.rows]
        return self.lam * (self.diagonal @ selected.square() @ self.weights)

value()

P at the current coefficients

Source code in scdesigner/src/scdesigner/distributions/penalties.py
124
125
126
127
def value(self) -> torch.Tensor:
    """``P`` at the current coefficients"""
    selected = self.coefficient[self.rows]
    return self.lam * (self.diagonal @ selected.square() @ self.weights)

CoefficientPenalty

P on named design columns of one marginal parameter.

Parameters:

Name Type Description Default
parameter str

Penalized parameter, e.g. "mean".

required
columns sequence of str

Penalized design columns. Matched by name, so their position in the design is irrelevant.

required
diagonal array-like of shape (len(columns),)

Nonnegative d_k for each column.

required
penalty QuadraticPenalty
required

Examples:

>>> spec = CoefficientPenalty("mean", ["x"], [1.0], QuadraticPenalty(lam=0.1))
>>> spec.columns
('x',)
Source code in scdesigner/src/scdesigner/distributions/penalties.py
 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
class CoefficientPenalty:
    """``P`` on named design columns of one marginal parameter.

    Parameters
    ----------
    parameter : str
        Penalized parameter, e.g. ``"mean"``.
    columns : sequence of str
        Penalized design columns. Matched by name, so their position in the
        design is irrelevant.
    diagonal : array-like of shape (len(columns),)
        Nonnegative ``d_k`` for each column.
    penalty : QuadraticPenalty

    Examples
    --------
    >>> spec = CoefficientPenalty("mean", ["x"], [1.0], QuadraticPenalty(lam=0.1))
    >>> spec.columns
    ('x',)
    """

    def __init__(
        self,
        parameter: str,
        columns: Sequence[str],
        diagonal: Union[Sequence[float], np.ndarray],
        penalty: QuadraticPenalty,
    ):
        self.parameter = parameter
        self.columns = tuple(columns)
        self.diagonal = np.array(diagonal, dtype=np.float64)
        self.diagonal.setflags(write=False)
        self.penalty = penalty

    @property
    def uses_feature_means(self) -> bool:
        """Whether :meth:`bind` needs ``feature_means``."""
        return self.penalty.weighting == "inverse_mean"

    def bind(
        self,
        predictor_names: Mapping[str, Sequence[str]],
        coefs: Mapping[str, torch.Tensor],
        feature_means: Optional[np.ndarray] = None,
    ) -> "BoundCoefficientPenalty":
        """Bind to coefficients

        Parameters
        ----------
        predictor_names : mapping of str to sequence of str
            Design-column names per parameter.
        coefs : mapping of str to torch.Tensor
            Coefficients per parameter, shape (n_design_columns, n_features).
        feature_means : ndarray of shape (n_features,), optional
            ``m``; used only under inverse-mean weighting.
        """
        coefficient = coefs[self.parameter]
        names = list(predictor_names[self.parameter])
        rows = [names.index(column) for column in self.columns]

        def as_tensor(values, dtype=coefficient.dtype):
            return torch.tensor(values, dtype=dtype, device=coefficient.device)

        return BoundCoefficientPenalty(
            coefficient=coefficient,
            rows=as_tensor(rows, dtype=torch.long),
            diagonal=as_tensor(self.diagonal),
            weights=as_tensor(self._feature_weights(feature_means, coefficient.shape[1])),
            lam=self.penalty.lam,
        )

    def _feature_weights(self, feature_means, n_features: int) -> np.ndarray:
        if not self.uses_feature_means:
            return np.ones(n_features)
        means = np.asarray(feature_means, dtype=np.float64)
        return 1.0 / np.maximum(means, MEAN_FLOOR)

uses_feature_means property

Whether :meth:bind needs feature_means.

bind(predictor_names, coefs, feature_means=None)

Bind to coefficients

Parameters:

Name Type Description Default
predictor_names mapping of str to sequence of str

Design-column names per parameter.

required
coefs mapping of str to torch.Tensor

Coefficients per parameter, shape (n_design_columns, n_features).

required
feature_means ndarray of shape (n_features,)

m; used only under inverse-mean weighting.

None
Source code in scdesigner/src/scdesigner/distributions/penalties.py
 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
def bind(
    self,
    predictor_names: Mapping[str, Sequence[str]],
    coefs: Mapping[str, torch.Tensor],
    feature_means: Optional[np.ndarray] = None,
) -> "BoundCoefficientPenalty":
    """Bind to coefficients

    Parameters
    ----------
    predictor_names : mapping of str to sequence of str
        Design-column names per parameter.
    coefs : mapping of str to torch.Tensor
        Coefficients per parameter, shape (n_design_columns, n_features).
    feature_means : ndarray of shape (n_features,), optional
        ``m``; used only under inverse-mean weighting.
    """
    coefficient = coefs[self.parameter]
    names = list(predictor_names[self.parameter])
    rows = [names.index(column) for column in self.columns]

    def as_tensor(values, dtype=coefficient.dtype):
        return torch.tensor(values, dtype=dtype, device=coefficient.device)

    return BoundCoefficientPenalty(
        coefficient=coefficient,
        rows=as_tensor(rows, dtype=torch.long),
        diagonal=as_tensor(self.diagonal),
        weights=as_tensor(self._feature_weights(feature_means, coefficient.shape[1])),
        lam=self.penalty.lam,
    )

QuadraticPenalty dataclass

Strength lam >= 0 and feature weights w of P.

Parameters:

Name Type Description Default
lam float
1.0
weighting (inverse_mean, none)
"inverse_mean"
Source code in scdesigner/src/scdesigner/distributions/penalties.py
22
23
24
25
26
27
28
29
30
31
32
33
@dataclass(frozen=True)
class QuadraticPenalty:
    """Strength ``lam >= 0`` and feature weights ``w`` of ``P``.

    Parameters
    ----------
    lam : float
    weighting : {"inverse_mean", "none"}
    """

    lam: float = 1.0
    weighting: Literal["inverse_mean", "none"] = "inverse_mean"