Utilities

buoy.utils.data.get_local_or_hf(filename, repo_id, descriptor, revision=None, cache_dir=None)

Determine whether a given file exists locally or in a HuggingFace repository. If the file exists locally, return the filename. If it does not exist locally, attempt to download it from the HuggingFace repository. If the file is not found in either location, raise a ValueError.

Parameters:

• filename (str | Path) – The name of the file to load.

• repo_id (str) – The HuggingFace repository ID.

• descriptor (str) – A description of the file for logging.

• revision (str | None) – The HuggingFace repository revision (branch, tag, or commit hash) to download from. If None, uses the default branch.

• cache_dir (str | Path | None) – Local directory to use as the HuggingFace download cache. If None, uses the default HuggingFace cache location.

Return type:

str

Returns:

The path to the file.

buoy.utils.data.slice_amplfi_data(data, sample_rate, t0, tc, kernel_length, event_position, psd_length, fduration)

Slice a strain tensor into the PSD background and inference window required by AMPLFI.

Parameters:

• data (Tensor) – Strain tensor of shape (1, num_channels, num_samples).

• sample_rate (float) – Sampling rate in Hz.

• t0 (float) – GPS start time of data.

• tc (float) – Coalescence time (GPS).

• kernel_length (float) – Length of the inference kernel in seconds.

• event_position (float) – Position of the coalescence within the kernel in seconds (range [0, kernel_length]).

• psd_length (float) – Length of the PSD background segment in seconds.

• fduration (float) – Whitening filter duration in seconds.

Return type:

tuple[Tensor, Tensor]

Returns:

A (psd_data, window) tuple where psd_data has shape (num_channels, psd_length * sample_rate) and window has shape (num_channels, (kernel_length + fduration) * sample_rate).

Raises:

ValueError – If the requested window extends outside the bounds of data.

class buoy.utils.preprocessing.BackgroundSnapshotter(psd_length, kernel_length, fduration, sample_rate, inference_sampling_rate)

Bases: Module

Update a kernel with a new piece of streaming data

forward(update, snapshot)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

Return type:

tuple[Tensor, ...]

class buoy.utils.preprocessing.PsdEstimator(length, sample_rate, fftlength, window=None, overlap=None, average='median', fast=True)

Bases: Module

Module that takes a sample of data, splits it into two unequal-length segments, calculates the PSD of the first section, then returns this PSD along with the second section.

Parameters:

• length (float) – The length, in seconds, of timeseries data to be returned for whitening. Note that the length of time used for the PSD will then be whatever remains along first part of the time axis of the input.

• sample_rate (float) – Rate at which input data has been sampled in Hz

• fftlength (float) – Length of FFTs to use when computing the PSD

• overlap (float | None) – Amount of overlap between FFT windows when computing the PSD. Default value of None uses fftlength / 2

• average (str) – Method for aggregating spectra from FFT windows, either “mean” or “median”

• fast (bool) – If True, use a slightly faster PSD algorithm that is inaccurate for the lowest two frequency bins. If you plan on highpassing later, this should be fine.

forward(X)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

Return type:

tuple[Tensor, Tensor]

class buoy.utils.preprocessing.BatchWhitener(kernel_length, sample_rate, inference_sampling_rate, batch_size, fduration, fftlength, augmentor=None, highpass=None, lowpass=None, return_whitened=False)

Bases: Module

Calculate the PSDs and whiten an entire batch of kernels at once

forward(x)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

Return type:

Tensor | tuple[Tensor, Tensor]

buoy.utils.pe.get_redshifts(distances, num_pts=10000)

Compute redshift using the Planck18 cosmology. Implementation taken from https://git.ligo.org/emfollow/em-properties/em-bright/-/blob/main/ligo/em_bright/em_bright.py

This function accepts distance values in Mpc and computes redshifts by interpolating the distance-redshift relation. This process is much faster compared to astropy.cosmology APIs with lesser than a percent difference.

buoy.utils.pe.postprocess_samples(samples, event_time, inference_params, parameter_sampler)

Process samples into a bilby Result object that can be used for all downstream tasks

Return type:

AmplfiResult