Antenna position Correction pipeline

Astrohack provides an executable script for obtaining antenna position corrections, which is installed by pip somewhere in the PATH. This script has 5 main stages:

ASDM import to ms (if data set has not yet been imported to an MS).
A CASA pre-locit stage where visibilities are channel averaged and phase solutions are computed.
A locit stage where phase solutions are extracted from a gain table and then processed to obtained antenna position corrections.
An export stage where data products such as plots and reports are created.
The creation of a report grouping all the data products.

This pipeline has been written under the assumption that the user will be running it in CASA or in an environment that provides the casatasks, casaplotms and casatools modules. The instructions below assume that the pipeline is being run inside CASA.

Pipeline interface

The pipeline has been written with a simple command line interface that expects two mandatory arguments from the user, the name of the dataset to be processed (be it an MS or an ASDM) and a reference antenna for the calibration stage, several execution customization options are also available a simple help can be accessed with the -h flag:

CASA <1>: !baseline-reduction-pipeline -h

#####################################################################################################################################
###  Welcome to the AstroHACK baseline pipeline for the VLA                                                                       ###
#####################################################################################################################################

usage: baseline-reduction-pipeline [-h] [-r ROOT_NAME] [-f FRINGEFIT_SOURCE] [--scans_to_flag SCANS_TO_FLAG] [-i INTENT] [-s SPW]
                                   [-a ANTENNA] [-e ELEVATION_LIMIT] [-p {both,L,R}] [-c {simple,difference}] [-k]
                                   [-l DELAY_LIMITS] [-d DPI] [-o] [--starting-stage {calibration,locit,exports,report}]
                                   [--reimport-asdm] [-y]
                                   filename refant

CASA baseline pipeline

positional arguments:
  filename              Path to the input MS/ASDM file
  refant                Reference antenna for calibration

