Julia API reference

glm(X, y, family, link; kwargs...)
glm(formula, data, family, link; kwargs...)

Fit a generalized linear model and return a StatisticalResult. Use distributions from Distributions.jl and links from GLM.jl:

Binary responses must be numeric 0/1 values. For binomial success counts with known trials and Tweedie regression, use the named-family fit interface. The distribution constructor's probability is not the fitted mean.

All common input, backend, solver, initialization and inference keywords are documented under fit. The distribution/link select the family parameters; do not pass a separate family_options keyword. Formula fitting requires StatsModels; the formula controls the intercept and is retained for prediction.

Example

using SpectralMM, Distributions, GLM
X = [sin(i*j) for i in 1:100, j in 1:3]
y = Float64.(isodd.(1:100))
m = SpectralMM.glm(X, y, Bernoulli(), LogitLink(); solver=:pcg)
predict(m, X)

fit(X, y; family=:gaussian, kwargs...)
fit(formula, data; family=:gaussian, kwargs...)
fit(X, y, loss; kwargs...)

Fit a model from a predictor matrix and response vector, or from a StatsModels formula and table. Matrix rows are observations. Dense and sparse real matrices are accepted. The exported loss objects are PseudoHuber, Expectile, SmoothQuantile, and StudentT.

Model specification

• family=:gaussian: one of :gaussian, :gaussian_log, :bernoulli, :probit, :poisson, :gamma, :gamma_inverse, :negative_binomial, :binomial, :tweedie, :pseudo_huber, :expectile, :smooth_quantile, :student_t.
• family_options=NamedTuple(): fixed family parameters. Supported keys/defaults: negative binomial (theta=1.0,); binomial (trials=1.0,) (scalar or per-row); Tweedie (power=1.5,), with 1 < power < 2; Pseudo-Huber (delta=1.0,); expectile (q=0.5,); smoothed quantile (q=0.5, smoothing=0.1); Student-t (nu=4.0, sigma=1.0). Binomial responses are success counts. With a positional loss object, specify tuning parameters in its constructor.
• backend=:julia: use :cpp for the shared C++ implementation. Its first use builds and caches the library and requires a C++17 compiler.
• intercept=true: prepend an intercept for matrix input. Set false for a complete design. Formula input controls its intercept and rejects this keyword.
• start=nothing: initial coefficient vector, including the intercept first. beta0 is an alias; supplying both raises an error. Omission uses backend initialization. weights and offset are not implemented and must be nothing.

Numerical options

• solver=:pcg: also :mm, :cg, :cho, :cgls, :crls, :lsqr, :lsmr; aliases :spectral and :cholesky select :pcg and :cho.
• rank=nothing: retained spectral rank; defaults to p-1 for p<20, otherwise 10, where p includes the intercept. Requires 1 <= rank < p (rank=0 for p=1).
• maxiter=200, inner_maxiter=100: outer and inner iteration limits.
• gtol=1e-7, relgtol=1e-8: absolute and relative gradient tolerances.
• floor=1e-6: positive spectral floor; ridge=0.0: nonnegative ridge penalty; penalize_intercept=false: exclude an automatically fitted intercept from ridge.
• verbose=false: print iteration diagnostics. C++ also supports trace=false to retain structured iteration rows.
• control=SpectralMMControl(): additional backend/solver-specific options; supported numerical options may also be passed directly. See SpectralMMControl.

Inference options

• inference=:auto: attempt inference for at most inference_max_p=50 total coefficients. true bypasses only this size limit; false disables inference.
• cov_type=:auto: model-based for GLMs, HC1 sandwich for residual losses. Explicit values are :model or :sandwich, subject to family restrictions.
• level=0.95: confidence level; use_t=nothing: select the reference distribution automatically (true requests t, false requests normal).
• dispersion=nothing: estimate dispersion where applicable, or provide a positive fixed value for model-based covariance.

Inference is withheld for failed validity checks, including insufficient gradient convergence, unidentified coefficients and ridge penalties. It can form dense coefficient matrices even when fitting is matrix-free.

Returns

