Struct Fit 

pub struct Fit<'a, M, F>
where
    M: Glm,
    F: Float,
{
    pub result: Array1<F>,
    pub options: FitOptions<F>,
    pub model_like: F,
    pub n_iter: usize,
    pub history: Vec<IrlsStep<F>>,
    /* private fields */
}

the result of a successful GLM fit

Fields

result: Array1<F>

The parameter values that maximize the likelihood as given by the IRLS regression.

options: FitOptions<F>

The options used for this fit.

model_like: F

The value of the likelihood function for the fit result.

n_iter: usize

The number of overall iterations taken in the IRLS.

history: Vec<IrlsStep<F>>

The history of guesses and likelihoods over the IRLS iterations.

Implementations

impl<'a, M, F> Fit<'a, M, F>

where M: Glm, F: 'static + Float,

pub fn aic(&self) -> F

Returns the Akaike information criterion for the model fit.

\text{AIC} = D + 2K - 2\sum_{i} \ln w_{i}

where $D$ is the deviance, $K$ is the number of parameters, and $w_i$ are the variance weights. This is unique only to an additive constant, so only differences in AIC are meaningful.

pub fn bic(&self) -> F

Returns the Bayesian information criterion for the model fit.

\text{BIC} = K \ln(n) - 2l - s\sum_{i} \ln w_{i}

where $K$ is the number of parameters, $n$ is the number of observations, and $l$ is the log-likelihood (including the variance weight normalization terms).

pub fn cooks(&self) -> RegressionResult<Array1<F>>

The Cook’s distance for each observation, which measures how much the predicted values change when leaving out each observation.

C_i = \frac{r_i^2 \, h_i}{K \, \hat\phi \, (1 - h_i)^2}

where $r_i$ is the Pearson residual, $h_i$ is the leverage, $K$ is the rank (number of parameters), and $\hat\phi$ is the estimated dispersion.

pub fn covariance(&self) -> RegressionResult<Array2<F>>

The covariance matrix of the parameter estimates:

\text{Cov}[\hat{\boldsymbol\beta}] = \hat\phi \, (\mathbf{X}^\mathsf{T}\mathbf{WSX})^{-1}

where $\hat\phi$ is the estimated dispersion, $\mathbf{W}$ is the weight matrix, and $\mathbf{S}$ is the diagonal variance matrix. The Fisher matrix inverse is cached.

pub fn deviance(&self) -> F

Returns the deviance of the fit:

D = -2 \left[ l(\hat{\boldsymbol\beta}) - l_\text{sat} \right]

Asymptotically $\chi^2$-distributed with ndf() degrees of freedom. The unregularized likelihood is used.

pub fn dispersion(&self) -> F

The dispersion parameter $\hat\phi$ relating the variance to the variance function: $\text{Var}[y] = \phi \, V(\mu)$.

Identically one for logistic, binomial, and Poisson regression. For families with a free dispersion (linear, gamma), estimated as:

\hat\phi = \frac{D}{\left(1 - \frac{K}{n_\text{eff}}\right) \sum_i w_i}

which reduces to $D / (N - K)$ without variance weights.

pub fn expectation<S>( &self, data_x: &ArrayBase<S, Ix2>, lin_off: Option<&Array1<F>>, ) -> Array1<F>

where S: Data<Elem = F>,

👎Deprecated since 0.0.10: use predict() instead

pub fn fisher(&self, params: &Array1<F>) -> Array2<F>

Returns the Fisher information (the negative Hessian of the log-likelihood) at the parameter values given:

\mathcal{I}(\boldsymbol\beta) = \mathbf{X}^\mathsf{T}\mathbf{W}\eta'^2\mathbf{S}\mathbf{X}

where $\mathbf{S} = \text{diag}(V(\mu_i))$ and $\eta'$ is the derivative of the natural parameter in terms of the linear predictor ($\eta(\omega) = g_0(g^{-1}(\omega))$ where $g_0$ is the canonical link function). functions. The regularization is included.

