`pycbc_condition_strain`: operations with strain data files

pycbc_condition_strain is a command-line tool which can be used for a variety of operations related to gravitational-wave strain data files. The basic idea of the tool is to combine the following operations:

Obtain a segment of gravitational-wave strain data, either by simulating detector noise, or reading an existing data file, or downloading public data from GWOSC.
Optionally, simulate one or more signals and add them to the data.
Optionally, apply a number of operations that a matched-filter search would apply before matched-filtering, such as low- or high-passing, resampling or glitch gating. These operations are sometimes referred to as “data conditioning”, hence the name of the tool.
Write the resulting data back to one or more files. Different output file formats are supported.

The following sections show concrete examples of common use cases. For a detailed list of all options, and option-specific help, see the output of:

pycbc_condition_strain --help

Splitting existing data into shorter frame files

The following command downloads a 64 s segment of gravitational-wave data from GWOSC and writes the data as four frame files of 16 s duration:

pycbc_condition_strain \
    --gps-start-time 1242442818 \
    --gps-end-time 1242442882 \
    --frame-type GWOSC \
    --channel-name H1:GWOSC-16KHZ_R1_STRAIN \
    --frame-duration 16 \
    --output-strain-file 'H1-STRAIN-{start}-{duration}.gwf'

Note that the strings {start} and {duration} in the output file name should be literally given like that. They are automatically replaced with the right values by pycbc_condition_strain when the --frame-duration option is used.

Conditioning existing data

This command downloads 64 s of gravitational-wave data from GWOSC, applies a high-pass filter with corner frequency of 15 Hz, downsamples the data to 2048 Hz, and writes it to a single frame file:

pycbc_condition_strain \
    --gps-start-time 1242442818 \
    --gps-end-time 1242442882 \
    --frame-type GWOSC \
    --channel-name H1:GWOSC-16KHZ_R1_STRAIN \
    --strain-high-pass 15 \
    --sample-rate 2048 \
    --output-strain-file H1-STRAIN_CONDITIONED-1242442818-64.gwf

Injecting simulated signals into existing data

Read 64 s of existing gravitational-wave data from GWOSC, add one or more simulated signals into it (specified by the injections.hdf file), and write the result to four frame files of 16 s duration:

pycbc_condition_strain \
    --gps-start-time 1242442818 \
    --gps-end-time 1242442882 \
    --frame-type GWOSC \
    --channel-name H1:GWOSC-16KHZ_R1_STRAIN \
    --injection-file injections.hdf \
    --frame-duration 16 \
    --output-strain-file 'H1-STRAIN_WITH_INJECTIONS-{start}-{duration}.gwf'

Simulating gravitational-wave data

The following command simulates 64 s of detector noise with a given power spectral density (in this case, a model for the noise expected for Virgo in the O4 run), adds one or more simulated signals to it (specified by the injections.hdf file), and writes the result to a single frame file:

pycbc_condition_strain \
    --fake-strain aLIGOAdVO4T1800545 \
    --fake-strain-seed 1234 \
    --fake-strain-flow 10 \
    --sample-rate 16384 \
    --gps-start-time 1242442818 \
    --gps-end-time 1242442882 \
    --channel-name V1:SIMULATED_STRAIN \
    --injection-file injections.hdf \
    --output-strain-file V1-SIMULATED_STRAIN-1242442818-64.gwf

Caveats

An error will be raised if data is not available for the requested time/detector combination. See Determine the times an instrument has valid data for an example of how to determine when data is valid for a particular detector.

When applying filters to the data, care should be taken to use the --pad-data option appropriately, in order to remove the portion of the data corrupted by the finite duration of the filter’s impulse response. --pad-data defaults to several seconds, which is usually safe.

Depending on the value of the --pad-data option, pycbc_condition_strain might read more data than what specified by the --gps-start-time and --gps-end-time options. Errors will arise if --pad-data is set to a value that causes pycbc_condition_strain to request data outside the range of availability.

pycbc_condition_strain: operations with strain data files