A StatisticalResult for the named families and exported residual losses. Use diagnostics to inspect convergence, and predict for response or link predictions. Unsupported combinations raise errors.

Example

using SpectralMM
X = [sin(i*j) for i in 1:100, j in 1:3]
y = [cos(i) for i in 1:100]
m = SpectralMM.fit(X, y, PseudoHuber(); inference=false)
coef(m)

SpectralMMControl(; kwargs...)

Collect advanced numerical options for fit and glm. Pass the result as control=SpectralMMControl(maxiter=500, gtol=1e-8). Only supplied settings are stored; omitted settings retain the selected backend/solver defaults. Duplicating an option in control and direct keywords raises ArgumentError. Unknown option names are rejected.

Options

• Iteration limits: maxiter, inner_maxiter.
• Spectral approximation: krylovdim, floor, eta_max, correction_tol, resid_tol.
• Penalty and convergence: ridge, gtol, relgtol.
• Iterative solves: preconditioner (:jacobi or :none); Julia uses krylov_reltol/krylov_abstol, C++ uses krylov_rtol/krylov_atol.
• Stopping safeguards: accept_stalled, step_reltol, stalled_relgtol; C++ additionally exposes accept_negligible, negligible_step_tol.
• Solver-specific controls: nesterov, line_search, alpha_min, backtrack_factor, c_armijo, chol_jitter, max_chol_tries.

Acceptance by this container does not imply support by every solver/backend; unsupported options raise an error during fitting. solver, rank, backend, initial coefficients and inference settings are direct fitting keywords, not control fields. See the fitting docstring for common defaults.

StatisticalResult <: StatsAPI.RegressionModel

Statistical result returned by the public GLM and named-family fitting routes. Use coef, predict, fitted, residuals, nobs, and the inference/statistics accessors below.

Properties include family, link, formula, coefficient_names, intercept, objective, nparams, and backend. model holds the backend result; diagnostics returns optimization metadata. A successful fit does not imply available inference: inspect model.inference.status and .reason. modelmatrix is not implemented for this result type. Obtain results through fitting functions rather than constructing this metadata container manually.

coef(model::StatisticalResult)

Return the coefficient vector in fitted order, including any intercept first.

predict(model::StatisticalResult, newdata=nothing; type=:response, trials=nothing)

Predict response means (type=:response, default) or linear predictors (type=:link). Omitting newdata returns a copy of cached training predictions. For matrix input use the same feature order as fitting, excluding an automatically added intercept. A formula-fitted model also accepts tables and applies its saved schema and categorical contrasts. New feature dimensions must match.

trials applies only to binomial success-count models; provide a scalar or values for the prediction rows when training trials cannot be reused. Response predictions for these models are expected counts. Residual-loss predictions are fitted locations.

fitted(model::StatisticalResult)

Return a copy of the fitted response means (expected counts for grouped binomial).

residuals(model::StatisticalResult)

Return response residuals y - fitted(model).

nobs(model::StatisticalResult)

Return the number of observations used for fitting.

diagnostics(model::StatisticalResult)

Return stored optimization metadata as a named tuple, including the objective, absolute/relative gradients, convergence, iterations, solver, rank, backend, Krylov dimension and numerical controls. Does not refit or recompute inference. An unavailable exact stopping reason is reported explicitly.

vcov(model::StatisticalResult)

Return the full post-fit coefficient covariance matrix. Throws an informative error if inference is disabled, skipped or unavailable; does not compute inference on demand.

stderror(model::StatisticalResult)

Return coefficient standard errors from stored post-fit inference. Throws if inference is unavailable; does not compute inference on demand.

confint(model::StatisticalResult; level=0.95)

Return a two-column matrix of lower and upper coefficient confidence limits. Requires available inference and 0 < level < 1; uses the stored t/normal reference distribution.

coeftable(model::StatisticalResult)

Return a GLM.CoefTable with estimates, standard errors, t/z statistics and two-sided p-values. Requires available inference.

deviance(model::StatisticalResult)

Return unscaled GLM deviance, excluding ridge penalties. Throws for residual losses and Tweedie, whose deviance is not implemented in the statistical result layer.

loglikelihood(model::StatisticalResult)