options:
  -h, --help            show this help message and exit
  -r ROOT_NAME, --root-name ROOT_NAME
                        Root name for the calibration tables, default is filename without extension
  -f FRINGEFIT_SOURCE, --fringefit_source FRINGEFIT_SOURCE
                        Fringe fit source, default is 0319+415
  --scans_to_flag SCANS_TO_FLAG
                        Comma separated list of scans to flag, default is None
  -i INTENT, --intent INTENT
                        Intent for pointing observations.
  -s SPW, --spw SPW     Select SPWs for locit processing, for a list use comma separated values with no spaces, e.g.: '0,1,2', default is all
  -a ANTENNA, --antenna ANTENNA
                        Select antennas for which to produce antenna position corrections, for a list use comma separated values with no spaces, e.g.: 'ea01,ea02', default is all
  -e ELEVATION_LIMIT, --elevation-limit ELEVATION_LIMIT
                        Lowest elevation of data for consideration in degrees, default is 10.0
  -p {both,L,R}, --polarization {both,L,R}
                        Which polarization hands to be used for locit processing, default is both
  -c {simple,difference}, --combination {simple,difference}
                        How to combine different spws for locit processing, default is simple
  -k, --fit_kterm       Fit antennas K term (i.e. Offset between azimuth and elevation axes)
  -l DELAY_LIMITS, --delay_limits DELAY_LIMITS
                        Delay limits for delay plots, values must be given between quotes("), default is "-0.1,0.1"
  -d DPI, --dpi DPI     DPI for png figures (default: 300)
  -o, --overwrite       Overwrite existing files (MSes, caltables, locit files, plots)
  --starting-stage {calibration,locit,exports,report}
                        Starting stage in which to start processing (default: calibration).
  --reimport-asdm       Forcefully re-import the asdm file is the ms already exists (default: False)
  -y, --assume-yes      Assume yes on proceed.

Pre-locit stage

With a reference antenna chosen it is now time to run the antenna position correction pipeline. The first step of the pipeline is to check whether the data is an ASDM or an MS and if it is an ASDM if it needs to be imported into an MS. With an MS in hands the pipeline proceeds to fetching some metadata from it and then prints a summary of what it has found and which parameters it will use for calibration and further data reduction, e.g.:

CASA <3>: !baseline-reduction-pipeline short_x.ms ea13 -f 2148+611

#####################################################################################################################################
###  Welcome to the AstroHACK baseline pipeline for the VLA                                                                       ###
#####################################################################################################################################

2026-07-20 17:44:09 INFO    msmetadata_cmpt.cc::open        Performing internal consistency checks on short_x.ms...

Baseline determination parameters:
    filename           => short_x.ms
    refant             => ea13
    root_name          => None
    fringefit_source   => 2148+611
    scans_to_flag      => []
    intent             => CALIBRATE_POINTING#ON_SOURCE
    spw                => all
    antenna            => all
    elevation_limit    => 10.0
    polarization       => both
    combination        => simple
    fit_kterm          => False
    delay_limits       => [-0.1, 0.1]
    dpi                => 300
    overwrite          => False
    starting_stage     => calibration
    reimport_asdm      => False
    assume_yes         => False
    is_asdm            => False
    msname             => short_x.ms
    pointing_only_ms   => short_x.pnt.ms
    freq_averaged_ms   => short_x.avg.ms
    fringefit_caltable => short_x.sbd
    phase_caltable     => short_x.pha.gcal
    antpos_caltable    => short_x.antpos
    locit_name         => short_x.locit.zarr
    position_name      => short_x.position.zarr
    exports_name       => short_x.exports
    report_name        => short_x-report.html
    n_chan             => 64


Proceed? <(Y)es/(N)o>:

The check before proceeding can be suppressed by adding the -y option to the call, e.g.:

CASA <4>: !baseline-reduction-pipeline short_x.ms ea13 -y

The code will then proceed through the pre-locit steps:

Split the data to contain only the pointing scans with split.
(Optional) Flag scans provided with the --scans-to-flag option, default is to do no flagging.
Perform a fringefit over all sources in the pointing only MS to obtain a delay estimate with each spectral window.
Apply the fringefit computed delays with applycal.
Average all channels in the now phase aligned spectral windows with split.
Obtain phase solutions for all sources using gaincal(calmode="p")
Apply the phase solutions to the channel averaged ms with applycal and then plot then with plotms for user inspection (they are now expected to be clustered around 0).

Locit stage

With the phase gain table obtained in the previous stage the pipeline now goes through the astrohack steps in the locit stage:

extract_locit: extract phase gains from the gain table and stored then in a convenient format for further processing.
locit: Process phases from all spectral windows either combined or through their differences to produce antenna position solutions.

In case of failures or there is a desire to re run the pipeline from a particular stage, the user can then use option --starting-stage. For more details on the antenna position corrections processing stages there is the more detailed locit tutorial.

Export & report stages

After the astrohack data files are created, the pipeline then proceeds to execute the exporting functions from the associated Python classes:

AstrohackLocitFile.plot_source_positions: Single plot showing the positions in the sky of the sources used for obtaining antenna position corrections.
AstrohackLocitFile.plot_array_configuration: Single plot displaying the array configuration at observation time.
AstrohackPositionFile.export_locit_fit_results: Produce a single table with all antenna position corrections.
AstrohackPositionFile.export_results_to_parminator: Produce a parminator file with proposed antenna position corrections to bea applied at the correlator.
AstrohackPositionFile.plot_position_corrections: Produce a single plot with arbitrarily scaled antenna position corrections over the plot of the array configuration to have a graphical representation of antenna corrections.
AstrohackPositionFile.plot_delays: Produce a plot per antenna showing the measured delays, the modeled delays and the residual delays.

After creating the astrohack plots the pipeline then proceeds to an extra stage:

Produce an antenna position correction calibration table using CASA’s gencal.
Apply antenna position corrections to the channel averaged MS using applycal.
Produce plots of the over time for the raw and baseline corrected data.

After the production of these export products the pipeline then creates a standalone HTML report with all of them that can then be stored or shared without the need to carry any extra data, an example of such a report can be seen here.