reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/contracts/builtins/four_state_event_window.py

@@ -0,0 +1,214 @@
+"""Dataframe contracts for plate-reader four-state event-window records."""
+
+from __future__ import annotations
+
+from ..model import ColumnRule, DataFrameContract
+
+_STATES = ["00", "10", "01", "11"]
+_REDUCTION_ROLES = ["primary", "sensitivity"]
+_REDUCTION_METHODS = ["geometric_time_mean", "integrated_linear_mean"]
+_RESPONSE_BASES = ["post_window", "post_minus_pre"]
+_VALUE_BOUND_KINDS = ["exact", "lower", "upper", "indeterminate"]
+
+
+def _state_summary_columns() -> list[ColumnRule]:
+    columns: list[ColumnRule] = []
+    for state in _STATES:
+        columns.extend(
+            [
+                ColumnRule(f"r{state}", "float"),
+                ColumnRule(f"b{state}", "float"),
+                ColumnRule(f"r{state}_descriptive_resampling_sd", "float", nonnegative=True),
+                ColumnRule(f"b{state}_descriptive_resampling_sd", "float", nonnegative=True),
+                ColumnRule(f"r{state}_descriptive_interval_low", "float"),
+                ColumnRule(f"r{state}_descriptive_interval_high", "float"),
+                ColumnRule(f"b{state}_descriptive_interval_low", "float"),
+                ColumnRule(f"b{state}_descriptive_interval_high", "float"),
+                ColumnRule(f"r{state}_event_half_range", "float", nonnegative=True),
+                ColumnRule(f"b{state}_event_half_range", "float", nonnegative=True),
+                ColumnRule(f"r{state}_event_sensitivity_has_policy_clipping", "bool"),
+                ColumnRule(f"r{state}_event_sensitivity_has_instrument_overflow", "bool"),
+                ColumnRule(f"b{state}_event_sensitivity_has_policy_clipping", "bool"),
+                ColumnRule(f"b{state}_event_sensitivity_has_instrument_overflow", "bool"),
+                ColumnRule(f"r{state}_has_policy_clipping", "bool"),
+                ColumnRule(f"r{state}_has_instrument_overflow", "bool"),
+                ColumnRule(f"r{state}_bound_kind", "string", allowed_values=_VALUE_BOUND_KINDS),
+                ColumnRule(f"b{state}_has_policy_clipping", "bool"),
+                ColumnRule(f"b{state}_has_instrument_overflow", "bool"),
+                ColumnRule(f"b{state}_bound_kind", "string", allowed_values=_VALUE_BOUND_KINDS),
+                ColumnRule(f"n{state}", "int", nonnegative=True),
+            ]
+        )
+    return columns
+
+
+CONTRACTS: tuple[DataFrameContract, ...] = (
+    DataFrameContract(
+        id="plate_reader.four_state_event_window.wells.v3",
+        description="Event-relative well summary with clipping and censor-bound support.",
+        columns=[
+            ColumnRule("experiment_id", "string"),
+            ColumnRule("design_id", "string"),
+            ColumnRule("state", "string", allowed_values=_STATES),
+            ColumnRule("position", "string"),
+            ColumnRule("response_well", "float"),
+            ColumnRule("response_observed_point_count", "int", nonnegative=True),
+            ColumnRule("response_integration_point_count", "int", nonnegative=True),
+            ColumnRule("response_max_interior_gap_h", "float", nonnegative=True),
+            ColumnRule("response_pre_observed_point_count", "int", nonnegative=True),
+            ColumnRule("response_pre_integration_point_count", "int", nonnegative=True),
+            ColumnRule("response_pre_max_interior_gap_h", "float", nonnegative=True),
+            ColumnRule("response_policy_clipped_point_count", "int", nonnegative=True),
+            ColumnRule("response_instrument_overflow_point_count", "int", nonnegative=True),
+            ColumnRule("response_bound_kind", "string", allowed_values=_VALUE_BOUND_KINDS),
+            ColumnRule("magnitude_well", "float"),
+            ColumnRule("magnitude_observed_point_count", "int", nonnegative=True),
+            ColumnRule("magnitude_integration_point_count", "int", nonnegative=True),
+            ColumnRule("magnitude_max_interior_gap_h", "float", nonnegative=True),
+            ColumnRule("magnitude_pre_observed_point_count", "int", nonnegative=True),
+            ColumnRule("magnitude_pre_integration_point_count", "int", nonnegative=True),
+            ColumnRule("magnitude_pre_max_interior_gap_h", "float", nonnegative=True),
+            ColumnRule("magnitude_policy_clipped_point_count", "int", nonnegative=True),
+            ColumnRule("magnitude_instrument_overflow_point_count", "int", nonnegative=True),
+            ColumnRule("magnitude_bound_kind", "string", allowed_values=_VALUE_BOUND_KINDS),
+            ColumnRule("reduction_id", "string"),
+            ColumnRule("reduction_method", "string", allowed_values=_REDUCTION_METHODS),
+            ColumnRule("response_basis", "string", allowed_values=_RESPONSE_BASES),
+            ColumnRule("reduction_role", "string", allowed_values=_REDUCTION_ROLES),
+            ColumnRule("event_time_estimate_assay_h", "float", nonnegative=True),
+            ColumnRule("window_start_event_h", "float", nonnegative=True),
+            ColumnRule("window_end_event_h", "float", nonnegative=True),
+            ColumnRule("window_start_assay_h", "float", nonnegative=True),
+            ColumnRule("window_end_assay_h", "float", nonnegative=True),
+            ColumnRule("is_reference", "bool"),
+        ],
+        unique_keys=[["experiment_id", "design_id", "state", "position", "reduction_id"]],
+        domain="plate_reader",
+        kind="four-state-event-window-well-summary",
+        allow_extra_columns=False,
+    ),
+    DataFrameContract(
+        id="plate_reader.four_state_event_window.designs.v4",
+        description=(
+            "Four-state response and anchored-magnitude summary with within-experiment observation counts, "
+            "descriptive resampling intervals, and state-level censor bounds."
+        ),
+        columns=[
+            ColumnRule("experiment_id", "string"),
+            ColumnRule("design_id", "string"),
+            ColumnRule("reference_design_id", "string"),
+            ColumnRule("reduction_id", "string"),
+            ColumnRule("reduction_method", "string", allowed_values=_REDUCTION_METHODS),
+            ColumnRule("response_basis", "string", allowed_values=_RESPONSE_BASES),
+            ColumnRule("reduction_role", "string", allowed_values=_REDUCTION_ROLES),
+            ColumnRule("observation_stat", "string", allowed_values=["mean", "median"]),
+            ColumnRule("descriptive_resampling_draws", "int", nonnegative=True),
+            ColumnRule("descriptive_interval_mass", "float", nonnegative=True),
+            ColumnRule("event_id", "string"),
+            ColumnRule("event_time_estimate_assay_h", "float", nonnegative=True),
+            ColumnRule("event_time_uncertainty_h", "float", nonnegative=True),
+            ColumnRule("window_start_event_h", "float", nonnegative=True),
+            ColumnRule("window_end_event_h", "float", nonnegative=True),
+            ColumnRule("is_reference", "bool"),
+            ColumnRule("positive_floor", "float", nonnegative=True),
+            ColumnRule("allowed_max_interior_gap_h", "float", nonnegative=True),
+            ColumnRule("required_min_observations_per_state", "int", nonnegative=True),
+            ColumnRule("min_observation_count_per_state", "int", nonnegative=True),
+            ColumnRule("min_observed_points_per_trace", "int", nonnegative=True),
+            ColumnRule("max_observed_interior_gap_h", "float", nonnegative=True),
+            ColumnRule("min_pre_observed_points_per_trace", "int", nonnegative=True),
+            ColumnRule("max_pre_observed_interior_gap_h", "float", nonnegative=True),
+            *_state_summary_columns(),
+        ],
+        unique_keys=[["experiment_id", "design_id", "reduction_id"]],
+        domain="plate_reader",
+        kind="four-state-event-window-design-summary",
+        allow_extra_columns=False,
+    ),
+    DataFrameContract(
+        id="plate_reader.four_state_event_window.descriptive_resampling_draws.v3",
+        description=(
+            "Joint descriptive resampling draw over eight four-state event-window components from "
+            "within-experiment observations."
+        ),
+        columns=[
+            ColumnRule("experiment_id", "string"),
+            ColumnRule("design_id", "string"),
+            ColumnRule("reduction_id", "string"),
+            ColumnRule("draw_index", "int", nonnegative=True),
+            *(ColumnRule(column, "float") for state in _STATES for column in (f"r{state}", f"b{state}")),
+            ColumnRule("is_reference", "bool"),
+        ],
+        unique_keys=[["experiment_id", "design_id", "reduction_id", "draw_index"]],
+        domain="plate_reader",
+        kind="four-state-event-window-descriptive-resampling-draw",
+        allow_extra_columns=False,
+    ),
+    DataFrameContract(
+        id="plate_reader.four_state_event_window.traces.v3",
+        description="Source trace observations with clipping and censor bounds aligned to one event.",
+        columns=[
+            ColumnRule("experiment_id", "string"),
+            ColumnRule("design_id", "string"),
+            ColumnRule("position", "string"),
+            ColumnRule("state", "string", allowed_values=_STATES),
+            ColumnRule("time", "float", nonnegative=True),
+            ColumnRule("time_from_event_h", "float"),
+            ColumnRule("value", "float"),
+            ColumnRule("value_policy_clipped", "bool"),
+            ColumnRule("value_instrument_overflow", "bool"),
+            ColumnRule("value_bound_kind", "string", allowed_values=_VALUE_BOUND_KINDS),
+            ColumnRule("signal_kind", "string", allowed_values=["response", "magnitude", "growth"]),
+            ColumnRule("is_reference", "bool"),
+        ],
+        unique_keys=[["experiment_id", "design_id", "position", "state", "signal_kind", "time"]],
+        domain="plate_reader",
+        kind="four-state-event-window-trace",
+        allow_extra_columns=False,
+    ),
+    DataFrameContract(
+        id="plate_reader.four_state_event_window.events.v2",
+        description="Declared intervention interval and event-relative coverage for one experiment.",
+        columns=[
+            ColumnRule("experiment_id", "string"),
+            ColumnRule("event_id", "string"),
+            ColumnRule("event_kind", "string"),
+            ColumnRule("event_interval_start_assay_h", "float", nonnegative=True),
+            ColumnRule("event_interval_end_assay_h", "float", nonnegative=True),
+            ColumnRule("event_time_estimate_assay_h", "float", nonnegative=True),
+            ColumnRule("event_time_estimate_method", "string", allowed_values=["segment_gap_midpoint"]),
+            ColumnRule("event_time_uncertainty_h", "float", nonnegative=True),
+            ColumnRule("post_event_coverage_h", "float", nonnegative=True),
+            ColumnRule("declaration", "string"),
+        ],
+        unique_keys=[["experiment_id"]],
+        domain="plate_reader",
+        kind="four-state-event-window-event",
+        allow_extra_columns=False,
+    ),
+    DataFrameContract(
+        id="plate_reader.four_state_event_window.dispositions.v1",
+        description="Plate- and reduction-scoped well or design eligibility dispositions.",
+        columns=[
+            ColumnRule("experiment_id", "string"),
+            ColumnRule("design_id", "string"),
+            ColumnRule("scope", "string", allowed_values=["well", "design"]),
+            ColumnRule("state", "string", allowed_values=_STATES),
+            ColumnRule("position", "string", allow_nan=True),
+            ColumnRule("reduction_id", "string"),
+            ColumnRule(
+                "reason",
+                "string",
+                allowed_values=["insufficient_event_window_coverage", "insufficient_state_observations"],
+            ),
+            ColumnRule("observed_count", "int", allow_nan=True, nonnegative=True),
+            ColumnRule("required_count", "int", allow_nan=True, nonnegative=True),
+        ],
+        unique_keys=[["experiment_id", "design_id", "scope", "state", "position", "reduction_id"]],
+        domain="plate_reader",
+        kind="four-state-event-window-disposition",
+        allow_extra_columns=False,
+    ),
+)
+
+__all__ = ["CONTRACTS"]

