#####################
Data-quality segments
#####################

.. currentmodule:: gwpy.segments

It is crucial to instrumental operation, and to analyses of data, that time segments denoting good or bad state of the instrument and its environment are recorded accurately.
To that end, the international collaboration operates using the GPS time standard (seconds since the GPS epoch of midnight on January 6th 1980), and records such times as semi-open GPS ``[start, stop)`` `segments <Segment>`.

GWpy imports a number of low-level classes for handling these segments provided by the :mod:`glue.segments` module.
All credits for their usefulness go to the authors of that package.
These basic objects are as follows:

.. autosummary::

   Segment
   SegmentList
   SegmentListDict

.. currentmodule:: gwpy.segments

While these objects are key to representing core data segments, they are usually applied to analyses of data as a `DataQualityFlag`.

============================
The :class:`DataQualityFlag`
============================

A `DataQualityFlag` is an annotated set of segments that indicate something about instrumental operation.
Each flag is defined by applying some algorithm on data and generating a :class:`SegmentList` that indicates some good or bad condition has been met during those times.
For example, the times during which the LIGO interferometers are operating under 'science-mode' conditions are recorded as the 'science' flag, which are used by data analysis groups to define periods of data over which to run their pipelines.
Conversely, in the last science run (S6, June 2009 - October 2010), high seismic noise around the observatory buildings was recorded in a data-quality flag used by analysis groups to veto periods of analysis due to sub-standard data.

Each `DataQualityFlag` has some key attributes:

.. autosummary::

   ~DataQualityFlag.name
   ~DataQualityFlag.active
   ~DataQualityFlag.valid

====================
The Segment Database
====================

The LIGO and Virgo instruments utilise hundreds of data-quality flags to record instrumental state on a daily basis.
These flags are stored in a joint segment database - a queryable database recording each flag, its valid and active segment lists, and all metadata associated with its generation.
The segment database is the primary access point for users to study data-quality flags and apply them in their analyses.

The `DataQualityFlag` object comes with a direct link to the segment database, through the :meth:`DataQualityFlag.query` classmethod:

.. automethod:: DataQualityFlag.query
   :noindex:

==============================
`DataQualityFlag` applications
==============================

The major application of data-quality flags is to record times during which the instrument was operating outside of its nominal condition.
These flags are typically generated by analysing auxiliary signals in the instrument that aren't sensitive to gravitational-wave amplitude, but do have a recorded noise coupling into the main gravitational-wave channel.

.. toctree::
   :maxdepth: 1

   thresholding

=====================
The `DataQualityDict`
=====================

Groups of `DataQualityFlags <DataQualityFlag>` can be collected into a `DataQualityDict`, a simple extension of the :class:`~collections.OrderedDict` with methods for operating on a group of flags in bulk.

The most immediate utility of this group class is a bulk query of the segment database, using the :meth:`DataQualityDict.query` `classmethod`.
This method is what is actually called by the :meth:`DataQualityFlag.query` `classmethod` anyway.

===============
Class reference
===============

This reference includes the following `class` entries:

.. autosummary::
   :nosignatures:

   DataQualityFlag
   DataQualityDict
   Segment
   SegmentList
   SegmentListDict

.. autoclass:: DataQualityFlag

.. autoclass:: DataQualityDict

.. autoclass:: Segment

.. autoclass:: SegmentList

.. autoclass:: SegmentListDict