reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/protocols/semantic_coverage.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+from typing import Any
+
+from reader_workbench.protocols.model import ProtocolSemanticExecution, ProtocolSemanticProgram
+
+
+def _semantic_program(
+    protocol: Any,
+    *,
+    overrides: dict[str, ProtocolSemanticExecution],
+    active_profile: str | None = None,
+) -> ProtocolSemanticProgram:
+    return protocol.semantic_program(active_profile=active_profile, execution_overrides=overrides)
+
+
+def _plate_reader_semantic_program(
+    protocol: Any,
+    *,
+    include_crosstalk_pairs: bool,
+    include_fold_change: bool,
+) -> ProtocolSemanticProgram:
+    active_profile = _dual_reporter_semantic_profile(
+        include_fold_change=include_fold_change,
+        include_crosstalk_pairs=include_crosstalk_pairs,
+    )
+    overrides: dict[str, ProtocolSemanticExecution] = {
+        "OD": ProtocolSemanticExecution(
+            status="compiled",
+            step_ids=("ingest",),
+            plugin_ids=("ingest/synergy_h1",),
+            record_ids=("ingest/df",),
+            note="Raw OD600 values are materialized on the ingest dataframe.",
+        ),
+    }
+    overrides.update(
+        {
+            "CFP": ProtocolSemanticExecution(
+                status="compiled",
+                step_ids=("ingest",),
+                plugin_ids=("ingest/synergy_h1",),
+                record_ids=("ingest/df",),
+                note="Raw CFP values are materialized on the ingest dataframe.",
+            ),
+            "YFP": ProtocolSemanticExecution(
+                status="compiled",
+                step_ids=("ingest",),
+                plugin_ids=("ingest/synergy_h1",),
+                record_ids=("ingest/df",),
+                note="Raw YFP values are materialized on the ingest dataframe.",
+            ),
+            "CFP_OD": ProtocolSemanticExecution(
+                status="compiled",
+                step_ids=("ratio_cfp_od600",),
+                plugin_ids=("transform/ratio",),
+                record_ids=("ratio_cfp_od600/df",),
+                note="The CFP/OD600 support channel is materialized as a ratio step output.",
+            ),
+            "YFP_OD": ProtocolSemanticExecution(
+                status="compiled",
+                step_ids=("ratio_yfp_od600",),
+                plugin_ids=("transform/ratio",),
+                record_ids=("ratio_yfp_od600/df",),
+                note="The YFP/OD600 support channel is materialized as a ratio step output.",
+            ),
+            "Ratio": ProtocolSemanticExecution(
+                status="compiled",
+                step_ids=("ratio_yfp_cfp",),
+                plugin_ids=("transform/ratio",),
+                record_ids=("ratio_yfp_cfp/df",),
+                note="The primary YFP/CFP ratio is materialized as a ratio step output.",
+            ),
+        }
+    )
+    if include_fold_change:
+        fold_change_step_id = "fold_change__yfp_over_cfp"
+        fold_change_record_id = "fold_change__yfp_over_cfp/table"
+        fold_change_note = "Nearest-time fold-change summaries are materialized from the primary ratio channel."
+        overrides.update(
+            {
+                "FC": ProtocolSemanticExecution(
+                    status="compiled",
+                    step_ids=(fold_change_step_id,),
+                    plugin_ids=("transform/fold_change",),
+                    record_ids=(fold_change_record_id,),
+                    note=fold_change_note,
+                ),
+                "log2FC": ProtocolSemanticExecution(
+                    status="compiled",
+                    step_ids=(fold_change_step_id,),
+                    plugin_ids=("transform/fold_change",),
+                    record_ids=(fold_change_record_id,),
+                    note=fold_change_note,
+                ),
+            }
+        )
+    if include_crosstalk_pairs:
+        overrides["ranking"] = ProtocolSemanticExecution(
+            status="compiled",
+            step_ids=("crosstalk_pairs",),
+            plugin_ids=("transform/crosstalk_pairs",),
+            record_ids=("crosstalk_pairs/table",),
+            config_paths=("protocol.analysis.crosstalk_pairs",),
+            note="When crosstalk pair analysis is enabled, pair selection is compiled from fold-change output.",
+        )
+    return _semantic_program(protocol, overrides=overrides, active_profile=active_profile)
+
+
+def _plate_reader_single_reporter_semantic_program(
+    protocol: Any,
+    *,
+    reporter_channel: str,
+    normalizer_channel: str,
+    include_fold_change: bool,
+) -> ProtocolSemanticProgram:
+    ratio_label = _single_reporter_ratio_label(
+        reporter_channel=reporter_channel,
+        normalizer_channel=normalizer_channel,
+    )
+    ratio_note = f"The primary {ratio_label} ratio is materialized as a ratio step output."
+    fold_change_note = f"Nearest-time fold-change summaries are materialized from the primary {ratio_label} channel."
+    overrides: dict[str, ProtocolSemanticExecution] = {
+        "Normalizer": ProtocolSemanticExecution(
+            status="compiled",
+            step_ids=("ingest",),
+            plugin_ids=("ingest/synergy_h1",),
+            record_ids=("ingest/df",),
+            note=f"Raw {normalizer_channel} values are materialized on the ingest dataframe.",
+        ),
+        "Reporter": ProtocolSemanticExecution(
+            status="compiled",
+            step_ids=("ingest",),
+            plugin_ids=("ingest/synergy_h1",),
+            record_ids=("ingest/df",),
+            note=f"Raw {reporter_channel} values are materialized on the ingest dataframe.",
+        ),
+        "Reporter_Normalizer": ProtocolSemanticExecution(
+            status="compiled",
+            step_ids=("ratio_reporter_normalizer",),
+            plugin_ids=("transform/ratio",),
+            record_ids=("ratio_reporter_normalizer/df",),
+            note=ratio_note,
+        ),
+    }
+    if include_fold_change:
+        overrides.update(
+            {
+                "FC": ProtocolSemanticExecution(
+                    status="compiled",
+                    step_ids=("fold_change__single_reporter",),
+                    plugin_ids=("transform/fold_change",),
+                    record_ids=("fold_change__single_reporter/table",),
+                    note=fold_change_note,
+                ),
+                "log2FC": ProtocolSemanticExecution(
+                    status="compiled",
+                    step_ids=("fold_change__single_reporter",),
+                    plugin_ids=("transform/fold_change",),
+                    record_ids=("fold_change__single_reporter/table",),
+                    note=fold_change_note,
+                ),
+            }
+        )
+    return _semantic_program(
+        protocol, overrides=overrides, active_profile=_single_reporter_semantic_profile(include_fold_change)
+    )
+
+
+def _plate_reader_growth_semantic_program(
+    protocol: Any,
+    *,
+    growth_channel: str,
+) -> ProtocolSemanticProgram:
+    return _semantic_program(
+        protocol,
+        overrides={
+            "Growth": ProtocolSemanticExecution(
+                status="compiled",
+                step_ids=("ingest",),
+                plugin_ids=("ingest/synergy_h1",),
+                record_ids=("ingest/df",),
+                note=f"Raw {growth_channel} values are materialized on the ingest dataframe.",
+            )
+        },
+        active_profile="growth_raw",
+    )
+
+
+def _logic_semantic_program(protocol: Any, *, include_four_state_vector: bool) -> ProtocolSemanticProgram:
+    overrides: dict[str, ProtocolSemanticExecution] = {}
+    if include_four_state_vector:
+        vector_binding = ProtocolSemanticExecution(
+            status="compiled",
+            step_ids=("four_state_vector",),
+            plugin_ids=("transform/four_state_vector",),
+            record_ids=("four_state_vector/vector",),
+            config_paths=(
+                "protocol.inputs.reference",
+                "protocol.inputs.design_by",
+                "protocol.inputs.state_map_ref",
+                "protocol.inputs.time_mode",
+                "protocol.inputs.target_time_h",
+                "protocol.inputs.time_tolerance_h",
+            ),
+            note="The four-state vector transform materializes the protocol control rule, summary window, and measurement vector.",
+        )
+        overrides.update(
+            {
+                "logic_corner_map": vector_binding,
+                "summary_timepoint": vector_binding,
+                "four_state_vector": vector_binding,
+            }
+        )
+    return _semantic_program(protocol, overrides=overrides)
+
+
+def _cytometry_semantic_program(protocol: Any) -> ProtocolSemanticProgram:
+    return _semantic_program(protocol, overrides={})
+
+
+def _dual_reporter_semantic_profile(*, include_fold_change: bool, include_crosstalk_pairs: bool) -> str:
+    if include_crosstalk_pairs:
+        return "yfp_cfp_crosstalk"
+    if include_fold_change:
+        return "yfp_cfp_fold_change"
+    return "yfp_cfp_raw"
+
+
+def _single_reporter_semantic_profile(include_fold_change: bool) -> str:
+    return "single_reporter_fold_change" if include_fold_change else "single_reporter_raw"
+
+
+def _single_reporter_ratio_label(*, reporter_channel: str, normalizer_channel: str) -> str:
+    return f"{reporter_channel}/{normalizer_channel}"

