RejuvenationKit

RejuvenationKit is a typed Python toolkit for auditing and analyzing longitudinal preclinical rejuvenation studies. It sits above established assay-specific pipelines and helps research teams answer:

Is this study trustworthy, did the intervention produce a coherent response, when did it appear, and which measurement systems contributed the evidence?

All four roadmap phases are available as an integrated alpha. Phase 1 includes protocol-aware quality control, analysis-readiness profiling, experimental-confounding checks, held-out DSP change detection, sequential response monitoring, randomized longitudinal inference, and reproducible report bundles. Phase 2 adds calibrated fixed- and random-effects multimodal fusion, evidence-level covariance and hierarchical fusion, dense/sparse genome-scale matrices, genomic signatures, leakage-aware target calibration, optional provenance-tracked Hugging Face sequence embeddings, and an offline provider-neutral layer for versioned annotations, gene sets, overrepresentation analysis, interaction networks, variant context, ortholog maps, and public sequencing-study manifests. Phase 3 adds irregular-time latent-state filtering, smoothing, forecasting, held-out calibration, and innovation change detection. Phase 4 adds explicit endpoint bridges, factorial combination-therapy estimands, design diagnostics, and design helpers.

This project is for research use. It is not medical software and does not produce treatment recommendations.

Who this is for

RejuvenationKit is designed for:

• preclinical gene-therapy and longevity teams comparing constructs, doses, or vector lots;
• canine-aging and veterinary-trial researchers with repeated visits and heterogeneous endpoints;
• computational biologists who need a decision layer above RNA-seq, methylation, proteomics, histology, imaging, or clinical-assay pipelines; and
• collaborators reviewing whether a study is ready to support an efficacy claim.

It is especially useful when an experiment combines several noisy readouts and risks confusing biology with site, plate, assay run, operator, manufacturing lot, or visit timing.

What it catches

• Missing visits and missing features at expected visits
• Treatment, cohort, or timepoint confounding with experimental handling
• Batch shifts, replicate disagreement, distribution anomalies, and attrition bias
• Weak paired-analysis sample sizes hidden by apparently large enrollment
• Multichannel responses that emerge gradually or persist across visits
• Individual trajectory departures and dominant evidence modalities
• False precision from correlated clocks or several signatures built from the same omics data
• Species, tissue, feature-namespace, and training/evaluation-domain mismatches in genomic models
• Unresolved or mismatched external-resource releases, query domains, feature sets, and assemblies
• Enrichment analyses with an invalid selected/background relationship or hidden test family
• Sequencing manifests that confuse technical runs with independent animals
• Randomized treatment effects calibrated without fitting the null model on treated subjects

Public canine validation

The one-command audit was run end to end on public Dog Aging Project longitudinal chemistry data:

Result	Observed
Dogs	972
Long-form observations	6,808
Complete-case retention to the second wave	75.5%
Held-out complete trajectories scored	213
Held-out trajectories crossing the nominal 5% threshold	11

The cohort is observational and contains no rapamycin assignment, so detections are not treatment effects. The case demonstrates real ingestion, missingness, retention, held-out calibration, reporting, and artifact integrity. See the DAP audit case study. These figures record a prior online reference run. CI exercises the adapter with a bounded fixture, but the original downloaded archive digest was not retained, so the exact counts are not presented as a content-addressed regression target.

Evaluate it with a study

The most valuable feedback is a de-identified, simulated, or public dataset shaped like a real preclinical workflow. Open a study-evaluation request with the decision, visit schedule, modalities, and known complications. Do not attach confidential or identifiable data to a public issue.

Architecture

Study / subject / observation schemas
                 │
        ┌────────▼────────┐
        │ Phase 1: Trust  │  QC, readiness, DSP diagnostics
        └────────┬────────┘
                 │
             QC gate
       ┌─────────┼──────────┐
       │         │          │
┌──────▼─────┐ ┌─▼────────┐ ┌▼──────────────┐
│ Phase 2    │ │ Phase 3  │ │ Phase 4       │
│ evidence   │ │ state    │ │ combinations  │
│ + fusion   │ │ tracking │ │ + design      │
└──────┬─────┘ └─┬────────┘ └┬──────────────┘
       └─────────┼───────────┘
                 ▼
       Verified workflow report

