orfdata 0.8.0__tar.gz → 0.9.0__tar.gz

{orfdata-0.8.0/orfdata.egg-info → orfdata-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orfdata
-Version: 0.8.0
+Version: 0.9.0
 Summary: Reference open reading frames and experimental translation evidence on annotated transcripts
 Author: OpenVax
 License-Expression: Apache-2.0

{orfdata-0.8.0 → orfdata-0.9.0}/docs/measurements.md

@@ -51,6 +51,24 @@ For native sources with unreported genomic metadata, use explicit
 [source references and mapping views](source-references.md) to retain the original
 observation alongside its mapping to a PyEnsembl target.
 
+Choose a native series explicitly when a source supplies several units:
+
+```python
+values = dataset.measurements(quantity="protein_abundance", unit="iBAQ", scale="linear")
+dataset.export_parquet("ibaq.parquet", unit="iBAQ", scale="linear")
+```
+
+`unit`, `scale` and `log_base` also work with `mapped_measurements` and existing
+storage v1-v4 releases. Units are exact and case-sensitive. Selecting
+`scale="log", log_base=2` returns values already on that scale; nothing is transformed.
+An unavailable series returns no observations. Contradictory linear/log requests
+raise an error. Omitting selectors preserves all native series.
+
+For example, Pfizer iBAQ and rIBAQ are two series from the same source rows.
+Selecting or exporting both does not create additional donors, spectra or
+independent detections. Source row/sample/assay lineage stays attached to each
+measurement.
+
 The CLI uses the same operations:
 
 ```sh

{orfdata-0.8.0 → orfdata-0.9.0}/docs/pfizer-protein.md

@@ -20,7 +20,7 @@ include sex. Channels and technical runs do not count as independent donors.
 pip install 'orfdata[data]'
 orfdata datasets list --species dog
 orfdata datasets download pfizer-atlas-dog-protein
-orfdata datasets query pfizer-atlas-dog-protein --quantity protein_abundance
+orfdata datasets query pfizer-atlas-dog-protein --quantity protein_abundance --unit iBAQ --scale linear
 ```
 
 ```python
@@ -30,10 +30,13 @@ registry = DatasetRegistry()
 dataset = registry.open("pfizer-atlas-dog-protein")  # After explicit download.
 reference, = dataset.manifest.references
 group = ScopedTarget(reference, "protein_group", "A0A0A0MPB0", "MSV000099744:ProteinGroup")
-for value in dataset.measurements(target=group):
+for value in dataset.measurements(target=group, unit="iBAQ", scale="linear"):
     print(value.sample_id, value.unit, value.value, value.status)
 ```
 
+Omit the unit selector to return both native series. They retain the same source
+row and sample identity; two units do not imply two independent measurements.
+
 Every target retains its species and the checksum of the deposited UniProt
 search FASTA. The original genomic assembly and UniProt release are unknown.
 They stay unknown; a future annotation mapping must be explicit and validated.

{orfdata-0.8.0 → orfdata-0.9.0}/orfdata/dataset.py

@@ -18,6 +18,8 @@ from .measurements import (
     MeasurementReference,
     Sample,
     TargetMapping,
+    _identifier,
+    _number,
     _plain,
 )
 from .pairing import (
@@ -138,6 +140,19 @@ def _measurement_record(observation):
     return result
 
 
+def _validate_native_selectors(unit=None, scale=None, log_base=None):
+    if unit is not None:
+        _identifier(unit, "measurement unit selector")
+    if scale is not None and scale not in ("linear", "log"):
+        raise ValueError("Measurement scale selector must be linear or log")
+    if log_base is not None:
+        _number(log_base, "logarithm base selector")
+        if log_base <= 0 or log_base == 1:
+            raise ValueError("Logarithm base selector must be positive and not one")
+        if scale == "linear":
+            raise ValueError("A linear scale selector cannot have a logarithm base")
+
+
 class QuantitativeDataset:
     """A read-only release. Constructing or querying it never downloads data.
 
@@ -405,8 +420,9 @@ class QuantitativeDataset:
             raise ValueError("Choose explicit usable mapping statuses")
         if type(require_sequence) is not bool:
             raise TypeError("require_sequence must be a boolean")
-        if set(observation_filters) - {"sample_id", "assay_id", "quantity", "status"}:
+        if set(observation_filters) - {"sample_id", "assay_id", "quantity", "status", "unit", "scale", "log_base"}:
             raise ValueError("Mapped observation filters cannot override source/target reference identity")
+        _validate_native_selectors(**{name: observation_filters.get(name) for name in ("unit", "scale", "log_base")})
         for mapping in self.reference_mappings(target=target):
             if mapping.status not in allowed or (require_sequence and not mapping.sequence_validated):
                 continue
@@ -468,16 +484,19 @@ class QuantitativeDataset:
                                               tuple(by_target[1].get(relation.right.key, ())))
 
     def measurements(self, *, target=None, reference=None, sample_id=None,
-                     assay_id=None, quantity=None, status=None):
+                     assay_id=None, quantity=None, status=None, unit=None, scale=None,
+                     log_base=None):
         """Iterate native observations; a target match is exact, never orthology.
 
         Unqualified IDs across multiple references are rejected. To browse all
         species together, omit ID filters; each result still carries its scope.
+        Native unit/scale/base selectors are exact; no conversion or aggregation.
         """
         if quantity is not None and quantity not in QUANTITIES:
             raise ValueError("Unknown measurement quantity")
         if status is not None and status not in MEASUREMENT_STATUSES:
             raise ValueError("Unknown measurement status")
+        _validate_native_selectors(unit, scale, log_base)
         scope = self._scope(reference)
         if target is not None:
             if not isinstance(target, ScopedTarget):
@@ -495,11 +514,23 @@ class QuantitativeDataset:
                  "m.id, m.sample_id, m.assay_id, m.quantity, m.status "
                  "FROM measurement m JOIN target t ON m.reference_key=t.reference_key "
                  "AND m.target_key=t.key")
-        if selected:
-            query += " WHERE " + " AND ".join(f"m.{key}=?" for key, _ in selected)
+        conditions = [f"m.{key}=?" for key, _ in selected]
+        parameters = [value for _, value in selected]
+        # JSON extraction applies to original v1-v3 records and compact v4
+        # residual records. SQLite filters before Python reconstructs objects.
+        for value, expression in (
+            (unit, "json_extract(m.record, '$.unit')"),
+            (scale, "coalesce(json_extract(m.record, '$.scale'), 'linear')"),
+            (log_base, "json_extract(m.record, '$.log_base')"),
+        ):
+            if value is not None:
+                conditions.append(expression + "=?")
+                parameters.append(value)
+        if conditions:
+            query += " WHERE " + " AND ".join(conditions)
         query += " ORDER BY m.reference_key, m.id"
         with closing(self._connect()) as connection:
-            for row in connection.execute(query, [value for _, value in selected]):
+            for row in connection.execute(query, parameters):
                 values = json.loads(row[0])
                 if self._storage_version == 4:
                     values = dict(_V4_DEFAULTS, **values)

{orfdata-0.8.0 → orfdata-0.9.0}/orfdata/dataset_cli.py

@@ -39,6 +39,9 @@ def run(argv=None, prog=None):
             subparser.add_argument("--assay-id")
             subparser.add_argument("--quantity")
             subparser.add_argument("--status")
+            subparser.add_argument("--unit", help="Exact native unit, e.g. iBAQ, rIBAQ, TPM or counts")
+            subparser.add_argument("--scale", choices=("linear", "log"))
+            subparser.add_argument("--log-base", type=float, help="Exact native logarithm base; no transformation")
             subparser.add_argument("--target")
             subparser.add_argument("--kind")
             subparser.add_argument("--namespace")
@@ -111,7 +114,8 @@ def run(argv=None, prog=None):
                 references = {r.key: r for r in dataset.manifest.references}
                 target = ScopedTarget(references[args.reference], args.kind, args.target, args.namespace)
             filters = dict(sample_id=args.sample, assay_id=args.assay_id,
-                           quantity=args.quantity, status=args.status)
+                           quantity=args.quantity, status=args.status,
+                           unit=args.unit, scale=args.scale, log_base=args.log_base)
             if args.mapped:
                 if target is None:
                     parser.error("--mapped requires an exact target and reference")

orfdata-0.9.0/orfdata/version.py

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

{orfdata-0.8.0 → orfdata-0.9.0/orfdata.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orfdata
-Version: 0.8.0
+Version: 0.9.0
 Summary: Reference open reading frames and experimental translation evidence on annotated transcripts
 Author: OpenVax
 License-Expression: Apache-2.0

{orfdata-0.8.0 → orfdata-0.9.0}/orfdata.egg-info/SOURCES.txt

@@ -57,6 +57,7 @@ tests/test_pfizer.py
 tests/test_reference_context.py
 tests/test_reference_mapping.py
 tests/test_reference_orf.py
+tests/test_selectors.py
 tests/test_storage.py
 tests/test_uorf_catalog.py
 tests/data/copy/GSM1905474.soft

orfdata-0.9.0/tests/test_selectors.py

@@ -0,0 +1,130 @@
+"""Native series selection preserves values, lineage and target resolution."""
+
+import json
+from dataclasses import replace
+from pathlib import Path
+
+import pytest
+
+from orfdata import DatasetManifest, DatasetRegistry, Measurement, QuantitativeDataset
+from orfdata.cli import run
+from orfdata.sources.pfizer import import_protein
+
+
+@pytest.fixture(params=("human", "mouse", "dog"))
+def native(request, tmp_path):
+    root = Path(__file__).parent / "data/pfizer" / request.param
+    manifest = DatasetManifest.from_dict(json.loads((root / "manifest.json").read_text()))
+    return import_protein({a.asset_id: root / a.asset_id for a in manifest.sources}, tmp_path / "native.sqlite", manifest)
+
+
+def test_native_unit_values_and_source_identity(native):
+    original = list(native.measurements(quantity="protein_abundance"))
+    assert len(original) == 10
+    selected = {}
+    for unit in ("iBAQ", "rIBAQ"):
+        values = list(native.measurements(quantity="protein_abundance", unit=unit, scale="linear"))
+        assert len(values) == 5 and values == [m for m in original if m.unit == unit]
+        assert any(m.value == 0 and m.status == "measured" for m in values)
+        assert any(m.value is None and m.status == "missing" for m in values)
+        selected[unit] = {(m.sample_id, m.assay_id, m.provenance["line"]) for m in values}
+    assert selected["iBAQ"] == selected["rIBAQ"]  # Same five source rows, two series.
+    for unit in ("copies/cell", "ibaq", "iBAQ' OR 1=1 --"):
+        assert list(native.measurements(unit=unit)) == []
+    assert list(native.measurements(unit="iBAQ", scale="log")) == []
+    mapping = next(m for m in native.reference_mappings() if m.targets)
+    target = mapping.targets[0]
+    assert list(native.mapped_measurements(target, unit="iBAQ")) == []
+    views = list(native.mapped_measurements(target, mapping_statuses=["unresolved"], unit="iBAQ", scale="linear"))
+    assert views and all(v.measurement.unit == "iBAQ" and v.attribution == "group_membership_context" for v in views)
+
+
+def test_cli_native_and_mapped(native, tmp_path, capsys):
+    from test_measurements import definition
+
+    definitions = definition(native)
+    path = tmp_path / "registry.json"
+    path.write_text(json.dumps(definitions))
+    cache = tmp_path / "cache"
+    DatasetRegistry(definitions, cache_root=cache).download(native.manifest.dataset_id, show_progress=False)
+    prefix = ["datasets", "--registry", str(path), "--cache-root", str(cache), "query", native.manifest.dataset_id]
+    run(prefix + ["--unit", "iBAQ", "--scale", "linear"])
+    rows = [json.loads(line) for line in capsys.readouterr().out.splitlines()]
+    assert len(rows) == 5 and all(r["unit"] == "iBAQ" for r in rows)
+    target = next(m.targets[0] for m in native.reference_mappings() if m.targets)
+    run(prefix + ["--mapped", "--mapping-status", "unresolved", "--reference", target.reference.key,
+                  "--target", target.identifier, "--kind", target.kind, "--namespace", target.namespace,
+                  "--unit", "rIBAQ", "--scale", "linear"])
+    rows = [json.loads(line) for line in capsys.readouterr().out.splitlines()]
+    assert rows and all(r["measurement"]["unit"] == "rIBAQ" for r in rows)
+    run(prefix + ["--unit", "copies/cell"])
+    assert capsys.readouterr().out == ""
+
+
+def test_parquet_uses_the_same_selection(native, tmp_path):
+    parquet = pytest.importorskip("pyarrow.parquet")
+    output = tmp_path / "selected.parquet"
+    native.export_parquet(output, unit="iBAQ", scale="linear")
+    rows = parquet.read_table(output).to_pylist()
+    assert len(rows) == 5 and all(r["unit"] == "iBAQ" for r in rows)
+    assert [Measurement.from_dict(json.loads(r["measurement_json"])) for r in rows] == list(native.measurements(unit="iBAQ"))
+    native.export_parquet(output, unit="unavailable")
+    assert parquet.read_table(output).num_rows == 0
+
+
+@pytest.mark.parametrize("version", (1, 2, 3))
+def test_legacy_exact_series_filters(version):
+    dataset = QuantitativeDataset(Path(__file__).parent / f"data/storage/v{version}.sqlite")
+    original = list(dataset.measurements())
+    for unit in ("TPM", "iBAQ", "fixture-units"):
+        assert list(dataset.measurements(unit=unit, scale="linear")) == [m for m in original if m.unit == unit]
+    assert list(dataset.measurements(scale="log")) == []
+    assert list(dataset.measurements(log_base=2)) == []
+
+
+@pytest.fixture
+def transformed(experiment, tmp_path):
+    manifest, samples, assays, values = experiment
+    value = values[0]
+    observations = [replace(value, measurement_id="linear", value=0),
+                    replace(value, measurement_id="log2", value=-2, scale="log", log_base=2),
+                    replace(value, measurement_id="log10", value=-1, scale="log", log_base=10)]
+    return QuantitativeDataset.create(tmp_path / "log.sqlite", manifest, samples=samples, assays=assays, measurements=observations)
+
+
+def test_log_base_selection_never_transforms(transformed):
+    assert [m.value for m in transformed.measurements(unit="TPM", scale="linear")] == [0]
+    assert {m.value for m in transformed.measurements(scale="log")} == {-1, -2}
+    assert [m.value for m in transformed.measurements(unit="TPM", log_base=2)] == [-2]
+    assert [m.value for m in transformed.measurements(scale="log", log_base=10)] == [-1]
+    assert list(transformed.measurements(log_base=3)) == []
+
+
+def test_cli_log_base_and_contradictory_selection(transformed, tmp_path, capsys):
+    from test_measurements import definition
+
+    definitions = definition(transformed)
+    path = tmp_path / "registry.json"
+    path.write_text(json.dumps(definitions))
+    cache = tmp_path / "cache"
+    DatasetRegistry(definitions, cache_root=cache).download("fixture", show_progress=False)
+    prefix = ["datasets", "--registry", str(path), "--cache-root", str(cache), "query", "fixture"]
+    run(prefix + ["--unit", "TPM", "--scale", "log", "--log-base", "2"])
+    rows = [json.loads(line) for line in capsys.readouterr().out.splitlines()]
+    assert len(rows) == 1 and rows[0]["value"] == -2 and rows[0]["log_base"] == 2
+    with pytest.raises(SystemExit):
+        run(prefix + ["--scale", "linear", "--log-base", "2"])
+    assert "cannot have a logarithm base" in capsys.readouterr().err
+
+
+@pytest.mark.parametrize("filters", [
+    {"unit": ""}, {"unit": "  "}, {"unit": 1}, {"scale": "log2"}, {"log_base": 0},
+    {"log_base": 1}, {"log_base": -2}, {"log_base": True}, {"log_base": float("inf")},
+    {"log_base": float("nan")}, {"scale": "linear", "log_base": 2},
+])
+def test_invalid_selectors(transformed, filters):
+    with pytest.raises((ValueError, TypeError)):
+        list(transformed.measurements(**filters))
+    target = next(transformed.measurements()).target
+    with pytest.raises((ValueError, TypeError)):
+        list(transformed.mapped_measurements(target, **filters))

orfdata-0.8.0/orfdata/version.py

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