reader-workbench 1.0.0__py3-none-any.whl

reader_workbench/domains/plate_reader/analysis/four_state_event_window/disposition_records.py

@@ -0,0 +1,140 @@
+"""Materialize explicit well and design eligibility dispositions."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import pandas as pd
+
+from .design_dispositions import DesignDisposition
+from .well_exclusions import WellExclusion
+
+_COLUMNS = (
+    "experiment_id",
+    "design_id",
+    "scope",
+    "state",
+    "position",
+    "reduction_id",
+    "reason",
+    "observed_count",
+    "required_count",
+)
+
+
+def partition_eligible_wells(
+    wells: pd.DataFrame,
+    *,
+    dispositions: Sequence[DesignDisposition],
+    experiment_id: str,
+    reduction_id: str,
+    reference_design_id: str,
+    available_design_ids: set[str],
+    required_count: int,
+) -> tuple[pd.DataFrame, list[dict[str, object]]]:
+    selected = [
+        item for item in dispositions if item.experiment_id == experiment_id and item.reduction_id == reduction_id
+    ]
+    disposed_ids: set[str] = set()
+    records: list[dict[str, object]] = []
+    for item in selected:
+        if item.design_id == reference_design_id:
+            raise ValueError(f"{experiment_id}:{reduction_id} cannot dispose the reference design.")
+        if item.design_id not in available_design_ids:
+            raise ValueError(f"{experiment_id}:{reduction_id} disposition names absent design {item.design_id!r}.")
+        observed_count = int(
+            wells.loc[
+                wells["design_id"].astype(str).eq(item.design_id) & wells["state"].astype(str).eq(item.state)
+            ].shape[0]
+        )
+        if observed_count >= required_count:
+            raise ValueError(
+                f"{experiment_id}:{item.design_id}:{item.state}:{reduction_id} has {observed_count} observations; "
+                f"at least {required_count} are required, so the design disposition is not justified."
+            )
+        disposed_ids.add(item.design_id)
+        records.append(
+            _record(
+                experiment_id=item.experiment_id,
+                design_id=item.design_id,
+                scope="design",
+                state=item.state,
+                position=None,
+                reduction_id=item.reduction_id,
+                reason=item.reason,
+                observed_count=observed_count,
+                required_count=required_count,
+            )
+        )
+    eligible = wells.loc[~wells["design_id"].astype(str).isin(disposed_ids)].copy()
+    return eligible, records
+
+
+def partition_reduction_wells(
+    midpoint: pd.DataFrame,
+    lower: pd.DataFrame,
+    upper: pd.DataFrame,
+    *,
+    exclusions: Sequence[WellExclusion],
+    dispositions: Sequence[DesignDisposition],
+    experiment_id: str,
+    reduction_id: str,
+    reference_design_id: str,
+    available_design_ids: set[str],
+    required_count: int,
+) -> tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame, list[dict[str, object]]]:
+    eligible, records = partition_eligible_wells(
+        midpoint,
+        dispositions=dispositions,
+        experiment_id=experiment_id,
+        reduction_id=reduction_id,
+        reference_design_id=reference_design_id,
+        available_design_ids=available_design_ids,
+        required_count=required_count,
+    )
+    eligible_ids = set(eligible["design_id"].astype(str))
+    eligible_lower = lower.loc[lower["design_id"].astype(str).isin(eligible_ids)].copy()
+    eligible_upper = upper.loc[upper["design_id"].astype(str).isin(eligible_ids)].copy()
+    records[:0] = well_disposition_records(
+        exclusions,
+        experiment_id=experiment_id,
+        reduction_id=reduction_id,
+    )
+    return eligible, eligible_lower, eligible_upper, records
+
+
+def well_disposition_records(
+    exclusions: Sequence[WellExclusion],
+    *,
+    experiment_id: str,
+    reduction_id: str,
+) -> list[dict[str, object]]:
+    return [
+        _record(
+            experiment_id=item.experiment_id,
+            design_id=item.design_id,
+            scope="well",
+            state=item.state,
+            position=item.position,
+            reduction_id=item.reduction_id,
+            reason=item.reason,
+            observed_count=None,
+            required_count=None,
+        )
+        for item in exclusions
+        if item.experiment_id == experiment_id and item.reduction_id == reduction_id
+    ]
+
+
+def disposition_frame(records: Sequence[dict[str, object]]) -> pd.DataFrame:
+    frame = pd.DataFrame.from_records(records, columns=_COLUMNS)
+    frame["observed_count"] = frame["observed_count"].astype("Int64")
+    frame["required_count"] = frame["required_count"].astype("Int64")
+    return frame
+
+
+def _record(**values: object) -> dict[str, object]:
+    return {column: values[column] for column in _COLUMNS}
+
+
+__all__ = ["disposition_frame", "partition_reduction_wells"]

reader_workbench/domains/plate_reader/analysis/four_state_event_window/event_sensitivity.py

@@ -0,0 +1,27 @@
+"""Event-time sensitivity primitives for four-state event-window reductions."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def symmetric_event_sensitivity_half_width(
+    midpoint: float,
+    lower_bound: float,
+    upper_bound: float,
+) -> float:
+    """Return a midpoint-centered envelope covering both event-bound reductions.
+
+    Four-state event-window reduction is not necessarily linear in event time. The
+    midpoint estimate therefore need not bisect the values obtained at the two
+    event bounds. A symmetric display interval uses the larger absolute
+    deviation from the midpoint.
+    """
+
+    values = np.asarray([midpoint, lower_bound, upper_bound], dtype=float)
+    if not np.all(np.isfinite(values)):
+        raise ValueError("event-time sensitivity values must be finite.")
+    return float(max(abs(values[0] - values[1]), abs(values[2] - values[0])))
+
+
+__all__ = ["symmetric_event_sensitivity_half_width"]

