pycbc.inject package

Submodules

pycbc.inject.inject module

This module provides utilities for injecting signals into data

class pycbc.inject.inject.CBCHDFInjectionSet(sim_file, hdf_group=None, **kwds)

Bases: _HDFInjectionSet

Manages CBC injections.

apply(strain, detector_name, f_lower=None, distance_scale=1, simulation_ids=None, inj_filter_rejector=None, injection_sample_rate=None)

Add injections (as seen by a particular detector) to a time series.

Parameters:

• strain (TimeSeries) – Time series to inject signals into, of type float32 or float64.

• detector_name (string) – Name of the detector used for projecting injections.

• f_lower ({None, float}, optional) – Low-frequency cutoff for injected signals. If None, use value provided by each injection.

• distance_scale ({1, float}, optional) – Factor to scale the distance of an injection with. The default is no scaling.

• simulation_ids (iterable, optional) – If given, only inject signals with the given simulation IDs.

• inj_filter_rejector (InjFilterRejector instance; optional, default=None) – If given send each injected waveform to the InjFilterRejector instance so that it can store a reduced representation of that injection if necessary.

• injection_sample_rate (float, optional) – The sample rate to generate the signal before injection

Return type:

None

Raises:

TypeError – For invalid types of strain.

end_times()

Return the end times of all injections

injtype = 'cbc'

make_strain_from_inj_object(inj, delta_t, detector_name, f_lower=None, distance_scale=1)

Make a h(t) strain time-series from an injection object.

Parameters:

• inj (injection object) – The injection object to turn into a strain h(t). Can be any object which has waveform parameters as attributes, such as an element in a WaveformArray.

• delta_t (float) – Sample rate to make injection at.

• detector_name (string) – Name of the detector used for projecting injections.

• f_lower ({None, float}, optional) – Low-frequency cutoff for injected signals. If None, use value provided by each injection.

• distance_scale ({1, float}, optional) – Factor to scale the distance of an injection with. The default is no scaling.

Returns:

signal – h(t) corresponding to the injection.

Return type:

float

required_params = ('tc',)

static supported_approximants()

Return a list of the supported approximants.

class pycbc.inject.inject.IncoherentFromFileHDFInjectionSet(sim_file, hdf_group=None, **kwds)

Bases: _HDFInjectionSet

Manages injecting an arbitrary time series loaded from a file.

The injections must have the following attributes set:

• filename: (str) the name of the file to load containing the time series. The file type and format can be a frame file or anything understood by pycbc.types.timeseries.load_timeseries(). If a frame file (ends in .gwf) is specified, a channel attribute must also be set.

• DETECTOR_gps_time: (float) The GPS time at which the time series should be added to the DETECTOR data, where DETECTOR is the name of the instrument to inject into (e.g., h1_gps_time). The time series will only be injected into a detector if a GPS time is given for that detector. Set to -inf, nan, or do not provide a GPS time for a particular detector if you do not want to inject into that detector.

• ref_point: (str or float) What to use as the reference time of the injected time series. The time series will be injected into the detector such that the ref_point in the time series occurs at the specifed DETECTOR_gps_time. Options are: 'start', 'end', 'center', 'absmax', or a float giving the number of seconds into the time series.

In addition, the following attributes may optionally be provided:

• channel: (str): If the filename points to a frame file, the channel to load in that file. Must be provided for frame files.

• DETECTOR_phase_shift: (float) Apply a phase shift to the time series before adding it to detector DETECTOR.

• DETECTOR_amp_scale: (float) Scale the amplitude by the given amount before adding it to detector DETECTOR.

• slice_start: (float) Slice the time series starting at ref_point + slice_start before injecting into the data. Measured in seconds.

• slice_end: (float) Slice the time series ending at ref_point + slice_end before injecting into the data. Measured in seconds.

• left_taper_width: (float) Taper the start of the time series (after slicing) using half a kaiser window over the given number of seconds. See :py:func:waveform.utils.td_taper for more details.

• right_taper_width: (float) Taper the end of the time series (after slicing) using half a kaiser window over the given number of seconds. See :py:func:waveform.utils.td_taper for more details.

