onsetwindow: Individual Risk Trajectories for Alzheimer’s Disease as an Accumulating, Whole-Body Process
Individual burden trajectories under the accumulating, whole-body burden model of Alzheimer's disease described in the Perspective "Risk with a clock: reconsidering Alzheimer's disease as an accumulating, whole-body process" (Barnaghi, Fogel, Biggart, Pownall, Ricotti and Voit).
Given one person's sex, genotype, reserve, environment and exposure histories, onsetwindow computes the accumulated burden .param file.
Research prototype. The example parameters are synthetic and describe no real person. The framework and its implementation are research hypotheses intended to generate testable predictions; it has not been validated in patients, and no output should be used to inform diagnosis, prognosis or treatment.
git clone <your-repo-url> onsetwindow
cd onsetwindow
pip install -e ".[dev]" # numpy; scipy and pytest for speed and testsonsetwindow examples/parameters.param --out results
# or, without installing:
PYTHONPATH=src python -m onsetwindow examples/parameters.param --out resultsConsole output for the synthetic example:
Threshold theta_i: 9.400 transition age T_i: 74.3 rho_i: 0.158
age S(t) pi(t) pibar(t) next 5y
40 3.313 0.001 0.001 0.001
50 4.968 0.005 0.005 0.008
60 6.674 0.037 0.037 0.058
65 7.492 0.092 0.092 0.209
70 8.621 0.282 0.282 0.352
75 9.517 0.535 0.535 0.436
80 10.262 0.738 0.738 0.457
...
W_i(metabolic) [exposure x0.5, delta=2 y]: start ages 20-72
W_i(vascular) [exposure x0.5, delta=2 y]: start ages 20-70
W_i(immune) [exposure x0.5, delta=2 y]: start ages 20-65
W_i(latent) [exposure x0.5, delta=2 y]: start ages 20-70
examples/parameters_psen1_carrier.param is the same synthetic person carrying a pathogenic PSEN1 variant.
Files written to --out:
| File | Content |
|---|---|
risk_by_age.csv |
For each report age: |
trajectory.csv |
The same quantities on the full age grid |
window.csv |
For each target and start age u: new |
summary.json |
|
From Python:
from onsetwindow import load_parameters, simulate, risk_by_age, window_of_opportunity, Intervention
p = load_parameters("examples/parameters.param")
traj = simulate(p)
print(traj.T, traj.rho)
rows = risk_by_age(traj, [60, 70, 80], horizon=5)
treated = simulate(p, [Intervention("metabolic", start_age=50, scale=0.5)])
print(treated.T - traj.T)| Paper | Code | Meaning |
|---|---|---|
| Eq. (1) |
simulate |
Accumulated burden |
kernel_integral |
Memory kernel; tau = inf gives a permanent contribution |
|
weight_F, weight_M, weight_genotype
|
|
|
| Eq. (2) |
domain section | Exposure generated by propensity × opportunity |
onset_age, onset_genotype, onset_env
|
Age at which the domain switches on | |
| Eq. (3) |
[latent], nu
|
Latent capacity deficit shared across domains |
kappa |
Optional direct contribution of the deficit | |
| Eq. (4) |
[threshold], [gamma], [eta]
|
Manifestation as a transition |
Trajectory.T |
First crossing, interpolated between grid points | |
Trajectory.pibar |
Probability of having manifested by age t (absorbing) | |
| Eq. (5) |
Trajectory.rho |
Share of the threshold supplied by the genetic term |
| Eq. (6) |
window_of_opportunity |
Start ages at which a sustained intervention shifts |
The integral is updated exactly for exposure that is constant within each step dt, so results do not depend on dt beyond the resolution of the input profiles.
Risk at an age. pibar is the reported risk of having manifested by that age. risk_next_h is the conditional risk of manifesting within h years,
Window of opportunity. An intervention multiplies the target's exposure by scale from start age u onwards and is sustained. Because an earlier sustained intervention never does worse, the lower edge of the reported window is usually start_min. The informative quantity is the upper edge, the latest start age that still shifts delta. If an intervention prevents any crossing before age_max,
Deliberately not implemented. The residual group-level term
INI format: [section], key = value, comments after # or ;. Lists are comma-separated. Gene coefficients are written LOCUS:value, and inf is accepted wherever a number is expected. examples/parameters.param is fully commented.
| Section | Keys |
|---|---|
[simulation] |
age_start (0), age_max, dt (0.1), report_ages, risk_horizon (5) |
[individual] |
id, sex (F/M), environment ( |
[genotype] |
one line per locus: |
[beta] |
|
[reserve], [gamma]
|
reserve proxies |
[reserve_genotype], [eta]
|
tolerance-acting variants |
[threshold] |
theta0, a
|
[latent] |
ages, values, interpolation (linear/step), kappa
|
[domain:NAME] |
weight_F, weight_M, weight_genotype, tau, lambda0, lambda_genotype, opportunity_ages, opportunity_values, opportunity_interpolation, env_baseline (1), env_coef (0), onset_age, onset_genotype, onset_env, nu
|
[window] (optional) |
targets (domain names or latent), scale (one value, or one per target), delta, start_min, start_max, start_step
|
The opportunity profile is env_baseline and env_coef. A domain whose exposure is the environment (for example deprivation) uses env_baseline = 0, env_coef = 1.
The loader checks the file and stops with a clear message for: an unknown sex; a locus used in a coefficient but missing from [genotype]; non-increasing profile ages; negative nu, kappa, lambda0 or latent values; a non-positive tau or a; and a window target that is not a domain.
pytest -qThe tests check the kernel integral against closed forms and
- Do not commit parameter files that contain data from real participants.
.gitignoreexcludesdata/and*.private.param. - Coefficients must be estimated with causal methods (for example target-trial emulation and Mendelian randomisation, as the paper argues) before outputs are interpreted for individuals.
- Sex enters only through the weights
$w_k(s)$ , as in the paper. It is a modelling choice to test, not an assumption to report as a finding.
See CITATION.cff. Please also cite the Perspective once it is published.
MIT. See LICENSE.