pytesprocess 0.1.1__py3-none-any.whl

pytesprocess/process/randoms.py

@@ -0,0 +1,921 @@
+"""Random-trigger generation for continuous/segmented raw data.
+
+This refactor keeps the public Randoms API close to the historical version,
+while separating storage-region discovery, count allocation, and random index
+sampling.
+"""
+
+from __future__ import annotations
+
+import copy
+from dataclasses import dataclass
+from math import ceil
+from pathlib import Path
+import random
+import re
+
+import numpy as np
+import vaex as vx
+
+from pytesdaqx.io import AcquisitionCatalog
+from pytesprocess.utils import create_dataframe_group
+
+
+__all__ = ["Randoms"]
+
+
+@dataclass(frozen=True)
+class _SelectionRegion:
+    """One independent interval from which random triggers may be selected."""
+
+    region_id: int
+    stream_id: str
+    start_index: int
+    length_samples: int
+    usable_start_index: int
+    usable_stop_index: int  # exclusive, local to the region
+    usable_samples: int
+    capacity: int
+
+    # HDF5 segment metadata
+    dump_num: int | None = None
+    global_segment_num: int | None = None
+
+    # Zarr processing-partition metadata
+    partition_index: int | None = None
+    partition_start_index: int | None = None
+    partition_length_samples: int | None = None
+
+
+class Randoms:
+    """Generate random-trigger metadata from raw-data streams.
+
+    HDF5 data are sampled independently within each stored segment.
+
+    Zarr data support two modes:
+      * ``partition_target_duration_s`` provided: sample independently within
+        logical processing partitions, preserving the historical segment-like
+        behavior.
+      * ``partition_target_duration_s=None``: sample across each full
+        continuous stream, so edge exclusion is applied only at the beginning
+        and end of the stream.
+    """
+
+    def __init__(
+        self,
+        data_path,
+        streams=None,
+        processing_label=None,
+        data_type="background",
+        restricted=False,
+        verbose=True,
+    ):
+        self._verbose = verbose
+
+        self._processing_label = processing_label
+        self._restricted = restricted
+        self._data_type = data_type
+
+        catalog_full = AcquisitionCatalog(data_path, verbose=verbose)
+        self._catalog = catalog_full.filter(
+            streams=streams,
+            measurement_types=data_type,
+            restricted=restricted,
+        )
+
+        selected_data = self._catalog.select_files_by_stream(
+            stream_key="stream_id"
+        )
+        if not selected_data:
+            raise ValueError("No files were found! Check configuration...")
+
+        self._files_by_stream = copy.deepcopy(selected_data)
+        self._streams = list(selected_data.keys())
+
+        acquisition_path = Path(self._catalog.acquisition_path)
+        self._acquisition_name = self._catalog.acquisition_name
+        self._input_base_path = str(acquisition_path.parent)
+
+        match = re.search(r"_I(\d+)", self._acquisition_name)
+        if not match:
+            raise ValueError(
+                "ERROR: No facility found from acquisition name!"
+            )
+        self._facility = int(match.group(1))
+
+        self._duration_s = self._catalog.get_duration()
+        if self._verbose:
+            print(
+                "INFO: Total raw data duration = "
+                f"{self._duration_s / 60} minutes"
+            )
+
+        self._storage_format = self._catalog.storage_format
+        self._sample_rate_hz = self._catalog.sample_rate_hz
+
+        self._output_path = None
+        self._dataframe_group = None
+        self._nrandoms = None
+        self._randoms_livetime_s = 0.0
+
+    @property
+    def verbose(self):
+        return self._verbose
+
+    @verbose.setter
+    def verbose(self, value):
+        self._verbose = value
+
+    def get_base_path(self):
+        return self._input_base_path
+
+    def get_acquisition_name(self):
+        return self._acquisition_name
+
+    def get_output_path(self):
+        """Get output acquisition path."""
+        return self._output_path
+
+    def process(
+        self,
+        random_rate=None,
+        nrandoms=None,
+        min_separation_msec=0,
+        edge_exclusion_msec=0,
+        edge_exclusion_samples=None,
+        partition_target_duration_s=None,
+        random_seed=None,
+        lgc_save=False,
+        lgc_output=False,
+        save_path=None,
+        output_dir_name=None,
+    ):
+        """Generate random triggers.
+
+        Exactly one of ``random_rate`` or ``nrandoms`` must be provided.
+
+        Parameters
+        ----------
+        random_rate : float, optional
+            Requested average random-trigger rate in Hz. The total generated
+            count is ``round(random_rate * eligible_livetime)``.
+        nrandoms : int, optional
+            Exact number of random triggers to generate. If the requested
+            number cannot satisfy ``min_separation_msec`` within the eligible
+            regions, a ValueError is raised.
+        min_separation_msec : float
+            Minimum separation between triggers selected from the same region.
+            For HDF5 a region is one segment. For partitioned Zarr it is one
+            logical partition. For whole-stream Zarr it is one stream.
+        edge_exclusion_msec : float
+            Exclusion applied to both edges of each selection region.
+        edge_exclusion_samples : int, optional
+            Same as ``edge_exclusion_msec`` but specified directly in samples.
+            Takes precedence when provided.
+        partition_target_duration_s : float, optional
+            For Zarr, use logical processing partitions near this duration.
+            If None, select across each entire continuous Zarr stream. HDF5
+            always uses stored segments.
+        random_seed : int, optional
+            Seed for reproducible count allocation and trigger selection.
+        lgc_save : bool
+            If True, save the generated random-trigger dataframe.
+        lgc_output : bool
+            If True, return the generated Vaex dataframe.
+        save_path : str, optional
+            Base output path used when ``lgc_save=True``.
+        output_dir_name : str, optional
+            Optional output directory name used when ``lgc_save=True``.
+        """
+
+        self._validate_selection_arguments(
+            random_rate=random_rate,
+            nrandoms=nrandoms,
+            min_separation_msec=min_separation_msec,
+            edge_exclusion_msec=edge_exclusion_msec,
+            edge_exclusion_samples=edge_exclusion_samples,
+        )
+
+        if edge_exclusion_samples is not None:
+            edge_exclusion_samples = int(edge_exclusion_samples)
+        else:
+            edge_exclusion_samples = int(
+                ceil(
+                    float(edge_exclusion_msec)
+                    * self._sample_rate_hz
+                    / 1000.0
+                )
+            )
+
+        min_separation_samples = int(
+            ceil(
+                float(min_separation_msec)
+                * self._sample_rate_hz
+                / 1000.0
+            )
+        )
+
+        regions_by_stream = self._build_selection_regions(
+            edge_exclusion_samples=edge_exclusion_samples,
+            min_separation_samples=min_separation_samples,
+            partition_target_duration_s=partition_target_duration_s,
+        )
+        all_regions = [
+            region
+            for stream_regions in regions_by_stream.values()
+            for region in stream_regions
+        ]
+
+        total_usable_samples = sum(
+            region.usable_samples for region in all_regions
+        )
+        self._randoms_livetime_s = (
+            total_usable_samples / float(self._sample_rate_hz)
+        )
+        if self._verbose:
+            print(
+                "INFO: Livetime for randoms = "
+                f"{self._randoms_livetime_s / 60} minutes"
+            )
+
+        if total_usable_samples <= 0:
+            raise ValueError(
+                "ERROR: No eligible samples remain after edge exclusion."
+            )
+
+        if nrandoms is not None:
+            target_nrandoms = int(nrandoms)
+        else:
+            target_nrandoms = int(
+                round(float(random_rate) * self._randoms_livetime_s)
+            )
+
+        total_capacity = sum(region.capacity for region in all_regions)
+        if target_nrandoms > total_capacity:
+            max_rate = total_capacity / self._randoms_livetime_s
+            raise ValueError(
+                "ERROR: Requested random selection is not possible with the "
+                "specified edge exclusion and minimum separation. "
+                f"Requested={target_nrandoms}, maximum={total_capacity}, "
+                f"eligible_livetime_s={self._randoms_livetime_s:.6g}, "
+                f"maximum_average_rate_hz={max_rate:.6g}."
+            )
+
+        self._nrandoms = target_nrandoms
+
+        rng = random.Random(random_seed)
+        region_counts = self._allocate_exact_counts(
+            all_regions,
+            target_nrandoms,
+            rng=rng,
+        )
+
+        output_path = None
+        dataframe_group = None
+        if lgc_save:
+            if save_path is None:
+                save_path = str(Path(self._input_base_path) / "processed")
+                save_path = save_path.replace("/raw/processed", "/processed")
+
+            if self._acquisition_name not in str(save_path):
+                save_path = str(Path(save_path) / self._acquisition_name)
+
+            dataframe_group = create_dataframe_group(
+                save_path, dataframe_type="randoms", facility=self._facility,
+                processing_label=self._processing_label,
+                restricted=self._restricted, data_type=self._data_type,
+                output_group_name=output_dir_name,
+            )
+            output_path = dataframe_group.path
+            if self._verbose:
+                print(
+                    "INFO: Processing output acquisition path: "
+                    f"{output_path}"
+                )
+
+        self._output_path = output_path
+        self._dataframe_group = dataframe_group
+
+        output_df = self._generate_dataframe(
+            regions_by_stream=regions_by_stream,
+            region_counts=region_counts,
+            min_separation_samples=min_separation_samples,
+            edge_exclusion_samples=edge_exclusion_samples,
+            partition_target_duration_s=partition_target_duration_s,
+            rng=rng,
+            dataframe_group=dataframe_group,
+        )
+
+        actual = len(output_df)
+        if actual != target_nrandoms:
+            raise RuntimeError(
+                "ERROR: Internal random-selection count mismatch: "
+                f"expected {target_nrandoms}, generated {actual}."
+            )
+
+        if lgc_save:
+            self._save_dataframe(output_df, dataframe_group=dataframe_group)
+
+        if self._verbose:
+            print(
+                "INFO: Randoms acquisition done! "
+                f"Generated {target_nrandoms} randoms."
+            )
+
+        if lgc_output:
+            return output_df
+        return None
+
+    def _build_selection_regions(
+        self,
+        *,
+        edge_exclusion_samples,
+        min_separation_samples,
+        partition_target_duration_s,
+    ):
+        """Build HDF5-segment or Zarr stream/partition selection regions."""
+
+        regions_by_stream = {}
+        self._stream_length_samples_by_stream = {}
+        region_id = 0
+
+        for stream_id in self._streams:
+            catalog_stream = self._catalog.filter(streams=stream_id)
+            sample_rate_hz = catalog_stream.sample_rate_hz
+            if not np.isclose(sample_rate_hz, self._sample_rate_hz):
+                raise ValueError(
+                    "ERROR: Randoms currently requires one common sample rate "
+                    "across selected streams."
+                )
+
+            stream_regions = []
+
+            if self._storage_format == "hdf5":
+                stream_start_index = 0
+                entries = sorted(
+                    catalog_stream.entries,
+                    key=lambda entry: int(entry.get("dump_num", 0)),
+                )
+
+                for entry in entries:
+                    dump_num = int(entry["dump_num"])
+                    n_segments = int(entry.get("n_segments") or 0)
+                    segment_length_samples = entry.get("segment_length_samples")
+                    if segment_length_samples is None:
+                        segment_duration_s = entry.get("segment_duration_s")
+                        if segment_duration_s is None:
+                            raise ValueError(
+                                "ERROR: Unable to determine HDF5 segment length "
+                                f"for dump {dump_num}."
+                            )
+                        segment_length_samples = int(
+                            round(float(segment_duration_s) * sample_rate_hz)
+                        )
+                    segment_length_samples = int(segment_length_samples)
+
+                    for segment_num in range(1, n_segments + 1):
+                        usable_start, usable_stop, usable_samples, capacity = (
+                            self._region_limits(
+                                segment_length_samples,
+                                edge_exclusion_samples,
+                                min_separation_samples,
+                            )
+                        )
+                        stream_regions.append(
+                            _SelectionRegion(
+                                region_id=region_id,
+                                stream_id=stream_id,
+                                start_index=stream_start_index,
+                                length_samples=segment_length_samples,
+                                usable_start_index=usable_start,
+                                usable_stop_index=usable_stop,
+                                usable_samples=usable_samples,
+                                capacity=capacity,
+                                dump_num=dump_num,
+                                global_segment_num=(
+                                    dump_num * 100000 + segment_num
+                                ),
+                            )
+                        )
+                        region_id += 1
+                        stream_start_index += segment_length_samples
+
+            elif self._storage_format == "zarr":
+                stream_length_samples = int(catalog_stream.n_samples)
+
+                if partition_target_duration_s is None:
+                    usable_start, usable_stop, usable_samples, capacity = (
+                        self._region_limits(
+                            stream_length_samples,
+                            edge_exclusion_samples,
+                            min_separation_samples,
+                        )
+                    )
+                    stream_regions.append(
+                        _SelectionRegion(
+                            region_id=region_id,
+                            stream_id=stream_id,
+                            start_index=0,
+                            length_samples=stream_length_samples,
+                            usable_start_index=usable_start,
+                            usable_stop_index=usable_stop,
+                            usable_samples=usable_samples,
+                            capacity=capacity,
+                        )
+                    )
+                    region_id += 1
+                else:
+                    stream_plan = catalog_stream.plan_partitions(
+                        partition_target_duration_s
+                    )[0]
+                    partition_length_samples = int(
+                        stream_plan["partition_length_samples"]
+                    )
+
+                    for partition in stream_plan["partitions"]:
+                        partition_index = int(partition["partition_index"])
+                        partition_start_index = int(
+                            partition["partition_start_index"]
+                        )
+                        (
+                            usable_start,
+                            usable_stop,
+                            usable_samples,
+                            capacity,
+                        ) = self._region_limits(
+                            partition_length_samples,
+                            edge_exclusion_samples,
+                            min_separation_samples,
+                        )
+                        stream_regions.append(
+                            _SelectionRegion(
+                                region_id=region_id,
+                                stream_id=stream_id,
+                                start_index=partition_start_index,
+                                length_samples=partition_length_samples,
+                                usable_start_index=usable_start,
+                                usable_stop_index=usable_stop,
+                                usable_samples=usable_samples,
+                                capacity=capacity,
+                                partition_index=partition_index,
+                                partition_start_index=partition_start_index,
+                                partition_length_samples=(
+                                    partition_length_samples
+                                ),
+                            )
+                        )
+                        region_id += 1
+            else:
+                raise ValueError(
+                    f'ERROR: Unsupported storage format "{self._storage_format}".'
+                )
+
+            regions_by_stream[stream_id] = stream_regions
+            if self._storage_format == "hdf5":
+                self._stream_length_samples_by_stream[stream_id] = (
+                    stream_start_index
+                )
+            else:
+                self._stream_length_samples_by_stream[stream_id] = (
+                    stream_length_samples
+                )
+
+        return regions_by_stream
+
+    @staticmethod
+    def _region_limits(
+        length_samples,
+        edge_exclusion_samples,
+        min_separation_samples,
+    ):
+        """Return usable interval and maximum trigger capacity for a region."""
+
+        length_samples = int(length_samples)
+        edge = int(edge_exclusion_samples)
+        min_sep = int(min_separation_samples)
+
+        usable_start = edge
+        usable_stop = length_samples - edge
+        usable_samples = max(0, usable_stop - usable_start)
+
+        if usable_samples == 0:
+            capacity = 0
+        else:
+            spacing = max(1, min_sep)
+            capacity = 1 + (usable_samples - 1) // spacing
+
+        return usable_start, usable_stop, usable_samples, capacity
+
+    @staticmethod
+    def _allocate_exact_counts(regions, total_count, *, rng):
+        """Allocate exactly ``total_count`` among regions.
+
+        Allocation is proportional to eligible samples, but each region is
+        capped by its minimum-separation capacity. Fractional ties are broken
+        randomly so equal-sized partitions are not systematically favored.
+        """
+
+        total_count = int(total_count)
+        if total_count < 0:
+            raise ValueError("nrandoms must be non-negative")
+
+        counts = {region.region_id: 0 for region in regions}
+        if total_count == 0:
+            return counts
+
+        if total_count > sum(region.capacity for region in regions):
+            raise ValueError("Requested count exceeds total region capacity")
+
+        active = [region for region in regions if region.capacity > 0]
+        remaining = total_count
+
+        while remaining > 0:
+            active = [
+                region
+                for region in active
+                if counts[region.region_id] < region.capacity
+            ]
+            if not active:
+                raise RuntimeError("Unable to allocate requested random count")
+
+            total_weight = sum(region.usable_samples for region in active)
+            if total_weight <= 0:
+                raise RuntimeError("No eligible samples available for allocation")
+
+            quotas = {
+                region.region_id: (
+                    remaining * region.usable_samples / total_weight
+                )
+                for region in active
+            }
+
+            allocated_this_round = 0
+            for region in active:
+                room = region.capacity - counts[region.region_id]
+                add = min(room, int(np.floor(quotas[region.region_id])))
+                if add > 0:
+                    counts[region.region_id] += add
+                    allocated_this_round += add
+
+            remaining -= allocated_this_round
+            if remaining == 0:
+                break
+
+            active = [
+                region
+                for region in active
+                if counts[region.region_id] < region.capacity
+            ]
+            if not active:
+                raise RuntimeError("Unable to allocate requested random count")
+
+            # Largest remainder, with random tie breaking for equal regions.
+            ranked = sorted(
+                active,
+                key=lambda region: (
+                    quotas.get(region.region_id, 0.0)
+                    - np.floor(quotas.get(region.region_id, 0.0)),
+                    rng.random(),
+                ),
+                reverse=True,
+            )
+
+            for region in ranked:
+                if remaining == 0:
+                    break
+                if counts[region.region_id] >= region.capacity:
+                    continue
+                counts[region.region_id] += 1
+                remaining -= 1
+
+        return counts
+
+    @staticmethod
+    def _sample_trigger_indices(region, count, min_separation_samples, *, rng):
+        """Sample exact local trigger indices with minimum separation."""
+
+        count = int(count)
+        if count == 0:
+            return np.empty(0, dtype=np.int64)
+        if count > region.capacity:
+            raise ValueError(
+                f"Requested {count} triggers from region capacity "
+                f"{region.capacity}."
+            )
+
+        spacing = max(1, int(min_separation_samples))
+        usable_count = int(region.usable_samples)
+
+        # Compress away the required gaps, sample distinct compressed
+        # positions, then reinsert the gaps. This avoids building a potentially
+        # enormous list(range(...)) for long continuous streams.
+        compressed_count = usable_count - (count - 1) * (spacing - 1)
+        if compressed_count < count:
+            raise ValueError(
+                "Requested random count cannot satisfy minimum separation."
+            )
+
+        reduced = sorted(rng.sample(range(compressed_count), count))
+        trigger_indices = np.asarray(reduced, dtype=np.int64)
+        trigger_indices += np.arange(count, dtype=np.int64) * (spacing - 1)
+        trigger_indices += int(region.usable_start_index)
+
+        return trigger_indices
+
+    def _generate_dataframe(
+        self,
+        *,
+        regions_by_stream,
+        region_counts,
+        min_separation_samples,
+        edge_exclusion_samples,
+        partition_target_duration_s,
+        rng,
+        dataframe_group,
+    ):
+        """Generate one dataframe for all selected streams."""
+
+        dataframe_metadata = {}
+        if dataframe_group is not None:
+            dataframe_metadata = dataframe_group.row_metadata(1)
+
+        feature_dict = self._initialize_feature_dict(
+            include_hdf5=(self._storage_format == "hdf5"),
+            include_partition=(
+                self._storage_format == "zarr"
+                and partition_target_duration_s is not None
+            ),
+        )
+
+        for stream_id in self._streams:
+            stream_regions = regions_by_stream[stream_id]
+            n_stream_randoms = sum(
+                region_counts[region.region_id]
+                for region in stream_regions
+            )
+            if n_stream_randoms == 0:
+                continue
+
+            if self._verbose:
+                print(
+                    f"INFO: Acquiring {n_stream_randoms} randoms "
+                    f"for stream {stream_id}"
+                )
+
+            catalog_stream = self._catalog.filter(streams=stream_id)
+            sample_rate_hz = float(catalog_stream.sample_rate_hz)
+            catalog_entries = catalog_stream.entries
+            stream_length_samples = int(
+                self._stream_length_samples_by_stream[stream_id]
+            )
+
+            first_entry = catalog_entries[0]
+            acquisition_num = first_entry["acquisition_num"]
+            acquisition_start = first_entry.get("acquisition_start")
+            fridge_run_start = first_entry.get("fridge_run_start")
+            fridge_run = first_entry.get("fridge_run")
+            stream_start = first_entry.get("stream_start")
+            stream_num = first_entry["stream_num"]
+
+            stream_trigger_id = 0
+            for region in stream_regions:
+                count = region_counts[region.region_id]
+                if count == 0:
+                    continue
+
+                trigger_indices = self._sample_trigger_indices(
+                    region,
+                    count,
+                    min_separation_samples,
+                    rng=rng,
+                )
+
+                for local_trigger_index in trigger_indices:
+                    local_trigger_index = int(local_trigger_index)
+                    stream_trigger_id += 1
+                    stream_trigger_index = (
+                        region.start_index + local_trigger_index
+                    )
+
+                    self._append_feature_row(
+                        feature_dict,
+                        acquisition_num=acquisition_num,
+                        stream_num=stream_num,
+                        fridge_run=fridge_run,
+                        stream_start=stream_start,
+                        acquisition_start=acquisition_start,
+                        fridge_run_start=fridge_run_start,
+                        stream_trigger_index=stream_trigger_index,
+                        stream_trigger_id=stream_trigger_id,
+                        stream_length_samples=stream_length_samples,
+                        sample_rate_hz=sample_rate_hz,
+                        min_separation_samples=min_separation_samples,
+                        edge_exclusion_samples=edge_exclusion_samples,
+                        dataframe_metadata=dataframe_metadata,
+                        region=region,
+                        local_trigger_index=local_trigger_index,
+                    )
+
+        return vx.from_dict(feature_dict)
+
+    def _save_dataframe(self, dataframe, *, dataframe_group):
+        """Save the generated random-trigger dataframe as one F0001 shard."""
+        dataframe.export_hdf5(dataframe_group.file_path(1), mode="w")
+
+    def _initialize_feature_dict(self, *, include_hdf5, include_partition):
+        feature_dict = {
+            "acquisition_number": [],
+            "storage_format": [],
+            "stream_id": [],
+            "stream_number": [],
+            "fridge_run_number": [],
+            "data_type": [],
+            "stream_start": [],
+            "acquisition_start": [],
+            "fridge_run_start": [],
+            "stream_trigger_index": [],
+            "stream_trigger_time_s": [],
+            "stream_length_samples": [],
+            "stream_trigger_id": [],
+            "trigger_type": [],
+            "randoms_min_separation_time_s": [],
+            "randoms_edge_exclusion_time_s": [],
+            "randoms_livetime_s": [],
+            "dataframe_type": [],
+            "dataframe_group_name": [],
+            "dataframe_group_id": [],
+            "dataframe_group_number": [],
+            "dataframe_file_index": [],
+            "processing_label": [],
+        }
+
+        if include_hdf5:
+            feature_dict.update(
+                {
+                    "dump_number": [],
+                    "global_segment_number": [],
+                    "segment_trigger_index": [],
+                    "segment_trigger_time_s": [],
+                    "segment_length_samples": [],
+                }
+            )
+
+        if include_partition:
+            feature_dict.update(
+                {
+                    "partition_start_time_s": [],
+                    "partition_start_index": [],
+                    "partition_trigger_time_s": [],
+                    "partition_trigger_index": [],
+                    "partition_length_samples": [],
+                }
+            )
+
+        return feature_dict
+
+    def _append_feature_row(
+        self,
+        feature_dict,
+        *,
+        acquisition_num,
+        stream_num,
+        fridge_run,
+        stream_start,
+        acquisition_start,
+        fridge_run_start,
+        stream_trigger_index,
+        stream_trigger_id,
+        stream_length_samples,
+        sample_rate_hz,
+        min_separation_samples,
+        edge_exclusion_samples,
+        dataframe_metadata,
+        region,
+        local_trigger_index,
+    ):
+        feature_dict["acquisition_number"].append(acquisition_num)
+        feature_dict["storage_format"].append(self._storage_format)
+        feature_dict["stream_id"].append(region.stream_id)
+        feature_dict["stream_number"].append(stream_num)
+        feature_dict["fridge_run_number"].append(fridge_run)
+        feature_dict["data_type"].append(self._data_type)
+        feature_dict["stream_start"].append(stream_start)
+        feature_dict["acquisition_start"].append(acquisition_start)
+        feature_dict["fridge_run_start"].append(fridge_run_start)
+        feature_dict["stream_trigger_index"].append(stream_trigger_index)
+        feature_dict["stream_trigger_time_s"].append(
+            stream_trigger_index / sample_rate_hz
+        )
+        feature_dict["stream_length_samples"].append(stream_length_samples)
+        feature_dict["stream_trigger_id"].append(stream_trigger_id)
+        feature_dict["trigger_type"].append(3)
+        feature_dict["randoms_min_separation_time_s"].append(
+            min_separation_samples / sample_rate_hz
+        )
+        feature_dict["randoms_edge_exclusion_time_s"].append(
+            edge_exclusion_samples / sample_rate_hz
+        )
+        feature_dict["randoms_livetime_s"].append(
+            self._randoms_livetime_s
+        )
+        feature_dict["dataframe_type"].append(
+            dataframe_metadata.get("dataframe_type", np.nan)
+        )
+        feature_dict["dataframe_group_name"].append(
+            dataframe_metadata.get("dataframe_group_name", np.nan)
+        )
+        feature_dict["dataframe_group_id"].append(
+            dataframe_metadata.get("dataframe_group_id", np.nan)
+        )
+        feature_dict["dataframe_group_number"].append(
+            dataframe_metadata.get("dataframe_group_number", np.nan)
+        )
+        feature_dict["dataframe_file_index"].append(
+            dataframe_metadata.get("dataframe_file_index", np.nan)
+        )
+        feature_dict["processing_label"].append(
+            dataframe_metadata.get("processing_label", None)
+        )
+
+        if self._storage_format == "hdf5":
+            feature_dict["dump_number"].append(region.dump_num)
+            feature_dict["global_segment_number"].append(
+                region.global_segment_num
+            )
+            feature_dict["segment_trigger_index"].append(
+                local_trigger_index
+            )
+            feature_dict["segment_trigger_time_s"].append(
+                local_trigger_index / sample_rate_hz
+            )
+            feature_dict["segment_length_samples"].append(
+                region.length_samples
+            )
+
+        elif region.partition_start_index is not None:
+            feature_dict["partition_start_time_s"].append(
+                region.partition_start_index / sample_rate_hz
+            )
+            feature_dict["partition_start_index"].append(
+                region.partition_start_index
+            )
+            feature_dict["partition_trigger_index"].append(
+                local_trigger_index
+            )
+            feature_dict["partition_trigger_time_s"].append(
+                local_trigger_index / sample_rate_hz
+            )
+            feature_dict["partition_length_samples"].append(
+                region.partition_length_samples
+            )
+
+    @staticmethod
+    def _validate_selection_arguments(
+        *,
+        random_rate,
+        nrandoms,
+        min_separation_msec,
+        edge_exclusion_msec,
+        edge_exclusion_samples,
+    ):
+        if (random_rate is None) == (nrandoms is None):
+            raise ValueError(
+                'ERROR: Use exactly one of "random_rate" or "nrandoms".'
+            )
+
+        if random_rate is not None and float(random_rate) <= 0:
+            raise ValueError("ERROR: random_rate must be positive.")
+
+        if nrandoms is not None:
+            if int(nrandoms) != nrandoms or int(nrandoms) < 0:
+                raise ValueError(
+                    "ERROR: nrandoms must be a non-negative integer."
+                )
+
+        if float(min_separation_msec) < 0:
+            raise ValueError(
+                "ERROR: min_separation_msec must be non-negative."
+            )
+        if float(edge_exclusion_msec) < 0:
+            raise ValueError(
+                "ERROR: edge_exclusion_msec must be non-negative."
+            )
+        if (
+            edge_exclusion_samples is not None
+            and int(edge_exclusion_samples) < 0
+        ):
+            raise ValueError(
+                "ERROR: edge_exclusion_samples must be non-negative."
+            )
+
+    def _create_output_directory(
+        self, base_path, facility, output_dir_name=None, restricted=False,
+        data_type="background",
+    ):
+        """Compatibility wrapper around the common dataframe-group helper."""
+        group = create_dataframe_group(
+            base_path, dataframe_type="randoms", facility=facility,
+            processing_label=self._processing_label, restricted=restricted,
+            data_type=data_type, output_group_name=output_dir_name,
+        )
+        return group.path, group.group_number