pycbc.frame package

Submodules

pycbc.frame.buffer module

Rolling buffers of frame data, used by low-latency analyses.

class pycbc.frame.buffer.DataBuffer(frame_src, channel_name, start_time, max_buffer=2048, force_update_cache=True, increment_update_cache=None, dtype=<class 'numpy.float64'>)[source]

Bases: object

A linear buffer that acts as a FILO for reading in frame data

advance(blocksize)[source]

Add blocksize seconds more to the buffer, push blocksize seconds from the beginning.

Parameters:: blocksize (int) – The number of seconds to attempt to read from the channel

attempt_advance(blocksize, timeout=10)[source]

Attempt to advance the frame buffer. Retry upon failure, except if the frame file is beyond the timeout limit.

Parameters:

blocksize (int) – The number of seconds to attempt to read from the channel
timeout ({int, 10}, Optional) – Number of seconds before giving up on reading a frame

Returns:

data – TimeSeries containg ‘blocksize’ seconds of frame data

Return type:

TimeSeries

null_advance(blocksize)[source]

Advance and insert zeros

Parameters:: blocksize (int) – The number of seconds to attempt to read from the channel

update_cache()[source]: Reset the cache. This can be used to update the cache if the result may change due to more files being added to the filesystem, for example.

update_cache_by_increment(blocksize)[source]

Update the internal cache by starting from the first frame and incrementing.

Guess the next frame file name by incrementing from the first found one. This allows a pattern to be used for the GPS folder of the file, which is indicated by GPSX where x is the number of digits to use.

Parameters:: blocksize (int) – Number of seconds to increment the next frame file.

class pycbc.frame.buffer.IDQBuffer(frame_src, idq_channel_name, idq_status_channel_name, idq_threshold, start_time, max_buffer=512, force_update_cache=False, increment_update_cache=None)[source]

Bases: object

Read iDQ timeseries from a frame file

advance(blocksize)[source]

Add blocksize seconds more to the buffer, push blocksize seconds from the beginning.

Parameters:: blocksize (int) – The number of seconds to attempt to read
Returns:: status – Returns True if advance is succesful, False if not.
Return type:: boolean

flag_at_times(start_time, duration, times, padding=0)[source]

Check whether the idq flag was on at given times

Parameters:

start_time (int) – Beginning time to request for
duration (int) – Number of seconds to check.
times (array of floats) – Times to check for an active flag
padding (float) – Amount of time in seconds to flag around samples below the iDQ FAP threshold

Returns:

flag_state – Boolean array of whether flag was on at given times

Return type:

np.ndarray

null_advance(blocksize)[source]

Advance and insert zeros

Parameters:: blocksize (int) – The number of seconds to advance the buffers

class pycbc.frame.buffer.StatusBuffer(frame_src, channel_name, start_time, max_buffer=2048, valid_mask=3, force_update_cache=False, increment_update_cache=None, valid_on_zero=False)[source]

Bases: DataBuffer

Read state vector or DQ information from a frame file

advance(blocksize)[source]

Add blocksize seconds more to the buffer, push blocksize seconds from the beginning.

Parameters:: blocksize (int) – The number of seconds to attempt to read from the channel
Returns:: status – Returns True if all of the status information if valid, False if any is not.
Return type:: boolean

check_valid(values, flag=None)[source]

Check if the data contains any non-valid status information

Parameters:

values (pycbc.types.Array) – Array of status information
flag (str, optional) – Override the default valid mask with a user defined mask.

Returns:

status –

Returns True if all of the status information if valid,: False if any is not.

Return type:

boolean

indices_of_flag(start_time, duration, times, padding=0)[source]

Return the indices of the times lying in the flagged region

Parameters:

start_time (int) – Beginning time to request for
duration (int) – Number of seconds to check.
padding (float) – Number of seconds to add around flag inactive times to be considered
well. (inactive as)

Returns:

indices (np.ndarray) – Array of indices marking the location of triggers within valid
time.

is_extent_valid(start_time, duration, flag=None)[source]

Check if the duration contains any non-valid frames

Parameters:

