nullcal 0.2.0__py3-none-any.whl

nullcal/__init__.py

@@ -0,0 +1,16 @@
+"""
+A package to constrain calibration errors of a closed-geometry network
+of gravitational-wave detectors.
+"""
+
+from __future__ import annotations
+
+from .utils.log import setup_logger
+from .version import __version__
+
+setup_logger()
+
+
+__all__ = [
+    "__version__",
+]

nullcal/calibration.py

@@ -0,0 +1,189 @@
+"""Pure JAX calibration model and Gaussian knot-prior functions.
+
+The spline interpolates amplitude and latent phase in log10 frequency using
+not-a-knot boundary conditions. It matches the archived reference model on a
+uniform log-frequency grid and also permits nonuniform knot placement.
+
+Importing this module enables JAX's process-wide ``jax_enable_x64`` setting.
+Calibration inference requires float64 precision, so this side effect is an
+intentional part of the module's public behavior.
+"""
+
+from __future__ import annotations
+
+import jax
+
+# Calibration inference needs substantially more precision than JAX's default
+# float32 mode.  Enable x64 before importing jax.numpy so every public function
+# can explicitly construct float64 inputs and complex128 outputs.
+jax.config.update("jax_enable_x64", True)
+
+import jax.numpy as jnp  # noqa: E402
+
+MINIMUM_CUBIC_SPLINE_KNOTS = 4
+
+
+def _float64(values):
+    """Return ``values`` as a JAX float64 array."""
+    return jnp.asarray(values, dtype=jnp.float64)
+
+
+def _validate_prior_shapes(values, mean, sigma, parameter):
+    """Require array hyperparameters to match their knot-value shape."""
+    if (mean.ndim != 0 and mean.shape != values.shape) or (sigma.ndim != 0 and sigma.shape != values.shape):
+        raise ValueError(f"{parameter} mean and sigma must be scalar or match the value shape")
+
+
+def _not_a_knot_second_derivatives(log_knots, node_values):
+    """Solve the nonuniform not-a-knot cubic-spline continuity equations."""
+    knot_count = log_knots.shape[0]
+    widths = jnp.diff(log_knots)
+    system = jnp.zeros((knot_count, knot_count), dtype=jnp.float64)
+    right_hand_side = jnp.zeros(knot_count, dtype=jnp.float64)
+
+    system = system.at[0, :3].set(jnp.array((-widths[1], widths[0] + widths[1], -widths[0])))
+    system = system.at[-1, -3:].set(jnp.array((widths[-1], -(widths[-2] + widths[-1]), widths[-2])))
+
+    interior = jnp.arange(1, knot_count - 1)
+    left_widths = widths[:-1]
+    right_widths = widths[1:]
+    system = system.at[interior, interior - 1].set(left_widths)
+    system = system.at[interior, interior].set(2.0 * (left_widths + right_widths))
+    system = system.at[interior, interior + 1].set(right_widths)
+    right_hand_side = right_hand_side.at[interior].set(
+        6.0
+        * ((node_values[2:] - node_values[1:-1]) / right_widths - (node_values[1:-1] - node_values[:-2]) / left_widths)
+    )
+    return jnp.linalg.solve(system, right_hand_side)
+
+
+def _evaluate_spline(frequencies, knot_frequencies, node_values):
+    """Evaluate a not-a-knot cubic spline in log10 frequency."""
+    log_knots = jnp.log10(knot_frequencies)
+    log_frequencies = jnp.log10(frequencies)
+    second_derivatives = _not_a_knot_second_derivatives(log_knots, node_values)
+    intervals = jnp.searchsorted(log_knots, log_frequencies, side="right") - 1
+    intervals = jnp.clip(intervals, 0, log_knots.size - 2)
+
+    left = log_knots[intervals]
+    right = log_knots[intervals + 1]
+    widths = right - left
+    left_distance = right - log_frequencies
+    right_distance = log_frequencies - left
+    return (
+        second_derivatives[intervals] * left_distance**3 / (6.0 * widths)
+        + second_derivatives[intervals + 1] * right_distance**3 / (6.0 * widths)
+        + (node_values[intervals] - second_derivatives[intervals] * widths**2 / 6.0) * left_distance / widths
+        + (node_values[intervals + 1] - second_derivatives[intervals + 1] * widths**2 / 6.0) * right_distance / widths
+    )
+
+
+def calibration_factor(frequencies, knot_frequencies, amplitude, phase):
+    """Evaluate the reference cubic-spline calibration factor in explicit float64.
+
+    Args:
+        frequencies: Positive frequencies at which to evaluate the factor.
+        knot_frequencies: At least four positive, strictly increasing knots.
+            Knot placement and count are function parameters; nonuniform grids
+            such as the 19-knot spectroscopy grid are supported.
+        amplitude: Fractional amplitude error at each knot.
+        phase: Latent phase parameter at each knot, in radians.
+
+    Returns:
+        A complex128 array equal to ``(1 + amplitude_spline) *
+        (2 + 1j * phase_spline) / (2 - 1j * phase_spline)``.
+    """
+    frequencies = _float64(frequencies)
+    knot_frequencies = _float64(knot_frequencies)
+    amplitude = _float64(amplitude)
+    phase = _float64(phase)
+    if frequencies.ndim != 1 or knot_frequencies.ndim != 1 or amplitude.ndim != 1 or phase.ndim != 1:
+        raise ValueError("frequencies, knots, amplitude, and phase must be one-dimensional")
+    if knot_frequencies.size < MINIMUM_CUBIC_SPLINE_KNOTS:
+        raise ValueError("a cubic spline requires at least four knots")
+    if amplitude.shape != knot_frequencies.shape or phase.shape != knot_frequencies.shape:
+        raise ValueError("amplitude and phase must contain one value per knot")
+    delta_amplitude = _evaluate_spline(frequencies, knot_frequencies, amplitude)
+    delta_phase = _evaluate_spline(frequencies, knot_frequencies, phase)
+    imaginary_phase = jnp.asarray(1j, dtype=jnp.complex128) * delta_phase
+    return (1.0 + delta_amplitude) * (2.0 + imaginary_phase) / (2.0 - imaginary_phase)
+
+
+def calibration_log_prior(
+    amplitude,
+    phase,
+    amplitude_mean,
+    amplitude_sigma,
+    phase_mean,
+    phase_sigma,
+):
+    """Return the normalized independent-Gaussian log-prior for knot values."""
+    amplitude = _float64(amplitude)
+    phase = _float64(phase)
+    amplitude_mean = _float64(amplitude_mean)
+    amplitude_sigma = _float64(amplitude_sigma)
+    phase_mean = _float64(phase_mean)
+    phase_sigma = _float64(phase_sigma)
+    _validate_prior_shapes(amplitude, amplitude_mean, amplitude_sigma, "amplitude")
+    _validate_prior_shapes(phase, phase_mean, phase_sigma, "phase")
+
+    def gaussian_log_prob(values, means, sigmas):
+        return -0.5 * jnp.sum(((values - means) / sigmas) ** 2 + jnp.log(2.0 * jnp.pi * sigmas**2))
+
+    return gaussian_log_prob(amplitude, amplitude_mean, amplitude_sigma) + gaussian_log_prob(
+        phase, phase_mean, phase_sigma
+    )
+
+
+def calibration_parameters_to_unconstrained(
+    amplitude,
+    phase,
+    amplitude_mean,
+    amplitude_sigma,
+    phase_mean,
+    phase_sigma,
+):
+    """Map physical Gaussian knot values to standard-normal coordinates."""
+    amplitude = _float64(amplitude)
+    phase = _float64(phase)
+    amplitude_mean = _float64(amplitude_mean)
+    amplitude_sigma = _float64(amplitude_sigma)
+    phase_mean = _float64(phase_mean)
+    phase_sigma = _float64(phase_sigma)
+    _validate_prior_shapes(amplitude, amplitude_mean, amplitude_sigma, "amplitude")
+    _validate_prior_shapes(phase, phase_mean, phase_sigma, "phase")
+    return (
+        (amplitude - amplitude_mean) / amplitude_sigma,
+        (phase - phase_mean) / phase_sigma,
+    )
+
+
+def unconstrained_to_calibration_parameters(
+    unconstrained_amplitude,
+    unconstrained_phase,
+    amplitude_mean,
+    amplitude_sigma,
+    phase_mean,
+    phase_sigma,
+):
+    """Map standard-normal coordinates to physical Gaussian knot values."""
+    unconstrained_amplitude = _float64(unconstrained_amplitude)
+    unconstrained_phase = _float64(unconstrained_phase)
+    amplitude_mean = _float64(amplitude_mean)
+    amplitude_sigma = _float64(amplitude_sigma)
+    phase_mean = _float64(phase_mean)
+    phase_sigma = _float64(phase_sigma)
+    _validate_prior_shapes(unconstrained_amplitude, amplitude_mean, amplitude_sigma, "amplitude")
+    _validate_prior_shapes(unconstrained_phase, phase_mean, phase_sigma, "phase")
+    return (
+        amplitude_mean + amplitude_sigma * unconstrained_amplitude,
+        phase_mean + phase_sigma * unconstrained_phase,
+    )
+
+
+__all__ = [
+    "calibration_factor",
+    "calibration_log_prior",
+    "calibration_parameters_to_unconstrained",
+    "unconstrained_to_calibration_parameters",
+]

