Metadata-Version: 2.4
Name: sega
Version: 0.1.0
Summary: Segment Evaluation & Generation Application
Project-URL: Homepage, https://git.ligo.org/detchar/sgn-dq/sega
Project-URL: Documentation, https://detchar.docs.ligo.org/sgn-dq/sega
Project-URL: Repository, https://git.ligo.org/detchar/sgn-dq/sega.git
Project-URL: Issues, https://git.ligo.org/detchar/sgn-dq/sega/issues
Author-email: Derek Davis <derek.davis@ligo.org>, Olivia Godwin <olivia.godwin@ligo.org>, Zach Yarbrough <zach.yarbrough@ligo.org>
Maintainer-email: Derek Davis <derek.davis@ligo.org>, Olivia Godwin <olivia.godwin@ligo.org>, Zach Yarbrough <zach.yarbrough@ligo.org>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: igwn-auth-utils
Requires-Dist: pyparsing>=3.0
Requires-Dist: rich>=13.0
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: sgn-arrakis>=0.5
Requires-Dist: sgn-dq
Requires-Dist: sgn-gwframe>=0.4.1
Requires-Dist: sgn-ligo>=0.4
Requires-Dist: sgn-ts>=0.8
Requires-Dist: sgn>=0.8
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: markdown-callouts>=0.2; extra == 'dev'
Requires-Dist: markdown-exec>=0.5; extra == 'dev'
Requires-Dist: mkdocs-coverage>=0.2; extra == 'dev'
Requires-Dist: mkdocs-gen-files>=0.3; extra == 'dev'
Requires-Dist: mkdocs-literate-nav>=0.4; extra == 'dev'
Requires-Dist: mkdocs-material-igwn; extra == 'dev'
Requires-Dist: mkdocs-section-index>=0.3; extra == 'dev'
Requires-Dist: mkdocs>=1.3; extra == 'dev'
Requires-Dist: mkdocstrings[python]; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: mypy-extensions; extra == 'dev'
Requires-Dist: pip; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: requests-mock; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: toml>=0.10; extra == 'dev'
Requires-Dist: types-requests; extra == 'dev'
Provides-Extra: docs
Requires-Dist: markdown-callouts>=0.2; extra == 'docs'
Requires-Dist: markdown-exec>=0.5; extra == 'docs'
Requires-Dist: mkdocs-coverage>=0.2; extra == 'docs'
Requires-Dist: mkdocs-gen-files>=0.3; extra == 'docs'
Requires-Dist: mkdocs-literate-nav>=0.4; extra == 'docs'
Requires-Dist: mkdocs-material-igwn; extra == 'docs'
Requires-Dist: mkdocs-section-index>=0.3; extra == 'docs'
Requires-Dist: mkdocs>=1.3; extra == 'docs'
Requires-Dist: mkdocstrings[python]; extra == 'docs'
Requires-Dist: toml>=0.10; extra == 'docs'
Provides-Extra: lint
Requires-Dist: mypy; extra == 'lint'
Requires-Dist: mypy-extensions; extra == 'lint'
Requires-Dist: pip; extra == 'lint'
Requires-Dist: ruff; extra == 'lint'
Requires-Dist: types-requests; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: requests-mock; extra == 'test'
Description-Content-Type: text/markdown

<h1 align="center">sega</h1>

<p align="center">Segment Evaluation & Generation Application</p>

<p align="center">
  <a href="https://git.ligo.org/detchar/sgn-dq/sega/-/pipelines/latest">
    <img alt="ci" src="https://git.ligo.org/detchar/sgn-dq/sega/badges/main/pipeline.svg" />
  </a>
  <a href="https://git.ligo.org/detchar/sgn-dq/sega/-/pipelines/latest">
    <img alt="coverage" src="https://git.ligo.org/detchar/sgn-dq/sega/badges/main/coverage.svg" />
  </a>
  <a href="https://detchar.docs.ligo.org/sgn-dq/sega">
    <img alt="documentation" src="https://img.shields.io/badge/docs-mkdocs%20material-blue.svg?style=flat" />
  </a>
  <a href="https://pypi.org/project/sega/">
    <img alt="pypi version" src="https://img.shields.io/pypi/v/sega.svg" />
  </a>
