# CFF–longevity: applied corrections and working methods

Documentation reviewed 24 October 2026. Prepared for Gilang Senja Kharisma.

## Start here: current status and files

Pass 4 is the latest measurement audit. This documentation review adds no source decisions, numerical corrections or eligibility approvals. Read this README for current methods and PASS4_PROGRESS.md for the latest source-check findings. Earlier pass notes are historical snapshots.

| Purpose | Current file | Meaning |
| --- | --- | --- |
| Measurement audit | `measurement_audit_pass4.csv` | 280 rows; 237 raw taxon/tree labels |
| Identity and longevity crosswalk | `crosswalk_pass2.csv` | 237 labels; use audited pass-2 identity/quality fields |
| Review queue | `candidate_source_check_queue_pass4.csv` | 117 measurements across 91 labels; not an approved sample |
| Latest pass summary | `audit_summary_pass4.json` | Four records revisited; no numeric replacements in pass 4 |
| Source decision history | `applied_decisions.csv`, `source_decisions_pass2.csv`, `source_decisions_pass3.csv`, `source_decisions_pass4.csv` | Pass-specific decisions; rows can recur across passes |
| Tree-check history | `tree_checks.csv`, `audit_summary.json` | Earlier derived checks; raw trees absent from this ZIP |
| Data gaps | `PLATYPUS_DATA_GAP.md`, `data_gap_register.csv`, `data_gap_register.json` | Separate register; not part of measurement counts |
| Documentation changes | `DOCUMENTATION_REVIEW.md` | Review scope, changes and validation limits |

There are **94 longevity-quality candidate labels**, recalculated from the bundled crosswalk, down from the historical 95 after domestic-cat reclassification. This is a different denominator from the 91 labels in the measurement review queue. Neither is the final analysis sample. All 280 measurement rows retain `final_analysis_eligible = not_finalized`.

In `audit_summary_pass2.json`, `quality_candidates_not_final = 95` is inherited pass-1 metadata; use `quality_candidates_after_domestic_cat_reclassification = 94` for the updated count. In the crosswalk, original name, longevity and quality fields remain historical; audited `*_pass2` fields take precedence. Its measurement-status summaries are pass-2 snapshots: consult the pass-4 measurement table for current screening decisions.

## Evidence limits of this package

This ZIP contains derived tables, decisions and scripts, not the raw CFF archive, raw AnAge snapshot, original crosswalk archive or raw trees. The documentation review checks internal consistency and incremental reproducibility; it does not independently reverify published sources, raw-input hashes or phylogenetic validity. Source links below preserve earlier audit provenance, not a claim of new source access on this review date.

## What has actually been completed

The earlier raw-input audit reports that the supplied October 2025 Haarlem CSV contains 280 measurements and 237 taxon labels. The supplied AnAge file contains 4,645 entries and is byte-identical to the input documented in the previous crosswalk audit. These source files were previously supplied, but are not bundled here; full regeneration requires access to them.

Four measurement decisions are implemented in `measurement_audit.csv` and propagated to `crosswalk_with_corrections.csv`:

1. Ficedula albicollis: compiled 138.2 Hz corrected to 128.1 Hz.
2. Ficedula hypoleuca: compiled 128.1 Hz corrected to 138.2 Hz.
   These are species means at peak temporal resolution, not the largest individual values (141 and 146 Hz). Primary source: Boström et al. (2016), Results, https://doi.org/10.1371/journal.pone.0151099 . Both means were measured at 1,500 cd/m². Retaining means avoids silently changing the measurement statistic.
3. Melanophila acuminata: the compiled 400 Hz value remains visible, but its endpoint is classified as nonvisual infrared pit-organ response and excluded from visual-CFF analyses. The source's abstract establishes sensory modality; the exact derivation of the compiled 400 is not verified from full text. No replacement visual value is invented. Source: Hammer et al. (2001), https://pubmed.ncbi.nlm.nih.gov/11282323/ . It had no AnAge match, so this exclusion does not reduce the previous 95 quality-rated overlap candidates.
4. Ovis aries, Ezra-Elia et al. (2014): the compiled 80 Hz is a lower bound; the source reports CFF >80 Hz. Retain 80 as the bound and exclude this row from models requiring an exact threshold. The separate 60 Hz row remains pending source verification, not automatically excluded or accepted. Source: https://pubmed.ncbi.nlm.nih.gov/25204753/ .

Raw source columns and original CFF values are retained. `CFF_corrected` is the numeric field for subsequent processing; it must be used together with endpoint status. A number in that field does not imply eligibility.