pub fn hat(&self) -> RegressionResult<Ref<'_, Array2<F>>>

Returns the hat matrix, also known as the “projection” or “influence” matrix:

P_{ij} = \frac{\partial \hat{y}_i}{\partial y_j}

Orthogonal to the response residuals at the fit result: $\mathbf{P}(\mathbf{y} - \hat{\mathbf{y}}) = 0$. This version is not symmetric, but the diagonal is invariant to this choice of convention.

pub fn infl_coef(&self) -> RegressionResult<Array2<F>>

The one-step approximation to the change in coefficients from excluding each observation:

\Delta\boldsymbol\beta^{(-i)} \approx \frac{1}{1-h_i}\,\mathcal{I}^{-1}\mathbf{x}^{(i)} w_i \eta'_i e_i

Each row $i$ should be subtracted from $\hat{\boldsymbol\beta}$ to approximate the coefficients that would result from excluding observation $i$. Exact for linear models; a one-step approximation for nonlinear models.

pub fn leverage(&self) -> RegressionResult<Array1<F>>

Returns the leverage $h_i = P_{ii}$ for each observation: the diagonal of the hat matrix. Indicates the sensitivity of each prediction to its corresponding observation.

pub fn loo_exact(&self) -> RegressionResult<Array2<F>>

Returns exact coefficients from leaving each observation out, one-at-a-time. This is a much more expensive operation than the original regression because a new one is performed for each observation.

pub fn lr_test(&self) -> F

Perform a likelihood-ratio test, returning the statistic:

\Lambda = -2 \ln \frac{L_0}{L} = -2(l_0 - l)

where $L_0$ is the null model likelihood (intercept only) and $L$ is the fit likelihood. By Wilks’ theorem, asymptotically $\chi^2$-distributed with test_ndf() degrees of freedom.

pub fn lr_test_against(&self, alternative: &Array1<F>) -> F

Perform a likelihood-ratio test against a general alternative model, not necessarily a null model. The alternative model is regularized the same way that the regression resulting in this fit was. The degrees of freedom cannot be generally inferred.

pub fn ndf(&self) -> F

Returns the residual degrees of freedom in the model, i.e. the number of data points minus the number of parameters. Not to be confused with test_ndf(), the degrees of freedom in the statistical tests of the fit parameters.

pub fn null_like(&self) -> F

Returns the likelihood given the null model, which fixes all parameters to zero except the intercept (if it is used). A total of test_ndf() parameters are constrained.

pub fn predict<S>( &self, data_x: &ArrayBase<S, Ix2>, lin_off: Option<&Array1<F>>, ) -> Array1<F>

where S: Data<Elem = F>,

Returns $\hat{\mathbf{y}} = g^{-1}(\mathbf{X}\hat{\boldsymbol\beta} + \boldsymbol\omega_0)$ given input data $\mathbf{X}$ and an optional linear offset $\boldsymbol\omega_0$. The data need not be the training data.

pub fn resid_dev(&self) -> Array1<F>

Return the deviance residuals for each point in the training data:

d_i = \text{sign}(y_i - \hat\mu_i)\sqrt{D_i}

where $D_i$ is the per-observation deviance contribution. This is usually a better choice than Pearson residuals for non-linear models.

pub fn resid_dev_std(&self) -> RegressionResult<Array1<F>>

Return the standardized deviance residuals (internally studentized):

d_i^* = \frac{d_i}{\sqrt{\hat\phi(1 - h_i)}}

where $d_i$ is the deviance residual, $\hat\phi$ is the dispersion, and $h_i$ is the leverage. Generally applicable for outlier detection.

pub fn resid_part(&self) -> Array1<F>

Return the partial residuals.

pub fn resid_pear(&self) -> Array1<F>

Return the Pearson residuals for each point in the training data:

r_i = \sqrt{w_i} \, \frac{y_i - \hat\mu_i}{\sqrt{V(\hat\mu_i)}}