</p>

---

Evaluate data quality conditions on detector channel data and produce IGWN XML
segment files or publish directly to DQSegDB. SEGA is built on the
[SGN](https://detchar.docs.ligo.org/sgn/) streaming pipeline framework and
driven by declarative YAML configuration.

## Resources

* [Documentation](https://detchar.docs.ligo.org/sgn-dq/sega)
* [Source Code](https://git.ligo.org/detchar/sgn-dq/sega)
* [Issue Tracker](https://git.ligo.org/detchar/sgn-dq/sega/-/issues)

## Installation

```
pip install sega
```

## Where to Start

* **[Tutorial](https://detchar.docs.ligo.org/sgn-dq/sega/tutorials/getting-started/)** -- New to SEGA? Write a config file and generate your first segments step by step.
* **[User Guide](https://detchar.docs.ligo.org/sgn-dq/sega/user/)** -- Configuration, condition types, data sources, output modes, and the CLI.
* **[API Reference](https://detchar.docs.ligo.org/sgn-dq/sega/reference/)** -- API documentation.

## Features

* Declarative YAML configuration with includes, defaults, and bulk expansion
* Per-sample threshold, range, and bitwise condition checks
* Aggregate statistics (mean, RMS) with trend detection
* Boolean condition logic with arbitrary nesting (`all_of`, `any_of`, `not`)
* Infix expression syntax for complex boolean conditions (`a & !b | c`)
* Multiple data sources: gravitational wave frames, Arrakis, or synthetic data
* Output to IGWN XML segment files or DQSegDB
* Dry-run mode for config validation

## Quickstart

### Write a configuration file

Create a file called `config.yaml`:

``` yaml
meta:
  ifo: H1
  subsystem: DQ

conditions:
  calibrated:
    operator: bits_set
    channel: H1:GDS-CALIB_STATE_VECTOR
    bits: [0, 6]

  low_noise:
    operator: below
    channel: H1:PEM-CS_ACC_BEAMTUBE_X_DQ
    threshold: 500.0

  science_ready:
    operator: boolean
    expr: "calibrated & low_noise"

segments:
  H1:DQ-SCIENCE_READY:
    condition: science_ready
    version: 1
    limit: 16
    comment: "Calibrated and low noise"
```

### Run from frame files

``` bash
sega --config config.yaml --source frames \
     --frames /path/to/H-H1_R-*.gwf \
     --start 1187000000 --end 1187001000
```

This evaluates the conditions over the specified time range and writes an XML
segment file to the current directory.

### Validate a config without running

``` bash
sega --config config.yaml --source fake --dry-run
```

The `--dry-run` flag parses and validates the configuration, printing a summary
table of conditions and output segments. Use `-v` to include the full segment
listing.

### Stream from Arrakis

``` bash
sega --config config.yaml --source arrakis
```

Without `--start` and `--end`, SEGA streams live data continuously. Press
`Ctrl+C` to stop.

### Publish to DQSegDB

``` bash
sega --config config.yaml --source arrakis \
     --output-mode dqsegdb \
     --segment-server https://segments.ligo.org
```

### Boolean expressions

Boolean conditions support infix notation with `&` (AND), `|` (OR), and `!`
(NOT), with standard precedence:

``` yaml
conditions:
  calibrated:
    operator: bits_set
    channel: H1:GDS-CALIB_STATE_VECTOR
    bits: [0, 6]

  injecting:
    operator: bits_set
    channel: H1:GDS-CALIB_STATE_VECTOR
    bits: [5]

  low_noise:
    operator: below
    channel: H1:PEM-CS_ACC_BEAMTUBE_X_DQ
    threshold: 500.0

  analysis_ready:
    operator: boolean
    expr: "calibrated & !injecting & low_noise"
```

This is equivalent to the explicit form:

``` yaml
  analysis_ready:
    operator: boolean
    all_of:
      - calibrated
      - not: injecting
      - low_noise
```
