HCC senescence construct audit

Corrected reproducibility release for:

Directional responsiveness and specificity limits of transcriptomic senescence models in hepatocellular carcinoma

This archive accompanies PRJ-2026-008. It evaluates transcriptomic senescence models across 10 public Gene Expression Omnibus (GEO) data sets and 92 unique biological samples. The evidence supports descriptive directional concordance in senescence-labeled perturbations, partial tiered discrimination, and limited internal directional transport. It does not establish HCC senescence specificity, irreversibility, external validation, prognostic or predictive utility, or clinical applicability.

One-command reproduction

For the complete public-accession-to-score reconstruction, install the single upstream parser dependency and run:

python -m pip install -r requirements-upstream.txt
python run_reproduction.py --from-geo

The full command downloads or verifies 15 fixed public files for all 10 GEO accessions, checks their byte counts and SHA-256 values, rebuilds the frozen expression representations and scores, and reproduces:

• all 60 phase-v1.2 native-score rows;
• all 100 phase-v1.3 native-score rows;
• all 828 phase-v2 sample-module rows, including 12 frozen non-estimable rows;
• all 11 phase-v1.2 native-score effects, exact permutation tests, Hedges' g, and Holm adjustments;
• all 25 phase-v1.3 effects, including the 13-test exact-permutation/Holm family;
• all sample probabilities from the deposited fold coefficients and preprocessing parameters;
• the 19 internal-transport contrasts, 11 adversarial contrasts, five IMR90-versus-quiescence contrasts, and the locked v2 decision.

Outputs are written to reproduced/. A successful clean-directory execution produces reproduction_summary.json, OUTPUT_HASHES.tsv, and clean_run_log.json.

OUTPUT_HASHES.tsv is the fixed bitwise registry for the six substantive numeric outputs only: the v1.2 and v1.3 effect tables, the three v2 contrast tables, and the final-sample probability table. reproduction_summary.json and clean_run_log.json are deliberately excluded from that fixed registry because they record run timestamps and elapsed time. Their scientific checks must agree across runs, but their complete-file SHA-256 values are run-specific.

The faster derived-data-only verification remains available and uses only the Python standard library:

python run_reproduction.py

Reproducibility boundary

This corrected release supports an independently executable GEO-accession-to-expression-to-score-to-reported-statistics-and-decisions reconstruction from author-deposited processed GEO files. It does not download FASTQ, BAM, or SRA data, and it does not refit or retune the stopped developmental model.

The distinction is deliberate:

1. results/ is the aggregate audit trail from the frozen project execution;
2. source_data/ contains the sample-level values and fitted parameters underlying the reported statistics, thresholds, and decisions;
3. run_accession_to_score.py reconstructs frozen scores from the fixed public GEO inputs and compares every estimable score with the deposited values;
4. run_reproduction.py --from-geo chains that upstream verification to the independent reconstruction of the published statistics and decision logic.

The original project-relative executors remain in code/ as provenance. They are not used as the portable entry point. The portable route contains frozen, hash-verified hUSI weights, the dated HGNC mapping snapshot, and the exact project-used gene-set definitions with source attribution.

Archive contents

• config/: all redistributable phase manifests, labels, contrasts, modules, splits, and execution contracts, including the three manifests missing from release v1.0.1.
• source_data/: sample-level native scores, module values, centered module values, final probabilities, fold coefficients, preprocessing parameters, and a SHA-256 manifest.
• results/: frozen aggregate phase outputs and integrated evidence ledgers.
• code/: original versioned analysis and figure scripts retained for provenance.
• figure_data/: data underlying the contracted figures.
• figures/: revised vector and production-size figure assets.
• protocols/: dated internal phase records and implementation amendments.
• run_reproduction.py: package-local clean-run entry point.
• run_accession_to_score.py: public GEO processed-file acquisition, preprocessing, scoring, and score-level verification.
• upstream_resources/: frozen HGNC snapshot, hUSI weights and license, and exact gene-set definitions used by the project.
• clean_run_evidence/: log, expected-output hashes, and numerical verification summary from fresh directories containing no pre-existing reproduced outputs, including a two-run 6/6 fixed-output hash comparison.
• VERSION_MAP.md: manuscript/archive/phase version map and chronology.

Public data

The source studies are available at:

• https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE261099
• https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE288534
• https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE153123
• https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE162175
• https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE17546
• https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE61110
• https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE47739
• https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE260862
• https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE29084
• https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE279929

Raw and author-processed expression matrices and externally authored model resources remain subject to their original repositories and terms. The deposited sample-level tables are project-derived source data and contain no private or controlled-access patient information.

Environment and random numbers

The derived-data-only reproduction uses Python 3.12 and the standard library only. The full GEO route additionally uses xlrd==2.0.2 to read the author-deposited GSE260862 .xls file. environment-lock.json records the tested environment. No stochastic algorithm is used, so a random seed is not applicable. The original v2 model fit used Python 3.12.10, NumPy 2.5.1, SciPy 1.16.3, and constrained L-BFGS-B; those fit parameters are deposited and are reconstructed, not re-estimated, by the clean-run command.

Internal freezing and chronology

The dated protocols were internally frozen before their corresponding project analyses. They were not prospectively registered in an external registry. Internal hashes document file integrity but are not presented as proof of external preregistration. See VERSION_MAP.md.

License

Original code is released under the MIT License. Public source data, external model resources, article text, and third-party gene sets remain subject to their original licenses and terms.

Release status

GitHub release v1.1.0 fixes the code, public-input manifests, derived source data, figures, and clean-run evidence at commit 5bbe6a207ed01a230a1c86adbddd4de6dd277361. The immutable Zenodo version DOI is 10.5281/zenodo.21707461; the concept DOI is 10.5281/zenodo.21683045.

The audited standalone GitHub release asset has SHA-256 8cce9c2ffda0cf4203a7239d6f6e75f51647ea087f5d014a320594a4fa57eecf. The Zenodo-generated source archive has SHA-256 872b091b34e781ae2346a7749574e3ae980df1f0c81a092b1287d91755551ae1 and Zenodo-recorded MD5 9d146c9805396ac85458b5fa14c622be.