ASPT-Gate Software v1.1.1

Reusable research software for the Analytical-System Provenance Transportability Gate (ASPT-Gate).

The package asks a deliberately narrow question: whether a declared provenance/reference relation has enough independent analytical evidence to be transported from one measurement system to another under prospectively declared rules.

New user: if you installed from PyPI, first run aspt-gate resources --copy ./aspt_gate_resources and open aspt_gate_resources/START_HERE.md. If you downloaded the release bundle, open START_HERE.md directly.

Executable scope

The end-to-end executable route in this release is deliberately bounded to BP — paired physical specimens with a supervised classification endpoint and balanced accuracy. It implements:

1. manifest-backed evidence/provenance checks;
2. additive class + analytical-system structural estimability screening;
3. deterministic stratified TRAIN/AUDIT/TEST split generation;
4. held-out bridge adequacy with 90% equivalence/TOST intervals and the final two-sided 95% interval convention for hard directional guards;
5. training-only sparse coordinate-wise slope-fixed shifts when the correction branch is eligible;
6. three-state physical-specimen bootstrap support (DEMONSTRATED_PASS, DEMONSTRATED_FAIL, UNDERPOWERED);
7. the five-score system-swap transport diagnostic using L2 logistic regression and balanced accuracy;
8. reason-coded terminal states, a machine-readable diagnostic profile, and a route-specific repair for every refusal.

This release does not claim operating validation for arbitrary regression, ranking, unsupervised endpoints, or arbitrary evidence modes. BS1 and BT are methodological evidence categories in the associated method framework but are not end-to-end executable routes here.

Install

From PyPI (after production publication):

python -m venv .venv
# Linux/macOS: source .venv/bin/activate
# Windows PowerShell: .\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install aspt-gate==1.1.1
aspt-gate resources --copy ./aspt_gate_resources

Then open aspt_gate_resources/START_HERE.md.

From the extracted release bundle:

python -m venv .venv
# Linux/macOS: source .venv/bin/activate
# Windows PowerShell: .\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install dist/aspt_gate-1.1.1-py3-none-any.whl

Then:

aspt-gate --help
aspt-gate explain BRIDGE_EVIDENCE_UNRESOLVED

The wheel declares the runtime dependencies. requirements-exact-tested.txt records the exact environment used for release QA and is optional for ordinary use.

Confirmatory workflow

aspt-gate make-template --out my_study.json
aspt-gate validate --config my_study.json --data my_data.csv
aspt-gate freeze --config my_study.json --data my_data.csv --out STUDY_LOCK.json
aspt-gate run --lock STUDY_LOCK.json --out results_locked

freeze hashes the declared configuration, paired data, and declared evidence objects. run --lock refuses execution if the locked data or evidence bytes have changed. Direct run --config ... --data ... remains available for exploration but is stamped prospective_lock_verified=false.

Important statistical semantics

• Equivalence/TOST guards at alpha=0.05 use two-sided 90% intervals.
• Hard directional guards at alpha=0.05 use a two-sided 95% t interval: PASS when the interval lies wholly in the required direction, FAIL when wholly in the opposite direction, UNDERPOWERED otherwise.
• Bootstrap resampling is at the physical-specimen level. Repeated bootstrap draws are integer frequency weights, not new independent specimens.
• The manuscript-associated population rule is PASS if q0.025(L) > 0.80, FAIL if q0.975(U) < 0.80, and UNDERPOWERED otherwise. Equality is non-decisive.

These numerical settings reproduce the manuscript-associated architecture. They are not universal scientific constants. A new study must prospectively justify its coordinate scope, transform, equivalence margin, thresholds, evidence route, and endpoint.

Input shape

One comma-delimited CSV row per physical specimen:

specimen_id,class_label,A_Fe,B_Fe,A_Rb,B_Rb,A_Zr,B_Zr
SH_001,SourceA,18442,18901,141,138,281,289

A_ is the canonical/reference system and B_ the candidate system. Prefixes and coordinate names are configurable.

For scale.transform="ln", every admitted A/B value must be finite and strictly positive. The current release does not implement censored-value imputation; 0, -1, blanks, or text sentinels for non-detects must not be silently converted into invented concentrations.

Supplied examples

A fast synthetic example uses 20 splits and 200 bootstrap replicates:

aspt-gate run --config examples/config_quick.json --data examples/paired_example.csv --out out_pass

A deliberately imprecise candidate-system example demonstrates abstention:

aspt-gate run --config examples/config_refusal_imprecise.json --data examples/paired_example_imprecise.csv --out out_refusal

The publication-style template uses 100 splits and 10,000 bootstrap replicates.

Main outputs

Depending on how far the route proceeds, the result directory contains:

• diagnostic_profile.json
• run_receipt.json
• split_universe.json
• unit_weight_split_states.csv
• population_summary.json
• population_bootstrap_sufficient_trace.npz
• transport_split_scores.csv when transport is licensed/evaluable
• RUN_MANIFEST.sha256

Interpretation firewall

• ADMISSIBLE licenses only the declared analytical transport operation; it is not archaeological provenance truth.
• STOP_B is demonstrated failure of the declared bridge-support criterion; it is not a claim of general instrument incompatibility.
• BRIDGE_EVIDENCE_UNRESOLVED is an abstention, not a negative result.
• NOT_EVALUABLE says the required evidence was unavailable, circular, or otherwise not evaluable; it is not a negative compatibility result.

See docs/INTERPRETATION_FIREWALL.md.

Release integrity

Before use, run:

python verify_release.py

For developer/reviewer QA, after installing the exact test environment:

python -m pytest -q

What changed in v1.1.1

v1.1.1 is a distribution-only independent-use repair. The scientific computation modules and decision semantics are unchanged from v1.1.0. The wheel now bundles the user guide, examples, evidence templates, and interpretation documentation, and the aspt-gate resources --copy ... command exposes them after a normal pip install.

What changed in v1.1.0

v1.1.0 is a usability and independent-use release. The scientific core and decision semantics remain those of the frozen architecture; the release adds human-readable repair guidance, aspt-gate explain, friendlier CLI errors, runnable refusal examples, evidence templates, and the independent-user documentation in this bundle.

The final Zenodo packaging repair also removes cache artefacts, removes unpublished DOI placeholders from live package metadata, and keeps empirical source-study relations out of the generic software record. See RELEASE_REPORT_v1.1.1.md.

Citation and metadata

Use CITATION.cff. Real Zenodo/article identifiers should be added only after they exist. RELATED_IDENTIFIERS_TEMPLATE.json documents the intended future reciprocal links; placeholders in that template are examples only and are not live metadata.

License

BSD-3-Clause for this software package. This license does not apply to third-party datasets or publications analyzed with the software.