The signal will be resampled to the same sample rate as the data it is being injected into.

In order to use with pycbc_create_injections, set the approximant name to 'incoherent_from_file'.

apply(strain, detector_name, distance_scale=1, injection_sample_rate=None, inj_filter_rejector=None)

Adds injections to a detector’s time series.

end_times()

Return the end times of all injections

injtype = 'incoherent_from_file'

loadts(inj)

Loads an injection time series.

After the first time a time series is loaded it will be added to an internal buffer for faster in case another injection uses the same series.

make_strain_from_inj_object(inj, delta_t, detector_name, distance_scale=1, ts=None)

Make a h(t) strain time-series from an injection object.

required_params = ('filename', 'ref_point')

set_ref_time(inj, ts)

Sets t=0 of the given time series based on what the given injection’s ref_point is.

static slice_and_taper(inj, ts)

Slices and tapers a timeseries based on the injection settings.

This assumes that set_ref_time has been applied to the timeseries first. A copy of the time series will be returned even if no slicing or tapering is done.

static supported_approximants()

Return a list of the supported approximants.

class pycbc.inject.inject.InjectionSet(sim_file, **kwds)

Bases: object

Manages sets of injections and injects them into time series.

Injections are read from either LIGOLW XML files or HDF files.

Parameters:

• sim_file (string) – Path to an hdf file or a LIGOLW XML file that contains a SimInspiralTable.

• **kwds – The rest of the keyword arguments are passed to the waveform generation function when generating injections.

table

static from_cli(opt)

Return an instance of InjectionSet configured as specified on the command line.

static write(filename, samples, write_params=None, static_args=None, injtype=None, **metadata)

Writes the injection samples to the given hdf file.

Parameters:

• filename (str) – The name of the file to write to.

• samples (io.FieldArray) – FieldArray of parameters.

• write_params (list, optional) – Only write the given parameter names. All given names must be keys in samples. Default is to write all parameters in samples.

• static_args (dict, optional) – Dictionary mapping static parameter names to values. These are written to the attrs.

• injtype (str, optional) – Specify which HDFInjectionSet class to use for writing. If not provided, will try to determine it by looking for an approximant in the static_args, followed by the samples.

• **metadata – All other keyword arguments will be written to the file’s attrs.

class pycbc.inject.inject.RingdownHDFInjectionSet(sim_file, hdf_group=None, **kwds)

Bases: _HDFInjectionSet

Manages a ringdown injection: reads injection from hdf file and injects it into time series.

apply(strain, detector_name, distance_scale=1, simulation_ids=None, inj_filter_rejector=None, injection_sample_rate=None)

Add injection (as seen by a particular detector) to a time series.

Parameters:

• strain (TimeSeries) – Time series to inject signals into, of type float32 or float64.

• detector_name (string) – Name of the detector used for projecting injections.

• distance_scale (float, optional) – Factor to scale the distance of an injection with. The default (=1) is no scaling.

• simulation_ids (iterable, optional) – If given, only inject signals with the given simulation IDs.

• inj_filter_rejector (InjFilterRejector instance, optional) – Not implemented. If not None, a NotImplementedError will be raised.

• injection_sample_rate (float, optional) – The sample rate to generate the signal before injection

Return type:

None

Raises:

• NotImplementedError – If an inj_filter_rejector is provided.

• TypeError – For invalid types of strain.

end_times()

Return the approximate end times of all injections.

Currently, this just assumes all ringdowns are 2 seconds long.

injtype = 'ringdown'

make_strain_from_inj_object(inj, delta_t, detector_name, distance_scale=1)

Make a h(t) strain time-series from an injection object as read from an hdf file.

Parameters:

• inj (injection object) – The injection object to turn into a strain h(t).

• delta_t (float) – Sample rate to make injection at.

• detector_name (string) – Name of the detector used for projecting injections.

• distance_scale (float, optional) – Factor to scale the distance of an injection with. The default (=1) is no scaling.

Returns:

signal – h(t) corresponding to the injection.

Return type:

float

required_params = ('tc',)

static supported_approximants()

Return a list of the supported approximants.

class pycbc.inject.inject.SGBurstInjectionSet(sim_file, **kwds)

