The Channel¶

What is a ‘channel’?¶

Each of the laser-interferometer gravitational-wave detectors record thousands of different data streams capturing a single instrumental error or control signal, or the output of an environmental sensor. These data streams are known as ‘channels’, and are named according to a convention that describes its source in the instrument, and the signal it records, for example:

L1:PSS-ISS_PDB_OUT_DQ

describes the output signal (OUT) from photodiode-B (PDB) inside the Intensity Stabilisation System (ISS) of the Pre-Stabilised Laser (PSL) powering the L1 instrument, hosted at the LIGO Livingston Observatory. The DQ suffix indicates that this channel was recorded in data files for offline study (many more ‘test point’ channels are used only in real-time, and are never recorded).

A simple representation of this physical signal is provided by the Channel object:

>>> from gwpy.detector import Channel
>>> signal = Channel('L1:PSL-ISS_PDB_OUT_DQ')

This new Channel has a number of attributes that describe its source, derived from its name:

>>> print(hoft.ifo)
'L1'
>>> print(hoft.system)
'PSL'
>>> print(hoft.subsystem)
'ISS'

and so on.

Alongside nomnitive attributes, each Channel has the following attributes:

Each of these can be manually passed to the Channel constructor, or downloaded directly from the LIGO Channel Information System.

The LIGO Channel Information System (https://cis.ligo.org)¶

All of the LIGO interferometer data channels are recorded in the Channel Information System (https://cis.ligo.org), a queryable database containing the details of each channel recorded to disk from the observatories. The Channel.query() classmethod allows you to query the database as follows:

>>> from gwpy.detector import Channel
>>> chan = Channel.query('L1:IMC-F_OUT_DQ')
>>> print(chan.sample_rate)
16384.0 Hz
>>> print(chan.url)
https://cis.ligo.org/channel/282666
>>> print(chan.model)
l1lsc

In this example we have accessed the information for the frequency noise output signal (F_OUT) from the Input Mode Cleaner (IMC) of the L1 instrument.

The ChannelList¶

Groups of channels may be collected together in a ChannelList, a simple extension of the built-in list with functionality for finding and sieveing for specific Channel names, sample-rates, or types.

Class reference¶

This reference contains the following class entries:

class gwpy.detector.Channel(name, **params)[source]¶

Bases: object

Representation of a laser-interferometer 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, Quantity, optional number of samples per second unit : 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 is this channel ‘safe’ to use as a witness of non-gravitational-wave noise in the interferometer 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.

copy()[source]¶

Returns a copy of this channel

dtype¶

Numeric type for data in this channel.

Type:	dtype

find_frametype(gpstime=None, frametype_match=None, host=None, port=None, return_all=False, allow_tape=True)[source]¶

Find the containing frametype(s) for this Channel

Parameters:

gpstime : int a reference GPS time at which to search for frame files frametype_match : str a regular expression string to use to down-select from the list of all available frametypes host : str the name of the datafind server to use for frame file discovery port : int the port of the datafind server on the given host return_all: `bool`, default: `False` return all matched frame types, otherwise only the first match is returned allow_tape : bool, default: True include frame files on (slow) magnetic tape in the search

Returns:

frametype : str, list the first matching frametype containing the this channel (return_all=False, or a list of all matches

frametype¶

LDAS type description for frame files containing this channel.

frequency_range¶

Frequency range of interest (Hertz) for this channel

Type:	Quantity array

classmethod from_nds2(nds2channel)[source]¶

Generate a new channel using an existing nds2.channel object

ifo¶

Interferometer prefix for this channel.

Type:	str

model¶

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

Type:	str

name¶

Name of this channel.

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

Type:	str

ndsname¶

Name of this channel as stored in the NDS database

ndstype¶

NDS type integer for this channel.

This property is mapped to the Channel.type string.

classmethod parse_channel_name(name, strict=True)[source]¶

Decompose a channel name string into its components

Parameters:	name : str name to parse strict : bool, optional require exact matching of format, with no surrounding text, default True
Returns:	match : dict 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
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'}

classmethod query(name, use_kerberos=None, debug=False)[source]¶

Query the LIGO Channel Information System for the Channel matching the given name

Parameters:	name : str name of channel use_kerberos : bool, optional use an existing Kerberos ticket as the authentication credential, default behaviour will check for credentials and request username and password if none are found (None) debug : bool, optional print verbose HTTP connection status for debugging, default: False
Returns:	c : Channel a new Channel containing all of the attributes set from its entry in the CIS

classmethod query_nds2(name, host=None, port=None, connection=None, type=None)[source]¶

Query an NDS server for channel information

Parameters:	name : str name of requested channel 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 channel with metadata retrieved from NDS2 server
Raises:	ValueError if multiple channels are found for a given name

Notes

Warning

A host is required if an open connection is not given

safe¶

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

Type:	bool or None

sample_rate¶

Rate of samples (Hertz) for this channel.

Type:	Quantity

signal¶

Instrumental signal for this channel.

Type:	str

subsystem¶

Instrumental sub-system for this channel.

Type:	str

system¶

Instrumental system for this channel.

Type:	str

texname¶

Name of this channel in LaTeX printable format.

trend¶

Trend type for this channel.

Type:	str

type¶

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’

Type:	str

unit¶

Data unit for this channel.

Type:	Unit

url¶

CIS browser url for this channel.

Type:	str

class gwpy.detector.ChannelList[source]¶

Bases: list

A list of channels, with parsing utilities.

append()¶

L.append(object) – append object to end

count(value) → integer -- return number of occurrences of value¶

extend()¶

L.extend(iterable) – extend list by appending elements from the iterable

find(name)[source]¶

Find the Channel with a specific name in this ChannelList.

Parameters:	name : str name of the Channel to find
Returns:	index : int the position of the first Channel in this ChannelList whose name matches the search key.
Raises:	ValueError if no matching Channel is found.

classmethod from_names(*names)[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.

ifos¶

The set of interferometer prefixes used in this ChannelList.

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

insert()¶

L.insert(index, object) – insert object before index

pop([index]) → item -- remove and return item at index (default last).¶

Raises IndexError if list is empty or index is out of range.

classmethod query(name, use_kerberos=None, debug=False)[source]¶

Query the LIGO Channel Information System a ChannelList.

Parameters:	name : str name of channel, or part of it. use_kerberos : bool, optional use an existing Kerberos ticket as the authentication credential, default behaviour will check for credentials and request username and password if none are found (None) debug : bool, optional print verbose HTTP connection status for debugging, default: False
Returns:	channels : ChannelList a new list containing all Channels found.

classmethod query_nds2(names, host=None, port=None, connection=None, type=127, unique=False)[source]¶

Query an NDS server for channel information

Parameters:	name : str name of requested channel 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 unique : bool, optional require a unique query result for each name given, default False
Returns:	channellist : ChannelList list of Channels with metadata retrieved from NDS2 server
Raises:	ValueError if multiple channels are found for a given name and unique=True is given

Notes

Warning

A host is required if an open connection is not given

classmethod query_nds2_availability(*args, **kwargs)[source]¶

Query for when data are available for these channels in NDS2

Parameters:

channels : list list of Channel or str for which to search start : int GPS start time of search, or any acceptable input to to_gps() end : int GPS end time of search, or any acceptable input to to_gps() connection : nds2.connection, optional open connection to an NDS(2) server, if not given, one will be created based on host and port keywords host : str, optional name of NDS server host port : int, optional port number for NDS connection

Returns:

segdict : SegmentListDict dict of (name, SegmentList) pairs

classmethod read(source, *args, **kwargs)[source]¶

Read a ChannelList from a file

Parameters:	source : str, file either an open file object, or a file name path to read

Notes

The available built-in formats are:

Format	Read	Write	Auto-identify
ini	Yes	Yes	Yes
omega-scan	Yes	No	No

remove()¶

L.remove(value) – remove first occurrence of value. Raises ValueError if the value is not present.

reverse()¶

L.reverse() – reverse IN PLACE

sieve(name=None, sample_rate=None, sample_range=None, exact_match=False, **others)[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 return channels matching name exactly, default: False
Returns:	new : ChannelList a new ChannelList containing the matching channels

sort()¶

L.sort(cmp=None, key=None, reverse=False) – stable sort IN PLACE; cmp(x, y) -> -1, 0, 1

write(target, *args, **kwargs)[source]¶

Write a ChannelList to a file

Notes

The available built-in formats are:

Format	Read	Write	Auto-identify
ini	Yes	Yes	Yes
omega-scan	Yes	Yes	No