Extract an experimental heritability confidence interval — heritability

Usage

heritability_interval(object, ...)

Arguments

object: A fitted model object.
...: Unused. Extra arguments, including level, are an error because they would be ignored; the interval level is fixed at the engine value.

Value

A one-row data frame with estimate, lower, upper, level, se (NA for the profile method), and method, for hsquared_fit objects that contain it.

Details

heritability_interval() returns an experimental large-sample confidence interval for h^2. It is available when an hsquared_fit object contains the interval field, which the default Gaussian animal-model fit (engine = "fit") populates from the engine's HSquared.heritability_interval() when a local Julia engine is present. A non-converged or variance-component-boundary fit still returns that engine row when it is present: the extractor warns and keeps the number for inspection (the same warn-and-return as heritability()). Those numbers must not be reported. print() says the heritability is not reportable when the fit did not converge. summary() omits the printed SE/CI block when the fit did not converge or is at a variance-component boundary. The engine omits the field only when it could not compute the interval (for example when the information matrix is not invertible), not merely because the estimate sits near 0 or 1. Printed endpoints may be 0 or 1 even though the Julia docstring describes a logit-delta interval that always lies in (0, 1). On the opt-in two-effect fit it returns the direct-heritability ratio interval (ratio1), and on the opt-in multi-effect fit (target = "multi_effect", K >= 3 blocks) it returns the ANIMAL block's ratio interval (the animal additive variance over the total phenotypic variance); the other blocks' variance-ratio intervals are surfaced separately in fit$result$variance_ratio_intervals.

The interval leg is a REML-only, asymptotic (logit delta-method or profile) approximation returned by the engine. On the default univariate route the SE comes from the REML average-information matrix. On the repeatability, two-effect, and multivariate routes the engine uses the observed information from a central finite-difference Hessian (fd_step = 1e-4). Those two matrices are not the same estimand; do not compare SEs across routes as if they were. R cannot request the profile interval from this extractor; only the engine-returned interval is shown. See the information-matrix table on Can I fit and report this?. The 2000-rep C1 coverage confirm (HSquared.jl DRAC job 47925485) places the univariate pedigree h² interval at the directional-conservative claim level under doc-34 §4: delta over-covers (worst Ĉ 0.969), profile is in-band (worst Ĉ 0.950), and bootstrap mildly under-covers versus nominal 0.95 at the governing interior cell (worst Ĉ 0.924 at h²=0.5, still at least 0.90). Those figures were measured on one interpretable small design (q = 120), at interior h² in {0.3, 0.5, 0.7}, at the 0.95 level, in DRAC job 47925485; unbalanced designs were not in the confirm grid, so these numbers say nothing about coverage under imbalance. That is not coverage-calibrated at nominal and not "never under-covers." Profile and bootstrap h² interval legs were measured in the same confirm but are not separately surfaced by this extractor; only the engine-returned interval is shown. It is reported as a point estimate plus bounds, not a validated (coverage-calibrated) capability. The Wald SE and this logit-delta CI are not valid when additive variance is near 0 (h^2 -> 0 is the same edge): that is an interior-point approximation. The likelihood-ratio test of V_A = 0 uses a 50:50 mixture of chi^2_0 and chi^2_1 (Self and Liang 1987; Stram and Lee 1994). R anova() does not run it; Julia HSquared.nested_lrt(..., df = 1, boundary_df = 1) already does. Genomic fits still error (scale-labelled interval not validated). The underlying estimators V3-TWOEFFECT-REML / V3-NEFFECT-REML are covered, but this interval is not.