## AnAge provenance decision

Use the uploaded, hashed 4,645-entry snapshot as the fixed input. The official Build 15 release notes list 4,671 entries (3 July 2023): https://genomics.senescence.info/species/release.html . HAGR explains that downloaded stable-build data and online data may differ: https://www.genomics.senescence.info/download.html . This does not specifically identify the 26-entry discrepancy. Do not claim the file is corrupt, outdated, or an exact verified Build 15 release based solely on counts. Record its hash and user-provided provenance; the exact upstream revision remains unverified. This is a provenance qualification, not a demand for another user upload or a reason to stop all checking.

## Supplied phylogeny checked

The earlier tree audit, recorded in `tree_checks.csv` and `audit_summary.json`, reports that `Haarlem_et_al_tree.tre` contains 100 trees, each with 237 unique tips. Every compiled CFF label appears in every tree. All 95 previous quality-rated longevity candidates have label-level tree coverage. Across all trees there are no negative, zero or nonfinite non-root edge lengths. Each has 12 multifurcations. Root-to-tip spread is approximately 0.000005 in the file's branch units; this is consistent with rounding, rather than substantive non-ultrametricity.

The accompanying CFF_phylo_2025.Rmd describes a composite distribution built with an Open Tree of Life backbone and clade-specific sources. Do not describe it as a newly downloaded TimeTree database product. Label coverage was reported verified in that audit; source-species identity, dating assumptions and suitability for the final model still need assessment. Preserve multifurcations; do not randomly resolve them merely to force binary trees. Check covariance positive definiteness after pruning to the final sample.

## Working inclusion and analysis rules

These are proposed methodological decisions made after earlier exploratory work. They are not yet preregistered. Finalize after source checks, then register the remaining analyses with explicit disclosure of prior results.

### Measurement eligibility

- Study endpoint: association between visual temporal resolution and maximum recorded longevity. Neither is a direct measure of subjective time or intrinsic ageing rate.
- Primary measurement stratum: source-verified behavioural visual flicker-fusion thresholds in healthy, normally developed animals. Analyse source-verified retinal ERG thresholds separately as a secondary stratum. Central-neuron, single-cell, blood-flow and thermal-response endpoints must not be pooled with behavioural CFF merely because the compilation calls them electrophysiology.
- Extract population, age/developmental stage, sensory site, method, stimulus luminance, spectrum, modulation/contrast, adaptation, temperature and threshold criterion from each included study when reported. Missing means unknown, never zero. AnAge temperature is not CFF experimental temperature; ecological light category is not stimulus luminance.
- A maximum tested frequency with continuing response is a censored bound, not an exact CFF. Exclude bounds from the planned exact-response PGLS. Keep a separate inventory; any later censored model requires its own specified likelihood.
- Following the pass-3 clarification, the working estimand is a measured behavioural uniform-flicker threshold under documented test conditions, not automatically a species maximum. The earlier default of selecting peak thresholds is superseded. Retain luminance-series results, individual-peak means and protocol-specific maxima with their statistic and conditions identified. A consistent condition/statistic-selection rule remains to be specified before freezing the sample; no automatic highest-value fallback is approved.
- Within each species and measurement stratum, deduplicate shared experiments. Only after compatible endpoints, statistics and test conditions have been established, consider a geometric mean across independent eligible study-level estimates, with equal study weights when comparable uncertainty estimates are unavailable. This is a working summarization choice, not a claimed optimum. Report sensitivity to the maximum eligible study estimate and to restriction to directly reported species means. Never pick the highest value across incompatible methods.
- Missing luminance or temperature does not automatically make a published genuine threshold invalid. Flag it, assess method and clade imbalance, and compare with a subset having documented conditions. Do not pool unlike photometric units or fabricate conversions. If comparability remains poor, restrict scope and report descriptive results.

### Longevity and identity eligibility

- Require a documented same-organism match, positive maximum longevity, and AnAge quality acceptable/high for the primary analysis. Keep questionable values for a separately labelled sensitivity analysis. Exclude missing longevity; never impute it from a related species.
- Verify synonyms, spelling corrections and specimen suffixes. Keep the raw dataset/tree label, accepted biological name and AnAge identifier as separate fields. An exact text match does not settle domestic/wild or experimental-species conflicts.
- Withhold unresolved cat/wildcat, dog/wolf, lionfish species, neonatal pig and caste-mismatch records from the primary sample pending adequate source evidence. Pass 2 already records domestic-dog and domestic-cat candidate joins; this does not resolve experimental population or tree placement. Do not silently rename tree tips. The current quality-rated candidate count is 94.
- Retain wild/captive/unknown origin and ordinal longevity sample-size category for sensitivity analyses; these are not individual counts or precision weights. Maximum recorded longevity depends on observation effort and husbandry.