where $V$ is the variance function and $w_i$ are the variance weights. Not scaled by the dispersion for families with a free dispersion parameter.

pub fn resid_pear_std(&self) -> RegressionResult<Array1<F>>

Return the standardized Pearson residuals (internally studentized):

r_i^* = \frac{r_i}{\sqrt{\hat\phi(1 - h_i)}}

where $r_i$ is the Pearson residual and $h_i$ is the leverage. These are expected to have unit variance.

pub fn resid_resp(&self) -> Array1<F>

Return the response residuals: $e_i^\text{resp} = y_i - \hat\mu_i$.

pub fn resid_student(&self) -> RegressionResult<Array1<F>>

Return the externally studentized residuals:

\tilde{t}_i = \text{sign}(e_i) \sqrt{\frac{D_i^{(-i)}}{\hat\phi^{(-i)}}}

where $D_i^{(-i)}$ and $\hat\phi^{(-i)}$ are the LOO deviance and dispersion approximated via one-step deletion. Under normality, $t$-distributed with $N - K - 1$ degrees of freedom. This is a robust and general method for outlier detection.

pub fn resid_work(&self) -> Array1<F>

Returns the working residuals:

e_i^\text{work} = \frac{\eta'(\omega_i)(y_i - \hat\mu_i)}{V(\hat\mu_i)}

Equal to the response residuals divided by the variance function (as opposed to the square root of the variance as in the Pearson residuals).

pub fn score(&self, params: &Array1<F>) -> Array1<F>

Returns the score function $\nabla_{\boldsymbol\beta} l$ (the gradient of the log-likelihood) at the parameter values given. Should be zero at the MLE.

pub fn score_test(&self) -> RegressionResult<F>

Returns the score test statistic:

S = \mathbf{J}(\boldsymbol\beta_0)^\mathsf{T} \, \mathcal{I}(\boldsymbol\beta_0)^{-1} \, \mathbf{J}(\boldsymbol\beta_0)

where $\mathbf{J}$ is the score and $\mathcal{I}$ is the Fisher information, both evaluated at the null parameters. Asymptotically $\chi^2$-distributed with test_ndf() degrees of freedom.

pub fn score_test_against(&self, alternative: Array1<F>) -> RegressionResult<F>

Returns the score test statistic compared to another set of model parameters, not necessarily a null model. The degrees of freedom cannot be generally inferred.

pub fn test_ndf(&self) -> usize

The degrees of freedom for the likelihood ratio test, the score test, and the Wald test. Not to be confused with ndf(), the degrees of freedom in the model fit.

pub fn wald_test(&self) -> F

Returns the Wald test statistic:

W = (\hat{\boldsymbol\beta} - \boldsymbol\beta_0)^\mathsf{T} \, \mathcal{I}(\boldsymbol\beta_0) \, (\hat{\boldsymbol\beta} - \boldsymbol\beta_0)

Compared to a null model with only an intercept (if one is used). Asymptotically $\chi^2$-distributed with test_ndf() degrees of freedom.

pub fn wald_test_against(&self, alternative: &Array1<F>) -> F

Returns the Wald test statistic compared to another specified model fit instead of the null model. The degrees of freedom cannot be generally inferred.

pub fn wald_z(&self) -> RegressionResult<Array1<F>>

Returns the per-parameter Wald $z$-statistic:

z_k = \frac{\hat\beta_k}{\sqrt{\text{Cov}[\hat{\boldsymbol\beta}]_{kk}}}

Since it does not account for covariance between parameters it may not be accurate.

impl<'a, F> Fit<'a, Linear, F>

where F: 'static + Float,

Specialized functions for OLS.

pub fn r_sq(&self) -> F

Returns the coefficient of determination $R^2$:

R^2 = 1 - \frac{\text{RSS}}{\text{TSS}}

where RSS is the residual sum of squares and TSS is the total sum of squares.

pub fn resid_sum_sq(&self) -> F

Returns the residual sum of squares: $\text{RSS} = \sum_i (y_i - \hat\mu_i)^2$.