nullcal 0.2.0__py3-none-any.whl

nullcal/likelihood/__init__.py

@@ -0,0 +1,9 @@
+"""A submodule for likelihoods."""
+
+from __future__ import annotations
+
+from .recalibration_likelihood import RecalibrationLikelihood
+
+__all__ = [
+    "RecalibrationLikelihood",
+]

nullcal/likelihood/recalibration_likelihood.py

@@ -0,0 +1,227 @@
+"""Pure JAX log density for null-stream recalibration inference."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import jax
+
+jax.config.update("jax_enable_x64", True)
+
+import jax.numpy as jnp  # noqa: E402
+import numpy as np  # noqa: E402
+
+from ..calibration import MINIMUM_CUBIC_SPLINE_KNOTS, calibration_factor, calibration_log_prior  # noqa: E402
+from ..data import InterferometerData  # noqa: E402
+from ..null_stream.whiten import (  # noqa: E402
+    compute_whitened_antenna_response,
+    compute_whitened_frequency_domain_strain,
+)
+from ..time_frequency_transform.transform_freq_funcs import (  # noqa: E402
+    phitilde_vec_norm,
+    transform_wavelet_freq_helper,
+)
+from ..time_frequency_transform.wavelet_transforms import WaveletTransform  # noqa: E402
+
+PARAMETER_NAMES = frozenset({"amplitude", "phase"})
+PARAMETER_ARRAY_NDIM = 2
+ET_BEAM_PATTERN = np.array(
+    [[-1.0 / np.sqrt(6.0), -1.0 / np.sqrt(2.0)], [np.sqrt(6.0) / 3.0, 0.0], [-1.0 / np.sqrt(6.0), 1.0 / np.sqrt(2.0)]]
+)
+
+
+def _broadcast_prior(value, shape: tuple[int, int], name: str) -> jax.Array:
+    array = jnp.asarray(value, dtype=jnp.float64)
+    try:
+        return jnp.broadcast_to(array, shape)
+    except ValueError as error:
+        raise ValueError(f"{name} must be scalar or broadcast to detector-by-knot shape {shape}") from error
+
+
+def _validated_knots(knot_frequencies, detector_count: int) -> np.ndarray:
+    knots = np.asarray(knot_frequencies, dtype=np.float64)
+    if knots.ndim == 1:
+        knots = np.broadcast_to(knots, (detector_count, knots.size)).copy()
+    if knots.ndim != PARAMETER_ARRAY_NDIM or knots.shape[0] != detector_count:
+        raise ValueError("knot_frequencies must have shape (knot,) or (detector, knot)")
+    if knots.shape[1] < MINIMUM_CUBIC_SPLINE_KNOTS:
+        raise ValueError("a cubic spline requires at least four knots")
+    if np.any(knots <= 0.0) or np.any(np.diff(knots, axis=1) <= 0.0):
+        raise ValueError("knot_frequencies must be positive and strictly increasing")
+    return knots
+
+
+def _whitened_inputs(interferometers, shared_mask, supplied_whitened_strain):
+    delta_f = 1.0 / float(interferometers.duration)
+    psd = np.asarray(interferometers.psd)
+    whitened_response = compute_whitened_antenna_response(ET_BEAM_PATTERN, psd, delta_f, shared_mask)
+    if supplied_whitened_strain is None:
+        whitened_strain = compute_whitened_frequency_domain_strain(
+            np.asarray(interferometers.strain), psd, delta_f, shared_mask
+        )
+    else:
+        whitened_strain = np.asarray(supplied_whitened_strain)
+        if whitened_strain.shape != psd.shape:
+            raise ValueError("whitened_frequency_domain_strain must match the detector data shape")
+        if not np.all(whitened_strain[:, ~shared_mask] == 0.0):
+            raise ValueError("whitened_frequency_domain_strain must be zero outside the shared mask")
+    return psd, whitened_response, whitened_strain
+
+
+class RecalibrationLikelihood:
+    """Immutable-data recalibration posterior with a pure ``logdensity_fn``.
+
+    One instance represents one detector-network realization. Parameters are a
+    pytree with ``amplitude`` and ``phase`` arrays of shape ``(detector, knot)``.
+    Knot frequencies and Gaussian prior hyperparameters are fixed model data,
+    not sampled coordinates.
+    """
+
+    def __init__(
+        self,
+        interferometers: InterferometerData,
+        knot_frequencies,
+        *,
+        time_frequency_filter: np.ndarray,
+        wavelet_transform_frequency_resolution: float = 4.0,
+        wavelet_transform_nx: float = 4.0,
+        amplitude_prior_mean=0.0,
+        amplitude_prior_sigma=0.05,
+        phase_prior_mean=0.0,
+        phase_prior_sigma=0.05,
+        whitened_frequency_domain_strain=None,
+    ) -> None:
+        if not isinstance(interferometers, InterferometerData):
+            raise TypeError("interferometers must be an InterferometerData instance")
+        if len(interferometers) != ET_BEAM_PATTERN.shape[0]:
+            raise ValueError("the recalibration likelihood currently requires the three-detector ET triangle")
+
+        transform = WaveletTransform(
+            duration=float(interferometers.duration),
+            sampling_frequency=float(interferometers.sampling_frequency),
+            frequency_resolution=wavelet_transform_frequency_resolution,
+            nx=wavelet_transform_nx,
+        )
+        time_frequency_filter = np.asarray(time_frequency_filter, dtype=bool)
+        if time_frequency_filter.shape != transform.shape:
+            raise ValueError(
+                f"time_frequency_filter has shape {time_frequency_filter.shape}; expected {transform.shape}"
+            )
+
+        shared_mask = np.all(np.asarray(interferometers.mask, dtype=bool), axis=0)
+        frequency_indices = np.flatnonzero(shared_mask)
+        if frequency_indices.size == 0:
+            raise ValueError("the shared detector frequency mask must not be empty")
+        masked_frequencies = np.asarray(interferometers.frequency_array)[frequency_indices]
+        if np.any(masked_frequencies <= 0.0):
+            raise ValueError("calibration frequencies must be positive")
+
+        knots = _validated_knots(knot_frequencies, len(interferometers))
+        psd, whitened_response, whitened_strain = _whitened_inputs(
+            interferometers, shared_mask, whitened_frequency_domain_strain
+        )
+
+        parameter_shape = knots.shape
+        self.interferometers = interferometers
+        self.knot_frequencies = jnp.asarray(knots)
+        self.time_frequency_filter = jnp.asarray(time_frequency_filter)
+        self.time_frequency_transform = transform
+        self.amplitude_prior_mean = _broadcast_prior(amplitude_prior_mean, parameter_shape, "amplitude_prior_mean")
+        self.amplitude_prior_sigma = _broadcast_prior(amplitude_prior_sigma, parameter_shape, "amplitude_prior_sigma")
+        self.phase_prior_mean = _broadcast_prior(phase_prior_mean, parameter_shape, "phase_prior_mean")
+        self.phase_prior_sigma = _broadcast_prior(phase_prior_sigma, parameter_shape, "phase_prior_sigma")
+        if np.any(np.asarray(self.amplitude_prior_sigma) <= 0.0) or np.any(np.asarray(self.phase_prior_sigma) <= 0.0):
+            raise ValueError("prior standard deviations must be positive")
+
+        self._frequency_indices = jnp.asarray(frequency_indices)
+        self._masked_frequencies = jnp.asarray(masked_frequencies)
+        self._whitened_antenna_response = jnp.asarray(whitened_response[frequency_indices])
+        self._whitened_frequency_domain_strain = jnp.asarray(whitened_strain[:, frequency_indices])
+        self._frequency_count = psd.shape[1]
+        n_time, n_frequency = transform.shape
+        self._wavelet_n_time = n_time
+        self._wavelet_n_frequency = n_frequency
+        self._wavelet_window = (2.0 / n_frequency) * phitilde_vec_norm(n_frequency, n_time, wavelet_transform_nx)
+        self._wavelet_scale = jnp.sqrt((self._frequency_count - 1) * 2.0)
+
+    @property
+    def parameter_shape(self) -> tuple[int, int]:
+        """Required shape of each parameter array."""
+        return self.knot_frequencies.shape
+
+    def _validated_parameters(self, params: Mapping[str, jax.Array]) -> tuple[jax.Array, jax.Array]:
+        if not isinstance(params, Mapping) or set(params) != PARAMETER_NAMES:
+            raise ValueError("params must contain exactly amplitude and phase")
+        amplitude = jnp.asarray(params["amplitude"], dtype=jnp.float64)
+        phase = jnp.asarray(params["phase"], dtype=jnp.float64)
+        if amplitude.shape != self.parameter_shape or phase.shape != self.parameter_shape:
+            raise ValueError(
+                f"amplitude and phase must each have shape {self.parameter_shape}; "
+                f"received {amplitude.shape} and {phase.shape}"
+            )
+        return amplitude, phase
+
+    def _calibration_factor(self, amplitude: jax.Array, phase: jax.Array) -> jax.Array:
+        return jax.vmap(calibration_factor, in_axes=(None, 0, 0, 0))(
+            self._masked_frequencies,
+            self.knot_frequencies,
+            amplitude,
+            phase,
+        )
+
+    def _frequency_domain_null_stream(self, amplitude: jax.Array, phase: jax.Array) -> jax.Array:
+        factors = self._calibration_factor(amplitude, phase)
+        response = self._whitened_antenna_response * jnp.swapaxes(factors, 0, 1)[:, :, None]
+        response_dagger = jnp.swapaxes(jnp.conj(response), 1, 2)
+        gram = response_dagger @ response
+        projected_response = response @ jnp.linalg.solve(gram, response_dagger)
+        projector = jnp.eye(response.shape[1], dtype=response.dtype)[None, :, :] - projected_response
+        masked_null_stream = jnp.einsum("fij,jf->if", projector, self._whitened_frequency_domain_strain)
+        return (
+            jnp.zeros((self.parameter_shape[0], self._frequency_count), dtype=masked_null_stream.dtype)
+            .at[:, self._frequency_indices]
+            .set(masked_null_stream)
+        )
+
+    def _time_frequency_null_stream(self, amplitude: jax.Array, phase: jax.Array) -> jax.Array:
+        frequency_domain = self._frequency_domain_null_stream(amplitude, phase)
+
+        def transform(detector_data):
+            return (
+                transform_wavelet_freq_helper(
+                    detector_data,
+                    self._wavelet_n_frequency,
+                    self._wavelet_n_time,
+                    self._wavelet_window,
+                )
+                * self._wavelet_scale
+            )
+
+        time_frequency = jax.vmap(transform)(frequency_domain)
+        return jnp.where(self.time_frequency_filter[None, :, :], time_frequency, 0.0)
+
+    def log_likelihood_fn(self, params: Mapping[str, jax.Array]) -> jax.Array:
+        """Return the pure JAX null-stream log likelihood for ``params``."""
+        amplitude, phase = self._validated_parameters(params)
+        null_stream = self._time_frequency_null_stream(amplitude, phase)
+        return -0.5 * jnp.sum(jnp.abs(null_stream) ** 2)
+
+    def logdensity_fn(self, params: Mapping[str, jax.Array]) -> jax.Array:
+        """Return normalized Gaussian log prior plus null-stream log likelihood."""
+        amplitude, phase = self._validated_parameters(params)
+        return self.log_likelihood_fn(params) + calibration_log_prior(
+            amplitude,
+            phase,
+            self.amplitude_prior_mean,
+            self.amplitude_prior_sigma,
+            self.phase_prior_mean,
+            self.phase_prior_sigma,
+        )
+
+    def noise_log_likelihood(self) -> jax.Array:
+        """Return the likelihood for an exactly uncalibrated response."""
+        zeros = jnp.zeros(self.parameter_shape, dtype=jnp.float64)
+        return self.log_likelihood_fn({"amplitude": zeros, "phase": zeros})
+
+
+__all__ = ["RecalibrationLikelihood"]

nullcal/metadata/yaml.py

@@ -0,0 +1,30 @@
+"""YAML read and write utilities."""
+
+from __future__ import annotations
+
+import yaml
+
+
+def write_to_yaml(fname: str, data: dict) -> None:
+    """Write a dictionary to a YAML file.
+
+    Args:
+        fname (str): File name.
+        data (dict): A dictionary of data.
+    """
+    with open(fname, mode="w", encoding="utf-8") as f:
+        yaml.safe_dump(data, f, default_flow_style=False)
+
+
+def load_from_yaml(fname: str) -> dict:
+    """Load from a YAML file.
+
+    Args:
+        fname (str): File name.
+
+    Returns:
+        dict: A dictionary of data.
+    """
+    with open(fname, encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+    return data

nullcal/null_stream/calibration.py

@@ -0,0 +1,40 @@
+"""
+Functions for including calibration factors into
+the antenna response function.
+"""
+
+from __future__ import annotations
+
+import jax
+
+# Calibration inference is numerically unstable in JAX's default float32 mode.
+# Keep this kernel consistent with nullcal.calibration, which establishes x64 as
+# a process-wide requirement for the calibration path.
+jax.config.update("jax_enable_x64", True)
+
+import jax.numpy as jnp  # noqa: E402
+import numpy as np  # noqa: E402
+
+
+def compute_calibrated_whitened_antenna_response(
+    whitened_antenna_response: np.ndarray, calibration_factor: np.ndarray, frequency_mask: np.ndarray
+) -> np.ndarray:
+    """Compute the whitened antenna response function
+    with the calibration factor included.
+
+    Args:
+        whitened_antenna_response (np.ndarray): Whitened antenna response function.
+            Dimensions: (frequency, detector, polarization).
+        calibration_factor (np.ndarray): Calibration factor.
+            Dimensions: (detector, frequency).
+        frequency_mask (np.ndarray): Frequency mask.
+            Dimensions: (frequency,)
+
+    Returns:
+        np.ndarray: Calibrated antenna response function.
+    """
+    calibration_factor = jnp.asarray(calibration_factor)
+    response = jnp.asarray(whitened_antenna_response, dtype=calibration_factor.dtype)
+    mask = jnp.asarray(frequency_mask, dtype=bool)[:, None, None]
+    calibrated = response * jnp.swapaxes(calibration_factor, 0, 1)[:, :, None]
+    return jnp.where(mask, calibrated, jnp.zeros((), dtype=calibrated.dtype))

nullcal/null_stream/null_stream.py

@@ -0,0 +1,252 @@
+"""A submodule for null stream calculation."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from ..calibration import MINIMUM_CUBIC_SPLINE_KNOTS, calibration_factor
+from ..data import InterferometerData
+from ..time_frequency_transform.wavelet_transforms import WaveletTransform
+from .calibration import compute_calibrated_whitened_antenna_response
+from .projector import compute_projector
+from .whiten import compute_whitened_antenna_response, compute_whitened_frequency_domain_strain
+
+
+def compute_projected_strain_data(
+    projector: np.ndarray, strain_data: np.ndarray, frequency_mask: np.ndarray
+) -> np.ndarray:
+    """Compute the projected strain data.
+
+    Args:
+        projector (np.ndarray): Projector. Dimensions: (frequency, detector, detector).
+        strain_data (np.ndarray): Strain data. Dimensions: (detector, frequency).
+        frequency_mask (np.ndarray): Frequency mask. Dimensions: (frequency,).
+
+    Raises:
+        ValueError: Projector shape mismatch. project must have the same dimensions in the two last axes.
+        ValueError: Shape mismatch. projector and strain_data must have the same detector and frequency dimensions.
+        ValueError: Shape mismatch. strain_data and frequency_mask must have the same frequency dimension.
+
+    Returns:
+        np.ndarray: Projected strain data. Dimensions: (detector, frequency).
+    """
+    n_freq_1, n_det_1, n_det_2 = projector.shape
+    if n_det_1 != n_det_2:
+        raise ValueError(
+            "Shape mismatch."
+            f"projector: (frequency={n_freq_1},detector={n_det_1}, detector={n_det_2})."
+            "project must have the same dimensions in the two last axes."
+        )
+    n_det_3, n_freq_2 = strain_data.shape
+    if n_det_1 != n_det_3 or n_freq_1 != n_freq_2:
+        raise ValueError(
+            "Shape mismatch."
+            f"projector: (frequency={n_freq_1},detector={n_det_1}, detector={n_det_2})."
+            f"strain_data: (detector={n_det_3},frequency={n_freq_2})."
+            "projector and strain_data must have the same detector and frequency dimensions."
+        )
+    n_freq_3 = frequency_mask.shape[0]
+    if n_freq_2 != n_freq_3:
+        raise ValueError(
+            "Shape mismatch."
+            f"strain_data: (detector={n_det_3},frequency={n_freq_2})."
+            f"frequency_mask: (frequency={n_freq_3})."
+            "strain_data and frequency_mask must have the same frequency dimension."
+        )
+    output = np.zeros_like(strain_data)
+    output[:, frequency_mask] = np.einsum("fij,jf->if", projector[frequency_mask, :, :], strain_data[:, frequency_mask])
+    return output
+
+
+class NullStream:
+    """A class to handle null stream calculation."""
+
+    def __init__(
+        self,
+        interferometers: InterferometerData,
+        time_frequency_transform: WaveletTransform,
+        time_frequency_filter: np.ndarray,
+    ):
+        """A null stream calculator.
+
+        Args:
+            interferometers (InterferometerData): Frozen detector arrays and metadata.
+            time_frequency_transform (WaveletTransform): A WaveletTransform instance.
+            time_frequency_filter (np.ndarray): A time-frequency filter.
+        """
+        self.interferometers = interferometers
+        self.time_frequency_transform = time_frequency_transform
+        self.time_frequency_filter = time_frequency_filter
+
+        # Pre-compute the whitened quantities.
+        self.frequency_mask = np.all(self.interferometers.mask, axis=0)
+        self.masked_frequency_array = self.interferometers.frequency_array[self.frequency_mask]
+        # Construct the noise weighed antenna pattern
+        # This is the orthogonalized beam pattern matrix, correct for ET only,
+        # ignoring the small difference in location of the detectors.
+        beam_pattern_matrix = np.array(
+            [[-1.0 / np.sqrt(6), -1 / np.sqrt(2)], [np.sqrt(6) / 3, 0], [-1 / np.sqrt(6), 1 / np.sqrt(2)]]
+        )
+        power_spectral_density_array = np.asarray(interferometers.psd)
+        self._whitened_antenna_response = compute_whitened_antenna_response(
+            beam_pattern_matrix,
+            power_spectral_density_array,
+            1 / self.interferometers.duration,
+            self.frequency_mask,
+        )
+        self._whitened_frequency_domain_strain_array = compute_whitened_frequency_domain_strain(
+            frequency_domain_strain_array=np.asarray(interferometers.strain),
+            power_spectral_density_array=power_spectral_density_array,
+            delta_f=1.0 / interferometers.duration,
+            frequency_mask=self.frequency_mask,
+        )
+
+    def compute_uncalibrated_frequency_domain_null_stream(self) -> np.ndarray:
+        """Compute the uncalibrated frequency domain null stream.
+
+        Returns:
+            np.ndarray: Uncalibrated frequency domain null stream. Dimensions: (detector, frequency).
+        """
+        # Dimensions: (frequency, detector, detector)
+        projector = compute_projector(self._whitened_antenna_response, frequency_mask=self.frequency_mask)
+        # Dimensions: (frequency, detector)
+
+        return np.einsum("ijk,ki->ji", projector, self._whitened_frequency_domain_strain_array)
+
+    def compute_calibrated_frequency_domain_null_stream(self, calibration_factor: np.ndarray) -> np.ndarray:
+        """Compute the calibrated frequency domain null stream.
+
+        Args:
+            calibration_factor (np.ndarray): Calibration factor. Dimensions: (detector, frequency).
+
+        Returns:
+            np.ndarray: Calibrated frequency domain null stream. Dimensions: (detector, frequency).
+        """
+        calibrated_whitened_antenna_response = compute_calibrated_whitened_antenna_response(
+            self._whitened_antenna_response, calibration_factor, self.frequency_mask
+        )
+        projector = compute_projector(calibrated_whitened_antenna_response, frequency_mask=self.frequency_mask)
+        # Dimensions: (frequency, detector)
+
+        return np.einsum("ijk,ki->ji", projector, self._whitened_frequency_domain_strain_array)
+
+    def compute_uncalibrated_time_frequency_domain_null_stream(self) -> np.ndarray:
+        """Compute the uncalibrated time-frequency domain null stream, confined to the filter.
+
+        The returned array is zero outside ``time_frequency_filter``, matching what
+        ``compute_calibrated_time_frequency_domain_null_stream_from_parameters`` returns. That
+        symmetry is the point: ``noise_log_likelihood`` sums this array's energy and
+        ``log_likelihood`` sums the calibrated one's, so if the two were confined to different
+        domains their difference — the log Bayes factor, and anything derived from it — would be
+        normalised against different sets of pixels.
+
+        Returns:
+            np.ndarray: Uncalibrated time-frequency domain null stream, zero outside the filter.
+        """
+        uncalibrated_frequency_domain_null_stream = self.compute_uncalibrated_frequency_domain_null_stream()
+        # Transform to time-frequency domain
+        uncalibrated_time_frequency_domain_null_stream = np.array(
+            [
+                self.time_frequency_transform.frequency_to_wavelet(frequency_domain_data=data)
+                for data in uncalibrated_frequency_domain_null_stream
+            ]
+        )
+        uncalibrated_time_frequency_domain_null_stream[:, ~self.time_frequency_filter] = 0.0
+        return uncalibrated_time_frequency_domain_null_stream
+
+    def compute_calibrated_time_frequency_domain_null_stream(self, calibration_factor: np.ndarray) -> np.ndarray:
+        """Compute the calibrated time-frequency domain null stream, confined to the filter.
+
+        Like its uncalibrated counterpart, the returned array is zero outside
+        ``time_frequency_filter``. The two are deliberately symmetric: a caller that used one
+        filtered method and one unfiltered one would sum energies over different pixel domains and
+        recreate exactly the normalisation defect this pair was fixed for, silently and without an
+        exception.
+
+        Args:
+            calibration_factor (np.ndarray): Calibration factor.
+
+        Returns:
+            np.ndarray: Calibrated time-frequency domain null stream, zero outside the filter.
+        """
+        calibrated_frequency_domain_null_stream = self.compute_calibrated_frequency_domain_null_stream(
+            calibration_factor=calibration_factor
+        )
+        # Transform to time-frequency domain
+        calibrated_time_frequency_domain_null_stream = np.array(
+            [
+                self.time_frequency_transform.frequency_to_wavelet(frequency_domain_data=data)
+                for data in calibrated_frequency_domain_null_stream
+            ]
+        )
+        calibrated_time_frequency_domain_null_stream[:, ~self.time_frequency_filter] = 0.0
+        return calibrated_time_frequency_domain_null_stream
+
+    def construct_calibration_factor_from_parameters(self, parameters: dict) -> np.ndarray:
+        """Construct the calibration factor from parameters.
+
+        Args:
+            parameters (dict): Calibration parameters.
+
+        Returns:
+            np.ndarray: Calibration factor.
+        """
+        detector_nodes = []
+        expected_keys = set()
+        for name in self.interferometers.name:
+            prefix = f"recalib_{name}_"
+            frequency_indices = sorted(
+                int(key.removeprefix(f"{prefix}frequency_"))
+                for key in parameters
+                if key.startswith(f"{prefix}frequency_") and key.removeprefix(f"{prefix}frequency_").isdigit()
+            )
+            if (
+                frequency_indices != list(range(len(frequency_indices)))
+                or len(frequency_indices) < MINIMUM_CUBIC_SPLINE_KNOTS
+            ):
+                raise ValueError("calibration parameters do not match the required detector spline nodes")
+            keys = {
+                f"{prefix}{quantity}_{index}"
+                for quantity in ("frequency", "amplitude", "phase")
+                for index in frequency_indices
+            }
+            expected_keys.update(keys)
+            detector_nodes.append((prefix, frequency_indices))
+
+        supplied_keys = {key for key in parameters if key.startswith("recalib_")}
+        if supplied_keys != expected_keys:
+            missing = sorted(expected_keys - supplied_keys)
+            unexpected = sorted(supplied_keys - expected_keys)
+            raise ValueError(
+                f"calibration parameters do not match the required keys; missing={missing}, unexpected={unexpected}"
+            )
+
+        calibration_factor_array = np.asarray(
+            [
+                calibration_factor(
+                    self.masked_frequency_array,
+                    [parameters[f"{prefix}frequency_{index}"] for index in indices],
+                    [parameters[f"{prefix}amplitude_{index}"] for index in indices],
+                    [parameters[f"{prefix}phase_{index}"] for index in indices],
+                )
+                for prefix, indices in detector_nodes
+            ]
+        )
+        output = np.zeros_like(self._whitened_frequency_domain_strain_array)
+        output[:, self.frequency_mask] = calibration_factor_array
+
+        return output
+
+    def compute_calibrated_time_frequency_domain_null_stream_from_parameters(self, parameters: dict) -> np.ndarray:
+        """Compute the calibrated time-frequency domain null stream from parameters.
+
+        Args:
+            parameters (dict): A dictionary of calibration parameters.
+
+        Returns:
+            np.ndarray: Calibrated time-frequency domain null stream.
+        """
+        calibration_factor = self.construct_calibration_factor_from_parameters(parameters)
+        # The filtering lives in compute_calibrated_time_frequency_domain_null_stream, which
+        # guarantees confinement for every caller rather than only for this wrapper.
+        return self.compute_calibrated_time_frequency_domain_null_stream(calibration_factor=calibration_factor)

