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

genome_spy/__init__.py

@@ -0,0 +1,199 @@
+"""Public package interface for genome_spy."""
+
+from genome_spy.arrow import to_arrow_ipc
+from genome_spy.data_transformers import data_transformers
+from genome_spy.api import (
+    Angle,
+    AxisGenomeData,
+    BrushConfig,
+    Color,
+    condition,
+    Direction,
+    ConcatChart,
+    Data,
+    DataFormat,
+    DynamicOpacity,
+    Dx,
+    Dy,
+    ExprRef,
+    Expression,
+    FacetIndex,
+    Fill,
+    FillOpacity,
+    GenomeAxis,
+    HandledTooltip,
+    HConcatChart,
+    ImportedView,
+    JupyterChart,
+    Key,
+    LayerChart,
+    Legend,
+    Locus,
+    MultiscaleChart,
+    Opacity,
+    Parameter,
+    Paddings,
+    Parse,
+    RulerMarkConfig,
+    Sample,
+    Scale,
+    Search,
+    SelectionDomainRef,
+    SemanticScore,
+    Shape,
+    Size,
+    SizeDef,
+    Step,
+    Stroke,
+    StrokeOpacity,
+    StrokeWidth,
+    Text,
+    Tooltip,
+    TopLevelSpec,
+    Title,
+    UniqueId,
+    VConcatChart,
+    X,
+    X2,
+    XOffset,
+    Y,
+    Y2,
+    YOffset,
+    Chart,
+    axes,
+    config,
+    compare,
+    concat,
+    data_format,
+    datum,
+    dynamic_opacity,
+    expr,
+    hconcat,
+    import_view,
+    layer,
+    lazy,
+    locus,
+    multiscale,
+    parse,
+    scales,
+    step,
+    title,
+    value,
+    view,
+    view_config,
+    vconcat,
+    when,
+)
+
+# BEGIN GENERATED INTERACTION IMPORTS
+from genome_spy.helpers import (
+    binding,
+    binding_checkbox,
+    binding_radio,
+    binding_range,
+    binding_select,
+    param,
+    ruler,
+    selection_interval,
+    selection_point,
+)
+# END GENERATED INTERACTION IMPORTS
+
+__all__ = [
+    "data_transformers",
+    "__version__",
+    "Angle",
+    "AxisGenomeData",
+    "axes",
+    "BrushConfig",
+    "Chart",
+    "Color",
+    "condition",
+    "Direction",
+    "compare",
+    "ConcatChart",
+    "Data",
+    "DataFormat",
+    "DynamicOpacity",
+    "Dx",
+    "Dy",
+    "ExprRef",
+    "Expression",
+    "FacetIndex",
+    "Fill",
+    "FillOpacity",
+    "GenomeAxis",
+    "HandledTooltip",
+    "HConcatChart",
+    "ImportedView",
+    "JupyterChart",
+    "Key",
+    "LayerChart",
+    "Legend",
+    "Locus",
+    "MultiscaleChart",
+    "Opacity",
+    "Parameter",
+    "Paddings",
+    "Parse",
+    "Sample",
+    "Scale",
+    "Search",
+    "SelectionDomainRef",
+    "SemanticScore",
+    "Shape",
+    "Size",
+    "SizeDef",
+    "Step",
+    "Stroke",
+    "StrokeOpacity",
+    "StrokeWidth",
+    "Text",
+    "Tooltip",
+    "TopLevelSpec",
+    "to_arrow_ipc",
+    "Title",
+    "UniqueId",
+    "VConcatChart",
+    "X",
+    "X2",
+    "XOffset",
+    "Y",
+    "Y2",
+    "YOffset",
+    "concat",
+    "config",
+    "data_format",
+    "datum",
+    "dynamic_opacity",
+    "expr",
+    "hconcat",
+    "import_view",
+    "layer",
+    "lazy",
+    "locus",
+    "multiscale",
+    "parse",
+    "RulerMarkConfig",
+    "scales",
+    "step",
+    "title",
+    "value",
+    "view",
+    "view_config",
+    "vconcat",
+    "when",
+    # BEGIN GENERATED INTERACTION EXPORTS
+    "binding",
+    "binding_checkbox",
+    "binding_radio",
+    "binding_range",
+    "binding_select",
+    "param",
+    "ruler",
+    "selection_interval",
+    "selection_point",
+    # END GENERATED INTERACTION EXPORTS
+]
+
+__version__ = "0.1.0"

