# mstool — MeasurementSet utilities

`mstool` provides utilities for inspecting and manipulating MeasurementSets
directly via casacore TAQL: inspecting metadata, column arithmetic,
concatenating in time, and extracting an LST range.

## info — inspect a MeasurementSet

Prints a summary of the columns, time range, and frequency range of a
MeasurementSet.

### Usage

```
mstool info obs.MS
```

Example output:

```
MS: obs.MS

Columns:
  UVW                      double      71280 x (3,)
  FLAG                     bool        71280 x (3072,)
  DATA                     complex     71280 x (3072,)
  CORRECTED_DATA           complex     71280 x (3072,)
  ...

Time:
  start: 2023-12-08T06:12:00.000
  end:   2023-12-08T10:07:05.000
  duration: 3.92 h
  integration: 1.00 s

Frequency:
  range: 16.99 – 87.89 MHz
  channel width: 3.05 kHz
  total channels: 3072
```

### Reference

```{eval-rst}
.. click:: nenucal.tools.mstool:infocmd
   :prog: mstool info
   :nested: full
```

---

## add / sub — column arithmetic

`add` and `sub` perform element-wise arithmetic between two visibility
columns using casacore TAQL.  Both commands operate on complex data, so
they work correctly on visibility data regardless of polarisation shape.

### Usage

```
mstool add obs.MS CORRECTED_DATA MODEL_DATA
```

Adds in place — equivalent to the TAQL
`UPDATE obs.MS SET CORRECTED_DATA = CORRECTED_DATA + MODEL_DATA`.  With
`--out_col` the result goes to a separate column instead (created if needed):

```
mstool add obs.MS DATA MODEL_DATA --out_col CORRECTED_DATA
```

`sub` works identically with subtraction, e.g.
`mstool sub obs.MS CORRECTED_DATA MODEL_DATA --out_col RESIDUAL_DATA`.

### Notes

- When `--out_col` is omitted the first column (`COL1`) must already
  exist; the operation is performed in place.
- When `--out_col` is specified and the column does not yet exist, it is
  created with the same shape and data manager as `DATA`, then
  zero-initialised before the arithmetic is applied.

### Reference

```{eval-rst}
.. click:: nenucal.tools.mstool:addcmd
   :prog: mstool add
   :nested: full
```

```{eval-rst}
.. click:: nenucal.tools.mstool:subcmd
   :prog: mstool sub
   :nested: full
```

---

## concat — concatenate MeasurementSets in time

Concatenates two or more MeasurementSets along the time axis into a single
output MS using a casacore TAQL `select … giving … AS PLAIN` query.  The
input MSs are assumed to be from the same observation (same spectral window
and antenna layout) but observed at consecutive times.

### Usage

```
mstool concat /net/node101/.../SW03_T001.MS /net/node102/.../SW03_T002.MS out_concat.MS
```

The last positional argument is always the output path, so any number of inputs
(e.g. from a glob) can precede it:

```
mstool concat $(ls -d /data/SW03_T*.MS) out_concat.MS
```

### Notes

- At least two input MSs are required.
- The output directory is created automatically if it does not exist.
- The concatenation is a physical copy — the output MS is self-contained
  and does not reference the input MSs.

### Reference

```{eval-rst}
.. click:: nenucal.tools.mstool:concat
   :prog: mstool concat
   :nested: full
```

---

## extract_lst — extract an LST range

Extracts a Local Sidereal Time (LST) window from a set of MeasurementSets
and writes the selected rows to a new MS.  This is used to cut a fixed
nightly LST bin (e.g. 1–3 h) from each observation so that all nights cover
the same region of the sky.

The input MSs are first concatenated in memory using a TAQL virtual
concatenation, then a TIME selection is derived from the requested LST range
and applied.

### Algorithm

1. Concatenate all input MSs virtually (in memory, no disk copy).
2. Read the TIME of the first and last row to determine the observed LST range.
3. Linearly interpolate between those endpoints to find the TIME boundaries
   that correspond to the requested LST window.
4. Select rows whose TIME falls in that window and copy them to the output MS.

### Usage

```
mstool extract_lst obs.MS \
    --ms_out lst_2h.MS \
    --lst_start 2.0 --lst_end 4.0 \
    --longitude 6.57
```

Extracts the 2–4 h LST window from a night.  Multiple consecutive MSs (e.g.
time chunks on different nodes) can be passed at once:

```
mstool extract_lst /net/node101/...T001.MS /net/node102/...T002.MS \
    --ms_out lst_window.MS --lst_start 2.0 --lst_end 4.0 --longitude 6.57
```

`--data_column CORRECTED_DATA` selects which column is copied into the output
`DATA` column, and `--overwrite` replaces an existing output MS.

### Options

| Option | Default | Description |
|---|---|---|
| `--ms_out` | (required) | Output MS path |
| `--lst_start` | (required) | Start of LST window in hours |
| `--lst_end` | (required) | End of LST window in hours (exclusive) |
| `--longitude` | (required) | Observatory east longitude in degrees |
| `--data_column` | `DATA` | Column copied into the output `DATA` column |
| `--overwrite` | false | Remove and overwrite the output MS if it exists |
| `--min_fraction` | `0.8` | Minimum fraction of the requested LST duration that must be present; raises an error if below this threshold |

### Notes

- LST values are in hours (0–24).
- The LST-to-TIME mapping assumes a linear drift, which is accurate for
  continuous observations of a few hours but may introduce small errors for
  very long baselines or highly fragmented data.
- The NenuFAR longitude is `6.57°E`.
- `--min_fraction` guards against edge effects when the requested LST window
  extends slightly outside the observed range: a value of `0.8` means at
  least 80 % of the requested window must be covered.

### Reference

```{eval-rst}
.. click:: nenucal.tools.mstool:extract_lst
   :prog: mstool extract_lst
   :nested: full
```