Phases 2–4 are separately configured branches after the common QC gate. Optional typed bridges can turn calibrated subject/time measurements into Phase 3 observations or prespecified Phase 3 states into Phase 4 endpoints, but the workflow never invents either conversion.

The core schemas are assay-neutral. An observation identifies a subject, time point, modality, feature, value, unit, and optional uncertainty. Algorithms consume validated Study objects and return typed result objects rather than unstructured tables.

See the detailed Phase 2 architecture and research use cases and the external biology resource boundary.

Roadmap

• Phase 1 — aging-qc (baseline implemented): subject- and visit-level missingness, absolute and subject-relative visit windows, input ordering, range and unit checks, batch mean shifts, treatment/batch/site/plate/lot/timepoint confounding, replicate consistency, visit coverage, longitudinal retention, paired-analysis readiness, robust outliers, attrition-bias diagnostics, and covariance-aware multivariate and sequential change detection, leakage-safe control calibration, and randomized longitudinal treatment-effect inference.
• Phase 2 — aging-fusion (expanded baseline implemented): fuse commensurate clocks, omics, pathology, imaging, and clinical estimates while preserving uncertainty, covariance, missingness, calibration provenance, disagreement, evidence/modality influence, and genomic domain metadata. The current expansion also provides explicit cross-species ortholog mapping, an external genomic benchmark, and frozen external annotation, enrichment, network, variant, and sequencing-discovery artifacts that remain outside efficacy fusion until independently prespecified or calibrated.
• Phase 3 — aging-state (implemented baseline): typed continuous-time linear-Gaussian models, exact irregular-time filtering, RTS smoothing, partial-channel updates, held-out forecast validation, and innovation change-point detection.
• Phase 4 — full SDK (implemented alpha): explicit subject-endpoint bridges, factorial combination-therapy interaction analysis, uncertainty and multiplicity policies, cell and identifiability diagnostics, two-by-two design helpers, and a manifest-verified workflow that runs any configured Phase 1-to-4 subset behind the serialized QC gate.

Milestones and acceptance criteria live in docs/roadmap.md.

Quick start

Until the first version is published to PyPI, install from a source checkout and record the exact commit used for any research result:

git clone https://github.com/weston-wang/RejuvenationKit.git
cd RejuvenationKit
python -m venv .venv
source .venv/bin/activate
python -m pip install ".[visualization]"

After a version is available on PyPI, replace the last command with a version-pinned install such as python -m pip install "rejuvenationkit[visualization]==<version>".

For genome-scale matrices, target calibration, VCF/BCF, and optional sequence models:

python -m pip install "rejuvenationkit[genomics,hts]"
# For bounded-memory Parquet imports of large archived tables:
python -m pip install "rejuvenationkit[arrow]"
# Large model dependencies are deliberately separate:
python -m pip install "rejuvenationkit[genome-hf]"

Reproducible source-SHA installation and release steps are described in the publishing guide.

from datetime import datetime, timezone

from rejuvenationkit.schemas import Modality, Observation, Study, Subject

study = Study(
    study_id="demo",
    subjects=[Subject(subject_id="mouse-001", cohort="treated")],
    observations=[
        Observation(
            subject_id="mouse-001",
            timestamp=datetime.now(timezone.utc),
            modality=Modality.CLINICAL,
            feature="body_mass",
            value=31.2,
            unit="g",
        )
    ],
)

Run run_phase1_audit(...) with a QCConfig and output directory to create the JSON, CSV, Markdown, manifest, and visualization bundle. The Phase 1 workflow is documented in the study-audit guide; the integrated SDK workflow is documented in the four-phase workflow guide.

For development:

python -m pip install -e ".[dev,docs,genomics,hts,visualization]"
pre-commit install
pytest

See examples/minimal_study.py and examples/phase_1_qc.py, with sample data in examples/data/longitudinal_observations.csv. For a complete report bundle, call run_phase1_audit(...) or run examples/public_dog_phase1_audit.py. The audit writes its configuration, input fingerprint, QC findings, readiness tables, summary, and overview figure in one operation. Optional plans add held-out multivariate detection or randomized treatment inference without changing the underlying study.

