idq.utils

describe module, architecture, etc. Write a brief section about each of the main types of helpers we have in this module

class idq.utils.CadenceManager(timestamp=None, stride=1.0, delay=0.0, logger=None, enforce_integer_strides=True, offset=0, max_iters=inf, max_latency=inf, max_timestamp=inf, **extra_kwargs)

manages the cadence of our queries, including delay and timeout logic

poll()

generate segments corresponding to strides up until the current time This is essentially a multi-stide version of wait

wait()

wait until the current time is after timestamp+delay then update timestamp (increment by one stride)

idq.utils.chunker(sequence, chunk_size)

split up a sequence into sub-sequences of a maximum chunk size

idq.utils.draw_random_times(segments, rate=0.1)

draw random times poisson distributed within segments with corresponding rate (in Hz)

idq.utils.draw_random_times_in_segment(start, end, rate=0.1)

draw random times poisson distributed within [start, end] with corresponding rate (in Hz)

idq.utils.elapsed_time(func)

measures the elapsed time that a function call makes usage: add @elapsed_time decorator to function/method you want to time

idq.utils.expand_segments(segments, span)

expand segments to a minimum span

idq.utils.floor_div(x, n)

Floor a number by removing its remainder from division by another number n.

>>> floor_div(163, 10)
160
>>> floor_div(158, 10)
150

idq.utils.generate_unique_id(n=8)

generate a unique ID of length N

idq.utils.gps2latency(gps_time)

Given a gps time, measures the latency to ms precision relative to now.

idq.utils.livetime(segments)

return the livetime spanning the segment list NOTE: assumes segments are non-overlapping

>>> seg1 = segment(12300, 12302)
>>> seg2 = segment(12345, 12349)
>>> segs = segmentlist([seg1, seg2])
>>> livetime(segs)
6

idq.utils.parse_variable_args(args, max_args, default=None)

fill in unspecified variable arguments with a default value.

idq.utils.path2cache(rootdir, pathname)

given a rootdir and a glob-compatible pathname with possible shell-style wildcards, will find all files that match and populate a Cache. NOTE: this will only work with files that comply with the T050017 file convention.

idq.utils.segdb2active(start, end, flag, segdb_url='https://segments.ligo.org')

return the active segments for a flag

idq.utils.segdb2segs(start, end, union=None, intersect=None, exclude=None, segdb_url='https://segments.ligo.org')

query SegDb through the Python API directly adapted from a function originally written by Chris Pankow

idq.utils.segments_causal_kfold(segments, num_folds, initial_segs=None)

Split segments into K equal folds, returning a list over all possible K splits.

This is different from a regular K-fold split in that successive splits are supersets from the previous iteration.

Return segments in the form [(k-1) folds, k th fold].

Also can take in initial_segs, otherwise the first fold will have an empty training fold.

idq.utils.segments_checkerboard(segments, num_bins, num_segs_per_bin)

split segments into num_bins*num_segs_per_bin equal folds and associate segments within bins in a checkerboard pattern. return a list over segmentlists, one for each bin

idq.utils.segments_kfold(segments, num_folds)

Split segments into K equal folds, returning a list over all possible K splits.

Return segments in the form [(k-1) folds, 1 fold].

idq.utils.segs2datasets(segs, stride=32, keytype='string')

given a segment list, will give names for all relevant datasets that could be within an hdf5 file alongside the relevant segments within each dataset in a pair. the stride is given for a span of a single dataset.

idq.utils.segs2times(segs, dt)

Given a segment list, returns a list of inclusive ranges of times, spaced by an interval dt, which spans these segments.

>>> seg1 = segment(12300, 12302)
>>> seg2 = segment(12345, 12349)
>>> segs = segmentlist([seg1, seg2])
>>> segs2times(segs, 1)
[array([12300., 12301.]), array([12345., 12346., 12347., 12348.])]

idq.utils.split_segments_by_livetime(segments, num_folds)

Split segments into K equal folds by livetime, returning a list over all folds.

idq.utils.split_segments_by_stride(start, end, segments, stride)

Split segments into multiple segments with a maximum extent defined by stride. Returns a list of segment lists.

idq.utils.start_end2gps_dirs(start, end, lookback=0)

given start, end times, return the relevant gps directories to look at (leading 5 digits containing 100000 seconds)

if lookback is given, also lookback N directories in time.

idq.utils.time2window(time, duration)

Return the start and end time corresponding to the span rounded down to the nearest window time.

>>> time2window(12335, 100)
(12300, 12400)
>>> time2window(12300, 10)
(12300, 12310)

idq.utils.time_in_segment(t, seg)

return True iff time is in segment

>>> seg = segment(12300, 12302)
>>> time_in_segment(12346, seg)
False

idq.utils.time_in_segments(t, segments)

return True iff time is in segments

>>> seg1 = segment(12300, 12302)
>>> seg2 = segment(12345, 12349)
>>> segs = segmentlist([seg1, seg2])
>>> time_in_segments(12346, segs)
True

idq.utils.times_in_segment(times, seg)

like time_in_segment, but deals with an array instead of just a scalar

idq.utils.times_in_segments(times, segments)

returns a boolean array with the same shape as timestamp representing whether they are within segments