API Reference¶

Main Module¶

datafind.main.get_pesummary(components, settings)[source]¶

Fetch data from a PESummary metafile.

Frames Module¶

The frames module handles retrieval of gravitational wave strain data from GWOSC and private data sources.

Data find logic for locating frame files.

class datafind.frames.Frame(framefile)[source]¶

Bases: object

A lightweight class to represent a data Frame.

__init__(framefile)[source]¶

property channels¶

spectrogram(channel=None, time=None)[source]¶

nearest_calibration(time, channel='V1:Hrec_hoft_U00_lastWriteGPS')[source]¶

Find the nearest calibration data in the file to a given time, and return in.

Parameters:

• time (float) – A GPS time for which the calibration should be returned.

• channel (str) – The channel which should be checked to find the nearest calibration envelope.

Returns:

• array-like (If the calibration is in this file it is returned as an array.)

• None (If the calibration is not present in this file None is returned.)

datafind.frames.get_data_frames_private(types, start, end, download=False, host='datafind.igwn.org')[source]¶

Gather data frames which are not available via GWOSC.

Parameters:

• types (list) – The list of frame types to search for.

• start (int) – The starting GPS time.

• end (int) – The ending GPS time.

• download (bool, optional) – Choose whether to download the frame files, or simply return the URL. Defaults to False (will not download the files.)

Returns:

• urls (dict) – The dictionary of urls indexed by the detector name.

• files (dict) – The dictionary of downloaded files indexed by detector name.

datafind.frames.get_data_frames_gwosc(detectors, start, end, duration)[source]¶

Get data frames from GWOSC.

Calibration Module¶

The calibration module provides functionality for retrieving and manipulating calibration uncertainty envelopes.

Code to work with calibration files.

datafind.calibration.copy_file(path, rename, directory)[source]¶

class datafind.calibration.CalibrationUncertaintyEnvelope[source]¶

Bases: object

A class to represent an uncertainty envelope.

__init__()[source]¶

classmethod from_array(data, *args, **kwargs)[source]¶

Create an envelope from a data array.

classmethod from_file(filename, *args, **kwargs)[source]¶

Turn an ascii file into a CalibrationUncertaintyEnvelope

classmethod from_frame(frame, *args, **kwargs)[source]¶

Create an envelope by extracting it from a frame file.

frequency_domain_envelope(frame=None, **kwargs)[source]¶

Compute the frequency-domain representation of the envelope.

Parameters:

frame (str) – The filepath of the frame file.

to_file(filename)[source]¶

Write the envelope to an ascii file in the format expected by e.g. bilby.

Parameters:

filename (str) – The location the file should be written to.

plot(filename, save=True)[source]¶

Plot the calibration envelope.

datafind.calibration.get_calibration_from_frame(ifo, time, host='datafind.igwn.org', prefix='V1:Hrec_hoft_U00', timestamp_channel=None, frametype='V1:HoftAR1')[source]¶

Retrieve a calibration file from a frame file.

Parameters:

• ifo (str) – The interferometer to get the calibration data for.

• time (int) – The gpstime which calibration is required for.

• host (str, optional) – The URL of the datafind server which should be queried to retrieve frame file information. Defaults to datafind.igwn.org

• timestamp_channel (str) – The channel to check the location of the nearest calibration uncertainty envelope from.

• frametype (str, optional) – The frametype to be used to retrieve calibration uncertainty data from.

datafind.calibration.get_o3_style_calibration(dir, time)[source]¶

datafind.calibration.get_o4_style_calibration(dir, time, version='v1')[source]¶

datafind.calibration.find_calibrations_on_cit(time, base_dir=None, version=None, datafind_host='datafind.igwn.org', virgo_prefix='V1:Hrec_hoft_U00', timestamp_channel=None, frametype='V1:HoftAR1')[source]¶

Find the calibration file for a given time.

Parameters:

• time (number) – The GPS time for which the nearest calibration should be returned.

• base_dir (str) – The base directory to search for calibration envelopes. By default will use the default location.

• version (str) – The version number for LIGO (L1 and H1) calibration.

• datafind_host (str) – The URL to use for frame lookup using gw_data_find. Defaults to datafind.igwn.org.