nullcal/clustering/base.py

@@ -0,0 +1,39 @@
+"""A submodule for clustering."""
+
+import numpy as np
+
+from ..time_frequency_transform.wavelet_transforms import WaveletTransform
+
+
+class Clustering:
+    """A base class to handle time-frequency clustering."""
+
+    def __init__(self, time_frequency_transform: WaveletTransform):
+        """A class to handle time-frequency clustering.
+
+        Args:
+            time_frequency_transform (WaveletTransform): Wavelet transform instance.
+        """
+        self.time_frequency_transform = time_frequency_transform
+        self._time_frequency_filter = None
+
+    @property
+    def shape(self) -> tuple:
+        """Get the shape of the time-frequency transform.
+
+        Returns:
+            tuple: Shape of time-frequency transform.
+                (n_time, n_freq).
+        """
+        return self.time_frequency_transform.shape
+
+    @property
+    def time_frequency_filter(self) -> np.ndarray:
+        """Get the time-frequency filter.
+
+        Returns:
+            np.ndarray: Time-frequency filter.
+        """
+        if self._time_frequency_filter is None:
+            raise ValueError("self._time_frequency_filter is None.")
+        return self._time_frequency_filter

nullcal/clustering/injection.py

@@ -0,0 +1,63 @@
+"""Clustering over injected strain prepared outside the likelihood."""
+
+import logging
+from collections.abc import Iterable
+
+import numpy as np
+
+from ..data import InterferometerData
+from ..time_frequency_transform.wavelet_transforms import WaveletTransform
+from .base import Clustering
+from .single import single_clustering_by_threshold
+
+logger = logging.getLogger("nullcal")
+
+
+class InjectionClustering(Clustering):
+    """Clustering method using waveform injections."""
+
+    def __init__(
+        self,
+        time_frequency_transform: WaveletTransform,
+        injections: Iterable[InterferometerData],
+        threshold: float,
+        minimum_frequency: float | None = None,
+        maximum_frequency: float | None = None,
+    ):
+        """Clustering method using waveform injections.
+
+        Args:
+            time_frequency_transform (WaveletTransform): A WaveletTransform instance.
+            injections (Iterable[InterferometerData]): Zero-noise injected
+                strain prepared by a loader or waveform package.
+            threshold (float): The threshold to select time-frequency pixels.
+            minimum_frequency (float, optional): Lowest clustering frequency.
+            maximum_frequency (float, optional): Highest clustering frequency.
+        """
+        super().__init__(time_frequency_transform=time_frequency_transform)
+        injections = tuple(injections)
+        if not injections:
+            raise ValueError("injections must contain at least one prepared data set")
+        filters = [
+            single_clustering_by_threshold(
+                interferometers=injection,
+                time_frequency_transform=self.time_frequency_transform,
+                threshold=threshold,
+                padding_time=0.0,
+                padding_freq=0.0,
+                minimum_frequency=minimum_frequency,
+                maximum_frequency=maximum_frequency,
+            )
+            for injection in injections
+        ]
+        self._time_frequency_filter = np.logical_or.reduce(filters)
+        logger.info("Injection clustering preprocessing done.")
+
+    @property
+    def time_frequency_filter(self) -> np.ndarray:
+        """Get the time-frequency filter.
+
+        Returns:
+            np.ndarray: Time-frequency filter.
+        """
+        return self._time_frequency_filter

