Detector Utilities

Stability: Stable

Detector channel definitions, unit handling, and I/O helpers.

class gwexpy.detector.Channel(name: str | Self, **params)[source]

Bases: object

Representation of a gravitational-wave detectory data channel.

Parameters:

  • name (str, Channel) – Name of this Channel (or another Channel itself). If a Channel is given, all other parameters not set explicitly will be copied over.

  • sample_rate (float, ~astropy.units.Quantity, optional) – Rate at which data are sampled for this channel, simple floats must be given in Hz.

  • unit (~astropy.units.Unit, str, optional) – Name of the unit for the data of this channel.

  • frequency_range (tuple of float) – [low, high) spectral frequency range of interest for this channel.

  • safe (bool, optional) – If True this channel is β€˜safe’ to use as a witness of non-gravitational-wave noise in the detector.

  • dtype (numpy.dtype, optional) – Numeric type of data for this channel.

  • frametype (str, optional) – LDAS name for frames that contain this channel.

  • model (str, optional) – Name of the SIMULINK front-end model that produces this channel.

Notes

The Channel structure implemented here is designed to match the data recorded in the LIGO Channel Information System (https://cis.ligo.org) for which a query interface is provided.

MATCH = re.compile('((?:(?P<ifo>[A-Z]\\d))?|[\\w-]+):(?:(?P<system>[a-zA-Z0-9]+))?(?:[-_](?P<subsystem>[a-zA-Z0-9]+))?(?:[-_](?P<signal>[a-zA-Z0-9_-]+?))?(?:[\\.-](?P<trend>[a-z]+))?(?:,(?P<type>([a-z]-)?[a-z]+))?$')
property name: str

Name of this channel.

This should follow the naming convention, with the following format: β€˜IFO:SYSTEM-SUBSYSTEM_SIGNAL’

property sample_rate: Quantity | None

Rate of samples (Hertz) for this channel.

property unit: UnitBase | None

Data unit for this channel.

property frequency_range: Quantity | None

Frequency range of interest (Hertz) for this channel.

property safe: bool | None

Whether this channel is β€˜safe’ to use as a noise witness.

Any channel that records part or all of a GW signal as it interacts with the interferometer is not safe to use as a noise witness

A safe value of None simply indicates that the safety of this channel has not been determined

property model: str | None

Name of the SIMULINK front-end model that defines this channel.

property type: str | None

DAQ data type for this channel.

Valid values for this field are restricted to those understood by the NDS2 client sofware, namely:

β€˜m-trend’, β€˜online’, β€˜raw’, β€˜reduced’, β€˜s-trend’, β€˜static’, β€˜test-pt’

property ndstype: int

NDS type integer for this channel.

This property is mapped to the Channel.type string.

property dtype: dtype | None

Numeric type for data in this channel.

property url: str | None

CIS browser url for this channel.

property frametype: str | None

LDAS type description for frame files containing this channel.

property ifo: str | None

Interferometer prefix for this channel.

property system: str | None

Instrumental system for this channel.

property subsystem: str | None

Instrumental sub-system for this channel.

property signal: str | None

Instrumental signal for this channel.

property trend: str | None

Trend type for this channel.

property texname: str

Name of this channel in LaTeX printable format.

property ndsname: str

Name of this channel as stored in the NDS database.

classmethod query(name: str, *, kerberos: bool | None = None, **kwargs) → Self[source]

Query the LIGO Channel Information System for name.

Parameters:

  • name (str) – Name of channel for which to query.

  • kerberos (bool, optional) – If True use an existing Kerberos ticket as the authentication credential. Default (None) is to check for credentials and request username and password if none are found.

  • kwargs – Other keyword arguments are passed directly to ciecplib.get().

Returns:

channel – A new Channel containing all of the attributes set from its entry in the CIS.

Return type:

Channel

classmethod query_nds2(name: str, host: str | None = None, port: int | None = None, connection: nds2.connection | None = None, type: str | int | None = None) → Self[source]

Query an NDS server for channel information.

Parameters:

  • name (str) – Name of channel for which to query.

  • host (str, optional) – Name of NDS2 server.

  • port (int, optional) – Port number for NDS2 connection.

  • connection (nds2.connection) – Open connection to use for query.

  • type (str, int) – NDS2 channel type with which to restrict query

Returns:

channel – Channel with metadata retrieved from NDS2 server.

Return type:

Channel

Raises:

ValueError – If multiple channels are found for a given name.

Notes

Warning

One of host or connection is required.

classmethod from_nds2(nds2channel: nds2.channel) → Self[source]

Generate a new channel using an existing nds2.channel object.

classmethod from_arrakis(arrakischannel: arrakis.Channel) → Self[source]

Generate a new channel using an existing arrakis.Channel.

Parameters:

arrakischannel (arrakis.Channel) – The input channel from Arrakis to parse.

Returns:

channel – A new Channel.

Return type:

gwpy.detector.Channel

classmethod parse_channel_name(name: str, *, strict: bool = True) → dict[str, str | None][source]

Decompose a channel name string into its components.

This method parses channels acccording to the LIGO Channel Naming Convention LIGO-T990033.

Parameters:

  • name (str) – Name to parse.

  • strict (bool, optional) – If True (default) require exact matching of format, with no surrounding text.

Returns:

match – dict of channel name components with the following keys:

  • ’ifo’: the letter-number interferometer prefix

  • ’system’: the top-level system name

  • ’subsystem’: the second-level sub-system name

  • ’signal’: the remaining underscore-delimited signal name

  • ’trend’: the trend type

  • ’ndstype’: the NDS2 channel suffix

Any optional keys that aren’t found will return a value of None

Return type:

dict

Raises:

ValueError – if the name cannot be parsed with at least an IFO and SYSTEM

Examples

>>> Channel.parse_channel_name("L1:LSC-DARM_IN1_DQ")
{'ifo': 'L1',
 'ndstype': None,
 'signal': 'IN1_DQ',
 'subsystem': 'DARM',
 'system': 'LSC',
 'trend': None}

>>> Channel.parse_channel_name(
...     "H1:ISI-BS_ST1_SENSCOR_GND_STS_X_BLRMS_100M_300M.rms,m-trend",
... )
{'ifo': 'H1',
 'ndstype': 'm-trend',
 'signal': 'ST1_SENSCOR_GND_STS_X_BLRMS_100M_300M',
 'subsystem': 'BS',
 'system': 'ISI',
 'trend': 'rms'}
find_frametype(gpstime: SupportsToGps | None = None, *, frametype_match: str | Pattern | None = None, return_all: Literal[False] = False, allow_tape: bool = True, **kwargs) → str[source]
find_frametype(gpstime: SupportsToGps | None = None, *, frametype_match: str | Pattern | None = None, return_all: Literal[True] = True, allow_tape: bool = True, **kwargs) → list[str]

Find the containing frametype(s) for this Channel.

Parameters:

  • gpstime (int, optional) – A reference GPS time at which to search for frame files. Default is to search in the latest available data for each discoverable dataset.

  • frametype_match (str) – A regular expression string to use to down-select from the list of all available datasets.

  • return_all (bool, optional) – If True return all matched datasets; if False (default) only the first match is returned

  • allow_tape (bool, default: True) – If True (default) include datasets whose files are stored on slow magnetic tape.

  • kwargs – Other keyword arguments are passed directly to gwpy.io.datafind.find_frametype().

Returns:

frametype – If return_all=False a single str containing the β€˜best’ dataset name. If return_all=True a list of dataset names.

Return type:

str or list[str]

copy() → Self[source]

Return a copy of this Channel.

class gwexpy.detector.ChannelList(iterable=(), /)[source]

Bases: list

A list of channels <Channel>, with parsing utilities.

property ifos: set[str]

The set of interferometer prefixes used in this ChannelList.

read = <gwpy.detector.connect.ChannelListRead object>
write = <gwpy.detector.connect.ChannelListWrite object>
classmethod from_names(*names: str) → Self[source]

Create a new ChannelList from a list of names.

The list of names can include comma-separated sets of names, in which case the return will be a flattened list of all parsed channel names.

find(name: str) → int[source]

Find the Channel with a specific name in this ChannelList.

Parameters:

name (str) – name of the Channel to find

Returns:

index – the position of the first Channel in this ChannelList whose ~Channel.name matches the search key.

Return type:

int

Raises:

ValueError – if no matching Channel is found.

sieve(name: str | re.Pattern | None = None, sample_rate: float | None = None, *, sample_range: tuple[float, float] | None = None, exact_match: bool = False, **others) → Self[source]

Find all channels in this list matching the specified criteria.

Parameters:

  • name (str, or regular expression) – Any part of the channel name against which to match (or full name if exact_match=False is given).

  • sample_rate (float) – Rate (number of samples per second) to match exactly.

  • sample_range (2-tuple) – [low, high] closed interval or rates to match within.

  • exact_match (bool) – If True return channels matching name exactly. If False (default) allow partial matches.

  • others – Other (key, value) attribute pairs to match.

Returns:

new – A new ChannelList containing the matching channels.

Return type:

ChannelList

classmethod query(name: str, *, kerberos: bool | None = None, **kwargs) → Self[source]

Query the LIGO Channel Information System a ChannelList.

Parameters:

  • name (str) – name of channel, or part of it.

  • kerberos (bool, optional) – If True use an existing Kerberos ticket as the authentication credential. Default (None) is to check for credentials and request username and password if none are found.

  • kwargs – Other keyword arguments are passed directly to ciecplib.get().

Returns:

channels – A new list containing all Channels <Channel> found.

Return type:

ChannelList

classmethod query_nds2(names: list[str], *, host: str | None = None, port: int | None = None, connection: nds2.connection | None = None, type: str | int | None = 127, unique: bool = False) → Self[source]

Query an NDS server for channel information.

Parameters:

  • names (str) – Names of requested channels.

  • host (str, optional) – Name of NDS2 server.

  • port (int, optional) – Port number for NDS2 connection.

  • connection (nds2.connection, optional) – Open connection to use for query.

  • type (str, int, optional) – NDS2 channel type with which to restrict query

  • unique (bool, optional) – If True require a unique query result for each name given. Default is False.

Returns:

channellist – list of Channels <Channel> with metadata retrieved from NDS2 server

Return type:

ChannelList

Raises:

ValueError – If multiple channels are found for a given name and unique=True is given.

Notes

Warning

One of host or connection is required.

classmethod query_nds2_availability(channels: list[str | Channel], start: SupportsToGps, end: SupportsToGps, ctype: int | str = 127, connection: nds2.connection | None = None, host: str | None = None, port: int | None = None) → SegmentListDict[source]

Query for when data are available for these channels in NDS2.

Parameters:

  • channels (list of str or Channel) – List of Channel or str for which to search.

  • start (~gwpy.time.LIGOTimeGPS, float, str) – GPS start time of search. Any input parseable by ~gwpy.time.to_gps is fine.

  • end (~gwpy.time.LIGOTimeGPS, float, str, optional) – GPS end time of search. Any input parseable by ~gwpy.time.to_gps is fine.

  • ctype (int, str) – The NDS2 channel type name or enum ID against which to restrict results. Default is 127 which means β€˜all’.

  • host (str, optional) – Name of NDS2 server to use.

  • port (int, optional) – Port number for NDS2 connection.

  • connection (nds2.connection, optional) – Open connection to use for query.

Returns:

segdict – dict of (name, SegmentList) pairs

Return type:

~gwpy.segments.SegmentListDict

gwexpy.detector.get_timezone(ifo: str) → str[source]

Return the timezone for the given interferometer prefix.

Parameters:

ifo (str) – Prefix of interferometer, e.g. 'X1'

Returns:

timezone – The name of the timezone for ifo.

Return type:

str

Raises:

ValueError – If ifo is not recognised.

Examples

>>> get_timezone("G1")
'Europe/Berlin'
gwexpy.detector.get_timezone_offset(ifo: str, dt: datetime | None = None) → float[source]

Return the offset in seconds between UTC and the given interferometer.

Parameters:

  • ifo (str) – Prefix of interferometer, e.g. 'X1'

  • dt (datetime.datetime, optional) – The time at which to calculate the offset. Default is datetime.datetime.now.

Returns:

offset – The offset in seconds between the timezone of the interferometer and UTC.

Return type:

float