Return normalized log likelihood excluding penalties, where implemented. Gaussian uses RSS/n unless dispersion is supplied; Gamma uses supplied or Pearson dispersion. Student-t includes its fixed-scale normalization constant. Throws for unsupported losses and Tweedie; returns NaN for noninteger discrete responses or unavailable dispersion.

PseudoHuber(delta=1.0)

Pseudo-Huber residual loss with positive transition parameter delta. Pass the object as SpectralMM.fit(X, y, loss; kwargs...); see fit.

Expectile(q=0.5)

Asymmetric squared residual loss at expectile level 0 < q < 1. Pass the object as SpectralMM.fit(X, y, loss; kwargs...); see fit.

SmoothQuantile(q=0.5, epsilon=0.1)

Smoothed quantile residual loss with 0 < q < 1 and positive smoothing parameter epsilon. Inference concerns the smoothed objective. Pass the object as SpectralMM.fit(X, y, loss; kwargs...); see fit.

StudentT(nu=4.0, sigma=1.0)

Student-t residual loss with positive degrees of freedom nu and fixed positive residual scale sigma. These parameters are supplied, not estimated. Pass the object as SpectralMM.fit(X, y, loss; kwargs...); see fit.

spectral_mm(X::AbstractMatrix{T}, y::AbstractVector{T};
            family=SpectralMM.BernoulliLogit(), beta0=nothing,
            spectral=SpectralOptions{T}(), inner=InnerOptions{T}(),
            outer=OuterOptions{T}()) where T<:Real

Run the low-level pure Julia spectral optimizer, returning MMResult. X is the complete design matrix: this function does not add an intercept. y has one value per row and the same element type as X. beta0 supplies an initial coefficient vector; family is an internal IRLSFamily object (exported residual-loss objects also qualify). Use fit or glm for ordinary statistical modeling, formulas and post-fit inference.

spectral, inner and outer configure approximation, inner iterations and outer stopping. Only inner.solver=:mm or :pcg is supported here. The default rank is 5; adjust it to the design dimension before calling.

SpectralOptions{T}(; kwargs...)

Spectral approximation and regularization options for spectral_mm. Use a floating-point type such as Float64. Defaults below are low-level defaults; high-level fitting may select different values.

k is retained rank, rho is the spectral floor, and ridge is the penalty. Choose k < size(X, 2); an intercept must already be in the design. krylovdim controls the Lanczos subspace; correction/restart settings control spectrum refresh. penalize_intercept=true is the low-level default.

InnerOptions{T}(; kwargs...)

Inner spectral MM/PCG iteration options for spectral_mm. Use a floating-point type such as Float64. Defaults below are low-level defaults; high-level fitting may select different values.

solver accepts only :mm or :pcg. The forcing tolerance is bounded by eta_max, with scaling forcing_c and exponent forcing_alpha. alpha_min, alpha_max and shrink control inner step selection.

OuterOptions{T}(; kwargs...)

Outer iteration and stopping options for spectral_mm. Use a floating-point type such as Float64. Defaults below are low-level defaults; high-level fitting may select different values.

gtol/relgtol control gradient stopping; w_floor bounds working weights. accept_stalled, step_reltol and stalled_relgtol control stalled-step acceptance. safeguard enables the outer objective safeguard.

MMResult

Low-level Julia spectral solver result. beta holds final coefficients; losses, gradnorms, relgradnorms, eigresiduals, inner_iters, inner_stats, outer_steps, restart_flags and correction_failed_flags record diagnostics. restarts, iters and converged summarize the solve. No statistical inference is computed by this result type. See spectral_mm.

SpectralGLM

Julia-backend GLM result containing coefficients, design, response, distribution/link, solver result and optional inference. The public statistical interface wraps this in StatisticalResult.

SpectralModel

Julia-backend result for an internal residual or GLM family, containing coefficients, design, response, solver result and optional inference. The public statistical interface wraps this in StatisticalResult.

FittedModel

C++ backend result holding coef, family, family_options, info, intercept, inference and optional trace. The public statistical interface wraps this result in StatisticalResult. Obtain it through fitting, not manual construction.