Parset Options

This page details available parset options. However, invoking gocubical -h should be preferred as it will always be up-to-date. The following is broken up into the various sections of the parset.

Note

These parset options can be specified via command line. For inclusion in a .parset file, omit the leading --section- component and place the remainder in the appropriate section.

[data]

Options pertaining to data selection and chunking strategy.

--data-ms=string

Name/path of input measurement set. Mandatory.

--data-column=string

Name of measurement set column from which to read for input data (uncalibrated visibilities). Default: ‘DATA’.

--data-time-chunk=string

Data will be cut up into blocks containing this many timeslots. This limits the amount of data processed at once. Smaller chunks allow for a smaller RAM footprint and greater parallelism, but this sets an upper limit on the solution intervals that may be employed. Specify as an integer number of timeslots, or a value with a unit (e.g. ‘300s’). 0 means use full time axis. Default: 32.

--data-freq-chunk=string

Data will be cut up into blocks containing this many channels. This limits the amount of data processed at once. Smaller chunks allow for a smaller RAM footprint and greater parallelism, but this sets an upper limit on the solution intervals that may be employed. Specify as an integer number of channels, or a value with a unit (e.g. ‘128MHz’). 0 means use full frequency axis. Default: 32.

--data-chunk-by=string

If set, then time chunks will be broken up whenever the value in the named column(s) jumps by --data-chunk-by-jump. Multiple column names may be given, separated by commas. Set to None to disable. Default: SCAN_NUMBER.

--data-chunk-by-jump=int

The jump size used in conjunction with --data-chunk-by. If 0, then any change in value is a jump. If n, then the change must be >n.

--data-rebin-time=string

Rebin data in time on the fly. Specify as a number of timeslots to average together, or a value with a unit (e.g. ‘5s’). Default: 1

--data-rebin-freq=string

Rebin data in frequency on the fly. Specify as a number of channels to average together, or a value with a unit (e.g. ‘4MHz’). Default: 1

--data-single-chunk=string

Each data chunk is assigned a unique identifier, e.g. ‘D0T0F0’. If set, processes just one chunk of data matching the identifier. Primarily a debugging option. No default.

[sel]

Options pertaining to data selection.

--sel-field=int

FIELD_ID to read from the MS. Default: 0.

--sel-ddid=multi

DATA_DESC_IDs to read from the MS. Can be specified as e.g. “5”, “5,6,7”, “5~7” (inclusive range), “5:8” (exclusive range), “5:” (from 5 to last). Default reads all.

--sel-taql=string

Additional TaQL selection string. Combined with other selection options. No default.

--sel-chan=multi

Channels to read (within each DDID). Can be specified as e.g. “5”, “10~20” (10 to 20 inclusive), “10:21” (same), “10:” (from 10 to end), “:10:2” (0 to 9 inclusive, stepped by 2), “~9:2” (same). Default reads all.

--sel-diag=bool

Use diagonal (i.e. parallel hand) correlations only. Off-diagonals will be null in the outputs. See also –JONES-diag-only.

[model]

Options related to model selection and prediction.

--model-list=multi

Predict model visibilities from MS column/s and LSM/s (using Montblanc). The simplest usage is to specify a column, e.g. MODEL_DATA, or a Tigger LSM, e.g. skymodel.lsm.html, or, as a special case, 1 simply uses unity visibilities. (The LSM option is only available if Montblanc is installed). Use @TAG, e.g. skymodel.lsm.html@dE to group sources in the LSM by direction, according to the specified tag. You can also specify models for different directions by means of a colon. For example, MODEL_DATA_1:MODEL_DATA_2 defines two directions, while MODEL_DATA:skymodel.lsm.html@dE defines a direction modelled by the MODEL_DATA column, and other directions as defined by the LSM. By contrast, the plus sign adds model visibilities together without splitting them into directions, e.g. MODEL_DATA_1+MODEL_DATA_2:skymodel.lsm.html@dE will define one direction modelled by a sum of columns, and other directions as defined by the LSM. Finally, a comma separates model sets. Each model set defines a separate minimization problem, weighted differently (in which case the –weight-column option must specify the same number of comma-separated weight sets). The priority of the separators is as follows: first, commas split up model sets. Within each set, colons split up directions. Finally, within each direction, plus signs split up its additive components. This can be quite a complex option, so check the log to make sure it is being interpreted correctly. No default.

