# MapleOmics current public catalog snapshot

This is a snapshot of the current public catalog and selected API metadata, **not a validation of all data provenance or a frozen submission-ready scientific release**. It contains no genomes, raw reads, private records, or expression measurements. Capture timestamps and source-response SHA256 values are recorded in `inputs/sources.json` and `inputs/registry_evidence.json`. Different URLs were retrieved separately; this is not an atomic database export.

## Scope and units

- The nuclear catalog has **16 entries: 13 Acer + 2 Dipteronia + 1 Citrus outgroup**. Thus 15 focal maple-family resources and 13 Acer species have different denominators. Restricted and metadata-only entries count as catalog records; their presence does not imply a released assembly download.
- Capability booleans reproduce the catalog declarations. Orthology has 14 true entries; synteny has 13. These counts include the scope shown in each row. PPI `listed/not_listed` follows the public Data page and is not a fresh API execution test.
- The sample catalog has 204 records: 70 general-expression samples and 134 resequencing records. Seven tissues are metadata categories. The expression-only sample species Asac is not a nuclear catalog entry; do not add it to the genome count. Developmental-stage counts cover only returned labels.
- The separate 70-individual GWAS analysis cohort and the Oil, Leaf Color, seasonal epigenome and RNA/Ribo/proteome datasets are not extra rows in this general sample catalog. Do not sum those scopes together.
- Catalog protein-coding counts refer to source annotation models. The homepage gene field is described publicly as primary annotated gene records. Neither is the broader Gene Search transcript/orthology index count. The API `proteins` field counts distinct PPI protein identifiers, as explicitly declared in the public API documentation; it is not a proteomic measurement count.
- General Gene expression is tissue-averaged TPM. Oil and Leaf Color use separate FPKM datasets. No such measurements are bundled here.

## Accessions and source differences

`accessions.tsv` separates a catalog-declared identifier from a repository identifier whose accession and species label were matched. This verification does **not** establish that the repository assembly or annotation is the one deployed by MapleOmics. Missing values are JSON `null` or TSV `unknown`; unavailable checks remain `unverified`.

The package records 30 provided identifiers: 23 accession/species matches (including the versioned Figshare DOI) and seven GWH checks that were unavailable in this retrieval. No missing accession was filled by guessing. The Figshare catalog DOI is unversioned; the repository response identifies version 2, retained verbatim.

`catalog_repository_differences.tsv` lists all eight numerical differences detected between catalog values and retrieved NCBI assembly/annotation metadata. Assembly-size comparison allows 0.05 Mb for a catalog rounded to one decimal. These are documented source differences; no claim is made about which assembly the site actually uses. The exact public input and per-check retrieval provenance are retained.

No dataset-wide license is declared. A repository-specific license is copied only when explicitly returned (the Atru Figshare record reports CC BY 4.0 for that repository item). Public metadata availability does not establish redistribution rights for every linked dataset; consult the original repository and paper.

## Files

- `snapshot.json`: all tables, count definitions, exclusions, data-scope statements and primary public-source provenance.
- `species.tsv`, `capabilities.tsv`, `accessions.tsv`: resource metadata, declared module coverage, identifier checks.
- `sample_counts.tsv`: marginal record counts by assay, species, tissue and returned developmental stage.
- `catalog_repository_differences.tsv`: definite differences in recorded numbers, without replacing either source.
- `inputs/`: captured public metadata and compact repository evidence. Original response hashes and hashes of normalized saved core inputs are distinguished.
- `capture_sources.py`: optional public metadata retrieval using only the Python standard library. It does not download genome files. Re-running it changes the input snapshot; review source changes before releasing a refreshed package.
- `build_snapshot.py`: deterministic generation, consistency checking and ZIP packaging from fixed inputs.
- `SHA256SUMS`: SHA256 for package members (excluding itself).

## Reproduce and check

Use Python 3.9 or later; no third-party packages are required. Run inside this folder:

```sh
python3 build_snapshot.py
python3 build_snapshot.py --check
```

The first command rewrites generated TSV/JSON files, `SHA256SUMS`, and the sibling `mapleomics_release_snapshot.zip`. With unchanged input files, scripts and README, repeated builds produce identical bytes. ZIP entries use sorted paths, fixed timestamps, fixed permissions and no compression. No random sampling or random seed is involved.

The check validates species uniqueness, sample-count partitions, tissue-category counts, catalog versus public-scope denominators, verified-accession status, saved-input checksums and generated-output consistency. It does not prove the scientific validity of linked analyses. Gene-level Ribo differential statistics and derived TE remain excluded pending correction.

To deliberately capture a new public snapshot, run `python3 capture_sources.py`, inspect differences and update this README's scope/count statements if necessary, then rebuild. Network failures are explicitly retained as unverified checks rather than silently assigning accessions or licenses.

## Public sources

- [Species catalog](https://mapleomics.com/data/species_catalog.json)
- [Overall API statistics](https://mapleomics.com/api/stats)
- [Sample API statistics](https://mapleomics.com/api/samples/stats)
- [Data scope and count definitions](https://mapleomics.com/data.html)
- [Public API count definitions](https://www.mapleomics.com/api.html)

Repository API URLs, UTC retrieval times, response hashes and selected observed metadata are listed beside each check in `inputs/registry_evidence.json`.