nullcal/null_stream/projector.py

@@ -0,0 +1,48 @@
+"""
+Functions for projections.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def compute_projector(
+    calibrated_whitened_antenna_response_function: np.ndarray, frequency_mask: np.ndarray
+) -> np.ndarray:
+    """Compute the projector.
+
+    Args:
+        calibrated_whitened_antenna_response_function (np.ndarray): Calibrated whitened antenna response function.
+            Dimensions: (frequency, detector, mode).
+        frequency_mask (np.ndarray): Frequency mask.
+
+    Raises:
+        ValueError: Frequency mask shape mismatch. The frequency dimensions must have the same length.
+
+    Returns:
+        np.ndarray: Projector. Dimensions: (frequency, detector, detector).
+    """
+    n_freq, n_det, _ = calibrated_whitened_antenna_response_function.shape
+    if n_freq != frequency_mask.shape[0]:
+        raise ValueError(
+            "Frequency mask shape mismatch."
+            "calibrated_whitened_antenna_response_function:"
+            f"(frequency={n_freq},detector={n_det},mode={_})"
+            f"and frequency_mask: (frequency={frequency_mask.shape[0]})."
+            "The frequency dimensions must have the same length."
+        )
+    calibrated_whitened_antenna_response_function_masked = calibrated_whitened_antenna_response_function[
+        frequency_mask, :, :
+    ]
+    output = np.eye(n_det, dtype=calibrated_whitened_antenna_response_function.dtype)[np.newaxis, :, :].repeat(
+        n_freq, axis=0
+    )
+    f_dagger = np.transpose(np.conj(calibrated_whitened_antenna_response_function_masked), axes=(0, 2, 1))
+    # I - F@(F'F)^-1 F'
+    projector_gw = np.matmul(
+        calibrated_whitened_antenna_response_function_masked,
+        np.matmul(np.linalg.inv(np.matmul(f_dagger, calibrated_whitened_antenna_response_function_masked)), f_dagger),
+    )
+    output[frequency_mask, :, :] = output[frequency_mask, :, :] - projector_gw
+    return output