--model-ddes=keyword

Enables direction-dependent models. If auto, this is determined by --sol-jones and --model-list, otherwise, enable/disable explicitly. Keywords: never, auto, always. Default: auto.

--model-beam-pattern=string

Apply beams from specified .fits files eg. “beam_$(corr)_$(reim).fits” or “beam_$(CORR)_$(REIM).fits”. No default.

--model-beam-l-axis=keyword

Specify which axis in the .fits file is associated with the l axis. Keywords: X, Y, -X, -Y. No default.

--model-beam-m-axis=keyword

Specify which axis in the .fits file is associated with the m axis. Keywords: X, Y, -X, -Y. No default.

--model-feed-rotate=multi

Apply a feed angle rotation to the model visibilities. Use ‘auto’ to read angles from FEED subtable, or give an explicit value in degrees. Default: auto.

--model-pa-rotate=bool

Apply parallactic angle rotation to model visibilities. Enable this for alt-az mounts, unless your model visibilities are already rotated. Default: True.

[weight]

Options related to weights.

--weight-column=string

Column/s to read weights from. Weights are applied by default. Specify an empty string or None to disable. Default: WEIGHT_SPECTRUM.

--weight-fill-offdiag=bool

Fill off-diagonal weights from geometric mean of diagonal weights. Use this if you have missing off-diagonal weights for whatever reason. Default: False.

[montblanc]

Options which will be used during model prediction (using Montblanc.)

--montblanc-device-type=keyword

Use CPU or GPU for simulation. Keywords: CPU, GPU. Default: CPU.

--montblanc-dtype=keyword

Precision for simulation. Keywords: float, double. Default: float.

--montblanc-feed-type=keyword

Simulate using linear or circular feeds. Keywords: linear, circular. Default: linear.

--montblanc-mem-budget=int

Memory budget in MB for simulation. Default: 1024.

--montblanc-verbosity=keyword

Verbosity level of Montblanc’s console output. Keywords: DEBUG, INFO, WARNING, ERROR. Default: WARNING.

--montblanc-threads=int

Number of OMP threads to run for Montblanc. Note that –dist-pin-io overrides this, if set. If 0, uses Montblanc’s insternal default (all). Default: 0.

[degridding]

Options for the degridder. Only in use when predicting from DicoModels using DDFacet.

--degridding-OverS=int

Oversampling factor. Default: 11.

--degridding-Support=int

CF support size. Default: 7.

--degridding-Nw=int

Number of w-planes. Default: 100.

--degridding-wmax=float

Maximum w coordinate. Visibilities with larger w will not be gridded. If 0, no maximum is imposed. Default: 0.

--degridding-Padding=float

Facet padding factor. Default: 1.7.

--degridding-NDegridBand=int

Number of image bands for degridding. 0 means degrid each channel. Default: 16.

--degridding-MaxFacetSize=float

Maximum facet size in degrees. Default: 0.25.

--degridding-MinNFacetPerAxis=int

Minimum number of facets per direction. Default: 1.

--degriding-NProcess=int

Number of subprocesses to use in degridding-based predict. Default: 8.

[flags]

Options controlling how flags are applied and written to.

--flags-apply=string

Which flagsets will be applied prior to calibration. Use “-FLAGSET” to apply everything except the named flagset (“-cubical” is useful, to ignore the flags of a previous CubiCal run). Default: -cubical.

--flags-auto-init=string

Insert BITFLAG column if it is missing, and initialize a named flagset from FLAG and FLAG_ROW. Default: legacy.

--flags-save=string

Save flags to named flagset in BITFLAG. If none or 0, will not save. Default: cubical.

--flags-save-legacy=keyword

Controls whether output flags are written to FLAG/FLAG_ROW. Is set to ‘auto’, then follows the –flag-save option. Default: auto

--flags-reinit-bitflags=bool

If true, reninitializes BITFLAG column from scratch. Useful if you ended up with a botched one, but be careful what the state of the FLAG/FLAG_ROW column is when you use this option. Default: 0.

