genome-spy-python 0.1.0__py3-none-any.whl

genome_spy/data.py

@@ -0,0 +1,56 @@
+"""Helpers for schema-backed GenomeSpy data sources."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any, cast
+
+from genome_spy.schema import Data, ExprRef, LazyDataParams, UrlTemplate
+from genome_spy.schema.lazy import LazyDataMethodMixin
+
+__all__ = ["Data", "LazyNamespace", "lazy"]
+
+_LazyUrl = str | Sequence[str] | ExprRef | dict[str, Any] | UrlTemplate
+
+
+class LazyNamespace(LazyDataMethodMixin):
+    """Convenience builders for GenomeSpy lazy data sources.
+
+    Description:
+        These helpers build schema-backed :class:`genome_spy.schema.Data`
+        objects with a populated ``lazy`` block so callers can stay within the
+        handwritten chart API instead of assembling nested dictionaries by hand.
+
+    Example:
+        >>> lazy.bigwig("https://example.test/signal.bw")
+        >>> lazy.gff3("https://example.test/genes.gff3.gz", windowSize=2_000_000)
+    """
+
+    def source(self, type: str, url: _LazyUrl, /, **kwargs: Any) -> Data:
+        """Create a lazy data source of an arbitrary GenomeSpy type.
+
+        Description:
+            This is the generic escape hatch for lazy data sources. Named
+            helpers such as :meth:`bigwig` and :meth:`gff3` cover each
+            schema-defined URL-backed source type.
+
+        Args:
+            type: GenomeSpy lazy source type such as ``"bigwig"`` or
+                ``"gff3"``.
+            url: Remote data URL.
+            **kwargs: Additional lazy-source parameters supported by GenomeSpy.
+
+        Returns:
+            A schema-backed :class:`genome_spy.schema.Data` object.
+
+        Raises:
+            No exceptions are raised directly here.
+
+        Example:
+            >>> lazy.source("bigwig", "https://example.test/signal.bw")
+        """
+
+        return Data(lazy=LazyDataParams(type=cast(Any, type), url=url, **kwargs))
+
+
+lazy = LazyNamespace()

genome_spy/data_transformers.py

@@ -0,0 +1,267 @@
+"""Settings for preparing chart data during serialization."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from contextlib import AbstractContextManager
+from hashlib import sha256
+from typing import Any
+
+from genome_spy.schema.core import _ROOT_SCHEMA
+from genome_spy.schemapi import SchemaBase, Undefined, UndefinedType
+
+__all__ = ["DataTransformerSettings", "data_transformers"]
+
+
+class _RestoreSettings(AbstractContextManager["DataTransformerSettings"]):
+    def __init__(self, settings: DataTransformerSettings, previous: bool) -> None:
+        self.settings = settings
+        self.previous = previous
+
+    def __enter__(self) -> DataTransformerSettings:
+        return self.settings
+
+    def __exit__(self, *args: Any) -> None:
+        self.settings.consolidate_datasets = self.previous
+
+
+class DataTransformerSettings:
+    """Control whether exported charts share repeated inline tables.
+
+    Description:
+        Consolidation is enabled by default. This settings object supports
+        dataset consolidation only, not a registry of transformer plugins.
+
+    Example:
+        >>> with data_transformers.enable(consolidate_datasets=False):
+        ...     spec = chart.to_dict()
+    """
+
+    def __init__(self) -> None:
+        self._consolidate_datasets = True
+
+    @property
+    def consolidate_datasets(self) -> bool:
+        """Whether eligible inline tables become shared named datasets."""
+        return self._consolidate_datasets
+
+    @consolidate_datasets.setter
+    def consolidate_datasets(self, value: bool) -> None:
+        if not isinstance(value, bool):
+            raise TypeError("consolidate_datasets must be a boolean.")
+        self._consolidate_datasets = value
+
+    def enable(
+        self, *, consolidate_datasets: bool | UndefinedType = Undefined
+    ) -> AbstractContextManager[DataTransformerSettings]:
+        """Apply a setting, optionally restoring it after a ``with`` block.
+
+        Description:
+            The change takes effect immediately. When used as a context manager,
+            the previous value is restored even if the block raises an error.
+
+        Args:
+            consolidate_datasets: Whether to share eligible inline tables.
+                Omit to keep the current setting.
+
+        Returns:
+            A context manager that restores the previous setting.
+
+        Raises:
+            TypeError: If the setting is not a boolean.
+
+        Example:
+            >>> with data_transformers.enable(consolidate_datasets=False):
+            ...     spec = chart.to_dict()
+        """
+        previous = self.consolidate_datasets
+        if not isinstance(consolidate_datasets, UndefinedType):
+            self.consolidate_datasets = consolidate_datasets
+        return _RestoreSettings(self, previous)
+
+
+data_transformers = DataTransformerSettings()
+
+
+def _schema_parts(
+    schema: dict[str, Any], seen: set[int] | None = None
+) -> Iterator[dict[str, Any]]:
+    """Resolve schema alternatives without descending into instance fields."""
+    if seen is None:
+        seen = set()
+    if id(schema) in seen:
+        return
+    seen.add(id(schema))
+    yield schema
+    ref = schema.get("$ref")
+    if isinstance(ref, str):
+        name = ref.removeprefix("#/definitions/")
+        target = _ROOT_SCHEMA.get("definitions", {}).get(name, {})
+        yield from _schema_parts(target, seen)
+    for keyword in ("anyOf", "oneOf", "allOf"):
+        for alternative in schema.get(keyword, []):
+            yield from _schema_parts(alternative, seen)
+
+
+def _data_slots(
+    value: Any,
+    schema: dict[str, Any] = _ROOT_SCHEMA,
+    *,
+    owner: str | None = None,
+    scoped: bool = False,
+    root: bool = True,
+    include_templates: bool = False,
+) -> Iterator[tuple[str, dict[str, Any], str | None, bool]]:
+    """Visit only schema-declared data sources and dataset declarations.
+
+    Open mappings (including rows, metadata, and parameter values) are opaque.
+    Templates are separate serialization roots, not live view instances.
+    Schema references also discover sources inside new transform definitions.
+    """
+    if isinstance(value, SchemaBase):
+        value = value._kwds
+    if not isinstance(value, (dict, list, tuple)):
+        return
+    parts = list(_schema_parts(schema))
+    # Stop at a data source: its records are user data, not chart grammar.
+    source_refs = {"#/definitions/InlineData", "#/definitions/NamedData"}
+    if (
+        isinstance(value, dict)
+        and value.keys() & {"values", "name", "url", "lazy", "sequence"}
+        and any(p.get("$ref") in source_refs for p in parts)
+    ):
+        yield "data", value, owner, scoped
+        return
+    if isinstance(value, (list, tuple)):
+        items = [p["items"] for p in parts if isinstance(p.get("items"), dict)]
+        if items:
+            for item in value:
+                yield from _data_slots(
+                    item,
+                    {"anyOf": items},
+                    owner=owner,
+                    scoped=scoped,
+                    root=False,
+                    include_templates=include_templates,
+                )
+        return
+    # Merge property locations, not validation rules. The generated wrappers
+    # remain responsible for validating which union branch the value satisfies.
+    properties: dict[str, list[dict[str, Any]]] = {}
+    for part in parts:
+        for key, child_schema in part.get("properties", {}).items():
+            properties.setdefault(key, []).append(child_schema)
+    if not root and "datasets" in properties and "datasets" in value:
+        name = value.get("name")
+        owner = name if isinstance(name, str) and name else None
+        scoped = True
+    for key, child_schemas in properties.items():
+        if key not in value:
+            continue
+        if key == "templates" and isinstance(value[key], dict):
+            for template in value[key].values():
+                if isinstance(template, SchemaBase):
+                    template = template._kwds
+                if isinstance(template, dict):
+                    yield "template", template, None, True
+                    if include_templates:
+                        yield from _data_slots(template, include_templates=True)
+        elif key == "datasets":
+            if isinstance(value[key], dict):
+                yield "datasets", value[key], owner, scoped
+        else:
+            yield from _data_slots(
+                value[key],
+                {"anyOf": child_schemas},
+                owner=owner,
+                scoped=scoped,
+                root=False,
+                include_templates=include_templates,
+            )
+
+    # Typed maps (Record[str, T]) contain grammar; arbitrary maps do not.
+    additional = [
+        part["additionalProperties"]
+        for part in parts
+        if isinstance(part.get("additionalProperties"), dict)
+    ]
+    if additional:
+        for key in value.keys() - properties.keys():
+            yield from _data_slots(
+                value[key],
+                {"anyOf": additional},
+                owner=owner,
+                scoped=scoped,
+                root=False,
+                include_templates=include_templates,
+            )
+
+
+def _dataset_name(canonical: str) -> str:
+    """Name normalized content consistently, independently of object identity."""
+    return "data-" + sha256(canonical.encode()).hexdigest()[:32]
+
+
+class _DatasetConsolidation:
+    """Collect tables once per serialization, reserving authored names first."""
+
+    def __init__(self, authored: Any) -> None:
+        self.reserved: set[str] = set()
+        for kind, value, _, _ in _data_slots(authored, include_templates=True):
+            if kind == "datasets":
+                self.reserved.update(value)
+            elif kind == "data" and isinstance(value.get("name"), str):
+                self.reserved.add(value["name"])
+        self.names: dict[str, str] = {}
+        self.datasets: dict[str, Any] = {}
+
+    def source(self, source: Any) -> Any:
+        if not isinstance(source, dict) or set(source) - {"values", "description"}:
+            return source
+        rows = source.get("values")
+        # Non-array and format-bearing sources need their inline loader.
+        if not isinstance(rows, list) or not all(isinstance(row, dict) for row in rows):
+            return source
+        # Secondary inputs may arrive as raw schema values rather than through
+        # Chart's data normalizer. Hash the same JSON-safe rows in either path.
+        from genome_spy._chart_authoring import json_safe
+
+        rows = json_safe(rows)
+        canonical = json.dumps(
+            rows, sort_keys=True, separators=(",", ":"), allow_nan=False
+        )
+        name = self.names.get(canonical)
+        if name is None:
+            base = _dataset_name(canonical)
+            name = base
+            suffix = 1
+            while name in self.reserved:
+                name = f"{base}-{suffix}"
+                suffix += 1
+            self.reserved.add(name)
+            self.names[canonical] = name
+            self.datasets[name] = rows
+        return {key: value for key, value in source.items() if key != "values"} | {
+            "name": name
+        }
+
+    def finish(self, spec: dict[str, Any]) -> dict[str, Any]:
+        # Also cover raw/generated nested specs and secondary transform inputs.
+        for kind, source, _, _ in _data_slots(spec):
+            if kind == "template":
+                # Each imported instance owns these declarations at runtime.
+                _consolidate(source)
+            elif kind == "data":
+                replacement = self.source(source)
+                if replacement is not source:
+                    source.clear()
+                    source.update(replacement)
+        if self.datasets:
+            spec.setdefault("datasets", {}).update(self.datasets)
+        return spec
+
+
+def _consolidate(spec: dict[str, Any]) -> dict[str, Any]:
+    """Consolidate an owned serialized spec without changing authored names."""
+    return _DatasetConsolidation(spec).finish(spec)

