The `Channel`¶

>>> from gwpy.detector import 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:

`name`	Name of this channel.
`sample_rate`	Rate of samples (Hertz) for this channel.
`unit`	Data unit for this channel.
`dtype`	Numeric type for data in this channel.
`url`	CIS browser url for this channel.
`model`	Name of the SIMULINK front-end model that defines this channel.

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:

`Channel`	Representation of a laser-interferometer data channel.
`ChannelList`	A `list` of `channels`, with parsing utilities.

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(self)[source]¶: Returns a copy of this channel

property dtype¶

Numeric type for data in this channel.

Type: dtype

find_frametype(self, 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

property frametype¶: LDAS type description for frame files containing this channel.

property 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

property ifo¶

Interferometer prefix for this channel.

Type: str

property model¶

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

Type: str

property name¶

Name of this channel.

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

Type: str

property ndsname¶: Name of this channel as stored in the NDS database

property 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

property 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

property sample_rate¶

Rate of samples (Hertz) for this channel.

Type: Quantity

property signal¶

Instrumental signal for this channel.

Type: str

property subsystem¶

Instrumental sub-system for this channel.

Type: str

property system¶

Instrumental system for this channel.

Type: str

property texname¶: Name of this channel in LaTeX printable format.

property trend¶

Trend type for this channel.

Type: str

property 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

property unit¶

Data unit for this channel.

Type: Unit

property url¶

CIS browser url for this channel.

Type: str

class gwpy.detector.ChannelList[source]¶

Bases: list

A list of channels, with parsing utilities.

append(self, object, /)¶: Append object to the end of the list.

clear(self, /)¶: Remove all items from list.

copy(self, /)¶: Return a shallow copy of the list.

count(self, value, /)¶: Return number of occurrences of value.

extend(self, iterable, /)¶: Extend list by appending elements from the iterable.

find(self, 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.

property ifos¶: The set of interferometer prefixes used in this ChannelList.

index(self, value, start=0, stop=9223372036854775807, /)¶

Return first index of value.

Raises ValueError if the value is not present.

insert(self, index, object, /)¶: Insert object before index.

pop(self, index=-1, /)¶

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(channels, start, end, ctype=126, connection=None, host=None, port=None)[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(self, value, /)¶

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse(self, /)¶: Reverse IN PLACE.

sieve(self, 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(self, /, *, key=None, reverse=False)¶: Stable sort IN PLACE.

write(self, 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

The Channel¶

What is a ‘channel’?¶

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

The ChannelList¶

Class reference¶

The `Channel`¶

The `ChannelList`¶