genome_spy/_chart_authoring.py

@@ -0,0 +1,231 @@
+"""Authoring-edge normalization helpers for the handwritten chart API."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from datetime import date, datetime
+from typing import Any, cast
+
+from genome_spy._utils import is_mapping
+from genome_spy.arrow import _is_pandas_frame, _is_polars_frame, _is_pyarrow_table
+from genome_spy.channels import Channel, channel
+from genome_spy.schemapi import (
+    SchemaBase,
+    Undefined,
+    normalize_mapping_value,
+    normalize_schema_value,
+)
+
+
+def normalize_data(data: Any) -> Any:
+    """Normalize Python-side data inputs into schema-compatible values."""
+    if data is None:
+        return None
+    if isinstance(data, SchemaBase):
+        return json_safe(data.to_dict(validate=False))
+    if is_mapping(data):
+        return cast(
+            dict[str, Any], json_safe(normalize_schema_value(data, validate=False))
+        )
+    records = records_from_data(data)
+    if records is not None:
+        return records_data(records)
+    raise TypeError(f"Unsupported data value: {type(data)!r}")
+
+
+def json_safe(value: Any) -> Any:
+    """Convert authoring-edge values into JSON-safe primitives."""
+    if value is None:
+        return None
+    if isinstance(value, float) and not math.isfinite(value):
+        return None
+    if isinstance(value, datetime | date):
+        return value.isoformat()
+    if not isinstance(value, str | bytes) and hasattr(value, "item"):
+        try:
+            item = value.item()
+        except (AttributeError, TypeError, ValueError):
+            item = value
+        if item is not value:
+            return json_safe(item)
+    if isinstance(value, list):
+        return [json_safe(item) for item in value]
+    if is_mapping(value):
+        return {key: json_safe(item) for key, item in value.items()}
+    return value
+
+
+def records_from_data(data: Any) -> list[dict[str, Any]] | None:
+    """Extract record-like rows from common Python table inputs."""
+    if isinstance(data, list):
+        return data
+    if _is_pyarrow_table(data):
+        records = data.to_pylist()
+        return records if isinstance(records, list) else None
+    if hasattr(data, "to_dicts"):
+        records = data.to_dicts()
+        if isinstance(records, list):
+            return records
+        return None
+    if is_mapping(data):
+        values = data.get("values")
+        if isinstance(values, list):
+            return values
+        return None
+    if hasattr(data, "to_dict"):
+        try:
+            records = data.to_dict(orient="records")
+        except TypeError:
+            return None
+        if isinstance(records, list):
+            return records
+    return None
+
+
+def records_data(records: list[dict[str, Any]]) -> dict[str, Any]:
+    """Wrap record rows as inline schema data."""
+    return {"values": json_safe(records)}
+
+
+def infer_field_type(field: str, data: Any) -> str | None:
+    """Infer a GenomeSpy encoding type from up to the first 100 records."""
+    table_type = infer_table_field_type(field, data)
+    if table_type is not None:
+        return table_type
+    if _is_polars_frame(data) or _is_pandas_frame(data) or _is_pyarrow_table(data):
+        return None
+
+    records = records_from_data(data)
+    if not records:
+        return None
+
+    for row in records[:100]:
+        if not is_mapping(row) or field not in row:
+            continue
+        inferred_type = infer_value_type(row[field])
+        if inferred_type is not None:
+            return inferred_type
+    return None
+
+
+def infer_table_field_type(field: str, data: Any) -> str | None:
+    """Infer a field type from supported table dtype metadata without rows."""
+    if _is_polars_frame(data):
+        dtype = getattr(data, "schema", {}).get(field)
+        if dtype is None:
+            return None
+        is_numeric = getattr(dtype, "is_numeric", None)
+        return "quantitative" if callable(is_numeric) and is_numeric() else "nominal"
+
+    if _is_pandas_frame(data):
+        dtypes = getattr(data, "dtypes", None)
+        if dtypes is None:
+            return None
+        try:
+            dtype = dtypes[field]
+        except (KeyError, TypeError):
+            return None
+        return "quantitative" if getattr(dtype, "kind", "") in "iufc" else "nominal"
+
+    if _is_pyarrow_table(data):
+        schema = getattr(data, "schema", None)
+        if schema is None:
+            return None
+        try:
+            arrow_type = schema.field(field).type
+        except (KeyError, TypeError, AttributeError):
+            return None
+        return (
+            "quantitative"
+            if str(arrow_type).startswith(("int", "uint", "float", "double", "decimal"))
+            else "nominal"
+        )
+
+    return None
+
+
+def infer_value_type(value: Any) -> str | None:
+    """Infer a GenomeSpy encoding type for one Python value."""
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return "nominal"
+    if isinstance(value, int | float):
+        return "quantitative"
+    return "nominal"
+
+
+def normalize_channel(
+    name: str,
+    value: Channel
+    | SchemaBase
+    | str
+    | dict[str, Any]
+    | Sequence[Channel | SchemaBase | str | dict[str, Any]]
+    | None,
+    *,
+    data: Any = None,
+) -> dict[str, Any] | list[dict[str, Any]] | None:
+    """Normalize one chart encoding channel definition."""
+    if value is None:
+        return None
+    if isinstance(value, Sequence) and not isinstance(value, str | bytes):
+        return [channel(item, encoding_name=name).to_dict() for item in value]
+    definition = channel(value).to_dict()
+    return normalized_channel_definition(name, definition, data=data)
+
+
+def normalized_channel_definition(
+    name: str,
+    definition: dict[str, Any],
+    *,
+    data: Any = None,
+) -> dict[str, Any]:
+    """Normalize one mapping-form channel definition."""
+    normalized = dict(definition)
+    if name in {"x2", "y2", "key"}:
+        normalized.pop("type", None)
+    elif "type" not in normalized and isinstance(normalized.get("field"), str):
+        inferred_type = infer_field_type(normalized["field"], data)
+        if inferred_type is not None:
+            normalized["type"] = inferred_type
+    return normalized
+
+
+def merge_encoding_definitions(
+    current_encoding: Any,
+    updates: dict[
+        str,
+        Channel
+        | SchemaBase
+        | str
+        | dict[str, Any]
+        | Sequence[Channel | SchemaBase | str | dict[str, Any]]
+        | None,
+    ],
+    *,
+    data: Any,
+) -> dict[str, Any]:
+    """Merge and normalize chart encoding updates."""
+    merged = {} if current_encoding is Undefined else dict(current_encoding)
+    for name, value in updates.items():
+        merged[name] = normalize_channel(name, value, data=data)
+    return merged
+
+
+def normalize_transform(transform: SchemaBase | dict[str, Any]) -> dict[str, Any]:
+    """Normalize one transform definition."""
+    try:
+        return normalize_mapping_value(transform, key="transform", validate=False)
+    except TypeError as error:
+        raise TypeError(f"Unsupported transform value: {type(transform)!r}") from error
+
+
+def normalize_transform_kwarg(
+    value: SchemaBase | dict[str, Any],
+    *,
+    key: str,
+) -> dict[str, Any]:
+    """Normalize one nested transform keyword value."""
+    return normalize_mapping_value(value, key=key, validate=False)

genome_spy/_conditions.py

@@ -0,0 +1,72 @@
+"""Altair-style conditional encoding authoring."""
+
+from __future__ import annotations
+
+from typing import TypeAlias
+
+from genome_spy._parameters import Parameter
+from genome_spy.channels import Channel, channel
+from genome_spy.schemapi import SchemaBase
+
+ConditionValue: TypeAlias = Channel | SchemaBase | str | dict[str, object]
+
+
+def _branch_definition(value: ConditionValue) -> dict[str, object]:
+    return channel(value).to_dict()
+
+
+class _Then(Channel):
+    """A conditional channel awaiting an optional fallback branch."""
+
+    def otherwise(self, value: ConditionValue) -> Channel:
+        """Return the conditional channel with its fallback branch."""
+        return Channel({**_branch_definition(value), **self.to_dict()})
+
+
+class _When:
+    """A validated parameter predicate awaiting its true branch."""
+
+    def __init__(self, predicate: Parameter) -> None:
+        self._predicate = predicate
+
+    def then(self, value: ConditionValue) -> _Then:
+        """Return a conditional channel using ``value`` when selected."""
+        condition = {
+            "param": self._predicate.name,
+            "empty": self._predicate.empty,
+            **_branch_definition(value),
+        }
+        return _Then({"condition": condition})
+
+
+def when(predicate: Parameter) -> _When:
+    """Start an Altair-style selection condition.
+
+    GenomeSpy 0.86 supports selection parameters as conditional predicates.
+    Expression predicates will become available only if the upstream schema
+    adds that grammar.
+
+    Args:
+        predicate: A point or interval selection parameter.
+
+    Returns:
+        A builder whose ``then()`` method defines the selected branch.
+
+    Raises:
+        TypeError: If ``predicate`` is not a selection parameter.
+
+    Example:
+        >>> import genome_spy as gs
+        >>> brush = gs.selection_interval(encodings=["x"])
+        >>> condition = gs.when(brush).then(gs.value("red")).otherwise(
+        ...     gs.value("gray")
+        ... )
+        >>> condition.to_dict()["condition"]["param"] == brush.name
+        True
+    """
+    if not isinstance(predicate, Parameter) or not predicate.is_selection:
+        raise TypeError("when() currently requires a selection parameter.")
+    return _When(predicate)
+
+
+__all__ = ["when"]

genome_spy/_embed.py

@@ -0,0 +1,87 @@
+"""Shared rendering configuration for GenomeSpy browser embeds."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Literal, TypeAlias
+
+from genome_spy.schema import SCHEMA_VERSION
+from genome_spy.schemapi import Undefined, UndefinedType
+
+ControlName: TypeAlias = Literal["svg", "png", "inspector", "full-window"]
+Controls: TypeAlias = bool | ControlName | Sequence[ControlName]
+
+_CONTROL_DEFINITIONS: dict[ControlName, tuple[str, str]] = {
+    "svg": ("core", "svgButton"),
+    "png": ("core", "pngButton"),
+    "inspector": ("inspector", "inspectorButton"),
+    "full-window": ("core", "fullWindowButton"),
+}
+DEFAULT_CONTROLS: tuple[ControlName, ...] = ("svg", "png", "inspector")
+SUPPORTED_CONTROLS: tuple[ControlName, ...] = tuple(_CONTROL_DEFINITIONS)
+
+_CORE_PACKAGE_URL = (
+    f"https://cdn.jsdelivr.net/npm/@genome-spy/core@{SCHEMA_VERSION}/dist"
+)
+DEFAULT_EMBED_URL = f"{_CORE_PACKAGE_URL}/bundle/index.es.js"
+DEFAULT_CONTROLS_MODULE_URL = f"{_CORE_PACKAGE_URL}/src/controls.js"
+DEFAULT_INSPECTOR_MODULE_URL = (
+    "https://cdn.jsdelivr.net/npm/"
+    f"@genome-spy/inspector@{SCHEMA_VERSION}/dist/index.es.js"
+)
+
+
+def normalize_controls(
+    controls: Controls | UndefinedType = Undefined,
+) -> tuple[ControlName, ...]:
+    """Return validated control names in display order."""
+    if controls is Undefined or controls is True:
+        return DEFAULT_CONTROLS
+    if controls is False:
+        return ()
+
+    values: Sequence[str]
+    if isinstance(controls, str):
+        values = (controls,)
+    elif isinstance(controls, Sequence):
+        values = controls
+    else:
+        raise TypeError(
+            "controls must be a boolean, a control name, or a sequence of "
+            "control names."
+        )
+
+    normalized: list[ControlName] = []
+    seen: set[str] = set()
+    for value in values:
+        if not isinstance(value, str):
+            raise TypeError("Every control name must be a string.")
+        if value not in SUPPORTED_CONTROLS:
+            expected = ", ".join(repr(name) for name in SUPPORTED_CONTROLS)
+            raise ValueError(
+                f"Unknown GenomeSpy control {value!r}. Expected one of: {expected}."
+            )
+        if value in seen:
+            raise ValueError(f"GenomeSpy control {value!r} was specified twice.")
+        seen.add(value)
+        normalized.append(value)
+    return tuple(normalized)
+
+
+def control_definitions() -> dict[str, dict[str, str]]:
+    """Return browser module and export metadata for supported controls."""
+    return {
+        name: {"module": module, "export": export}
+        for name, (module, export) in _CONTROL_DEFINITIONS.items()
+    }
+
+
+__all__ = [
+    "ControlName",
+    "Controls",
+    "DEFAULT_CONTROLS",
+    "DEFAULT_CONTROLS_MODULE_URL",
+    "DEFAULT_EMBED_URL",
+    "DEFAULT_INSPECTOR_MODULE_URL",
+    "SUPPORTED_CONTROLS",
+]