nullcal/clustering/precompute.py

@@ -0,0 +1,30 @@
+"""
+A class to handle pre-computed clustering.
+"""
+
+import numpy as np
+
+from ..time_frequency_transform.wavelet_transforms import WaveletTransform
+from .base import Clustering
+
+
+class PrecomputedClustering(Clustering):
+    """Pre-computed clustering."""
+
+    def __init__(self, time_frequency_transform: WaveletTransform, time_frequency_filter: np.ndarray):
+        """Pre-computed clustering.
+
+        Args:
+            time_frequency_transform (WaveletTransform): A WaveletTransform instance
+                for performing wavelet transforms.
+            time_frequency_filter (np.ndarray): A pre-computed time-frequency filter.
+        """
+        super().__init__(time_frequency_transform=time_frequency_transform)
+        # Check the shape of the input time-frequency filter.
+        if time_frequency_filter.shape != self.shape:
+            raise ValueError(
+                f"The shape of time_frequency_filter: {time_frequency_filter.shape}"
+                f"does not match the expected shape: {self.shape}."
+            )
+
+        self._time_frequency_filter = time_frequency_filter

nullcal/clustering/single.py

@@ -0,0 +1,208 @@
+"""A submodule for single-signal clustering."""
+
+from __future__ import annotations
+
+import logging
+
+import numpy as np
+
+from ..data import InterferometerData
+from ..time_frequency_transform.wavelet_transforms import WaveletTransform
+from .time_frequency_map import construct_time_frequency_map
+
+logger = logging.getLogger("nullcal")
+
+
+def _get_neighbors(i: int, j: int, mask: np.ndarray) -> list:
+    """Get the neighbors of a pixel at (i,j ).
+
+    Args:
+        i (int): Time index.
+        j (int): Frequency index.
+        mask (np.ndarray): A time-frequency mask.
+
+    Returns:
+        list: A list of time-frequency coordinates of the neighbors.
+    """
+    neighbors = []
+    for x in range(-1, 2):
+        for y in range(-1, 2):
+            if x == 0 and y == 0:
+                continue
+            if 0 <= i + x < mask.shape[0] and 0 <= j + y < mask.shape[1]:
+                neighbors.append((i + x, j + y))
+    return neighbors
+
+
+# Depth-first search
+def _dfs(i: int, j: int, mask: np.ndarray, visited: np.ndarray) -> list:
+    """Depth-first search.
+
+    Args:
+        i (int): Time index.
+        j (int): Frequency index.
+        mask (np.ndarray): The time-frequency mask.
+        visited (np.ndarray): An array to indicate the pixels that have been visited.
+
+    Returns:
+        list: A list of time-frequency coordinates in the cluster.
+    """
+    stack = [(i, j)]
+    cluster = []
+    while stack:
+        i, j = stack.pop()
+        if visited[i, j]:
+            continue
+        visited[i, j] = 1
+        cluster.append((i, j))
+        for neighbor in _get_neighbors(i, j, mask):
+            if mask[neighbor[0], neighbor[1]]:
+                stack.append(neighbor)
+    return cluster
+
+
+def clustering(tf_filter: np.ndarray, dt: float, df: float, padding_time: float = 0.1, padding_freq: float = 10):
+    """
+    Find the largest cluster in the filter.
+
+    Args:
+        filter (np.ndarray): A binary mask in shape (n_time, n_freq).
+        dt (float): The time resolution in seconds.
+    df (float): The frequency resolution in Hz.
+    padding_time (float, optional): The padding in time direction in seconds. Default is 0.1.
+    padding_freq (float, optional): The padding in frequency direction in Hz. Default is 10.
+
+    Returns:
+    np.ndarray: A mask with the largest cluster in shape (n_time, n_freq).
+    """
+
+    # find clusters
+    visited = np.zeros(tf_filter.shape, dtype=np.uint8)
+    clusters = []
+    for i in range(tf_filter.shape[0]):
+        for j in range(tf_filter.shape[1]):
+            if tf_filter[i, j] and not visited[i, j]:
+                clusters.append(_dfs(i, j, tf_filter, visited))
+
+    # find the largest cluster
+    largest_cluster = max(clusters, key=len)
+    mask = np.zeros(tf_filter.shape, dtype=np.uint8)
+    for i, j in largest_cluster:
+        mask[i, j] = 1
+
+    # add padding
+    padding_time = int(np.ceil(padding_time / dt))
+    padding_freq = int(np.ceil(padding_freq / df))
+    for i, j in largest_cluster:
+        for x in range(-padding_time, padding_time + 1):
+            for y in range(-padding_freq, padding_freq + 1):
+                if 0 <= i + x < mask.shape[0] and 0 <= j + y < mask.shape[1]:
+                    mask[i + x, j + y] = 1
+
+    return mask
+
+
+def single_clustering_by_quantile(
+    interferometers: InterferometerData,
+    time_frequency_transform: WaveletTransform,
+    quantile: float,
+    padding_time: float = 0.05,
+    padding_freq: float = 0.0,
+    minimum_frequency: float | None = None,
+    maximum_frequency: float | None = None,
+) -> np.ndarray:
+    """Perform clustering with the threshold set by the quantile of the power.
+
+    This function only selects the largest cluster.
+
+    Args:
+        interferometers (InterferometerData): Frozen detector arrays and metadata.
+        frequency_resolution (float): The frequency resolution in Hz.
+        nx (float): The sharpness of wavelet.
+        quantile (float): The quantile to define the threshold.
+        padding_time (float, optional): The time window to pad at both ends. Defaults to 0.05.
+        padding_freq (float, optional): The frequency window to pad at both ends. Defaults to 0.0.
+        minimum_frequency (Optional[float], optional): Minimum frequency. Defaults to None.
+        maximum_frequency (Optional[float], optional): Maximum frequency. Defaults to None.
+
+    Returns:
+        np.ndarray: A boolean time-frequency mask.
+    """
+    time_frequency_map = construct_time_frequency_map(
+        interferometers=interferometers, time_frequency_transform=time_frequency_transform
+    )
+    # Zero the components beyond the frequency range
+    if minimum_frequency is not None:
+        freq_low_idx = int(np.ceil(minimum_frequency / time_frequency_transform.frequency_resolution))
+        time_frequency_map[:, :freq_low_idx] = 0.0
+    if maximum_frequency is not None:
+        freq_high_idx = int(np.floor(maximum_frequency / time_frequency_transform.frequency_resolution))
+        if freq_high_idx == time_frequency_map.shape[1] - 1:
+            logger.warning("The freq_high_idx = %s contains the Nyquist frequency.", freq_high_idx)
+            freq_high_idx -= 1
+            logger.warning("freq_high_idx is set to %s.", freq_high_idx)
+        time_frequency_map[:, freq_high_idx + 1 :] = 0.0
+    threshold = np.quantile(time_frequency_map[time_frequency_map > 0.0], quantile)
+    tf_filter = time_frequency_map > threshold
+    dt = interferometers.duration / time_frequency_transform.shape[0]
+    output = clustering(
+        tf_filter,
+        dt,
+        time_frequency_transform.frequency_resolution,
+        padding_time=padding_time,
+        padding_freq=padding_freq,
+    )
+    return output.astype(bool)
+
+
+def single_clustering_by_threshold(
+    interferometers: InterferometerData,
+    time_frequency_transform: WaveletTransform,
+    threshold: float,
+    padding_time: float = 0.05,
+    padding_freq: float = 0.0,
+    minimum_frequency: float | None = None,
+    maximum_frequency: float | None = None,
+) -> np.ndarray:
+    """Perform clustering with a given threshold.
+
+    This function only selects the largest cluster.
+
+    Args:
+        interferometers (InterferometerData): Frozen detector arrays and metadata.
+        time_frequency_transform (WaveletTransform): A WaveletTransform instance.
+        threshold (float): The threshold to select time-frequency pixels.
+        padding_time (float, optional): The time window to pad at both ends. Defaults to 0.05.
+        padding_freq (float, optional): The frequency window to pad at both ends. Defaults to 0.0.
+        minimum_frequency (Optional[float], optional): Minimum frequency. Defaults to None.
+        maximum_frequency (Optional[float], optional): Maximum frequency. Defaults to None.
+
+    Returns:
+        np.ndarray: A boolean time-frequency mask.
+    """
+    time_frequency_map = construct_time_frequency_map(
+        interferometers=interferometers, time_frequency_transform=time_frequency_transform
+    )
+    # Zero the components beyond the frequency range
+    if minimum_frequency is not None:
+        freq_low_idx = int(np.ceil(minimum_frequency / time_frequency_transform.frequency_resolution))
+        time_frequency_map[:, :freq_low_idx] = 0.0
+    if maximum_frequency is not None:
+        freq_high_idx = int(np.floor(maximum_frequency / time_frequency_transform.frequency_resolution))
+        if freq_high_idx == time_frequency_map.shape[1] - 1:
+            logger.warning("The freq_high_idx = %s contains the Nyquist frequency.", freq_high_idx)
+            freq_high_idx -= 1
+            logger.warning("freq_high_idx is set to %s.", freq_high_idx)
+        time_frequency_map[:, freq_high_idx:] = 0.0
+    tf_filter = time_frequency_map > threshold
+    n_f = int(interferometers.sampling_frequency / 2 / time_frequency_transform.frequency_resolution)
+    n_t = int(interferometers.duration * interferometers.sampling_frequency / n_f)
+    dt = interferometers.duration / n_t
+    output = clustering(
+        tf_filter,
+        dt,
+        time_frequency_transform.frequency_resolution,
+        padding_time=padding_time,
+        padding_freq=padding_freq,
+    )
+    return output.astype(bool)

