Skip to content

Apply to all targets

Jump to bottom
jradcliffe5 edited this page Jul 20, 2022 · 7 revisions

Apply to all targets (apply_to_all)

The apply_to_all step is designed for multi-phase centre VLBI observations only and is to cast the calibration from the previous steps to all of the other phase centres. This step will also apply a nominal primary beam correction to these data and produce an initial, naturally weighted image.

Parameters

    "apply_to_all":{  
        "target_path"       : "/Users/jackradcliffe/Documents/BD228L/target_files", #path to the fitsidi files of the phase centres
        "target_outpath"    : "/Users/jackradcliffe/Documents/BD228L/calibrated", #path to where the calibrated data should be stored
        "tar_output"        : true, #if true, tar the calibrated products (uses gzip compression)
        "tar_ms_only"       : true, #if true and "tar_output=true" only tar the measurement set (useful for inspecting images quickly)
        "mppc_parallel"     : false, #if true (+ and mpi enabled + job manager = bash) process multiple phase centres at ones
        "pbcor":{
            "run"           : true, #run primary beam correction
            "implementation": "uvcorr", #type of primary beam correction (see below for options)
            "vex_file"      : "", #vex file name+path (will override pointing_centre)
            "pointing_centre"  : ["10h01m22.8650000s","+2d19m28.333s"], #pointing centre of observations in CASA format
            "backup_caltables"  : true #add pbcor tables to the tar bundle of calibration tables
        },
        "image_target":{
            "run"           : true, #if true, image targets with natural weighting
            "imsize"        : [1024,1024] #image size
        },
        "hpc_options":{ 
            "partition"     :  "default",
            "walltime"      :  "default",
            "nodes"         :    -1,
            "cpus"          :    -1,
            "mpiprocs"      :    -1,
            "nodetype"      :  "default",
            "max_jobs"      : 24 #important for PBS/slurm runs. Determines how many concurrent jobs can run at once.
        }

Applying to all data sets

Parallelisation

Parallelisation is essential if you are to calibrate the many datasets that are produced with multiple phase centre correlations. The parallelisation is through two different methods depending on the job manager selected.

For the slurm and pbs (PBS Pro) job managers, each dataset is calibrated using an array job where the total number of jobs is the number of phase centres and the maximum jobs at once determined by the max_jobs parameter in the params file. It is generally recommended to calibrate with one core per dataset as monolithic CASA jobs are executed (and will be a waste of cores).

For the bash job manager, parallelisation is conducted through the casampi module. The mppc_parallel parameter determines how the parallelisation is conducted. If it is false, each measurement set is processed in turn, but a multi-measurement set is produced which speeds up the applying of calibration tables. This is generally better for a small number of phase centres or large individual datasets.

If it is true, casampi will calibrate multiple phase centres at once (depending on the number of cores available to mpi, e.g., mpirun -q -n 5 will calibrate 4 at once -- Nb: the other is reserved to control the CASA instance). This is generally better for large number of phase centres. Note that both parallelisation methods cannot be used together as problems with resource allocation has been found to occur.

Important should you decide to set mppc_parallel: true, you have to conduct the steps on the following page to make this work properly on your machine (otherwise the job will hang forever):

Enabling casampi using bash job manager

Primary beam correction

The primary beam corrections comprise of a a fairly complex bit of code, and the next two sections will help you decide which of the four different implementations to use or which of the two different ways of setting the pointing centres to use. The final sub-section shows you how to add a new primary beam model for telescopes that are not supported.

Implementations

The four different implementations are listed below in detail but the uvcorr method is most applicable to the majority of cases.

  1. Image plane correction ("implementation": "imcorr")

    The image plane correction will calculate a primary beam correction which will scale the image that is produced (and not the uv data). It will produce a .pbcor.image image. This is the least computationally intense algorithm. For homogeneous arrays, the output will be correct for all weightings, while for heterogeneous arrays, there may be residual amplitude errors and the correction will only be correct when using natural weighting (as the primary beam shape changes with the weighting scheme).

    When to use: For homogeneous arrays and/or large fields of view that are less than the primary beam HPBW. Only use for heterogeneous arrays if using natural weighting and close to the pointing centre.

  2. uv plane correction ("implementation": "uvcorr")

    The uv plane correction calculates a single amplitude primary beam corrections per antenna, per spectral windown, at the pointing centre only as a CASA gain table (ending in .pbcor). This sort of correction is computationally inexpensive but the fluxes are only correct at the pointing centre. The errors away from the pointing centre scale with distance and the derivative of the primary beam model (e.g., higher at the HPBW where the PB attenuation changes over a smaller angular distance).

    When to use: For any sort of array, and the images you create are a very small fraction of the primary beam area (so the beam doesn't change significantly over the image)

  3. Differential primary beam correction ("implementation":"diffuvcorr")

    The differential $uv$ correction is a mixture of 1. and 2.. A gain table, the same as described in 1., is produced and then a resultant image is made. This image then rescaled by the model divided my the singular uv correction at the phase centre. This ensures that the fluxes are correct across the image.

  4. a-term correction ("implementation":"aterm")

    The a-term correction is the most compuationally complex but the most accurate by far. This generates a direction-dependent diagonal gain calibration which is used to correct for the primary beam through a convolution while gridding the image. Errors via this method are from the resampling of the convolution and the accuracy of the primary beam model but are significantly less than the other methods.

    The issue with this method is that it requires the wsclean package to be installed (see https://wsclean.readthedocs.io) and the Image Domain Gridding libraries to be installed also (see https://wsclean.readthedocs.io/en/latest/image_domain_gridding.html).

    When to use: If you are generating a large image relative to the primary beam size and you have a heterogeneous array. This ensures that amplitude errors are reduced dramatically across the whole image.

Adding a new primary beam model

The VPIPE attempts to keep up-to-date information on the primary beam models used in most VLBI arrays. This is not comprehensive so you may have a telescope that is not supported (see Supported-telescopes-for-primary-beam-correction section for the current list) or the station code in your observation differs.

To add a telescope, open the primary_beams.json file located in the data folder of the pipeline. You will find entries that look like the following for the Effelsberg telescope:

    "EF":{
        "L":{
           "diameter":   76.0,
           "pb_model":   "G",
           "pb_freq" : 1.6e9,
           "pb_params": [76.0],
           "pb_squint": [0,0],
           "pb_source":""
        }
    },

Copy this and adjust in the various information. The station code should be the first indent (i.e., EF) and then the frequency band (i.e, L) on the second indent. The bands labels have the following tolerances (in GHz):

Band Frequency range (GHz)
L 1.00-2.00
S 2.15-2.35
C 3.90-7.90
X 8.00-8.80
Ku 12.0-15.4
K 21.6-24.1
Q 41.0-45.0

The parameters can be set as following:

  • "diameter" is the effective diameter of the telescope. It does not matter what this is set as as it just changes the metadata in the measurement set's ANTENNA table. May only be useful when CASA gets their in-house primary beam correction sorted
  • "pb_model" and "pb_params" determine the analytical function used to model the primary beam and the parameters for that model respectively. A summary of the models can be found in this document.
  • "pb_freq" is the central frequency where the primary beam model and parameters are correct. The model is then scaled as 1/frequency.
  • The pb_squint describes the beam squint which is the offset of the peak sensitivity / gain of the two orthogonal polarisations relative to the pointing centre of the telescope. This should be entered in units of arcmin in the Az-El frame with the polarisations in the following order: [L,R] for circular or [X,Y] for linear polarisations.
  • pb_source is an extra note to write the origin / reference for the beam model inserted into the pipeline.

Supported telescopes for primary beam correction

Telescope Array Frequency bands Station code(s) PB model status
Effelsberg EVN L, C EF, EB H
Lovell (Jodrell Bank 1) EVN L JB, JB1 S
Westerbork EVN L WB G
Onsala (85ft) EVN L O8, ON G
Tianma (65m) EVN L T6 G
Sardinia EVN L SR G
Zeluchunaya EVN L ZC G
Svetloe EVN L SV G
Torun EVN L TR G
Badary EVN L BD G
Sheshan EVN L SH G
Hartebeesoek L HH S, Sq
Noto EVN L NT G
Urumqi EVN L UR G
Medicina EVN L MC G
Irbene EVN L IR G
Robledo (70m) EVN L RO G
Cambridge (32m) e-MERLIN L CM G
Mark 2 (Jodrell Bank 2) e-MERLIN L JB2, MK2 G
Darnall e-MERLIN L DA G
Pickmere e-MERLIN L PI G
Knockin e-MERLIN L JN G
Defford e-MERLIN L DE G
Arecibo L AR S, Sq
Brewster VLBA L BR S, Sq
Fort Davis VLBA L FD S, Sq
Hancock VLBA L HN S, Sq
Kitt Peak VLBA L KP S, Sq
Mauna Kea VLBA L MK S, Sq
North Liberty VLBA L NL S, Sq
Owens Valley VLBA L OV S, Sq
Pie Town VLBA L PT S, Sq
Los Alamos VLBA L LA S, Sq
St. Croix VLBA L SC S, Sq
Green Bank (110m) VLBA L GB S

PB model status key: G = best guess, S = from scan, H = holographic scan, Sq = includes squint information.

Clone this wiki locally