Metadata-Version: 2.4
Name: aspt-gate
Version: 1.1.1
Summary: Analytical-System Provenance Transportability Gate: decide whether a provenance relation may be transported between two analytical systems
Author: F. M. Al-Otaibi, Ion Andronache, Ioannis Liritzis
License-Expression: BSD-3-Clause
Keywords: archaeometry,provenance,calibration transfer,transportability,reproducibility,prospective analysis,research data reuse
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0
Requires-Dist: scipy>=1.12
Requires-Dist: pandas>=2.0
Requires-Dist: scikit-learn>=1.5
Dynamic: license-file

# 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`](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):

```bash
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:

```bash
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:

```bash
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

```bash
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:

```text
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:

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

A deliberately imprecise candidate-system example demonstrates abstention:

```bash
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`](docs/INTERPRETATION_FIREWALL.md).

## Release integrity

Before use, run:

```bash
python verify_release.py
```

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

```bash
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.
