Skip to content

API Reference

The two main classes in glum are GeneralizedLinearRegressor and GeneralizedLinearRegressorCV. Most users will use fit() and predict().

BinomialDistribution

Bases: ExponentialDispersionModel

A class for the Binomial distribution.

The Binomial distribution models outcomes y in [0, 1].

See the documentation of the superclass, ExponentialDispersionModel, for details.

lower_bound class-attribute instance-attribute

lower_bound = 0

Get the lower bound of values for the EDM.

upper_bound class-attribute instance-attribute

upper_bound = 1

Get the upper bound of values for the EDM.

include_lower_bound class-attribute instance-attribute

include_lower_bound = True

Return whether lower_bound is allowed as a value of y.

include_upper_bound class-attribute instance-attribute

include_upper_bound = True

Return whether upper_bound is allowed as a value of y.

in_y_range

in_y_range(x) -> np.ndarray

Return True if x is in the valid range of the EDM.

Source code in src/glum/_distribution.py
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def in_y_range(self, x) -> np.ndarray:
    """Return `True` if `x` is in the valid range of the EDM."""
    if self.include_lower_bound:
        lb_op: np.ufunc = np.greater_equal
    else:
        lb_op = np.greater

    if self.include_upper_bound:
        ub_op: np.ufunc = np.less_equal
    else:
        ub_op = np.less

    return lb_op(x, self.lower_bound) & ub_op(x, self.upper_bound)

to_tweedie

to_tweedie(safe=True)

Return the Tweedie representation of a distribution if it exists.

Source code in src/glum/_distribution.py
102
103
104
105
106
107
108
def to_tweedie(self, safe=True):
    """Return the Tweedie representation of a distribution if it exists."""
    if hasattr(self, "__tweedie_repr__"):
        return self.__tweedie_repr__()
    if safe:
        raise ValueError("This distribution has no Tweedie representation.")
    return None

variance

variance(mu, dispersion=1, sample_weight=1) -> np.ndarray

Compute the variance function.