--flags-warn-thr=float

If more than this fraction of data is flagged by the solver, issues gentle warnings. Default: 0.3.

--flags-see-no-evil=bool

Proceed even if flag columns appear to be botched or damaged. Default: 0.

[madmax]

“Mad Max” flags visibilities on-the-fly inside the solution loop, by using a MAD filter. This computes the median absolute residual (i.e. median absolute deviation from zero), and flags visibilities exceeding the thresholds set below.

--madmax-enable=bool

Enable Mad Max flagging. Default: 0

--madmax-estimate=keyword

MAD estimation mode. Use ‘corr’ for a separate estimate per each baseline and correlation. Otherwise, a single estimate per baseline is computed using ‘all’ correlations, or only the ‘diag’ or ‘offdiag’ correlations. Default: ‘corr’

--madmax-diag=bool

Flag on on-diagonal (parallel-hand) residuals. Default: 1.

--madmax-offdiag=bool

Flag on off-diagonal (cross-hand) residuals. Default: 1

--madmax-threshold=list

Threshold for MAD flagging per baseline (specified in sigmas). Residuals exceeding S*MAD/1.428 (where S is the given threshold) will be flagged. MAD is computed per baseline. This can be specified as a list e.g. N1,N2,N3,… The first value is used to flag residuals before a solution starts (use 0 to disable), the next value is used when the residuals are first recomputed during the solution several iteratins later (see -chi-int), etc. A final pass may be done at the end of the solution. The last value in the list is reused if necessary. Using a list with gradually decreasing values may be sensible. Default: 0,10.

--madmax-global-threshold=list

Threshold for global MMAD flagging. MMAD is computed as the median of the per-baseline MADs. Residuals exceeding S*MMAD/1.428 (where S is the given threshold) will be flagged.Can be specified as a list, with the same semantics as –madmax-threshold. Default: 0,12.

--madmax-plot=keyword

Enable plots for Mad Max flagging. Use ‘show’ to show figures interactively, or ‘1’ to save plots to files instead. Plots will show the worst flagged baseline, and a median flagged baseline, provided the fraction of flagged visibilities is above some threshold. Default: 0

--madmax-plot-frac-above=float

Threshold (in terms of fraction of visibilities flagged) above which Mad Max plots will be generated. Default: 0.01.

--madmax-plot-bl=str

Plot given baseline regardless (multiple baseline IDs may be separated by commas), No default.

--madmax-flag-ant=bool

Flag antennas with excessive residuals, based on MAD criterion. Note that currently –madmax-plot must be enabled for this to work. Default: False.

--madmax-flag-ant-thr=float

Threshold (in sigmas) used to flag bad antennas. Default: 5.

[postmortem]

Postmortem flagging is done on things like chi-square statistics after a solutionis finished.

--postmortem-enable=bool

If True, will do an extra round of flagging at the end (post-solution) based on solution statistics, as per the following options. Default: 0.

--postmortem-tf-chisq-median=float

Intervals with chi-squared values larger than X times the median chi-square value will be flagged. Default: 1.2.

--postmortem-tf-np-median=float

Intervals with a number of valid point less than X times the median number of valid points will be flagged. Default: 0.5.

--postmortem-time-density=float

If more than the given fraction of data in a timeslot is flagged, flag entire timeslot. Default: 0.5.

--postmortem-chan-density=float

If more than the given fraction of data in a timeslot is flagged, flag entire channel. Default: 0.5.

--postmortem-ddid-density=float

If more than the given fraction of data in a DDID is flagged, flag entire DDID. Default: 0.5.

[sol]

Options pertaining to the solver.

--sol-jones=multi

Comma-separated list of Jones terms to enable, e.g. “G,B,dE”. These tags must correspond to the user-defined gain templates at the bottom of the .parset file. Default: G.

--sol-precision=keyword

Solve in single or double precision. Keywords: 32, 64. Default: 32.

--sol-delta-g=float

Theshold for gain accuracy - gains which improve by less than this value are considered converged. Default: 1e-6.

--sol-delta-chi=float