start_time (int) – Beginning of the duration to check in gps seconds
duration (int) – Number of seconds after the start_time to check
flag (str, optional) – Override the default valid mask with a user defined mask.

Returns:

status – Returns True if all of the status information if valid, False if any is not.

Return type:

boolean

pycbc.frame.cache module

Lists of data files (caches) and the file formats that can be read from them.

class pycbc.frame.cache.CacheEntry(observatory, description, start, duration, path)[source]

Bases: CacheEntry

One data file and the span of time it contains.

property end

classmethod from_file(path)[source]: Describe a file, using its name if it follows LIGO-T050017 and its content otherwise.

classmethod from_lal_line(line)[source]: Parse a line of a LAL-format cache file.

property url

class pycbc.frame.cache.FrameCache(iterable=(), /)[source]

Bases: list

A list of CacheEntry, sorted by start time.

sieve(regex=None, start=None, end=None)[source]: Return the entries whose URL matches regex and which overlap the interval [start, end).

pycbc.frame.cache.file_format(path)[source]: Return the format module that can read path, or None.

pycbc.frame.cache.locations_to_cache(locations, latest=False)[source]

Return a cumulative cache file build from the list of locations

Parameters:

locations (list) – A list of strings containing files, globs, or cache files used to build a combined cache.
latest (Optional, {False, Boolean}) – Only return a cache with the most recent frame in the locations. If false, all results are returned.

Returns:

cache – A cumulative cache containing the files derived from the list of locations, sorted by start time.

Return type:

FrameCache

pycbc.frame.frame module

This modules contains functions for reading in data from frame files or caches

pycbc.frame.frame.frame_paths(frame_type, start_time, end_time, server=None, url_type='file', site=None)[source]

Return the paths to a span of frame files.

Parameters:

frame_type (string) – The string representation of the frame type (ex. ‘H1_ER_C00_L1’).
start_time (int) – The start time that we need the frames to span.
end_time (int) – The end time that we need the frames to span.
server ({None, SERVER:PORT string}, optional) – Optional string to specify the datafind server to use. By default an attempt is made to use a local datafind server.
url_type (string) – Returns only frame URLs with a particular scheme or head such as “file” or “https”. Default is “file”, which queries locally stored frames. Option can be disabled if set to None.
site (string, optional) – One-letter string specifying which site you want data from (H, L, V, etc). If not given, the site is assumed to be the first letter of frame_type, which is usually (but not always) a safe assumption.

Returns:

paths – The list of paths to the frame files.

Return type:

list of paths

Examples

>>> paths = frame_paths('H1_LDAS_C02_L2', 968995968, 968995968+2048)

pycbc.frame.frame.locations_to_cache(locations, latest=False)[source]

Return a cumulative cache file build from the list of locations

Parameters:

locations (list) – A list of strings containing files, globs, or cache files used to build a combined cache.
latest (Optional, {False, Boolean}) – Only return a cache with the most recent frame in the locations. If false, all results are returned.

Returns:

cache – A cumulative cache containing the files derived from the list of locations, sorted by start time.

Return type:

FrameCache

pycbc.frame.frame.query_and_read_frame(frame_type, channels, start_time, end_time, sieve=None, check_integrity=False, sample_rate=None)[source]

Read time series from frame data.

Query for the location of physical frames matching the frame type. Return a time series containing the channel between the given start and end times.

Parameters:

frame_type (string) – The type of frame file that we are looking for. The string should begin with S: or SN:, in which case S is taken as the site to query. If this is not the case, the site will be guessed from the channel name or from the type in a different way, which may not work.
channels (string or list of strings) – Either a string that contains the channel name or a list of channel name strings.
start_time (LIGOTimeGPS or int) – The gps start time of the time series. Defaults to reading from the beginning of the available frame(s).
end_time (LIGOTimeGPS or int) – The gps end time of the time series. Defaults to the end of the frame.
sieve (string, optional) – Selects only frames where the frame URL matches the regular expression sieve
check_integrity (boolean) – Do an expensive checksum of the file before returning.
sample_rate (int, optional) – Sample rate in Hz for GWOSC/LOSC frames only. See pycbc.frame.gwosc.get_run. Ignored for other frame types.

