hifa_antpos

hifa_antpos(vis: list[str] | None = None, caltable: list[str] | None = None, hm_antpos: Literal['online', 'manual', 'file'] | None = None, antenna: str | None = None, offsets: list[float] | None = None, antposfile: str | None = None, threshold: float | None = None, snr: float | None = None, search: Literal['both_latest', 'both_closest'] | None = None) → ResultsList[Results][source]

Derive and apply antenna position corrections for a list of MeasurementSets.

The hifa_antpos task corrects antenna positions recorded in the ASDMs using updated calibration information obtained after the observation. Corrections can be input by hand, read from a file on disk, or by querying an ALMA database service.

The antposfile parameter serves a dual purpose, depending on which mode is set.

For hm_antpos='file', antposfile defines the antenna positions file in 'csv' format containing 6 comma-delimited columns as shown below. This file should not include blank lines, including after the end of the last entry. This parameter is required for hm_antpos='file'.

Example of contents for a .csv file:

ms, antenna, xoffset, yoffset, zoffset, comment
uid___A002_X30a93d_X43e.ms, DV11, 0.000, 0.010, 0.000, 'No comment'
uid___A002_X30a93d_X43e.dup.ms, DV11, 0.000, -0.010, 0.000, 'No comment'

The offset values in this file are in meters.

For hm_antpos='online', antposfile defines the base outfile name used by the CASA tasks getantposalma and gencal with the MS basename prepended to it. The file must be in JSON format. If no value is set, it will default to antennapos.json.

The corrections are used to generate a calibration table which is recorded in the pipeline context and applied to the raw visibility data, on the fly to generate other calibration tables, or permanently to generate calibrated visibilities for imaging.

The WebLog shows the corrections in two tables: one sorted by antenna name and one sorted by the vector total correction. Values larger than the threshold (default: 1.0 wavelength) are highlighted in bold.

Parameters:

  • vis --

    List of input MeasurementSets. Defaults to those specified in the pipeline context.

    Example: ['ngc5921.ms']

  • caltable --

    List of output calibration table names. Defaults to the standard pipeline naming convention.

    Example: ['ngc5921.gcal']

  • hm_antpos --

    • 'online' : Query ALMA database through CASA task getantposalma or reuse pre-existing queried/downloaded JSON files. Files follow the naming pattern {eb_name}.{antposfile}. For multi-MS pipeline runs, the MS basename is appended to the filename (e.g., uid___A002_X123_X4567.antennapos.json).

    • 'manual' : Use user-provided corrections.

    • 'file' : Load corrections from a single old-style CSV antenna position file.

    Example: 'manual'

  • antenna --

    A comma-separated string of antennas whose positions are to be corrected (if hm_antpos is 'manual' or 'online').

    Example: 'DV05,DV07'

  • offsets --

    A flat list of floating-point offsets (X, Y, Z) for all specified antennas. The length of the list must be three times the number of antennas.

    Example (for two antennas): [0.01, 0.02, 0.03, 0.03, 0.02, 0.01]

  • antposfile --

    Path to a csv file containing antenna position offsets for hm_antpos='file' (required) or the name

    of the outfile created by getantposalma for hm_antpos='online'. In order to work with multi-MS pipeline runs, the MS basename will be appended to the file name when using hm_antpos='online' (i.e. 'uid___A002_X123_X4567.antennapos.json').

    Default: 'antennapos.json'

  • threshold --

    Threshold value (in wavelengths) above which antenna position offsets are highlighted in the weblog. Defaults to 1.0.

    Example: 1.0

  • snr --

    A float value describing the signal-to-noise threshold used by the getantposalma task. Antennas with snr below the threshold will not be retrieved. Only used with hm_antpos='online'. Defaults to 'default'.

    Example: 5.0

  • search --

    Search algorithm used by the getantposalma task. Supports 'both_latest', 'both_closest', and 'auto'. Only used with hm_antpos='online'. Defaults to 'auto'.

    Example: 'both_closest'

Notes

QA = 1.0 if no antenna position corrections were needed. QA = 0.9 if one or more antenna positions were corrected.

Returns:

The results object for the pipeline task is returned.

Examples

1. Correct the position of antenna 'DV05' for all the visibility files in a single pipeline run:

>>> hifa_antpos(antenna='DV05', offsets=[0.01, 0.02, 0.03])

2. Correct the position of antennas for all the visibility files in a single pipeline run using antenna positions files on disk. These files are assumed to conform to a default naming scheme if antposfile is unspecified by the user:

>>> hifa_antpos(hm_antpos='file', antposfile='myantposfile.csv')

3. Correct the position of antennas for all the visibility files in a single pipeline run using antenna positions retrieved from DB, limiting the selection to antennas with S/N of 5.0 or more and using the 'both_closest' search algorithm. A JSON file is returned and fed into the gencal task to apply corrections.

>>> hifa_antpos(hm_antpos='online', snr=5.0, search='both_closest')