Reproducible Codebase for: Structure-based geroprotector classifiers systematically under-rank endpoint-positive compounds with higher quantitative estimates of drug-likeness: a benchmarking and explainability analysis

Abstract

This codebase contains the analysis code, locked protocol configurations, data schemas, integrity checks, and automated tests used for the study: Structure-based geroprotector classifiers systematically under-rank endpoint-positive compounds with higher quantitative estimates of drug-likeness: a benchmarking and explainability analysis The study evaluates structure-based geroprotector classifiers across several validation settings. It compares conventional machine-learning algorithms, molecular-similarity models, neural tabular models, tabular foundation models, and equal-weight score ensembles. The analyses examine model performance, sensitivity to validation design, chemical familiarity, calibration, component complementarity, feature attribution, and the relationship between model scores and quantitative estimates of drug-likeness (QED). The archive supports analyses on: · The released Geroprotectors.org/ChEMBL benchmark from Santiago-de-la-Cruz et al. · Repeated random cross-validation. · Scaffold-grouped and similarity-component-grouped validation. · Retrospective DrugAge and AgeXtend stress tests. · Endpoint-aligned retraining on DrugAge, AgeXtend, and the Kapsiani-Howlin benchmark. · Model ablation and component-combination experiments. · Calibration, applicability-domain, QED, attribution, and error-ranking analyses. The software does not designate one classifier as a universal best model. Its purpose is to examine how model-family rankings and screening behavior change across validation regimes and operational definitions of geroprotection. Archive contents The ZIP archive contains the following directories and files: · src/geroprotector/: data curation, molecular representation, model training, validation, ensemble analysis, explainability, and reporting code. · configs/: locked data, model, validation, external-cohort, and analysis protocols. · scripts/: command-line runners, environment checks, integrity checks, and workflow entry points. · schemas/: JSON schemas for predictions, metrics, assay observations, run manifests, and permitted claims. · tests/: unit, contract, leakage, configuration, and integration tests. · README.md: package overview and initial setup. · REPRODUCING.md: recommended execution order and example commands. · DATA_AND_MODEL_ACCESS.md: required datasets, model checkpoints, hashes, and local staging conventions. · LEAKAGE_CONTRACT.md: data-separation and model-selection safeguards. · THIRD_PARTY_NOTICES.md: third-party software and data-use boundaries. · REFERENCES.md: publications and implementation sources used to define the workflows. · MANIFEST_SHA256.txt: SHA-256 checksum inventory for the distributed source files. · CONTENTS.txt: deterministic package-content inventory. · CITATION.cff: software citation metadata. · LICENSE: BSD 3-Clause License covering original project code and documentation. The archive does not contain raw datasets, fitted models, model checkpoints, prediction tables, manuscript figures, or numerical result artifacts. Archive identity File: NgocThacPham_geroprotector_prediction_code_v1.0.0.zip SHA-256: a4b29fc7b0d4d747325fdafbf3a0acae3143acf7d7bcd817f53651480ec9c518 Users should verify the archive checksum before installation. Software requirements The locked software environment targets Python 3.12. Core dependencies include: · NumPy 2.0.2 · pandas 2.3.2 · SciPy 1.16.1 · scikit-learn 1.7.1 · RDKit 2025.3.6 · XGBoost 3.3.0 · PyArrow 21.0.0 · PyYAML 6.0.2 · joblib 1.5.2 · jsonschema 4.25.1 Optional traditional-model dependencies include: · CatBoost 1.2.10 · LightGBM 4.6.0 Optional foundation-model dependencies include: · PyTorch 2.6.0 · TabPFN 8.1.0 · TabICL 2.1.1 Some experiments also require separately obtained TabFM source code and model weights. Foundation-model checkpoints, third-party implementations, and provider-specific licenses are not redistributed. A CUDA-compatible GPU is required for the foundation-model and some neural-model experiments. The conventional machine-learning, curation, validation, and reporting workflows can be run on CPU. Installation Unpack the archive and create a Python 3.12 virtual environment: unzip NgocThacPham_geroprotector_prediction_code_v1.0.0.zipcd geroprotector_prediction-1.0.0python3.12 -m venv .venvsource .venv/bin/activatepython -m pip install --upgrade pippython -m pip install -e '.[traditional,test]' Install the optional foundation-model environment when needed: python -m pip install -e '.[v6]' Verify the source-package manifest: python scripts/freeze_package_manifest.py --check Run the automated test suite: pytest -q The validated package produced: 191 passed, 4 skipped The skipped tests require optional DrugAge, AgeXtend, or Kapsiani-Howlin source files that are not included in the archive. Required data Geroprotectors.org/ChEMBL benchmark The primary benchmark was introduced by Santiago-de-la-Cruz et al.: DOI: 10.1186/s13321-025-01058-5Pinned source revision:c8f458925f5ea2beeba87c7c2dda62eefacf618c Three source files are required: 0.Data/Geroprotectors_Clean_Descriptors_2024.csv0.Data/No_geroprotectors_and_Toxicos.csv5.Chemical space/Geroprotectors by ML.csv Their roles are: · 206 reported geroprotectors. · 199 ChEMBL reference compounds. · 1,488 previously predicted candidates retained as unlabeled compounds. The 1,488 predicted candidates must not be converted into positive labels or used as supervised training targets. Expected hashes, row counts, delimiters, encodings, and column names are declared in configs/data.yaml. The preparation workflow stops if an input differs from its declared contract. DrugAge DrugAge Build 5 must be obtained from: https://genomics.senescence.info/drugs/ Stage the files under: external_data/drugage_build5/ Alternatively, set: export DRUGAGE_SOURCE_DIR=/absolute/path/to/drugage_build5 The primary endpoint-aligned DrugAge analysis uses Caenorhabditis elegans observations. Label construction and alternative endpoint variants are specified in: configs/drugage_celegans_benchmark_protocol.yaml The negative class means that no significant lifespan extension was recorded under the active rule. It is not a class of experimentally certified non-geroprotectors. AgeXtend AgeXtend materials are associated with: Article DOI: 10.1038/s43587-024-00763-4Training archive DOI: 10.5281/zenodo.10034994 Stage the required workbooks under: external_data/agextend_2024/ Alternatively, set: export AGEXTEND_SOURCE_DIR=/absolute/path/to/agextend_2024 The required filenames and hashes are declared in: configs/agextend_endpoint_benchmark_protocol.yamlconfigs/agextend_official_reference_protocol.yaml Kapsiani-Howlin benchmark The historical endpoint reconstruction uses the official supplementary workbook associated with: DOI: 10.1038/s41598-021-93070-6 The expected source path and SHA-256 checksum are recorded in: configs/kapsiani_historical_benchmark_protocol.yaml Exact reproduction of the historical fitted random forest is not possible from the released materials because the original split membership, fold identities, full MOE descriptor matrix, software state, and fitted model artifact were not released. The included workflow therefore performs a documented protocol reconstruction and does not present it as an exact historical refit. Stage 0: curation and split registry Define the Python interpreter: export GERO_PYTHON="${GERO_PYTHON:-python3}" Run Stage 0 with the three Geroprotectors.org/ChEMBL source files: bash scripts/prepare_stage0.sh \ "/absolute/path/to/Geroprotectors-Project-INGER/5.Chemical space/Geroprotectors by ML.csv" \ "/absolute/path/to/Geroprotectors-Project-INGER/0.Data/Geroprotectors_Clean_Descriptors_2024.csv" \ "/absolute/path/to/Geroprotectors-Project-INGER/0.Data/No_geroprotectors_and_Toxicos.csv" Stage 0 performs: · Input identity and checksum verification. · Structure standardization. · Parent-structure and connectivity identity resolution. · Duplicate and label-conflict handling. · Shared split-registry construction. · Chemical-similarity grouping. · Leakage tests. · Separation of labeled compounds from the 1,488 unlabeled candidates. Model training should not proceed if any Stage 0 check fails. Reproducing the released 405-compound benchmark Set the positive and reference-compound paths: export GERO_POSITIVE="/absolute/path/to/Geroprotectors_Clean_Descriptors_2024.csv"export GERO_NEGATIVE="/absolute/path/to/No_geroprotectors_and_Toxicos.csv" Run the conventional machine-learning baselines: bash scripts/run_traditional_paper405.sh \ traditional405_reproduction \ "$GERO_POSITIVE" \ "$GERO_NEGATIVE" Run the component and equal-weight ensemble comparison: bash scripts/run_fixed_blend_paper405.sh \ fixedblend405_reproduction \ "$GERO_POSITIVE" \ "$GERO_NEGATIVE" These workflows preserve the source study's released 80/20 assignment: Training set: 324 compoundsHeld-out test set: 81 compoundsRandom seed: 42Stratification: none Threshold-dependent comparisons use the protocol-defined cutoff. Ranking metrics are calculated from continuous model scores. Robustness and insight analyses After the required data, third-party implementations, and checkpoints have been staged, run the complete insight suite with: bash scripts/run_insight_suite.sh \ --stamp reproduction \ --resume The suite runs sequentially because several stages share GPU resources. It includes: · Model-wide QED analyses. · Repeated five-fold cross-validation. · Validation-rank stability analysis. · Scaffold-group