Returns:

Frame Data – A TimeSeries or a list of TimeSeries, corresponding to the data from the frame file/cache for a given channel or channels.

Return type:

TimeSeries or list of TimeSeries

Examples

>>> ts = query_and_read_frame('H1_LDAS_C02_L2', 'H1:LDAS-STRAIN',
>>>                               968995968, 968995968+2048)

pycbc.frame.frame.read_frame(location, channels, start_time=None, end_time=None, duration=None, check_integrity=False, sieve=None)[source]

Read time series from frame data.

Using the location, which can either be a frame file “.gwf” or a frame cache “.gwf”, read in the data for the given channel(s) and output as a TimeSeries or list of TimeSeries.

Parameters:

location (string) – A source of gravitational wave frames. Either a frame filename (can include pattern), a list of frame files, or frame cache file.
channels (string or list of strings) – Either a string that contains the channel name or a list of channel name strings.
start_time ({None, LIGOTimeGPS}, optional) – The gps start time of the time series. Defaults to reading from the beginning of the available frame(s).
end_time ({None, LIGOTimeGPS}, optional) – The gps end time of the time series. Defaults to the end of the contiguous data following start_time. Note, this argument is incompatible with duration.
duration ({None, float}, optional) – The amount of data to read in seconds. Note, this argument is incompatible with end.
check_integrity ({True, bool}, optional) – Test the frame files for internal integrity.
sieve (string, optional) – Selects only frames where the frame URL matches the regular expression sieve

Returns:

Frame Data – A TimeSeries or a list of TimeSeries, corresponding to the data from the frame file/cache for a given channel or channels.

Return type:

TimeSeries or list of TimeSeries

pycbc.frame.frame.write_frame(location, channels, timeseries)[source]

Write a list of time series to a single frame file.

Parameters:

location (string) – A frame filename. A name ending in .hdf, .hdf5 or .h5 is written as a GWOSC HDF5 file, and any other as a GWF file.
channels (string or list of strings) – Either a string that contains the channel name or a list of channel name strings.
timeseries (TimeSeries) – A TimeSeries or list of TimeSeries, corresponding to the data to be written to the frame file for a given channel.

pycbc.frame.gwf module

Read and write GWF frame files using lalframe.

This is the only module in pycbc.frame that uses lalframe. It provides the same functions as pycbc.frame.gwosc_hdf (is_format, span, channel_info and read), each acting on a single file.

pycbc.frame.gwf.channel_info(path, channel)[source]: Return the numpy dtype and sample rate of a channel in a file.

pycbc.frame.gwf.is_format(path)[source]: Test if a file is a frame file by checking if its contents begins with the magic string ‘IGWD’.

pycbc.frame.gwf.read(path, channel, start, end, check_integrity=False)[source]

Read the samples of a channel between GPS times start and end, which must lie within the file.

Returns:

data (np.ndarray)
epoch (lal.LIGOTimeGPS) – GPS time of the first sample.
delta_t (float) – Sample spacing in seconds.

pycbc.frame.gwf.span(path)[source]: Return the GPS start time and duration of the data in a file.

pycbc.frame.gwf.write(location, channels, timeseries, start_time, duration)[source]: Write a list of time series to a single frame file. See pycbc.frame.write_frame.

pycbc.frame.gwosc module

This modules contains functions for getting data from the Gravitational Wave Open Science Center (GWOSC).

pycbc.frame.gwosc.get_run(time, ifo=None, sample_rate=None)[source]

Return the run name for a given time.

Parameters:

time (int) – The GPS time.
ifo (str) – The interferometer prefix string. Optional and normally unused, except for some special times where data releases were made for a single detector under unusual circumstances. For example, to get the data around GW170608 in the Hanford detector.
sample_rate (int, optional) – Select 4096 or 16384 Hz. The default preserves the existing release: 4096 Hz before O2 and 16384 Hz from O2 onward.

