sage.data.primer.get_segments

Filename : get_segments.py Description : Short description of the file

Created on 2025-11-06 15:06:12

__author__ = Narenraju Nagarajan __copyright__ = Copyright 2025, Sage __license__ = MIT Licence __version__ = 0.0.1 __maintainer__ = Narenraju Nagarajan __affiliation__ = N/A __email__ = N/A __status__ = inUsage

GitHub Repository: NULL

Documentation: NULL

Attributes

logger

Classes

TimelineQuery

GWOSC segment query engine with multi-case dispatch.

Functions

get_all_detnames()	Return all detector names for reference
get_all_runnames()	Return all run names for reference
get_all_events()	Return all events as JSON from GWOSC

Module Contents

logger

get_all_detnames()

Return all detector names for reference

get_all_runnames()

Return all run names for reference

get_all_events()

Return all events as JSON from GWOSC

class TimelineQuery(detector=None, observing_run=None, start=None, end=None, dq_flag=None, auto_clean_empty_timelines=False)

GWOSC segment query engine with multi-case dispatch.

Accepts any combination of detector names, observing-run labels, GPS start/end, and data-quality (DQ) flags and routes to the appropriate GWOSC API call via a match statement (14 supported input combinations).

Results are stored in timeline as a NumPy structured array with dtype SEGMENT_DTYPE. Use download_segments() to populate the timeline, then optionally prune_segments() to remove known events or short segments.

Parameters:

• detector (str or list[str] or None) – Detector prefix(es) to query (e.g. "H1", ["H1", "L1"]).

• observing_run (str or list[str] or None) – LIGO observing-run label(s) (e.g. "O3a", "O3b").

• start (float or list[float] or None) – GPS start and end times bounding the query.

• end (float or list[float] or None) – GPS start and end times bounding the query.

• dq_flag (str or list[str] or None) – Data-quality flag(s) to query (e.g. "H1_DATA").

• auto_clean_empty_timelines (bool) – If True, automatically remove records with empty segment lists after download_segments() (default False).

timeline

Populated after download_segments(); structured array of (detector, flag, start_time, end_time, observing_run, segments) rows.

Type:

list or np.ndarray (SEGMENT_DTYPE)

Retrieve segment details from GWOSC

observing_run

start = None

end = None

data_quality_flag

detector

timeline = []

auto_clean = False

extract_det_from_flag(flag, detectors=_DETECTORS)

Return the detector prefix if the flag contains one, else None

Parameters:

• flag (str) – _description_

• detectors (_type_, optional) – _description_. Defaults to _DETECTORS.

Returns:

_description_

Return type:

_type_

clean_empty_timelines()

Remove timelines with empty segments

download_segments()

Match cases of all possible download scenarios We can write this in a super modular way without any redundancy but this reduces readability quite a bit.

Raises:

ValueError – _description_

prune_segments(rm_short_segments=False, rm_min_duration=20, rm_allevents=False, rm_window_length=30)

Prune segments of events/short-duration-segs and return updated timeline

Parameters:

• rmevents (bool, optional) – _description_. Defaults to False.

• rmwindow_length (float, optional) – _description_. Defaults to 30.

• min_segment_length (float, optional) – _description_. Defaults to 20.

• rm_short_segments (bool)

• rm_min_duration (float)

• rm_allevents (bool)

• rm_window_length (float)

split_into_mini_segments(mini_segment_length=512.0, minimum_segment_duration=20.0, sample_rate=4096.0)

Split segments in a structured array into mini-segments for training.

Each mini-segment: - Length mini_segment_length (seconds) - Starts exactly 1 sample after previous mini-segment end - Last mini-segment kept if >= minimum_segment_duration

Parameters:

• struct_array – np.ndarray Structured array of detectors and segments (same as your input)

• mini_segment_length – float Length of mini-segments in seconds

• minimum_segment_duration – float Minimum segment length to keep

Returns:

np.ndarray

Structured array in same format, with ‘segments’ replaced by mini-segments

sanity_check_mini_segments(mini_segment_length=512.0, minimum_segment_duration=20.0, sample_rate=4096.0, verbose=True)

Check the integrity of mini-segments in a structured array.

Parameters:

• struct_array – np.ndarray Structured array with ‘segments’ field containing mini-segments

• mini_segment_length – float Expected mini-segment length (for reference)

• minimum_segment_duration – float Minimum segment duration allowed

• verbose – bool Whether to print warnings

Raises:

ValueError if any check fails –