Theshold for solution stagnancy - if the chi-squared is improving by less than this value, the gain is considered stalled. Default: 1e-6.

--sol-chi-int=int

Number of iterations to perform between chi-suqared checks. This is done to avoid computing the expensive chi-squared test evey iteration. Default

--sol-last-rites=bool

Re-estimate chi-squred and noise at the end of a solution cycle. Disabling last rites can save a bit of time, but makes the post-solution stats less informative. Default: 1.

--sol-stall-quorum=float

Minimum percentage of solutions which must have stalled before terminating the solver. Default: 0.99.

--sol-term-iters=multi

Number of iterations per Jones term. If empty, then each Jones term is solved for once, up to convergence, or up to its -max-iter setting. Otherwise, set to a list giving the number of iterations per Jones term. For example, given two Jones terms and --sol-term-iters 10,20,10 it will do 10 iterations on the first term, 20 on the second, and 10 again on the first. No default.

--sol-min-bl=float

Min baseline length to include in solution. Default: 0.

--sol-max-bl=float

Max baseline length to include in solution. If 0, no maximum is applied. Default: 0.0.

--sol-subset=str

Additional subset of data to actually solve for. Any TaQL string may be used. No default.

[bbc]

Options related to baseline-based corrections.

--bbc-load-from=str

Load and apply BBCs computed in a previous run. Apply with care! This will tend to suppress all unmodelled flux towards the centre of the field. No default.

--bbc-compute-2x2=bool

Compute full 2x2 BBCs (as opposed to diagonal-only). Only useful if you really trust the polarisation information in your sky model. Default: 0.

--bbc-apply-2x2=bool

Apply full 2x2 BBCs (as opposed to diagonal-only). Only enable this if you really trust the polarisation information in your sky model. Default: 0.

--bbc-save-to=str

Compute suggested BBCs at end of run, and save them to the given database. It can be useful to have this always enabled, since the BBCs provide useful diagnostics of the solution quality (and are not actually applied without a load-from setting). (default: “{data[ms]}/BBC- field:{sel[field]}-ddid:{sel[ddid]}.parmdb”)

--bbc-per-chan=bool

Compute BBCs per-channel (instead of across the entire band). Default: 1.

--bbc-plot=bool

Generate output BBC plots. Default: 1.

[dist]

Options related to parallelism.

--dist-ncpu=int

Max number of CPU cores to use. 0 disables parallelism. Default: 0.

--dist-nworker=int

Number of worker processes to launch (excluding the IO worker). When 0, determined automatically from the --dist-ncpu. Default: 0.

--dist-nthread=int

Number of OMP threads to use. When 0, determine automatically. Default: 0.

--dist-max-chunks=int

Maximum number of time/freq data-chunks to load into memory simultaneously. If 0, then as many as possible will be loaded. Default: 0.

--dist-min-chunks=int

Minimum number of time/freq data-chunks to load into memory simultaneously. If 0, determined automatically. Default: 0.

--dist-pin=multi

If empty or None, processes will not be pinned to cores. Otherwise, set to the starting core number, or “N:K” to start with N and step by K. Default: 0.

--dist-pin-io=bool

If not 0, pins the I/O & Montblanc process to a separate core, or cores (if --montblanc-threads is specified). Ignored if --dist-pin is not set. Default: 0.

--dist-pin-main=keyword

If set, pins the main process to a separate core. If set to “io”, pins it to the same core as the I/O process, if I/O process is pinned. Ignored if --dist- pin is not set. Keywords: 0, 1, io. Default: io.

[out]

Options controlling output locations and types.

--out-dir=str

Base name of directory for output files. The suffix .cc-out will be implicitly appended, unless OUTDIR ends with a slash. Default: cubical.

--out-name=str

Base name for output files. Full base path will be OUTDIR[.cc-out]/OUTNAMExxx, unless OUTNAME contains a slash, in which case OUTDIR is ignored and OUTNAME is taken to be a full base path. Default: cc.

--out-overwrite=bool

Allow overwriting of existing output files. If this is set, and the output parset file exists, will raise an exception. Default: False.

--out-backup=bool