reader_workbench/runtime/__init__.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from importlib import import_module
+
+from .model import ReaderRuntime
+
+
+def builtin_runtime() -> ReaderRuntime:
+    return import_module("reader_workbench.runtime.builtin").builtin_runtime()
+
+
+__all__ = ["ReaderRuntime", "builtin_runtime"]

reader_workbench/runtime/builtin.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from functools import cache
+
+from reader_workbench.contracts import builtin_contract_catalog
+from reader_workbench.plotting.mpl import ensure_mpl_cache_dir
+from reader_workbench.plugins.catalog import builtin_plugin_descriptors
+from reader_workbench.protocols.builtins import builtin_protocol_catalog
+from reader_workbench.workbench.registry import load_plugin_catalog
+
+from .model import ReaderRuntime
+
+
+@cache
+def builtin_runtime() -> ReaderRuntime:
+    ensure_mpl_cache_dir()
+    contracts = builtin_contract_catalog()
+    protocols = builtin_protocol_catalog()
+    plugins = load_plugin_catalog(
+        contracts=contracts,
+        builtin_descriptors=builtin_plugin_descriptors(),
+    )
+    return ReaderRuntime(contracts=contracts, protocols=protocols, plugins=plugins)

reader_workbench/runtime/model.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import import_module
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from reader_workbench.contracts import ContractCatalog
+    from reader_workbench.protocols.model import BoundProtocol, ProtocolBinding, ProtocolCatalog
+    from reader_workbench.workbench.records.store import RecordStore
+    from reader_workbench.workbench.registry import Registry
+
+
+@dataclass(frozen=True)
+class ReaderRuntime:
+    """Single composed runtime for contracts, protocols, plugins, and record stores."""
+
+    contracts: ContractCatalog
+    protocols: ProtocolCatalog
+    plugins: Registry
+
+    def bind_protocol(self, binding: ProtocolBinding) -> BoundProtocol:
+        return self.protocols.bind(binding)
+
+    def record_store(
+        self,
+        outputs_dir: Path,
+        *,
+        plots_subdir: str | None = "plots",
+        exports_subdir: str | None = "exports",
+        experiment_root: Path | None = None,
+        create: bool = True,
+    ) -> RecordStore:
+        return import_module("reader_workbench.workbench.records.store").RecordStore(
+            outputs_dir,
+            contracts=self.contracts,
+            plots_subdir=plots_subdir,
+            exports_subdir=exports_subdir,
+            experiment_root=experiment_root,
+            create=create,
+        )

