About ERVAtlas

# webtool_reference — Data Dictionary

Generated from the REAL data line only (see ../../HONEST_NUMBERS.md, ../../CLAUDE.md).
Do not add anything from the synthetic/archived files into this directory.

## erv_family_age_association.csv
Source: `meta/meta_ERVfam_age_spearman.csv` (n=84 donors, 90 cell_type x ERV_family tests).
Columns: cell_type, ERV_family, n_donor, spearman_age, p, p_fdr, significant_fdr10 (added here).
**Honesty note**: 0/90 tests pass FDR<0.10. Most associations are weak
and not individually significant after correction — report as an atlas/resource,
not as a validated aging-biology discovery. Do not describe any single row as
"the ERV aging clock."

## cmv_association_top_features.csv
Source: `cmv_erv_top10_paper_table.csv`. CMV-serostatus-stratified ERV expression
by cell subtype, top-ranked by effect size. This table is where the real,
independently-strong signal lives (CMV x inflammaging r=0.53, p=4e-9, per
PILOT_REPORT_blood_ERV_ISG.md) — CMV status, not raw chronological age, is the
stronger organizing variable in this dataset.

## immune_subtype_age_association.csv
Source: `A0_immune_subtype_age.csv`, n=24 rows, pilot-scale (n=14 donors underlying).
Underpowered sanity screen only — do not present as a standalone result.

## pseudobulk_reference_matrix.parquet
Source: `meta/meta_donor_celltype_ERVfam.csv`. 756 rows (donor x cell_type
pseudobulk), ~442 TE/ERV subfamily+locus features + age column.
This is the reference cohort the web tool's "upload and compare" feature will
compute percentiles/z-scores against. Built from n=84 donors across the
Terekhova et al. Immunity 2023 blood atlas (14 batches, subsample "-1" only —
see CLAUDE.md 2026-06-16 entry for batch structure). **Before public hosting,
confirm Synapse syn49637038 data-use terms permit redistributing this level of
aggregation (pseudobulk summary, not per-cell/raw) — tracked as a separate task.**

## inflammaging_modules.json
Source: `inflammaging_summary.json`. Curated immune gene sets (Type I/II IFN,
NFkB inflammation, cytotoxic) used for module scoring, plus source cohort size
(n_cells, n_donors, n_subtypes). Reused as-is for the tool's module-score display.

## What this package deliberately does NOT include
- No synthetic/ground-truth-age results (ERV_Research_Proposal_ARCHIVE / README_ARCHIVE).
- No claim of a working "ERV aging clock" — real multi-tissue GTEx clock performance
  (MAE~9.2y, R^2~0.155, barely above the guess-the-mean baseline) is documented in
  HONEST_NUMBERS.md and is NOT part of this web-tool reference package.
- No per-cell raw matrices (stay on EVO; h5ad files are 80-150MB each, ~7.4GB total).

---

## UPDATE 2026-07-29 — erv_family_age_association.csv superseded by hardened version

The original version of this table (raw Spearman, mislabeled Bonferroni as
"p_fdr") has been replaced by output from `scripts/50_hardened_family_age_meta.py`,
which applies the SAME confound-control method validated in
`scripts/46_gdt_composition_decouple.py` for the gammaDelta-T HERVK signal
(partial Spearman controlling for per-donor-per-cell-type sequencing depth
and cell count) to all 90 cell_type x ERV_family pairs, plus a correctly
computed Benjamini-Hochberg FDR (both on the raw and on the confound-controlled
p-values).

**Result: still 0/90 pass BH-FDR<0.10, before or after confound control.**
2 pairs (incl. gd T cells x HERVK, reproducing the known collapsing signal
from HONEST_NUMBERS.md via an independent feature-engineering path — family-
level sum here vs the z-scored HERVK-int+LTR5 panel there, so exact rho
differs but the qualitative "collapses after confound control" verdict
matches) are explicitly flagged `collapses_after_confound_control`: raw
p<0.05, partial p>=0.05.

**Conclusion for the manuscript/tool**: no individual cell-type x ERV-family
age association in this atlas survives both multiple-testing correction and
depth/cell-count confound control. This table should be presented as an
honest negative/resource screen (with per-row raw vs partial numbers and
verdict visible to the user), not mined for a "significant" row to headline.
The real citable positive finding in this dataset remains CMV serostatus x
inflammaging (see cmv_association_top_features.csv).


---

## UPDATE 2026-07-29 — Synapse syn49637038 data-use check (task closed)

Checked programmatically via `synapseclient` (read-only): the Synapse entity
`syn49637038` ("SINGLE-CELL ATLAS OF HUMAN BLOOD DURING HEALTHY AGING",
Terekhova et al. *Immunity* 2023) has **zero formal accessRequirements**
attached (`GET /entity/syn49637038/accessRequirement` -> 0 results) — i.e. no
DUA, no controlled-access gate beyond a standard Synapse account, consistent
with CLAUDE.md's earlier note that this is not a formal Data Access Request
and has a low barrier to entry. The source publication itself is CC BY-NC
(noncommercial, attribution required).

**Conclusion**: redistributing DERIVED/AGGREGATE summary statistics (this
webtool_reference/ package: pseudobulk means, association tables) through a
free, noncommercial NAR web tool with proper citation to Terekhova et al.
2023 is consistent with both the license and the absence of any formal access
restriction. This is a read-only automated check, not a legal opinion — worth
a final human skim of the paper's Data Availability statement before the tool
goes public, but no blocker found.

**Do NOT** redistribute the raw per-cell h5ad files or fastq/BAM this way —
only the aggregated tables in this directory are cleared for public hosting.