# InverseGaussian Inverse Gaussian family with log link. Usage ``` python InverseGaussian() ``` The Inverse Gaussian family models strictly positive, continuous responses whose variance grows even faster than in the Gamma case, producing heavier right tails. It arises naturally as a first-passage-time distribution (e.g. the time for a diffusion process to reach a threshold) and is a common choice for lifetime, duration, and other highly skewed positive data. [InverseGaussian](InverseGaussian.md#whittaker.InverseGaussian) is the Tweedie special case with variance power `p = 3` (compare [Tweedie](Tweedie.md#whittaker.Tweedie) and [tw()](tw.md#whittaker.tw)), implemented directly here for exact deviance and log-likelihood computations rather than the saddlepoint approximation used by the general [Tweedie](Tweedie.md#whittaker.Tweedie) family. The log link is used for the same reasons as in [Gamma](Gamma.md#whittaker.Gamma): it keeps fitted values positive and gives coefficients a multiplicative interpretation. ## Notes The link is the natural logarithm: g(\mu) = \log(\mu) The variance function grows with the cube of the mean: V(\mu) = \mu^{3}, making this family appropriate when large means are associated with disproportionately large variability. The deviance is D(y, \hat\mu) = \sum_i \frac{(y_i - \hat\mu_i)^2}{\hat\mu_i^2\\ y_i} . ## Examples Fit a GAM to heavy-tailed positive data with a smooth trend: ``` python import numpy as np import whittaker as wk rng = np.random.default_rng(0) n = 200 x = np.linspace(0, 2 * np.pi, n) mu = np.exp(1.0 + 0.4 * np.sin(x)) scale = 0.5 lam = mu / scale y = rng.wald(mu, lam) data = {"x": x, "y": y} model = wk.GAM("y ~ s(x)", family=wk.InverseGaussian()) model.fit(data, method="REML") print(model.summary()) ``` GAM fit summary ============================================================ Formula: y ~ s(x) Family: InverseGaussian(link='log') Inference: REML Observations: 200 Coefficients: 10 Parametric coefficients: Term Estimate Std.Err t value p-value ------------------------ ---------- ---------- ---------- ---------- (Intercept) 1.0954 0.0555 19.735 < 1e-16 Approximate significance of smooth terms: Term EDF Ref.df Chi.sq p-value ------------------------ ------ ------ ---------- ---------- s(x) 4.19 5 32.744 4.231e-06 Total EDF: 5.19 Scale est: 0.198556 Deviance: 38.6806 Null dev: 45.4465 Dev. expl: 14.9% GCV score: 0.203847 AIC: 783.07 BIC: 800.19 ## Attributes | Name | Description | |----|----| | [scale_known](#scale_known) | Whether the dispersion parameter is fixed. Always `False` for InverseGaussian. | ------------------------------------------------------------------------ ### scale_known Whether the dispersion parameter is fixed. Always `False` for InverseGaussian. `scale_known: bool` The dispersion `phi` is estimated from the data during fitting rather than fixed, analogous to how [Gamma](Gamma.md#whittaker.Gamma) and [Gaussian](Gaussian.md#whittaker.Gaussian) estimate their own dispersion parameters. This affects how [GAM.fit()](GAM.md#whittaker.GAM.fit) and [GAM.summary()](GAM.md#whittaker.GAM.summary) treat the scale. ## Methods | Name | Description | |----|----| | [deviance()](#deviance) | Total Inverse Gaussian deviance, the (weighted) sum of `unit_deviance`. | | [initialize()](#initialize) | Starting values for `mu`: `y` nudged away from zero. | | [link()](#link) | Apply the log link: \eta = \log(\mu). | | [link_derivative()](#link_derivative) | Derivative of the log link: g'(\mu) = 1/\mu. | | [link_inverse()](#link_inverse) | Apply the inverse log link: \mu = e^{\eta}. | | [log_likelihood()](#log_likelihood) | Inverse Gaussian log-likelihood evaluated at dispersion `scale`. | | [simulate()](#simulate) | Simulate Inverse Gaussian (Wald) response values with mean `mu` and dispersion `scale`. | | [unit_deviance()](#unit_deviance) | Per-observation Inverse Gaussian deviance contributions. | | [variance()](#variance) | Inverse Gaussian variance function: V(\mu) = \mu^3. | ------------------------------------------------------------------------ ### deviance() Total Inverse Gaussian deviance, the (weighted) sum of `unit_deviance`. Usage ``` python deviance( y, mu, *, weights=None, ) ``` #### Parameters `y: NDArray` Observed response values (positive), shape `(n,)`. `mu: NDArray` Fitted conditional mean values, shape `(n,)`. `weights: NDArray | None = None` Optional prior weights, shape `(n,)`. #### Returns `float` The total (weighted) deviance. ------------------------------------------------------------------------ ### initialize() Starting values for `mu`: `y` nudged away from zero. Usage ``` python initialize(y) ``` Since the log link requires strictly positive `mu`, values are pushed away from zero to avoid `log(0)` on the first P-IRLS iteration. #### Parameters `y: NDArray` Observed response values (positive), shape `(n,)`. #### Returns `NDArray` Starting values for `mu`, shape `(n,)`. ------------------------------------------------------------------------ ### link() Apply the log link: \eta = \log(\mu). Usage ``` python link(mu) ``` #### Parameters `mu: NDArray` Conditional mean values, shape `(n,)`. Must be positive. #### Returns `NDArray` Linear predictor values \eta = \log(\mu), shape `(n,)`. ------------------------------------------------------------------------ ### link_derivative() Derivative of the log link: g'(\mu) = 1/\mu. Usage ``` python link_derivative(mu) ``` #### Parameters `mu: NDArray` Conditional mean values, shape `(n,)`. #### Returns `NDArray` Derivative values 1/\mu, shape `(n,)`. ------------------------------------------------------------------------ ### link_inverse() Apply the inverse log link: \mu = e^{\eta}. Usage ``` python link_inverse(eta) ``` The linear predictor is clipped to `[-30, 30]` before exponentiating to guard against overflow while fitting. #### Parameters `eta: NDArray` Linear predictor values, shape `(n,)`. #### Returns `NDArray` Conditional mean values \mu = e^{\eta}, shape `(n,)`. ------------------------------------------------------------------------ ### log_likelihood() Inverse Gaussian log-likelihood evaluated at dispersion `scale`. Usage ``` python log_likelihood( y, mu, scale, *, weights=None, ) ``` #### Parameters `y: NDArray` Observed response values (positive), shape `(n,)`. `mu: NDArray` Fitted conditional mean values, shape `(n,)`. `scale: float` Dispersion parameter \phi. `weights: NDArray | None = None` Optional prior weights, shape `(n,)`. #### Returns `float` The total log-likelihood. ------------------------------------------------------------------------ ### simulate() Simulate Inverse Gaussian (Wald) response values with mean `mu` and dispersion `scale`. Usage ``` python simulate( mu, scale, rng, ) ``` Draws are generated via Michael, Schucany & Haas's transformation of a chi-squared variate, then adjusted with a uniform random variable to select between the two candidate roots. #### Parameters `mu: NDArray` Mean (fitted values), shape `(n,)`. `scale: float` Dispersion parameter \phi. `rng: np.random.Generator` A `numpy.random.Generator` instance. #### Returns `NDArray` Simulated response values, shape `(n,)`. ------------------------------------------------------------------------ ### unit_deviance() Per-observation Inverse Gaussian deviance contributions. Usage ``` python unit_deviance( y, mu, ) ``` Computes d_i = (y_i - \hat\mu_i)^2 / (\hat\mu_i^2\\ y_i). #### Parameters `y: NDArray` Observed response values (positive), shape `(n,)`. `mu: NDArray` Fitted conditional mean values, shape `(n,)`. #### Returns `NDArray` Per-observation deviance contributions, shape `(n,)`. ------------------------------------------------------------------------ ### variance() Inverse Gaussian variance function: V(\mu) = \mu^3. Usage ``` python variance(mu) ``` The variance grows with the cube of the mean, giving this family the heaviest right tail among Whittaker's built-in continuous positive families. #### Parameters `mu: NDArray` Conditional mean values, shape `(n,)`. #### Returns `NDArray` Variance values \mu^3, shape `(n,)`.