orfdata 0.17.0__tar.gz → 0.18.0__tar.gz

{orfdata-0.17.0/orfdata.egg-info → orfdata-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orfdata
-Version: 0.17.0
+Version: 0.18.0
 Summary: Reference open reading frames and experimental translation evidence on annotated transcripts
 Author: OpenVax
 License-Expression: Apache-2.0
@@ -99,6 +99,9 @@ checks. **The bundled experimental ORF catalogue is currently human-only**. Offl
 bind real human, mouse, dog and yeast reference slices; those fixtures are not
 new experimental ORF catalogues. [Species and reference identity](docs/species.md).
 
+[Optional catalogue management](docs/catalogs.md) provides explicit, versioned
+downloads and source builds while returning the same ORF objects and queries.
+
 Install with `pip install orfdata[pyensembl]`. See the
 [measurement API](docs/measurements.md) for native units, explicit samples and
 assays, and DataCache-managed downloads. Downloadable

{orfdata-0.17.0 → orfdata-0.18.0}/README.md

@@ -72,6 +72,9 @@ checks. **The bundled experimental ORF catalogue is currently human-only**. Offl
 bind real human, mouse, dog and yeast reference slices; those fixtures are not
 new experimental ORF catalogues. [Species and reference identity](docs/species.md).
 
+[Optional catalogue management](docs/catalogs.md) provides explicit, versioned
+downloads and source builds while returning the same ORF objects and queries.
+
 Install with `pip install orfdata[pyensembl]`. See the
 [measurement API](docs/measurements.md) for native units, explicit samples and
 assays, and DataCache-managed downloads. Downloadable

orfdata-0.18.0/docs/catalogs.md

@@ -0,0 +1,89 @@
+# Optional ORF catalogues
+
+`CatalogRegistry` manages versioned ORF catalogues with the same explicit
+discovery, download, build and offline-open workflow as `DatasetRegistry`.
+It returns the existing `ORFCatalog`; query results still bind to the original
+PyEnsembl transcript through `ReferenceORF`.
+
+The default optional registry currently has no released entries. The bundled
+human catalogue remains available through `load_catalog()` without downloads.
+The examples below use a caller-supplied registry; they do not imply a published
+experimental catalogue for another species.
+
+```python
+import json
+from orfdata import CatalogRegistry
+
+with open("catalog-registry.json") as handle:
+    registry = CatalogRegistry(json.load(handle))
+releases = registry.list(species="yeast")
+for manifest in releases:
+    print(manifest.catalog_id, manifest.version, manifest.coverage)
+
+# Select an entry from your populated registry.
+name = releases[0].catalog_id
+registry.download(name)             # Explicit, checksum-verified acquisition.
+catalog = registry.open(name)       # Offline; no implicit download or repair.
+records = catalog.query(evidence="ms", require_resolved=True)
+orfs = catalog.for_transcript(transcript)  # An already loaded PyEnsembl transcript.
+```
+
+Use `info(name)` for immutable provenance and `download_metadata(name)` for
+artifact URLs, checksums and access terms. `inspect(name)` checks the local
+installation. Species, strain, assembly and annotation contexts remain attached
+to accepted records; a matching accession alone cannot transfer evidence.
+
+```sh
+orfdata catalogs --registry catalog-registry.json list --species yeast
+orfdata catalogs --registry catalog-registry.json download NAME
+orfdata catalogs --registry catalog-registry.json query NAME --evidence ms --require-resolved
+```
+
+Queries share the ordinary ORF CLI's gene, transcript, genomic-position and
+evidence filters, and JSON/TSV/FASTA exports. They cannot override the selected
+release with a local `--catalog` argument. Use `orfdata --catalog FILE` for the
+existing standalone local-file workflow.
+
+## Source builds
+
+`registry.build(name, source_paths={"source.json": path})` explicitly rebuilds
+an allowlisted source adapter. `registry.open_build(name)` opens that local
+result, and `inspect_build(name)` checks its input pins, transform identity and
+output receipt without reopening original input files. The CLI equivalents are
+`catalogs build NAME --source-path source.json=PATH` and
+`catalogs query NAME --built`. A local receipt's checksum is distinct from an
+independently pinned published artifact; `inspect_build().verified` remains false.
+
+Builds are atomic. `force=True` creates a fresh bundle while existing readers'
+files survive. Cache roots follow `ORFDATA_CACHE`, `OPENVAX_DATA_CACHE`, or the
+explicit `cache_root`; catalogues, quantitative datasets and local source builds
+use separate locations.
+
+## Defining a release
+
+A registry definition maps a name to `default_version` and `versions`. Each
+version contains a `CatalogManifest`, `distribution` access terms and an
+`assets` entry for raw `catalog.json.gz` bytes, pinned by URL, SHA-256 and size.
+The manifest declares references, original `SourceAsset` inputs, citations,
+processing and coverage. `coverage.records` is required; source importers also
+report original assignment counts and unresolved categories. Distinct protein
+sequences and evidence summaries are separate counts.
+
+Managed files use the existing `orfdata.catalog.v1` JSON representation and embed
+the full manifest in `metadata.catalog_manifest`. Every accepted record must
+declare a complete genomic reference included in that manifest. Opening validates
+the whole manifest, species/assembly, references and declared output counts.
+
+The initial `catalog-copy-v1` adapter wraps an independently prepared, unmanaged, pinned
+portable catalogue named by `processing.catalog_asset`; it preserves native
+metadata and adds the managed manifest. It rejects an input that already has a
+managed manifest instead of replacing its release provenance. It does not infer missing references or
+validate new biological models on behalf of a source importer. Python developers
+can use `build_catalog(manifest, builder)`, where `builder(inputs, output_path)`
+writes the managed file. DataCache verifies inputs and validates the completed
+output before publishing the local build. Importer paths in metadata are never
+executed as Python code.
+
+[OpenProt source qualification](https://github.com/openvax/orfdata/issues/18)
+and its [coordinate discrepancy](https://github.com/openvax/orfdata/issues/55)
+remain separate from this data-management API.

{orfdata-0.17.0 → orfdata-0.18.0}/orfdata/__init__.py

@@ -12,6 +12,8 @@ from .catalog import (
     load_catalog,
     load_uorf_catalog,
 )
+from .catalog_manifest import CatalogManifest
+from .catalogs import CatalogRegistry, build_catalog
 from .dataset import QuantitativeDataset
 from .datasets import DatasetRegistry, build_dataset
 from .evidence_summary import EvidenceSummary
@@ -45,6 +47,9 @@ __all__ = [
     "ORFCatalog",
     "ORFRecord",
     "ORFEvidence",
+    "CatalogManifest",
+    "CatalogRegistry",
+    "build_catalog",
     "EvidenceSummary",
     "PeptideEvidence",
     "ORFModel",

{orfdata-0.17.0 → orfdata-0.18.0}/orfdata/catalog.py

@@ -516,8 +516,8 @@ class ORFCatalog:
 
         A locus query requires an explicit assembly. Gene and transcript lookup
         is a discovery aid, not evidence transfer between transcript isoforms.
-        Transcript identifiers match exactly as supplied in the source; these
-        are unversioned identifiers. Empty results do not prove no translation.
+        Transcript identifiers match exactly as supplied in the source,
+        including versions when present. Empty results do not prove no translation.
         ``require_unique`` means unique within the evidence source's mapping
         scope, not unique in every normal human proteome.
         ``require_resolved`` excludes aggregate-only support: MS needs a peptide

orfdata-0.18.0/orfdata/catalog_cli.py

@@ -0,0 +1,63 @@
+"""Explicit optional catalogue discovery, acquisition and offline queries."""
+
+import argparse
+import json
+from pathlib import Path
+
+from .catalogs import CatalogRegistry
+from .cli import _add_query_arguments, _query
+
+
+def run(argv=None, prog=None):
+    parser = argparse.ArgumentParser(description=__doc__, prog=prog)
+    parser.add_argument("--registry", help="Local JSON catalogue registry definitions")
+    parser.add_argument("--cache-root", help="Override the OpenVax cache root")
+    commands = parser.add_subparsers(dest="command", required=True)
+    listing = commands.add_parser("list", help="Discover release manifests without downloading")
+    listing.add_argument("--species")
+    listing.add_argument("--taxon-id", type=int)
+    query_parser = None
+    for command in ("info", "inspect", "download", "build", "query"):
+        subparser = commands.add_parser(command)
+        subparser.add_argument("name")
+        subparser.add_argument("--version")
+        if command in ("inspect", "query"):
+            subparser.add_argument("--built", action="store_true", help="Select a local source build explicitly")
+        if command in ("download", "build"):
+            subparser.add_argument("--force", action="store_true")
+            subparser.add_argument("--source-path", action="append", default=[], metavar="ASSET=PATH")
+        if command == "query":
+            query_parser = subparser
+            _add_query_arguments(subparser, catalog_path=False)
+    args = parser.parse_args(argv)
+    try:
+        definitions = json.loads(Path(args.registry).read_text()) if args.registry else None
+        registry = CatalogRegistry(definitions, cache_root=args.cache_root)
+        if args.command == "list":
+            output = [m.to_dict() for m in registry.list(species=args.species, taxon_id=args.taxon_id)]
+        elif args.command == "info":
+            output = registry.info(args.name, args.version).to_dict()
+        elif args.command == "inspect":
+            method = registry.inspect_build if args.built else registry.inspect
+            inspection = method(args.name, args.version)
+            output = dict(status=inspection.status, path=str(inspection.path), verified=inspection.verified)
+            if inspection.error is not None:
+                output["error"] = str(inspection.error)
+        elif args.command in ("download", "build"):
+            paths = {}
+            for item in args.source_path:
+                asset, separator, path = item.partition("=")
+                if not separator or not asset or not path or asset in paths:
+                    raise ValueError("Source overrides require unique ASSET=PATH entries")
+                paths[asset] = path
+            method = registry.build if args.command == "build" else registry.download
+            method(args.name, args.version, force=args.force, source_paths=paths or None)
+            inspect = registry.inspect_build if args.command == "build" else registry.inspect
+            result = inspect(args.name, args.version)
+            output = dict(status=result.status, path=str(result.path), verified=result.verified)
+        else:
+            method = registry.open_build if args.built else registry.open
+            return _query(args, query_parser, lambda _: method(args.name, args.version))
+    except (ValueError, TypeError, KeyError, OSError) as error:
+        parser.error(str(error))
+    print(json.dumps(output, indent=2, sort_keys=True))

orfdata-0.18.0/orfdata/catalog_manifest.py

@@ -0,0 +1,101 @@
+"""Pinned provenance and coverage for an optional ORF catalogue."""
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from .measurements import SourceAsset, _identifier, _metadata, _Record
+from .reference import ReferenceContext
+
+
+@dataclass(frozen=True)
+class CatalogManifest(_Record):
+    """One species/assembly catalogue release, independent of abundance data."""
+
+    catalog_id: str
+    version: str
+    title: str
+    references: tuple
+    sources: tuple
+    citations: tuple
+    coverage: Mapping
+    processing: Mapping
+    schema: str = "orfdata.catalog-manifest.v1"
+
+    @classmethod
+    def from_dict(cls, data):
+        values = dict(data)
+        values["references"] = tuple(ReferenceContext(**c) for c in values["references"])
+        values["sources"] = tuple(SourceAsset.from_dict(s) for s in values["sources"])
+        return cls(**values)
+
+    def __post_init__(self):
+        for name in ("catalog_id", "version", "title"):
+            _identifier(getattr(self, name), name)
+        for name in ("catalog_id", "version"):
+            if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]*", getattr(self, name)):
+                raise ValueError(f"{name} must be a portable catalogue/path identifier")
+        if self.schema != "orfdata.catalog-manifest.v1":
+            raise ValueError("Unsupported catalogue manifest schema")
+        for name in ("references", "sources", "citations"):
+            values = getattr(self, name)
+            if isinstance(values, str):
+                raise TypeError(f"Catalogue {name} must be a sequence of entries")
+            values = tuple(values)
+            if not values:
+                raise ValueError(f"Catalogue {name} cannot be empty")
+            object.__setattr__(self, name, values)
+        if any(not isinstance(r, ReferenceContext) for r in self.references):
+            raise TypeError("Catalogue references must be ReferenceContexts")
+        if len({r.key for r in self.references}) != len(self.references):
+            raise ValueError("Duplicate catalogue reference contexts")
+        if len({r.taxon_id for r in self.references}) != 1:
+            raise ValueError("A catalogue must have one species")
+        builds = {r.genome_build for r in self.references if r.genome_build is not None}
+        if len(builds) != 1 or not any(r.is_genomic for r in self.references):
+            raise ValueError("A catalogue must have one assembly and a complete genomic reference")
+        if any(not isinstance(s, SourceAsset) for s in self.sources):
+            raise TypeError("Catalogue sources must be SourceAssets")
+        if len({s.asset_id for s in self.sources}) != len(self.sources):
+            raise ValueError("Duplicate catalogue source assets")
+        for citation in self.citations:
+            _identifier(citation, "citation")
+        _metadata(self, "coverage", "processing")
+        count = self.coverage.get("records")
+        if type(count) is not int or count < 0:
+            raise ValueError("Catalogue coverage must declare a nonnegative records count")
+        for key in ("distinct_protein_sequences", "evidence_summaries"):
+            if key in self.coverage and (type(self.coverage[key]) is not int or self.coverage[key] < 0):
+                raise ValueError(f"Catalogue {key} must be a nonnegative integer")
+        if not self.processing:
+            raise ValueError("Catalogue processing provenance is required")
+
+    @property
+    def taxon_id(self):
+        return self.references[0].taxon_id
+
+    @property
+    def genome_build(self):
+        return next(r.genome_build for r in self.references if r.is_genomic)
+
+    def validate_catalog(self, catalog):
+        """Check content identity, accepted records and declared reference scope."""
+        if catalog.metadata.get("catalog_manifest") != self.to_dict():
+            raise ValueError("Catalogue manifest disagrees with the registered release")
+        if catalog.taxon_id != self.taxon_id or catalog.genome_build != self.genome_build:
+            raise ValueError("Catalogue species or assembly disagrees with manifest")
+        if len(catalog.records) != self.coverage["records"]:
+            raise ValueError("Catalogue record count disagrees with manifest")
+        references = {r.key for r in self.references}
+        for record in catalog.records:
+            reference = record.reference_context
+            if reference is None or not reference.is_genomic or reference.key not in references:
+                raise ValueError("Managed ORF records require a declared complete genomic reference")
+        for summary in catalog.evidence_summaries:
+            if summary.target.reference.key not in references:
+                raise ValueError("Evidence summary reference is absent from catalogue manifest")
+        counts = dict(distinct_protein_sequences=len({r.protein_sequence for r in catalog.records}),
+                      evidence_summaries=len(catalog.evidence_summaries))
+        for key, actual in counts.items():
+            if key in self.coverage and self.coverage[key] != actual:
+                raise ValueError(f"Catalogue {key} count disagrees with manifest")

orfdata-0.18.0/orfdata/catalogs.py

@@ -0,0 +1,197 @@
+"""Explicit optional catalogue downloads and builds using OpenVax DataCache."""
+
+import gzip
+import json
+from dataclasses import replace
+from importlib.resources import files
+
+from .catalog import ORFCatalog, load_catalog
+from .catalog_manifest import CatalogManifest
+from .datasets import _datacache, _digest, get_data_dir
+from .reference import species_taxon
+
+_ASSET = "catalog.json.gz"
+
+
+def _build_store(manifest, cache_root):
+    return (get_data_dir(cache_root) / "catalog-imports" / manifest.catalog_id /
+            manifest.version / _digest(manifest.to_dict()))
+
+
+def _open(path, manifest):
+    catalog = load_catalog(path)
+    manifest.validate_catalog(catalog)
+    return catalog
+
+
+def _copy_catalog(inputs, output, manifest):
+    """Wrap pinned portable data with release provenance, retaining native facts."""
+    asset = manifest.processing.get("catalog_asset")
+    if asset not in inputs:
+        raise ValueError("Copy importer requires a declared catalog_asset")
+    catalog = load_catalog(inputs[asset])
+    metadata = catalog.metadata
+    if "catalog_manifest" in metadata:
+        raise ValueError("Copy importer expects an unmanaged source catalogue; cannot replace release provenance")
+    metadata["catalog_manifest"] = manifest.to_dict()
+    catalog = ORFCatalog(catalog.records, metadata)
+    manifest.validate_catalog(catalog)
+    with open(output, "wb") as raw, gzip.GzipFile(filename="", mode="wb", fileobj=raw, mtime=0) as handle:
+        handle.write(json.dumps(catalog.to_dict(), sort_keys=True, separators=(",", ":"), allow_nan=False).encode())
+
+
+class CatalogRegistry:
+    """Discover offline, explicitly acquire, then open the existing ORFCatalog.
+
+    Each definition names a pinned default_version, manifests, distribution
+    terms and one checksummed catalog.json.gz asset. No method except download
+    or build may acquire data. Bundled load_catalog() remains independent.
+    """
+
+    def __init__(self, definitions=None, *, cache_root=None):
+        if definitions is None:
+            definitions = json.loads(files("orfdata").joinpath("data/catalogs.json").read_text())
+        self._definitions = json.loads(json.dumps(definitions, allow_nan=False))
+        self._cache_root = cache_root
+        self._manifests = {}
+        self._registry = None
+        for name, entry in self._definitions.items():
+            if entry["default_version"] not in entry["versions"]:
+                raise ValueError("A catalogue default must be a pinned version")
+            for version, release in entry["versions"].items():
+                manifest = CatalogManifest.from_dict(release["manifest"])
+                if (manifest.catalog_id, manifest.version) != (name, version):
+                    raise ValueError("Registry and manifest catalogue identities disagree")
+                if set(release["assets"]) != {_ASSET} or release["assets"][_ASSET].get("decompress", False):
+                    raise ValueError("A catalogue release requires raw catalog.json.gz bytes")
+                distribution = release["distribution"]
+                if not isinstance(distribution.get("access_terms"), str) or not distribution["access_terms"].strip():
+                    raise ValueError("Catalogue artifact access terms are required")
+                if type(distribution.get("redistributable")) is not bool:
+                    raise ValueError("Catalogue artifact redistribution must be explicit")
+                self._manifests[name, version] = manifest
+
+    def _version(self, name, version):
+        if name not in self._definitions:
+            raise ValueError(f"Unknown catalogue {name!r}; use CatalogRegistry.list()")
+        version = self._definitions[name]["default_version"] if version is None else version
+        if (name, version) not in self._manifests:
+            raise ValueError(f"Unknown catalogue version {name!r} {version!r}")
+        return version
+
+    def list(self, *, species=None, taxon_id=None):
+        """Return matching versioned manifests without downloading data."""
+        if species is not None:
+            found = species_taxon(species)
+            if found is None:
+                raise ValueError("Unknown species alias; supply its explicit taxon_id")
+            if taxon_id is not None and taxon_id != found:
+                raise ValueError("Species and taxon_id disagree")
+            taxon_id = found
+        return tuple(m for _, m in sorted(self._manifests.items()) if taxon_id is None or m.taxon_id == taxon_id)
+
+    def info(self, name, version=None):
+        return self._manifests[name, self._version(name, version)]
+
+    def download_metadata(self, name, version=None):
+        release = self._definitions[name]["versions"][self._version(name, version)]
+        return json.loads(json.dumps({k: release[k] for k in ("distribution", "assets")}))
+
+    def _data_registry(self):
+        if self._registry is None:
+            definitions = {name: dict(default_version=entry["default_version"], versions={
+                version: release["assets"] for version, release in entry["versions"].items()})
+                for name, entry in self._definitions.items()}
+
+            def store_path(name, version):
+                release = self._definitions[name]["versions"][version]
+                return get_data_dir(self._cache_root) / "catalogs" / name / version / _digest(release)
+
+            self._registry = _datacache().VersionedDatasetRegistry(definitions, store_path=store_path)
+        return self._registry
+
+    def inspect(self, name, version=None, *, verify_files=True):
+        return self._data_registry().inspect(name, self._version(name, version), verify_files=verify_files)
+
+    def download(self, name, version=None, *, force=False, source_paths=None, **options):
+        """Explicitly install a pinned artifact; accept verified local overrides."""
+        return self._data_registry().download(name, self._version(name, version), force=force,
+                                             source_paths=source_paths, **options)
+
+    def open(self, name, version=None, *, verify_files=True):
+        """Validate installed bytes and content, then return an offline ORFCatalog."""
+        manifest = self.info(name, version)
+        path = self._data_registry().local_path(name, manifest.version, asset=_ASSET, verify_files=verify_files)
+        return _open(path, manifest)
+
+    def build(self, name, version=None, *, force=False, source_paths=None, download_options=None):
+        """Explicitly materialize an allowlisted catalogue source adapter."""
+        manifest = self.info(name, version)
+        if manifest.processing.get("importer") != "catalog-copy-v1":
+            raise ValueError("No packaged importer for this catalogue release")
+        return build_catalog(manifest, lambda inputs, output: _copy_catalog(inputs, output, manifest),
+                             cache_root=self._cache_root, source_paths=source_paths, force=force,
+                             download_options=download_options)
+
+    def inspect_build(self, name, version=None, *, verify_files=True):
+        """Inspect build receipts offline; their hashes are not released-artifact pins."""
+        manifest = self.info(name, version)
+        inspected = _datacache().inspect_materialization(_build_store(manifest, self._cache_root),
+                                                        verify_files=verify_files)
+        if inspected.status != "available":
+            return inspected
+        try:
+            expected = {s.asset_id: s for s in manifest.sources}
+            if set(inspected.sources) != set(expected) or set(inspected.files) != {_ASSET}:
+                raise ValueError("Built catalogue source/output inventory disagrees")
+            for name, source in expected.items():
+                recorded = inspected.sources[name]
+                if (recorded["sha256"] != source.sha256 or recorded["size"] != source.size
+                        or recorded["verified"] is not True):
+                    raise ValueError("Built catalogue source integrity pins disagree")
+            if inspected.transform != dict(version=manifest.schema, options=manifest.to_dict()):
+                raise ValueError("Built catalogue transform/manifest disagrees")
+        except (KeyError, TypeError, ValueError) as exc:
+            return replace(inspected, status="invalid", verified=False, error=exc)
+        return inspected
+
+    def open_build(self, name, version=None, *, verify_files=True):
+        """Open the local source build explicitly; never fall back to a download."""
+        inspected = self.inspect_build(name, version, verify_files=verify_files)
+        if inspected.status == "missing":
+            raise FileNotFoundError(inspected.path)
+        if inspected.status != "available":
+            raise _datacache().FileValidationError(inspected.path, inspected.status) from inspected.error
+        return _open(inspected.files[_ASSET].path, self.info(name, version))
+
+
+def build_catalog(manifest, builder, *, cache_root=None, source_paths=None, force=False, download_options=None):
+    """Materialize pinned sources with builder(inputs, output_path), atomically.
+
+    The output is a portable ORF catalogue with its exact CatalogManifest in
+    metadata['catalog_manifest']. Source and output hashes live in DataCache's
+    receipt. Building does not register or publish a released artifact.
+    """
+    if not isinstance(manifest, CatalogManifest):
+        raise TypeError("manifest must be a CatalogManifest")
+    source_paths = {} if source_paths is None else dict(source_paths)
+    if set(source_paths) - {s.asset_id for s in manifest.sources}:
+        raise ValueError("Unknown local catalogue source asset override")
+    sources = {}
+    for asset in manifest.sources:
+        source = dict(sha256=asset.sha256, size=asset.size)
+        if asset.asset_id in source_paths:
+            source["path"] = str(source_paths[asset.asset_id])
+        else:
+            source["url"] = asset.url
+        sources[asset.asset_id] = source
+
+    def build(inputs, outputs):
+        builder(inputs, outputs[_ASSET])
+        _open(outputs[_ASSET], manifest)
+
+    paths = _datacache().materialize(
+        _build_store(manifest, cache_root), sources,
+        transform=dict(version=manifest.schema, options=manifest.to_dict()),
+        outputs={_ASSET: {}}, builder=build, force=force, download_options=download_options)
+    return _open(paths[_ASSET], manifest)

{orfdata-0.17.0 → orfdata-0.18.0}/orfdata/cli.py

@@ -12,16 +12,29 @@ from .catalog import EVIDENCE_METHODS, UORFCatalog, load_catalog
 def run(argv=None, prog=None, *, catalog_loader=load_catalog):
     """Export reference records as JSON, TSV or FASTA."""
     argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] == "catalogs":
+        from .catalog_cli import run as catalog_run
+
+        return catalog_run(argv[1:], prog=(prog or "orfdata") + " catalogs")
     if argv and argv[0] == "datasets":
         from .dataset_cli import run as dataset_run
 
         return dataset_run(argv[1:], prog=(prog or "orfdata") + " datasets")
     parser = argparse.ArgumentParser(
         description=__doc__, prog=prog,
-        epilog="For quantitative data management, use 'orfdata datasets --help'.")
-    parser.add_argument("--catalog", help="Use a compatible local JSON/JSON.gz catalogue")
-    parser.add_argument("--gene", help="Exact gene symbol or Ensembl gene ID")
-    parser.add_argument("--transcript", help="Exact source transcript ID (unversioned)")
+        epilog="Manage optional ORF catalogues with 'orfdata catalogs --help'; quantitative data with 'orfdata datasets --help'.")
+    _add_query_arguments(parser)
+    args = parser.parse_args(argv)
+    return _query(args, parser, catalog_loader)
+
+
+def _add_query_arguments(parser, *, catalog_path=True):
+    if catalog_path:
+        parser.add_argument("--catalog", help="Use a compatible local JSON/JSON.gz catalogue")
+    else:
+        parser.set_defaults(catalog=None)
+    parser.add_argument("--gene", help="Exact source gene symbol or identifier")
+    parser.add_argument("--transcript", help="Exact source transcript ID, including its version when supplied")
     parser.add_argument("--orf-id", help="Exact catalogue ORF identifier")
     parser.add_argument("--evidence", choices=EVIDENCE_METHODS)
     parser.add_argument("--require-resolved", action="store_true",
@@ -47,10 +60,12 @@ def run(argv=None, prog=None, *, catalog_loader=load_catalog):
     parser.add_argument("--ref", help="Forward-genomic SNV REF; requires --alt and --position")
     parser.add_argument("--alt", help="Forward-genomic SNV ALT; compare initiation contexts")
     parser.add_argument(
-        "--genome-build", help="Required for genomic queries; packaged data use GRCh38"
+        "--genome-build", help="Required for genomic queries; must match the selected catalogue"
     )
     parser.add_argument("--format", choices=("json", "tsv", "fasta"), default="json")
-    args = parser.parse_args(argv)
+
+
+def _query(args, parser, catalog_loader):
     if args.region and args.position:
         parser.error("Choose --region or --position")
     if args.position and args.format != "json":

orfdata-0.18.0/orfdata/data/catalogs.json

@@ -0,0 +1 @@
+{}

orfdata-0.18.0/orfdata/version.py

@@ -0,0 +1 @@
+__version__ = "0.18.0"

{orfdata-0.17.0 → orfdata-0.18.0/orfdata.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orfdata
-Version: 0.17.0
+Version: 0.18.0
 Summary: Reference open reading frames and experimental translation evidence on annotated transcripts
 Author: OpenVax
 License-Expression: Apache-2.0
@@ -99,6 +99,9 @@ checks. **The bundled experimental ORF catalogue is currently human-only**. Offl
 bind real human, mouse, dog and yeast reference slices; those fixtures are not
 new experimental ORF catalogues. [Species and reference identity](docs/species.md).
 
+[Optional catalogue management](docs/catalogs.md) provides explicit, versioned
+downloads and source builds while returning the same ORF objects and queries.
+
 Install with `pip install orfdata[pyensembl]`. See the
 [measurement API](docs/measurements.md) for native units, explicit samples and
 assays, and DataCache-managed downloads. Downloadable

{orfdata-0.17.0 → orfdata-0.18.0}/orfdata.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ deploy.sh
 lint.sh
 pyproject.toml
 test.sh
+docs/catalogs.md
 docs/copy-yeast.md
 docs/coverage.md
 docs/design.md
@@ -22,6 +23,9 @@ docs/storage.md
 orfdata/__init__.py
 orfdata/build.py
 orfdata/catalog.py
+orfdata/catalog_cli.py
+orfdata/catalog_manifest.py
+orfdata/catalogs.py
 orfdata/cli.py
 orfdata/dataset.py
 orfdata/dataset_cli.py
@@ -42,6 +46,7 @@ orfdata.egg-info/dependency_links.txt
 orfdata.egg-info/entry_points.txt
 orfdata.egg-info/requires.txt
 orfdata.egg-info/top_level.txt
+orfdata/data/catalogs.json
 orfdata/data/datasets.json
 orfdata/data/orf-evidence/AUTHOR-LICENSE.txt
 orfdata/data/orf-evidence/NOTICE.txt
@@ -58,6 +63,7 @@ orfdata/sources/pfizer.py
 orfdata/sources/pfizer_rna.py
 orfdata/sources/wang.py
 tests/conftest.py
+tests/test_catalog_registry.py
 tests/test_copy.py
 tests/test_cross_reference_pairing.py
 tests/test_ensembl_search_reference.py

{orfdata-0.17.0 → orfdata-0.18.0}/pyproject.toml

@@ -29,7 +29,7 @@ version = {attr = "orfdata.version.__version__"}
 include = ["orfdata*"]
 
 [tool.setuptools.package-data]
-orfdata = ["data/uorf-evidence/*", "data/orf-evidence/*", "data/datasets.json"]
+orfdata = ["data/uorf-evidence/*", "data/orf-evidence/*", "data/datasets.json", "data/catalogs.json"]
 
 [tool.ruff]
 target-version = "py39"