The variance of \(Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)\) takes the form \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(w_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def variance(self, mu, dispersion=1, sample_weight=1) -> np.ndarray:
    r"""Compute the variance function.

    The variance of $Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)$ takes
    the form $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the
    unit variance and $w_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance(mu) * dispersion / sample_weight

variance_derivative

variance_derivative(mu, dispersion=1, sample_weight=1)

Compute the derivative of the variance with respect to mu.

The derivative of the variance is equal to \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(ws_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def variance_derivative(self, mu, dispersion=1, sample_weight=1):
    r"""Compute the derivative of the variance with respect to `mu`.

    The derivative of the variance is equal to
    $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the unit
    variance and $ws_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance_derivative(mu) * dispersion / sample_weight

unit_deviance_derivative

unit_deviance_derivative(y, mu)

Compute the derivative of the unit deviance with respect to mu.

The derivative of the unit deviance is given by \(2 \times (\mu - y) / v(\mu)\), where \(v(\mu)\) is the unit variance.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
def unit_deviance_derivative(self, y, mu):
    r"""Compute the derivative of the unit deviance with respect to `mu`.

    The derivative of the unit deviance is given by
    $2 \times (\mu - y) / v(\mu)$, where $v(\mu)$ is the unit
    variance.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return -2 * (y - mu) / self.unit_variance(mu)

deviance

deviance(y, mu, sample_weight=1) -> float

Compute the deviance.

The deviance is a weighted sum of the unit deviances. In terms of the unit log likelihood \(\ell\), it equals \(2 \sum_i [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which the variance is inversely proportional.

1
Source code in src/glum/_distribution.py
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
def deviance(self, y, mu, sample_weight=1) -> float:
    r"""Compute the deviance.

    The deviance is a weighted sum of the unit deviances. In terms of the
    unit log likelihood $\ell$, it equals
    $2 \sum_i [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]$,
    i.e. twice the difference between the log likelihood of a saturated
    model (with one parameter per observation) and the model at hand.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which the variance is inversely proportional.
    """
    if sample_weight is None:
        return np.sum(self.unit_deviance(y, mu))
    else:
        return np.sum(self.unit_deviance(y, mu) * sample_weight)

deviance_derivative

deviance_derivative(y, mu, sample_weight=1)

Compute the derivative of the deviance with respect to mu.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples)(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
def deviance_derivative(self, y, mu, sample_weight=1):
    r"""Compute the derivative of the deviance with respect to `mu`.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,) (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return sample_weight * self.unit_deviance_derivative(y, mu)

eta_mu_deviance

eta_mu_deviance(link: Link, factor: float, cur_eta, X_dot_d, y, sample_weight) -> tuple[np.ndarray, np.ndarray, float]

Compute eta, mu and the deviance.

Returns:

Type Description
(ndarray, shape(shape[0]))

The linear predictor, eta, as cur_eta + factor * X_dot_d.

(ndarray, shape(shape[0]))

The link-function-transformed prediction, mu.

float

The deviance.

Source code in src/glum/_distribution.py
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
def eta_mu_deviance(
    self,
    link: Link,
    factor: float,
    cur_eta,
    X_dot_d,
    y,
    sample_weight,
) -> tuple[np.ndarray, np.ndarray, float]:
    """Compute `eta`, `mu` and the deviance.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The linear predictor, `eta`, as `cur_eta + factor * X_dot_d`.
    numpy.ndarray, shape (X.shape[0],)
        The link-function-transformed prediction, `mu`.
    float
        The deviance.
    """
    # eta_out and mu_out are filled inside self._eta_mu_deviance,
    # avoiding allocating new arrays for every line search loop
    eta_out = np.empty_like(cur_eta)
    mu_out = np.empty_like(cur_eta)

    deviance = self._eta_mu_deviance(
        link, factor, cur_eta, X_dot_d, y, sample_weight, eta_out, mu_out
    )

    return eta_out, mu_out, deviance

rowwise_gradient_hessian

rowwise_gradient_hessian(link: Link, coef, dispersion, X: Union[MatrixBase, StandardizedMatrix], y, sample_weight, eta, mu, offset=None)

Compute the gradient and negative Hessian of the log likelihood row-wise.

Returns:

Type Description
(ndarray, shape(shape[0]))

The gradient of the log likelihood, row-wise.

(ndarray, shape(shape[0]))

The negative Hessian of the log likelihood, row-wise.

Source code in src/glum/_distribution.py
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
def rowwise_gradient_hessian(
    self,
    link: Link,
    coef,
    dispersion,
    X: Union[MatrixBase, StandardizedMatrix],
    y,
    sample_weight,
    eta,
    mu,
    offset=None,
):
    """Compute the gradient and negative Hessian of the log likelihood row-wise.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The gradient of the log likelihood, row-wise.
    numpy.ndarray, shape (X.shape[0],)
        The negative Hessian of the log likelihood, row-wise.
    """
    gradient_rows = np.empty_like(mu)
    hessian_rows = np.empty_like(mu)

    self._rowwise_gradient_hessian(
        link, y, sample_weight, eta, mu, gradient_rows, hessian_rows
    )

    # To form the full Hessian matrix from the IRLS sample_weight:
    # hessian_matrix = _safe_sandwich_dot(X, hessian_rows, intercept=intercept)
    return gradient_rows, hessian_rows

unit_variance

unit_variance(mu)

Compute the unit variance.

The unit variance, \(v(\mu) \equiv b''((b')^{-1} (\mu))\), determines the variance as a function of the mean \(\mu\) by \(\mathrm{var}(y_i) = v(\mu_i) \times \phi / w_i\). It can also be derived from the unit deviance \(d(y, \mu)\) as

\[ v(\mu) = 2 \div \frac{\partial^2 d(y, \mu)}{\partial\mu^2} \big| _{y=\mu}. \]

See also variance.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
1269
1270
def unit_variance(self, mu):  # noqa D
    return mu * (1 - mu)

unit_variance_derivative

unit_variance_derivative(mu)

Compute the derivative of the unit variance with respect to mu.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
1272
1273
def unit_variance_derivative(self, mu):  # noqa D
    return 1 - 2 * mu

unit_deviance

unit_deviance(y, mu)

Compute the unit deviance.

In terms of the unit log likelihood \(\ell\), the unit deviance is \(2 [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
1275
1276
1277
def unit_deviance(self, y, mu):  # noqa D
    # see Wooldridge and Papke (1996) for the fractional case
    return -2 * (special.xlogy(y, mu) + special.xlogy(1 - y, 1 - mu))

log_likelihood

log_likelihood(y, mu, sample_weight=None, dispersion=1) -> float

Compute the log likelihood.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Sample weights.

None
dispersion (float, optional(default=1))

Ignored.

1
Source code in src/glum/_distribution.py
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
def log_likelihood(self, y, mu, sample_weight=None, dispersion=1) -> float:
    """Compute the log likelihood.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Sample weights.

    dispersion : float, optional (default=1)
        Ignored.
    """
    ll = special.xlogy(y, mu) + special.xlogy(1 - y, 1 - mu)
    return np.sum(ll) if sample_weight is None else np.dot(ll, sample_weight)

dispersion

dispersion(y, mu, sample_weight=None, ddof=1, method='pearson') -> float

Estimate the dispersion parameter \(\phi\).

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inversely proportional.

None
ddof (int, optional(default=1))

Degrees of freedom consumed by the model for mu.

1
method

Whether to base the estimate on the Pearson residuals or the deviance.

'pearson'
Source code in src/glum/_distribution.py
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
def dispersion(  # noqa D
    self, y, mu, sample_weight=None, ddof=1, method="pearson"
) -> float:
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)

    if method == "pearson":
        formula = "((y - mu) ** 2) / (mu * (1 - mu))"
        if sample_weight is None:
            return numexpr.evaluate(formula).sum() / (len(y) - ddof)
        else:
            formula = f"sample_weight * {formula}"
            return numexpr.evaluate(formula).sum() / (sample_weight.sum() - ddof)

    return super().dispersion(
        y, mu, sample_weight=sample_weight, ddof=ddof, method=method
    )

ExponentialDispersionModel

Base class for reproductive Exponential Dispersion Models (EDM).

The PDF of \(Y \sim \mathrm{EDM}(\theta, \phi)\) is given by

\[ p(y \mid \theta, \phi) = \exp \left(\frac{y \theta - b(\theta)}{\phi / w} + c(y; w / \phi) \right), \]

where \(\theta\) is the scale parameter, \(\phi\) is the dispersion parameter, \(w\) is a given weight, \(b\) is the cumulant function and \(c\) is a normalization term.

It can be shown that \(\mathrm{E}(Y) = b'(\theta)\) and \(\mathrm{var}(Y) = b''(\theta) \times \phi / w\).

References

< https://en.wikipedia.org/wiki/Exponential_dispersion_model >.

lower_bound abstractmethod property

lower_bound: float

Get the lower bound of values for the EDM.

upper_bound abstractmethod property

upper_bound: float

Get the upper bound of values for the EDM.

include_lower_bound abstractmethod property

include_lower_bound: bool

Return whether lower_bound is allowed as a value of y.

include_upper_bound abstractmethod property

include_upper_bound: bool

Return whether upper_bound is allowed as a value of y.

in_y_range

in_y_range(x) -> np.ndarray

Return True if x is in the valid range of the EDM.

Source code in src/glum/_distribution.py
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def in_y_range(self, x) -> np.ndarray:
    """Return `True` if `x` is in the valid range of the EDM."""
    if self.include_lower_bound:
        lb_op: np.ufunc = np.greater_equal
    else:
        lb_op = np.greater

    if self.include_upper_bound:
        ub_op: np.ufunc = np.less_equal
    else:
        ub_op = np.less

    return lb_op(x, self.lower_bound) & ub_op(x, self.upper_bound)

to_tweedie

to_tweedie(safe=True)

Return the Tweedie representation of a distribution if it exists.

Source code in src/glum/_distribution.py
102
103
104
105
106
107
108
def to_tweedie(self, safe=True):
    """Return the Tweedie representation of a distribution if it exists."""
    if hasattr(self, "__tweedie_repr__"):
        return self.__tweedie_repr__()
    if safe:
        raise ValueError("This distribution has no Tweedie representation.")
    return None

unit_variance abstractmethod

unit_variance(mu)

Compute the unit variance.

The unit variance, \(v(\mu) \equiv b''((b')^{-1} (\mu))\), determines the variance as a function of the mean \(\mu\) by \(\mathrm{var}(y_i) = v(\mu_i) \times \phi / w_i\). It can also be derived from the unit deviance \(d(y, \mu)\) as

\[ v(\mu) = 2 \div \frac{\partial^2 d(y, \mu)}{\partial\mu^2} \big| _{y=\mu}. \]

See also variance.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
@abstractmethod
def unit_variance(self, mu):
    r"""Compute the unit variance.

    The unit variance, $v(\mu) \equiv b''((b')^{-1} (\mu))$,
    determines the variance as a function of the mean $\mu$ by
    $\mathrm{var}(y_i) = v(\mu_i) \times \phi / w_i$. It can also be
    derived from the unit deviance $d(y, \mu)$ as

    $$
    v(\mu) = 2 \div \frac{\partial^2 d(y, \mu)}{\partial\mu^2} \big| _{y=\mu}.
    $$

    See also [`variance`][glum.ExponentialDispersionModel.variance].

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.
    """
    pass

unit_variance_derivative abstractmethod

unit_variance_derivative(mu)

Compute the derivative of the unit variance with respect to mu.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
132
133
134
135
136
137
138
139
140
141
@abstractmethod
def unit_variance_derivative(self, mu):
    r"""Compute the derivative of the unit variance with respect to `mu`.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.
    """
    pass

variance

variance(mu, dispersion=1, sample_weight=1) -> np.ndarray

Compute the variance function.

The variance of \(Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)\) takes the form \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(w_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def variance(self, mu, dispersion=1, sample_weight=1) -> np.ndarray:
    r"""Compute the variance function.

    The variance of $Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)$ takes
    the form $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the
    unit variance and $w_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance(mu) * dispersion / sample_weight

variance_derivative

variance_derivative(mu, dispersion=1, sample_weight=1)

Compute the derivative of the variance with respect to mu.

The derivative of the variance is equal to \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(ws_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def variance_derivative(self, mu, dispersion=1, sample_weight=1):
    r"""Compute the derivative of the variance with respect to `mu`.

    The derivative of the variance is equal to
    $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the unit
    variance and $ws_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance_derivative(mu) * dispersion / sample_weight

unit_deviance abstractmethod

unit_deviance(y, mu)

Compute the unit deviance.

In terms of the unit log likelihood \(\ell\), the unit deviance is \(2 [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
@abstractmethod
def unit_deviance(self, y, mu):
    r"""Compute the unit deviance.

    In terms of the unit log likelihood $\ell$, the unit deviance is
    $2 [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]$, i.e. twice the
    difference between the log likelihood of a saturated model (with one
    parameter per observation) and the model at hand.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.
    """
    pass

unit_deviance_derivative

unit_deviance_derivative(y, mu)

Compute the derivative of the unit deviance with respect to mu.

The derivative of the unit deviance is given by \(2 \times (\mu - y) / v(\mu)\), where \(v(\mu)\) is the unit variance.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
def unit_deviance_derivative(self, y, mu):
    r"""Compute the derivative of the unit deviance with respect to `mu`.

    The derivative of the unit deviance is given by
    $2 \times (\mu - y) / v(\mu)$, where $v(\mu)$ is the unit
    variance.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return -2 * (y - mu) / self.unit_variance(mu)

deviance

deviance(y, mu, sample_weight=1) -> float

Compute the deviance.

The deviance is a weighted sum of the unit deviances. In terms of the unit log likelihood \(\ell\), it equals \(2 \sum_i [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which the variance is inversely proportional.

1
Source code in src/glum/_distribution.py
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
def deviance(self, y, mu, sample_weight=1) -> float:
    r"""Compute the deviance.

    The deviance is a weighted sum of the unit deviances. In terms of the
    unit log likelihood $\ell$, it equals
    $2 \sum_i [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]$,
    i.e. twice the difference between the log likelihood of a saturated
    model (with one parameter per observation) and the model at hand.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which the variance is inversely proportional.
    """
    if sample_weight is None:
        return np.sum(self.unit_deviance(y, mu))
    else:
        return np.sum(self.unit_deviance(y, mu) * sample_weight)

deviance_derivative

deviance_derivative(y, mu, sample_weight=1)

Compute the derivative of the deviance with respect to mu.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples)(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
def deviance_derivative(self, y, mu, sample_weight=1):
    r"""Compute the derivative of the deviance with respect to `mu`.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,) (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return sample_weight * self.unit_deviance_derivative(y, mu)

eta_mu_deviance

eta_mu_deviance(link: Link, factor: float, cur_eta, X_dot_d, y, sample_weight) -> tuple[np.ndarray, np.ndarray, float]

Compute eta, mu and the deviance.

Returns:

Type Description
(ndarray, shape(shape[0]))

The linear predictor, eta, as cur_eta + factor * X_dot_d.

(ndarray, shape(shape[0]))

The link-function-transformed prediction, mu.

float

The deviance.

Source code in src/glum/_distribution.py
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
def eta_mu_deviance(
    self,
    link: Link,
    factor: float,
    cur_eta,
    X_dot_d,
    y,
    sample_weight,
) -> tuple[np.ndarray, np.ndarray, float]:
    """Compute `eta`, `mu` and the deviance.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The linear predictor, `eta`, as `cur_eta + factor * X_dot_d`.
    numpy.ndarray, shape (X.shape[0],)
        The link-function-transformed prediction, `mu`.
    float
        The deviance.
    """
    # eta_out and mu_out are filled inside self._eta_mu_deviance,
    # avoiding allocating new arrays for every line search loop
    eta_out = np.empty_like(cur_eta)
    mu_out = np.empty_like(cur_eta)

    deviance = self._eta_mu_deviance(
        link, factor, cur_eta, X_dot_d, y, sample_weight, eta_out, mu_out
    )

    return eta_out, mu_out, deviance

rowwise_gradient_hessian

rowwise_gradient_hessian(link: Link, coef, dispersion, X: Union[MatrixBase, StandardizedMatrix], y, sample_weight, eta, mu, offset=None)

Compute the gradient and negative Hessian of the log likelihood row-wise.

Returns:

Type Description
(ndarray, shape(shape[0]))

The gradient of the log likelihood, row-wise.

(ndarray, shape(shape[0]))

The negative Hessian of the log likelihood, row-wise.

Source code in src/glum/_distribution.py
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
def rowwise_gradient_hessian(
    self,
    link: Link,
    coef,
    dispersion,
    X: Union[MatrixBase, StandardizedMatrix],
    y,
    sample_weight,
    eta,
    mu,
    offset=None,
):
    """Compute the gradient and negative Hessian of the log likelihood row-wise.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The gradient of the log likelihood, row-wise.
    numpy.ndarray, shape (X.shape[0],)
        The negative Hessian of the log likelihood, row-wise.
    """
    gradient_rows = np.empty_like(mu)
    hessian_rows = np.empty_like(mu)

    self._rowwise_gradient_hessian(
        link, y, sample_weight, eta, mu, gradient_rows, hessian_rows
    )

    # To form the full Hessian matrix from the IRLS sample_weight:
    # hessian_matrix = _safe_sandwich_dot(X, hessian_rows, intercept=intercept)
    return gradient_rows, hessian_rows

dispersion

dispersion(y, mu, sample_weight=None, ddof=1, method='pearson') -> float

Estimate the dispersion parameter \(\phi\).

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inversely proportional.

None
ddof (int, optional(default=1))

Degrees of freedom consumed by the model for mu.

1
method

Whether to base the estimate on the Pearson residuals or the deviance.

'pearson'
Source code in src/glum/_distribution.py
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
def dispersion(self, y, mu, sample_weight=None, ddof=1, method="pearson") -> float:
    r"""Estimate the dispersion parameter $\phi$.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inversely proportional.

    ddof : int, optional (default=1)
        Degrees of freedom consumed by the model for `mu`.

    method = {'pearson', 'deviance'}, optional (default='pearson')
        Whether to base the estimate on the Pearson residuals or the deviance.
    """
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)

    if method == "pearson":
        pearson_residuals = ((y - mu) ** 2) / self.unit_variance(mu)
        if sample_weight is None:
            numerator = pearson_residuals.sum()
        else:
            numerator = np.dot(pearson_residuals, sample_weight)
    elif method == "deviance":
        numerator = self.deviance(y, mu, sample_weight)
    else:
        raise NotImplementedError(f"Method {method} hasn't been implemented.")

    if sample_weight is None:
        return numerator / (len(y) - ddof)
    else:
        return numerator / (sample_weight.sum() - ddof)

GammaDistribution

Bases: ExponentialDispersionModel

Class for the gamma distribution.

The gamma distribution models outcomes y in (0, +∞).

See the documentation of the superclass, ExponentialDispersionModel, for details.

lower_bound class-attribute instance-attribute

lower_bound = 0

Get the lower bound of values for the EDM.

upper_bound class-attribute instance-attribute

upper_bound = np.inf

Get the upper bound of values for the EDM.

include_lower_bound class-attribute instance-attribute

include_lower_bound = False

Return whether lower_bound is allowed as a value of y.

include_upper_bound class-attribute instance-attribute

include_upper_bound = False

Return whether upper_bound is allowed as a value of y.

in_y_range

in_y_range(x) -> np.ndarray

Return True if x is in the valid range of the EDM.

Source code in src/glum/_distribution.py
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def in_y_range(self, x) -> np.ndarray:
    """Return `True` if `x` is in the valid range of the EDM."""
    if self.include_lower_bound:
        lb_op: np.ufunc = np.greater_equal
    else:
        lb_op = np.greater

    if self.include_upper_bound:
        ub_op: np.ufunc = np.less_equal
    else:
        ub_op = np.less

    return lb_op(x, self.lower_bound) & ub_op(x, self.upper_bound)

to_tweedie

to_tweedie(safe=True)

Return the Tweedie representation of a distribution if it exists.

Source code in src/glum/_distribution.py
102
103
104
105
106
107
108
def to_tweedie(self, safe=True):
    """Return the Tweedie representation of a distribution if it exists."""
    if hasattr(self, "__tweedie_repr__"):
        return self.__tweedie_repr__()
    if safe:
        raise ValueError("This distribution has no Tweedie representation.")
    return None

variance

variance(mu, dispersion=1, sample_weight=1) -> np.ndarray

Compute the variance function.

The variance of \(Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)\) takes the form \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(w_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def variance(self, mu, dispersion=1, sample_weight=1) -> np.ndarray:
    r"""Compute the variance function.

    The variance of $Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)$ takes
    the form $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the
    unit variance and $w_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance(mu) * dispersion / sample_weight

variance_derivative

variance_derivative(mu, dispersion=1, sample_weight=1)

Compute the derivative of the variance with respect to mu.

The derivative of the variance is equal to \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(ws_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def variance_derivative(self, mu, dispersion=1, sample_weight=1):
    r"""Compute the derivative of the variance with respect to `mu`.

    The derivative of the variance is equal to
    $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the unit
    variance and $ws_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance_derivative(mu) * dispersion / sample_weight

unit_deviance_derivative

unit_deviance_derivative(y, mu)

Compute the derivative of the unit deviance with respect to mu.

The derivative of the unit deviance is given by \(2 \times (\mu - y) / v(\mu)\), where \(v(\mu)\) is the unit variance.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
def unit_deviance_derivative(self, y, mu):
    r"""Compute the derivative of the unit deviance with respect to `mu`.

    The derivative of the unit deviance is given by
    $2 \times (\mu - y) / v(\mu)$, where $v(\mu)$ is the unit
    variance.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return -2 * (y - mu) / self.unit_variance(mu)

deviance_derivative

deviance_derivative(y, mu, sample_weight=1)

Compute the derivative of the deviance with respect to mu.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples)(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
def deviance_derivative(self, y, mu, sample_weight=1):
    r"""Compute the derivative of the deviance with respect to `mu`.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,) (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return sample_weight * self.unit_deviance_derivative(y, mu)

eta_mu_deviance

eta_mu_deviance(link: Link, factor: float, cur_eta, X_dot_d, y, sample_weight) -> tuple[np.ndarray, np.ndarray, float]

Compute eta, mu and the deviance.

Returns:

Type Description
(ndarray, shape(shape[0]))

The linear predictor, eta, as cur_eta + factor * X_dot_d.

(ndarray, shape(shape[0]))

The link-function-transformed prediction, mu.

float

The deviance.

Source code in src/glum/_distribution.py
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
def eta_mu_deviance(
    self,
    link: Link,
    factor: float,
    cur_eta,
    X_dot_d,
    y,
    sample_weight,
) -> tuple[np.ndarray, np.ndarray, float]:
    """Compute `eta`, `mu` and the deviance.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The linear predictor, `eta`, as `cur_eta + factor * X_dot_d`.
    numpy.ndarray, shape (X.shape[0],)
        The link-function-transformed prediction, `mu`.
    float
        The deviance.
    """
    # eta_out and mu_out are filled inside self._eta_mu_deviance,
    # avoiding allocating new arrays for every line search loop
    eta_out = np.empty_like(cur_eta)
    mu_out = np.empty_like(cur_eta)

    deviance = self._eta_mu_deviance(
        link, factor, cur_eta, X_dot_d, y, sample_weight, eta_out, mu_out
    )

    return eta_out, mu_out, deviance

rowwise_gradient_hessian

rowwise_gradient_hessian(link: Link, coef, dispersion, X: Union[MatrixBase, StandardizedMatrix], y, sample_weight, eta, mu, offset=None)

Compute the gradient and negative Hessian of the log likelihood row-wise.

Returns:

Type Description
(ndarray, shape(shape[0]))

The gradient of the log likelihood, row-wise.

(ndarray, shape(shape[0]))

The negative Hessian of the log likelihood, row-wise.

Source code in src/glum/_distribution.py
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
def rowwise_gradient_hessian(
    self,
    link: Link,
    coef,
    dispersion,
    X: Union[MatrixBase, StandardizedMatrix],
    y,
    sample_weight,
    eta,
    mu,
    offset=None,
):
    """Compute the gradient and negative Hessian of the log likelihood row-wise.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The gradient of the log likelihood, row-wise.
    numpy.ndarray, shape (X.shape[0],)
        The negative Hessian of the log likelihood, row-wise.
    """
    gradient_rows = np.empty_like(mu)
    hessian_rows = np.empty_like(mu)

    self._rowwise_gradient_hessian(
        link, y, sample_weight, eta, mu, gradient_rows, hessian_rows
    )

    # To form the full Hessian matrix from the IRLS sample_weight:
    # hessian_matrix = _safe_sandwich_dot(X, hessian_rows, intercept=intercept)
    return gradient_rows, hessian_rows

unit_variance

unit_variance(mu) -> np.ndarray

Compute the unit variance.

The unit variance, \(v(\mu) \equiv b''((b')^{-1} (\mu))\), determines the variance as a function of the mean \(\mu\) by \(\mathrm{var}(y_i) = v(\mu_i) \times \phi / w_i\). It can also be derived from the unit deviance \(d(y, \mu)\) as

\[ v(\mu) = 2 \div \frac{\partial^2 d(y, \mu)}{\partial\mu^2} \big| _{y=\mu}. \]

See also variance.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
1022
1023
def unit_variance(self, mu) -> np.ndarray:  # noqa D
    return mu**2

unit_variance_derivative

unit_variance_derivative(mu) -> np.ndarray

Compute the derivative of the unit variance with respect to mu.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
1025
1026
def unit_variance_derivative(self, mu) -> np.ndarray:  # noqa D
    return 2 * mu

deviance

deviance(y, mu, sample_weight=None) -> float

Compute the deviance.

The deviance is a weighted sum of the unit deviances. In terms of the unit log likelihood \(\ell\), it equals \(2 \sum_i [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which the variance is inversely proportional.

None
Source code in src/glum/_distribution.py
1028
1029
1030
1031
1032
1033
1034
1035
def deviance(self, y, mu, sample_weight=None) -> float:  # noqa D
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)
    sample_weight = np.ones_like(y) if sample_weight is None else sample_weight

    # NOTE: the dispersion parameter is only necessary to convey
    # type information on account of a bug in Cython

    return gamma_deviance(y, sample_weight, mu, dispersion=1.0)

unit_deviance

unit_deviance(y, mu)

Compute the unit deviance.

In terms of the unit log likelihood \(\ell\), the unit deviance is \(2 [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
1037
1038
def unit_deviance(self, y, mu):  # noqa D
    return 2 * (np.log(mu / y) + y / mu - 1)

log_likelihood

log_likelihood(y, mu, sample_weight=None, dispersion=None) -> float

Compute the log likelihood.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Sample weights.

None
dispersion (float, optional(default=None))

Dispersion parameter \(\phi\). Estimated if None.

None
Source code in src/glum/_distribution.py
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
def log_likelihood(self, y, mu, sample_weight=None, dispersion=None) -> float:
    r"""Compute the log likelihood.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Sample weights.

    dispersion : float, optional (default=None)
        Dispersion parameter $\phi$. Estimated if `None`.
    """
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)
    sample_weight = np.ones_like(y) if sample_weight is None else sample_weight

    if dispersion is None:
        dispersion = self.dispersion(y, mu, sample_weight)

    return gamma_log_likelihood(y, sample_weight, mu, float(dispersion))

dispersion

dispersion(y, mu, sample_weight=None, ddof=1, method='pearson') -> float

Estimate the dispersion parameter \(\phi\).

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inversely proportional.

None
ddof (int, optional(default=1))

Degrees of freedom consumed by the model for mu.

1
method

Whether to base the estimate on the Pearson residuals or the deviance.

'pearson'
Source code in src/glum/_distribution.py
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
def dispersion(  # noqa D
    self, y, mu, sample_weight=None, ddof=1, method="pearson"
) -> float:
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)

    if method == "pearson":
        formula = "((y - mu) ** 2) / (mu ** 2)"
        if sample_weight is None:
            return numexpr.evaluate(formula).sum() / (len(y) - ddof)
        else:
            formula = f"sample_weight * {formula}"
            return numexpr.evaluate(formula).sum() / (sample_weight.sum() - ddof)

    return super().dispersion(
        y, mu, sample_weight=sample_weight, ddof=ddof, method=method
    )

GeneralizedHyperbolicSecant

Bases: ExponentialDispersionModel

A class for the Generalized Hyperbolic Secant (GHS) distribution.

The GHS distribution models outcomes y in (-∞, +∞).

See the documentation of the superclass, ExponentialDispersionModel, for details.

lower_bound class-attribute instance-attribute

lower_bound = -np.inf

Get the lower bound of values for the EDM.

upper_bound class-attribute instance-attribute

upper_bound = np.inf

Get the upper bound of values for the EDM.

include_lower_bound class-attribute instance-attribute

include_lower_bound = False

Return whether lower_bound is allowed as a value of y.

include_upper_bound class-attribute instance-attribute

include_upper_bound = False

Return whether upper_bound is allowed as a value of y.

in_y_range

in_y_range(x) -> np.ndarray

Return True if x is in the valid range of the EDM.

Source code in src/glum/_distribution.py
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def in_y_range(self, x) -> np.ndarray:
    """Return `True` if `x` is in the valid range of the EDM."""
    if self.include_lower_bound:
        lb_op: np.ufunc = np.greater_equal
    else:
        lb_op = np.greater

    if self.include_upper_bound:
        ub_op: np.ufunc = np.less_equal
    else:
        ub_op = np.less

    return lb_op(x, self.lower_bound) & ub_op(x, self.upper_bound)

to_tweedie

to_tweedie(safe=True)

Return the Tweedie representation of a distribution if it exists.

Source code in src/glum/_distribution.py
102
103
104
105
106
107
108
def to_tweedie(self, safe=True):
    """Return the Tweedie representation of a distribution if it exists."""
    if hasattr(self, "__tweedie_repr__"):
        return self.__tweedie_repr__()
    if safe:
        raise ValueError("This distribution has no Tweedie representation.")
    return None

variance

variance(mu, dispersion=1, sample_weight=1) -> np.ndarray

Compute the variance function.

The variance of \(Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)\) takes the form \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(w_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def variance(self, mu, dispersion=1, sample_weight=1) -> np.ndarray:
    r"""Compute the variance function.

    The variance of $Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)$ takes
    the form $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the
    unit variance and $w_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance(mu) * dispersion / sample_weight

variance_derivative

variance_derivative(mu, dispersion=1, sample_weight=1)

Compute the derivative of the variance with respect to mu.

The derivative of the variance is equal to \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(ws_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def variance_derivative(self, mu, dispersion=1, sample_weight=1):
    r"""Compute the derivative of the variance with respect to `mu`.

    The derivative of the variance is equal to
    $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the unit
    variance and $ws_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance_derivative(mu) * dispersion / sample_weight

unit_deviance_derivative

unit_deviance_derivative(y, mu)

Compute the derivative of the unit deviance with respect to mu.

The derivative of the unit deviance is given by \(2 \times (\mu - y) / v(\mu)\), where \(v(\mu)\) is the unit variance.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
def unit_deviance_derivative(self, y, mu):
    r"""Compute the derivative of the unit deviance with respect to `mu`.

    The derivative of the unit deviance is given by
    $2 \times (\mu - y) / v(\mu)$, where $v(\mu)$ is the unit
    variance.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return -2 * (y - mu) / self.unit_variance(mu)

deviance

deviance(y, mu, sample_weight=1) -> float

Compute the deviance.

The deviance is a weighted sum of the unit deviances. In terms of the unit log likelihood \(\ell\), it equals \(2 \sum_i [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which the variance is inversely proportional.

1
Source code in src/glum/_distribution.py
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
def deviance(self, y, mu, sample_weight=1) -> float:
    r"""Compute the deviance.

    The deviance is a weighted sum of the unit deviances. In terms of the
    unit log likelihood $\ell$, it equals
    $2 \sum_i [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]$,
    i.e. twice the difference between the log likelihood of a saturated
    model (with one parameter per observation) and the model at hand.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which the variance is inversely proportional.
    """
    if sample_weight is None:
        return np.sum(self.unit_deviance(y, mu))
    else:
        return np.sum(self.unit_deviance(y, mu) * sample_weight)

deviance_derivative

deviance_derivative(y, mu, sample_weight=1)

Compute the derivative of the deviance with respect to mu.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples)(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
def deviance_derivative(self, y, mu, sample_weight=1):
    r"""Compute the derivative of the deviance with respect to `mu`.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,) (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return sample_weight * self.unit_deviance_derivative(y, mu)

eta_mu_deviance

eta_mu_deviance(link: Link, factor: float, cur_eta, X_dot_d, y, sample_weight) -> tuple[np.ndarray, np.ndarray, float]

Compute eta, mu and the deviance.

Returns:

Type Description
(ndarray, shape(shape[0]))

The linear predictor, eta, as cur_eta + factor * X_dot_d.

(ndarray, shape(shape[0]))

The link-function-transformed prediction, mu.

float

The deviance.

Source code in src/glum/_distribution.py
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
def eta_mu_deviance(
    self,
    link: Link,
    factor: float,
    cur_eta,
    X_dot_d,
    y,
    sample_weight,
) -> tuple[np.ndarray, np.ndarray, float]:
    """Compute `eta`, `mu` and the deviance.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The linear predictor, `eta`, as `cur_eta + factor * X_dot_d`.
    numpy.ndarray, shape (X.shape[0],)
        The link-function-transformed prediction, `mu`.
    float
        The deviance.
    """
    # eta_out and mu_out are filled inside self._eta_mu_deviance,
    # avoiding allocating new arrays for every line search loop
    eta_out = np.empty_like(cur_eta)
    mu_out = np.empty_like(cur_eta)

    deviance = self._eta_mu_deviance(
        link, factor, cur_eta, X_dot_d, y, sample_weight, eta_out, mu_out
    )

    return eta_out, mu_out, deviance

rowwise_gradient_hessian

rowwise_gradient_hessian(link: Link, coef, dispersion, X: Union[MatrixBase, StandardizedMatrix], y, sample_weight, eta, mu, offset=None)

Compute the gradient and negative Hessian of the log likelihood row-wise.

Returns:

Type Description
(ndarray, shape(shape[0]))

The gradient of the log likelihood, row-wise.

(ndarray, shape(shape[0]))

The negative Hessian of the log likelihood, row-wise.

Source code in src/glum/_distribution.py
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
def rowwise_gradient_hessian(
    self,
    link: Link,
    coef,
    dispersion,
    X: Union[MatrixBase, StandardizedMatrix],
    y,
    sample_weight,
    eta,
    mu,
    offset=None,
):
    """Compute the gradient and negative Hessian of the log likelihood row-wise.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The gradient of the log likelihood, row-wise.
    numpy.ndarray, shape (X.shape[0],)
        The negative Hessian of the log likelihood, row-wise.
    """
    gradient_rows = np.empty_like(mu)
    hessian_rows = np.empty_like(mu)

    self._rowwise_gradient_hessian(
        link, y, sample_weight, eta, mu, gradient_rows, hessian_rows
    )

    # To form the full Hessian matrix from the IRLS sample_weight:
    # hessian_matrix = _safe_sandwich_dot(X, hessian_rows, intercept=intercept)
    return gradient_rows, hessian_rows

dispersion

dispersion(y, mu, sample_weight=None, ddof=1, method='pearson') -> float

Estimate the dispersion parameter \(\phi\).

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inversely proportional.

None
ddof (int, optional(default=1))

Degrees of freedom consumed by the model for mu.

1
method

Whether to base the estimate on the Pearson residuals or the deviance.

'pearson'
Source code in src/glum/_distribution.py
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
def dispersion(self, y, mu, sample_weight=None, ddof=1, method="pearson") -> float:
    r"""Estimate the dispersion parameter $\phi$.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inversely proportional.

    ddof : int, optional (default=1)
        Degrees of freedom consumed by the model for `mu`.

    method = {'pearson', 'deviance'}, optional (default='pearson')
        Whether to base the estimate on the Pearson residuals or the deviance.
    """
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)

    if method == "pearson":
        pearson_residuals = ((y - mu) ** 2) / self.unit_variance(mu)
        if sample_weight is None:
            numerator = pearson_residuals.sum()
        else:
            numerator = np.dot(pearson_residuals, sample_weight)
    elif method == "deviance":
        numerator = self.deviance(y, mu, sample_weight)
    else:
        raise NotImplementedError(f"Method {method} hasn't been implemented.")

    if sample_weight is None:
        return numerator / (len(y) - ddof)
    else:
        return numerator / (sample_weight.sum() - ddof)

unit_variance

unit_variance(mu) -> np.ndarray

Compute the unit variance.

The unit variance, \(v(\mu) \equiv b''((b')^{-1} (\mu))\), determines the variance as a function of the mean \(\mu\) by \(\mathrm{var}(y_i) = v(\mu_i) \times \phi / w_i\). It can also be derived from the unit deviance \(d(y, \mu)\) as

\[ v(\mu) = 2 \div \frac{\partial^2 d(y, \mu)}{\partial\mu^2} \big| _{y=\mu}. \]

See also variance.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
1242
1243
def unit_variance(self, mu) -> np.ndarray:  # noqa D
    return 1 + mu**2

unit_variance_derivative

unit_variance_derivative(mu) -> np.ndarray

Compute the derivative of the unit variance with respect to mu.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
1245
1246
def unit_variance_derivative(self, mu) -> np.ndarray:  # noqa D
    return 2 * mu

unit_deviance

unit_deviance(y, mu) -> np.ndarray

Compute the unit deviance.

In terms of the unit log likelihood \(\ell\), the unit deviance is \(2 [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
1248
1249
def unit_deviance(self, y, mu) -> np.ndarray:  # noqa D
    return 2 * y * (np.arctan(y) - np.arctan(mu)) + np.log((1 + mu**2) / (1 + y**2))

InverseGaussianDistribution

Bases: ExponentialDispersionModel

Class for the inverse Gaussian distribution.

The inverse Gaussian distribution models outcomes y in (0, +∞).

See the documentation of the superclass, ExponentialDispersionModel, for details.

lower_bound class-attribute instance-attribute

lower_bound = 0

Get the lower bound of values for the EDM.

upper_bound class-attribute instance-attribute

upper_bound = np.inf

Get the upper bound of values for the EDM.

include_lower_bound class-attribute instance-attribute

include_lower_bound = False

Return whether lower_bound is allowed as a value of y.

include_upper_bound class-attribute instance-attribute

include_upper_bound = False

Return whether upper_bound is allowed as a value of y.

in_y_range

in_y_range(x) -> np.ndarray

Return True if x is in the valid range of the EDM.

Source code in src/glum/_distribution.py
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def in_y_range(self, x) -> np.ndarray:
    """Return `True` if `x` is in the valid range of the EDM."""
    if self.include_lower_bound:
        lb_op: np.ufunc = np.greater_equal
    else:
        lb_op = np.greater

    if self.include_upper_bound:
        ub_op: np.ufunc = np.less_equal
    else:
        ub_op = np.less

    return lb_op(x, self.lower_bound) & ub_op(x, self.upper_bound)

to_tweedie

to_tweedie(safe=True)

Return the Tweedie representation of a distribution if it exists.

Source code in src/glum/_distribution.py
102
103
104
105
106
107
108
def to_tweedie(self, safe=True):
    """Return the Tweedie representation of a distribution if it exists."""
    if hasattr(self, "__tweedie_repr__"):
        return self.__tweedie_repr__()
    if safe:
        raise ValueError("This distribution has no Tweedie representation.")
    return None

variance

variance(mu, dispersion=1, sample_weight=1) -> np.ndarray

Compute the variance function.

The variance of \(Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)\) takes the form \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(w_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def variance(self, mu, dispersion=1, sample_weight=1) -> np.ndarray:
    r"""Compute the variance function.

    The variance of $Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)$ takes
    the form $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the
    unit variance and $w_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance(mu) * dispersion / sample_weight

variance_derivative

variance_derivative(mu, dispersion=1, sample_weight=1)

Compute the derivative of the variance with respect to mu.

The derivative of the variance is equal to \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(ws_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def variance_derivative(self, mu, dispersion=1, sample_weight=1):
    r"""Compute the derivative of the variance with respect to `mu`.

    The derivative of the variance is equal to
    $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the unit
    variance and $ws_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance_derivative(mu) * dispersion / sample_weight

unit_deviance_derivative

unit_deviance_derivative(y, mu)

Compute the derivative of the unit deviance with respect to mu.

The derivative of the unit deviance is given by \(2 \times (\mu - y) / v(\mu)\), where \(v(\mu)\) is the unit variance.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
def unit_deviance_derivative(self, y, mu):
    r"""Compute the derivative of the unit deviance with respect to `mu`.

    The derivative of the unit deviance is given by
    $2 \times (\mu - y) / v(\mu)$, where $v(\mu)$ is the unit
    variance.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return -2 * (y - mu) / self.unit_variance(mu)

deviance_derivative

deviance_derivative(y, mu, sample_weight=1)

Compute the derivative of the deviance with respect to mu.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples)(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
def deviance_derivative(self, y, mu, sample_weight=1):
    r"""Compute the derivative of the deviance with respect to `mu`.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,) (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return sample_weight * self.unit_deviance_derivative(y, mu)

eta_mu_deviance

eta_mu_deviance(link: Link, factor: float, cur_eta, X_dot_d, y, sample_weight) -> tuple[np.ndarray, np.ndarray, float]

Compute eta, mu and the deviance.

Returns:

Type Description
(ndarray, shape(shape[0]))

The linear predictor, eta, as cur_eta + factor * X_dot_d.

(ndarray, shape(shape[0]))

The link-function-transformed prediction, mu.

float

The deviance.

Source code in src/glum/_distribution.py
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
def eta_mu_deviance(
    self,
    link: Link,
    factor: float,
    cur_eta,
    X_dot_d,
    y,
    sample_weight,
) -> tuple[np.ndarray, np.ndarray, float]:
    """Compute `eta`, `mu` and the deviance.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The linear predictor, `eta`, as `cur_eta + factor * X_dot_d`.
    numpy.ndarray, shape (X.shape[0],)
        The link-function-transformed prediction, `mu`.
    float
        The deviance.
    """
    # eta_out and mu_out are filled inside self._eta_mu_deviance,
    # avoiding allocating new arrays for every line search loop
    eta_out = np.empty_like(cur_eta)
    mu_out = np.empty_like(cur_eta)

    deviance = self._eta_mu_deviance(
        link, factor, cur_eta, X_dot_d, y, sample_weight, eta_out, mu_out
    )

    return eta_out, mu_out, deviance

rowwise_gradient_hessian

rowwise_gradient_hessian(link: Link, coef, dispersion, X: Union[MatrixBase, StandardizedMatrix], y, sample_weight, eta, mu, offset=None)

Compute the gradient and negative Hessian of the log likelihood row-wise.

Returns:

Type Description
(ndarray, shape(shape[0]))

The gradient of the log likelihood, row-wise.

(ndarray, shape(shape[0]))

The negative Hessian of the log likelihood, row-wise.

Source code in src/glum/_distribution.py
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
def rowwise_gradient_hessian(
    self,
    link: Link,
    coef,
    dispersion,
    X: Union[MatrixBase, StandardizedMatrix],
    y,
    sample_weight,
    eta,
    mu,
    offset=None,
):
    """Compute the gradient and negative Hessian of the log likelihood row-wise.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The gradient of the log likelihood, row-wise.
    numpy.ndarray, shape (X.shape[0],)
        The negative Hessian of the log likelihood, row-wise.
    """
    gradient_rows = np.empty_like(mu)
    hessian_rows = np.empty_like(mu)

    self._rowwise_gradient_hessian(
        link, y, sample_weight, eta, mu, gradient_rows, hessian_rows
    )

    # To form the full Hessian matrix from the IRLS sample_weight:
    # hessian_matrix = _safe_sandwich_dot(X, hessian_rows, intercept=intercept)
    return gradient_rows, hessian_rows

unit_variance

unit_variance(mu) -> np.ndarray

Compute the unit variance.

The unit variance, \(v(\mu) \equiv b''((b')^{-1} (\mu))\), determines the variance as a function of the mean \(\mu\) by \(\mathrm{var}(y_i) = v(\mu_i) \times \phi / w_i\). It can also be derived from the unit deviance \(d(y, \mu)\) as

\[ v(\mu) = 2 \div \frac{\partial^2 d(y, \mu)}{\partial\mu^2} \big| _{y=\mu}. \]

See also variance.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
1135
1136
def unit_variance(self, mu) -> np.ndarray:  # noqa D
    return mu**3

unit_variance_derivative

unit_variance_derivative(mu) -> np.ndarray

Compute the derivative of the unit variance with respect to mu.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
1138
1139
def unit_variance_derivative(self, mu) -> np.ndarray:  # noqa D
    return 3 * (mu**2)

deviance

deviance(y, mu, sample_weight=None) -> float

Compute the deviance.

The deviance is a weighted sum of the unit deviances. In terms of the unit log likelihood \(\ell\), it equals \(2 \sum_i [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which the variance is inversely proportional.

None
Source code in src/glum/_distribution.py
1141
1142
1143
1144
1145
def deviance(self, y, mu, sample_weight=None) -> float:  # noqa D
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)
    sample_weight = np.ones_like(y) if sample_weight is None else sample_weight

    return inv_gaussian_deviance(y, sample_weight, mu, dispersion=1.0)

unit_deviance

unit_deviance(y, mu)

Compute the unit deviance.

In terms of the unit log likelihood \(\ell\), the unit deviance is \(2 [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
1147
1148
def unit_deviance(self, y, mu):  # noqa D
    return numexpr.evaluate("y / (mu**2) + 1 / y - 2 / mu")

log_likelihood

log_likelihood(y, mu, sample_weight=None, dispersion=None) -> float

Compute the log likelihood.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Sample weights.

None
dispersion (float, optional(default=None))

Dispersion parameter \(\phi\). Estimated if None.

None
Source code in src/glum/_distribution.py
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
def log_likelihood(self, y, mu, sample_weight=None, dispersion=None) -> float:
    r"""Compute the log likelihood.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Sample weights.

    dispersion : float, optional (default=None)
        Dispersion parameter $\phi$. Estimated if `None`.
    """
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)
    sample_weight = np.ones_like(y) if sample_weight is None else sample_weight

    if dispersion is None:
        dispersion = self.dispersion(y, mu, sample_weight)

    return inv_gaussian_log_likelihood(y, sample_weight, mu, float(dispersion))

dispersion

dispersion(y, mu, sample_weight=None, ddof=1, method='pearson') -> float

Estimate the dispersion parameter \(\phi\).

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inversely proportional.

None
ddof (int, optional(default=1))

Degrees of freedom consumed by the model for mu.

1
method

Whether to base the estimate on the Pearson residuals or the deviance.

'pearson'
Source code in src/glum/_distribution.py
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
def dispersion(  # noqa D
    self, y, mu, sample_weight=None, ddof=1, method="pearson"
) -> float:
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)

    if method == "pearson":
        formula = "((y - mu) ** 2) / (mu ** 3)"
        if sample_weight is None:
            return numexpr.evaluate(formula).sum() / (len(y) - ddof)
        else:
            formula = f"sample_weight * {formula}"
            return numexpr.evaluate(formula).sum() / (sample_weight.sum() - ddof)

    return super().dispersion(
        y, mu, sample_weight=sample_weight, ddof=ddof, method=method
    )

NegativeBinomialDistribution

NegativeBinomialDistribution(theta=1.0)

Bases: ExponentialDispersionModel

A class for the Negative Binomial distribution.

A negative binomial distribution with mean \(\mu = \mathrm{E}(Y)\) is uniquely defined by its mean-variance relationship \(\mathrm{var}(Y) \propto \mu + \theta * \mu^2\).

Parameters:

Name Type Description Default
theta (float, optional(default=1.0))

The dispersion parameter from the unit_variance \(v(\mu) = \mu + \theta * \mu^2\). For \(\theta <= 0\), no distribution exists.

1.0
References

For the log-likelihood and deviance:

Source code in src/glum/_distribution.py
1375
1376
1377
def __init__(self, theta=1.0):
    # validate power and set _upper_bound, _include_upper_bound attrs
    self.theta = theta

lower_bound class-attribute instance-attribute

lower_bound = 0

Get the lower bound of values for the EDM.

upper_bound class-attribute instance-attribute

upper_bound = np.inf

Get the upper bound of values for the EDM.

include_lower_bound class-attribute instance-attribute

include_lower_bound = True

Return whether lower_bound is allowed as a value of y.

include_upper_bound class-attribute instance-attribute

include_upper_bound = False

Return whether upper_bound is allowed as a value of y.

theta property writable

theta

Return the negative binomial theta parameter.

in_y_range

in_y_range(x) -> np.ndarray

Return True if x is in the valid range of the EDM.

Source code in src/glum/_distribution.py
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def in_y_range(self, x) -> np.ndarray:
    """Return `True` if `x` is in the valid range of the EDM."""
    if self.include_lower_bound:
        lb_op: np.ufunc = np.greater_equal
    else:
        lb_op = np.greater

    if self.include_upper_bound:
        ub_op: np.ufunc = np.less_equal
    else:
        ub_op = np.less

    return lb_op(x, self.lower_bound) & ub_op(x, self.upper_bound)

to_tweedie

to_tweedie(safe=True)

Return the Tweedie representation of a distribution if it exists.

Source code in src/glum/_distribution.py
102
103
104
105
106
107
108
def to_tweedie(self, safe=True):
    """Return the Tweedie representation of a distribution if it exists."""
    if hasattr(self, "__tweedie_repr__"):
        return self.__tweedie_repr__()
    if safe:
        raise ValueError("This distribution has no Tweedie representation.")
    return None

variance

variance(mu, dispersion=1, sample_weight=1) -> np.ndarray

Compute the variance function.

The variance of \(Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)\) takes the form \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(w_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def variance(self, mu, dispersion=1, sample_weight=1) -> np.ndarray:
    r"""Compute the variance function.

    The variance of $Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)$ takes
    the form $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the
    unit variance and $w_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance(mu) * dispersion / sample_weight

variance_derivative

variance_derivative(mu, dispersion=1, sample_weight=1)

Compute the derivative of the variance with respect to mu.

The derivative of the variance is equal to \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(ws_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def variance_derivative(self, mu, dispersion=1, sample_weight=1):
    r"""Compute the derivative of the variance with respect to `mu`.

    The derivative of the variance is equal to
    $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the unit
    variance and $ws_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance_derivative(mu) * dispersion / sample_weight

unit_deviance_derivative

unit_deviance_derivative(y, mu)

Compute the derivative of the unit deviance with respect to mu.

The derivative of the unit deviance is given by \(2 \times (\mu - y) / v(\mu)\), where \(v(\mu)\) is the unit variance.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
def unit_deviance_derivative(self, y, mu):
    r"""Compute the derivative of the unit deviance with respect to `mu`.

    The derivative of the unit deviance is given by
    $2 \times (\mu - y) / v(\mu)$, where $v(\mu)$ is the unit
    variance.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return -2 * (y - mu) / self.unit_variance(mu)

deviance_derivative

deviance_derivative(y, mu, sample_weight=1)

Compute the derivative of the deviance with respect to mu.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples)(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
def deviance_derivative(self, y, mu, sample_weight=1):
    r"""Compute the derivative of the deviance with respect to `mu`.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,) (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return sample_weight * self.unit_deviance_derivative(y, mu)

eta_mu_deviance

eta_mu_deviance(link: Link, factor: float, cur_eta, X_dot_d, y, sample_weight) -> tuple[np.ndarray, np.ndarray, float]

Compute eta, mu and the deviance.

Returns:

Type Description
(ndarray, shape(shape[0]))

The linear predictor, eta, as cur_eta + factor * X_dot_d.

(ndarray, shape(shape[0]))

The link-function-transformed prediction, mu.

float

The deviance.

Source code in src/glum/_distribution.py
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
def eta_mu_deviance(
    self,
    link: Link,
    factor: float,
    cur_eta,
    X_dot_d,
    y,
    sample_weight,
) -> tuple[np.ndarray, np.ndarray, float]:
    """Compute `eta`, `mu` and the deviance.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The linear predictor, `eta`, as `cur_eta + factor * X_dot_d`.
    numpy.ndarray, shape (X.shape[0],)
        The link-function-transformed prediction, `mu`.
    float
        The deviance.
    """
    # eta_out and mu_out are filled inside self._eta_mu_deviance,
    # avoiding allocating new arrays for every line search loop
    eta_out = np.empty_like(cur_eta)
    mu_out = np.empty_like(cur_eta)

    deviance = self._eta_mu_deviance(
        link, factor, cur_eta, X_dot_d, y, sample_weight, eta_out, mu_out
    )

    return eta_out, mu_out, deviance

rowwise_gradient_hessian

rowwise_gradient_hessian(link: Link, coef, dispersion, X: Union[MatrixBase, StandardizedMatrix], y, sample_weight, eta, mu, offset=None)

Compute the gradient and negative Hessian of the log likelihood row-wise.

Returns:

Type Description
(ndarray, shape(shape[0]))

The gradient of the log likelihood, row-wise.

(ndarray, shape(shape[0]))

The negative Hessian of the log likelihood, row-wise.

Source code in src/glum/_distribution.py
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
def rowwise_gradient_hessian(
    self,
    link: Link,
    coef,
    dispersion,
    X: Union[MatrixBase, StandardizedMatrix],
    y,
    sample_weight,
    eta,
    mu,
    offset=None,
):
    """Compute the gradient and negative Hessian of the log likelihood row-wise.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The gradient of the log likelihood, row-wise.
    numpy.ndarray, shape (X.shape[0],)
        The negative Hessian of the log likelihood, row-wise.
    """
    gradient_rows = np.empty_like(mu)
    hessian_rows = np.empty_like(mu)

    self._rowwise_gradient_hessian(
        link, y, sample_weight, eta, mu, gradient_rows, hessian_rows
    )

    # To form the full Hessian matrix from the IRLS sample_weight:
    # hessian_matrix = _safe_sandwich_dot(X, hessian_rows, intercept=intercept)
    return gradient_rows, hessian_rows

unit_variance

unit_variance(mu)

Compute the unit variance.

The unit variance, \(v(\mu) \equiv b''((b')^{-1} (\mu))\), determines the variance as a function of the mean \(\mu\) by \(\mathrm{var}(y_i) = v(\mu_i) \times \phi / w_i\). It can also be derived from the unit deviance \(d(y, \mu)\) as

\[ v(\mu) = 2 \div \frac{\partial^2 d(y, \mu)}{\partial\mu^2} \big| _{y=\mu}. \]

See also variance.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
1399
1400
def unit_variance(self, mu):  # noqa D
    return mu + self.theta * mu**2

unit_variance_derivative

unit_variance_derivative(mu)

Compute the derivative of the unit variance with respect to mu.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
1402
1403
def unit_variance_derivative(self, mu):  # noqa D
    return 1 + 2 * self.theta * mu

deviance

deviance(y, mu, sample_weight=None) -> float

Compute the deviance.

The deviance is a weighted sum of the unit deviances. In terms of the unit log likelihood \(\ell\), it equals \(2 \sum_i [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which the variance is inversely proportional.

None
Source code in src/glum/_distribution.py
1405
1406
1407
1408
1409
1410
def deviance(self, y, mu, sample_weight=None) -> float:  # noqa D
    theta = self.theta
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)
    sample_weight = np.ones_like(y) if sample_weight is None else sample_weight

    return negative_binomial_deviance(y, sample_weight, mu, theta=float(theta))

unit_deviance

unit_deviance(y, mu)

Compute the unit deviance.

In terms of the unit log likelihood \(\ell\), the unit deviance is \(2 [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
1412
1413
1414
1415
1416
1417
def unit_deviance(self, y, mu):  # noqa D
    theta = self.theta

    r = 1.0 / theta

    return 2 * (special.xlogy(y, y / mu) - (y + r) * np.log((y + r) / (mu + r)))

log_likelihood

log_likelihood(y, mu, sample_weight=None, dispersion=1) -> float

Compute the log likelihood.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Sample weights.

None
dispersion (float, optional(default=1.0))

Ignored.

1
Source code in src/glum/_distribution.py
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
def log_likelihood(self, y, mu, sample_weight=None, dispersion=1) -> float:
    r"""Compute the log likelihood.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Sample weights.

    dispersion : float, optional (default=1.0)
        Ignored.
    """
    theta = self.theta
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)
    sample_weight = np.ones_like(y) if sample_weight is None else sample_weight

    return negative_binomial_log_likelihood(y, sample_weight, mu, float(theta), 1.0)

dispersion

dispersion(y, mu, sample_weight=None, ddof=1, method='pearson') -> float

Estimate the dispersion parameter \(\phi\).

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inversely proportional.

None
ddof (int, optional(default=1))

Degrees of freedom consumed by the model for mu.

1
method

Whether to base the estimate on the Pearson residuals or the deviance.

'pearson'
Source code in src/glum/_distribution.py
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
def dispersion(  # noqa D
    self, y, mu, sample_weight=None, ddof=1, method="pearson"
) -> float:
    theta = self.theta  # noqa: F841
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)

    if method == "pearson":
        formula = "((y - mu) ** 2) / (mu + theta * mu ** 2)"
        if sample_weight is None:
            return numexpr.evaluate(formula).sum() / (len(y) - ddof)
        else:
            formula = f"sample_weight * {formula}"
            return numexpr.evaluate(formula).sum() / (sample_weight.sum() - ddof)

    return super().dispersion(
        y, mu, sample_weight=sample_weight, ddof=ddof, method=method
    )

NormalDistribution

Bases: ExponentialDispersionModel

Class for the normal (a.k.a. Gaussian) distribution.

The normal distribution models outcomes y in (-∞, +∞).

See the documentation of the superclass, ExponentialDispersionModel, for details.

lower_bound class-attribute instance-attribute

lower_bound = -np.inf

Get the lower bound of values for the EDM.

upper_bound class-attribute instance-attribute

upper_bound = np.inf

Get the upper bound of values for the EDM.

include_lower_bound class-attribute instance-attribute

include_lower_bound = False

Return whether lower_bound is allowed as a value of y.

include_upper_bound class-attribute instance-attribute

include_upper_bound = False

Return whether upper_bound is allowed as a value of y.

in_y_range

in_y_range(x) -> np.ndarray

Return True if x is in the valid range of the EDM.

Source code in src/glum/_distribution.py
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def in_y_range(self, x) -> np.ndarray:
    """Return `True` if `x` is in the valid range of the EDM."""
    if self.include_lower_bound:
        lb_op: np.ufunc = np.greater_equal
    else:
        lb_op = np.greater

    if self.include_upper_bound:
        ub_op: np.ufunc = np.less_equal
    else:
        ub_op = np.less

    return lb_op(x, self.lower_bound) & ub_op(x, self.upper_bound)

to_tweedie

to_tweedie(safe=True)

Return the Tweedie representation of a distribution if it exists.

Source code in src/glum/_distribution.py
102
103
104
105
106
107
108
def to_tweedie(self, safe=True):
    """Return the Tweedie representation of a distribution if it exists."""
    if hasattr(self, "__tweedie_repr__"):
        return self.__tweedie_repr__()
    if safe:
        raise ValueError("This distribution has no Tweedie representation.")
    return None

variance

variance(mu, dispersion=1, sample_weight=1) -> np.ndarray

Compute the variance function.

The variance of \(Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)\) takes the form \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(w_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def variance(self, mu, dispersion=1, sample_weight=1) -> np.ndarray:
    r"""Compute the variance function.

    The variance of $Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)$ takes
    the form $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the
    unit variance and $w_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance(mu) * dispersion / sample_weight

variance_derivative

variance_derivative(mu, dispersion=1, sample_weight=1)

Compute the derivative of the variance with respect to mu.

The derivative of the variance is equal to \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(ws_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def variance_derivative(self, mu, dispersion=1, sample_weight=1):
    r"""Compute the derivative of the variance with respect to `mu`.

    The derivative of the variance is equal to
    $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the unit
    variance and $ws_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance_derivative(mu) * dispersion / sample_weight

unit_deviance_derivative

unit_deviance_derivative(y, mu)

Compute the derivative of the unit deviance with respect to mu.

The derivative of the unit deviance is given by \(2 \times (\mu - y) / v(\mu)\), where \(v(\mu)\) is the unit variance.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
def unit_deviance_derivative(self, y, mu):
    r"""Compute the derivative of the unit deviance with respect to `mu`.

    The derivative of the unit deviance is given by
    $2 \times (\mu - y) / v(\mu)$, where $v(\mu)$ is the unit
    variance.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return -2 * (y - mu) / self.unit_variance(mu)

deviance_derivative

deviance_derivative(y, mu, sample_weight=1)

Compute the derivative of the deviance with respect to mu.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples)(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
def deviance_derivative(self, y, mu, sample_weight=1):
    r"""Compute the derivative of the deviance with respect to `mu`.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,) (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return sample_weight * self.unit_deviance_derivative(y, mu)

eta_mu_deviance

eta_mu_deviance(link: Link, factor: float, cur_eta, X_dot_d, y, sample_weight) -> tuple[np.ndarray, np.ndarray, float]

Compute eta, mu and the deviance.

Returns:

Type Description
(ndarray, shape(shape[0]))

The linear predictor, eta, as cur_eta + factor * X_dot_d.

(ndarray, shape(shape[0]))

The link-function-transformed prediction, mu.

float

The deviance.

Source code in src/glum/_distribution.py
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
def eta_mu_deviance(
    self,
    link: Link,
    factor: float,
    cur_eta,
    X_dot_d,
    y,
    sample_weight,
) -> tuple[np.ndarray, np.ndarray, float]:
    """Compute `eta`, `mu` and the deviance.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The linear predictor, `eta`, as `cur_eta + factor * X_dot_d`.
    numpy.ndarray, shape (X.shape[0],)
        The link-function-transformed prediction, `mu`.
    float
        The deviance.
    """
    # eta_out and mu_out are filled inside self._eta_mu_deviance,
    # avoiding allocating new arrays for every line search loop
    eta_out = np.empty_like(cur_eta)
    mu_out = np.empty_like(cur_eta)

    deviance = self._eta_mu_deviance(
        link, factor, cur_eta, X_dot_d, y, sample_weight, eta_out, mu_out
    )

    return eta_out, mu_out, deviance

rowwise_gradient_hessian

rowwise_gradient_hessian(link: Link, coef, dispersion, X: Union[MatrixBase, StandardizedMatrix], y, sample_weight, eta, mu, offset=None)

Compute the gradient and negative Hessian of the log likelihood row-wise.

Returns:

Type Description
(ndarray, shape(shape[0]))

The gradient of the log likelihood, row-wise.

(ndarray, shape(shape[0]))

The negative Hessian of the log likelihood, row-wise.

Source code in src/glum/_distribution.py
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
def rowwise_gradient_hessian(
    self,
    link: Link,
    coef,
    dispersion,
    X: Union[MatrixBase, StandardizedMatrix],
    y,
    sample_weight,
    eta,
    mu,
    offset=None,
):
    """Compute the gradient and negative Hessian of the log likelihood row-wise.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The gradient of the log likelihood, row-wise.
    numpy.ndarray, shape (X.shape[0],)
        The negative Hessian of the log likelihood, row-wise.
    """
    gradient_rows = np.empty_like(mu)
    hessian_rows = np.empty_like(mu)

    self._rowwise_gradient_hessian(
        link, y, sample_weight, eta, mu, gradient_rows, hessian_rows
    )

    # To form the full Hessian matrix from the IRLS sample_weight:
    # hessian_matrix = _safe_sandwich_dot(X, hessian_rows, intercept=intercept)
    return gradient_rows, hessian_rows

unit_variance

unit_variance(mu) -> np.ndarray

Compute the unit variance.

The unit variance, \(v(\mu) \equiv b''((b')^{-1} (\mu))\), determines the variance as a function of the mean \(\mu\) by \(\mathrm{var}(y_i) = v(\mu_i) \times \phi / w_i\). It can also be derived from the unit deviance \(d(y, \mu)\) as

\[ v(\mu) = 2 \div \frac{\partial^2 d(y, \mu)}{\partial\mu^2} \big| _{y=\mu}. \]

See also variance.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
796
797
def unit_variance(self, mu) -> np.ndarray:  # noqa D
    return 1 if np.isscalar(mu) else np.ones_like(mu)  # type: ignore

unit_variance_derivative

unit_variance_derivative(mu) -> np.ndarray

Compute the derivative of the unit variance with respect to mu.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
799
800
def unit_variance_derivative(self, mu) -> np.ndarray:  # noqa D
    return 0 if np.isscalar(mu) else np.zeros_like(mu)  # type: ignore

deviance

deviance(y, mu, sample_weight=None) -> float

Compute the deviance.

The deviance is a weighted sum of the unit deviances. In terms of the unit log likelihood \(\ell\), it equals \(2 \sum_i [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which the variance is inversely proportional.

None
Source code in src/glum/_distribution.py
802
803
804
805
806
807
808
809
def deviance(self, y, mu, sample_weight=None) -> float:  # noqa D
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)
    sample_weight = np.ones_like(y) if sample_weight is None else sample_weight

    # NOTE: the dispersion parameter is only necessary to convey
    # type information on account of a bug in Cython

    return normal_deviance(y, sample_weight, mu, dispersion=1.0)

unit_deviance

unit_deviance(y, mu)

Compute the unit deviance.

In terms of the unit log likelihood \(\ell\), the unit deviance is \(2 [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
811
812
def unit_deviance(self, y, mu):  # noqa D
    return (y - mu) ** 2

log_likelihood

log_likelihood(y, mu, sample_weight=None, dispersion=None) -> float

Compute the log likelihood.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Sample weights.

None
dispersion (float, optional(default=None))

Dispersion parameter \(\phi\). Estimated if None.

None
Source code in src/glum/_distribution.py
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
def log_likelihood(self, y, mu, sample_weight=None, dispersion=None) -> float:
    r"""Compute the log likelihood.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Sample weights.

    dispersion : float, optional (default=None)
        Dispersion parameter $\phi$. Estimated if `None`.
    """
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)
    sample_weight = np.ones_like(y) if sample_weight is None else sample_weight

    if dispersion is None:
        dispersion = self.dispersion(y, mu, sample_weight)

    return normal_log_likelihood(y, sample_weight, mu, float(dispersion))

dispersion

dispersion(y, mu, sample_weight=None, ddof=1, method='pearson') -> float

Estimate the dispersion parameter \(\phi\).

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inversely proportional.

None
ddof (int, optional(default=1))

Degrees of freedom consumed by the model for mu.

1
method

Whether to base the estimate on the Pearson residuals or the deviance.

'pearson'
Source code in src/glum/_distribution.py
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
def dispersion(  # noqa D
    self, y, mu, sample_weight=None, ddof=1, method="pearson"
) -> float:
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)

    if method == "pearson":
        formula = "(y - mu) ** 2"
        if sample_weight is None:
            return numexpr.evaluate(formula).sum() / (len(y) - ddof)
        else:
            formula = f"sample_weight * {formula}"
            return numexpr.evaluate(formula).sum() / (sample_weight.sum() - ddof)

    return super().dispersion(
        y, mu, sample_weight=sample_weight, ddof=ddof, method=method
    )

PoissonDistribution

Bases: ExponentialDispersionModel

Class for the scaled Poisson distribution.

The Poisson distribution models discrete outcomes y in [0, +∞).

See the documentation of the superclass, ExponentialDispersionModel, for details.

lower_bound class-attribute instance-attribute

lower_bound = 0

Get the lower bound of values for the EDM.

upper_bound class-attribute instance-attribute

upper_bound = np.inf

Get the upper bound of values for the EDM.

include_lower_bound class-attribute instance-attribute

include_lower_bound = True

Return whether lower_bound is allowed as a value of y.

include_upper_bound class-attribute instance-attribute

include_upper_bound = False

Return whether upper_bound is allowed as a value of y.

in_y_range

in_y_range(x) -> np.ndarray

Return True if x is in the valid range of the EDM.

Source code in src/glum/_distribution.py
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def in_y_range(self, x) -> np.ndarray:
    """Return `True` if `x` is in the valid range of the EDM."""
    if self.include_lower_bound:
        lb_op: np.ufunc = np.greater_equal
    else:
        lb_op = np.greater

    if self.include_upper_bound:
        ub_op: np.ufunc = np.less_equal
    else:
        ub_op = np.less

    return lb_op(x, self.lower_bound) & ub_op(x, self.upper_bound)

to_tweedie

to_tweedie(safe=True)

Return the Tweedie representation of a distribution if it exists.

Source code in src/glum/_distribution.py
102
103
104
105
106
107
108
def to_tweedie(self, safe=True):
    """Return the Tweedie representation of a distribution if it exists."""
    if hasattr(self, "__tweedie_repr__"):
        return self.__tweedie_repr__()
    if safe:
        raise ValueError("This distribution has no Tweedie representation.")
    return None

variance

variance(mu, dispersion=1, sample_weight=1) -> np.ndarray

Compute the variance function.

The variance of \(Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)\) takes the form \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(w_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def variance(self, mu, dispersion=1, sample_weight=1) -> np.ndarray:
    r"""Compute the variance function.

    The variance of $Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)$ takes
    the form $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the
    unit variance and $w_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance(mu) * dispersion / sample_weight

variance_derivative

variance_derivative(mu, dispersion=1, sample_weight=1)

Compute the derivative of the variance with respect to mu.

The derivative of the variance is equal to \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(ws_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def variance_derivative(self, mu, dispersion=1, sample_weight=1):
    r"""Compute the derivative of the variance with respect to `mu`.

    The derivative of the variance is equal to
    $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the unit
    variance and $ws_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance_derivative(mu) * dispersion / sample_weight

unit_deviance_derivative

unit_deviance_derivative(y, mu)

Compute the derivative of the unit deviance with respect to mu.

The derivative of the unit deviance is given by \(2 \times (\mu - y) / v(\mu)\), where \(v(\mu)\) is the unit variance.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
def unit_deviance_derivative(self, y, mu):
    r"""Compute the derivative of the unit deviance with respect to `mu`.

    The derivative of the unit deviance is given by
    $2 \times (\mu - y) / v(\mu)$, where $v(\mu)$ is the unit
    variance.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return -2 * (y - mu) / self.unit_variance(mu)

deviance_derivative

deviance_derivative(y, mu, sample_weight=1)

Compute the derivative of the deviance with respect to mu.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples)(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
def deviance_derivative(self, y, mu, sample_weight=1):
    r"""Compute the derivative of the deviance with respect to `mu`.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,) (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return sample_weight * self.unit_deviance_derivative(y, mu)

eta_mu_deviance

eta_mu_deviance(link: Link, factor: float, cur_eta, X_dot_d, y, sample_weight) -> tuple[np.ndarray, np.ndarray, float]

Compute eta, mu and the deviance.

Returns:

Type Description
(ndarray, shape(shape[0]))

The linear predictor, eta, as cur_eta + factor * X_dot_d.

(ndarray, shape(shape[0]))

The link-function-transformed prediction, mu.

float

The deviance.

Source code in src/glum/_distribution.py
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
def eta_mu_deviance(
    self,
    link: Link,
    factor: float,
    cur_eta,
    X_dot_d,
    y,
    sample_weight,
) -> tuple[np.ndarray, np.ndarray, float]:
    """Compute `eta`, `mu` and the deviance.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The linear predictor, `eta`, as `cur_eta + factor * X_dot_d`.
    numpy.ndarray, shape (X.shape[0],)
        The link-function-transformed prediction, `mu`.
    float
        The deviance.
    """
    # eta_out and mu_out are filled inside self._eta_mu_deviance,
    # avoiding allocating new arrays for every line search loop
    eta_out = np.empty_like(cur_eta)
    mu_out = np.empty_like(cur_eta)

    deviance = self._eta_mu_deviance(
        link, factor, cur_eta, X_dot_d, y, sample_weight, eta_out, mu_out
    )

    return eta_out, mu_out, deviance

rowwise_gradient_hessian

rowwise_gradient_hessian(link: Link, coef, dispersion, X: Union[MatrixBase, StandardizedMatrix], y, sample_weight, eta, mu, offset=None)

Compute the gradient and negative Hessian of the log likelihood row-wise.

Returns:

Type Description
(ndarray, shape(shape[0]))

The gradient of the log likelihood, row-wise.

(ndarray, shape(shape[0]))

The negative Hessian of the log likelihood, row-wise.

Source code in src/glum/_distribution.py
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
def rowwise_gradient_hessian(
    self,
    link: Link,
    coef,
    dispersion,
    X: Union[MatrixBase, StandardizedMatrix],
    y,
    sample_weight,
    eta,
    mu,
    offset=None,
):
    """Compute the gradient and negative Hessian of the log likelihood row-wise.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The gradient of the log likelihood, row-wise.
    numpy.ndarray, shape (X.shape[0],)
        The negative Hessian of the log likelihood, row-wise.
    """
    gradient_rows = np.empty_like(mu)
    hessian_rows = np.empty_like(mu)

    self._rowwise_gradient_hessian(
        link, y, sample_weight, eta, mu, gradient_rows, hessian_rows
    )

    # To form the full Hessian matrix from the IRLS sample_weight:
    # hessian_matrix = _safe_sandwich_dot(X, hessian_rows, intercept=intercept)
    return gradient_rows, hessian_rows

unit_variance

unit_variance(mu) -> np.ndarray

Compute the unit variance.

The unit variance, \(v(\mu) \equiv b''((b')^{-1} (\mu))\), determines the variance as a function of the mean \(\mu\) by \(\mathrm{var}(y_i) = v(\mu_i) \times \phi / w_i\). It can also be derived from the unit deviance \(d(y, \mu)\) as

\[ v(\mu) = 2 \div \frac{\partial^2 d(y, \mu)}{\partial\mu^2} \big| _{y=\mu}. \]

See also variance.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
909
910
def unit_variance(self, mu) -> np.ndarray:  # noqa D
    return mu

unit_variance_derivative

unit_variance_derivative(mu) -> np.ndarray

Compute the derivative of the unit variance with respect to mu.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
912
913
def unit_variance_derivative(self, mu) -> np.ndarray:  # noqa D
    return 1.0 if np.isscalar(mu) else np.ones_like(mu)  # type: ignore

deviance

deviance(y, mu, sample_weight=None) -> float

Compute the deviance.

The deviance is a weighted sum of the unit deviances. In terms of the unit log likelihood \(\ell\), it equals \(2 \sum_i [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which the variance is inversely proportional.

None
Source code in src/glum/_distribution.py
915
916
917
918
919
920
921
922
def deviance(self, y, mu, sample_weight=None) -> float:  # noqa D
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)
    sample_weight = np.ones_like(y) if sample_weight is None else sample_weight

    # NOTE: the dispersion parameter is only necessary to convey
    # type information on account of a bug in Cython

    return poisson_deviance(y, sample_weight, mu, dispersion=1.0)

unit_deviance

unit_deviance(y, mu)

Compute the unit deviance.

In terms of the unit log likelihood \(\ell\), the unit deviance is \(2 [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
924
925
def unit_deviance(self, y, mu):  # noqa D
    return 2 * (special.xlogy(y, y / mu) - y + mu)

log_likelihood

log_likelihood(y, mu, sample_weight=None, dispersion=None) -> float

Compute the log likelihood.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Sample weights.

None
dispersion (float, optional(default=None))

Dispersion parameter \(\phi\). Estimated if None.

None
Source code in src/glum/_distribution.py
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
def log_likelihood(self, y, mu, sample_weight=None, dispersion=None) -> float:
    r"""Compute the log likelihood.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Sample weights.

    dispersion : float, optional (default=None)
        Dispersion parameter $\phi$. Estimated if `None`.
    """
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)
    sample_weight = np.ones_like(y) if sample_weight is None else sample_weight

    # NOTE: the dispersion parameter is only necessary to convey
    # type information on account of a bug in Cython

    return poisson_log_likelihood(y, sample_weight, mu, 1.0)

dispersion

dispersion(y, mu, sample_weight=None, ddof=1, method='pearson') -> float

Estimate the dispersion parameter \(\phi\).

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inversely proportional.

None
ddof (int, optional(default=1))

Degrees of freedom consumed by the model for mu.

1
method

Whether to base the estimate on the Pearson residuals or the deviance.

'pearson'
Source code in src/glum/_distribution.py
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
def dispersion(  # noqa D
    self, y, mu, sample_weight=None, ddof=1, method="pearson"
) -> float:
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)

    if method == "pearson":
        formula = "((y - mu) ** 2) / mu"
        if sample_weight is None:
            return numexpr.evaluate(formula).sum() / (len(y) - ddof)
        else:
            formula = f"sample_weight * {formula}"
            return numexpr.evaluate(formula).sum() / (sample_weight.sum() - ddof)

    return super().dispersion(
        y, mu, sample_weight=sample_weight, ddof=ddof, method=method
    )

TweedieDistribution

TweedieDistribution(power=0)

Bases: ExponentialDispersionModel

A class for the Tweedie distribution.

A Tweedie distribution with mean \(\mu = \mathrm{E}(Y)\) is uniquely defined by its mean-variance relationship \(\mathrm{var}(Y) \propto \mu^{\mathrm{p}}\).

Special cases are:

Power Distribution Support
0 Normal (-∞, +∞)
1 Poisson [0, +∞)
(1, 2) Compound Poisson [0, +∞)
2 Gamma (0, +∞)
3 Inverse Gaussian (0, +∞)

See the documentation of the superclass, ExponentialDispersionModel, for details.

Parameters:

Name Type Description Default
power (float, optional(default=0))

The variance power of the unit_variance \(v(\mu) = \mu^{\mathrm{power}}\). For \(0 < \mathrm{power} < 1\), no distribution exists.

0
Source code in src/glum/_distribution.py
572
573
574
def __init__(self, power=0):
    # validate power and set _upper_bound, _include_upper_bound attrs
    self.power = power

upper_bound class-attribute instance-attribute

upper_bound = np.inf

Get the upper bound of values for the EDM.

include_upper_bound class-attribute instance-attribute

include_upper_bound = False

Return whether upper_bound is allowed as a value of y.

power property writable

power

Return the Tweedie power parameter.

lower_bound property

lower_bound: float

Get the lower bound of values for the EDM.

include_lower_bound property

include_lower_bound: bool

Return whether lower_bound is allowed as a value of y.

in_y_range

in_y_range(x) -> np.ndarray

Return True if x is in the valid range of the EDM.

Source code in src/glum/_distribution.py
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def in_y_range(self, x) -> np.ndarray:
    """Return `True` if `x` is in the valid range of the EDM."""
    if self.include_lower_bound:
        lb_op: np.ufunc = np.greater_equal
    else:
        lb_op = np.greater

    if self.include_upper_bound:
        ub_op: np.ufunc = np.less_equal
    else:
        ub_op = np.less

    return lb_op(x, self.lower_bound) & ub_op(x, self.upper_bound)

to_tweedie

to_tweedie(safe=True)

Return the Tweedie representation of a distribution if it exists.

Source code in src/glum/_distribution.py
102
103
104
105
106
107
108
def to_tweedie(self, safe=True):
    """Return the Tweedie representation of a distribution if it exists."""
    if hasattr(self, "__tweedie_repr__"):
        return self.__tweedie_repr__()
    if safe:
        raise ValueError("This distribution has no Tweedie representation.")
    return None

variance

variance(mu, dispersion=1, sample_weight=1) -> np.ndarray

Compute the variance function.

The variance of \(Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)\) takes the form \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(w_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def variance(self, mu, dispersion=1, sample_weight=1) -> np.ndarray:
    r"""Compute the variance function.

    The variance of $Y_i \sim \mathrm{EDM}(\mu_i, \phi / w_i)$ takes
    the form $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the
    unit variance and $w_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance(mu) * dispersion / sample_weight

variance_derivative

variance_derivative(mu, dispersion=1, sample_weight=1)

Compute the derivative of the variance with respect to mu.

The derivative of the variance is equal to \(v(\mu_i) \times \phi / w_i\), where \(v(\mu)\) is the unit variance and \(ws_i\) are weights.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
dispersion (float, optional(default=1))

Dispersion parameter \(\phi\).

1
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def variance_derivative(self, mu, dispersion=1, sample_weight=1):
    r"""Compute the derivative of the variance with respect to `mu`.

    The derivative of the variance is equal to
    $v(\mu_i) \times \phi / w_i$, where $v(\mu)$ is the unit
    variance and $ws_i$ are weights.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Predicted mean.

    dispersion : float, optional (default=1)
        Dispersion parameter $\phi$.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return self.unit_variance_derivative(mu) * dispersion / sample_weight

unit_deviance_derivative

unit_deviance_derivative(y, mu)

Compute the derivative of the unit deviance with respect to mu.

The derivative of the unit deviance is given by \(2 \times (\mu - y) / v(\mu)\), where \(v(\mu)\) is the unit variance.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
def unit_deviance_derivative(self, y, mu):
    r"""Compute the derivative of the unit deviance with respect to `mu`.

    The derivative of the unit deviance is given by
    $2 \times (\mu - y) / v(\mu)$, where $v(\mu)$ is the unit
    variance.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return -2 * (y - mu) / self.unit_variance(mu)

deviance_derivative

deviance_derivative(y, mu, sample_weight=1)

Compute the derivative of the deviance with respect to mu.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples)(default=1))

Weights or exposure to which variance is inverse proportional.

1

Returns:

Type Description
(array - like, shape(n_samples))
Source code in src/glum/_distribution.py
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
def deviance_derivative(self, y, mu, sample_weight=1):
    r"""Compute the derivative of the deviance with respect to `mu`.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,) (default=1)
        Weights or exposure to which variance is inverse proportional.

    Returns
    -------
    array-like, shape (n_samples,)
    """
    return sample_weight * self.unit_deviance_derivative(y, mu)

eta_mu_deviance

eta_mu_deviance(link: Link, factor: float, cur_eta, X_dot_d, y, sample_weight) -> tuple[np.ndarray, np.ndarray, float]

Compute eta, mu and the deviance.

Returns:

Type Description
(ndarray, shape(shape[0]))

The linear predictor, eta, as cur_eta + factor * X_dot_d.

(ndarray, shape(shape[0]))

The link-function-transformed prediction, mu.

float

The deviance.

Source code in src/glum/_distribution.py
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
def eta_mu_deviance(
    self,
    link: Link,
    factor: float,
    cur_eta,
    X_dot_d,
    y,
    sample_weight,
) -> tuple[np.ndarray, np.ndarray, float]:
    """Compute `eta`, `mu` and the deviance.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The linear predictor, `eta`, as `cur_eta + factor * X_dot_d`.
    numpy.ndarray, shape (X.shape[0],)
        The link-function-transformed prediction, `mu`.
    float
        The deviance.
    """
    # eta_out and mu_out are filled inside self._eta_mu_deviance,
    # avoiding allocating new arrays for every line search loop
    eta_out = np.empty_like(cur_eta)
    mu_out = np.empty_like(cur_eta)

    deviance = self._eta_mu_deviance(
        link, factor, cur_eta, X_dot_d, y, sample_weight, eta_out, mu_out
    )

    return eta_out, mu_out, deviance

rowwise_gradient_hessian

rowwise_gradient_hessian(link: Link, coef, dispersion, X: Union[MatrixBase, StandardizedMatrix], y, sample_weight, eta, mu, offset=None)

Compute the gradient and negative Hessian of the log likelihood row-wise.

Returns:

Type Description
(ndarray, shape(shape[0]))

The gradient of the log likelihood, row-wise.

(ndarray, shape(shape[0]))

The negative Hessian of the log likelihood, row-wise.

Source code in src/glum/_distribution.py
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
def rowwise_gradient_hessian(
    self,
    link: Link,
    coef,
    dispersion,
    X: Union[MatrixBase, StandardizedMatrix],
    y,
    sample_weight,
    eta,
    mu,
    offset=None,
):
    """Compute the gradient and negative Hessian of the log likelihood row-wise.

    Returns
    -------
    numpy.ndarray, shape (X.shape[0],)
        The gradient of the log likelihood, row-wise.
    numpy.ndarray, shape (X.shape[0],)
        The negative Hessian of the log likelihood, row-wise.
    """
    gradient_rows = np.empty_like(mu)
    hessian_rows = np.empty_like(mu)

    self._rowwise_gradient_hessian(
        link, y, sample_weight, eta, mu, gradient_rows, hessian_rows
    )

    # To form the full Hessian matrix from the IRLS sample_weight:
    # hessian_matrix = _safe_sandwich_dot(X, hessian_rows, intercept=intercept)
    return gradient_rows, hessian_rows

unit_variance

unit_variance(mu)

Compute the unit variance.

The unit variance, \(v(\mu) \equiv b''((b')^{-1} (\mu))\), determines the variance as a function of the mean \(\mu\) by \(\mathrm{var}(y_i) = v(\mu_i) \times \phi / w_i\). It can also be derived from the unit deviance \(d(y, \mu)\) as

\[ v(\mu) = 2 \div \frac{\partial^2 d(y, \mu)}{\partial\mu^2} \big| _{y=\mu}. \]

See also variance.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
615
616
617
def unit_variance(self, mu):  # noqa D
    p = self.power  # noqa: F841
    return numexpr.evaluate("mu ** p")

unit_variance_derivative

unit_variance_derivative(mu)

Compute the derivative of the unit variance with respect to mu.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
619
620
621
def unit_variance_derivative(self, mu):  # noqa D
    p = self.power  # noqa: F841
    return numexpr.evaluate("p * mu ** (p - 1)")

deviance

deviance(y, mu, sample_weight=None) -> float

Compute the deviance.

The deviance is a weighted sum of the unit deviances. In terms of the unit log likelihood \(\ell\), it equals \(2 \sum_i [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which the variance is inversely proportional.

None
Source code in src/glum/_distribution.py
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
def deviance(self, y, mu, sample_weight=None) -> float:  # noqa D
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)
    sample_weight = np.ones_like(y) if sample_weight is None else sample_weight

    # NOTE: the dispersion parameter is only necessary to convey
    # type information on account of a bug in Cython

    if self.power == 0:
        return normal_deviance(y, sample_weight, mu, dispersion=1.0)
    if self.power == 1:
        return poisson_deviance(y, sample_weight, mu, dispersion=1.0)
    elif self.power == 2:
        return gamma_deviance(y, sample_weight, mu, dispersion=1.0)
    elif self.power == 3:
        return inv_gaussian_deviance(y, sample_weight, mu, dispersion=1.0)
    else:
        return tweedie_deviance(y, sample_weight, mu, p=float(self.power))

unit_deviance

unit_deviance(y, mu)

Compute the unit deviance.

In terms of the unit log likelihood \(\ell\), the unit deviance is \(2 [\ell(y_i, y_i, \phi) - \ell(y_i, \mu, \phi)]\), i.e. twice the difference between the log likelihood of a saturated model (with one parameter per observation) and the model at hand.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
Source code in src/glum/_distribution.py
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
def unit_deviance(self, y, mu):  # noqa D
    if self.power == 0:  # normal distribution
        return (y - mu) ** 2
    if self.power == 1:  # Poisson distribution
        return 2 * (special.xlogy(y, y / mu) - y + mu)
    elif self.power == 2:  # Gamma distribution
        return 2 * (np.log(mu / y) + y / mu - 1)
    elif self.power == 3:  # inverse Gaussian distribution
        return ((y / mu - 1) ** 2) / y
    else:
        mu1mp = mu ** (1 - self.power)
        return 2 * (
            (np.maximum(y, 0) ** (2 - self.power))
            / ((1 - self.power) * (2 - self.power))
            - y * mu1mp / (1 - self.power)
            + mu * mu1mp / (2 - self.power)
        )

log_likelihood

log_likelihood(y, mu, sample_weight=None, dispersion=None) -> float

Compute the log likelihood.

For 1 < p < 2, we use the series approximation by Dunn and Smyth (2005) to compute the normalization term.

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Sample weights.

None
dispersion (float, optional(default=None))

Dispersion parameter \(\phi\). Estimated if None.

None
Source code in src/glum/_distribution.py
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
def log_likelihood(self, y, mu, sample_weight=None, dispersion=None) -> float:
    r"""Compute the log likelihood.

    For `1 < p < 2`, we use the series approximation by Dunn and Smyth
    (2005) to compute the normalization term.

    Parameters
    ----------
    y : array-like, shape (n_samples,)
        Target values.

    mu : array-like, shape (n_samples,)
        Predicted mean.

    sample_weight : array-like, shape (n_samples,), optional (default=1)
        Sample weights.

    dispersion : float, optional (default=None)
        Dispersion parameter $\phi$. Estimated if `None`.
    """
    p = self.power
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)
    sample_weight = np.ones_like(y) if sample_weight is None else sample_weight

    if (p != 1) and (dispersion is None):
        dispersion = self.dispersion(y, mu, sample_weight)

    if p == 0:
        return normal_log_likelihood(y, sample_weight, mu, float(dispersion))
    if p == 1:
        # NOTE: the dispersion parameter is only necessary to convey
        # type information on account of a bug in Cython
        return poisson_log_likelihood(y, sample_weight, mu, 1.0)
    elif p == 2:
        return gamma_log_likelihood(y, sample_weight, mu, float(dispersion))
    elif p < 2:
        return tweedie_log_likelihood(
            y, sample_weight, mu, float(p), float(dispersion)
        )
    elif p == 3:
        return inv_gaussian_log_likelihood(y, sample_weight, mu, float(dispersion))
    else:
        raise NotImplementedError

dispersion

dispersion(y, mu, sample_weight=None, ddof=1, method='pearson') -> float

Estimate the dispersion parameter \(\phi\).

Parameters:

Name Type Description Default
y (array - like, shape(n_samples))

Target values.

required
mu (array - like, shape(n_samples))

Predicted mean.

required
sample_weight (array - like, shape(n_samples), optional(default=1))

Weights or exposure to which variance is inversely proportional.

None
ddof (int, optional(default=1))

Degrees of freedom consumed by the model for mu.

1
method

Whether to base the estimate on the Pearson residuals or the deviance.

'pearson'
Source code in src/glum/_distribution.py
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
def dispersion(  # noqa D
    self, y, mu, sample_weight=None, ddof=1, method="pearson"
) -> float:
    p = self.power  # noqa: F841
    y, mu, sample_weight = _as_float_arrays(y, mu, sample_weight)

    if method == "pearson":
        formula = "((y - mu) ** 2) / (mu ** p)"
        if sample_weight is None:
            return numexpr.evaluate(formula).sum() / (len(y) - ddof)
        else:
            formula = f"sample_weight * {formula}"
            return numexpr.evaluate(formula).sum() / (sample_weight.sum() - ddof)

    return super().dispersion(
        y, mu, sample_weight=sample_weight, ddof=ddof, method=method
    )

GeneralizedLinearRegressor

GeneralizedLinearRegressor(*, alpha=None, l1_ratio=0, P1: Optional[Union[str, ndarray]] = 'identity', P2: Optional[Union[str, ndarray, spmatrix]] = 'identity', fit_intercept=True, family: Union[str, ExponentialDispersionModel] = 'normal', link: Union[str, Link] = 'auto', solver: str = 'auto', max_iter=100, max_inner_iter=100000, gradient_tol: Optional[float] = None, step_size_tol: Optional[float] = None, hessian_approx: float = 0.0, warm_start: bool = False, alpha_search: bool = False, alphas: Optional[ndarray] = None, n_alphas: int = 100, min_alpha_ratio: Optional[float] = None, min_alpha: Optional[float] = None, start_params: Optional[ndarray] = None, selection: str = 'cyclic', random_state=None, copy_X: Optional[bool] = None, check_input: bool = True, verbose=0, scale_predictors: bool = False, lower_bounds: Optional[ndarray] = None, upper_bounds: Optional[ndarray] = None, A_ineq: Optional[ndarray] = None, b_ineq: Optional[ndarray] = None, monotonic_constraints: Optional[Mapping[str, str]] = None, force_all_finite: bool = True, drop_first: bool = False, robust: bool = True, expected_information: bool = False, formula: Optional[FormulaSpec] = None, interaction_separator: str = ':', categorical_format: str = '{name}[{category}]', cat_missing_method: str = 'fail', cat_missing_name: str = '(MISSING)')

Bases: GeneralizedLinearRegressorBase

Regression via a Generalized Linear Model (GLM) with penalties.

GLMs based on a reproductive Exponential Dispersion Model (EDM) aimed at fitting and predicting the mean of the target y as mu=h(X*w). Therefore, the fit minimizes the following objective function with combined L1 and L2 priors as regularizer:

    1/(2*sum(s)) * deviance(y, h(X*w); s)
    + alpha * l1_ratio * ||P1*w||_1
    + 1/2 * alpha * (1 - l1_ratio) * w*P2*w

with inverse link function h and s=sample_weight. Note that, for alpha=0 the unregularized GLM is recovered. This is not the default behavior (see alpha parameter description for details). Additionally, for sample_weight=None, one has s_i=1 and sum(s)=n_samples. For P1=P2='identity', the penalty is the elastic net:

    alpha * l1_ratio * ||w||_1 + 1/2 * alpha * (1 - l1_ratio) * ||w||_2^2.

If you are interested in controlling the L1 and L2 penalties separately, keep in mind that this is equivalent to:

    a * L1 + b * L2,

where:

    alpha = a + b and l1_ratio = a / (a + b).

The parameter l1_ratio corresponds to alpha in the R package glmnet, while alpha corresponds to the lambda parameter in glmnet. Specifically, l1_ratio = 1 is the lasso penalty.

Read more in background.

Parameters:

Name Type Description Default
alpha (float, array - like)

Constant that multiplies the penalty terms and thus determines the regularization strength. If alpha_search is False (the default), then alpha must be a scalar or None (equivalent to alpha=0). If alpha_search is True, then alpha must be an iterable or None. See alpha_search to find how the regularization path is set if alpha is None. See the notes for the exact mathematical meaning of this parameter. alpha=0 is equivalent to unpenalized GLMs. In this case, the design matrix X must have full column rank (no collinearities).

float
l1_ratio (float, optional(default=0))

The elastic net mixing parameter, with 0 <= l1_ratio <= 1. For l1_ratio = 0, the penalty is an L2 penalty. For l1_ratio = 1, it is an L1 penalty. For 0 < l1_ratio < 1, the penalty is a combination of L1 and L2.

0
P1 (identity, array - like, None)

(default='identity') This array controls the strength of the regularization for each coefficient independently. A high value will lead to higher regularization while a value of zero will remove the regularization on this parameter. Note that n_features = X.shape[1]. If X is a pandas DataFrame with a categorical dtype and P1 has the same size as the number of columns, the penalty of the categorical column will be applied to all the levels of the categorical.

'identity'
P2 'identity', array-like, sparse matrix, None

With this option, you can set the P2 matrix in the L2 penalty w*P2*w. This gives a fine control over this penalty (Tikhonov regularization). A 2d array is directly used as the square matrix P2. A 1d array is interpreted as diagonal (square) matrix. The default 'identity' and None set the identity matrix, which gives the usual squared L2-norm. If you just want to exclude certain coefficients, pass a 1d array filled with 1 and 0 for the coefficients to be excluded. Note that P2 must be positive semi-definite. If X is a pandas DataFrame with a categorical dtype and P2 has the same size as the number of columns, the penalty of the categorical column will be applied to all the levels of the categorical. Note that if P2 is two-dimensional, its size needs to be of the same length as the expanded X matrix.

'identity'
fit_intercept (bool, optional(default=True))

Specifies if a constant (a.k.a. bias or intercept) should be added to the linear predictor (X * coef + intercept).

True
family (str or ExponentialDispersionModel, optional(default=normal))

The distributional assumption of the GLM, i.e. the loss function to minimize. If a string, one of: 'binomial', 'gamma', 'gaussian', 'inverse.gaussian', 'normal', 'poisson', 'tweedie' or 'negative.binomial'. Note that 'tweedie' sets the power of the Tweedie distribution to 1.5; to use another value, specify it in parentheses (e.g., 'tweedie (1.5)'). The same applies for 'negative.binomial' and theta parameter.

'normal'
link (auto, identity, log, logit, cloglog)

The link function of the GLM, i.e. mapping from linear predictor (X * coef) to expectation (mu). Option 'auto' sets the link depending on the chosen family as follows:

  • 'identity' for family 'normal'
  • 'log' for families 'poisson', 'gamma', 'inverse.gaussian' and 'negative.binomial'.
  • 'logit' for family 'binomial'
'auto'
solver (auto, closed - form, irls - cd, irls - ls, lbfgs, trust - constr)

Algorithm to use in the optimization problem:

  • 'auto': 'closed-form' for eligible Gaussian identity-link problems without L1 regularization, 'irls-ls' for other pure-L2 cases, and 'irls-cd' otherwise.
  • 'closed-form': Direct linear solve for eligible Gaussian identity-link problems (ridge/OLS/WLS).
  • 'irls-cd': Iteratively reweighted least squares with a coordinate descent inner solver. This can deal with L1 as well as L2 penalties. Note that in order to avoid unnecessary memory duplication of X in the fit method, X should be directly passed as a Fortran-contiguous Numpy array or sparse CSC matrix.
  • 'irls-ls': Iteratively reweighted least squares with a least squares inner solver. This algorithm cannot deal with L1 penalties.
  • 'lbfgs': Scipy's L-BFGS-B optimizer. It cannot deal with L1 penalties.
  • 'trust-constr': Calls scipy.optimize.minimize(method='trust-constr'). It cannot deal with L1 penalties. This solver can optimize problems with inequality constraints, passed via A_ineq and b_ineq. It will be selected automatically when inequality constraints are set and solver='auto'. Note that using this method can lead to significantly increased runtimes by a factor of ten or higher.
'auto'
max_iter (int, optional(default=100))

The maximal number of iterations for solver algorithms.

100
max_inner_iter

The maximal number of iterations for the inner solver in the IRLS-CD algorithm. This parameter is only used when solver='irls-cd'.

100000
gradient_tol (float, optional(default=None))

Stopping criterion. If None, solver-specific defaults will be used. The default value for most solvers is 1e-4, except for 'trust-constr', which requires more conservative convergence settings and has a default value of 1e-8.

For the IRLS-LS, L-BFGS and trust-constr solvers, the iteration will stop when max{|g_i|, i = 1, ..., n} <= tol, where g_i is the i-th component of the gradient (derivative) of the objective function. For the CD solver, convergence is reached when sum_i(|minimum norm of g_i|), where g_i is the subgradient of the objective and the minimum norm of g_i is the element of the subgradient with the smallest L2 norm.

If you wish to only use a step-size tolerance, set gradient_tol to a very small number.

None
step_size_tol Optional[float]

Alternative stopping criterion. For the IRLS-LS and IRLS-CD solvers, the iteration will stop when the L2 norm of the step size is less than step_size_tol. This stopping criterion is disabled when step_size_tol is None.

None
hessian_approx float

The threshold below which data matrix rows will be ignored for updating the Hessian. See the algorithm documentation for the IRLS algorithm for further details.

0.0
warm_start (bool, optional(default=False))

Whether to reuse the solution of the previous call to fit as initialization for coef_ and intercept_ (supersedes start_params). If False or if the attribute coef_ does not exist (first call to fit), start_params sets the start values for coef_ and intercept_.

False
alpha_search (bool, optional(default=False))

Whether to search along the regularization path for the best alpha. When set to True, alpha should either be None or an iterable. To determine the regularization path, the following sequence is used:

  1. If alpha is an iterable, use it directly. All other parameters governing the regularization path are ignored.
  2. If min_alpha is set, create a path from min_alpha to the lowest alpha such that all coefficients are zero.
  3. If min_alpha_ratio is set, create a path where the ratio of min_alpha / max_alpha = min_alpha_ratio.
  4. If none of the above parameters are set, use a min_alpha_ratio of 1e-6 if n_samples >= n_features, else 1e-2.
False
alphas DEPRECATED. Use `alpha` instead.
None
n_alphas (int, optional(default=100))

Number of alphas along the regularization path

100
min_alpha_ratio (float, optional(default=None))

Length of the path. min_alpha_ratio=1e-6 means that min_alpha / max_alpha = 1e-6. If None, 1e-6 is used when n_samples >= n_features, else 1e-2.

None
min_alpha (float, optional(default=None))

Minimum alpha to estimate the model with. The grid will then be created over [max_alpha, min_alpha].

None
start_params array-like, shape (n_features*,), optional (default=None)

Relevant only if warm_start is False or if fit is called for the first time (so that self.coef_ does not exist yet). If None, all coefficients are set to zero and the start value for the intercept is the weighted average of y (If fit_intercept is True). If an array, used directly as start values; if fit_intercept is True, its first element is assumed to be the start value for the intercept_. Note that n_features* = X.shape[1] + fit_intercept, i.e. it includes the intercept.

None
selection (str, optional(default=cyclic))

For the CD solver 'cd', the coordinates (features) can be updated in either cyclic or random order. If set to 'random', a random coefficient is updated every iteration rather than looping over features sequentially in the same order, which often leads to significantly faster convergence, especially when gradient_tol is higher than 1e-4.

'cyclic'
random_state (int or RandomState, optional(default=None))

The seed of the pseudo random number generator that selects a random feature to be updated for the CD solver. If an integer, random_state is the seed used by the random number generator; if a RandomState instance, random_state is the random number generator; if None, the random number generator is the RandomState instance used by np.random. Used when selection is 'random'.

None
copy_X (bool, optional(default=None))

Whether to copy X. Since X is never modified by GeneralizedLinearRegressor, this is unlikely to be needed; this option exists mainly for compatibility with other scikit-learn estimators. If False, X will not be copied and there will be an error if you pass an X in the wrong format, such as providing integer X and float y (only guaranteed for numpy arrays and pandas data frames). If None, X will not be copied unless it is in the wrong format.

None
check_input (bool, optional(default=True))

Whether to bypass several checks on input: y values in range of family, sample_weight non-negative, P2 positive semi-definite. Don't use this parameter unless you know what you are doing.

True
verbose (int, optional(default=0))

For the IRLS solver, any positive number will result in a pretty progress bar showing convergence. This features requires having the tqdm package installed. For the L-BFGS and 'trust-constr' solvers, set verbose to any positive number for verbosity.

0
scale_predictors bool

If True, scale all predictors to have standard deviation one. Should be set to True if alpha > 0 and if you want coefficients to be penalized equally.

Reported coefficient estimates are always at the original scale.

Advanced developer note: Internally, predictors are always rescaled for computational reasons, but this only affects results if scale_predictors is True.

False
lower_bounds (array - like, shape(n_features), optional(default=None))

Set a lower bound for the coefficients. Setting bounds forces the use of the coordinate descent solver ('irls-cd').

None
upper_bounds array-like, shape=(n_features,), optional (default=None)

See lower_bounds.

None
A_ineq array-like, shape=(n_constraints, n_features), optional (default=None)

Constraint matrix for linear inequality constraints of the form A_ineq w <= b_ineq. Setting inequality constraints forces the use of the local gradient-based solver 'trust-constr', which may increase runtime significantly. Note that the constraints only apply to coefficients related to features in X. If you want to constrain the intercept, add it to the feature matrix X manually and set fit_intercept==False.

None
b_ineq array-like, shape=(n_constraints,), optional (default=None)

Constraint vector for linear inequality constraints of the form A_ineq w <= b_ineq. Refer to the documentation of A_ineq for details.

None
monotonic_constraints (dict, optional(default=None))

Mapping from variable names in formula (e.g. "x") to "increasing" or "decreasing". For single-column numeric variables, including transforms like np.log(x), constrains the sign of the coefficient. For bs() splines, categoricals and booleans, orders consecutive coefficients (including an implicit zero for a dropped first column). Other transforms are not supported. Categoricals must be ordered (pandas Categorical with ordered=True or polars Enum); their coefficients follow the category order.

None
drop_first (bool, optional(default=False))

If True, drop the first column when encoding categorical variables. Set this to True when alpha=0 and solver='auto' to prevent an error due to a singular feature matrix. In the case of using a formula with interactions, setting this argument to True ensures structural full-rankness (it is equivalent to ensure_full_rank in formulaic and tabmat).

False
robust (bool, optional(default=False))

If true, then robust standard errors are computed by default.

True
expected_information (bool, optional(default=False))

If true, then the expected information matrix is computed by default. Only relevant when computing robust standard errors.

False
formula FormulaSpec

A formula accepted by formulaic. It can either be a one-sided formula, in which case y must be specified in fit, or a two-sided formula, in which case y must be None.

None
interaction_separator str

The separator between the names of interacted variables.

':'
categorical_format str

Format string for categorical features. The format string should contain the placeholder {name} for the feature name and {category} for the category name. Only used if X is a pandas DataFrame.

'{name}[{category}]'
cat_missing_method str

How to handle missing values in categorical columns. Only used if X is a pandas data frame.

  • if 'fail', raise an error if there are missing values
  • if 'zero', missing values will represent all-zero indicator columns.
  • if 'convert', missing values will be converted to the cat_missing_name category.
'fail'
cat_missing_name str

Name of the category to which missing values will be converted if cat_missing_method='convert'. Only used if X is a pandas data frame.

'(MISSING)'

Attributes:

Name Type Description
coef_ (array, shape(n_features))

Estimated coefficients for the linear predictor (X*coef_+intercept_) in the GLM.

intercept_ float

Intercept (a.k.a. bias) added to linear predictor.

n_iter_ int

Actual number of iterations used in solver.

col_means_ (array, shape(n_features))

The means of the columns of the design matrix X.

col_stds_ (array, shape(n_features))

The standard deviations of the columns of the design matrix X.

feature_names_ list of str

The names of the coefficients.

Notes

The fit itself does not need outcomes to be from an EDM, but only assumes the first two moments to be \(\mu_i \equiv \mathrm{E}(y_i) = h(x_i' w)\) and \(\mathrm{var}(y_i) = (\phi / s_i) v(\mu_i)\). The unit variance function \(v(\mu_i)\) is a property of and given by the specific EDM; see background.

The parameters \(w\) (coef_ and intercept_) are estimated by minimizing the deviance plus penalty term, which is equivalent to (penalized) maximum likelihood estimation.

If the target y is a ratio, appropriate sample weights s should be provided. As an example, consider Poisson distributed counts z (integers) and weights s = exposure (time, money, persons years, ...). Then you fit y ≡ z/s, i.e. GeneralizedLinearModel(family='poisson').fit(X, y, sample_weight=s). The weights are necessary for the right (finite sample) mean. Consider \(\bar{y} = \sum_i s_i y_i / \sum_i s_i\): in this case, one might say that \(y\) follows a 'scaled' Poisson distribution. The same holds for other distributions.

References

For the coordinate descent implementation:

Source code in src/glum/_glm.py
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
def __init__(
    self,
    *,
    alpha=None,
    l1_ratio=0,
    P1: Optional[Union[str, np.ndarray]] = "identity",
    P2: Optional[Union[str, np.ndarray, sparse.spmatrix]] = "identity",
    fit_intercept=True,
    family: Union[str, ExponentialDispersionModel] = "normal",
    link: Union[str, Link] = "auto",
    solver: str = "auto",
    max_iter=100,
    max_inner_iter=100000,
    gradient_tol: Optional[float] = None,
    step_size_tol: Optional[float] = None,
    hessian_approx: float = 0.0,
    warm_start: bool = False,
    alpha_search: bool = False,
    alphas: Optional[np.ndarray] = None,
    n_alphas: int = 100,
    min_alpha_ratio: Optional[float] = None,
    min_alpha: Optional[float] = None,
    start_params: Optional[np.ndarray] = None,
    selection: str = "cyclic",
    random_state=None,
    copy_X: Optional[bool] = None,
    check_input: bool = True,
    verbose=0,
    scale_predictors: bool = False,
    lower_bounds: Optional[np.ndarray] = None,
    upper_bounds: Optional[np.ndarray] = None,
    A_ineq: Optional[np.ndarray] = None,
    b_ineq: Optional[np.ndarray] = None,
    monotonic_constraints: Optional[Mapping[str, str]] = None,
    force_all_finite: bool = True,
    drop_first: bool = False,
    robust: bool = True,
    expected_information: bool = False,
    formula: Optional[formulaic.FormulaSpec] = None,
    interaction_separator: str = ":",
    categorical_format: str = "{name}[{category}]",
    cat_missing_method: str = "fail",
    cat_missing_name: str = "(MISSING)",
):
    self.alphas = alphas
    self.alpha = alpha
    super().__init__(
        l1_ratio=l1_ratio,
        P1=P1,
        P2=P2,
        fit_intercept=fit_intercept,
        family=family,
        link=link,
        solver=solver,
        max_iter=max_iter,
        max_inner_iter=max_inner_iter,
        gradient_tol=gradient_tol,
        step_size_tol=step_size_tol,
        hessian_approx=hessian_approx,
        warm_start=warm_start,
        alpha_search=alpha_search,
        n_alphas=n_alphas,
        min_alpha=min_alpha,
        min_alpha_ratio=min_alpha_ratio,
        start_params=start_params,
        selection=selection,
        random_state=random_state,
        copy_X=copy_X,
        check_input=check_input,
        verbose=verbose,
        scale_predictors=scale_predictors,
        lower_bounds=lower_bounds,
        upper_bounds=upper_bounds,
        A_ineq=A_ineq,
        b_ineq=b_ineq,
        monotonic_constraints=monotonic_constraints,
        force_all_finite=force_all_finite,
        drop_first=drop_first,
        robust=robust,
        expected_information=expected_information,
        formula=formula,
        interaction_separator=interaction_separator,
        categorical_format=categorical_format,
        cat_missing_method=cat_missing_method,
        cat_missing_name=cat_missing_name,
    )

family_instance property

family_instance: ExponentialDispersionModel
link_instance: Link

Return a Link.

report_diagnostics

report_diagnostics(*, full_report: bool = False, custom_columns: Optional[Sequence] = None) -> None

Print diagnostics to stdout.

Parameters:

Name Type Description Default
full_report (bool, optional(default=False))

Print all available information. When False and custom_columns is None, a restricted set of columns is printed out.

False
custom_columns (iterable, optional(default=None))

Print only the specified columns.

None
Source code in src/glum/_glm.py
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
def report_diagnostics(
    self,
    *,
    full_report: bool = False,
    custom_columns: Optional[Sequence] = None,
) -> None:
    """Print diagnostics to `stdout`.

    Parameters
    ----------
    full_report : bool, optional (default=False)
        Print all available information. When `False` and
        `custom_columns` is `None`, a restricted set of columns is
        printed out.

    custom_columns : iterable, optional (default=None)
        Print only the specified columns.
    """
    diagnostics = self.get_formatted_diagnostics(
        full_report=full_report, custom_columns=custom_columns
    )
    if isinstance(diagnostics, str):
        print(diagnostics)
        return

    import pandas as pd

    print("Diagnostics:")
    with pd.option_context("display.max_rows", None, "display.max_columns", None):
        print(diagnostics)

get_formatted_diagnostics

get_formatted_diagnostics(*, full_report: bool = False, custom_columns: Optional[Sequence] = None) -> Union[str, pd.DataFrame]

Get formatted diagnostics which can be printed with report_diagnostics.

Parameters:

Name Type Description Default
full_report (bool, optional(default=False))

Print all available information. When False and custom_columns is None, a restricted set of columns is printed out.

False
custom_columns (iterable, optional(default=None))

Print only the specified columns.

None
Source code in src/glum/_glm.py
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
def get_formatted_diagnostics(
    self,
    *,
    full_report: bool = False,
    custom_columns: Optional[Sequence] = None,
) -> Union[str, pd.DataFrame]:
    """Get formatted diagnostics which can be printed with report_diagnostics.

    Parameters
    ----------
    full_report : bool, optional (default=False)
        Print all available information. When `False` and
        `custom_columns` is `None`, a restricted set of columns is
        printed out.

    custom_columns : iterable, optional (default=None)
        Print only the specified columns.
    """
    if not hasattr(self, "diagnostics_"):
        to_print = "Model has not been fit, so no diagnostics exist."
        return to_print
    if self.diagnostics_ is None:
        to_print = "solver does not report diagnostics"
        return to_print

    import pandas as pd

    df = pd.DataFrame(data=self.diagnostics_).set_index("n_iter", drop=True)
    if self.fit_intercept:
        df["intercept"] = df["first_coef"]
    else:
        df["intercept"] = np.nan

    if custom_columns is not None:
        keep_cols = custom_columns
    elif full_report:
        keep_cols = df.columns
    else:
        keep_cols = ["convergence", "n_cycles", "iteration_runtime", "intercept"]

    return df[keep_cols]

linear_predictor

linear_predictor(X: ArrayLike, offset: Optional[ArrayLike] = None, *, alpha_index: Optional[Union[int, Sequence[int]]] = None, alpha: Optional[Union[float, Sequence[float]]] = None, context: Optional[Union[int, Mapping[str, Any]]] = None)

Compute the linear predictor, X * coef_ + intercept_.

If alpha_search is True, but alpha_index and alpha are both None, the predictions are for the last alpha value self._alphas[-1].

Parameters:

Name Type Description Default
X (array - like, shape(n_samples, n_features))

Observations. X may be a pandas data frame with categorical types. If X was also a data frame with categorical types during fitting and a category wasn't observed at that point, the corresponding prediction will be numpy.nan.

required
offset (array - like, shape(n_samples), optional(default=None))

Offset added to the linear predictor.

None
alpha_index int or sequence of int, optional (default=None)

Index (or indices) into the fitted alpha path. Only valid when alpha_search is True. Incompatible with alpha.

None
alpha float or sequence of float, optional (default=None)

Alpha value(s) to predict at, resolved to the closest index on the fitted alpha path. Only valid when alpha_search is True. Incompatible with alpha_index.

None
context (int or mapping, optional(default=None))

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None

Returns:

Type Description
ndarray

Shape (n_samples,) when no alpha_index / alpha is given or when a scalar alpha is passed. Shape (n_samples, len(alpha_index)) when a sequence is passed.

Source code in src/glum/_glm.py
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
def linear_predictor(
    self,
    X: ArrayLike,
    offset: Optional[ArrayLike] = None,
    *,
    alpha_index: Optional[Union[int, Sequence[int]]] = None,
    alpha: Optional[Union[float, Sequence[float]]] = None,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
):
    """Compute the linear predictor, `X * coef_ + intercept_`.

    If `alpha_search` is `True`, but `alpha_index` and `alpha` are both
    `None`, the predictions are for the last alpha value `self._alphas[-1]`.

    Parameters
    ----------
    X : array-like, shape (n_samples, n_features)
        Observations. `X` may be a pandas data frame with categorical
        types. If `X` was also a data frame with categorical types during
        fitting and a category wasn't observed at that point, the
        corresponding prediction will be `numpy.nan`.

    offset : array-like, shape (n_samples,), optional (default=None)
        Offset added to the linear predictor.

    alpha_index : int or sequence of int, optional (default=None)
        Index (or indices) into the fitted alpha path. Only valid when
        `alpha_search` is `True`. Incompatible with `alpha`.

    alpha : float or sequence of float, optional (default=None)
        Alpha value(s) to predict at, resolved to the closest index on
        the fitted alpha path. Only valid when `alpha_search` is
        `True`. Incompatible with `alpha_index`.

    context : int or mapping, optional (default=None)
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.


    Returns
    -------
    np.ndarray
        Shape `(n_samples,)` when no `alpha_index` / `alpha` is
        given or when a scalar alpha is passed. Shape
        `(n_samples, len(alpha_index))` when a sequence is passed.
    """
    skl.utils.validation.check_is_fitted(self, "coef_")

    if (alpha is not None or alpha_index is not None) and not self.alpha_search:
        raise ValueError(
            "Cannot use 'alpha' or 'alpha_index' when 'alpha_search' is False."
        )

    alpha_index = self._resolve_alpha_index(alpha_index, alpha)

    use_path = alpha_index is not None
    return self._compute_linear_predictor(
        X,
        offset,
        alpha_index=alpha_index,
        coef_path=self.coef_path_ if use_path else self.coef_,
        intercept_path=self.intercept_path_ if use_path else self.intercept_,
        context=context,
    )

predict

predict(X: ShapedArrayLike, sample_weight: Optional[ArrayLike] = None, offset: Optional[ArrayLike] = None, *, alpha_index: Optional[Union[int, Sequence[int]]] = None, alpha: Optional[Union[float, Sequence[float]]] = None, context: Optional[Union[int, Mapping[str, Any]]] = None)

Predict using GLM with feature matrix X.

If alpha_search is True, but alpha_index and alpha are both None, we use the last alpha value self._alphas[-1].

Parameters:

Name Type Description Default
X (array - like, shape(n_samples, n_features))

Observations. X may be a pandas data frame with categorical types. If X was also a data frame with categorical types during fitting and a category wasn't observed at that point, the corresponding prediction will be numpy.nan.

required
sample_weight (array - like, shape(n_samples), optional(default=None))

Sample weights to multiply predictions by.

None
offset (array - like, shape(n_samples), optional(default=None))
None
alpha_index (int or list[int], optional(default=None))

Sets the index of the alpha(s) to use in case alpha_search is True. Incompatible with alpha (see below).

None
alpha (float or list[float], optional(default=None))

Sets the alpha(s) to use in case alpha_search is True. Incompatible with alpha_index (see above).

None
context Optional[Union[int, Mapping[str, Any]]]

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None

Returns:

Type Description
ndarray

Shape (n_samples,) when no alpha_index / alpha is given or when a scalar alpha is passed. Shape (n_samples, len(alpha_index)) when a sequence is passed.

Source code in src/glum/_glm.py
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
def predict(
    self,
    X: ShapedArrayLike,
    sample_weight: Optional[ArrayLike] = None,
    offset: Optional[ArrayLike] = None,
    *,
    alpha_index: Optional[Union[int, Sequence[int]]] = None,
    alpha: Optional[Union[float, Sequence[float]]] = None,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
):
    """Predict using GLM with feature matrix `X`.

    If `alpha_search` is `True`, but `alpha_index` and `alpha` are
    both `None`, we use the last alpha value `self._alphas[-1]`.

    Parameters
    ----------
    X : array-like, shape (n_samples, n_features)
        Observations. `X` may be a pandas data frame with categorical
        types. If `X` was also a data frame with categorical types during
        fitting and a category wasn't observed at that point, the
        corresponding prediction will be `numpy.nan`.

    sample_weight : array-like, shape (n_samples,), optional (default=None)
        Sample weights to multiply predictions by.

    offset : array-like, shape (n_samples,), optional (default=None)

    alpha_index : int or list[int], optional (default=None)
        Sets the index of the alpha(s) to use in case `alpha_search` is
        `True`. Incompatible with `alpha` (see below).

    alpha : float or list[float], optional (default=None)
        Sets the alpha(s) to use in case `alpha_search` is `True`.
        Incompatible with `alpha_index` (see above).

    context : Optional[Union[int, Mapping[str, Any]]], default=None
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.

    Returns
    -------
    np.ndarray
        Shape `(n_samples,)` when no `alpha_index` / `alpha` is
        given or when a scalar alpha is passed. Shape
        `(n_samples, len(alpha_index))` when a sequence is passed.
    """
    if nw.dependencies.is_into_dataframe(X):
        X = self._convert_from_df(X, context=capture_context(context))
    X = cast(ShapedArrayLikeConverted, X)

    eta = self.linear_predictor(
        X, offset=offset, alpha_index=alpha_index, alpha=alpha, context=context
    )

    mu = self.link_instance.inverse(eta)

    if sample_weight is None:
        return mu

    sample_weight = check_weights(sample_weight, X.shape[0], X.dtype)

    return mu * sample_weight

coef_table

coef_table(X=None, y=None, sample_weight=None, offset=None, *, confidence_level=0.95, mu=None, dispersion=None, robust=None, clusters: ndarray = None, expected_information=None, context: Optional[Union[int, Mapping[str, Any]]] = None)

Get a table of of the regression coefficients.

Includes coefficient estimates, standard errors, t-values, p-values and confidence intervals.

Parameters:

Name Type Description Default
confidence_level float

The confidence level for the confidence intervals.

0.95
X array-like, sparse matrix

Training data. Can be omitted if a covariance matrix has already been computed or if standard errors, etc. are not desired.

array-like
y (array - like, shape(n_samples))

Target values. Can be omitted if a covariance matrix has already been computed.

None
mu array - like

Array with predictions. Estimated if absent.

None
offset array - like

Array with additive offsets.

None
sample_weight (array - like, shape(n_samples))

Individual weights for each sample.

None
dispersion float

The dispersion parameter. Estimated if absent.

None
robust boolean

Whether to compute robust standard errors instead of normal ones. If not specified, the model's robust attribute is used.

None
clusters array - like

Array with cluster membership. Clustered standard errors are computed if clusters is not None.

None
expected_information boolean

Whether to use the expected or observed information matrix. Only relevant when computing robust standard errors. If not specified, the model's expected_information attribute is used.

None
context Optional[Union[int, Mapping[str, Any]]]

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None

Returns:

Type Description
DataFrame

A table of the regression results.

Source code in src/glum/_glm.py
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
def coef_table(
    self,
    X=None,
    y=None,
    sample_weight=None,
    offset=None,
    *,
    confidence_level=0.95,
    mu=None,
    dispersion=None,
    robust=None,
    clusters: np.ndarray = None,
    expected_information=None,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
):
    """Get a table of of the regression coefficients.

    Includes coefficient estimates, standard errors, t-values, p-values
    and confidence intervals.

    Parameters
    ----------
    confidence_level : float, optional, default=0.95
        The confidence level for the confidence intervals.
    X : {array-like, sparse matrix}, shape (n_samples, n_features), optional
        Training data. Can be omitted if a covariance matrix has already
        been computed or if standard errors, etc. are not desired.
    y : array-like, shape (n_samples,), optional
        Target values. Can be omitted if a covariance matrix has already
        been computed.
    mu : array-like, optional, default=None
        Array with predictions. Estimated if absent.
    offset : array-like, optional, default=None
        Array with additive offsets.
    sample_weight : array-like, shape (n_samples,), optional, default=None
        Individual weights for each sample.
    dispersion : float, optional, default=None
        The dispersion parameter. Estimated if absent.
    robust : boolean, optional, default=None
        Whether to compute robust standard errors instead of normal ones.
        If not specified, the model's `robust` attribute is used.
    clusters : array-like, optional, default=None
        Array with cluster membership. Clustered standard errors are
        computed if clusters is not None.
    expected_information : boolean, optional, default=None
        Whether to use the expected or observed information matrix.
        Only relevant when computing robust standard errors.
        If not specified, the model's `expected_information` attribute is used.
    context : Optional[Union[int, Mapping[str, Any]]], default=None
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.

    Returns
    -------
    pandas.DataFrame
        A table of the regression results.
    """
    if self.fit_intercept:
        names = ["intercept"] + list(self.feature_names_)
        beta = np.concatenate([[self.intercept_], self.coef_])
    else:
        names = self.feature_names_
        beta = self.coef_

    if (X is None) and (getattr(self, "covariance_matrix_", None) is None):
        return pd.Series(beta, index=names, name="coef")

    covariance_matrix = self.covariance_matrix(
        X=X,
        y=y,
        mu=mu,
        offset=offset,
        sample_weight=sample_weight,
        dispersion=dispersion,
        robust=robust,
        clusters=clusters,
        expected_information=expected_information,
        context=capture_context(context),
    )

    significance_level = 1 - confidence_level

    std_errors = np.sqrt(np.diag(covariance_matrix))
    ci_lower = beta + stats.norm.ppf(significance_level / 2) * std_errors
    ci_upper = beta + stats.norm.ppf(1 - significance_level / 2) * std_errors
    t_values = beta / std_errors
    p_values = 2.0 * (1.0 - stats.norm.cdf(np.abs(t_values)))

    return pd.DataFrame(
        {
            "coef": beta,
            "se": std_errors,
            "t_value": t_values,
            "p_value": p_values,
            "ci_lower": ci_lower,
            "ci_upper": ci_upper,
        },
        index=names,
    )

wald_test

wald_test(X=None, y=None, sample_weight=None, offset=None, *, R: Optional[ndarray] = None, features: Optional[Union[str, list[str]]] = None, terms: Optional[Union[str, list[str]]] = None, formula: Optional[str] = None, r: Optional[Sequence] = None, mu=None, dispersion=None, robust=None, clusters: ndarray = None, expected_information=None, context: Optional[Union[int, Mapping[str, Any]]] = None) -> WaldTestResult

Compute the Wald test statistic and p-value for a linear hypothesis.

The left hand side of the hypothesis may be specified in the following ways:

  • R: The restriction matrix representing the linear combination of coefficients to test.
  • features: The name of a feature or a list of features to test.
  • terms: The name of a term or a list of terms to test.
  • formula: A formula string specifying the hypothesis to test.

The right hand side of the tested hypothesis is specified by r. In the case of a terms-based test, the null hypothesis is that each coefficient relating to a term equals the corresponding value in r.

Parameters:

Name Type Description Default
X array-like, sparse matrix

Training data. Can be omitted if a covariance matrix has already been computed.

array-like
y (array - like, shape(n_samples))

Target values. Can be omitted if a covariance matrix has already been computed.

None
sample_weight (array - like, shape(n_samples))

Individual weights for each sample.

None
offset array - like

Array with additive offsets.

None
R ndarray

The restriction matrix representing the linear combination of coefficients to test.

None
features Union[str, list[str]]

The name of a feature or a list of features to test.

None
terms Union[str, list[str]]

The name of a term or a list of terms to test. It can cover one or more coefficients. In the case of a model based on a formula, a term is one of the expressions separated by + signs. Otherwise, a term is one column in the input data. As categorical variables need not be one-hot encoded in glum, in their case, the hypothesis to be tested is that the coefficients of all categories are equal to r.

None
r Sequence

The vector representing the values of the linear combination. If None, the test is for whether the linear combinations of the coefficients are zero.

None
mu array - like

Array with predictions. Estimated if absent.

None
dispersion float

The dispersion parameter. Estimated if absent.

None
robust boolean

Whether to compute robust standard errors instead of normal ones. If not specified, the model's robust attribute is used.

None
clusters array - like

Array with cluster membership. Clustered standard errors are computed if clusters is not None.

None
expected_information boolean

Whether to use the expected or observed information matrix. Only relevant when computing robust standard errors. If not specified, the model's expected_information attribute is used.

None
context Optional[Union[int, Mapping[str, Any]]]

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None

Returns:

Type Description
WaldTestResult

NamedTuple with test statistic, p-value, and degrees of freedom.

Source code in src/glum/_glm.py
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
def wald_test(
    self,
    X=None,
    y=None,
    sample_weight=None,
    offset=None,
    *,
    R: Optional[np.ndarray] = None,
    features: Optional[Union[str, list[str]]] = None,
    terms: Optional[Union[str, list[str]]] = None,
    formula: Optional[str] = None,
    r: Optional[Sequence] = None,
    mu=None,
    dispersion=None,
    robust=None,
    clusters: np.ndarray = None,
    expected_information=None,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
) -> WaldTestResult:
    """Compute the Wald test statistic and p-value for a linear hypothesis.

    The left hand side of the hypothesis may be specified in the following ways:

    - `R`: The restriction matrix representing the linear combination of
      coefficients to test.
    - `features`: The name of a feature or a list of features to test.
    - `terms`: The name of a term or a list of terms to test.
    - `formula`: A formula string specifying the hypothesis to test.

    The right hand side of the tested hypothesis is specified by `r`. In the
    case of a `terms`-based test, the null hypothesis is that each coefficient
    relating to a term equals the corresponding value in `r`.

    Parameters
    ----------
    X : {array-like, sparse matrix}, shape (n_samples, n_features), optional
        Training data. Can be omitted if a covariance matrix has already
        been computed.
    y : array-like, shape (n_samples,), optional
        Target values. Can be omitted if a covariance matrix has already
        been computed.
    sample_weight : array-like, shape (n_samples,), optional, default=None
        Individual weights for each sample.
    offset : array-like, optional, default=None
        Array with additive offsets.
    R : np.ndarray, optional, default=None
        The restriction matrix representing the linear combination of coefficients
        to test.
    features : Union[str, list[str]], optional, default=None
        The name of a feature or a list of features to test.
    terms : Union[str, list[str]], optional, default=None
        The name of a term or a list of terms to test. It can cover one or more
        coefficients. In the case of a model based on a formula, a term is one
        of the expressions separated by `+` signs. Otherwise, a term is one column
        in the input data. As categorical variables need not be one-hot encoded in
        glum, in their case, the hypothesis to be tested is that the coefficients
        of all categories are equal to `r`.
    r : Sequence, optional, default=None
        The vector representing the values of the linear combination.
        If None, the test is for whether the linear combinations of the coefficients
        are zero.
    mu : array-like, optional, default=None
        Array with predictions. Estimated if absent.
    dispersion : float, optional, default=None
        The dispersion parameter. Estimated if absent.
    robust : boolean, optional, default=None
        Whether to compute robust standard errors instead of normal ones.
        If not specified, the model's `robust` attribute is used.
    clusters : array-like, optional, default=None
        Array with cluster membership. Clustered standard errors are
        computed if clusters is not None.
    expected_information : boolean, optional, default=None
        Whether to use the expected or observed information matrix.
        Only relevant when computing robust standard errors.
        If not specified, the model's `expected_information` attribute is used.
    context : Optional[Union[int, Mapping[str, Any]]], default=None
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.

    Returns
    -------
    WaldTestResult
        NamedTuple with test statistic, p-value, and degrees of freedom.
    """

    num_lhs_specs = sum(
        [
            R is not None,
            features is not None,
            terms is not None,
            formula is not None,
        ]
    )
    if num_lhs_specs != 1:
        raise ValueError(
            "Exactly one of R, features, terms or formula must be specified. "
            f"Received {num_lhs_specs} specifications."
        )

    kwargs = {
        "X": X,
        "y": y,
        "sample_weight": sample_weight,
        "offset": offset,
        "mu": mu,
        "dispersion": dispersion,
        "robust": robust,
        "clusters": clusters,
        "expected_information": expected_information,
        "context": capture_context(context),
    }

    if R is not None:
        return self._wald_test_matrix(R=R, r=np.asarray(r), **kwargs)
    if features is not None:
        return self._wald_test_feature_names(features=features, values=r, **kwargs)
    if terms is not None:
        return self._wald_test_term_names(terms=terms, values=r, **kwargs)
    if formula is not None:
        if r is not None:
            raise ValueError("Cannot specify both formula and r")
        return self._wald_test_formula(formula=formula, **kwargs)

    raise RuntimeError("This should never happen")

std_errors

std_errors(X=None, y=None, sample_weight=None, offset=None, *, mu=None, dispersion=None, robust=None, clusters: ndarray = None, expected_information=None, store_covariance_matrix=False, context: Optional[Union[int, Mapping[str, Any]]] = None)

Calculate standard errors for generalized linear models.

See covariance_matrix for an in-depth explanation of how the standard errors are computed.

Parameters:

Name Type Description Default
X array-like, sparse matrix

Training data. Can be omitted if a covariance matrix has already been computed.

array-like
y (array - like, shape(n_samples))

Target values. Can be omitted if a covariance matrix has already been computed.

None
sample_weight (array - like, shape(n_samples))

Individual weights for each sample.

None
offset array - like

Array with additive offsets.

None
mu array - like

Array with predictions. Estimated if absent.

None
dispersion float

The dispersion parameter. Estimated if absent.

None
robust boolean

Whether to compute robust standard errors instead of normal ones. If not specified, the model's robust attribute is used.

None
clusters array - like

Array with cluster membership. Clustered standard errors are computed if clusters is not None.

None
expected_information boolean

Whether to use the expected or observed information matrix. Only relevant when computing robust standard errors. If not specified, the model's expected_information attribute is used.

None
store_covariance_matrix boolean

Whether to store the covariance matrix in the model instance. If a covariance matrix has already been stored, it will be overwritten.

False
context Optional[Union[int, Mapping[str, Any]]]

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None
Source code in src/glum/_glm.py
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
def std_errors(
    self,
    X=None,
    y=None,
    sample_weight=None,
    offset=None,
    *,
    mu=None,
    dispersion=None,
    robust=None,
    clusters: np.ndarray = None,
    expected_information=None,
    store_covariance_matrix=False,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
):
    """Calculate standard errors for generalized linear models.

    See `covariance_matrix` for an in-depth explanation of how the
    standard errors are computed.

    Parameters
    ----------
    X : {array-like, sparse matrix}, shape (n_samples, n_features), optional
        Training data. Can be omitted if a covariance matrix has already
        been computed.
    y : array-like, shape (n_samples,), optional
        Target values. Can be omitted if a covariance matrix has already
        been computed.
    sample_weight : array-like, shape (n_samples,), optional, default=None
        Individual weights for each sample.
    offset : array-like, optional, default=None
        Array with additive offsets.
    mu : array-like, optional, default=None
        Array with predictions. Estimated if absent.
    dispersion : float, optional, default=None
        The dispersion parameter. Estimated if absent.
    robust : boolean, optional, default=None
        Whether to compute robust standard errors instead of normal ones.
        If not specified, the model's `robust` attribute is used.
    clusters : array-like, optional, default=None
        Array with cluster membership. Clustered standard errors are
        computed if clusters is not None.
    expected_information : boolean, optional, default=None
        Whether to use the expected or observed information matrix.
        Only relevant when computing robust standard errors.
        If not specified, the model's `expected_information` attribute is used.
    store_covariance_matrix : boolean, optional, default=False
        Whether to store the covariance matrix in the model instance.
        If a covariance matrix has already been stored, it will be overwritten.
    context : Optional[Union[int, Mapping[str, Any]]], default=None
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.
    """
    covariance_matrix = self.covariance_matrix(
        X=X,
        y=y,
        sample_weight=sample_weight,
        offset=offset,
        mu=mu,
        dispersion=dispersion,
        robust=robust,
        clusters=clusters,
        expected_information=expected_information,
        store_covariance_matrix=store_covariance_matrix,
        context=capture_context(context),
    )

    return np.sqrt(covariance_matrix.diagonal())

covariance_matrix

covariance_matrix(X=None, y=None, sample_weight=None, offset=None, *, mu=None, dispersion=None, robust=None, clusters: Optional[ndarray] = None, expected_information=None, store_covariance_matrix=False, skip_checks=False, context: Optional[Union[int, Mapping[str, Any]]] = None)

Calculate the covariance matrix for generalized linear models.

Parameters:

Name Type Description Default
X array-like, sparse matrix

Training data. Can be omitted if a covariance matrix has already been computed.

array-like
y (array - like, shape(n_samples))

Target values. Can be omitted if a covariance matrix has already been computed.

None
mu array - like

Array with predictions. Estimated if absent.

None
offset array - like

Array with additive offsets.

None
sample_weight (array - like, shape(n_samples))

Individual weights for each sample.

None
dispersion float

The dispersion parameter. Estimated if absent.

None
robust boolean

Whether to compute robust standard errors instead of normal ones. If not specified, the model's robust attribute is used.

None
clusters array - like

Array with cluster membership. Clustered standard errors are computed if clusters is not None.

None
expected_information boolean

Whether to use the expected or observed information matrix. Only relevant when computing robust standard errors. If not specified, the model's expected_information attribute is used.

None
store_covariance_matrix boolean

Whether to store the covariance matrix in the model instance. If a covariance matrix has already been stored, it will be overwritten.

False
skip_checks boolean

Whether to skip input validation. For internal use only.

False
context Optional[Union[int, Mapping[str, Any]]]

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None
Notes

We support three types of covariance matrices:

  • non-robust
  • robust (HC-1)
  • clustered

For maximum-likelihood estimator, the covariance matrix takes the form \(\mathcal{H}^{-1}(\theta_0)\mathcal{I}(\theta_0) \mathcal{H}^{-1}(\theta_0)\) where \(\mathcal{H}^{-1}\) is the inverse Hessian and \(\mathcal{I}\) is the Information matrix. The different types of covariance matrices use different approximation of these quantities.

The non-robust covariance matrix is computed as the inverse of the Fisher information matrix. This assumes that the information matrix equality holds.

The robust (HC-1) covariance matrix takes the form \(\mathbf{H}^{−1} (\hat{\theta})\mathbf{G}^{T}(\hat{\theta})\mathbf{G}(\hat{\theta}) \mathbf{H}^{−1}(\hat{\theta})\) where \(\mathbf{H}\) is the empirical Hessian and \(\mathbf{G}\) is the gradient. We apply a finite-sample correction of \(\frac{N}{N-p}\).

The clustered covariance matrix uses a similar approach to the robust (HC-1) covariance matrix. However, instead of using \(\mathbf{G}^{T}( \hat{\theta}\mathbf{G}(\hat{\theta})\) directly, we first sum over all the groups first. The finite-sample correction is affected as well, becoming \(\frac{M}{M-1}\frac{N}{N-p}\) where \(M\) is the number of groups.

References
  • Davidson, Russell & MacKinnon, James G. (1993). "Estimation and Inference in Econometrics," OUP Catalogue, Oxford University Press
  • Cameron, A. C., & Trivedi, P. K. (2005). "Microeconometrics: methods and applications," Cambridge university press
Source code in src/glum/_glm.py
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
def covariance_matrix(
    self,
    X=None,
    y=None,
    sample_weight=None,
    offset=None,
    *,
    mu=None,
    dispersion=None,
    robust=None,
    clusters: Optional[np.ndarray] = None,
    expected_information=None,
    store_covariance_matrix=False,
    skip_checks=False,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
):
    """Calculate the covariance matrix for generalized linear models.

    Parameters
    ----------
    X : {array-like, sparse matrix}, shape (n_samples, n_features), optional
        Training data. Can be omitted if a covariance matrix has already
        been computed.

    y : array-like, shape (n_samples,), optional
        Target values. Can be omitted if a covariance matrix has already
        been computed.

    mu : array-like, optional, default=None
        Array with predictions. Estimated if absent.

    offset : array-like, optional, default=None
        Array with additive offsets.

    sample_weight : array-like, shape (n_samples,), optional, default=None
        Individual weights for each sample.

    dispersion : float, optional, default=None
        The dispersion parameter. Estimated if absent.

    robust : boolean, optional, default=None
        Whether to compute robust standard errors instead of normal ones.
        If not specified, the model's `robust` attribute is used.

    clusters : array-like, optional, default=None
        Array with cluster membership. Clustered standard errors are
        computed if clusters is not None.

    expected_information : boolean, optional, default=None
        Whether to use the expected or observed information matrix.
        Only relevant when computing robust standard errors.
        If not specified, the model's `expected_information` attribute is used.

    store_covariance_matrix : boolean, optional, default=False
        Whether to store the covariance matrix in the model instance.
        If a covariance matrix has already been stored, it will be overwritten.

    skip_checks : boolean, optional, default=False
        Whether to skip input validation. For internal use only.

    context : Optional[Union[int, Mapping[str, Any]]], default=None
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.

    Notes
    -----
    We support three types of covariance matrices:

    - non-robust
    - robust (HC-1)
    - clustered

    For maximum-likelihood estimator, the covariance matrix takes the form
    $\\mathcal{H}^{-1}(\\theta_0)\\mathcal{I}(\\theta_0)
    \\mathcal{H}^{-1}(\\theta_0)$ where $\\mathcal{H}^{-1}$ is the
    inverse Hessian and $\\mathcal{I}$ is the Information matrix.
    The different types of covariance matrices use different approximation
    of these quantities.

    The non-robust covariance matrix is computed as the inverse of the Fisher
    information matrix. This assumes that the information matrix equality holds.

    The robust (HC-1) covariance matrix takes the form $\\mathbf{H}^{−1}
    (\\hat{\\theta})\\mathbf{G}^{T}(\\hat{\\theta})\\mathbf{G}(\\hat{\\theta})
    \\mathbf{H}^{−1}(\\hat{\\theta})$ where $\\mathbf{H}$ is the empirical
    Hessian and $\\mathbf{G}$ is the gradient. We apply a finite-sample
    correction of $\\frac{N}{N-p}$.

    The clustered covariance matrix uses a similar approach to the robust (HC-1)
    covariance matrix. However, instead of using $\\mathbf{G}^{T}(
    \\hat{\\theta}\\mathbf{G}(\\hat{\\theta})$ directly, we first sum over
    all the groups first. The finite-sample correction is affected as well,
    becoming $\\frac{M}{M-1}\\frac{N}{N-p}$ where $M$ is the number
    of groups.

    References
    ----------
    - Davidson, Russell & MacKinnon, James G. (1993).
      "Estimation and Inference in Econometrics," OUP Catalogue,
      Oxford University Press
    - Cameron, A. C., & Trivedi, P. K. (2005).
      "Microeconometrics: methods and applications,"
      Cambridge university press

    """
    self.covariance_matrix_: Union[np.ndarray, None]

    if robust is None:
        _robust = getattr(self, "robust", True)
    else:
        _robust = robust

    if expected_information is None:
        _expected_information = getattr(self, "expected_information", False)
    else:
        _expected_information = expected_information

    if (
        (
            hasattr(self, "alpha")
            and isinstance(self.alpha, (int, float))
            and self.alpha > 0
        )
        or (hasattr(self, "alpha_") and self.alpha_ > 0)  # glm_cv
        or (hasattr(self, "_alphas") and self._alphas[-1] > 0)  # alpha_search
    ):
        warnings.warn(
            "Covariance matrix estimation assumes that the model is not "
            "penalized. You are estimating a penalized model. The covariance "
            "matrix will be incorrect."
        )

    cannot_estimate_cov = (y is None) and not hasattr(self, "y_model_spec_")
    cannot_estimate_cov |= X is None

    if not skip_checks:
        if cannot_estimate_cov and self.covariance_matrix_ is None:
            raise ValueError(
                "Either X and y must be provided or the covariance matrix "
                "must have been previously computed."
            )

        if cannot_estimate_cov and store_covariance_matrix:
            raise ValueError(
                "X and y must be provided if 'store_covariance_matrix' is True."
            )

        if store_covariance_matrix and self.covariance_matrix_ is not None:
            warnings.warn(
                "A covariance matrix has already been computed. "
                "It will be overwritten."
            )

        if X is None and y is None:
            if (
                offset is not None
                or mu is not None
                or offset is not None
                or sample_weight is not None
                or dispersion is not None
                or robust is not None
                or clusters is not None
                or expected_information is not None
            ):
                raise ValueError(
                    "Cannot reestimate the covariance matrix with different "
                    "parameters if X and y are not provided."
                )
            return self.covariance_matrix_

        if hasattr(self, "y_model_spec_"):
            y = self.y_model_spec_.get_model_matrix(X).toarray().ravel()
            # This has to go first because X is modified in the next line

        if nw.dependencies.is_into_dataframe(X):
            X = self._convert_from_df(X, context=capture_context(context))

        X, y = check_X_y_tabmat_compliant(
            X,
            y,
            accept_sparse=["csr", "csc", "coo"],
            dtype="numeric",
            copy=self._should_copy_X(),
            ensure_2d=True,
            allow_nd=False,
            drop_first=getattr(self, "drop_first", False),
        )

        if isinstance(X, np.ndarray):
            X = tm.DenseMatrix(X)
        if sparse.issparse(X) and not isinstance(X, tm.SparseMatrix):
            X = tm.SparseMatrix(X)

        sample_weight = check_weights(
            sample_weight,
            y.shape[0],
            X.dtype,
            force_all_finite=self.force_all_finite,
        )
        offset = check_offset(offset, y.shape[0], X.dtype)

    sum_weights = np.sum(sample_weight)  # type: ignore

    mu = self.predict(X, offset=offset) if mu is None else np.asanyarray(mu)

    if dispersion is None:
        # sample_weight here need to be non-normalized to count the number
        # of observations.
        dispersion = self._family_instance.dispersion(
            y,
            mu,
            sample_weight=sample_weight,
            ddof=X.shape[1] + self.fit_intercept,
            method="pearson",
        )

    if (
        np.linalg.cond(safe_toarray(X.sandwich(np.ones(X.shape[0]))))
        > 1 / sys.float_info.epsilon**2
    ):
        raise np.linalg.LinAlgError(
            "Matrix is singular. Cannot estimate standard errors."
        )

    if _robust or clusters is not None:
        if _expected_information:
            oim_fct = self._family_instance._fisher_information
        else:
            oim_fct = self._family_instance._observed_information
        oim = oim_fct(
            self._link_instance,
            X,
            y,
            mu,
            sample_weight,
            dispersion,
            self.fit_intercept,
        )
        gradient = self._family_instance._score_matrix(
            self._link_instance,
            X,
            y,
            mu,
            sample_weight,
            dispersion,
            self.fit_intercept,
        )
        if clusters is not None:
            n_groups = len(np.unique(clusters))
            grouped_gradient = _group_sum(clusters, gradient)
            inner_part = grouped_gradient.T @ grouped_gradient
            correction = (n_groups / (n_groups - 1)) * (
                (sum_weights - 1)
                / (sum_weights - self.n_features_in_ - int(self.fit_intercept))
            )
        else:
            inner_part = gradient.sandwich(np.ones_like(y, dtype=X.dtype))
            correction = sum_weights / (
                sum_weights - self.n_features_in_ - int(self.fit_intercept)
            )
        vcov = linalg.solve(oim, linalg.solve(oim, safe_toarray(inner_part)).T)
        vcov *= correction
    else:
        fisher = self._family_instance._fisher_information(
            self._link_instance,
            X,
            y,
            mu,
            sample_weight,
            dispersion,
            self.fit_intercept,
        )
        vcov = linalg.inv(safe_toarray(fisher))
        vcov *= sum_weights / (
            sum_weights - self.n_features_in_ - int(self.fit_intercept)
        )

    if store_covariance_matrix:
        self.covariance_matrix_ = vcov

    return vcov

score

score(X: ShapedArrayLike, y: VectorLike, sample_weight: Optional[VectorLike] = None, offset: Optional[ArrayLike] = None, *, context: Optional[Union[int, Mapping[str, Any]]] = None)

Compute \(D^2\), the percentage of deviance explained.

\(D^2\) is a generalization of the coefficient of determination \(R^2\). The \(R^2\) uses the squared error and the \(D^2\), the deviance. Note that those two are equal for family='normal'.

\(D^2\) is defined as \(D^2 = 1 - \frac{D(y_{\mathrm{true}}, y_{\mathrm{pred}})} {D_{\mathrm{null}}}\), \(D_{\mathrm{null}}\) is the null deviance, i.e. the deviance of a model with intercept alone. The best possible score is one and it can be negative.

Parameters:

Name Type Description Default
X array-like, sparse matrix

Test samples.

array-like
y (array - like, shape(n_samples))

True values of target.

required
sample_weight (array - like, shape(n_samples), optional(default=None))

Sample weights.

None
offset (array - like, shape(n_samples), optional(default=None))
None
context Optional[Union[int, Mapping[str, Any]]]

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None

Returns:

Type Description
float

D^2 of self.predict(X) w.r.t. y.

Source code in src/glum/_glm.py
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
def score(
    self,
    X: ShapedArrayLike,
    y: VectorLike,
    sample_weight: Optional[VectorLike] = None,
    offset: Optional[ArrayLike] = None,
    *,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
):
    """Compute $D^2$, the percentage of deviance explained.

    $D^2$ is a generalization of the coefficient of determination
    $R^2$. The $R^2$ uses the squared error and the $D^2$,
    the deviance. Note that those two are equal for `family='normal'`.

    $D^2$ is defined as
    $D^2 = 1 - \\frac{D(y_{\\mathrm{true}}, y_{\\mathrm{pred}})}
    {D_{\\mathrm{null}}}$,
    $D_{\\mathrm{null}}$ is the null deviance, i.e. the deviance of a
    model with intercept alone. The best possible score is one and it can be
    negative.

    Parameters
    ----------
    X : {array-like, sparse matrix}, shape (n_samples, n_features)
        Test samples.

    y : array-like, shape (n_samples,)
        True values of target.

    sample_weight : array-like, shape (n_samples,), optional (default=None)
        Sample weights.

    offset : array-like, shape (n_samples,), optional (default=None)

    context : Optional[Union[int, Mapping[str, Any]]], default=None
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.

    Returns
    -------
    float
        D^2 of self.predict(X) w.r.t. y.
    """
    sample_weight = check_weights(sample_weight, y.shape[0], y.dtype)

    mu = self.predict(X, offset=offset, context=context)
    y_mean: float = np.average(y, weights=sample_weight)

    dev = self.family_instance.deviance(y, mu, sample_weight=sample_weight)
    dev_null = self.family_instance.deviance(y, y_mean, sample_weight=sample_weight)

    return 1 - dev / dev_null

fit

fit(X: ArrayLike, y: Optional[ArrayLike] = None, sample_weight: Optional[ArrayLike] = None, offset: Optional[ArrayLike] = None, *, store_covariance_matrix: bool = False, clusters: Optional[ndarray] = None, weights_sum: Optional[float] = None, context: Optional[Union[int, Mapping[str, Any]]] = None)

Fit a Generalized Linear Model.

Parameters:

Name Type Description Default
X array-like, sparse matrix

Training data. Note that a float32 matrix is acceptable and will result in the entire algorithm being run in 32-bit precision. However, for problems that are poorly conditioned, this might result in poor convergence or flawed parameter estimates. If a Pandas data frame is provided, it may contain categorical columns. In that case, a separate coefficient will be estimated for each category. No category is omitted. This means that some regularization is required to fit models with an intercept or models with several categorical columns.

array-like
y (array - like, shape(n_samples))

Target values.

None
sample_weight (array - like, shape(n_samples), optional(default=None))

Individual weights w_i for each sample. Note that, for an Exponential Dispersion Model (EDM), one has \(\mathrm{var}(y_i) = \phi \times v(mu) / w_i\). If \(y_i \sim EDM(\mu, \phi / w_i)\), then \(\sum w_i y_i / \sum w_i \sim EDM(\mu, \phi / \sum w_i)\), i.e. the mean of \(y\) is a weighted average with weights equal to sample_weight.

None
offset Optional[ArrayLike]

Added to linear predictor. An offset of 3 will increase expected y by 3 if the link is linear and will multiply expected y by 3 if the link is logarithmic.

None
store_covariance_matrix (bool, optional(default=False))

Whether to estimate and store the covariance matrix of the parameter estimates. If True, the covariance matrix will be available in the covariance_matrix_ attribute after fitting.

False
clusters array - like

Array with cluster membership. Clustered standard errors are computed if clusters is not None.

None
context Optional[Union[int, Mapping[str, Any]]]

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None
weights_sum Optional[float]
None

Returns:

Type Description
self
Source code in src/glum/_glm.py
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
def fit(
    self,
    X: ArrayLike,
    y: Optional[ArrayLike] = None,
    sample_weight: Optional[ArrayLike] = None,
    offset: Optional[ArrayLike] = None,
    *,
    store_covariance_matrix: bool = False,
    clusters: Optional[np.ndarray] = None,
    # TODO: take out weights_sum (or use it properly)
    weights_sum: Optional[float] = None,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
):
    """Fit a Generalized Linear Model.

    Parameters
    ----------
    X : {array-like, sparse matrix}, shape (n_samples, n_features)
        Training data. Note that a `float32` matrix is acceptable and will
        result in the entire algorithm being run in 32-bit precision.
        However, for problems that are poorly conditioned, this might result
        in poor convergence or flawed parameter estimates. If a Pandas data
        frame is provided, it may contain categorical columns. In that case,
        a separate coefficient will be estimated for each category. No
        category is omitted. This means that some regularization is required
        to fit models with an intercept or models with several categorical
        columns.

    y : array-like, shape (n_samples,)
        Target values.

    sample_weight : array-like, shape (n_samples,), optional (default=None)
        Individual weights w_i for each sample. Note that, for an
        Exponential Dispersion Model (EDM), one has
        $\\mathrm{var}(y_i) = \\phi \\times v(mu) / w_i$.
        If $y_i \\sim EDM(\\mu, \\phi / w_i)$, then
        $\\sum w_i y_i / \\sum w_i \\sim EDM(\\mu, \\phi / \\sum w_i)$,
        i.e. the mean of $y$ is a weighted average with weights equal
        to `sample_weight`.

    offset: array-like, shape (n_samples,), optional (default=None)
        Added to linear predictor. An offset of 3 will increase expected
        `y` by 3 if the link is linear and will multiply expected `y` by
        3 if the link is logarithmic.

    store_covariance_matrix : bool, optional (default=False)
        Whether to estimate and store the covariance matrix of the parameter
        estimates. If `True`, the covariance matrix will be available in the
        `covariance_matrix_` attribute after fitting.

    clusters : array-like, optional, default=None
        Array with cluster membership. Clustered standard errors are
        computed if clusters is not None.

    context : Optional[Union[int, Mapping[str, Any]]], default=None
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.

    weights_sum: float, optional (default=None)

    Returns
    -------
    self
    """

    self._validate_hyperparameters()
    self._align_info_logs_emitted: set[str] = set()

    # NOTE: This function checks if all the entries in X and y are
    # finite. That can be expensive. But probably worthwhile.
    (
        X,
        y,
        sample_weight,
        offset,
        weights_sum,
        P1,
        P2,
    ) = self._set_up_and_check_fit_args(
        X,
        y,
        sample_weight,
        offset,
        force_all_finite=self.force_all_finite,
        context=capture_context(context),
    )

    assert isinstance(X, tm.MatrixBase)
    assert isinstance(y, np.ndarray)

    self._set_up_for_fit(y)

    # 1.3 arguments to take special care ##################################
    # P1, P2, start_params
    stype = ["csc"] if self._solver == "irls-cd" else ["csc", "csr"]
    P1_no_alpha = setup_p1(P1, X, X.dtype, 1, self.l1_ratio)
    P2_no_alpha = setup_p2(P2, X, stype, X.dtype, 1, self.l1_ratio)

    lower_bounds = check_bounds(self.lower_bounds, X.shape[1], X.dtype)
    upper_bounds = check_bounds(self.upper_bounds, X.shape[1], X.dtype)

    _A: Optional[np.ndarray]
    _b: Optional[np.ndarray]
    if self.monotonic_constraints is not None:
        _A, _b = self._resolve_monotonic_constraints()
    elif self.A_ineq is not None and self.b_ineq is not None:
        _A, _b = self.A_ineq, self.b_ineq
    else:
        _A, _b = None, None

    A_ineq, b_ineq = check_inequality_constraints(
        _A, _b, n_features=X.shape[1], dtype=X.dtype
    )

    if (lower_bounds is not None) and (upper_bounds is not None):
        if np.any(lower_bounds > upper_bounds):
            raise ValueError("Upper bounds must be higher than lower bounds.")

    # 1.4 additional validations ##########################################
    if self.check_input:
        # check if P2 is positive semidefinite
        if not isinstance(self.P2, str):  # self.P2 != 'identity'
            if not is_pos_semidef(P2_no_alpha):
                if P2_no_alpha.ndim == 1 or P2_no_alpha.shape[0] == 1:
                    error = "1d array P2 must not have negative values."
                else:
                    error = "P2 must be positive semi-definite."
                raise ValueError(error)
        # TODO: if alpha=0 check that X is not rank deficient
        # TODO: what else to check?

    #######################################################################
    # 2c. potentially rescale predictors
    #######################################################################

    (
        X,
        self.col_means_,
        self.col_stds_,
        lower_bounds,
        upper_bounds,
        A_ineq,
        P1_no_alpha,
        P2_no_alpha,
    ) = standardize(
        X,
        sample_weight,
        self._center_predictors,
        self.scale_predictors,
        lower_bounds,
        upper_bounds,
        A_ineq,
        P1_no_alpha,
        P2_no_alpha,
    )

    #######################################################################
    # 3. initialization of coef = (intercept_, coef_)                     #
    #######################################################################

    coef = self._get_start_coef(
        X,
        y,
        sample_weight,
        offset,
        self.col_means_,
        self.col_stds_,
        dtype=[np.float64, np.float32],
    )

    #######################################################################
    # 4. fit                                                              #
    #######################################################################
    if self.alpha_search:
        if self.alphas is not None:
            warnings.warn(
                "alphas is deprecated. Use alpha instead.", DeprecationWarning
            )
            self._alphas = self.alphas
        elif self.alpha is None:
            self._alphas = self._get_alpha_path(
                P1_no_alpha=P1_no_alpha, X=X, y=y, w=sample_weight, offset=offset
            )
        else:
            self._alphas = self.alpha
            if self.min_alpha is not None or self.min_alpha_ratio is not None:
                warnings.warn(
                    "`alpha` is set. Ignoring `min_alpha` and `min_alpha_ratio`."
                )

        coef = self._solve_regularization_path(
            X=X,
            y=y,
            sample_weight=sample_weight,
            P2_no_alpha=P2_no_alpha,
            P1_no_alpha=P1_no_alpha,
            alphas=self._alphas,
            coef=coef,
            offset=offset,
            lower_bounds=lower_bounds,
            upper_bounds=upper_bounds,
            A_ineq=A_ineq,
            b_ineq=b_ineq,
        )

        self._warn_if_saturated(X, coef[-1], offset)

        # intercept_ and coef_ return the last estimated alpha
        if self.fit_intercept:
            self.intercept_path_, self.coef_path_ = unstandardize(
                self.col_means_, self.col_stds_, coef[:, 0], coef[:, 1:]
            )
            self.intercept_ = self.intercept_path_[-1]  # type: ignore
            self.coef_ = self.coef_path_[-1]
        else:
            # set intercept to zero as the other linear models do
            self.intercept_path_, self.coef_path_ = unstandardize(
                self.col_means_, self.col_stds_, np.zeros(coef.shape[0]), coef
            )
            self.intercept_ = 0.0
            self.coef_ = self.coef_path_[-1]
    else:
        if self.alpha is None:
            _alpha = 0.0
        else:
            _alpha = self.alpha
        if _alpha > 0 and self.l1_ratio > 0 and self._solver != "irls-cd":
            raise ValueError(
                f"The chosen solver (solver={self._solver}) can't deal "
                "with L1 penalties, which are included with "
                f"(alpha={_alpha}) and (l1_ratio={self.l1_ratio})."
            )
        coef = self._solve(
            X=X,
            y=y,
            sample_weight=sample_weight,
            P2=P2_no_alpha * _alpha,
            P1=P1_no_alpha * _alpha,
            coef=coef,
            offset=offset,
            lower_bounds=lower_bounds,
            upper_bounds=upper_bounds,
            A_ineq=A_ineq,
            b_ineq=b_ineq,
        )

        self._warn_if_saturated(X, coef, offset)

        if self.fit_intercept:
            self.intercept_, self.coef_ = unstandardize(
                self.col_means_, self.col_stds_, coef[0], coef[1:]
            )
        else:
            # set intercept to zero as the other linear models do
            self.intercept_, self.coef_ = unstandardize(
                self.col_means_, self.col_stds_, 0.0, coef
            )

    self.covariance_matrix_ = None
    if store_covariance_matrix:
        self.covariance_matrix(
            X=X.unstandardize(),
            y=y,
            offset=offset,
            sample_weight=sample_weight * weights_sum,
            robust=getattr(self, "robust", True),
            clusters=clusters,
            expected_information=getattr(self, "expected_information", False),
            store_covariance_matrix=True,
            skip_checks=True,
        )

    return self

aic

aic(X: ArrayLike, y: VectorLike, sample_weight: Optional[ArrayLike] = None, *, context: Optional[Union[int, Mapping[str, Any]]] = None)

Akaike's information criteria. Computed as: \(-2\log\hat{\mathcal{L}} + 2\hat{k}\) where \(\hat{\mathcal{L}}\) is the maximum likelihood estimate of the model, and \(\hat{k}\) is the effective number of parameters. See _compute_information_criteria for more information on the computation of \(\hat{k}\).

Parameters:

Name Type Description Default
X array-like, sparse matrix

Same data as used in 'fit'

array-like
y (array - like, shape(n_samples))

Same data as used in 'fit'

required
sample_weight (array - like, shape(n_samples), optional(default=None))

Same data as used in 'fit'

None
context Optional[Union[int, Mapping[str, Any]]]

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None
Source code in src/glum/_glm.py
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
def aic(
    self,
    X: ArrayLike,
    y: VectorLike,
    sample_weight: Optional[ArrayLike] = None,
    *,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
):
    """
    Akaike's information criteria. Computed as:
    $-2\\log\\hat{\\mathcal{L}} + 2\\hat{k}$ where
    $\\hat{\\mathcal{L}}$ is the maximum likelihood estimate of the
    model, and $\\hat{k}$ is the effective number of parameters. See
    `_compute_information_criteria` for more information on the computation
    of $\\hat{k}$.

    Parameters
    ----------
    X : {array-like, sparse matrix}, shape (n_samples, n_features)
        Same data as used in 'fit'

    y : array-like, shape (n_samples,)
        Same data as used in 'fit'

    sample_weight : array-like, shape (n_samples,), optional (default=None)
        Same data as used in 'fit'

    context : Optional[Union[int, Mapping[str, Any]]], default=None
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.
    """
    return self._get_info_criteria("aic", X, y, sample_weight, context=context)

aicc

aicc(X: ArrayLike, y: VectorLike, sample_weight: Optional[ArrayLike] = None, *, context: Optional[Union[int, Mapping[str, Any]]] = None)

Second-order Akaike's information criteria (or small sample AIC). Computed as: \(-2\log\hat{\mathcal{L}} + 2\hat{k} + \frac{2k(k+1)}{n-k-1}\) where \(\hat{\mathcal{L}}\) is the maximum likelihood estimate of the model, \(n\) is the number of training instances, and \(\hat{k}\) is the effective number of parameters. See _compute_information_criteria for more information on the computation of \(\hat{k}\).

Parameters:

Name Type Description Default
X array-like, sparse matrix

Same data as used in 'fit'

array-like
y (array - like, shape(n_samples))

Same data as used in 'fit'

required
sample_weight (array - like, shape(n_samples), optional(default=None))

Same data as used in 'fit'

None
context Optional[Union[int, Mapping[str, Any]]]

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None
Source code in src/glum/_glm.py
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
def aicc(
    self,
    X: ArrayLike,
    y: VectorLike,
    sample_weight: Optional[ArrayLike] = None,
    *,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
):
    """
    Second-order Akaike's information criteria (or small sample AIC).
    Computed as:
    $-2\\log\\hat{\\mathcal{L}} + 2\\hat{k} + \\frac{2k(k+1)}{n-k-1}$
    where $\\hat{\\mathcal{L}}$ is the maximum likelihood estimate of
    the model, $n$ is the number of training instances, and
    $\\hat{k}$ is the effective number of parameters. See
    `_compute_information_criteria` for more information on the computation
    of $\\hat{k}$.

    Parameters
    ----------
    X : {array-like, sparse matrix}, shape (n_samples, n_features)
        Same data as used in 'fit'

    y : array-like, shape (n_samples,)
        Same data as used in 'fit'

    sample_weight : array-like, shape (n_samples,), optional (default=None)
         Same data as used in 'fit'

    context : Optional[Union[int, Mapping[str, Any]]], default=None
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.
    """
    aicc = self._get_info_criteria("aicc", X, y, sample_weight, context=context)

    if not aicc:
        msg = "Model degrees of freedom should be more than training data points."
        raise ValueError(msg)

    return aicc

bic

bic(X: ArrayLike, y: VectorLike, sample_weight: Optional[ArrayLike] = None, *, context: Optional[Union[int, Mapping[str, Any]]] = None)

Bayesian information criterion. Computed as: \(-2\log\hat{\mathcal{L}} + k\log(n)\) where \(\hat{\mathcal{L}}\) is the maximum likelihood estimate of the model, \(n\) is the number of training instances, and \(\hat{k}\) is the effective number of parameters. See _compute_information_criteria for more information on the computation of \(\hat{k}\).

Parameters:

Name Type Description Default
X array-like, sparse matrix

Same data as used in 'fit'

array-like
y (array - like, shape(n_samples))

Same data as used in 'fit'

required
sample_weight (array - like, shape(n_samples), optional(default=None))

Same data as used in 'fit'

None
context Optional[Union[int, Mapping[str, Any]]]

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None
Source code in src/glum/_glm.py
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
def bic(
    self,
    X: ArrayLike,
    y: VectorLike,
    sample_weight: Optional[ArrayLike] = None,
    *,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
):
    """
    Bayesian information criterion. Computed as:
    $-2\\log\\hat{\\mathcal{L}} + k\\log(n)$ where
    $\\hat{\\mathcal{L}}$ is the maximum likelihood estimate of the
    model, $n$ is the number of training instances, and
    $\\hat{k}$ is the effective number of parameters. See
    `_compute_information_criteria` for more information on the computation
    of $\\hat{k}$.

    Parameters
    ----------
    X : {array-like, sparse matrix}, shape (n_samples, n_features)
        Same data as used in 'fit'

    y : array-like, shape (n_samples,)
        Same data as used in 'fit'

    sample_weight : array-like, shape (n_samples,), optional (default=None)
         Same data as used in 'fit'

    context : Optional[Union[int, Mapping[str, Any]]], default=None
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.
    """
    return self._get_info_criteria("bic", X, y, sample_weight, context=context)

GeneralizedLinearRegressorCV

GeneralizedLinearRegressorCV(*, l1_ratio=0, P1='identity', P2='identity', fit_intercept=True, family: Union[str, ExponentialDispersionModel] = 'normal', link: Union[str, Link] = 'auto', solver: str = 'auto', max_iter=100, max_inner_iter=100000, gradient_tol: Optional[float] = None, step_size_tol: Optional[float] = None, hessian_approx: float = 0.0, warm_start: bool = False, n_alphas: int = 100, alphas: Optional[ndarray] = None, min_alpha_ratio: Optional[float] = None, min_alpha: Optional[float] = None, start_params: Optional[ndarray] = None, selection: str = 'cyclic', random_state=None, copy_X: Optional[bool] = None, check_input: bool = True, verbose=0, scale_predictors: bool = False, lower_bounds: Optional[ndarray] = None, upper_bounds: Optional[ndarray] = None, A_ineq: Optional[ndarray] = None, b_ineq: Optional[ndarray] = None, monotonic_constraints: Optional[Mapping[str, str]] = None, force_all_finite: bool = True, cv=None, n_jobs: Optional[int] = None, drop_first: bool = False, robust: bool = True, expected_information: bool = False, formula: Optional[FormulaSpec] = None, interaction_separator: str = ':', categorical_format: str = '{name}[{category}]', cat_missing_method: str = 'fail', cat_missing_name: str = '(MISSING)')

Bases: GeneralizedLinearRegressorBase

Generalized linear model with iterative fitting along a regularization path.

The best model is selected by cross-validation.

Cross-validated regression via a Generalized Linear Model (GLM) with penalties. For more on GLMs and on these parameters, see the documentation for GeneralizedLinearRegressor.

Parameters:

Name Type Description Default
l1_ratio float or array of floats, optional (default=0)

If you pass l1_ratio as an array, the fit method will choose the best value of l1_ratio and store it as self.l1_ratio.

0
P1 (identity, array - like, None)

(default='identity') This array controls the strength of the regularization for each coefficient independently. A high value will lead to higher regularization while a value of zero will remove the regularization on this parameter. Note that n_features = X.shape[1]. If X is a pandas DataFrame with a categorical dtype and P1 has the same size as the number of columns, the penalty of the categorical column will be applied to all the levels of the categorical.

'identity'
P2 'identity', array-like, sparse matrix, None

With this option, you can set the P2 matrix in the L2 penalty w*P2*w. This gives a fine control over this penalty (Tikhonov regularization). A 2d array is directly used as the square matrix P2. A 1d array is interpreted as diagonal (square) matrix. The default 'identity' and None set the identity matrix, which gives the usual squared L2-norm. If you just want to exclude certain coefficients, pass a 1d array filled with 1 and 0 for the coefficients to be excluded. Note that P2 must be positive semi-definite. If X is a pandas DataFrame with a categorical dtype and P2 has the same size as the number of columns, the penalty of the categorical column will be applied to all the levels of the categorical. Note that if P2 is two-dimensional, its size needs to be of the same length as the expanded X matrix.

'identity'
fit_intercept (bool, optional(default=True))

Specifies if a constant (a.k.a. bias or intercept) should be added to the linear predictor (X * coef + intercept).

True
family (str or ExponentialDispersionModel, optional(default=normal))

The distributional assumption of the GLM, i.e. the loss function to minimize. If a string, one of: 'binomial', 'gamma', 'gaussian', 'inverse.gaussian', 'normal', 'poisson', 'tweedie' or 'negative.binomial'. Note that 'tweedie' sets the power of the Tweedie distribution to 1.5; to use another value, specify it in parentheses (e.g., 'tweedie (1.5)'). The same applies for 'negative.binomial' and theta parameter.

'normal'
link (auto, identity, log, logit, cloglog)

The link function of the GLM, i.e. mapping from linear predictor (X * coef) to expectation (mu). Option 'auto' sets the link depending on the chosen family as follows:

  • 'identity' for family 'normal'
  • 'log' for families 'poisson', 'gamma', 'inverse.gaussian' and 'negative.binomial'.
  • 'logit' for family 'binomial'
'auto'
solver (auto, closed - form, irls - cd, irls - ls, lbfgs, trust - constr)

Algorithm to use in the optimization problem:

  • 'auto': 'closed-form' for eligible Gaussian identity-link problems without L1 regularization, 'irls-ls' for other pure-L2 cases, and 'irls-cd' otherwise.
  • 'closed-form': Direct linear solve for eligible Gaussian identity-link problems (ridge/OLS/WLS).
  • 'irls-cd': Iteratively reweighted least squares with a coordinate descent inner solver. This can deal with L1 as well as L2 penalties. Note that in order to avoid unnecessary memory duplication of X in the fit method, X should be directly passed as a Fortran-contiguous Numpy array or sparse CSC matrix.
  • 'irls-ls': Iteratively reweighted least squares with a least squares inner solver. This algorithm cannot deal with L1 penalties.
  • 'lbfgs': Scipy's L-BFGS-B optimizer. It cannot deal with L1 penalties.
'auto'
max_iter (int, optional(default=100))

The maximal number of iterations for solver algorithms.

100
max_inner_iter

The maximal number of iterations for the inner solver in the IRLS-CD algorithm. This parameter is only used when solver='irls-cd'.

100000
gradient_tol (float, optional(default=None))

Stopping criterion. If None, solver-specific defaults will be used. The default value for most solvers is 1e-4, except for 'trust-constr', which requires more conservative convergence settings and has a default value of 1e-8.

For the IRLS-LS, L-BFGS and trust-constr solvers, the iteration will stop when max{|g_i|, i = 1, ..., n} <= tol, where g_i is the i-th component of the gradient (derivative) of the objective function. For the CD solver, convergence is reached when sum_i(|minimum norm of g_i|), where g_i is the subgradient of the objective and the minimum norm of g_i is the element of the subgradient with the smallest L2 norm.

If you wish to only use a step-size tolerance, set gradient_tol to a very small number.

None
step_size_tol Optional[float]

Alternative stopping criterion. For the IRLS-LS and IRLS-CD solvers, the iteration will stop when the L2 norm of the step size is less than step_size_tol. This stopping criterion is disabled when step_size_tol is None.

None
hessian_approx float

The threshold below which data matrix rows will be ignored for updating the Hessian. See the algorithm documentation for the IRLS algorithm for further details.

0.0
warm_start (bool, optional(default=False))

Whether to reuse the solution of the previous call to fit as initialization for coef_ and intercept_ (supersedes start_params). If False or if the attribute coef_ does not exist (first call to fit), start_params sets the start values for coef_ and intercept_.

False
n_alphas (int, optional(default=100))

Number of alphas along the regularization path

100
alphas (array - like, optional(default=None))

List of alphas for which to compute the models. If None, the alphas are set automatically. Setting None is preferred.

None
min_alpha_ratio (float, optional(default=None))

Length of the path. min_alpha_ratio=1e-6 means that min_alpha / max_alpha = 1e-6. If None, 1e-6 is used when n_samples >= n_features, else 1e-2.

None
min_alpha (float, optional(default=None))

Minimum alpha to estimate the model with. The grid will then be created over [max_alpha, min_alpha].

None
start_params array-like, shape (n_features*,), optional (default=None)

Relevant only if warm_start is False or if fit is called for the first time (so that self.coef_ does not exist yet). If None, all coefficients are set to zero and the start value for the intercept is the weighted average of y (If fit_intercept is True). If an array, used directly as start values; if fit_intercept is True, its first element is assumed to be the start value for the intercept_. Note that n_features* = X.shape[1] + fit_intercept, i.e. it includes the intercept.

None
selection (str, optional(default=cyclic))

For the CD solver 'cd', the coordinates (features) can be updated in either cyclic or random order. If set to 'random', a random coefficient is updated every iteration rather than looping over features sequentially in the same order, which often leads to significantly faster convergence, especially when gradient_tol is higher than 1e-4.

'cyclic'
random_state (int or RandomState, optional(default=None))

The seed of the pseudo random number generator that selects a random feature to be updated for the CD solver. If an integer, random_state is the seed used by the random number generator; if a RandomState instance, random_state is the random number generator; if None, the random number generator is the RandomState instance used by np.random. Used when selection is 'random'.

None
copy_X (bool, optional(default=None))

Whether to copy X. Since X is never modified by GeneralizedLinearRegressor, this is unlikely to be needed; this option exists mainly for compatibility with other scikit-learn estimators. If False, X will not be copied and there will be an error if you pass an X in the wrong format, such as providing integer X and float y (only guaranteed for numpy arrays and pandas data frames). If None, X will not be copied unless it is in the wrong format.

None
check_input (bool, optional(default=True))

Whether to bypass several checks on input: y values in range of family, sample_weight non-negative, P2 positive semi-definite. Don't use this parameter unless you know what you are doing.

True
verbose (int, optional(default=0))

For the IRLS solver, any positive number will result in a pretty progress bar showing convergence. This features requires having the tqdm package installed. For the L-BFGS solver, set verbose to any positive number for verbosity.

0
scale_predictors bool

If True, estimate a scaled model where all predictors have a standard deviation of 1. This can result in better estimates if predictors are on very different scales (for example, centimeters and kilometers).

Advanced developer note: Internally, predictors are always rescaled for computational reasons, but this only affects results if scale_predictors is True.

False
lower_bounds (array - like, shape(n_features), optional(default=None))

Set a lower bound for the coefficients. Setting bounds forces the use of the coordinate descent solver ('irls-cd').

None
upper_bounds array-like, shape=(n_features), optional (default=None)

See lower_bounds.

None
A_ineq array-like, shape=(n_constraints, n_features), optional (default=None)

Constraint matrix for linear inequality constraints of the form A_ineq w <= b_ineq.

None
b_ineq array-like, shape=(n_constraints,), optional (default=None)

Constraint vector for linear inequality constraints of the form A_ineq w <= b_ineq.

None
monotonic_constraints (dict, optional(default=None))

Mapping from variable names in formula (e.g. "x") to "increasing" or "decreasing". For single-column numeric variables, including transforms like np.log(x), constrains the sign of the coefficient. For bs() splines, categoricals and booleans, orders consecutive coefficients (including an implicit zero for a dropped first column). Other transforms are not supported. Categoricals must be ordered (pandas Categorical with ordered=True or polars Enum); their coefficients follow the category order.

None
cv int, cross-validation generator or Iterable, optional (default=None)

Determines the cross-validation splitting strategy. One of:

  • None, to use the default 5-fold cross-validation,
  • int, to specify the number of folds.
  • Iterable yielding (train, test) splits as arrays of indices.

For integer/None inputs, KFold is used

None
n_jobs (int, optional(default=None))

The maximum number of concurrently running jobs. The number of jobs that are needed is len(l1_ratio) x n_folds. -1 is the same as the number of CPU on your machine. None means 1 unless in a joblib.parallel_backend context.

None
drop_first (bool, optional(default=False))

If True, drop the first column when encoding categorical variables. Set this to True when alpha=0 and solver='auto' to prevent an error due to a singular feature matrix. In the case of using a formula with interactions, setting this argument to True ensures structural full-rankness (it is equivalent to ensure_full_rank in formulaic and tabmat).

False
formula FormulaSpec

A formula accepted by formulaic. It can either be a one-sided formula, in which case y must be specified in fit, or a two-sided formula, in which case y must be None.

None
interaction_separator str

The separator between the names of interacted variables.

':'
categorical_format str

The format string used to generate the names of categorical variables. Has to include the placeholders {name} and {category}. Only used if formula is not None.

'{name}[{category}]'

Attributes:

Name Type Description
alpha_ float

The amount of regularization chosen by cross validation.

alphas_ (array, shape(n_l1_ratios, n_alphas))

Alphas used by the model.

l1_ratio_ float

The compromise between L1 and L2 regularization chosen by cross validation.

coef_ (array, shape(n_features))

Estimated coefficients for the linear predictor in the GLM at the optimal (l1_ratio_, alpha_).

intercept_ float

Intercept (a.k.a. bias) added to linear predictor.

n_iter_ int

The number of iterations run by the CD solver to reach the specified tolerance for the optimal alpha.

coef_path_ (array, shape(n_folds, n_l1_ratios, n_alphas, n_features))

Estimated coefficients for the linear predictor in the GLM at every point along the regularization path, per fold and l1_ratio.

intercept_path_ (array, shape(n_folds, n_l1_ratios, n_alphas, 1))

Estimated intercepts at every point along the regularization path, per fold and l1_ratio.

deviance_path_ (array, shape(n_folds, n_l1_ratios, n_alphas))

Deviance for the test set on each fold, varying alpha.

train_deviance_path_ (array, shape(n_folds, n_l1_ratios, n_alphas))

Deviance for the training set on each fold, varying alpha.

robust (bool, optional(default=False))

If true, then robust standard errors are computed by default.

expected_information (bool, optional(default=False))

If true, then the expected information matrix is computed by default. Only relevant when computing robust standard errors.

categorical_format (str, optional(default={name}[{category}]))

Format string for categorical features. The format string should contain the placeholder {name} for the feature name and {category} for the category name. Only used if X is a pandas DataFrame.

cat_missing_method str {'fail'|'zero'|'convert'}, default='fail'

How to handle missing values in categorical columns. Only used if X is a pandas data frame.

  • if 'fail', raise an error if there are missing values
  • if 'zero', missing values will represent all-zero indicator columns.
  • if 'convert', missing values will be converted to the cat_missing_name category.
cat_missing_name str, default='(MISSING)'

Name of the category to which missing values will be converted if cat_missing_method='convert'. Only used if X is a pandas data frame.

col_means_ (array, shape(n_features))

The means of the columns of the design matrix X.

col_stds_ (array, shape(n_features))

The standard deviations of the columns of the design matrix X.

feature_names_ list of str

The names of the coefficients.

Source code in src/glum/_glm_cv.py
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
def __init__(
    self,
    *,
    l1_ratio=0,
    P1="identity",
    P2="identity",
    fit_intercept=True,
    family: Union[str, ExponentialDispersionModel] = "normal",
    link: Union[str, Link] = "auto",
    solver: str = "auto",
    max_iter=100,
    max_inner_iter=100000,
    gradient_tol: Optional[float] = None,
    step_size_tol: Optional[float] = None,
    hessian_approx: float = 0.0,
    warm_start: bool = False,
    n_alphas: int = 100,
    alphas: Optional[np.ndarray] = None,
    min_alpha_ratio: Optional[float] = None,
    min_alpha: Optional[float] = None,
    start_params: Optional[np.ndarray] = None,
    selection: str = "cyclic",
    random_state=None,
    copy_X: Optional[bool] = None,
    check_input: bool = True,
    verbose=0,
    scale_predictors: bool = False,
    lower_bounds: Optional[np.ndarray] = None,
    upper_bounds: Optional[np.ndarray] = None,
    A_ineq: Optional[np.ndarray] = None,
    b_ineq: Optional[np.ndarray] = None,
    monotonic_constraints: Optional[Mapping[str, str]] = None,
    force_all_finite: bool = True,
    cv=None,
    n_jobs: Optional[int] = None,
    drop_first: bool = False,
    robust: bool = True,
    expected_information: bool = False,
    formula: Optional[formulaic.FormulaSpec] = None,
    interaction_separator: str = ":",
    categorical_format: str = "{name}[{category}]",
    cat_missing_method: str = "fail",
    cat_missing_name: str = "(MISSING)",
):
    self.alphas = alphas
    self.cv = cv
    self.n_jobs = n_jobs
    super().__init__(
        l1_ratio=l1_ratio,
        P1=P1,
        P2=P2,
        fit_intercept=fit_intercept,
        family=family,
        link=link,
        solver=solver,
        max_iter=max_iter,
        max_inner_iter=max_inner_iter,
        gradient_tol=gradient_tol,
        step_size_tol=step_size_tol,
        hessian_approx=hessian_approx,
        warm_start=warm_start,
        n_alphas=n_alphas,
        min_alpha_ratio=min_alpha_ratio,
        min_alpha=min_alpha,
        start_params=start_params,
        selection=selection,
        random_state=random_state,
        copy_X=copy_X,
        check_input=check_input,
        verbose=verbose,
        scale_predictors=scale_predictors,
        lower_bounds=lower_bounds,
        upper_bounds=upper_bounds,
        A_ineq=A_ineq,
        b_ineq=b_ineq,
        monotonic_constraints=monotonic_constraints,
        force_all_finite=force_all_finite,
        drop_first=drop_first,
        robust=robust,
        expected_information=expected_information,
        formula=formula,
        interaction_separator=interaction_separator,
        categorical_format=categorical_format,
        cat_missing_method=cat_missing_method,
        cat_missing_name=cat_missing_name,
    )

family_instance property

family_instance: ExponentialDispersionModel
link_instance: Link

Return a Link.

report_diagnostics

report_diagnostics(*, full_report: bool = False, custom_columns: Optional[Sequence] = None) -> None

Print diagnostics to stdout.

Parameters:

Name Type Description Default
full_report (bool, optional(default=False))

Print all available information. When False and custom_columns is None, a restricted set of columns is printed out.

False
custom_columns (iterable, optional(default=None))

Print only the specified columns.

None
Source code in src/glum/_glm.py
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
def report_diagnostics(
    self,
    *,
    full_report: bool = False,
    custom_columns: Optional[Sequence] = None,
) -> None:
    """Print diagnostics to `stdout`.

    Parameters
    ----------
    full_report : bool, optional (default=False)
        Print all available information. When `False` and
        `custom_columns` is `None`, a restricted set of columns is
        printed out.

    custom_columns : iterable, optional (default=None)
        Print only the specified columns.
    """
    diagnostics = self.get_formatted_diagnostics(
        full_report=full_report, custom_columns=custom_columns
    )
    if isinstance(diagnostics, str):
        print(diagnostics)
        return

    import pandas as pd

    print("Diagnostics:")
    with pd.option_context("display.max_rows", None, "display.max_columns", None):
        print(diagnostics)

get_formatted_diagnostics

get_formatted_diagnostics(*, full_report: bool = False, custom_columns: Optional[Sequence] = None) -> Union[str, pd.DataFrame]

Get formatted diagnostics which can be printed with report_diagnostics.

Parameters:

Name Type Description Default
full_report (bool, optional(default=False))

Print all available information. When False and custom_columns is None, a restricted set of columns is printed out.

False
custom_columns (iterable, optional(default=None))

Print only the specified columns.

None
Source code in src/glum/_glm.py
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
def get_formatted_diagnostics(
    self,
    *,
    full_report: bool = False,
    custom_columns: Optional[Sequence] = None,
) -> Union[str, pd.DataFrame]:
    """Get formatted diagnostics which can be printed with report_diagnostics.

    Parameters
    ----------
    full_report : bool, optional (default=False)
        Print all available information. When `False` and
        `custom_columns` is `None`, a restricted set of columns is
        printed out.

    custom_columns : iterable, optional (default=None)
        Print only the specified columns.
    """
    if not hasattr(self, "diagnostics_"):
        to_print = "Model has not been fit, so no diagnostics exist."
        return to_print
    if self.diagnostics_ is None:
        to_print = "solver does not report diagnostics"
        return to_print

    import pandas as pd

    df = pd.DataFrame(data=self.diagnostics_).set_index("n_iter", drop=True)
    if self.fit_intercept:
        df["intercept"] = df["first_coef"]
    else:
        df["intercept"] = np.nan

    if custom_columns is not None:
        keep_cols = custom_columns
    elif full_report:
        keep_cols = df.columns
    else:
        keep_cols = ["convergence", "n_cycles", "iteration_runtime", "intercept"]

    return df[keep_cols]

predict

predict(X: ShapedArrayLike, sample_weight: Optional[ArrayLike] = None, offset: Optional[ArrayLike] = None, *, alpha_index: Optional[Union[int, Sequence[int]]] = None, alpha: Optional[Union[float, Sequence[float]]] = None, context: Optional[Union[int, Mapping[str, Any]]] = None)

Predict using GLM with feature matrix X.

If alpha_search is True, but alpha_index and alpha are both None, we use the last alpha value self._alphas[-1].

Parameters:

Name Type Description Default
X (array - like, shape(n_samples, n_features))

Observations. X may be a pandas data frame with categorical types. If X was also a data frame with categorical types during fitting and a category wasn't observed at that point, the corresponding prediction will be numpy.nan.

required
sample_weight (array - like, shape(n_samples), optional(default=None))

Sample weights to multiply predictions by.

None
offset (array - like, shape(n_samples), optional(default=None))
None
alpha_index (int or list[int], optional(default=None))

Sets the index of the alpha(s) to use in case alpha_search is True. Incompatible with alpha (see below).

None
alpha (float or list[float], optional(default=None))

Sets the alpha(s) to use in case alpha_search is True. Incompatible with alpha_index (see above).

None
context Optional[Union[int, Mapping[str, Any]]]

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None

Returns:

Type Description
ndarray

Shape (n_samples,) when no alpha_index / alpha is given or when a scalar alpha is passed. Shape (n_samples, len(alpha_index)) when a sequence is passed.

Source code in src/glum/_glm.py
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
def predict(
    self,
    X: ShapedArrayLike,
    sample_weight: Optional[ArrayLike] = None,
    offset: Optional[ArrayLike] = None,
    *,
    alpha_index: Optional[Union[int, Sequence[int]]] = None,
    alpha: Optional[Union[float, Sequence[float]]] = None,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
):
    """Predict using GLM with feature matrix `X`.

    If `alpha_search` is `True`, but `alpha_index` and `alpha` are
    both `None`, we use the last alpha value `self._alphas[-1]`.

    Parameters
    ----------
    X : array-like, shape (n_samples, n_features)
        Observations. `X` may be a pandas data frame with categorical
        types. If `X` was also a data frame with categorical types during
        fitting and a category wasn't observed at that point, the
        corresponding prediction will be `numpy.nan`.

    sample_weight : array-like, shape (n_samples,), optional (default=None)
        Sample weights to multiply predictions by.

    offset : array-like, shape (n_samples,), optional (default=None)

    alpha_index : int or list[int], optional (default=None)
        Sets the index of the alpha(s) to use in case `alpha_search` is
        `True`. Incompatible with `alpha` (see below).

    alpha : float or list[float], optional (default=None)
        Sets the alpha(s) to use in case `alpha_search` is `True`.
        Incompatible with `alpha_index` (see above).

    context : Optional[Union[int, Mapping[str, Any]]], default=None
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.

    Returns
    -------
    np.ndarray
        Shape `(n_samples,)` when no `alpha_index` / `alpha` is
        given or when a scalar alpha is passed. Shape
        `(n_samples, len(alpha_index))` when a sequence is passed.
    """
    if nw.dependencies.is_into_dataframe(X):
        X = self._convert_from_df(X, context=capture_context(context))
    X = cast(ShapedArrayLikeConverted, X)

    eta = self.linear_predictor(
        X, offset=offset, alpha_index=alpha_index, alpha=alpha, context=context
    )

    mu = self.link_instance.inverse(eta)

    if sample_weight is None:
        return mu

    sample_weight = check_weights(sample_weight, X.shape[0], X.dtype)

    return mu * sample_weight

coef_table

coef_table(X=None, y=None, sample_weight=None, offset=None, *, confidence_level=0.95, mu=None, dispersion=None, robust=None, clusters: ndarray = None, expected_information=None, context: Optional[Union[int, Mapping[str, Any]]] = None)

Get a table of of the regression coefficients.

Includes coefficient estimates, standard errors, t-values, p-values and confidence intervals.

Parameters:

Name Type Description Default
confidence_level float

The confidence level for the confidence intervals.

0.95
X array-like, sparse matrix

Training data. Can be omitted if a covariance matrix has already been computed or if standard errors, etc. are not desired.

array-like
y (array - like, shape(n_samples))

Target values. Can be omitted if a covariance matrix has already been computed.

None
mu array - like

Array with predictions. Estimated if absent.

None
offset array - like

Array with additive offsets.

None
sample_weight (array - like, shape(n_samples))

Individual weights for each sample.

None
dispersion float

The dispersion parameter. Estimated if absent.

None
robust boolean

Whether to compute robust standard errors instead of normal ones. If not specified, the model's robust attribute is used.

None
clusters array - like

Array with cluster membership. Clustered standard errors are computed if clusters is not None.

None
expected_information boolean

Whether to use the expected or observed information matrix. Only relevant when computing robust standard errors. If not specified, the model's expected_information attribute is used.

None
context Optional[Union[int, Mapping[str, Any]]]

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None

Returns:

Type Description
DataFrame

A table of the regression results.

Source code in src/glum/_glm.py
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
def coef_table(
    self,
    X=None,
    y=None,
    sample_weight=None,
    offset=None,
    *,
    confidence_level=0.95,
    mu=None,
    dispersion=None,
    robust=None,
    clusters: np.ndarray = None,
    expected_information=None,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
):
    """Get a table of of the regression coefficients.

    Includes coefficient estimates, standard errors, t-values, p-values
    and confidence intervals.

    Parameters
    ----------
    confidence_level : float, optional, default=0.95
        The confidence level for the confidence intervals.
    X : {array-like, sparse matrix}, shape (n_samples, n_features), optional
        Training data. Can be omitted if a covariance matrix has already
        been computed or if standard errors, etc. are not desired.
    y : array-like, shape (n_samples,), optional
        Target values. Can be omitted if a covariance matrix has already
        been computed.
    mu : array-like, optional, default=None
        Array with predictions. Estimated if absent.
    offset : array-like, optional, default=None
        Array with additive offsets.
    sample_weight : array-like, shape (n_samples,), optional, default=None
        Individual weights for each sample.
    dispersion : float, optional, default=None
        The dispersion parameter. Estimated if absent.
    robust : boolean, optional, default=None
        Whether to compute robust standard errors instead of normal ones.
        If not specified, the model's `robust` attribute is used.
    clusters : array-like, optional, default=None
        Array with cluster membership. Clustered standard errors are
        computed if clusters is not None.
    expected_information : boolean, optional, default=None
        Whether to use the expected or observed information matrix.
        Only relevant when computing robust standard errors.
        If not specified, the model's `expected_information` attribute is used.
    context : Optional[Union[int, Mapping[str, Any]]], default=None
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.

    Returns
    -------
    pandas.DataFrame
        A table of the regression results.
    """
    if self.fit_intercept:
        names = ["intercept"] + list(self.feature_names_)
        beta = np.concatenate([[self.intercept_], self.coef_])
    else:
        names = self.feature_names_
        beta = self.coef_

    if (X is None) and (getattr(self, "covariance_matrix_", None) is None):
        return pd.Series(beta, index=names, name="coef")

    covariance_matrix = self.covariance_matrix(
        X=X,
        y=y,
        mu=mu,
        offset=offset,
        sample_weight=sample_weight,
        dispersion=dispersion,
        robust=robust,
        clusters=clusters,
        expected_information=expected_information,
        context=capture_context(context),
    )

    significance_level = 1 - confidence_level

    std_errors = np.sqrt(np.diag(covariance_matrix))
    ci_lower = beta + stats.norm.ppf(significance_level / 2) * std_errors
    ci_upper = beta + stats.norm.ppf(1 - significance_level / 2) * std_errors
    t_values = beta / std_errors
    p_values = 2.0 * (1.0 - stats.norm.cdf(np.abs(t_values)))

    return pd.DataFrame(
        {
            "coef": beta,
            "se": std_errors,
            "t_value": t_values,
            "p_value": p_values,
            "ci_lower": ci_lower,
            "ci_upper": ci_upper,
        },
        index=names,
    )

wald_test

wald_test(X=None, y=None, sample_weight=None, offset=None, *, R: Optional[ndarray] = None, features: Optional[Union[str, list[str]]] = None, terms: Optional[Union[str, list[str]]] = None, formula: Optional[str] = None, r: Optional[Sequence] = None, mu=None, dispersion=None, robust=None, clusters: ndarray = None, expected_information=None, context: Optional[Union[int, Mapping[str, Any]]] = None) -> WaldTestResult

Compute the Wald test statistic and p-value for a linear hypothesis.

The left hand side of the hypothesis may be specified in the following ways:

  • R: The restriction matrix representing the linear combination of coefficients to test.
  • features: The name of a feature or a list of features to test.
  • terms: The name of a term or a list of terms to test.
  • formula: A formula string specifying the hypothesis to test.

The right hand side of the tested hypothesis is specified by r. In the case of a terms-based test, the null hypothesis is that each coefficient relating to a term equals the corresponding value in r.

Parameters:

Name Type Description Default
X array-like, sparse matrix

Training data. Can be omitted if a covariance matrix has already been computed.

array-like
y (array - like, shape(n_samples))

Target values. Can be omitted if a covariance matrix has already been computed.

None
sample_weight (array - like, shape(n_samples))

Individual weights for each sample.

None
offset array - like

Array with additive offsets.

None
R ndarray

The restriction matrix representing the linear combination of coefficients to test.

None
features Union[str, list[str]]

The name of a feature or a list of features to test.

None
terms Union[str, list[str]]

The name of a term or a list of terms to test. It can cover one or more coefficients. In the case of a model based on a formula, a term is one of the expressions separated by + signs. Otherwise, a term is one column in the input data. As categorical variables need not be one-hot encoded in glum, in their case, the hypothesis to be tested is that the coefficients of all categories are equal to r.

None
r Sequence

The vector representing the values of the linear combination. If None, the test is for whether the linear combinations of the coefficients are zero.

None
mu array - like

Array with predictions. Estimated if absent.

None
dispersion float

The dispersion parameter. Estimated if absent.

None
robust boolean

Whether to compute robust standard errors instead of normal ones. If not specified, the model's robust attribute is used.

None
clusters array - like

Array with cluster membership. Clustered standard errors are computed if clusters is not None.

None
expected_information boolean

Whether to use the expected or observed information matrix. Only relevant when computing robust standard errors. If not specified, the model's expected_information attribute is used.

None
context Optional[Union[int, Mapping[str, Any]]]

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None

Returns:

Type Description
WaldTestResult

NamedTuple with test statistic, p-value, and degrees of freedom.

Source code in src/glum/_glm.py
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
def wald_test(
    self,
    X=None,
    y=None,
    sample_weight=None,
    offset=None,
    *,
    R: Optional[np.ndarray] = None,
    features: Optional[Union[str, list[str]]] = None,
    terms: Optional[Union[str, list[str]]] = None,
    formula: Optional[str] = None,
    r: Optional[Sequence] = None,
    mu=None,
    dispersion=None,
    robust=None,
    clusters: np.ndarray = None,
    expected_information=None,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
) -> WaldTestResult:
    """Compute the Wald test statistic and p-value for a linear hypothesis.

    The left hand side of the hypothesis may be specified in the following ways:

    - `R`: The restriction matrix representing the linear combination of
      coefficients to test.
    - `features`: The name of a feature or a list of features to test.
    - `terms`: The name of a term or a list of terms to test.
    - `formula`: A formula string specifying the hypothesis to test.

    The right hand side of the tested hypothesis is specified by `r`. In the
    case of a `terms`-based test, the null hypothesis is that each coefficient
    relating to a term equals the corresponding value in `r`.

    Parameters
    ----------
    X : {array-like, sparse matrix}, shape (n_samples, n_features), optional
        Training data. Can be omitted if a covariance matrix has already
        been computed.
    y : array-like, shape (n_samples,), optional
        Target values. Can be omitted if a covariance matrix has already
        been computed.
    sample_weight : array-like, shape (n_samples,), optional, default=None
        Individual weights for each sample.
    offset : array-like, optional, default=None
        Array with additive offsets.
    R : np.ndarray, optional, default=None
        The restriction matrix representing the linear combination of coefficients
        to test.
    features : Union[str, list[str]], optional, default=None
        The name of a feature or a list of features to test.
    terms : Union[str, list[str]], optional, default=None
        The name of a term or a list of terms to test. It can cover one or more
        coefficients. In the case of a model based on a formula, a term is one
        of the expressions separated by `+` signs. Otherwise, a term is one column
        in the input data. As categorical variables need not be one-hot encoded in
        glum, in their case, the hypothesis to be tested is that the coefficients
        of all categories are equal to `r`.
    r : Sequence, optional, default=None
        The vector representing the values of the linear combination.
        If None, the test is for whether the linear combinations of the coefficients
        are zero.
    mu : array-like, optional, default=None
        Array with predictions. Estimated if absent.
    dispersion : float, optional, default=None
        The dispersion parameter. Estimated if absent.
    robust : boolean, optional, default=None
        Whether to compute robust standard errors instead of normal ones.
        If not specified, the model's `robust` attribute is used.
    clusters : array-like, optional, default=None
        Array with cluster membership. Clustered standard errors are
        computed if clusters is not None.
    expected_information : boolean, optional, default=None
        Whether to use the expected or observed information matrix.
        Only relevant when computing robust standard errors.
        If not specified, the model's `expected_information` attribute is used.
    context : Optional[Union[int, Mapping[str, Any]]], default=None
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.

    Returns
    -------
    WaldTestResult
        NamedTuple with test statistic, p-value, and degrees of freedom.
    """

    num_lhs_specs = sum(
        [
            R is not None,
            features is not None,
            terms is not None,
            formula is not None,
        ]
    )
    if num_lhs_specs != 1:
        raise ValueError(
            "Exactly one of R, features, terms or formula must be specified. "
            f"Received {num_lhs_specs} specifications."
        )

    kwargs = {
        "X": X,
        "y": y,
        "sample_weight": sample_weight,
        "offset": offset,
        "mu": mu,
        "dispersion": dispersion,
        "robust": robust,
        "clusters": clusters,
        "expected_information": expected_information,
        "context": capture_context(context),
    }

    if R is not None:
        return self._wald_test_matrix(R=R, r=np.asarray(r), **kwargs)
    if features is not None:
        return self._wald_test_feature_names(features=features, values=r, **kwargs)
    if terms is not None:
        return self._wald_test_term_names(terms=terms, values=r, **kwargs)
    if formula is not None:
        if r is not None:
            raise ValueError("Cannot specify both formula and r")
        return self._wald_test_formula(formula=formula, **kwargs)

    raise RuntimeError("This should never happen")

std_errors

std_errors(X=None, y=None, sample_weight=None, offset=None, *, mu=None, dispersion=None, robust=None, clusters: ndarray = None, expected_information=None, store_covariance_matrix=False, context: Optional[Union[int, Mapping[str, Any]]] = None)

Calculate standard errors for generalized linear models.

See covariance_matrix for an in-depth explanation of how the standard errors are computed.

Parameters:

Name Type Description Default
X array-like, sparse matrix

Training data. Can be omitted if a covariance matrix has already been computed.

array-like
y (array - like, shape(n_samples))

Target values. Can be omitted if a covariance matrix has already been computed.

None
sample_weight (array - like, shape(n_samples))

Individual weights for each sample.

None
offset array - like

Array with additive offsets.

None
mu array - like

Array with predictions. Estimated if absent.

None
dispersion float

The dispersion parameter. Estimated if absent.

None
robust boolean

Whether to compute robust standard errors instead of normal ones. If not specified, the model's robust attribute is used.

None
clusters array - like

Array with cluster membership. Clustered standard errors are computed if clusters is not None.

None
expected_information boolean

Whether to use the expected or observed information matrix. Only relevant when computing robust standard errors. If not specified, the model's expected_information attribute is used.

None
store_covariance_matrix boolean

Whether to store the covariance matrix in the model instance. If a covariance matrix has already been stored, it will be overwritten.

False
context Optional[Union[int, Mapping[str, Any]]]

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None
Source code in src/glum/_glm.py
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
def std_errors(
    self,
    X=None,
    y=None,
    sample_weight=None,
    offset=None,
    *,
    mu=None,
    dispersion=None,
    robust=None,
    clusters: np.ndarray = None,
    expected_information=None,
    store_covariance_matrix=False,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
):
    """Calculate standard errors for generalized linear models.

    See `covariance_matrix` for an in-depth explanation of how the
    standard errors are computed.

    Parameters
    ----------
    X : {array-like, sparse matrix}, shape (n_samples, n_features), optional
        Training data. Can be omitted if a covariance matrix has already
        been computed.
    y : array-like, shape (n_samples,), optional
        Target values. Can be omitted if a covariance matrix has already
        been computed.
    sample_weight : array-like, shape (n_samples,), optional, default=None
        Individual weights for each sample.
    offset : array-like, optional, default=None
        Array with additive offsets.
    mu : array-like, optional, default=None
        Array with predictions. Estimated if absent.
    dispersion : float, optional, default=None
        The dispersion parameter. Estimated if absent.
    robust : boolean, optional, default=None
        Whether to compute robust standard errors instead of normal ones.
        If not specified, the model's `robust` attribute is used.
    clusters : array-like, optional, default=None
        Array with cluster membership. Clustered standard errors are
        computed if clusters is not None.
    expected_information : boolean, optional, default=None
        Whether to use the expected or observed information matrix.
        Only relevant when computing robust standard errors.
        If not specified, the model's `expected_information` attribute is used.
    store_covariance_matrix : boolean, optional, default=False
        Whether to store the covariance matrix in the model instance.
        If a covariance matrix has already been stored, it will be overwritten.
    context : Optional[Union[int, Mapping[str, Any]]], default=None
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.
    """
    covariance_matrix = self.covariance_matrix(
        X=X,
        y=y,
        sample_weight=sample_weight,
        offset=offset,
        mu=mu,
        dispersion=dispersion,
        robust=robust,
        clusters=clusters,
        expected_information=expected_information,
        store_covariance_matrix=store_covariance_matrix,
        context=capture_context(context),
    )

    return np.sqrt(covariance_matrix.diagonal())

covariance_matrix

covariance_matrix(X=None, y=None, sample_weight=None, offset=None, *, mu=None, dispersion=None, robust=None, clusters: Optional[ndarray] = None, expected_information=None, store_covariance_matrix=False, skip_checks=False, context: Optional[Union[int, Mapping[str, Any]]] = None)

Calculate the covariance matrix for generalized linear models.

Parameters:

Name Type Description Default
X array-like, sparse matrix

Training data. Can be omitted if a covariance matrix has already been computed.

array-like
y (array - like, shape(n_samples))

Target values. Can be omitted if a covariance matrix has already been computed.

None
mu array - like

Array with predictions. Estimated if absent.

None
offset array - like

Array with additive offsets.

None
sample_weight (array - like, shape(n_samples))

Individual weights for each sample.

None
dispersion float

The dispersion parameter. Estimated if absent.

None
robust boolean

Whether to compute robust standard errors instead of normal ones. If not specified, the model's robust attribute is used.

None
clusters array - like

Array with cluster membership. Clustered standard errors are computed if clusters is not None.

None
expected_information boolean

Whether to use the expected or observed information matrix. Only relevant when computing robust standard errors. If not specified, the model's expected_information attribute is used.

None
store_covariance_matrix boolean

Whether to store the covariance matrix in the model instance. If a covariance matrix has already been stored, it will be overwritten.

False
skip_checks boolean

Whether to skip input validation. For internal use only.

False
context Optional[Union[int, Mapping[str, Any]]]

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None
Notes

We support three types of covariance matrices:

  • non-robust
  • robust (HC-1)
  • clustered

For maximum-likelihood estimator, the covariance matrix takes the form \(\mathcal{H}^{-1}(\theta_0)\mathcal{I}(\theta_0) \mathcal{H}^{-1}(\theta_0)\) where \(\mathcal{H}^{-1}\) is the inverse Hessian and \(\mathcal{I}\) is the Information matrix. The different types of covariance matrices use different approximation of these quantities.

The non-robust covariance matrix is computed as the inverse of the Fisher information matrix. This assumes that the information matrix equality holds.

The robust (HC-1) covariance matrix takes the form \(\mathbf{H}^{−1} (\hat{\theta})\mathbf{G}^{T}(\hat{\theta})\mathbf{G}(\hat{\theta}) \mathbf{H}^{−1}(\hat{\theta})\) where \(\mathbf{H}\) is the empirical Hessian and \(\mathbf{G}\) is the gradient. We apply a finite-sample correction of \(\frac{N}{N-p}\).

The clustered covariance matrix uses a similar approach to the robust (HC-1) covariance matrix. However, instead of using \(\mathbf{G}^{T}( \hat{\theta}\mathbf{G}(\hat{\theta})\) directly, we first sum over all the groups first. The finite-sample correction is affected as well, becoming \(\frac{M}{M-1}\frac{N}{N-p}\) where \(M\) is the number of groups.

References
  • Davidson, Russell & MacKinnon, James G. (1993). "Estimation and Inference in Econometrics," OUP Catalogue, Oxford University Press
  • Cameron, A. C., & Trivedi, P. K. (2005). "Microeconometrics: methods and applications," Cambridge university press
Source code in src/glum/_glm.py
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
def covariance_matrix(
    self,
    X=None,
    y=None,
    sample_weight=None,
    offset=None,
    *,
    mu=None,
    dispersion=None,
    robust=None,
    clusters: Optional[np.ndarray] = None,
    expected_information=None,
    store_covariance_matrix=False,
    skip_checks=False,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
):
    """Calculate the covariance matrix for generalized linear models.

    Parameters
    ----------
    X : {array-like, sparse matrix}, shape (n_samples, n_features), optional
        Training data. Can be omitted if a covariance matrix has already
        been computed.

    y : array-like, shape (n_samples,), optional
        Target values. Can be omitted if a covariance matrix has already
        been computed.

    mu : array-like, optional, default=None
        Array with predictions. Estimated if absent.

    offset : array-like, optional, default=None
        Array with additive offsets.

    sample_weight : array-like, shape (n_samples,), optional, default=None
        Individual weights for each sample.

    dispersion : float, optional, default=None
        The dispersion parameter. Estimated if absent.

    robust : boolean, optional, default=None
        Whether to compute robust standard errors instead of normal ones.
        If not specified, the model's `robust` attribute is used.

    clusters : array-like, optional, default=None
        Array with cluster membership. Clustered standard errors are
        computed if clusters is not None.

    expected_information : boolean, optional, default=None
        Whether to use the expected or observed information matrix.
        Only relevant when computing robust standard errors.
        If not specified, the model's `expected_information` attribute is used.

    store_covariance_matrix : boolean, optional, default=False
        Whether to store the covariance matrix in the model instance.
        If a covariance matrix has already been stored, it will be overwritten.

    skip_checks : boolean, optional, default=False
        Whether to skip input validation. For internal use only.

    context : Optional[Union[int, Mapping[str, Any]]], default=None
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.

    Notes
    -----
    We support three types of covariance matrices:

    - non-robust
    - robust (HC-1)
    - clustered

    For maximum-likelihood estimator, the covariance matrix takes the form
    $\\mathcal{H}^{-1}(\\theta_0)\\mathcal{I}(\\theta_0)
    \\mathcal{H}^{-1}(\\theta_0)$ where $\\mathcal{H}^{-1}$ is the
    inverse Hessian and $\\mathcal{I}$ is the Information matrix.
    The different types of covariance matrices use different approximation
    of these quantities.

    The non-robust covariance matrix is computed as the inverse of the Fisher
    information matrix. This assumes that the information matrix equality holds.

    The robust (HC-1) covariance matrix takes the form $\\mathbf{H}^{−1}
    (\\hat{\\theta})\\mathbf{G}^{T}(\\hat{\\theta})\\mathbf{G}(\\hat{\\theta})
    \\mathbf{H}^{−1}(\\hat{\\theta})$ where $\\mathbf{H}$ is the empirical
    Hessian and $\\mathbf{G}$ is the gradient. We apply a finite-sample
    correction of $\\frac{N}{N-p}$.

    The clustered covariance matrix uses a similar approach to the robust (HC-1)
    covariance matrix. However, instead of using $\\mathbf{G}^{T}(
    \\hat{\\theta}\\mathbf{G}(\\hat{\\theta})$ directly, we first sum over
    all the groups first. The finite-sample correction is affected as well,
    becoming $\\frac{M}{M-1}\\frac{N}{N-p}$ where $M$ is the number
    of groups.

    References
    ----------
    - Davidson, Russell & MacKinnon, James G. (1993).
      "Estimation and Inference in Econometrics," OUP Catalogue,
      Oxford University Press
    - Cameron, A. C., & Trivedi, P. K. (2005).
      "Microeconometrics: methods and applications,"
      Cambridge university press

    """
    self.covariance_matrix_: Union[np.ndarray, None]

    if robust is None:
        _robust = getattr(self, "robust", True)
    else:
        _robust = robust

    if expected_information is None:
        _expected_information = getattr(self, "expected_information", False)
    else:
        _expected_information = expected_information

    if (
        (
            hasattr(self, "alpha")
            and isinstance(self.alpha, (int, float))
            and self.alpha > 0
        )
        or (hasattr(self, "alpha_") and self.alpha_ > 0)  # glm_cv
        or (hasattr(self, "_alphas") and self._alphas[-1] > 0)  # alpha_search
    ):
        warnings.warn(
            "Covariance matrix estimation assumes that the model is not "
            "penalized. You are estimating a penalized model. The covariance "
            "matrix will be incorrect."
        )

    cannot_estimate_cov = (y is None) and not hasattr(self, "y_model_spec_")
    cannot_estimate_cov |= X is None

    if not skip_checks:
        if cannot_estimate_cov and self.covariance_matrix_ is None:
            raise ValueError(
                "Either X and y must be provided or the covariance matrix "
                "must have been previously computed."
            )

        if cannot_estimate_cov and store_covariance_matrix:
            raise ValueError(
                "X and y must be provided if 'store_covariance_matrix' is True."
            )

        if store_covariance_matrix and self.covariance_matrix_ is not None:
            warnings.warn(
                "A covariance matrix has already been computed. "
                "It will be overwritten."
            )

        if X is None and y is None:
            if (
                offset is not None
                or mu is not None
                or offset is not None
                or sample_weight is not None
                or dispersion is not None
                or robust is not None
                or clusters is not None
                or expected_information is not None
            ):
                raise ValueError(
                    "Cannot reestimate the covariance matrix with different "
                    "parameters if X and y are not provided."
                )
            return self.covariance_matrix_

        if hasattr(self, "y_model_spec_"):
            y = self.y_model_spec_.get_model_matrix(X).toarray().ravel()
            # This has to go first because X is modified in the next line

        if nw.dependencies.is_into_dataframe(X):
            X = self._convert_from_df(X, context=capture_context(context))

        X, y = check_X_y_tabmat_compliant(
            X,
            y,
            accept_sparse=["csr", "csc", "coo"],
            dtype="numeric",
            copy=self._should_copy_X(),
            ensure_2d=True,
            allow_nd=False,
            drop_first=getattr(self, "drop_first", False),
        )

        if isinstance(X, np.ndarray):
            X = tm.DenseMatrix(X)
        if sparse.issparse(X) and not isinstance(X, tm.SparseMatrix):
            X = tm.SparseMatrix(X)

        sample_weight = check_weights(
            sample_weight,
            y.shape[0],
            X.dtype,
            force_all_finite=self.force_all_finite,
        )
        offset = check_offset(offset, y.shape[0], X.dtype)

    sum_weights = np.sum(sample_weight)  # type: ignore

    mu = self.predict(X, offset=offset) if mu is None else np.asanyarray(mu)

    if dispersion is None:
        # sample_weight here need to be non-normalized to count the number
        # of observations.
        dispersion = self._family_instance.dispersion(
            y,
            mu,
            sample_weight=sample_weight,
            ddof=X.shape[1] + self.fit_intercept,
            method="pearson",
        )

    if (
        np.linalg.cond(safe_toarray(X.sandwich(np.ones(X.shape[0]))))
        > 1 / sys.float_info.epsilon**2
    ):
        raise np.linalg.LinAlgError(
            "Matrix is singular. Cannot estimate standard errors."
        )

    if _robust or clusters is not None:
        if _expected_information:
            oim_fct = self._family_instance._fisher_information
        else:
            oim_fct = self._family_instance._observed_information
        oim = oim_fct(
            self._link_instance,
            X,
            y,
            mu,
            sample_weight,
            dispersion,
            self.fit_intercept,
        )
        gradient = self._family_instance._score_matrix(
            self._link_instance,
            X,
            y,
            mu,
            sample_weight,
            dispersion,
            self.fit_intercept,
        )
        if clusters is not None:
            n_groups = len(np.unique(clusters))
            grouped_gradient = _group_sum(clusters, gradient)
            inner_part = grouped_gradient.T @ grouped_gradient
            correction = (n_groups / (n_groups - 1)) * (
                (sum_weights - 1)
                / (sum_weights - self.n_features_in_ - int(self.fit_intercept))
            )
        else:
            inner_part = gradient.sandwich(np.ones_like(y, dtype=X.dtype))
            correction = sum_weights / (
                sum_weights - self.n_features_in_ - int(self.fit_intercept)
            )
        vcov = linalg.solve(oim, linalg.solve(oim, safe_toarray(inner_part)).T)
        vcov *= correction
    else:
        fisher = self._family_instance._fisher_information(
            self._link_instance,
            X,
            y,
            mu,
            sample_weight,
            dispersion,
            self.fit_intercept,
        )
        vcov = linalg.inv(safe_toarray(fisher))
        vcov *= sum_weights / (
            sum_weights - self.n_features_in_ - int(self.fit_intercept)
        )

    if store_covariance_matrix:
        self.covariance_matrix_ = vcov

    return vcov

score

score(X: ShapedArrayLike, y: VectorLike, sample_weight: Optional[VectorLike] = None, offset: Optional[ArrayLike] = None, *, context: Optional[Union[int, Mapping[str, Any]]] = None)

Compute \(D^2\), the percentage of deviance explained.

\(D^2\) is a generalization of the coefficient of determination \(R^2\). The \(R^2\) uses the squared error and the \(D^2\), the deviance. Note that those two are equal for family='normal'.

\(D^2\) is defined as \(D^2 = 1 - \frac{D(y_{\mathrm{true}}, y_{\mathrm{pred}})} {D_{\mathrm{null}}}\), \(D_{\mathrm{null}}\) is the null deviance, i.e. the deviance of a model with intercept alone. The best possible score is one and it can be negative.

Parameters:

Name Type Description Default
X array-like, sparse matrix

Test samples.

array-like
y (array - like, shape(n_samples))

True values of target.

required
sample_weight (array - like, shape(n_samples), optional(default=None))

Sample weights.

None
offset (array - like, shape(n_samples), optional(default=None))
None
context Optional[Union[int, Mapping[str, Any]]]

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None

Returns:

Type Description
float

D^2 of self.predict(X) w.r.t. y.

Source code in src/glum/_glm.py
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
def score(
    self,
    X: ShapedArrayLike,
    y: VectorLike,
    sample_weight: Optional[VectorLike] = None,
    offset: Optional[ArrayLike] = None,
    *,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
):
    """Compute $D^2$, the percentage of deviance explained.

    $D^2$ is a generalization of the coefficient of determination
    $R^2$. The $R^2$ uses the squared error and the $D^2$,
    the deviance. Note that those two are equal for `family='normal'`.

    $D^2$ is defined as
    $D^2 = 1 - \\frac{D(y_{\\mathrm{true}}, y_{\\mathrm{pred}})}
    {D_{\\mathrm{null}}}$,
    $D_{\\mathrm{null}}$ is the null deviance, i.e. the deviance of a
    model with intercept alone. The best possible score is one and it can be
    negative.

    Parameters
    ----------
    X : {array-like, sparse matrix}, shape (n_samples, n_features)
        Test samples.

    y : array-like, shape (n_samples,)
        True values of target.

    sample_weight : array-like, shape (n_samples,), optional (default=None)
        Sample weights.

    offset : array-like, shape (n_samples,), optional (default=None)

    context : Optional[Union[int, Mapping[str, Any]]], default=None
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.

    Returns
    -------
    float
        D^2 of self.predict(X) w.r.t. y.
    """
    sample_weight = check_weights(sample_weight, y.shape[0], y.dtype)

    mu = self.predict(X, offset=offset, context=context)
    y_mean: float = np.average(y, weights=sample_weight)

    dev = self.family_instance.deviance(y, mu, sample_weight=sample_weight)
    dev_null = self.family_instance.deviance(y, y_mean, sample_weight=sample_weight)

    return 1 - dev / dev_null

linear_predictor

linear_predictor(X: ArrayLike, offset: Optional[ArrayLike] = None, *, alpha_index: Optional[Union[int, Sequence[int]]] = None, alpha: Optional[Union[float, Sequence[float]]] = None, context: Optional[Union[int, Mapping[str, Any]]] = None)

Compute the linear predictor, X * coef_ + intercept_.

If alpha_search is True, but alpha_index and alpha are both None, the predictions are for the last alpha value self._alphas[-1].

Parameters:

Name Type Description Default
X (array - like, shape(n_samples, n_features))

Observations. X may be a pandas data frame with categorical types. If X was also a data frame with categorical types during fitting and a category wasn't observed at that point, the corresponding prediction will be numpy.nan.

required
offset (array - like, shape(n_samples), optional(default=None))

Offset added to the linear predictor.

None
alpha_index int or sequence of int, optional (default=None)

Index (or indices) into the fitted alpha path. Only valid when alpha_search is True. Incompatible with alpha.

None
alpha float or sequence of float, optional (default=None)

Alpha value(s) to predict at, resolved to the closest index on the fitted alpha path. Only valid when alpha_search is True. Incompatible with alpha_index.

None
context (int or mapping, optional(default=None))

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None

Returns:

Type Description
ndarray

Shape (n_samples,) when no alpha_index / alpha is given or when a scalar alpha is passed. Shape (n_samples, len(alpha_index)) when a sequence is passed.

Compute the linear predictor, `X * coef_ + intercept_`.
When neither `alpha_index` nor `alpha` are given, predictions are for the
best CV-selected `(l1_ratio_, alpha_)`.
When either `alpha_index` or `alpha` are specified, predictions are for the
corresponding alpha values on the full-data refit path for the best
`l1_ratio_`.

Parameters:

Name Type Description Default
X (array - like, shape(n_samples, n_features))

Observations.

required
offset (array - like, shape(n_samples), optional(default=None))

Offset added to the linear predictor.

None
alpha_index int or sequence of int, optional (default=None)

Index (or indices) into the alpha path from the full-data refit. Incompatible with alpha.

None
alpha float or sequence of float, optional (default=None)

Alpha value(s) to predict at, resolved to the closest index on the refit alpha path. Incompatible with alpha_index.

None
context (int or mapping, optional(default=None))

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None

Returns:

Type Description
ndarray

Shape (n_samples,) when no alpha_index / alpha is given or when a scalar alpha is passed. Shape (n_samples, len(alpha_index)) when a sequence is passed.

Source code in src/glum/_glm_cv.py
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
def linear_predictor(
    self,
    X: ArrayLike,
    offset: Optional[ArrayLike] = None,
    *,
    alpha_index: Optional[Union[int, Sequence[int]]] = None,
    alpha: Optional[Union[float, Sequence[float]]] = None,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
):
    """Compute the linear predictor, `X * coef_ + intercept_`.

    When neither `alpha_index` nor `alpha` are given, predictions are for the
    best CV-selected `(l1_ratio_, alpha_)`.

    When either `alpha_index` or `alpha` are specified, predictions are for the
    corresponding alpha values on the full-data refit path for the best
    `l1_ratio_`.

    Parameters
    ----------
    X : array-like, shape (n_samples, n_features)
        Observations.

    offset : array-like, shape (n_samples,), optional (default=None)
        Offset added to the linear predictor.

    alpha_index : int or sequence of int, optional (default=None)
        Index (or indices) into the alpha path from the full-data refit.
        Incompatible with `alpha`.

    alpha : float or sequence of float, optional (default=None)
        Alpha value(s) to predict at, resolved to the closest index on
        the refit alpha path. Incompatible with `alpha_index`.

    context : int or mapping, optional (default=None)
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.


    Returns
    -------
    np.ndarray
        Shape `(n_samples,)` when no `alpha_index` / `alpha` is
        given or when a scalar alpha is passed. Shape
        `(n_samples, len(alpha_index))` when a sequence is passed.
    """
    skl.utils.validation.check_is_fitted(self, "coef_")

    alpha_index = self._resolve_alpha_index(alpha_index, alpha)

    if alpha_index is None:
        return super().linear_predictor(X, offset, context=context)

    return self._compute_linear_predictor(
        X,
        offset,
        alpha_index=alpha_index,
        coef_path=self._refit_coef_path,
        intercept_path=self._refit_intercept_path,
        context=context,
    )

fit

fit(X: ArrayLike, y: Optional[ArrayLike] = None, sample_weight: Optional[ArrayLike] = None, offset: Optional[ArrayLike] = None, *, store_covariance_matrix: bool = False, clusters: Optional[ndarray] = None, context: Optional[Union[int, Mapping[str, Any]]] = None)

Choose the best model along a 'regularization path' by cross-validation.

Parameters:

Name Type Description Default
X array-like, sparse matrix

Training data. Note that a float32 matrix is acceptable and will result in the entire algorithm being run in 32-bit precision. However, for problems that are poorly conditioned, this might result in poor convergence or flawed parameter estimates. If a Pandas data frame is provided, it may contain categorical columns. In that case, a separate coefficient will be estimated for each category. No category is omitted. This means that some regularization is required to fit models with an intercept or models with several categorical columns.

array-like
y (array - like, shape(n_samples))

Target values.

None
sample_weight (array - like, shape(n_samples), optional(default=None))

Individual weights w_i for each sample. Note that, for an Exponential Dispersion Model (EDM), one has \(\mathrm{var}(y_i) = \phi \times v(mu) / w_i\). If \(y_i \sim EDM(\mu, \phi / w_i)\), then \(\sum w_i y_i / \sum w_i \sim EDM(\mu, \phi / \sum w_i)\), i.e. the mean of \(y\) is a weighted average with weights equal to sample_weight.

None
offset Optional[ArrayLike]

Added to linear predictor. An offset of 3 will increase expected y by 3 if the link is linear and will multiply expected y by 3 if the link is logarithmic.

None
store_covariance_matrix (bool, optional(default=False))

Whether to store the covariance matrix of the parameter estimates corresponding to the best best model.

False
clusters array - like

Array with cluster membership. Clustered standard errors are computed if clusters is not None.

None
context Optional[Union[int, Mapping[str, Any]]]

The context to add to the evaluation context of the formula with, e.g., custom transforms. If an integer, the context is taken from the stack frame of the caller at the given depth. Otherwise, a mapping from variable names to values is expected. By default, no context is added. Set context=0 to make the calling scope available.

None
Source code in src/glum/_glm_cv.py
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
def fit(
    self,
    X: ArrayLike,
    y: Optional[ArrayLike] = None,
    sample_weight: Optional[ArrayLike] = None,
    offset: Optional[ArrayLike] = None,
    *,
    store_covariance_matrix: bool = False,
    clusters: Optional[np.ndarray] = None,
    context: Optional[Union[int, Mapping[str, Any]]] = None,
):
    r"""
    Choose the best model along a 'regularization path' by cross-validation.

    Parameters
    ----------
    X : {array-like, sparse matrix}, shape (n_samples, n_features)
        Training data. Note that a `float32` matrix is acceptable and will
        result in the entire algorithm being run in 32-bit precision.
        However, for problems that are poorly conditioned, this might result
        in poor convergence or flawed parameter estimates. If a Pandas data
        frame is provided, it may contain categorical columns. In that case,
        a separate coefficient will be estimated for each category. No
        category is omitted. This means that some regularization is required
        to fit models with an intercept or models with several categorical
        columns.

    y : array-like, shape (n_samples,)
        Target values.

    sample_weight : array-like, shape (n_samples,), optional (default=None)
        Individual weights w_i for each sample. Note that, for an
        Exponential Dispersion Model (EDM), one has
        $\mathrm{var}(y_i) = \phi \times v(mu) / w_i$. If
        $y_i \sim EDM(\mu, \phi / w_i)$, then
        $\sum w_i y_i / \sum w_i \sim EDM(\mu, \phi / \sum w_i)$,
        i.e. the mean of $y$ is a weighted average with weights equal
        to `sample_weight`.

    offset: array-like, shape (n_samples,), optional (default=None)
        Added to linear predictor. An offset of 3 will increase expected
        `y` by 3 if the link is linear and will multiply expected `y` by
        3 if the link is logarithmic.

    store_covariance_matrix : bool, optional (default=False)
        Whether to store the covariance matrix of the parameter estimates
        corresponding to the best best model.

    clusters : array-like, optional, default=None
        Array with cluster membership. Clustered standard errors are
        computed if clusters is not None.

    context : Optional[Union[int, Mapping[str, Any]]], default=None
        The context to add to the evaluation context of the formula with,
        e.g., custom transforms. If an integer, the context is taken from
        the stack frame of the caller at the given depth. Otherwise, a
        mapping from variable names to values is expected. By default,
        no context is added. Set `context=0` to make the calling scope
        available.

    """
    self._validate_hyperparameters()
    self._align_info_logs_emitted: set[str] = set()

    (
        X,
        y,
        sample_weight,
        offset,
        weights_sum,
        P1,
        P2,
    ) = self._set_up_and_check_fit_args(
        X,
        y,
        sample_weight,
        offset,
        force_all_finite=self.force_all_finite,
        context=capture_context(context),
    )

    #########
    # Checks
    self._set_up_for_fit(y)
    if (
        hasattr(self._family_instance, "_power")
        and self._family_instance._power == 1.5  # type: ignore
    ):
        assert isinstance(self._link_instance, LogLink)

    l1_ratio = np.atleast_1d(self.l1_ratio)

    if self._solver == "irls-cd":
        _stype = ["csc"]
    else:
        _stype = ["csc", "csr"]

    if self.alphas is None:
        alphas: list[np.ndarray] = []
        for l1 in l1_ratio:
            P1_no_alpha = setup_p1(P1, X, X.dtype, 1, l1)
            P2_no_alpha = setup_p2(P2, X, _stype, X.dtype, 1, l1)
            X_std, _, _, _, _, _, P1_no_alpha, _ = standardize(
                X,
                sample_weight,
                self._center_predictors,
                self.scale_predictors,
                None,
                None,
                None,
                P1_no_alpha,
                P2_no_alpha,
            )
            alphas.append(
                self._get_alpha_path(P1_no_alpha, X_std, y, sample_weight, offset)
            )
    else:
        alphas = np.tile(  # type: ignore[assignment]
            np.sort(np.asarray(self.alphas, dtype=X.dtype))[::-1],
            (len(l1_ratio), 1),
        )

    if len(l1_ratio) == 1:
        self.alphas_ = alphas[0]
    else:
        self.alphas_ = np.asarray(alphas)

    lower_bounds = check_bounds(self.lower_bounds, X.shape[1], X.dtype)
    upper_bounds = check_bounds(self.upper_bounds, X.shape[1], X.dtype)

    if self.monotonic_constraints is not None:
        A_ineq, b_ineq = self._resolve_monotonic_constraints()
    elif self.A_ineq is not None and self.b_ineq is not None:
        A_ineq = copy.copy(self.A_ineq)
        b_ineq = copy.copy(self.b_ineq)
    else:
        A_ineq, b_ineq = None, None

    cv = skl.model_selection.check_cv(self.cv)

    def _fit_path(
        self,
        train_idx,
        test_idx,
        X,
        y,
        l1,
        alphas,
        sample_weight,
        offset,
        lower_bounds,
        upper_bounds,
        A_ineq,
        b_ineq,
    ):
        x_train, y_train, w_train = (
            X[train_idx, :],
            y[train_idx],
            sample_weight[train_idx],
        )
        w_train /= w_train.sum()

        x_test, y_test, w_test = (
            X[test_idx, :],
            y[test_idx],
            sample_weight[test_idx],
        )
        w_test /= w_test.sum()

        if offset is not None:
            offset_train = offset[train_idx]
            offset_test = offset[test_idx]
        else:
            offset_train, offset_test = None, None

        def _get_deviance(coef):
            mu = self._link_instance.inverse(
                _safe_lin_pred(x_test, coef, offset_test)
            )
            return self._family_instance.deviance(y_test, mu, sample_weight=w_test)

        if (
            hasattr(self._family_instance, "_power")
            and self._family_instance._power == 1.5
        ):
            assert isinstance(self._link_instance, LogLink)

        P1_no_alpha = setup_p1(P1, X, X.dtype, 1, l1)
        P2_no_alpha = setup_p2(P2, X, _stype, X.dtype, 1, l1)

        (
            x_train,
            self.col_means_,
            self.col_stds_,
            lower_bounds,
            upper_bounds,
            A_ineq,
            P1_no_alpha,
            P2_no_alpha,
        ) = standardize(
            x_train,
            w_train,
            self._center_predictors,
            self.scale_predictors,
            lower_bounds,
            upper_bounds,
            A_ineq,
            P1_no_alpha,
            P2_no_alpha,
        )

        def _get_train_deviance(coef):
            mu = self._link_instance.inverse(
                _safe_lin_pred(x_train, coef, offset_train)
            )
            return self._family_instance.deviance(
                y_train, mu, sample_weight=w_train
            )

        coef = self._get_start_coef(
            x_train,
            y_train,
            w_train,
            offset_train,
            self.col_means_,
            self.col_stds_,
            dtype=[np.float64, np.float32],
        )

        if self.check_input:
            # check if P2 is positive semidefinite
            if not isinstance(self.P2, str):  # self.P2 != 'identity'
                if not is_pos_semidef(P2_no_alpha):
                    if P2_no_alpha.ndim == 1 or P2_no_alpha.shape[0] == 1:
                        error = "1d array P2 must not have negative values."
                    else:
                        error = "P2 must be positive semi-definite."
                    raise ValueError(error)

        coef = self._solve_regularization_path(
            X=x_train,
            y=y_train,
            sample_weight=w_train,
            alphas=alphas,
            P2_no_alpha=P2_no_alpha,
            P1_no_alpha=P1_no_alpha,
            coef=coef,
            offset=offset_train,
            lower_bounds=lower_bounds,
            upper_bounds=upper_bounds,
            A_ineq=A_ineq,
            b_ineq=b_ineq,
        )

        train_deviance_path_ = [_get_train_deviance(_coef) for _coef in coef]

        # Unlike train deviance, test deviance is computed on unstandardized
        # x and coefficient rescaling differs by self.fit_intercept.
        if self.fit_intercept:
            intercept_path_, coef_path_ = unstandardize(
                self.col_means_, self.col_stds_, coef[:, 0], coef[:, 1:]
            )
            assert isinstance(intercept_path_, np.ndarray)  # make mypy happy
            full_coef_path = np.concatenate(
                [intercept_path_[:, np.newaxis], coef_path_], axis=1
            )
            deviance_path_ = [_get_deviance(_coef) for _coef in full_coef_path]
        else:
            # set intercept to zero as the other linear models do
            intercept_path_, coef_path_ = unstandardize(
                self.col_means_, self.col_stds_, np.zeros(coef.shape[0]), coef
            )
            deviance_path_ = [_get_deviance(_coef) for _coef in coef_path_]

        return intercept_path_, coef_path_, deviance_path_, train_deviance_path_

    jobs = (
        joblib.delayed(_fit_path)(
            self,
            train_idx=train_idx,
            test_idx=test_idx,
            X=X,
            y=y,
            l1=this_l1_ratio,
            alphas=this_alphas,
            sample_weight=sample_weight,
            offset=offset,
            lower_bounds=lower_bounds,
            upper_bounds=upper_bounds,
            A_ineq=A_ineq,
            b_ineq=b_ineq,
        )
        for train_idx, test_idx in cv.split(X, y)
        for this_l1_ratio, this_alphas in zip(l1_ratio, alphas)
    )

    paths_data = joblib.Parallel(n_jobs=self.n_jobs, prefer="processes")(jobs)

    self.intercept_path_ = np.reshape(
        [elmt[0] for elmt in paths_data],
        (cv.get_n_splits(), len(l1_ratio), len(alphas[0]), -1),
    )

    self.coef_path_ = np.reshape(
        [elmt[1] for elmt in paths_data],
        (cv.get_n_splits(), len(l1_ratio), len(alphas[0]), -1),
    )

    self.deviance_path_ = np.reshape(
        [elmt[2] for elmt in paths_data],
        (cv.get_n_splits(), len(l1_ratio), len(alphas[0])),
    )

    self.train_deviance_path_ = np.reshape(
        [elmt[3] for elmt in paths_data],
        (cv.get_n_splits(), len(l1_ratio), len(alphas[0])),
    )

    avg_deviance = self.deviance_path_.mean(axis=0)  # type: ignore

    best_l1, best_alpha = np.unravel_index(
        np.argmin(avg_deviance), avg_deviance.shape
    )

    if len(l1_ratio) > 1:
        self.l1_ratio_ = l1_ratio[best_l1]
        self.alpha_ = self.alphas_[best_l1, best_alpha]
    else:
        self.l1_ratio_ = l1_ratio[best_l1]
        self.alpha_ = self.alphas_[best_alpha]

    P1_no_alpha = setup_p1(P1, X, X.dtype, 1, self.l1_ratio_)  # type: ignore
    P2_no_alpha = setup_p2(P2, X, _stype, X.dtype, 1, self.l1_ratio_)  # type: ignore

    # Refit with full data along the entire alpha path for best l1_ratio
    (
        X,
        self.col_means_,
        self.col_stds_,
        lower_bounds,
        upper_bounds,
        A_ineq,
        P1_no_alpha,
        P2_no_alpha,
    ) = standardize(
        X,
        sample_weight,
        self._center_predictors,
        self.scale_predictors,
        lower_bounds,
        upper_bounds,
        A_ineq,
        P1_no_alpha,
        P2_no_alpha,
    )

    coef = self._get_start_coef(
        X, y, sample_weight, offset, self.col_means_, self.col_stds_, dtype=X.dtype
    )

    if len(l1_ratio) > 1:
        refit_alphas = self.alphas_[best_l1]
    else:
        refit_alphas = self.alphas_

    # _solve_regularization_path overwrites self.coef_path_; save and
    # restore the per-fold paths so the public attribute is unchanged.
    # It also overwrites n_iter_, _n_cycles, and diagnostics_, but those
    # just reflect whichever fold ran last, so we let the refit values stand.
    _cv_coef_path = self.coef_path_

    coef = self._solve_regularization_path(
        X=X,
        y=y,
        sample_weight=sample_weight,
        alphas=refit_alphas,
        P2_no_alpha=P2_no_alpha,
        P1_no_alpha=P1_no_alpha,  # type: ignore
        coef=coef,
        offset=offset,
        lower_bounds=lower_bounds,
        upper_bounds=upper_bounds,
        A_ineq=A_ineq,
        b_ineq=b_ineq,
    )

    self.coef_path_ = _cv_coef_path

    self._warn_if_saturated(X, coef[best_alpha], offset)

    if self.fit_intercept:
        self._refit_intercept_path, self._refit_coef_path = unstandardize(
            self.col_means_, self.col_stds_, coef[:, 0], coef[:, 1:]
        )
    else:
        # set intercept to zero as the other linear models do
        self._refit_intercept_path, self._refit_coef_path = unstandardize(
            self.col_means_, self.col_stds_, np.zeros(coef.shape[0]), coef
        )

    self.coef_ = self._refit_coef_path[best_alpha]
    self.intercept_ = self._refit_intercept_path[best_alpha]  # type: ignore[index]
    self._alphas = refit_alphas

    self.covariance_matrix_ = None
    if store_covariance_matrix:
        self.covariance_matrix(
            X=X.unstandardize(),
            y=y,
            offset=offset,
            sample_weight=sample_weight * weights_sum,
            robust=self.robust,
            clusters=clusters,
            expected_information=self.expected_information,
            store_covariance_matrix=True,
            skip_checks=True,
        )

    return self

Bases: Link

The complementary log-log link function log(-log(1-mu)).

to_tweedie

to_tweedie(safe=True)

Return the Tweedie representation of a link function if it exists.

Source code in src/glum/_link.py
 96
 97
 98
 99
100
101
102
def to_tweedie(self, safe=True):
    """Return the Tweedie representation of a link function if it exists."""
    if hasattr(self, "__tweedie_repr__"):
        return self.__tweedie_repr__()
    if safe:
        raise ValueError("This link function has no Tweedie representation.")
    return None
link(mu)

Compute the link function.

The link function g links the mean, mu ≡ E(Y), to the linear predictor, X * w, so that g(mu) is equal to the linear predictor.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Usually the (predicted) mean.

required
Source code in src/glum/_link.py
281
282
def link(self, mu):  # noqa D
    return np.log(-np.log1p(-mu))

derivative

derivative(mu)

Compute the derivative of the link function.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Usually the (predicted) mean.

required
Source code in src/glum/_link.py
284
285
def derivative(self, mu):  # noqa D
    return 1.0 / ((mu - 1) * (np.log1p(-mu)))

inverse

inverse(lin_pred)

Compute the inverse link function.

The inverse link function h gives the inverse relationship between the linear predictor, X * w, and the mean, mu ≡ E(Y), so that h(X * w) = mu.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
287
288
289
290
def inverse(self, lin_pred):  # noqa D
    # Clip silently: this regularly happens for intermediate solver iterates
    # and there is nothing a user could do about it.
    return _clip_probability(-np.expm1(-np.exp(lin_pred)))

is_saturated

is_saturated(lin_pred) -> np.ndarray

Whether inverse(lin_pred) is numerically at the boundary of its range.

Only links that clip their inverse at the boundary of the unit interval, such as the logit and cloglog links, can be saturated.

Source code in src/glum/_link.py
292
293
294
295
296
297
def is_saturated(self, lin_pred) -> np.ndarray:  # noqa D
    # The cloglog link is asymmetric: the inverse reaches 1 at a linear predictor
    # of about 3.5, which happens routinely, whereas reaching 0 requires about -32.
    # Only the lower tail is thus a sign of (quasi-)separation.
    prob = -np.expm1(-np.exp(lin_pred))
    return prob < _probability_bounds(prob)[0]

inverse_derivative

inverse_derivative(lin_pred)

Compute the derivative of the inverse link function.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
299
300
def inverse_derivative(self, lin_pred):  # noqa D
    return np.exp(lin_pred - np.exp(lin_pred))

inverse_derivative2

inverse_derivative2(lin_pred)

Compute second derivative of the inverse link function.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
302
303
def inverse_derivative2(self, lin_pred):  # noqa D
    return -np.exp(lin_pred - np.exp(lin_pred)) * np.expm1(lin_pred)

Bases: Link

The identity link function.

is_saturated

is_saturated(lin_pred) -> np.ndarray

Whether inverse(lin_pred) is numerically at the boundary of its range.

Only links that clip their inverse at the boundary of the unit interval, such as the logit and cloglog links, can be saturated.

Source code in src/glum/_link.py
26
27
28
29
30
31
32
def is_saturated(self, lin_pred) -> np.ndarray:
    """Whether `inverse(lin_pred)` is numerically at the boundary of its range.

    Only links that clip their inverse at the boundary of the unit interval,
    such as the logit and cloglog links, can be saturated.
    """
    return np.zeros(np.shape(lin_pred), dtype=bool)

to_tweedie

to_tweedie(safe=True)

Return the Tweedie representation of a link function if it exists.

Source code in src/glum/_link.py
 96
 97
 98
 99
100
101
102
def to_tweedie(self, safe=True):
    """Return the Tweedie representation of a link function if it exists."""
    if hasattr(self, "__tweedie_repr__"):
        return self.__tweedie_repr__()
    if safe:
        raise ValueError("This link function has no Tweedie representation.")
    return None
link(mu)

Compute the link function.

The link function g links the mean, mu ≡ E(Y), to the linear predictor, X * w, so that g(mu) is equal to the linear predictor.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Usually the (predicted) mean.

required
Source code in src/glum/_link.py
205
206
def link(self, mu):  # noqa D
    return mu

derivative

derivative(mu)

Compute the derivative of the link function.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Usually the (predicted) mean.

required
Source code in src/glum/_link.py
208
209
def derivative(self, mu):  # noqa D
    return 1 if np.isscalar(mu) else np.ones_like(mu)

inverse

inverse(lin_pred)

Compute the inverse link function.

The inverse link function h gives the inverse relationship between the linear predictor, X * w, and the mean, mu ≡ E(Y), so that h(X * w) = mu.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
211
212
def inverse(self, lin_pred):  # noqa D
    return lin_pred

inverse_derivative

inverse_derivative(lin_pred)

Compute the derivative of the inverse link function.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
214
215
def inverse_derivative(self, lin_pred):  # noqa D
    return 1.0 if np.isscalar(lin_pred) else np.ones_like(lin_pred)

inverse_derivative2

inverse_derivative2(lin_pred)

Compute second derivative of the inverse link function.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
217
218
def inverse_derivative2(self, lin_pred):  # noqa D
    return 0.0 if np.isscalar(lin_pred) else np.zeros_like(lin_pred)

Abstract base class for link functions.

is_saturated

is_saturated(lin_pred) -> np.ndarray

Whether inverse(lin_pred) is numerically at the boundary of its range.

Only links that clip their inverse at the boundary of the unit interval, such as the logit and cloglog links, can be saturated.

Source code in src/glum/_link.py
26
27
28
29
30
31
32
def is_saturated(self, lin_pred) -> np.ndarray:
    """Whether `inverse(lin_pred)` is numerically at the boundary of its range.

    Only links that clip their inverse at the boundary of the unit interval,
    such as the logit and cloglog links, can be saturated.
    """
    return np.zeros(np.shape(lin_pred), dtype=bool)
link(mu)

Compute the link function.

The link function g links the mean, mu ≡ E(Y), to the linear predictor, X * w, so that g(mu) is equal to the linear predictor.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Usually the (predicted) mean.

required
Source code in src/glum/_link.py
34
35
36
37
38
39
40
41
42
43
44
45
46
@abstractmethod
def link(self, mu):
    """Compute the link function.

    The link function `g` links the mean, `mu ≡ E(Y)`, to the linear
    predictor, `X * w`, so that `g(mu)` is equal to the linear predictor.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Usually the (predicted) mean.
    """
    pass

derivative abstractmethod

derivative(mu)

Compute the derivative of the link function.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Usually the (predicted) mean.

required
Source code in src/glum/_link.py
48
49
50
51
52
53
54
55
56
57
@abstractmethod
def derivative(self, mu):
    """Compute the derivative of the link function.

    Parameters
    ----------
    mu : array-like, shape (n_samples,)
        Usually the (predicted) mean.
    """
    pass

inverse abstractmethod

inverse(lin_pred)

Compute the inverse link function.

The inverse link function h gives the inverse relationship between the linear predictor, X * w, and the mean, mu ≡ E(Y), so that h(X * w) = mu.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@abstractmethod
def inverse(self, lin_pred):
    """Compute the inverse link function.

    The inverse link function `h` gives the inverse relationship between
    the linear predictor, `X * w`, and the mean, `mu ≡ E(Y)`, so that
    `h(X * w) = mu`.

    Parameters
    ----------
    lin_pred : array-like, shape (n_samples,)
        Usually the (fitted) linear predictor.
    """
    pass

inverse_derivative abstractmethod

inverse_derivative(lin_pred)

Compute the derivative of the inverse link function.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
74
75
76
77
78
79
80
81
82
83
@abstractmethod
def inverse_derivative(self, lin_pred):
    """Compute the derivative of the inverse link function.

    Parameters
    ----------
    lin_pred : array-like, shape (n_samples,)
        Usually the (fitted) linear predictor.
    """
    pass

inverse_derivative2 abstractmethod

inverse_derivative2(lin_pred)

Compute second derivative of the inverse link function.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
85
86
87
88
89
90
91
92
93
94
@abstractmethod
def inverse_derivative2(self, lin_pred):
    """Compute second derivative of the inverse link function.

    Parameters
    ----------
    lin_pred : array-like, shape (n_samples,)
        Usually the (fitted) linear predictor.
    """
    pass

to_tweedie

to_tweedie(safe=True)

Return the Tweedie representation of a link function if it exists.

Source code in src/glum/_link.py
 96
 97
 98
 99
100
101
102
def to_tweedie(self, safe=True):
    """Return the Tweedie representation of a link function if it exists."""
    if hasattr(self, "__tweedie_repr__"):
        return self.__tweedie_repr__()
    if safe:
        raise ValueError("This link function has no Tweedie representation.")
    return None

Bases: Link

The logit link function logit(x).

to_tweedie

to_tweedie(safe=True)

Return the Tweedie representation of a link function if it exists.

Source code in src/glum/_link.py
 96
 97
 98
 99
100
101
102
def to_tweedie(self, safe=True):
    """Return the Tweedie representation of a link function if it exists."""
    if hasattr(self, "__tweedie_repr__"):
        return self.__tweedie_repr__()
    if safe:
        raise ValueError("This link function has no Tweedie representation.")
    return None
link(mu)

Compute the link function.

The link function g links the mean, mu ≡ E(Y), to the linear predictor, X * w, so that g(mu) is equal to the linear predictor.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Usually the (predicted) mean.

required
Source code in src/glum/_link.py
252
253
def link(self, mu):  # noqa D
    return special.logit(mu)

derivative

derivative(mu)

Compute the derivative of the link function.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Usually the (predicted) mean.

required
Source code in src/glum/_link.py
255
256
def derivative(self, mu):  # noqa D
    return 1.0 / (mu * (1 - mu))

inverse

inverse(lin_pred)

Compute the inverse link function.

The inverse link function h gives the inverse relationship between the linear predictor, X * w, and the mean, mu ≡ E(Y), so that h(X * w) = mu.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
258
259
260
261
def inverse(self, lin_pred):  # noqa D
    # Clip silently: this regularly happens for intermediate solver iterates
    # and there is nothing a user could do about it.
    return _clip_probability(special.expit(lin_pred))

is_saturated

is_saturated(lin_pred) -> np.ndarray

Whether inverse(lin_pred) is numerically at the boundary of its range.

Only links that clip their inverse at the boundary of the unit interval, such as the logit and cloglog links, can be saturated.

Source code in src/glum/_link.py
263
264
def is_saturated(self, lin_pred) -> np.ndarray:  # noqa D
    return _is_clipped_probability(special.expit(lin_pred))

inverse_derivative

inverse_derivative(lin_pred)

Compute the derivative of the inverse link function.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
266
267
268
def inverse_derivative(self, lin_pred):  # noqa D
    ep = special.expit(lin_pred)
    return ep * (1.0 - ep)

inverse_derivative2

inverse_derivative2(lin_pred)

Compute second derivative of the inverse link function.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
270
271
272
def inverse_derivative2(self, lin_pred):  # noqa D
    ep = special.expit(lin_pred)
    return ep * (1.0 - ep) * (1.0 - 2 * ep)

Bases: Link

The log link function log(x).

is_saturated

is_saturated(lin_pred) -> np.ndarray

Whether inverse(lin_pred) is numerically at the boundary of its range.

Only links that clip their inverse at the boundary of the unit interval, such as the logit and cloglog links, can be saturated.

Source code in src/glum/_link.py
26
27
28
29
30
31
32
def is_saturated(self, lin_pred) -> np.ndarray:
    """Whether `inverse(lin_pred)` is numerically at the boundary of its range.

    Only links that clip their inverse at the boundary of the unit interval,
    such as the logit and cloglog links, can be saturated.
    """
    return np.zeros(np.shape(lin_pred), dtype=bool)

to_tweedie

to_tweedie(safe=True)

Return the Tweedie representation of a link function if it exists.

Source code in src/glum/_link.py
 96
 97
 98
 99
100
101
102
def to_tweedie(self, safe=True):
    """Return the Tweedie representation of a link function if it exists."""
    if hasattr(self, "__tweedie_repr__"):
        return self.__tweedie_repr__()
    if safe:
        raise ValueError("This link function has no Tweedie representation.")
    return None
link(mu)

Compute the link function.

The link function g links the mean, mu ≡ E(Y), to the linear predictor, X * w, so that g(mu) is equal to the linear predictor.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Usually the (predicted) mean.

required
Source code in src/glum/_link.py
230
231
def link(self, mu):  # noqa D
    return np.log(mu)

derivative

derivative(mu)

Compute the derivative of the link function.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Usually the (predicted) mean.

required
Source code in src/glum/_link.py
233
234
def derivative(self, mu):  # noqa D
    return 1 / mu

inverse

inverse(lin_pred)

Compute the inverse link function.

The inverse link function h gives the inverse relationship between the linear predictor, X * w, and the mean, mu ≡ E(Y), so that h(X * w) = mu.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
236
237
def inverse(self, lin_pred):  # noqa D
    return np.exp(lin_pred)

inverse_derivative

inverse_derivative(lin_pred)

Compute the derivative of the inverse link function.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
239
240
def inverse_derivative(self, lin_pred):  # noqa D
    return np.exp(lin_pred)

inverse_derivative2

inverse_derivative2(lin_pred)

Compute second derivative of the inverse link function.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
242
243
def inverse_derivative2(self, lin_pred):  # noqa D
    return np.exp(lin_pred)
TweedieLink(power)

Bases: Link

The Tweedie link function x^(1-p) if p≠1 and log(x) if p=1.

See the documentation of the superclass, Link, for details.

Source code in src/glum/_link.py
129
130
def __init__(self, power):
    self.power = power

is_saturated

is_saturated(lin_pred) -> np.ndarray

Whether inverse(lin_pred) is numerically at the boundary of its range.

Only links that clip their inverse at the boundary of the unit interval, such as the logit and cloglog links, can be saturated.

Source code in src/glum/_link.py
26
27
28
29
30
31
32
def is_saturated(self, lin_pred) -> np.ndarray:
    """Whether `inverse(lin_pred)` is numerically at the boundary of its range.

    Only links that clip their inverse at the boundary of the unit interval,
    such as the logit and cloglog links, can be saturated.
    """
    return np.zeros(np.shape(lin_pred), dtype=bool)

to_tweedie

to_tweedie(safe=True)

Return the Tweedie representation of a link function if it exists.

Source code in src/glum/_link.py
 96
 97
 98
 99
100
101
102
def to_tweedie(self, safe=True):
    """Return the Tweedie representation of a link function if it exists."""
    if hasattr(self, "__tweedie_repr__"):
        return self.__tweedie_repr__()
    if safe:
        raise ValueError("This link function has no Tweedie representation.")
    return None
link(mu)

Compute the link function.

The link function g links the mean, mu ≡ E(Y), to the linear predictor, X * w, so that g(mu) is equal to the linear predictor.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Usually the (predicted) mean.

required
Source code in src/glum/_link.py
152
153
154
155
156
157
def link(self, mu):  # noqa D
    if self.power == 0:
        return mu
    if self.power == 1:
        return np.log(mu)
    return mu ** (1 - self.power)

derivative

derivative(mu)

Compute the derivative of the link function.

Parameters:

Name Type Description Default
mu (array - like, shape(n_samples))

Usually the (predicted) mean.

required
Source code in src/glum/_link.py
159
160
161
162
163
164
def derivative(self, mu):  # noqa D
    if self.power == 0:
        return 1.0 if np.isscalar(mu) else np.ones_like(mu)
    if self.power == 1:
        return 1 / mu
    return (1 - self.power) * mu ** (-self.power)

inverse

inverse(lin_pred)

Compute the inverse link function.

The inverse link function h gives the inverse relationship between the linear predictor, X * w, and the mean, mu ≡ E(Y), so that h(X * w) = mu.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
166
167
168
169
170
171
172
@catch_p
def inverse(self, lin_pred):  # noqa D
    if self.power == 0:
        return lin_pred
    if self.power == 1:
        return np.exp(lin_pred)
    return lin_pred ** (1 / (1 - self.power))

inverse_derivative

inverse_derivative(lin_pred)

Compute the derivative of the inverse link function.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
174
175
176
177
178
179
180
181
@catch_p
def inverse_derivative(self, lin_pred):  # noqa D
    if self.power == 0:
        return 1.0 if np.isscalar(lin_pred) else np.ones_like(lin_pred)
    if self.power == 1:
        return np.exp(lin_pred)

    return (1 / (1 - self.power)) * lin_pred ** (self.power / (1 - self.power))

inverse_derivative2

inverse_derivative2(lin_pred)

Compute second derivative of the inverse link function.

Parameters:

Name Type Description Default
lin_pred (array - like, shape(n_samples))

Usually the (fitted) linear predictor.

required
Source code in src/glum/_link.py
183
184
185
186
187
188
189
190
191
192
193
@catch_p
def inverse_derivative2(self, lin_pred):  # noqa D
    if self.power == 0:
        return 0.0 if np.isscalar(lin_pred) else np.zeros_like(lin_pred)
    if self.power == 1:
        return np.exp(lin_pred)

    result = lin_pred ** ((2 * self.power - 1) / (1 - self.power))
    result *= self.power / (1 - self.power) ** 2

    return result
get_link(link: Union[str, Link], family: ExponentialDispersionModel) -> Link

For the Tweedie distribution, this code follows actuarial best practices regarding link functions. Note that these links are sometimes not canonical:

  • identity for normal (p = 0);
  • no convention for p < 0, so let's leave it as identity;
  • log otherwise.
Source code in src/glum/_glm.py
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
def get_link(link: Union[str, Link], family: ExponentialDispersionModel) -> Link:
    """
    For the Tweedie distribution, this code follows actuarial best practices
    regarding link functions. Note that these links are sometimes not canonical:

    - identity for normal (`p = 0`);
    - no convention for `p < 0`, so let's leave it as identity;
    - log otherwise.
    """
    if isinstance(link, Link):
        return link

    if (link is None) or (link == "auto"):
        if tweedie_representation := family.to_tweedie(safe=False):
            if tweedie_representation.power <= 0:
                return IdentityLink()
            return LogLink()
        if isinstance(family, GeneralizedHyperbolicSecant):
            return IdentityLink()
        if isinstance(family, BinomialDistribution):
            return LogitLink()
        if isinstance(family, NegativeBinomialDistribution):
            return LogLink()
        raise ValueError(
            "No default link known for the specified distribution family. "
            "Please set link manually, i.e. not to 'auto'. "
            f"Got (link='auto', family={family.__class__.__name__})."
        )

    mapping = {
        "cloglog": CloglogLink(),
        "identity": IdentityLink(),
        "log": LogLink(),
        "logit": LogitLink(),
        "tweedie": TweedieLink(1.5),
    }

    if link in mapping:
        return mapping[link]
    if custom_tweedie := re.search(r"tweedie\s?\((.+)\)", link):
        return TweedieLink(float(custom_tweedie.group(1)))

    raise ValueError(
        "The link must be an instance of class Link or an element of "
        "['auto', 'identity', 'log', 'logit', 'cloglog', 'tweedie']; "
        f"got (link={link})."
    )