reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/protocols/compiler.py

@@ -0,0 +1,22 @@
+"""Public compiler entry points, organized internally by assay family."""
+
+from .compilers.cytometry import compile_cytometry_flow_panel
+from .compilers.generic import compile_generic_protocol
+from .compilers.logic import compile_logic_four_state_vector_collection, compile_logic_four_state_vector_screen
+from .compilers.plate_reader import (
+    compile_plate_reader_dual_reporter_screen,
+    compile_plate_reader_four_state_event_window,
+    compile_plate_reader_growth_screen,
+    compile_plate_reader_single_reporter_screen,
+)
+
+__all__ = [
+    "compile_cytometry_flow_panel",
+    "compile_generic_protocol",
+    "compile_logic_four_state_vector_screen",
+    "compile_logic_four_state_vector_collection",
+    "compile_plate_reader_dual_reporter_screen",
+    "compile_plate_reader_four_state_event_window",
+    "compile_plate_reader_growth_screen",
+    "compile_plate_reader_single_reporter_screen",
+]

reader_workbench/protocols/compilers/__init__.py

@@ -0,0 +1 @@
+"""Assay-owned protocol compiler implementations."""

reader_workbench/protocols/compilers/common.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+from reader_workbench.errors import ConfigError
+from reader_workbench.workbench.decl.model import (
+    PluginStepDecl,
+    RecipeSourceDecl,
+)
+
+
+def _analysis_options(protocol: Any) -> dict[str, Any]:
+    raw = getattr(protocol, "analysis", {}) or {}
+    if not isinstance(raw, dict):
+        raise ConfigError(f"protocol.analysis for {protocol.id!r} must be a mapping")
+    return dict(raw)
+
+
+def _analysis_mapping(raw: dict[str, Any], *, key: str) -> dict[str, Any]:
+    value = raw.get(key, {})
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ConfigError(f"protocol.analysis.{key} must be a mapping")
+    return dict(value)
+
+
+def _analysis_bool(raw: dict[str, Any], *, key: str, default: bool) -> bool:
+    value = raw.get(key, default)
+    if isinstance(value, bool):
+        return value
+    raise ConfigError(f"protocol.analysis.{key} must be true or false")
+
+
+def _analysis_choice(raw: dict[str, Any], *, key: str, default: str, allowed: set[str]) -> str:
+    value = raw.get(key, default)
+    if not isinstance(value, str) or value not in allowed:
+        options = ", ".join(sorted(allowed))
+        raise ConfigError(f"protocol.analysis.{key} must be one of: {options}")
+    return value
+
+
+def _analysis_channel(raw: dict[str, Any], *, key: str, default: str) -> str:
+    value = raw.get(key, default)
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigError(f"protocol.analysis.{key} must be a non-empty string")
+    return value.strip()
+
+
+def _input_mapping(protocol: Any, *, key: str) -> dict[str, Any]:
+    raw = getattr(protocol, "inputs", {}) or {}
+    if not isinstance(raw, dict):
+        raise ConfigError(f"protocol.inputs for {protocol.id!r} must be a mapping")
+    value = raw.get(key, {})
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ConfigError(f"protocol.inputs.{key} for {protocol.id!r} must be a mapping")
+    return dict(value)
+
+
+def _config_bool(raw: dict[str, Any], *, key: str, default: bool) -> bool:
+    value = raw.get(key, default)
+    if isinstance(value, bool):
+        return value
+    raise ConfigError(f"{key} must be true or false")
+
+
+def _deep_merge(*mappings: dict[str, Any]) -> dict[str, Any]:
+    merged: dict[str, Any] = {}
+    for mapping in mappings:
+        for key, value in (mapping or {}).items():
+            if key in merged and isinstance(merged[key], dict) and isinstance(value, dict):
+                merged[key] = _deep_merge(merged[key], value)
+                continue
+            merged[key] = deepcopy(value)
+    return merged
+
+
+def _step(
+    *,
+    id: str,
+    plugin: str,
+    reads: dict[str, Any] | None = None,
+    writes: dict[str, Any] | None = None,
+    with_: dict[str, Any] | None = None,
+    source_recipe: str | None = None,
+    source_recipe_with: dict[str, Any] | None = None,
+) -> PluginStepDecl:
+    return PluginStepDecl(
+        id=id,
+        plugin=plugin,
+        reads=dict(reads or {}),
+        writes=dict(writes or {}),
+        with_=dict(with_ or {}),
+        source_recipe=(
+            RecipeSourceDecl(recipe=source_recipe, with_=dict(source_recipe_with or {})) if source_recipe else None
+        ),
+    )