### Planned statistical approach, after the dataset is frozen

- Primary working model within the behavioural stratum: log10(CFF in Hz) as response, log10(maximum longevity in years) and log10(adult body mass in grams) as predictors, using phylogenetic generalized least squares with Pagel's lambda estimated by maximum likelihood. This direction defines the coefficient and must be stated consistently. It does not establish causation. Use a fixed documented mass-source hierarchy, preferably the same AnAge adult-mass field throughout; do not substitute the metabolic-assay body mass without explicit review.
- Fit an unadjusted longevity model on the same complete-case sample for comparison. Report exclusions due to missing mass. Do not build an over-parameterized model if the eligible sample is small or clade coverage is inadequate; report that the planned model is not supportable rather than choose a smaller model by its p-value.
- Run the same frozen sample and formula over all 100 supplied trees. Report tree-specific estimates and confidence intervals, the distribution of estimates and the range of interval endpoints. Quantiles across trees reflect tree sensitivity, not a replacement sampling-confidence interval. Do not average p-values or select the tree producing significance.
- Secondary ERG analysis follows the same rules and stays separately labelled. Any combined-method exploratory model must include method and explicitly discuss remaining confounding; a method indicator does not make distinct endpoints equivalent.
- Diagnostics: residual patterns, heteroscedasticity, collinearity, influential species, likelihood/convergence, lambda boundaries and pruned covariance validity. Sensitivities: humans omitted, influential species left out one at a time, sufficiently represented clades analysed separately, wild/captive origin, questionable AnAge records, measurement-condition completeness, study aggregation choice, and lambda fixed at 0/1.
- Report beta, 95% confidence interval, sample counts, clade/method coverage, uncertainty across trees and limitations. Avoid claims about a species experiencing more lifetime or about physical time.
- R packages ape and caper are suitable standard implementations; caper documents PGLS and likelihood-estimated lambda: https://search.r-project.org/CRAN/refmans/caper/html/pgls.html . These are scientific software packages, not ChatGPT plugins. No extra plugin is needed for the present audit. The earlier audit recorded Rscript as unavailable at that time; this is not a current environment check. This package contains no final PGLS results. Installation or an available equivalent environment must be checked before the modelling stage, with version logging and validation.

## Still pending, precisely

This package resolves the two Ficedula numeric assignments, the Melanophila modality exclusion and the 80 Hz sheep bound. It does not claim all 280 measurements have been verified. Other priority records and the remaining candidate sources require primary-source extraction. The current 94 quality-rated candidates are not a final analysis sample. Human review remains pending; it is not replaced by this computational audit. Preregistration, final models, manuscript changes and public release updates are deferred as requested.

## Reproduce and inspect

Python 3 standard library is sufficient for these audit scripts. Run from the extracted package directory, preferably in a disposable copy: scripts overwrite their generated outputs.

**Self-contained pass-4 regeneration:**

```bash
python continue_audit_pass4.py .
```

This reads the bundled pass-3 table and regenerates four pass-4 CSV/JSON files. It does not regenerate documentation, the gap register or checksums. During the documentation review, all four outputs matched the bundled files byte-for-byte in a temporary directory.

**Full measurement pipeline, with external inputs available:**

```bash
python apply_audit.py INPUT_DIRECTORY OUTPUT_DIRECTORY
python continue_audit.py INPUT_DIRECTORY OUTPUT_DIRECTORY
python continue_audit_pass3.py INPUT_DIRECTORY OUTPUT_DIRECTORY
python continue_audit_pass4.py OUTPUT_DIRECTORY
```

INPUT_DIRECTORY must contain `anage_data.txt`, `30556475.zip` and `AnAge_Haarlem_2026_Final_Crosswalk_Audit_2026-10-23.zip`. Preserve their internal layouts. Pass 1 reads `Supplementary files/Haarlem_et_al_cff_dataset_21_10_2025.csv` from the first archive and `237_taxa_anage_crosswalk.csv` from the crosswalk archive. The raw tabular input hashes are asserted by the script. Pass 3 retains the two-argument interface but reads the existing output directory. The full pipeline was not rerun during this documentation-only review because its external inputs are absent from this package.

Assertions and deterministic output checks test implementation consistency, not scientific truth or independent human review. `SHA256SUMS.txt` covers the packaged files except itself; regenerate it after intentional changes. Original third-party rights remain unchanged.