pycbc.frame.gwosc.gwosc_frame_json(ifo, start_time, end_time, sample_rate=None)[source]

Get the information about the public data files in a duration of time.

Parameters:

ifo (str) – The name of the interferometer to find the information about.
start_time (int) – The start time in GPS seconds.
end_time (int) – The end time in GPS seconds.
sample_rate (int, optional) – See get_run.

Returns:

info – A dictionary containing information about the files that span the requested times.

Return type:

dict

pycbc.frame.gwosc.gwosc_frame_urls(ifo, start_time, end_time, sample_rate=None)[source]

Get a list of URLs to GWOSC frame files.

Parameters:

ifo (str) – The name of the interferometer to find the information about.
start_time (int) – The start time in GPS seconds.
end_time (int) – The end time in GPS seconds.
sample_rate (int, optional) – See get_run.

Returns:

frame_files – URLs of frame files that span the requested times.

Return type:

list

pycbc.frame.gwosc.read_frame_gwosc(channels, start_time, end_time, sample_rate=None)[source]

Read channels from GWOSC data.

Parameters:

channels (str or list) – The channel name to read or list of channel names.
start_time (int) – The start time in GPS seconds.
end_time (int) – The end time in GPS seconds.
sample_rate (int, optional) – See get_run.

Returns:

ts – Returns a timeseries or list of timeseries with the requested data.

Return type:

TimeSeries

pycbc.frame.gwosc.read_strain_gwosc(ifo, start_time, end_time, sample_rate=None)[source]

Get the strain data from the GWOSC data.

Parameters:

ifo (str) – The name of the interferometer to read data for. Ex. ‘H1’, ‘L1’, ‘V1’.
start_time (int) – The start time in GPS seconds.
end_time (int) – The end time in GPS seconds.
sample_rate (int, optional) – See get_run.

Returns:

ts – Returns a timeseries with the strain data.

Return type:

TimeSeries

pycbc.frame.gwosc_hdf module

Read GWOSC HDF5 strain files.

GWOSC (https://gwosc.org) distributes the same data as GWF and HDF5 files. In the HDF5 files the strain is the dataset strain/Strain and the 1 Hz data quality and injection bitmasks are quality/simple/DQmask and quality/injections/Injmask. Each has the attributes Xstart (GPS time of the first sample) and Xspacing (sample spacing in seconds).

This module provides the same functions as pycbc.frame.gwf.

pycbc.frame.gwosc_hdf.channel_info(path, channel)[source]: Return the numpy dtype and sample rate of a channel in a file.

pycbc.frame.gwosc_hdf.is_format(path)[source]: Test if a file is an HDF5 file by checking its signature.

pycbc.frame.gwosc_hdf.read(path, channel, start, end, check_integrity=False)[source]

Read the samples of a channel between GPS times start and end, which must lie within the file. check_integrity is ignored, as GWOSC HDF5 files contain no checksums.

Returns:

data (numpy.ndarray)
epoch (lal.LIGOTimeGPS) – GPS time of the first sample.
delta_t (float) – Sample spacing in seconds.

pycbc.frame.gwosc_hdf.span(path)[source]: Return the GPS start time and duration of the data in a file.

pycbc.frame.gwosc_hdf.write(location, channels, timeseries, start_time, duration)[source]: Write a list of time series to a single GWOSC HDF5 file. See pycbc.frame.write_frame. The channels must all be of one detector, which is taken from the first, e.g. ‘H1’ for ‘H1:STRAIN’.

pycbc.frame.store module

This modules contains functions for reading in data from hdf stores

pycbc.frame.store.read_store(fname, channel, start_time, end_time)[source]

Read time series data from hdf store

Parameters:

fname (str) – Name of hdf store file
channel (str) – Channel name to read
start_time (int) – GPS time to start reading from
end_time (int) – GPS time to end time series

Returns:

ts – Time series containing the requested data

Return type:

pycbc.types.TimeSeries

Module contents

pycbc.frame.flag_names_to_bitmask(flags)[source]: Takes a list of flag names corresponding to bits in a status channel and returns the corresponding bit mask.