Allow automatic backup of existing output directories. Automatic backup is only used when OUTDIR is used (i.e. OUTNAME doesn’t contain any slashes), and it ends with .cc-out (implicitly or explicitly). In this case, existing output directories are renamed to .cc.out.0, .1, etc. Default: True.

--out-mode=keyword

Operational mode. [so] solve only; [sc] solve and generate corrected visibilities; [sr] solve and generate corrected residuals; [ss] solve and generate uncorrected residuals; [ac] apply solutions, generate corrected visibilities; [ar] apply solutions, generate corrected residuals; [as] apply solutions, generate uncorrected residuals. Keywords: so, sc, sr, ss, ac, ar, as. Default: sc.

--out-apply-solver-flags=bool

Apply solver flags when writing new data to measurement set. Default: True.

--out-derotate=multi

Explicitly enables or disables derotation of output visibilities. Default (None) is to use the –model-pa-rotate and –model-feed-rotate settings. Options: None | 0 | 1.

--out-column=str

Output MS column name (if applicable). Default: CORRECTED_DATA.

--out-model-column=str

If set, model visibilities will be written to the specified column. No default.

--out-weight-column=str

If set, weights from the Robust Solver will be written to the specified column. This should be set only if we are using the robust solver. No default.

--out-reinit-column=bool

Reinitialize output MS column. Useful if the column is in a half-filled or corrupt state. Default: 0.

--out-subtract-model=int

Index of model to subtract, if generating residuals. Default: 0.

--out-subtract-dirs=multi

Which model directions to subtract, if generating residuals. “:” subtracts all. Can also be specified as “N”, “N:M”, “:N”, “N:”, “N,M,K”. Default: :.

--out-plots=bool

Generate summary plots. Default: 1.

--out-plots-show=bool

Show summary plots interactively. Default: 0.

--out-casa-gaintables=bool

Export gaintables to CASA caltable format. Tables are exported to same directory as set for cubical databases. Default: 1.

[log]

Options to allow control of logging functionality.

--log-memory=bool

Log memory usage. Default: 1.

--log-boring=bool

Disable progress bars and some console output. Default: 1.

--log-append=bool

Append to log file if it exists. Default: 0.

--log-verbose=multi

Default console output verbosity level. Can either be a single number, or a sequence of “name=level,name=level,…” assignments. Default: 0.

--log-file-verbose=multi

Default logfile output verbosity level. Can either be a single number, or a sequence of “name=level,name=level,…” assignments. If None, then this simply follows the console level. Default: None.

[debug]

Options pertaining to debugging. Mainly for developers.

--debug-pdb=bool

Jumps into pdb on error. Default: 0.

--debug-panic-amplitude=float

Throw an error if a visibility amplitude in the results exceeds the given value. Useful for troubleshooting. Default: 0.0.

--debug-stop-before-solver=bool

Invoke pdb before entering the solver. Default: 0.

[gainterm]

Options pertaining to a specific gain term. This is not a unique section in the parset. Each gain term specified in --sol-jones must have a (not necessarily complete) section like this one. For the example given in --sol-jones, there should be three separate sections like this, one for [g], [b] and [de] respectively. Their options will be specified by --g-, --b- and --de- respectively.

--gainterm-solvable=bool

Set to 0 (and specify -load-from or -xfer-from) to load a non-solvable term from disk. Not to be confused with --sol-jones, which determines the active Jones terms. Default: 1.

--gainterm-type=keyword

Type of Jones matrix to solve for. Note that if multiple Jones terms are enabled, then only complex- 2x2 is supported. Keywords: complex-2x2, complex-diag, phase-diag, robust-2x2, f-slope, t-slope, tf-plane. Default: complex-2x2.

--gainterm-load-from=str

Load solutions from given database. The DB must define solutions on the same time/frequency grid (i.e. should normally come from calibrating the same pointing/observation). By default, the Jones matrix label is used to form up parameter names, but his may be overridden by adding an explicit “//LABEL” to the database filename. No default.

--gainterm-xfer-from=str

Transfer solutions from given database. Similar to -load-from, but solutions will be interpolated onto the required time/frequency grid, so they can originate from a different field (e.g. from a calibrator). (default: )

--gainterm-save-to=str