Bases: object

Manages sets of sine-Gaussian burst injections: reads injections from LIGOLW XML files and injects them into time series.

Parameters:

sim_file (string) – Path to a LIGOLW XML file containing a SimBurstTable with injection definitions.

indoc

table

apply(strain, detector_name, f_lower=None, distance_scale=1)

Add injections (as seen by a particular detector) to a time series.

Parameters:

• strain (TimeSeries) – Time series to inject signals into, of type float32 or float64.

• detector_name (string) – Name of the detector used for projecting injections.

• f_lower ({None, float}, optional) – Low-frequency cutoff for injected signals. If None, use value provided by each injection.

• distance_scale ({1, foat}, optional) – Factor to scale the distance of an injection with. The default is no scaling.

Return type:

None

Raises:

TypeError – For invalid types of strain.

pycbc.inject.inject.get_hdf_injtype(sim_file)

Gets the HDFInjectionSet class to use with the given file.

This looks for the injtype in the given file’s top level attrs. If that attribute isn’t set, will default to CBCHDFInjectionSet.

Parameters:

sim_file (str) – Name of the file. The file must already exist.

Returns:

The type of HDFInjectionSet to use.

Return type:

HDFInjectionSet

pycbc.inject.inject.hdf_injtype_from_approximant(approximant)

Gets the HDFInjectionSet class to use with the given approximant.

Parameters:

approximant (str) – Name of the approximant.

Returns:

The type of HDFInjectionSet to use.

Return type:

HDFInjectionSet

pycbc.inject.inject.legacy_approximant_name(apx)

Convert the old style xml approximant name to a name and phase_order. Alex: I hate this function. Please delete this when we use Collin’s new tables.

pycbc.inject.inject.projector(detector_name, inj, hp, hc, distance_scale=1)

Use the injection row to project the polarizations into the detector frame

pycbc.inject.inject.set_sim_data(inj, field, data)

Sets data of a SimInspiral instance.

pycbc.inject.injfilterrejector module

This module contains functions to filter injections with only useful templates.

This module implements a set of checks to test for each segment and template combination whether injections contained within the segment are sufficiently “similar” to the template to require a matched-filter. There are a few ways of testing the “similarity” of templates and injections.

• A chirp time threshold rejects templates if chirp time difference is large

• A coarse match threshold rejects templates if a coarse overlap is small

class pycbc.inject.injfilterrejector.InjFilterRejector(injection_file, chirp_time_window, match_threshold, f_lower, coarsematch_deltaf=1.0, coarsematch_fmax=256, seg_buffer=10)

Bases: object

Class for holding parameters for using injection/template pre-filtering.

This class is responsible for identifying where a matched-filter operation between templates and data is unncessary because the injections contained in the data will not match well with the given template.

classmethod from_cli(opt)

Create an InjFilterRejector instance from command-line options.

classmethod from_cli_multi_ifos(opt, ifos)

Create an InjFilterRejector instance from command-line options.

classmethod from_cli_single_ifo(opt, ifo)

Create an InjFilterRejector instance from command-line options.

generate_short_inj_from_inj(inj_waveform, simulation_id)

Generate and a store a truncated representation of inj_waveform.

template_segment_checker(bank, t_num, segment)

Test if injections in segment are worth filtering with template.

Using the current template, current segment, and injections within that segment. Test if the injections and sufficiently “similar” to any of the injections to justify actually performing a matched-filter call. Ther are two parts to this test: First we check if the chirp time of the template is within a provided window of any of the injections. If not then stop here, it is not worth filtering this template, segment combination for this injection set. If this check passes we compute a match between a coarse representation of the template and a coarse representation of each of the injections. If that match is above a user-provided value for any of the injections then filtering can proceed. This is currently only available if using frequency-domain templates.

Parameters:

FIXME

Return type:

FIXME

pycbc.inject.injfilterrejector.insert_injfilterrejector_option_group(parser)

Add options for injfilterrejector to executable.

pycbc.inject.injfilterrejector.insert_injfilterrejector_option_group_multi_ifo(parser)

Add options for injfilterrejector to executable.

Module contents