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, sample_rate=None, unit=None, frequency_range=None, safe=None, type=None, dtype=None, frametype=None, model=None, url=None)[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.

Attributes Summary

MATCH
dtype	Numeric type for data in this channel.
frametype	LDAS type description for frame files containing this channel.
frequency_range	Frequency range of interest (Hertz) for this channel
ifo	Interferometer prefix for this channel.
model	Name of the SIMULINK front-end model that defines this channel.
name	Name of this channel.
ndsname	Name of this channel as stored in the NDS database
ndstype	NDS type integer for this channel.
safe	Whether this channel is ‘safe’ to use as a noise witness
sample_rate	Rate of samples (Hertz) for this channel.
signal	Instrumental signal for this channel.
subsystem	Instrumental sub-system for this channel.
system	Instrumental system for this channel.
texname	Name of this channel in LaTeX printable format.
trend	Trend type for this channel.
type	DAQ data type for this channel.
unit	Data unit for this channel.
url	CIS browser url for this channel.

Methods Summary

copy()
find_frametype([gpstime, frametype_match, ...])	Find the containing frametype(s) for this Channel
from_nds2(nds2channel)	Generate a new channel using an existing nds2.channel object
parse_channel_name(name[, strict])	Decompose a channel name string into its components
query(name[, debug, timeout])	Query the LIGO Channel Information System for the Channel
query_nds2(*args, **kwargs)	Query an NDS server for channel information

Attributes Documentation

MATCH = <_sre.SRE_Pattern object>¶

dtype¶

Numeric type for data in this channel.

Type:	dtype

frametype¶

LDAS type description for frame files containing this channel.

frequency_range¶

Frequency range of interest (Hertz) for this channel

Type:	Quantity array

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.

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

Methods Documentation

copy()[source]¶

find_frametype(gpstime=None, frametype_match=None, host=None, port=None, return_all=False, exclude_tape=False)[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 exclude_tape : bool, default: False do not search frame files that appear to be on magnetic tape

Returns:

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

classmethod from_nds2(nds2channel)[source]¶

Generate a new channel using an existing nds2.channel object

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, debug=False, timeout=None)[source]¶

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

Parameters:	name : str name of channel debug : bool, optional print verbose HTTP connection status for debugging, default: False timeout : float, optional maximum time to wait for a response from the CIS
Returns:	Channel : a new Channel containing all of the attributes set from its entry in the CIS

classmethod query_nds2(*args, **kwargs)[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

class gwpy.detector.ChannelList[source]¶

Bases: list

A list of channels, with parsing utilities.

Attributes Summary

ifos	The set of interferometer prefixes used in this ChannelList.

Methods Summary

append	L.append(object) – append object to end
count(...)
extend	L.extend(iterable) – extend list by appending elements from the iterable
find(name)	Find the Channel with a specific name in this ChannelList.
from_names(*names)
index((value, [start, ...)	Raises ValueError if the value is not present.
insert	L.insert(index, object) – insert object before index
pop(...)	Raises IndexError if list is empty or index is out of range.
query(name[, debug, timeout])	Query the LIGO Channel Information System a ChannelList.
query_nds2(*args, **kwargs)	Query an NDS server for channel information
query_nds2_availability(*args, **kwargs)	Query for when data are available for these channels in NDS2
read(*args, **kwargs)	Read a ChannelList from a file
remove	L.remove(value) – remove first occurrence of value.
reverse	L.reverse() – reverse IN PLACE
sieve([name, sample_rate, sample_range, ...])	Find all Channels in this list matching the specified criteria.
sort	L.sort(cmp=None, key=None, reverse=False) – stable sort IN PLACE;
write(data, *args, **kwargs)	Write out data

Attributes Documentation

ifos¶

The set of interferometer prefixes used in this ChannelList.

Methods Documentation

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]¶

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, debug=False, timeout=None)[source]¶

Query the LIGO Channel Information System a ChannelList.

Parameters:	name : str name of channel, or part of it. debug : bool, optional print verbose HTTP connection status for debugging, default: False timeout : float, optional maximum time to wait for a response from the CIS
Returns:	`ChannelList` : a new list containing all Channels found.

classmethod query_nds2(*args, **kwargs)[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() host : str name of NDS server port : int, optional port number for NDS connection
Returns:	nested dict : a dict of (channel, dict) pairs where the nested dict is over (frametype, SegmentList) segment-availability pairs

classmethod read(*args, **kwargs)¶

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(data, *args, **kwargs)¶

Write out data

The arguments passed to this method depend on the format

The available built-in formats are:

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