mwalib Concepts

Owned by Greg Sleap
Aug 21, 2024
3 min read

MetafitsContext / CorrelatorContext / VoltageContext

The three main context structs are the main interface for mwalib. Use the appropriate one depending on what you want to do.

  • If you want to work with a metafits file only, then use MetafitsContext. Call it by providing the path to the metafits file and also supply the MWAVersion (see MWAVersion for details).

  • If you want to work with visibilities, then use CorrelatorContext. Call it by providing the path to the metafits file and any gpubox files.

  • If you want to work with voltages, then use VoltageContext. Call it by providing the path to the metafits file and any voltage data files.

MWAVersion

MWAVersion is an enum used to identify or command mwalib how to interpret the metadata for an observation. CorrelatorContext and VoltageContexts don't need this supplied as they derive it from the data files provided by the user. However when using a MetafitsContext without supplying data files, you will need to provide the MWAVersion. The valid values are:

  • CorrOldLegacy = 1

    • MWA correlator (v1.0), having data files without any batch numbers.

  • CorrLegacy = 2

    • MWA correlator (v1.0), having data files with "gpubox" and batch numbers in their names.

  • CorrMWAXv2 = 3

    • MWAX correlator (v2.0)

  • VCSLegacyRecombined = 4

    • Legacy VCS Recombined, having .dat extension.

  • VCSMWAXv2 = 5

    • MWAX VCS, having .sub extension.

Timesteps and Coarse Channels

mwalib will attempt, based on the metafits and any data files provided, try to determine a sensible interpretation of what timesteps and coarse channels exist for the observation.

Metafits Timesteps and Coarse Channels

  • MetafitsContext timesteps and coarse channels are the expected / planned timesteps and coarse channels as specified in the metafits file.

  • Timesteps are contiguous from the start of the observation to the start + duration.

  • Coarse channels may not be contiguous (the channel selection is for the PI of the observation to decide and may be a "picket fence" channel selection containing gaps or groups of contiguous channels).

CorrelatorContext and VoltageContext Timesteps and Coarse Channels

  • Timesteps and Coarse channels are identified from the data files provided and then a superset is generated by merging in the MetafitsContext Timesteps and Coarse Channels. E.g. if a MetafitsContext had the following timestep timestamps: [0,2,4,6,8], and the provided data files had [2,4,6,8,10]; then the Correlator/Voltage Context would have [0,2,4,6,8,10], a superset of the metafits and data files.

Provided Timesteps and Coarse Channels

  • Since MWA data files are split by channel and by time, and the caller can supply any combination of times and channels, mwalib exposes simple arrays of provided timesteps and coarse channels.

  • 'provided' in this instance refers to any timestep or coarse channel which is present in at least 1 data file provided. This does not mean the provided coarse channel has data for all timesteps, but at least one/some timesteps. And same goes from timesteps- a provided timestep may not necessarily have data provided for all coarse channels, but certainly some/one.

Common Timesteps and Coarse Channels

  • As mwalib analyses the data files, it will determine the subset of timesteps and coarse channels that are 'common'.

  • 'common' timesteps in this sense means: timesteps that are common to the all of provided coarse channels and are contiguous.

  • 'common' coarse channels in this sense means the channels common to the common timesteps. These don't need to be contiguous as it may be a "picket fence" selection of channels.

Common Good Timesteps and Coarse Channels

  • "common good" works exactly the same way as "common" except it excludes any timesteps prior to the quacktime (derived from the metafits, it specifies how many seconds the telescope data is not reliable due to receiver and beamformers changing state- we generally want to skip those seconds).

Baselines

  • A baseline is the distance between any two antennas. However, raw MWA data also contains auto-correlation data, and so the number of "baselines" presented in the data is calculated as (n * (n+1))/2 (where n is the number of antennas/tiles).