Save solutions to given database. Default: {data[ms]} /{JONES}-field:{sel[field]}-ddid:{sel[ddid]}.parmdb.

--gainterm-dd-term=bool

Determines whether this term is direction dependent. --model-ddes must be enabled. Default: 0.

--gainterm-fix-dirs=multi

For DD terms, makes the listed directions non- solvable. No default.

--gainterm-update-type=keyword

Determines update type. This does not change the Jones solver type, but restricts the update rule to pin the solutions within a certain subspace: ‘full’ is the default behaviour; ‘diag’ pins the off-diagonal terms to 0; ‘phase-diag’ also pins the amplitudes of the diagonal terms to unity; ‘amp-diag’ also pins the phases to 0. Keywords: full, phase-diag, diag, amp-diag. Default: full.

--gainterm-time-int=int

Time solution interval for this term. Default: 1.

--gainterm-freq-int=int

Frequency solution interval for this term. Default: 1.

--gainterm-max-prior-error=float

Flag solution intervals where the prior error estimate is above this value. Default: 0.1.

--gainterm-max-post-error=float

Flag solution intervals where the posterior variance estimate is above this value. Default: 0.1.

--gainterm-low-snr-warn=float

Trigger SNR warning to the user at this threshold. Default: 75.

--gainterm-high-gain-var-warn=float

Trigger posterior gain variance warning to the user at this threshold. Default: 30.

--gainterm-clip-low=float

Amplitude clipping - flag solutions with diagonal amplitudes below this value. Default: 0.1.

--gainterm-clip-high=float

Amplitude clipping - flag solutions with any amplitudes above this value. 0 disables. Default: 10.0.

--gainterm-clip-after=int

Number of iterations after which to start clipping this gain. Default: 5.

--gainterm-max-iter=int

Maximum number of iterations spent on this term. Default: 20.

--gainterm-epsilon=float

Convergence threshold. Solutions that change by less than this value are considered converged. Default: 1e-6.

--gainterm-delta-chi=float

Threshold for solution stagnancy – if the chi-squared is improving by less (relatively), then the solution is marked as stalled. Default: 1e-6.

--gainterm-conv-quorum=float

Minimum percentage of converged solutions to accept. Default: 0.99.

--gainterm-ref-ant=int

Reference antenna - its phase is guaranteed to be zero. Default: None.

--gainterm-prop-flags=keyword

Flag propagation policy. Determines how flags raised on gains propagate back into the data. Options are ‘never’ to never propagate, ‘always’ to always propagate, ‘default’ to only propagate flags from direction-independent gains. Keywords: never, always, default. Default: default.

--gainterm-estimate-pzd=bool

Estimate phase-zero difference and initialize the gains with it. Use for polarization calibration. Default: False.

--gainterm-diag-only=bool

Use only diagonal (parallel-hand) data and model terms for the solution. Note that gains are still applied to the full 2x2 data (unless –sel-diag is also set). Default: False.

--gainterm-offdiag-only=bool

Use only off-diagonal data and model terms for the solution, and only solve for off-diagonal Jones elements, pinning the on-diagonals to 1. Default: False.

--gainterm-robust-cov=keyword

Determines how the residuals covariance matrix is computed if the robust-2x2 solver is selected. Options are ‘compute’ to compute normaly, ‘identity’ to set the covariance to 1 (identity matrix) as in the Robust-t paper, and ‘hybrid’ which is the default computes the covaraince matrix C but sets it to 1 if the elements are greater than 1. Keywords: compute | identity | hybrid.

--gainterm-robust-scale=bool

Scales down the residuals covariance matrix. Simulations show that this improves the results with unmodelled sources. Default: True.

--gainterm-robust-npol=int

The number of correlations (polarizations) actually present in the visibilities. This option only applies if the robust-2x2 solver is selected. Expectings 2 or 4 correlations. Default: 2.

--gainterm-robust-int=int

Number of iterations after which the v-parameter is recomputed for the robust solver. Default: 1.

--gainterm-robust-save-weights=bool

Determines if the appied weights from the robust-2x2 solver are stored. This option only applies if the robust-2x2 solver is selected. If this option is set, output-weight-column must be set too. Default: False.