nullcal/clustering/time_frequency_map.py

@@ -0,0 +1,42 @@
+"""A submodule for constructing time-frequency maps."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ..data import InterferometerData
+from ..null_stream.whiten import compute_whitened_frequency_domain_strain
+from ..time_frequency_transform.wavelet_transforms import WaveletTransform
+
+
+def construct_time_frequency_map(interferometers: InterferometerData, time_frequency_transform: WaveletTransform):
+    """Construct the time-frequency map from the interferometers.
+
+    Args:
+        interferometers (InterferometerData): Frozen detector arrays and metadata.
+        time_frequency_transform (WaveletTransform): A WaveletTransform instance
+            for performing wavelet transforms.
+    Returns:
+        np.ndarray: The combined time-frequency map.
+    """
+    n_det = interferometers.strain.shape[0]
+    # Compute the whitened time-frequency array
+    whitened_frequency_domain_strain = compute_whitened_frequency_domain_strain(
+        interferometers.strain,
+        interferometers.psd,
+        1 / interferometers.duration,
+        np.all(interferometers.mask, axis=0),
+    )
+    combined_power = np.zeros(time_frequency_transform.shape)
+    for i in range(n_det):
+        whitened_time_frequency_domain_strain_i = time_frequency_transform.frequency_to_wavelet(
+            frequency_domain_data=whitened_frequency_domain_strain[i]
+        )
+        whitened_time_frequency_domain_strain_quadrature_i = time_frequency_transform.frequency_to_wavelet_quadrature(
+            frequency_domain_data=whitened_frequency_domain_strain[i]
+        )
+        combined_power += (
+            np.abs(whitened_time_frequency_domain_strain_i) ** 2
+            + np.abs(whitened_time_frequency_domain_strain_quadrature_i) ** 2
+        ) / 2
+    return combined_power

nullcal/data.py

@@ -0,0 +1,93 @@
+"""Immutable detector data consumed by null-stream calculations."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any
+
+import jax
+import numpy as np
+
+DETECTOR_ARRAY_NDIM = 2
+
+
+@jax.tree_util.register_pytree_node_class
+@dataclass(frozen=True)
+class InterferometerData:
+    """Dependency-free arrays and shared metadata for a detector network.
+
+    Detector names are static pytree metadata. All numerical values are leaves,
+    so JAX transformations can move or batch the data without importing the
+    package that originally loaded the strain.
+    """
+
+    psd: Any
+    strain: Any
+    mask: Any
+    frequency_array: Any
+    duration: Any
+    sampling_frequency: Any
+    start_time: Any
+    name: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        if any(array.ndim != DETECTOR_ARRAY_NDIM for array in (self.psd, self.strain, self.mask)):
+            raise ValueError("psd, strain, and mask must have (detector, frequency) dimensions")
+        if self.psd.shape != self.strain.shape or self.psd.shape != self.mask.shape:
+            raise ValueError("psd, strain, and mask must have identical shapes")
+        if self.frequency_array.ndim != 1 or self.frequency_array.shape[0] != self.psd.shape[1]:
+            raise ValueError("frequency_array must match the frequency dimension")
+        if len(self.name) != self.psd.shape[0]:
+            raise ValueError("name must contain one label per detector")
+
+    def __len__(self) -> int:
+        """Return the number of detectors."""
+        return len(self.name)
+
+    @classmethod
+    def from_interferometers(cls, interferometers: Sequence[Any]) -> InterferometerData:
+        """Load arrays from detector objects without retaining their package type."""
+        interferometers = tuple(interferometers)
+        if not interferometers:
+            raise ValueError("interferometers must contain at least one detector")
+
+        def shared_scalar(attribute: str, label: str) -> float:
+            values = np.asarray([getattr(interferometer, attribute) for interferometer in interferometers])
+            if not np.allclose(values, values[0]):
+                raise ValueError(f"The interferometers do not have the same {label}: {values.tolist()}.")
+            return float(values[0])
+
+        frequency_arrays = np.asarray([interferometer.frequency_array for interferometer in interferometers])
+        if not np.allclose(frequency_arrays, frequency_arrays[0], rtol=0.0, atol=0.0):
+            raise ValueError("The interferometers do not have the same frequency array.")
+
+        return cls(
+            psd=np.asarray([interferometer.power_spectral_density_array for interferometer in interferometers]),
+            strain=np.asarray([interferometer.frequency_domain_strain for interferometer in interferometers]),
+            mask=np.asarray([interferometer.frequency_mask for interferometer in interferometers], dtype=bool),
+            frequency_array=np.asarray(frequency_arrays[0]),
+            duration=shared_scalar("duration", "duration"),
+            sampling_frequency=shared_scalar("sampling_frequency", "sampling frequency"),
+            start_time=shared_scalar("start_time", "start time"),
+            name=tuple(str(interferometer.name) for interferometer in interferometers),
+        )
+
+    def tree_flatten(self):
+        children = (
+            self.psd,
+            self.strain,
+            self.mask,
+            self.frequency_array,
+            self.duration,
+            self.sampling_frequency,
+            self.start_time,
+        )
+        return children, self.name
+
+    @classmethod
+    def tree_unflatten(cls, name, children):
+        return cls(*children, name=name)
+
+
+__all__ = ["InterferometerData"]