genome_spy/datasets/__init__.py

@@ -0,0 +1,189 @@
+"""Dataset helpers for packaged GenomeSpy example data."""
+
+from __future__ import annotations
+
+import json
+from importlib.abc import Traversable
+from importlib.resources import files
+from pathlib import Path
+from typing import Any, Literal, cast, overload
+
+__all__ = [
+    "DatasetNotFoundError",
+    "available_datasets",
+    "load_dataset",
+]
+
+_DATA_DIR = files("genome_spy.datasets").joinpath("data")
+_DATASETS = {
+    "airway_metadata": "airway_metadata.csv",
+    "airway_scaledcounts": "airway_scaledcounts.csv",
+    "brca_maf": "brca.maf.gz",
+    "hapmap_gwas": "hapmap_gwas.csv",
+    "mutation_impact_reference": "mutation_impact_reference.json",
+    "p53_sequence_comparison": "p53_sequence_comparison.json.gz",
+    "pik3ca_mutations": "pik3ca_mutations.json",
+    "pik3ca_tcga_brca_lollipop": "pik3ca_tcga_brca_lollipop.json",
+    "tal1_alphagenome_reference": "tal1_alphagenome_reference.json.gz",
+    "pyoncoprint_tcga": "tcga.tsv",
+    "refseq_gene_bodies": "refseq_gene_bodies.csv.gz",
+    "tcga_laml_annotations": "tcga_laml_annot.tsv",
+    "tcga_laml_combined_oncoplot": "tcga_laml_combined_oncoplot.json.gz",
+    "tcga_laml_maf": "tcga_laml.maf.gz",
+    "tcga_ov_gistic_lesions": "tcga_ov_gistic_lesions.tsv.gz",
+    "tcga_ov_gistic_scores": "tcga_ov_gistic_scores.tsv.gz",
+    "tcga_oncoprint": "oncoprint_dataset3.json",
+}
+
+
+class DatasetNotFoundError(ValueError):
+    """Dataset name lookup failed.
+
+    Description:
+        ``load_dataset`` and related helpers use this exception to report an
+        unknown dataset name together with the valid packaged choices.
+    """
+
+
+def available_datasets() -> tuple[str, ...]:
+    """Packaged dataset names.
+
+    Description:
+        The returned names are the public identifiers accepted by
+        ``load_dataset``.
+
+    Returns:
+        Dataset names that ``load_dataset`` accepts.
+
+    Raises:
+        None.
+
+    Example:
+        >>> available_datasets()
+        ('airway_metadata', 'airway_scaledcounts', 'hapmap_gwas', ...)
+    """
+
+    return tuple(sorted(_DATASETS))
+
+
+def _resource_for(name: str) -> Traversable:
+    try:
+        filename = _DATASETS[name]
+    except KeyError as exc:
+        known = ", ".join(available_datasets())
+        raise DatasetNotFoundError(
+            f"Unknown dataset {name!r}. Available datasets: {known}."
+        ) from exc
+    return _DATA_DIR.joinpath(filename)
+
+
+def _load_table_bundle(name: str, tables: tuple[str, ...]) -> dict[str, Any]:
+    """Load selected prepared JSON tables as DataFrames, preserving metadata."""
+    import pandas as pd
+
+    data = load_dataset(name, as_format="json")
+    if not isinstance(data, dict):
+        raise ValueError(f"Dataset {name!r} must contain a mapping of tables.")
+    for table in tables:
+        data[table] = pd.DataFrame.from_records(data[table])
+    return data
+
+
+def _load_dataframe(name: str) -> Any:
+    try:
+        import pandas as pd
+    except ImportError as exc:
+        raise ImportError(
+            f"Loading dataset {name!r} as a DataFrame requires pandas. "
+            "Install pandas or use as_format='text' or as_format='json'."
+        ) from exc
+
+    resource = _resource_for(name)
+    suffixes = Path(_DATASETS[name]).suffixes
+    if suffixes in ([".csv"], [".csv", ".gz"]):
+        return pd.read_csv(resource)
+    if suffixes in ([".tsv"], [".tsv", ".gz"]):
+        return pd.read_csv(resource, sep="\t")
+    if suffixes[-2:] == [".maf", ".gz"]:
+        return pd.read_csv(resource, sep="\t", compression="gzip")
+    raise ValueError(
+        f"Dataset {name!r} is not tabular and cannot be read as a DataFrame."
+    )
+
+
+@overload
+def load_dataset(name: str, *, as_format: Literal["auto"] = "auto") -> Any: ...
+
+
+@overload
+def load_dataset(name: str, *, as_format: Literal["dataframe"]) -> Any: ...
+
+
+@overload
+def load_dataset(
+    name: str, *, as_format: Literal["json"]
+) -> dict[str, Any] | list[Any]: ...
+
+
+@overload
+def load_dataset(name: str, *, as_format: Literal["text"]) -> str: ...
+
+
+def load_dataset(
+    name: str,
+    *,
+    as_format: Literal["auto", "dataframe", "json", "text"] = "auto",
+) -> Any:
+    """Load a packaged example dataset by name.
+
+    Description:
+        The loader understands the small set of real datasets vendored with the
+        package for examples and tutorials. ``"auto"`` returns a pandas
+        ``DataFrame`` for CSV, TSV, and compressed MAF files and parsed Python
+        objects for JSON files.
+
+    Args:
+        name: Dataset name from ``available_datasets()``.
+        as_format: Output format to return.
+
+    Returns:
+        The loaded dataset in the requested format.
+
+    Raises:
+        DatasetNotFoundError: If the dataset name is unknown.
+        ImportError: If ``as_format="dataframe"`` is requested without pandas.
+        ValueError: If the requested format does not match the stored file type.
+
+    Example:
+        >>> load_dataset("hapmap_gwas").head()
+        >>> load_dataset("pik3ca_mutations", as_format="json")["domains"][0]
+    """
+
+    resource = _resource_for(name)
+    filename = _DATASETS[name]
+    suffix = Path(filename).suffix
+    suffixes = Path(filename).suffixes
+
+    if as_format == "text":
+        if suffix == ".gz":
+            import gzip
+
+            return gzip.decompress(resource.read_bytes()).decode("utf-8")
+        return resource.read_text(encoding="utf-8")
+    is_json = suffix == ".json" or suffixes[-2:] == [".json", ".gz"]
+    if as_format == "json":
+        if not is_json:
+            raise ValueError(f"Dataset {name!r} is stored as {suffix}, not JSON.")
+        text = load_dataset(name, as_format="text")
+        return cast(dict[str, Any] | list[Any], json.loads(text))
+    if as_format == "dataframe":
+        return _load_dataframe(name)
+    if is_json:
+        return json.loads(load_dataset(name, as_format="text"))
+    if suffix in {".csv", ".tsv"} or suffixes[-2:] in (
+        [".csv", ".gz"],
+        [".tsv", ".gz"],
+        [".maf", ".gz"],
+    ):
+        return _load_dataframe(name)
+    raise ValueError(f"Unsupported dataset format for {name!r}: {suffix}.")