reader_workbench/domains/plate_reader/analysis/four_state_event_window/materialize.py

@@ -0,0 +1,274 @@
+"""Materialize well and design four-state event-window records from verified sources."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from .aggregation import build_design_records
+from .contracts import FourStateEventWindowAnalysisSpec, ReductionSpec
+from .disposition_records import disposition_frame, partition_reduction_wells
+from .observation_resampling import descriptive_resampling_records
+from .reduction import (
+    combine_bound_kinds,
+    four_state_event_window_temporal_spec,
+    invert_bound_kind,
+    reduce_temporal_trace,
+)
+from .sources import ExperimentSource, event_record
+from .well_exclusion_validation import require_well_exclusion_support_failure
+
+
+def materialize_experiment(
+    source: ExperimentSource,
+    *,
+    request: FourStateEventWindowAnalysisSpec,
+) -> tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame, pd.DataFrame, pd.DataFrame, pd.DataFrame]:
+    """Build midpoint well/design records plus event-bound sensitivity."""
+
+    require_well_exclusion_support_failure(
+        source.well_exclusions,
+        reductions={item.id: item for item in request.reductions},
+        quality=request.quality,
+        response=source.response,
+        magnitude=source.magnitude,
+        event_estimates_h=(
+            source.event.interval_start_assay_h,
+            source.event.estimate_assay_h,
+            source.event.interval_end_assay_h,
+        ),
+        pre_window_end_h=source.event.interval_start_assay_h,
+        experiment_id=source.experiment_id,
+    )
+    well_frames: list[pd.DataFrame] = []
+    design_frames: list[pd.DataFrame] = []
+    draw_frames: list[pd.DataFrame] = []
+    disposition_records: list[dict[str, object]] = []
+    for reduction in request.reductions:
+        midpoint = _reduce_wells(
+            source,
+            request=request,
+            reduction=reduction,
+            event_estimate_h=source.event.estimate_assay_h,
+        )
+        lower = _reduce_wells(
+            source,
+            request=request,
+            reduction=reduction,
+            event_estimate_h=source.event.interval_start_assay_h,
+        )
+        upper = _reduce_wells(
+            source,
+            request=request,
+            reduction=reduction,
+            event_estimate_h=source.event.interval_end_assay_h,
+        )
+        eligible_midpoint, eligible_lower, eligible_upper, reduction_dispositions = partition_reduction_wells(
+            midpoint,
+            lower,
+            upper,
+            exclusions=request.source.well_exclusions,
+            dispositions=request.source.design_dispositions,
+            experiment_id=source.experiment_id,
+            reduction_id=reduction.id,
+            reference_design_id=request.source.reference_design_id,
+            available_design_ids=set(source.response["design_id"].astype(str)),
+            required_count=request.quality.min_observations_per_state,
+        )
+        well_frames.append(midpoint)
+        draw_frames.append(descriptive_resampling_records(eligible_midpoint, request=request))
+        design_frames.append(
+            build_design_records(
+                eligible_midpoint,
+                lower=eligible_lower,
+                upper=eligible_upper,
+                source=source,
+                request=request,
+                reduction=reduction,
+            )
+        )
+        disposition_records.extend(reduction_dispositions)
+
+    wells = pd.concat(well_frames, ignore_index=True)
+    designs = pd.concat(design_frames, ignore_index=True)
+    draws = pd.concat(draw_frames, ignore_index=True)
+    well_key = ["experiment_id", "design_id", "state", "position", "reduction_id"]
+    design_key = ["experiment_id", "design_id", "reduction_id"]
+    if wells.duplicated(subset=well_key).any():
+        raise ValueError(f"{source.experiment_id}: well record identity is not unique.")
+    if designs.duplicated(subset=design_key).any():
+        raise ValueError(f"{source.experiment_id}: design record identity is not unique.")
+    draw_key = ["experiment_id", "design_id", "reduction_id", "draw_index"]
+    if draws.duplicated(subset=draw_key).any():
+        raise ValueError(f"{source.experiment_id}: descriptive-resampling draw identity is not unique.")
+    traces = _trace_record(source, request=request)
+    return wells, designs, draws, traces, event_record(source.event), disposition_frame(disposition_records)
+
+
+def _reduce_wells(
+    source: ExperimentSource,
+    *,
+    request: FourStateEventWindowAnalysisSpec,
+    reduction: ReductionSpec,
+    event_estimate_h: float,
+) -> pd.DataFrame:
+    response = _summaries_by_trace(
+        source.response,
+        request=request,
+        reduction=reduction,
+        event_estimate_h=event_estimate_h,
+        signal_kind="response",
+        pre_window_end_h=source.event.interval_start_assay_h,
+    )
+    magnitude = _summaries_by_trace(
+        source.magnitude,
+        request=request,
+        reduction=reduction,
+        event_estimate_h=event_estimate_h,
+        signal_kind="magnitude",
+        pre_window_end_h=None,
+    )
+    keys = ["design_id", "state", "position"]
+    merged = response.merge(
+        magnitude, on=keys, how="outer", validate="one_to_one", suffixes=("_response", "_magnitude")
+    )
+    if merged.isna().any().any():
+        missing = merged.columns[merged.isna().any()].tolist()
+        raise ValueError(f"{source.experiment_id}:{reduction.id}: response/magnitude wells do not align: {missing}.")
+    merged.insert(0, "experiment_id", source.experiment_id)
+    merged["reduction_id"] = reduction.id
+    merged["reduction_method"] = reduction.method
+    merged["response_basis"] = reduction.response_basis
+    merged["reduction_role"] = reduction.role
+    merged["event_time_estimate_assay_h"] = float(event_estimate_h)
+    merged["window_start_event_h"] = reduction.window_start_event_h
+    merged["window_end_event_h"] = reduction.window_end_event_h
+    merged["window_start_assay_h"] = event_estimate_h + reduction.window_start_event_h
+    merged["window_end_assay_h"] = event_estimate_h + reduction.window_end_event_h
+    merged["is_reference"] = merged["design_id"].astype(str).eq(request.source.reference_design_id)
+    return merged.sort_values(keys, kind="mergesort").reset_index(drop=True)
+
+
+def _summaries_by_trace(
+    frame: pd.DataFrame,
+    *,
+    request: FourStateEventWindowAnalysisSpec,
+    reduction: ReductionSpec,
+    event_estimate_h: float,
+    signal_kind: str,
+    pre_window_end_h: float | None,
+) -> pd.DataFrame:
+    rows: list[dict[str, object]] = []
+    excluded = {
+        (item.design_id, item.state, item.position)
+        for item in request.source.well_exclusions
+        if item.experiment_id == source_experiment_id(frame) and item.reduction_id == reduction.id
+    }
+    for (design_id, state, position), trace in frame.groupby(
+        ["design_id", "state", "position"], sort=True, dropna=False
+    ):
+        if (str(design_id), str(state), str(position)) in excluded:
+            continue
+        trace_id = f"{frame['experiment_id'].iloc[0]}:{signal_kind}:{design_id}:{state}:{position}:{reduction.id}"
+        post = reduce_temporal_trace(
+            trace["time"].to_numpy(dtype=float),
+            trace["value"].to_numpy(dtype=float),
+            spec=four_state_event_window_temporal_spec(reduction, request.quality),
+            origin_h=event_estimate_h,
+            trace_id=trace_id,
+            policy_clipped=trace["value_policy_clipped"].to_numpy(dtype=bool),
+            instrument_overflow=trace["value_instrument_overflow"].to_numpy(dtype=bool),
+            bound_kinds=trace["value_bound_kind"].to_numpy(dtype=object),
+        )
+        value = post.value
+        policy_clipped_point_count = post.policy_clipped_point_count
+        instrument_overflow_point_count = post.instrument_overflow_point_count
+        bound_kind = post.bound_kind
+        pre_observed_point_count = 0
+        pre_integration_point_count = 0
+        pre_max_interior_gap_h = 0.0
+        if signal_kind == "response" and reduction.response_basis == "post_minus_pre":
+            if reduction.pre_window_duration_h is None or pre_window_end_h is None:
+                raise ValueError(f"{trace_id}: delta response lacks an explicit pre-event window.")
+            pre = reduce_temporal_trace(
+                trace["time"].to_numpy(dtype=float),
+                trace["value"].to_numpy(dtype=float),
+                spec=four_state_event_window_temporal_spec(
+                    reduction,
+                    request.quality,
+                    absolute_window_h=(
+                        pre_window_end_h - reduction.pre_window_duration_h,
+                        pre_window_end_h,
+                    ),
+                ),
+                trace_id=f"{trace_id}:pre",
+                policy_clipped=trace["value_policy_clipped"].to_numpy(dtype=bool),
+                instrument_overflow=trace["value_instrument_overflow"].to_numpy(dtype=bool),
+                bound_kinds=trace["value_bound_kind"].to_numpy(dtype=object),
+            )
+            value -= pre.value
+            policy_clipped_point_count += pre.policy_clipped_point_count
+            instrument_overflow_point_count += pre.instrument_overflow_point_count
+            bound_kind = combine_bound_kinds(bound_kind, invert_bound_kind(pre.bound_kind))
+            pre_observed_point_count = pre.observed_point_count
+            pre_integration_point_count = pre.evaluation_point_count
+            pre_max_interior_gap_h = pre.max_interior_gap_h
+        rows.append(
+            {
+                "design_id": str(design_id),
+                "state": str(state),
+                "position": str(position),
+                f"{signal_kind}_well": float(value),
+                f"{signal_kind}_observed_point_count": post.observed_point_count,
+                f"{signal_kind}_integration_point_count": post.evaluation_point_count,
+                f"{signal_kind}_max_interior_gap_h": post.max_interior_gap_h,
+                f"{signal_kind}_pre_observed_point_count": pre_observed_point_count,
+                f"{signal_kind}_pre_integration_point_count": pre_integration_point_count,
+                f"{signal_kind}_pre_max_interior_gap_h": pre_max_interior_gap_h,
+                f"{signal_kind}_policy_clipped_point_count": policy_clipped_point_count,
+                f"{signal_kind}_instrument_overflow_point_count": instrument_overflow_point_count,
+                f"{signal_kind}_bound_kind": bound_kind,
+            }
+        )
+    result = pd.DataFrame.from_records(rows)
+    if result.empty:
+        raise ValueError(f"{signal_kind} reduction produced no well records.")
+    return result
+
+
+def source_experiment_id(frame: pd.DataFrame) -> str:
+    return str(frame["experiment_id"].iloc[0])
+
+
+def _trace_record(source: ExperimentSource, *, request: FourStateEventWindowAnalysisSpec) -> pd.DataFrame:
+    frames: list[pd.DataFrame] = []
+    for signal_kind, frame in (
+        ("response", source.response),
+        ("magnitude", source.magnitude),
+        ("growth", source.trajectory),
+    ):
+        selected = frame.loc[
+            :,
+            [
+                "experiment_id",
+                "design_id",
+                "position",
+                "state",
+                "time",
+                "time_from_event_h",
+                "value",
+                "value_policy_clipped",
+                "value_instrument_overflow",
+                "value_bound_kind",
+            ],
+        ].copy()
+        selected["signal_kind"] = signal_kind
+        selected["is_reference"] = selected["design_id"].astype(str).eq(request.source.reference_design_id)
+        frames.append(selected)
+    result = pd.concat(frames, ignore_index=True)
+    key = ["experiment_id", "design_id", "position", "state", "signal_kind", "time"]
+    if result.duplicated(subset=key).any():
+        raise ValueError(f"{source.experiment_id}: trace record identity is not unique.")
+    return result.sort_values(key, kind="mergesort").reset_index(drop=True)
+
+
+__all__ = ["materialize_experiment"]

reader_workbench/domains/plate_reader/analysis/four_state_event_window/observation_resampling.py

@@ -0,0 +1,97 @@
+"""Descriptive resampling primitives for within-experiment observations."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from .contracts import FourStateEventWindowAnalysisSpec, ObservationStat
+from .seeds import stable_seed
+from .sources import STATE_ORDER
+
+
+def descriptive_resampling_records(wells: pd.DataFrame, *, request: FourStateEventWindowAnalysisSpec) -> pd.DataFrame:
+    """Resample observed wells jointly without implying population inference."""
+
+    anchor_id = request.source.reference_design_id
+    anchor = wells.loc[wells["design_id"].astype(str).eq(anchor_id)]
+    records: list[pd.DataFrame] = []
+    for design_id, design_wells in wells.groupby("design_id", sort=True):
+        state_draws: dict[str, np.ndarray] = {}
+        for state in STATE_ORDER:
+            state_wells = design_wells.loc[design_wells["state"].astype(str).eq(state)]
+            anchor_wells = anchor.loc[anchor["state"].astype(str).eq(state)]
+            response_values = state_wells["response_well"].to_numpy(dtype=float)
+            magnitude_values = state_wells["magnitude_well"].to_numpy(dtype=float)
+            anchor_values = anchor_wells["magnitude_well"].to_numpy(dtype=float)
+            minimum = request.quality.min_observations_per_state
+            if min(len(response_values), len(magnitude_values), len(anchor_values)) < minimum:
+                raise ValueError(f"{design_id}:{state} lacks support for within-experiment descriptive resampling.")
+            reduction_id = str(state_wells["reduction_id"].iloc[0])
+            experiment_id = str(state_wells["experiment_id"].iloc[0])
+            rng = np.random.default_rng(
+                stable_seed(request.aggregation.random_seed, experiment_id, str(design_id), state, reduction_id)
+            )
+            response_draws, anchored_magnitude_draws = joint_state_descriptive_resampling_draws(
+                response_values,
+                magnitude_values,
+                anchor_values,
+                samples=request.aggregation.descriptive_resampling_draws,
+                stat=request.aggregation.observation_stat,
+                rng=rng,
+                paired_anchor=str(design_id) == anchor_id,
+            )
+            state_draws[f"r{state}"] = response_draws
+            state_draws[f"b{state}"] = anchored_magnitude_draws
+        frame = pd.DataFrame(state_draws)
+        frame.insert(0, "draw_index", np.arange(len(frame), dtype=int))
+        frame.insert(0, "reduction_id", str(design_wells["reduction_id"].iloc[0]))
+        frame.insert(0, "design_id", str(design_id))
+        frame.insert(0, "experiment_id", str(design_wells["experiment_id"].iloc[0]))
+        frame["is_reference"] = str(design_id) == anchor_id
+        records.append(frame)
+    return pd.concat(records, ignore_index=True)
+
+
+def joint_state_descriptive_resampling_draws(
+    response_values: np.ndarray,
+    magnitude_values: np.ndarray,
+    anchor_values: np.ndarray,
+    *,
+    samples: int,
+    stat: ObservationStat,
+    rng: np.random.Generator,
+    paired_anchor: bool = False,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Resample paired observed wells and either paired or independent reference wells."""
+
+    response = np.asarray(response_values, dtype=float)
+    magnitude = np.asarray(magnitude_values, dtype=float)
+    anchor = np.asarray(anchor_values, dtype=float)
+    if stat not in {"mean", "median"}:
+        raise ValueError("joint descriptive resampling requires stat to be 'mean' or 'median'.")
+    if response.ndim != 1 or magnitude.ndim != 1 or anchor.ndim != 1:
+        raise ValueError("joint descriptive-resampling inputs must be one-dimensional arrays.")
+    if len(response) != len(magnitude) or len(response) == 0 or len(anchor) == 0:
+        raise ValueError(
+            "joint descriptive resampling requires aligned design observations and non-empty reference observations."
+        )
+    if samples < 2:
+        raise ValueError("joint descriptive resampling requires at least two draws.")
+    if paired_anchor and not np.array_equal(magnitude, anchor):
+        raise ValueError(
+            "paired reference descriptive resampling requires identical ordered magnitude and anchor observations."
+        )
+    design_indexes = rng.integers(0, len(response), size=(samples, len(response)))
+    anchor_indexes = design_indexes if paired_anchor else rng.integers(0, len(anchor), size=(samples, len(anchor)))
+    aggregate = np.median if stat == "median" else np.mean
+    response_draws = aggregate(response[design_indexes], axis=1)
+    magnitude_draws = aggregate(magnitude[design_indexes], axis=1)
+    anchor_draws = aggregate(anchor[anchor_indexes], axis=1)
+    return response_draws, magnitude_draws - anchor_draws
+
+
+__all__ = [
+    "descriptive_resampling_records",
+    "joint_state_descriptive_resampling_draws",
+]

reader_workbench/domains/plate_reader/analysis/four_state_event_window/reduction.py

@@ -0,0 +1,62 @@
+"""Four-state event-window adapter to the assay-neutral temporal reducer."""
+
+from __future__ import annotations
+
+from reader_workbench.domains.time_series import (
+    IntervalSelection,
+    TemporalReductionSpec,
+    TemporalSupportPolicy,
+    combine_bound_kinds,
+    invert_bound_kind,
+    reduce_temporal_trace,
+)
+
+from .contracts import QualitySpec, ReductionSpec
+
+
+def four_state_event_window_temporal_spec(
+    reduction: ReductionSpec,
+    quality: QualitySpec,
+    *,
+    absolute_window_h: tuple[float, float] | None = None,
+) -> TemporalReductionSpec:
+    """Project four-state event-window policy into the neutral temporal contract.
+
+    Four-state event-window reductions remain event-relative unless an explicit
+    absolute pre-event interval is supplied. The projection preserves the
+    established interpolation, log2 output, support-gap, and censor behavior.
+    """
+
+    if absolute_window_h is None:
+        selection = IntervalSelection(
+            time_basis="event_relative",
+            start_h=reduction.window_start_event_h,
+            end_h=reduction.window_end_event_h,
+        )
+    else:
+        selection = IntervalSelection(
+            time_basis="absolute",
+            start_h=float(absolute_window_h[0]),
+            end_h=float(absolute_window_h[1]),
+        )
+    return TemporalReductionSpec(
+        selection=selection,
+        method=reduction.method,
+        output_space="log2",
+        support=TemporalSupportPolicy(
+            boundary_support="covered",
+            minimum_observations=0,
+            maximum_interior_gap_h=quality.max_interior_gap_h,
+            positive_floor=quality.positive_floor,
+            positive_value_scope="entire_trace",
+            censored_values="allow",
+        ),
+    )
+
+
+__all__ = [
+    "combine_bound_kinds",
+    "invert_bound_kind",
+    "reduce_temporal_trace",
+    "four_state_event_window_temporal_spec",
+]

reader_workbench/domains/plate_reader/analysis/four_state_event_window/seeds.py

@@ -0,0 +1,15 @@
+"""Deterministic seed derivation for four-state event-window resampling."""
+
+from __future__ import annotations
+
+import hashlib
+
+
+def stable_seed(base: int, *parts: str) -> int:
+    """Derive a reproducible unsigned seed from an explicit identity tuple."""
+
+    digest = hashlib.sha256((str(base) + ":" + ":".join(parts)).encode()).digest()
+    return int.from_bytes(digest[:8], "little")
+
+
+__all__ = ["stable_seed"]