reader_workbench/workbench/__init__.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import importlib
+
+_EXPORTS = {
+    "graph": {
+        "FileRef",
+        "InputRef",
+        "OutputRef",
+        "PluginStep",
+        "ProvenanceInput",
+        "RecipeSource",
+        "RecordRef",
+        "ResourceRef",
+        "Workbench",
+        "ensure_unique_workbench_ids",
+        "input_ref_display",
+        "input_ref_from_dict",
+        "input_ref_to_dict",
+        "materialize_workbench",
+        "output_ref_display",
+        "output_ref_from_dict",
+        "output_ref_to_dict",
+        "provenance_input_from_dict",
+        "provenance_input_to_dict",
+        "resolve_workbench",
+        "select_workbench_specs",
+    },
+    "ontology": {
+        "PluginCategory",
+        "PluginSemantics",
+        "WorkbenchItemKind",
+        "WorkbenchPluginStepKind",
+        "WorkbenchProducerKind",
+        "WorkbenchRecordKind",
+        "WorkbenchSurfaceSemantics",
+        "get_workbench_surface_semantics",
+    },
+    "records": {
+        "DataFrameArtifactRecord",
+        "FileBundleRecord",
+        "RecordProducer",
+        "RecordRecipeSource",
+        "RecordStore",
+        "WorkbenchRecord",
+        "record_from_dict",
+        "record_paths",
+        "record_to_dict",
+    },
+}
+
+__all__ = tuple(sorted({name for names in _EXPORTS.values() for name in names}))
+
+
+def __getattr__(name: str):
+    for module_name, names in _EXPORTS.items():
+        if name in names:
+            module = importlib.import_module(f"reader_workbench.workbench.{module_name}")
+            return getattr(module, name)
+    raise AttributeError(name)

