Binomial family with logit (canonical) link.
The Binomial family models a response that is either binary (0/1) or a proportion in [0, 1] (e.g. the fraction of successes out of a known number of trials). The logit link maps the unit interval to the whole real line, so the linear predictor is unconstrained while the fitted mean is always a valid probability. Use it for classification-style GAMs, for aggregated success/trial proportions, or wherever the outcome represents the probability of an event. The logit link additionally gives coefficients a log-odds interpretation: a one-unit increase in a covariate changes the log-odds of success by coefficient, and multiplies the odds by exp(coefficient).
Notes
The canonical link is the logit function:
g(\mu) = \log\!\left(\frac{\mu}{1-\mu}\right)
with inverse the logistic sigmoid \mu = g^{-1}(\eta) = 1 / (1 + e^{-\eta}). The variance function is
V(\mu) = \mu(1-\mu),
which is largest near \mu = 0.5 and shrinks toward zero as \mu approaches either boundary. The deviance is
D(y, \hat\mu) = 2 \sum_i \left[ y_i \log\!\left(\frac{y_i}{\hat\mu_i}\right)
+ (1 - y_i) \log\!\left(\frac{1 - y_i}{1 - \hat\mu_i}\right) \right] .
Examples
Fit a GAM to a binary outcome with a smooth, nonlinear log-odds relationship:
import numpy as np
import whittaker as wk
from scipy.special import expit
rng = np.random.default_rng(0)
n = 300
x = np.linspace(-3, 3, n)
p = expit(np.sin(x))
y = rng.binomial(1, p)
data = {"x": x, "y": y}
model = wk.GAM("y ~ s(x)", family=wk.Binomial())
model.fit(data, method="REML")
print(model.summary())
GAM fit summary
============================================================
Formula: y ~ s(x)
Family: Binomial(link='logit')
Inference: REML
Observations: 300
Coefficients: 10
Parametric coefficients:
Term Estimate Std.Err z value p-value
------------------------ ---------- ---------- ---------- ----------
(Intercept) -0.0002 0.1170 -0.002 0.9984
Approximate significance of smooth terms:
Term EDF Ref.df Chi.sq p-value
------------------------ ------ ------ ---------- ----------
s(x) 2.79 3 9.389 0.02454
Total EDF: 3.79
Scale est: 1.000000
Deviance: 404.3107
Null dev: 415.8883
Dev. expl: 2.8%
GCV score: 1.382449
AIC: 411.90
BIC: 425.95
Attributes
|
Name
|
Description
|
|
scale_known
|
Whether the dispersion parameter is fixed. Always True for Binomial.
|
scale_known
Whether the dispersion parameter is fixed. Always True for Binomial.
The Bernoulli/Binomial distribution has no free dispersion parameter, so the scale is fixed at 1 and is never estimated during fitting. This affects how GAM.summary() reports the scale and how many degrees of freedom are attributed to dispersion.
Methods
|
Name
|
Description
|
|
deviance()
|
Total binomial deviance, the (weighted) sum of unit_deviance.
|
|
initialize()
|
Starting values for mu: a constant shrunk toward the overall mean of y.
|
|
link()
|
Apply the logit link: \eta = \log(\mu / (1-\mu)).
|
|
link_derivative()
|
Derivative of the logit link: g'(\mu) = 1 / (\mu(1-\mu)).
|
|
link_inverse()
|
Apply the inverse logit link (logistic sigmoid): \mu = 1 / (1 + e^{-\eta}).
|
|
log_likelihood()
|
Bernoulli/binomial log-likelihood \ell_i = y_i \log(\mu_i) + (1-y_i)\log(1-\mu_i).
|
|
simulate()
|
Simulate Bernoulli response values with success probability mu.
|
|
unit_deviance()
|
Per-observation binomial deviance contributions.
|
|
variance()
|
Binomial variance function: V(\mu) = \mu(1-\mu).
|
deviance()
Total binomial deviance, the (weighted) sum of unit_deviance.
deviance(
y,
mu,
*,
weights=None,
)
Parameters
y: NDArray-
Observed response values (0/1 or proportions in [0, 1]), shape (n,).
mu: NDArray-
Fitted conditional mean values (probabilities), shape (n,).
weights: NDArray | None = None-
Optional prior weights, shape
(n,).
Returns
float-
The total (weighted) deviance.
initialize()
Starting values for mu: a constant shrunk toward the overall mean of y.
Every observation is initialized to (mean(y) + 0.5) / 2, a value strictly inside (0, 1) regardless of whether y contains only 0s, only 1s, or a mix, avoiding logit(0) or logit(1) on the first P-IRLS iteration.
Parameters
y: NDArray-
Observed response values, shape
(n,).
Returns
NDArray-
Starting values for
mu, shape (n,).
link()
Apply the logit link: \eta = \log(\mu / (1-\mu)).
Parameters
mu: NDArray-
Conditional mean values (probabilities), shape
(n,). Must lie in (0, 1).
Returns
NDArray-
Linear predictor (log-odds) values, shape
(n,).
link_derivative()
Derivative of the logit link: g'(\mu) = 1 / (\mu(1-\mu)).
Parameters
mu: NDArray-
Conditional mean values (probabilities), shape
(n,); clipped away from 0 and 1 to avoid division by zero.
Returns
NDArray-
Derivative values, shape
(n,).
link_inverse()
Apply the inverse logit link (logistic sigmoid): \mu = 1 / (1 + e^{-\eta}).
Parameters
eta: NDArray-
Linear predictor (log-odds) values, shape
(n,).
Returns
NDArray-
Conditional mean values (probabilities), shape
(n,), always in (0, 1).
log_likelihood()
Bernoulli/binomial log-likelihood \ell_i = y_i \log(\mu_i) + (1-y_i)\log(1-\mu_i).
log_likelihood(
y,
mu,
scale,
*,
weights=None,
)
The scale argument is accepted for interface compatibility but ignored, since the Binomial distribution has no free dispersion parameter (scale_known is True).
Parameters
y: NDArray-
Observed response values, shape (n,).
mu: NDArray-
Fitted conditional mean values (probabilities), shape (n,).
scale: float-
Ignored.
weights: NDArray | None = None-
Optional prior weights, shape
(n,).
Returns
float-
The total log-likelihood.
simulate()
Simulate Bernoulli response values with success probability mu.
simulate(
mu,
scale,
rng,
)
Parameters
mu: NDArray-
Success probabilities (fitted values), shape (n,).
scale: float-
Ignored (the Binomial distribution has no free dispersion parameter).
rng: np.random.Generator-
A
numpy.random.Generator instance.
Returns
NDArray-
Simulated 0/1 response values, shape
(n,).
unit_deviance()
Per-observation binomial deviance contributions.
Computes d_i = 2 \left[ y_i \log(y_i/\hat\mu_i) + (1-y_i)\log((1-y_i)/(1-\hat\mu_i)) \right], with the usual conventions that the y_i \log(\cdot) term vanishes when y_i = 0 and the (1-y_i)\log(\cdot) term vanishes when y_i = 1.
Parameters
y: NDArray-
Observed response values, shape (n,).
mu: NDArray-
Fitted conditional mean values (probabilities), shape
(n,).
Returns
NDArray-
Per-observation deviance contributions, shape
(n,).
variance()
Binomial variance function: V(\mu) = \mu(1-\mu).
Largest at \mu = 0.5 and shrinking toward zero as \mu approaches either boundary.
Parameters
mu: NDArray-
Conditional mean values (probabilities), shape
(n,).
Returns
NDArray-
Variance values \mu(1-\mu), shape
(n,).