SPVA-Ag

SPVA-Ag is a support- and leakage-aware GeoAI workflow for reconstructing partially observed ocean chromophoric dissolved organic matter (CDOM) absorption spectra from multisource Earth observations.

The method-paper implementation predicts 226 channels of log(a_g(lambda)) from 275 to 500 nm. Its main contribution is not a claim that one neural architecture is universally superior. It is the integration of four auditable contracts:

1. Target support separates native observations, training-only interpolation, and unsupported target cells.
2. Evidence dependence assigns exact spectra, overlap components, and associated sample groups before statistical roles.
3. Evaluation uses native-only, support-dependent estimands under frozen governance.
4. Serving preserves primary-supported, serving-only, unsupported-ocean, land, and below-bottom states.

Release status

This repository is a code-and-method release candidate for the SPVA-Ag method paper. It contains source code, the ordered 56-predictor model contract, synthetic contract benchmark, public HMAC test vectors, tests, aggregate tables, and reproducibility documentation.

It does not contain:

• private or third-party observations;
• row-level evaluation targets or predictions;
• model checkpoints or normalization arrays;
• global NetCDF products;
• credentials, production HMAC keys, or private paths.

The global fields discussed in the manuscript are an auditable execution demonstration, not an independently validated global CDOM product or climate record.

Quick start

Create a Python 3.12 environment and install the package:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-lock.txt
python -m pip install -e . --no-deps

On Windows PowerShell, activate with:

.\.venv\Scripts\Activate.ps1

Run the controlled synthetic benchmark:

python scripts/run_spva_ag_synthetic_contract_benchmark_r1.py \
  --config configs/spva_ag_synthetic_contract_benchmark_r1.yaml \
  --output-root outputs/synthetic_contract_benchmark

The output directory is intentionally no-overwrite. Choose a new path for a second run.

requirements-lock.txt records the environment used for the public mechanism benchmark. In that environment, the replicate CSV, summary CSV, and 600 dpi PNG reproduce the released files byte for byte. PDF rendering is visually identical; its raw hash changes because Matplotlib writes the creation time into PDF metadata.

Run the public checks:

python scripts/validate_no_data_tracked.py
python scripts/validate_text_hygiene.py
python scripts/validate_release_manifest.py
python -m pytest -q

Reproducible public evidence

• release_evidence/synthetic_contract_benchmark/ contains the 30-replicate controlled benchmark, including replicate-level and summary source data.
• docs/SPVA_AG_PUBLIC_HMAC_FINGERPRINT_SPEC_R1.md defines canonicalization, a synthetic key, three test vectors, and the expected component partition.
• configs/spva_ag_method_paper_main_model_r1.yaml freezes the exact ordered 48 dynamic and eight static predictors, output wavelengths, ensemble member identities, and artifact hashes without distributing model artifacts.
• release_evidence/aggregate_tables/ contains manuscript aggregate tables only; no row-level protected observations are included.

Repository layout

configs/           Public benchmark and frozen model contracts
data_registry/     Feature definitions, preprocessing, and wavelengths
docs/              Public specifications and release boundary
release_evidence/  Synthetic source data and aggregate manuscript tables
scripts/           Reproduction and release-validation commands
src/spva_ag/       SPVA-Ag implementation
tests/             Public mechanism, HMAC, and release tests

Data and model availability

The software and synthetic benchmark are released under the MIT License. Underlying observations retain their original provider terms and are not redistributed here. Model weights and the global three-dimensional output are withheld pending separate rights, product, and release review. See docs/RELEASE_BOUNDARY.md.

Citation

The manuscript citation and archival DOI will be added after acceptance and Zenodo deposition. Until then, use the metadata in CITATION.cff and cite the exact software release used.