reader_workbench/contracts/builtins/generic.py

@@ -0,0 +1,21 @@
+"""Generic tabular contracts shared across analysis domains."""
+
+from __future__ import annotations
+
+from ..model import ColumnRule, DataFrameContract
+
+CONTRACTS: tuple[DataFrameContract, ...] = (
+    DataFrameContract(
+        id="tidy.v1",
+        description="Tidy long table: position,str | time,float | channel,str | value,float",
+        columns=[
+            ColumnRule("position", "string"),
+            ColumnRule("time", "float", nonnegative=True),
+            ColumnRule("channel", "string"),
+            ColumnRule("value", "float"),
+        ],
+        unique_keys=[],
+        domain="tabular",
+        kind="measurement-trace",
+    ),
+)

reader_workbench/contracts/builtins/logic.py

@@ -0,0 +1,149 @@
+"""Logic-domain dataframe contracts."""
+
+from __future__ import annotations
+
+from ..model import ColumnRule, DataFrameContract
+
+
+def _four_state_vector_columns() -> list[ColumnRule]:
+    return [
+        ColumnRule("design_id", "string"),
+        ColumnRule("sequence", "string", required=False, allow_nan=True),
+        ColumnRule("id", "string", required=False, allow_nan=True),
+        ColumnRule("time_selected_h", "float", required=False, allow_nan=True),
+        ColumnRule("reference_design_id", "string"),
+        ColumnRule(
+            "intensity_log2_offset_delta",
+            "float",
+            nonnegative=True,
+        ),
+        ColumnRule("r_logic", "float", nonnegative=True),
+        ColumnRule("v00", "float"),
+        ColumnRule("v10", "float"),
+        ColumnRule("v01", "float"),
+        ColumnRule("v11", "float"),
+        ColumnRule("y00_star", "float"),
+        ColumnRule("y10_star", "float"),
+        ColumnRule("y01_star", "float"),
+        ColumnRule("y11_star", "float"),
+        ColumnRule("flat_logic", "bool"),
+    ]
+
+
+CONTRACTS: tuple[DataFrameContract, ...] = (
+    DataFrameContract(
+        id="logic.four_state_vector.v1",
+        description=(
+            "Per-design four-state logic-intensity measurement vector with explicit transform parameters "
+            "and reference provenance."
+        ),
+        columns=_four_state_vector_columns(),
+        unique_keys=[["design_id"]],
+        domain="logic",
+        kind="logic-summary",
+    ),
+    DataFrameContract(
+        id="logic.four_state_vector_collection.v1",
+        description="Cross-experiment four-state vector collection with exact source-record revision provenance.",
+        columns=[
+            ColumnRule("source_index", "int", nonnegative=True),
+            ColumnRule("source_resource_id", "string"),
+            ColumnRule("source_experiment_id", "string"),
+            ColumnRule("source_record_id", "string"),
+            ColumnRule("source_record_revision_digest", "string"),
+            ColumnRule("source_row_index", "int", nonnegative=True),
+            ColumnRule("row_label", "string"),
+            *_four_state_vector_columns(),
+        ],
+        unique_keys=[["source_experiment_id", "source_record_id", "design_id"]],
+        domain="logic",
+        kind="logic-summary-collection",
+    ),
+    DataFrameContract(
+        id="crosstalk_pairs.v1",
+        description="Pairwise crosstalk summary for design pairs at a single time/target.",
+        columns=[
+            ColumnRule("design_a", "string"),
+            ColumnRule("design_b", "string"),
+            ColumnRule("treatment_a", "string", allow_nan=True),
+            ColumnRule("treatment_b", "string", allow_nan=True),
+            ColumnRule("target", "string", allow_nan=True),
+            ColumnRule("time", "float", nonnegative=True, allow_nan=True),
+            ColumnRule("value_column", "string"),
+            ColumnRule("value_scale", "string", allowed_values=["log2", "linear"]),
+            ColumnRule("a_self_value", "float", allow_nan=True),
+            ColumnRule("b_self_value", "float", allow_nan=True),
+            ColumnRule("a_cross_to_b", "float", allow_nan=True),
+            ColumnRule("b_cross_to_a", "float", allow_nan=True),
+            ColumnRule("a_best_other_treatment", "string", required=False, allow_nan=True),
+            ColumnRule("b_best_other_treatment", "string", required=False, allow_nan=True),
+            ColumnRule("a_best_other_value", "float", required=False, allow_nan=True),
+            ColumnRule("b_best_other_value", "float", required=False, allow_nan=True),
+            ColumnRule("a_self_minus_best_other", "float", required=False, allow_nan=True),
+            ColumnRule("b_self_minus_best_other", "float", required=False, allow_nan=True),
+            ColumnRule("a_self_ratio_best_other", "float", required=False, allow_nan=True),
+            ColumnRule("b_self_ratio_best_other", "float", required=False, allow_nan=True),
+            ColumnRule("a_self_is_top1", "bool"),
+            ColumnRule("b_self_is_top1", "bool"),
+            ColumnRule("a_top1_treatment", "string", allow_nan=True),
+            ColumnRule("a_top2_treatment", "string", allow_nan=True),
+            ColumnRule("b_top1_treatment", "string", allow_nan=True),
+            ColumnRule("b_top2_treatment", "string", allow_nan=True),
+            ColumnRule("a_top1_value", "float", allow_nan=True),
+            ColumnRule("a_top2_value", "float", allow_nan=True),
+            ColumnRule("b_top1_value", "float", allow_nan=True),
+            ColumnRule("b_top2_value", "float", allow_nan=True),
+            ColumnRule("a_selectivity_delta", "float", allow_nan=True),
+            ColumnRule("b_selectivity_delta", "float", allow_nan=True),
+            ColumnRule("a_selectivity_ratio", "float", allow_nan=True),
+            ColumnRule("b_selectivity_ratio", "float", allow_nan=True),
+            ColumnRule("pair_score", "float", allow_nan=True),
+            ColumnRule("pair_ratio", "float", allow_nan=True),
+            ColumnRule("passes_filters", "bool"),
+        ],
+        unique_keys=[],
+        domain="logic",
+        kind="pairwise-summary",
+    ),
+    DataFrameContract(
+        id="logic_symmetry.v1",
+        description=(
+            "Logic-symmetry per design and batch summary with four-state observation counts, dispersion, "
+            "metrics, and coordinates."
+        ),
+        columns=[
+            ColumnRule("design_id", "string", required=False, allow_nan=True),
+            ColumnRule("genotype", "string", required=False, allow_nan=True),
+            ColumnRule("strain", "string", required=False, allow_nan=True),
+            ColumnRule("design", "string", required=False, allow_nan=True),
+            ColumnRule("construct", "string", required=False, allow_nan=True),
+            ColumnRule("batch", "int", required=False, allow_nan=True),
+            ColumnRule("n00", "int"),
+            ColumnRule("n10", "int"),
+            ColumnRule("n01", "int"),
+            ColumnRule("n11", "int"),
+            ColumnRule("b00", "float"),
+            ColumnRule("b10", "float"),
+            ColumnRule("b01", "float"),
+            ColumnRule("b11", "float"),
+            ColumnRule("sd00", "float"),
+            ColumnRule("sd10", "float"),
+            ColumnRule("sd01", "float"),
+            ColumnRule("sd11", "float"),
+            ColumnRule("r", "float"),
+            ColumnRule("log_r", "float"),
+            ColumnRule("cv", "float"),
+            ColumnRule("u00", "float"),
+            ColumnRule("u10", "float"),
+            ColumnRule("u01", "float"),
+            ColumnRule("u11", "float"),
+            ColumnRule("L", "float"),
+            ColumnRule("A", "float"),
+            ColumnRule("baseline_corner", "string"),
+            ColumnRule("baseline_value", "float"),
+        ],
+        unique_keys=[],
+        domain="logic",
+        kind="summary-table",
+    ),
+)

