# Command line — aostats

`aostats` groups four commands for inspecting AOQuality statistics:

```
aostats [plot | plot-grid | find-bad-obs | find-bad-stations] --help
```

Every command accepts paths that the readers understand — a Measurement Set, a
directory, or a `.qs` file.

## plot — single-MS diagnostic plots

```
aostats plot obs.MS SNR -o stat_snr
```

Produces time–frequency, baseline–frequency, and frequency-summary plots for one
observation.

## plot-grid — multi-observation grids

Compares a statistic across many observations at once, producing three PNGs:
frequency × observation, antenna × observation, and LST × observation.

```
aostats plot-grid obs_20231208/ obs_20231210/ obs_20231212/ SNR --out-dir plots/ --name dec2023
```

One row per observation; labels default to the date inferred from each path
(override with `--label`).

## find-bad-obs — flag bad MS time chunks

Detects anomalous time chunks across a set of MS files by fitting a robust LST
trend to the chosen statistic and sigma-clipping the residuals — useful for
spotting bad scans before stacking.

```
aostats find-bad-obs ms_list.txt SNR --out-dir qa/ --name night1
```

The input is one or more text files listing MS paths (one per line). It writes
the flagged MS list, a per-MS score table, and raw/residual diagnostic plots.

## find-bad-stations — detect bad antennas per observation

Loads one combined `.qs` file per observation, computes per-antenna statistics,
and sigma-clips across antennas within each observation to flag outliers. The
JSON output is ready for `nenudata bad-stations import`.

```
aostats find-bad-stations quality_l2_cal/20231208_CYGA/combined.qs SNR -o bad_stations_cal.json
```

When a path's basename starts with `combined`, the observation label is inferred
from the parent directory (e.g. `20231208_CYGA`). It works equally on calibrator
or target QS files.

## Reference

```{eval-rst}
.. click:: aoquality.tools.aostats:main
   :prog: aostats
   :nested: full
```