Fit outcomes and set priors

Examples use import kernelmix as km. See the tutorial for a complete analysis.

Fitting

km.fit(
    y, Z, X=None, *, family="gaussian", draws=1000, warmup=1000,
    chains=4, thin=1, seed=None, standardize=True, intercept=True,
    selection="none", groups=None, prior=None, r_fixed=None, missing="raise",
    exposure_names=None, covariate_names=None, initial=None, proposal_scales=None,
    cluster=None, offset=None, event=None, baseline_breaks=None,
    kernel="gaussian", kernel_alpha=1, approximation="dense", n_components=32,
    knots=None, random_slopes=None, random_covariance=None, random_scale=2,
    correlation=None, observation_time=None, correlation_parameter=None,
    variance_design=None, entry=None, upper=None, subject=None, n_causes=None,
)

fit returns a BKMRFit object. Selecting a structured option returns its StructuredFit subclass; the structured-model guide defines the additional inputs, priors, array shapes and predictions.

Family	Required outcome inputs	Mean or probability
Gaussian	Numeric y	Continuous outcome mean
Binomial	y equal to 0 or 1	Probit probability
Poisson / negative binomial	Nonnegative integer y; offset when needed	Count mean, including the log offset
Survival	Default: positive observed times and binary event; structured: cause codes, entry and censoring bounds	Relative hazard from predict; survival/hazard from predict_survival

cluster supplies one string or integer label per observation. Missing labels participate in missing="drop". Integer 1 and string "1" are distinct. offset is a finite vector of log observation exposures for count families. event is required only for survival; baseline_breaks supplies internal positive, strictly increasing cuts. Omit cuts to use event-time deciles, or pass [] for a constant baseline hazard. Family-specific arguments are rejected elsewhere.

Input	Meaning
y, Z, X	Outcome vector, exposure matrix and optional adjustment matrix, with matching rows. Supply raw adjustment columns without an intercept when intercept=True.
family	"gaussian", "binomial" (probit), "poisson", "negative_binomial" (NB2) or "survival" (piecewise-exponential proportional hazards).
draws, warmup, chains, thin	Saved draws per chain, discarded iterations, sequential chains and spacing between saved draws. Total iterations per chain are warmup + draws * thin. At least two saved draws are required.
seed	Nonnegative integer or None; uses local random generators without changing NumPy's global random state.
standardize	Center exposures and divide by retained-training sample standard deviations. Constant exposures are invalid when this is enabled.
selection	"none", "component" or "group". Group selection requires one groups label per exposure and permits at most one active exposure in each included group.
prior	Prior, a dictionary of its fields, or None for defaults.
r_fixed	Finite nonnegative vector fixing exposure relevance values; disallows variable selection.
missing	"raise" or joint complete-case "drop". Infinity remains invalid except for right-censoring upper bounds.
Names	Optional unique names for exposure and raw adjustment columns. Otherwise use input DataFrame columns, or generated names.
initial	Shared starting values; omitted entries use defaults. See initialization.
proposal_scales	Fixed positive log-scale proposal standard deviations (SDs), default 0.3. All routes accept r and lambda; default clustered fits add cluster_lambda, NB2 adds dispersion, and structured survival adds baseline_hazard.

Adjustment columns must be linearly independent, with fewer columns than retained rows. Default probit fits reject complete or quasi-complete separation, where covariates separate outcome classes, possibly with observations on the boundary. With the default flat coefficient prior, the unnormalized posterior density can then have an infinite integral. Structured fits use a proper normal prior.

For computation, dense fitting uses \(O(n^2)\) memory and \(O(n^3)\) matrix operations, where \(n\) is the retained observation count. Finite GP bases reduce this cost, but correlated residual blocks may remain dense.

Initialization

Fitting route	initial keys
Default Gaussian/probit	beta, r, lambda, delta, pi, sigma2; probit adds ystar
Default count/survival	beta, r, lambda, delta, pi, latent_white; NB2 adds dispersion, survival adds baseline_hazard
Default clustered fits	Add lambda_cluster; count/survival also add u_white
Structured	Cause-indexed coefficients and gp_weight; see shapes and restrictions

Inapplicable keys raise errors.

Prior configuration

km.Prior(
    r_distribution="invunif", r_mean=5.0, r_sd=5.0,
    r_lower=0.0, r_upper=100.0, lambda_mean=10.0, lambda_sd=10.0,
    sigma2_shape=0.001, sigma2_rate=0.001,
    inclusion_alpha=1.0, inclusion_beta=1.0,
    cluster_lambda_mean=10.0, cluster_lambda_sd=10.0, beta_sd=5.0,
    dispersion_shape=2.0, dispersion_rate=0.1,
    baseline_shape=0.1, baseline_rate=0.1,
)

Check each prior's parameterization when setting its fields. r_distribution accepts "gamma", "unif" or "invunif"; inverse-uniform bounds apply to 1/r for active exposures, while excluded exposures have r=0. Relevance and amplitude gamma priors use mean/SD fields; dispersion and baseline gamma priors use shape/rate. Residual variance uses inverse-gamma shape/rate, and inclusion probabilities use a beta prior. See the prior definitions.

For the default count/survival sampler, prior=None uses lambda_mean=1, lambda_sd=.5, cluster_lambda_mean=1, cluster_lambda_sd=.5; the other fields retain their listed defaults. A dictionary changes the supplied fields and keeps the family's other defaults. A Prior object supplies all its values explicitly, including its listed amplitude defaults. beta_sd controls the proper coefficient prior for count/survival. Dispersion and baseline parameters use gamma shape/rate. Structured priors use a direct GP amplitude and separate Gaussian residual-variance defaults.