• virgo_prefix (str) – The prefix to use for Virgo channels. Defaults to V1:Hrec_hoft_U00.

• timestamp_channel (str) – The channel to be used to look up the correct time for an uncertainty envelope. Defaults to using {virgo_prefix}__lastWriteGPS.

• frametype (str) – The frametype to use for extracting uncertainty envelopes. Defaults to V1:HoftAR1.

Metafiles Module¶

The metafiles module provides functionality for working with PESummary metafiles.

Functions to manipulate PESummary metafiles.

class datafind.metafiles.Metafile(filename: str)[source]¶

Bases: AbstractContextManager

This class handles PESummary metafiles in an efficient manner.

__init__(filename: str)[source]¶

Read a PESummary Metafile.

Parameters:

filename (str) – The path to the metafile.

psd(analysis=None)[source]¶

calibration(analysis=None)[source]¶

class datafind.metafiles.PSD(data, ifo=None)[source]¶

Bases: object

__init__(data, ifo=None)[source]¶

to_ascii(filename)[source]¶

to_xml()[source]¶

Report Module¶

The report module builds an HTML summary of a download job’s assets, including spectrograms of any downloaded frames.

Tools to help asimov-gwdata produce an html report.

class datafind.report.Report(production: GravitationalWaveTransient | None = None, settings: dict | None = None, webdir: str = 'report')[source]¶

Bases: object

A class to help produce an HTML report for asimov-gwdata.

__init__(production: GravitationalWaveTransient | None = None, settings: dict | None = None, webdir: str = 'report')[source]¶

Create a report for a GWData analysis.

Parameters:

• production (asimov.Production, optional) – The production object representing the analysis.

• settings (dict, optional) – The settings dictionary for the analysis.

• webdir (str) – The directory where the report HTML and assets will be saved.

Return type:

None

property frames¶

Return the frames in the report.

Returns:

A dictionary of frames. The keys correspond to the name of the interferometer, and the value will be the path to a single frame file or a list of paths to frame files.

Return type:

dict

Plotting Module¶

The plotting module provides the spectrogram plotting helper used by the report module.

datafind.plotting.plot_spectrogram(frame: str, channel: str, start: float | None = None, end: float | None = None, time: float | None = None, outseg_before: float = 2.0, outseg_after: float = 2.0, max_freq: float = 2048.0, min_freq: float = 10.0, q_range: tuple = (4, 64)) → Figure[source]¶

Plot a spectrogram around a given time and save to output_path.

Parameters:

• frame (str) – Path to the frame file to read data from.

• channel (str) – The channel to plot the spectrogram for.

• time (float) – GPS time of the event to plot around.

• outseg_before (float) – Number of seconds before the event time to include in the spectrogram.

• outseg_after (float) – Number of seconds after the event time to include in the spectrogram.

Returns:

fig – The figure object containing the spectrogram.

Return type:

matplotlib.figure.Figure

Asimov Pipeline¶

Integration with the asimov pipeline framework.

class datafind.asimov.Pipeline(production, category=None)[source]¶

Bases: Pipeline

An asimov pipeline for datafind.

name = 'gwdata'¶

config_template = PosixPath('/tmp/tmpa1c_88kq/cd23ff4cdcb40c75c8e4a2e31b2c91b3cf8a15e1/datafind/datafind_template.yml')¶

build_dag(dryrun=False)[source]¶

Create a condor submission description.

submit_dag(dryrun=False)[source]¶

Submit the DAG for this pipeline.

detect_completion()[source]¶

Check to see if the job has in fact completed.

after_completion()[source]¶

Define a hook to run after the DAG has completed execution successfully.

Note, this method should take no arguments, and should be over-written in the specific pipeline implementation if required.

collect_assets()[source]¶

Collect the assets for this job.

html()[source]¶

Return the HTML representation of this pipeline.

Utilities¶

datafind.utils.download_file(url, directory='frames', name=None)[source]¶

Download a file from a URL.

Parameters:

• url (str) – The URL of the file to be downloaded.

• name (str, optional) – The name the file should be saved as. Defaults to the name of the file on the remote resource.

• directory (str, optional) – The name of the directory in which to store the downloaded file. Defaults to “frames”.