reader_workbench/protocols/compilers/cytometry.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from typing import Any
+
+from reader_workbench.protocols.model import CompiledProtocolPlan
+from reader_workbench.protocols.semantic_coverage import _cytometry_semantic_program
+from reader_workbench.workbench.decl.model import RecordInputDecl, RecordOutputDecl, ResourceInputDecl
+
+from .common import _deep_merge, _step
+
+CYTOMETRY_PLOT_OUTPUTS = {"gating_diagnostic"}
+CYTOMETRY_EXPORT_OUTPUTS = {
+    "gate_definition_table": ("cytometry_gating/gate_definition", "cytometry_gate_definition.csv"),
+    "sample_stats_table": ("cytometry_gating/sample_stats", "cytometry_sample_stats.csv"),
+    "group_stats_table": ("cytometry_gating/group_stats", "cytometry_group_stats.csv"),
+    "qc_table": ("cytometry_gating/qc", "cytometry_qc.csv"),
+    "gated_events_table": ("cytometry_gating/gated_events", "cytometry_gated_events.csv"),
+}
+
+
+def compile_cytometry_flow_panel(protocol: Any):
+    selected_plots = protocol.select_plot_outputs(allowed=CYTOMETRY_PLOT_OUTPUTS)
+    selected_exports = protocol.select_export_outputs(
+        defaults=("gate_definition_table", "sample_stats_table", "group_stats_table", "qc_table"),
+        allowed=set(CYTOMETRY_EXPORT_OUTPUTS),
+    )
+    pipeline = (
+        _step(
+            id="ingest_cytometer",
+            plugin="ingest/flow_cytometer",
+            writes={"df": RecordOutputDecl(record_id="ingest/df")},
+        ),
+        _step(
+            id="merge_metadata",
+            plugin="transform/sample_metadata",
+            reads={
+                "df": RecordInputDecl(record_id="ingest/df"),
+                "metadata": ResourceInputDecl(resource_id="metadata"),
+            },
+            writes={"df": RecordOutputDecl(record_id="merged/df")},
+        ),
+        _step(
+            id="cytometry_gating",
+            plugin="transform/cytometry_gating",
+            reads={"events": RecordInputDecl(record_id="merged/df")},
+            writes={
+                "gate_definition": RecordOutputDecl(record_id="cytometry_gating/gate_definition"),
+                "gated_events": RecordOutputDecl(record_id="cytometry_gating/gated_events"),
+                "sample_stats": RecordOutputDecl(record_id="cytometry_gating/sample_stats"),
+                "group_stats": RecordOutputDecl(record_id="cytometry_gating/group_stats"),
+                "qc": RecordOutputDecl(record_id="cytometry_gating/qc"),
+            },
+        ),
+    )
+    plots = tuple(
+        _step(
+            id="gating_diagnostic",
+            plugin="plot/cytometry_diagnostic",
+            reads={
+                "original_events": RecordInputDecl(record_id="merged/df"),
+                "gate_definition": RecordInputDecl(record_id="cytometry_gating/gate_definition"),
+                "gated_events": RecordInputDecl(record_id="cytometry_gating/gated_events"),
+            },
+            with_=protocol.plot_view_config(figure_id="gating_diagnostic"),
+        )
+        for _ in selected_plots
+    )
+    exports = tuple(_cytometry_export_output(protocol, output_id=output_id) for output_id in selected_exports)
+    return CompiledProtocolPlan(
+        pipeline=pipeline,
+        plots=plots,
+        exports=exports,
+        semantic_program=_cytometry_semantic_program(protocol),
+    )
+
+
+def _cytometry_export_output(protocol: Any, *, output_id: str):
+    record_id, default_path = CYTOMETRY_EXPORT_OUTPUTS[output_id]
+    return _step(
+        id=output_id,
+        plugin="export/csv",
+        reads={"df": RecordInputDecl(record_id=record_id)},
+        with_=_deep_merge(
+            {"path": default_path},
+            protocol.export_artifact_config(artifact_id=output_id),
+        ),
+    )

