Exposure contrasts and curves

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

Exposure contrasts and curves

Exposure contrasts compare predictions at specified profiles. A quantile profile sets each exposure to a percentile of its own distribution; the all-median profile uses every exposure's median. Such combinations need not occur in observed rows.

km.overall_effect(
    fit, quantiles=(0.25, 0.5, 0.75), reference=0.5, scale="latent",
    X=None, probability=0.95, max_draws=None, seed=None,
)

km.univariate_response(
    fit, variable=None, grid=None, points=50, fixed_quantile=0.5,
    center=True, scale="latent", X=None, probability=0.95,
    max_draws=None, seed=None,
)

km.bivariate_response(
    fit, variables=(0, 1), grids=None, points=20, fixed_quantile=0.5,
    center=True, scale="latent", X=None, probability=0.95,
    max_draws=None, seed=None,
)

km.single_exposure_effects(
    fit, quantiles=(0.25, 0.75), fixed_quantiles=(0.25, 0.5, 0.75),
    scale="latent", X=None, probability=0.95, max_draws=None, seed=None,
)

km.interaction_effects(
    fit, variables=None, quantiles=(0.25, 0.75), fixed_quantile=0.5,
    scale="latent", X=None, probability=0.95, max_draws=None, seed=None,
)

Function	Quantity and result
overall_effect	Each all-exposure quantile profile minus the all-exposure reference profile. Returns EffectResult.
univariate_response	One named or zero-based indexed exposure, or all exposures with variable=None. Other exposures stay at fixed_quantile. Returns one joint CurveResult.
bivariate_response	Every combination of the supplied grid values for two distinct exposures. Other exposures stay at fixed_quantile. Returns SurfaceResult.
single_exposure_effects	High-minus-low quantile contrast for each exposure at every background fixed_quantiles value. Returns EffectResult.
interaction_effects	All unordered pairs from the selected names/indices, or all exposures by default. Returns EffectResult. For each pair the contrast is high/high - low/high - high/low + low/low, with other exposures fixed.

Quantiles use retained original training exposures and lie in [0, 1]. Default grids span the observed range; explicit grids must be finite, nonempty and strictly increasing. An all-variable curve shares one supplied grid; a surface uses one sequence per axis in grids. Dense joint calculations limit calls to 4096 output locations.

With center=True, curves and surfaces subtract the all-median reference profile, even if fixed_quantile is changed. This differs from R bkmr curve centering by the average fitted grid value. The pairwise interaction above also differs from the R summary that changes all background exposures together. These definitions should be specified when comparing results between packages.

Summary scale	Target
Latent	Contrasts of h; X is rejected
Response	Gaussian/count means, binary probabilities or survival relative hazards; random effects are zero
Count response	Zero log offset, representing unit observation exposure
Survival response	Differences in relative hazards, not hazard ratios or survival-probability differences

For response summaries, X fixes one raw adjustment vector, defaulting to training covariate means. Each joint draw is transformed to the requested scale before subtraction. This retains covariance and makes identical-profile contrasts exactly zero.

Results store draws shaped (chains, selected_draws, locations), mean, sd, lower, upper, scale, probability, kind and metadata. locations labels outputs; profiles holds distinct original-unit rows; coefficients maps joint profile draws to summaries. to_records() combines locations and summaries. SurfaceResult adds variables, grids and shape; reshape summaries to shape with the second grid changing fastest.

These summaries describe associations at the specified values of the other variables. Check that nearby exposure combinations occur in the data. The intervals do not account for unmeasured confounding or a wrongly specified model.