JiaruiLi/SpectraREML
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Handle boundary and line-search fixed-effect inference

Browse Source
This commit is contained in:
Jiarui Li
2026-08-14 16:54:57 +08:00
parent 48ab77f9ab
commit 9033201948
10 changed files with 220 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
docs/FORMAT.md
View File

@@ -165,7 +165,7 @@ The covariance array uses the row-wise packed lower triangle:
The `.complete` marker is written last and contains tab-separated key/value rows:
```text
format spectra-reml-block-v3
format spectra-reml-block-v4
block 0
tasks 256
beta_elements 4096
@@ -198,34 +198,39 @@ numerical_error
The four `fixed_*` arrays have the same offsets and coefficient order as
`beta`. They contain standard errors, statistics, denominator degrees of
freedom, and p-values. With Satterthwaite inference, a coefficient statistic is
a signed t statistic. With Kenward-Roger inference, it is an F statistic with
one numerator degree of freedom. For every task with extra covariates, the
summary also contains an F test of the joint null that all task-specific fixed
effects are zero.
freedom, and p-values. With ordinary least-squares or Satterthwaite inference,
a coefficient statistic is a signed t statistic. With Kenward-Roger inference,
it is an F statistic with one numerator degree of freedom. For every task with
extra covariates, the summary also contains a test of the joint null that all
task-specific fixed effects are zero.
The six `contrast_*` arrays share `contrast_test_offset` and follow the
contrast metadata order. A one-row Satterthwaite contrast reports a signed t
statistic; Kenward-Roger reports an F statistic with one numerator degree of
freedom. Both methods retain the signed `L beta` estimate and their adjusted
standard error. Negative `contrast_test_offset` means that no valid contrast
tests were emitted for that task.
contrast metadata order. A one-row ordinary least-squares or Satterthwaite
contrast reports a signed t statistic; Kenward-Roger reports an F statistic
with one numerator degree of freedom. All methods retain the signed `L beta`
estimate and their standard error. Negative `contrast_test_offset` means that
no valid contrast tests were emitted for that task.
`fixed_test_status` is one of:
```text
not_requested
ok
boundary_conditional
boundary_ols
line_search_conditional
fit_not_converged
invalid_contrast
information_singular
numerical_error
```
At `converged_boundary`, inference conditions on the accepted active set
`sigma_g2=0`; `fixed_test_status` is `boundary_conditional` and only residual
variance uncertainty contributes to the small-sample adjustment.
At `converged_boundary`, the random term is removed and the fixed model is
refitted as ordinary least squares. `fixed_test_method` is
`ordinary-least-squares`, `fixed_test_status` is `boundary_ols`, and the
denominator degrees of freedom are `n-rank(X)`. At `line_search_failed`, the
last retained REML iterate is tested with the requested Satterthwaite or
Kenward-Roger method and `fixed_test_status` is
`line_search_conditional`; the optimizer flag remains visible in `status`.
Phenotypes are scaled internally by their task-specific OLS residual RMS before
optimization. Reported fixed effects, fixed-effect covariance, variance