reader_workbench/contracts/builtins/plate_reader.py

@@ -0,0 +1,47 @@
+"""Plate-reader specific dataframe contracts layered on top of generic tidy data."""
+
+from __future__ import annotations
+
+from ..model import ColumnRule, DataFrameContract
+
+CONTRACTS: tuple[DataFrameContract, ...] = (
+    DataFrameContract(
+        id="plate_reader.annotated.v1",
+        description="Plate-reader tidy table with required mapped metadata: treatment,str | design_id,str | batch,float (optional).",
+        columns=[
+            ColumnRule("position", "string"),
+            ColumnRule("time", "float", nonnegative=True),
+            ColumnRule("channel", "string"),
+            ColumnRule("value", "float"),
+            ColumnRule("treatment", "string"),
+            ColumnRule("design_id", "string"),
+            ColumnRule("batch", "float", required=False, allow_nan=True),
+        ],
+        unique_keys=[],
+        parents=("tidy.v1",),
+        domain="plate_reader",
+        kind="annotated-measurement-trace",
+    ),
+    DataFrameContract(
+        id="fold_change.v1",
+        description=(
+            "Fold-change summary table per (group..., treatment, time, target) with explicit observation counts."
+        ),
+        columns=[
+            ColumnRule("target", "string"),
+            ColumnRule("time", "float", nonnegative=True),
+            ColumnRule("treatment", "string"),
+            ColumnRule("FC", "float", required=True, allow_nan=True),
+            ColumnRule("log2FC", "float", required=True, allow_nan=True),
+            ColumnRule("n", "int", required=True, allow_nan=False),
+            ColumnRule("baseline_value", "string", required=True, allow_nan=True),
+            ColumnRule("baseline_n", "int", required=True, allow_nan=True),
+            ColumnRule("baseline_time", "float", required=True, allow_nan=True),
+            ColumnRule("genotype", "string", required=False, allow_nan=True),
+            ColumnRule("batch", "int", required=False, allow_nan=True),
+        ],
+        unique_keys=[],
+        domain="plate_reader",
+        kind="summary-table",
+    ),
+)