reader_workbench/protocols/compilers/generic.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import Any
+
+from reader_workbench.protocols.model import CompiledProtocolPlan
+
+
+def compile_generic_protocol(protocol: Any):
+    return CompiledProtocolPlan(
+        pipeline=(),
+        plots=(),
+        exports=(),
+        semantic_program=protocol.descriptor.semantic_program(),
+    )

reader_workbench/protocols/compilers/logic.py

@@ -0,0 +1,245 @@
+from __future__ import annotations
+
+from typing import Any
+
+from reader_workbench.errors import ConfigError
+from reader_workbench.protocols.model import CompiledProtocolPlan
+from reader_workbench.protocols.semantic_coverage import _logic_semantic_program
+from reader_workbench.workbench.decl.model import (
+    PluginStepDecl,
+    RecordCollectionInputDecl,
+    RecordInputDecl,
+    RecordOutputDecl,
+)
+
+from .common import (
+    _analysis_bool,
+    _analysis_mapping,
+    _analysis_options,
+    _deep_merge,
+    _step,
+)
+from .plate_reader import (
+    _configured_fold_change_enabled,
+    _configured_fold_change_report_times,
+    _configured_fold_change_target,
+    _configured_ingest_channels,
+    _plate_reader_fold_change_step,
+    _plate_reader_plot_output,
+)
+from .plate_reader_pipeline import compose_dual_reporter_pipeline
+
+LOGIC_EXPORT_OUTPUTS = {"logic_summary_workbook"}
+FOUR_STATE_VECTOR_SCREEN_LOGIC_CHANNEL = "YFP/CFP"
+
+
+def compile_logic_four_state_vector_collection(protocol: Any):
+    resource_ids = tuple(protocol.effective_inputs().get("record_resources", ()))
+    pipeline = (
+        _step(
+            id="four_state_vector_collection",
+            plugin="transform/four_state_vector_collection",
+            reads={"sources": RecordCollectionInputDecl(resource_ids=resource_ids)},
+            writes={"vectors": RecordOutputDecl(record_id="four_state_vector_collection/vectors")},
+        ),
+    )
+    selected_plots = protocol.select_plot_outputs(allowed={"four_state_vector_heatmap"})
+    plots = tuple(
+        _step(
+            id="four_state_vector_heatmap",
+            plugin="plot/four_state_vector_collection",
+            reads={"vectors": RecordInputDecl(record_id="four_state_vector_collection/vectors")},
+            with_=protocol.plot_view_config(figure_id="four_state_vector_heatmap"),
+        )
+        for _ in selected_plots
+    )
+    selected_exports = protocol.select_export_outputs(defaults=("vector_table",), allowed={"vector_table"})
+    exports = tuple(
+        _step(
+            id="vector_table",
+            plugin="export/csv",
+            reads={"df": RecordInputDecl(record_id="four_state_vector_collection/vectors")},
+            with_=_deep_merge(
+                {"path": "four_state_vector_collection.csv"},
+                protocol.export_artifact_config(artifact_id="vector_table"),
+            ),
+        )
+        for _ in selected_exports
+    )
+    return CompiledProtocolPlan(
+        pipeline=pipeline,
+        plots=plots,
+        exports=exports,
+        semantic_program=protocol.descriptor.semantic_program(),
+    )
+
+
+def compile_logic_four_state_vector_screen(protocol: Any):
+    analysis = _analysis_options(protocol)
+    include_fold_change = _configured_fold_change_enabled(protocol, analysis=analysis)
+    include_four_state_vector = _analysis_bool(analysis, key="include_four_state_vector", default=True)
+    preprocessing = _analysis_mapping(analysis, key="preprocessing")
+    blank_cfg = _analysis_mapping(preprocessing, key="blank")
+    overflow_cfg = _analysis_mapping(preprocessing, key="overflow")
+
+    ingest_channels = _configured_ingest_channels(protocol, required=("OD600", "CFP", "YFP"))
+    pipeline = list(
+        compose_dual_reporter_pipeline(
+            ingest_channels=ingest_channels,
+            blank_config=blank_cfg,
+            overflow_config=overflow_cfg,
+        )
+    )
+    if include_fold_change:
+        _configured_fold_change_target(protocol, expected=FOUR_STATE_VECTOR_SCREEN_LOGIC_CHANNEL)
+        _configured_fold_change_report_times(protocol)
+        pipeline.append(_plate_reader_fold_change_step(measurement="yfp_cfp"))
+    default_exports = (
+        ("logic_summary_workbook",)
+        if include_four_state_vector
+        and _analysis_bool(analysis, key="include_export", default=include_four_state_vector)
+        else ()
+    )
+    selected_exports = protocol.select_export_outputs(
+        defaults=default_exports,
+        allowed=LOGIC_EXPORT_OUTPUTS,
+    )
+    selected_plot_ids = protocol.select_plot_outputs(
+        allowed={
+            "raw_kinetics",
+            "endpoint_by_condition",
+            "endpoint_by_design",
+            "intensity_overview",
+            "logic_symmetry",
+            "four_state_vector_diagnostic",
+            "four_state_vector_heatmap",
+        },
+    )
+    requires_four_state_vector = (
+        include_four_state_vector
+        or "four_state_vector_diagnostic" in selected_plot_ids
+        or "four_state_vector_heatmap" in selected_plot_ids
+        or "logic_summary_workbook" in selected_exports
+    )
+    requires_logic_symmetry = "logic_symmetry" in selected_plot_ids
+    requires_promoted_df = requires_four_state_vector or requires_logic_symmetry
+    if requires_promoted_df:
+        pipeline.append(_four_state_vector_promote_step())
+    if requires_logic_symmetry:
+        pipeline.append(_logic_symmetry_step(protocol))
+    if requires_four_state_vector:
+        pipeline.append(_four_state_vector_step(protocol))
+
+    plots = [_logic_plot_output(protocol, output_id=output_id) for output_id in selected_plot_ids]
+    exports = [_logic_export_output(protocol, output_id=output_id) for output_id in selected_exports]
+
+    return CompiledProtocolPlan(
+        pipeline=tuple(pipeline),
+        plots=tuple(plots),
+        exports=tuple(exports),
+        semantic_program=_logic_semantic_program(protocol, include_four_state_vector=requires_four_state_vector),
+    )
+
+
+def _four_state_vector_promote_step() -> PluginStepDecl:
+    return _step(
+        id="promote_to_tidy_plus_map",
+        plugin="validator/to_tidy_plus_map",
+        reads={"df": RecordInputDecl(record_id="ratio_yfp_od600/df")},
+        writes={"df": RecordOutputDecl(record_id="promote_to_tidy_plus_map/df")},
+    )
+
+
+def _four_state_vector_step(protocol: Any) -> PluginStepDecl:
+    return _step(
+        id="four_state_vector",
+        plugin="transform/four_state_vector",
+        reads={"df": RecordInputDecl(record_id="promote_to_tidy_plus_map/df")},
+        with_={"log2_offset_delta": _four_state_vector_delta(protocol)},
+        writes={"vector": RecordOutputDecl(record_id="four_state_vector/vector")},
+    )
+
+
+def _logic_symmetry_step(protocol: Any) -> PluginStepDecl:
+    inputs = protocol.effective_inputs()
+    settings = _analysis_mapping(protocol.effective_analysis(), key="logic_symmetry")
+    return _step(
+        id="logic_symmetry_summary",
+        plugin="transform/logic_symmetry",
+        reads={"df": RecordInputDecl(record_id="promote_to_tidy_plus_map/df")},
+        with_=_deep_merge(
+            {
+                "response_channel": FOUR_STATE_VECTOR_SCREEN_LOGIC_CHANNEL,
+                "design_by": inputs.get("design_by", ["design_id"]),
+                "state_map_ref": inputs.get("state_map_ref", "induction_logic"),
+            },
+            settings,
+        ),
+        writes={"table": RecordOutputDecl(record_id="logic_symmetry/table")},
+    )
+
+
+def _four_state_vector_delta(protocol: Any) -> float:
+    settings = _analysis_mapping(_analysis_options(protocol), key="four_state_vector")
+    return float(settings.get("intensity_log2_offset_delta", 0.0))
+
+
+def _four_state_vector_heatmap_defaults(protocol: Any) -> dict[str, Any]:
+    return dict(_analysis_mapping(_analysis_options(protocol), key="four_state_vector_heatmap"))
+
+
+def _logic_plot_output(protocol: Any, *, output_id: str) -> PluginStepDecl:
+    settings = protocol.plot_view_config(figure_id=output_id)
+    if output_id == "four_state_vector_diagnostic":
+        reserved = {"growth_channel", "response_channel", "state_map_ref", "time_column"}
+        overridden = sorted(reserved.intersection(settings))
+        if overridden:
+            raise ConfigError(
+                "protocol.outputs.plots.views.four_state_vector_diagnostic cannot override compiler-owned settings: "
+                + ", ".join(overridden)
+            )
+        inputs = protocol.effective_inputs()
+        return _step(
+            id="four_state_vector_diagnostic",
+            plugin="plot/four_state_vector_diagnostic",
+            reads={
+                "df": RecordInputDecl(record_id="promote_to_tidy_plus_map/df"),
+                "vector": RecordInputDecl(record_id="four_state_vector/vector"),
+            },
+            with_=_deep_merge(
+                {
+                    "growth_channel": "OD600",
+                    "response_channel": FOUR_STATE_VECTOR_SCREEN_LOGIC_CHANNEL,
+                    "state_map_ref": inputs.get("state_map_ref", "induction_logic"),
+                    "time_column": inputs.get("time_column", "time"),
+                },
+                settings,
+            ),
+        )
+    if output_id == "four_state_vector_heatmap":
+        return _step(
+            id="four_state_vector_heatmap",
+            plugin="plot/four_state_vector_heatmap",
+            reads={"vector": RecordInputDecl(record_id="four_state_vector/vector")},
+            with_=_deep_merge(_four_state_vector_heatmap_defaults(protocol), settings),
+        )
+    if output_id == "logic_symmetry":
+        return _step(
+            id="logic_symmetry",
+            plugin="plot/logic_symmetry",
+            reads={"table": RecordInputDecl(record_id="logic_symmetry/table")},
+            with_=settings,
+        )
+    return _plate_reader_plot_output(protocol, output_id=output_id, measurement="yfp_cfp")
+
+
+def _logic_export_output(protocol: Any, *, output_id: str) -> PluginStepDecl:
+    if output_id == "logic_summary_workbook":
+        settings = protocol.export_artifact_config(artifact_id=output_id)
+        return _step(
+            id="logic_summary_workbook",
+            plugin="export/xlsx",
+            reads={"df": RecordInputDecl(record_id="four_state_vector/vector")},
+            with_=_deep_merge({"path": "four_state_vector/vector.xlsx", "sheet_name": "vector"}, settings),
+        )
+    raise ConfigError(f"Unknown logic export output {output_id!r}")