# Usage

The Python API exposes three reader classes, one per AOQuality table type:

| Class | Table | Primary axes |
|---|---|---|
| {class}`~aoquality.BaselineStat` | baseline (cross-correlation) | antenna pair |
| {class}`~aoquality.FrequencyStat` | frequency | frequency |
| {class}`~aoquality.TimeStat` | time | time × frequency |

Each can read a single Measurement Set, or combine several with `from_ms_list`.

## Reading a single Measurement Set

```python
import aoquality

bl = aoquality.BaselineStat('obs.MS')

# Per-antenna summary (cross-baselines only, autocorrelations excluded)
ant_names, ant_stats = bl.get_antenna_stat('SNR')
# ant_names: (n_ant,)   ant_stats: (n_ant, n_pol)
```

Any statistic name from {data}`aoquality.available_stats` can be requested —
`'SNR'`, `'RFIPercentage'`, `'Std'`, `'Mean'`, … Derived statistics (`Mean`,
`Std`, `SNR`, `RFIPercentage`, …) are computed on the fly from the raw table
columns.

## Combining many Measurement Sets

`get_combined_stat` reduces over the frequency axis, which makes it the natural
entry point when several MS (or a `combined.qs`) have been gathered, e.g. a whole
night:

```python
ms_list = ['SW03_T000.MS', 'SW03_T001.MS', 'SW03_T002.MS']

fs = aoquality.FrequencyStat.from_ms_list(ms_list)
freqs, stat = fs.get_combined_stat('RFIPercentage')   # (n_freq,), (n_freq, n_pol)

ts = aoquality.TimeStat.from_ms_list(ms_list)
time_mjd, freqs, stat = ts.get_combined_stat('SNR')   # (n_time,), (n_freq,), (n_freq, n_time, n_pol)
```

## Loading all three at once

{class}`~aoquality.AOQuality` reads the baseline, frequency, and time tables
together:

```python
aoq = aoquality.AOQuality.from_ms_list(ms_list)
aoq.baseline.get_antenna_stat('SNR')
aoq.frequency.get_combined_stat('RFIPercentage')
aoq.time.get_combined_stat('SNR')
```

## Quick plots

Each reader has plotting helpers that return a Matplotlib figure:

```python
bl.plot_antennae_stats('SNR')             # per-antenna bar chart
bl.plot_baseline_length_stats('SNR')      # statistic vs baseline length
fs.plot_freq_stats('RFIPercentage')       # statistic vs frequency
ts.plot_time_stats('SNR')                 # time (or time–frequency) image
```

For batch plotting and outlier detection across many observations, use the
[`aostats`](aostats.md) command-line tool.

## Backward-compatible aliases

The older `AOQualityBaselineStat`, `AOQualityFrequencyStat`, and
`AOQualityTimeStat` names remain importable and behave identically to the new
classes.