The examples/rapamycin_phase_1_qc.py example demonstrates staggered dosing anchors and balanced treatment batches. The examples/public_gse131754_rapamycin.py workflow downloads a real public mouse RNA-seq dataset, converts it into typed study data, runs QC, and produces explicitly exploratory rapamycin-versus-control expression contrasts. The examples/public_dog_aging_project.py workflow downloads real longitudinal blood chemistry measurements from pet dogs, checks expected-visit missingness, and summarizes paired changes. It has no treatment assignment and is not a rapamycin-effectiveness analysis. The examples/public_dog_multimodal.py workflow combines aligned clinical chemistry and metabolomics, then applies held-out covariance-aware change detection across both modalities. Install .[public-data] to read the source R-data object and .[visualization] to export covariance, detection-score, whitening, and decomposition figures. The examples/gene_therapy_confounding.py workflow demonstrates how a superficially complete canine gene-therapy study can still be unusable because site, vector lot, and visit-specific plates overlap the biological contrasts. The examples/randomized_rapamycin_effect.py workflow demonstrates out-of-fold control calibration, covariance-aware randomization testing, and feature-level longitudinal effect intervals in a synthetic 60-dog trial. The examples/public_dog_sequential.py workflow learns reference dynamics over three Precision waves, reports onset and persistence of unusual held-out trajectories, and exports sequential evidence and modality plots. It is an observational monitoring demonstration, not a treatment-effect analysis. The examples/triad_like_rapamycin_sequential.py workflow generates a clearly labeled synthetic 580-dog, seven-visit trial shaped like the public TRIAD protocol. It demonstrates responder onset, persistence, transient effects, and modality-localized evidence; it contains no DAP treatment outcomes. The examples/canine_multimodal_fusion.py workflow demonstrates Phase 2 fusion under coherent evidence, a conflicting clinical response, and a missing proteomics assay. Its inputs are synthetic and do not imply measured canine efficacy. The examples/synthetic_canine_genomic_fusion.py workflow scores correlated canine transcriptomic signatures, propagates subject-level uncertainty, compares naive and covariance-aware inference, then balances genomic and clinical evidence hierarchically. A differently defined inflammatory safety signal stays outside the efficacy fusion. All values are synthetic. The examples/public_gse131754_genomic_fusion.py workflow downloads a real 43,629-gene mouse-liver rapamycin dataset and exercises joint genomic signature covariance, shrinkage, and pathway-specific estimands across age/sex/dose strata. It keeps the pathway vector intact instead of manufacturing one uncalibrated efficacy score. The panels are engineering fixtures, not validated biological-age clocks; see the public benchmark report. The examples/external_biology_context.py workflow imports archived GO- and STRING-shaped fixtures, runs explicit-background directionless overrepresentation and a separate directional ranked-set analysis, preserves interaction evidence channels, and demonstrates that database context remains not_fusible rather than becoming an efficacy estimate. The examples/phase3_longitudinal_state.py workflow uses irregular visits and partial channels to demonstrate filtering, smoothing, held-out forecast calibration, innovation change points, and model-conditional forecasts on synthetic data. The examples/phase4_factorial_combinations.py workflow analyzes a fully synthetic 72-dog rapamycin-by-senolytic factorial study with a declared endpoint, baseline adjustment, endpoint uncertainty, HC3 covariance, multiplicity control, and cell-level design diagnostics. Its interaction is a departure from additivity on the declared scale, not an automatic claim of synergy or efficacy. The examples/four_phase_workflow.py workflow runs a fully synthetic canine study through the serialized Phase 1 QC gate and explicit Phase 2, Phase 3, and Phase 4 inputs, publishes a checksummed manifest-last bundle, and verifies it on load. It is an integration demonstration, not evidence that the simulated interventions work.

Contribution workflow

1. Open an issue describing the scientific decision and expected validation.
2. Create a focused branch and add tests before or with the implementation.
3. Run ruff check ., ruff format --check ., mypy, and pytest.
4. Open a pull request using the template and document assumptions, validation data, and limits.

New algorithms should expose uncertainty, accept deterministic random seeds when applicable, and include a synthetic or public-data validation case. See CONTRIBUTING.md.

Scope boundaries

RejuvenationKit will not replace base calling, alignment, differential-expression software, clinical judgment, or regulatory validation. It is designed as a transparent decision layer over curated assay outputs. No therapy recommendations are produced.

License

Apache License 2.0. See LICENSE.

Citation

If RejuvenationKit contributes to research, cite the archived software release used in the analysis. Citation metadata are available in CITATION.cff; a DOI will be added after Zenodo archives the release.