reader_workbench/workbench/assets/__init__.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import importlib
+
+_EXPORTS = {
+    "types": {
+        "AssetCatalog",
+        "AssetDescriptor",
+        "build_plugin_asset",
+        "plugin_category_from_id",
+    },
+}
+
+__all__ = tuple(sorted({name for names in _EXPORTS.values() for name in names}))
+
+
+def __getattr__(name: str):
+    for module_name, names in _EXPORTS.items():
+        if name in names:
+            module = importlib.import_module(f"reader_workbench.workbench.assets.{module_name}")
+            return getattr(module, name)
+    raise AttributeError(name)

reader_workbench/workbench/assets/types.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, cast
+
+from reader_workbench.errors import ConfigError
+from reader_workbench.workbench.ontology import (
+    PluginCategory,
+    PluginDomain,
+    PluginSemantics,
+    validate_plugin_domain,
+)
+
+
+@dataclass(frozen=True)
+class AssetDescriptor:
+    name: str
+    domain: PluginDomain
+    family: str
+    summary: str
+    plugin_cls: type[Any]
+    tags: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "domain", validate_plugin_domain(self.domain))
+        if not isinstance(self.name, str) or not self.name.strip():
+            raise ValueError("AssetDescriptor.name must be a non-empty string.")
+        plugin_category_from_id(self.name)
+        if not isinstance(self.plugin_cls, type):
+            raise ValueError(f"Plugin asset {self.name!r} must declare a plugin class.")
+
+    @property
+    def plugin(self) -> str:
+        return self.name
+
+    @property
+    def plugin_id(self) -> str:
+        return self.plugin
+
+    @property
+    def key(self) -> str:
+        return self.name.split("/", 1)[1] if "/" in self.name else self.name
+
+    @property
+    def category(self) -> PluginCategory:
+        return plugin_category_from_id(self.name)
+
+    @property
+    def cls(self) -> type[Any]:
+        return self.plugin_cls
+
+
+class AssetCatalog:
+    def __init__(self, descriptors: list[AssetDescriptor]):
+        self._descriptors = tuple(sorted(descriptors, key=lambda item: (item.domain, item.family, item.name)))
+        by_name: dict[str, AssetDescriptor] = {}
+        for item in self._descriptors:
+            if item.name in by_name:
+                raise ConfigError(f"Duplicate plugin {item.name!r}.")
+            by_name[item.name] = item
+        self._by_name = by_name
+
+    def all(self) -> tuple[AssetDescriptor, ...]:
+        return self._descriptors
+
+    def filter(
+        self,
+        *,
+        category: str | None = None,
+        domain: str | None = None,
+        family: str | None = None,
+        tag: str | None = None,
+    ) -> tuple[AssetDescriptor, ...]:
+        return tuple(
+            descriptor
+            for descriptor in self._descriptors
+            if (category is None or descriptor.category == category)
+            and (domain is None or descriptor.domain == domain)
+            and (family is None or descriptor.family == family)
+            and (tag is None or tag in descriptor.tags)
+        )
+
+    def resolve(self, name: str) -> AssetDescriptor:
+        try:
+            return self._by_name[name]
+        except KeyError:
+            opts = ", ".join(sorted(item.name for item in self._descriptors))
+            raise ConfigError(f"Unknown plugin {name!r}. Available plugins: {opts}") from None
+
+    def list(
+        self,
+        *,
+        domain: str | None = None,
+        family: str | None = None,
+    ) -> list[tuple[str, str]]:
+        items = self.filter(domain=domain, family=family)
+        return [(item.name, item.summary) for item in items]
+
+
+def plugin_category_from_id(plugin_id: str) -> PluginCategory:
+    if not isinstance(plugin_id, str) or "/" not in plugin_id:
+        raise ValueError(f"Plugin id must be 'category/key', got {plugin_id!r}")
+    category = plugin_id.split("/", 1)[0]
+    if category not in {"ingest", "transform", "plot", "export", "validator"}:
+        raise ValueError(f"Unknown plugin category {category!r} in plugin id {plugin_id!r}")
+    return cast(PluginCategory, category)
+
+
+def build_plugin_asset(*, plugin_id: str, semantics: PluginSemantics, plugin_cls: type[Any]) -> AssetDescriptor:
+    plugin_category_from_id(plugin_id)
+    return AssetDescriptor(
+        name=plugin_id,
+        domain=semantics.domain,
+        family=semantics.family,
+        summary=semantics.summary,
+        plugin_cls=plugin_cls,
+        tags=tuple(semantics.tags),
+    )

reader_workbench/workbench/audit/__init__.py

@@ -0,0 +1,5 @@
+"""Operator audits for experiment workbenches."""
+
+from .experiments import AuditResult, audit_experiments
+
+__all__ = ["AuditResult", "audit_experiments"]