Usage

This page details running QuartiCal for the first time, including navigating the help and specifying input arguments.

Command Line Interface

Once QuartiCal has been successfully installed, it can be run from the command line using:

goquartical

This will produce detailed help on all the input parameters. The help can also be displayed using:

goquartical help

We appreciate that this can be overwhelming and difficult to navigate. Thus, users can ask for help on specific sections using the following:

goquartical help=[section1,section2]

The options for this are listed in green at the bottom of the full help.

QuartiCal can be run directly from the command line by specifying the relevant inputs, e.g.:

goquartical input_ms.path="/path/to.ms" input_model.recipe="MODEL_DATA" input_ms.sigma_column="SIGMA_SPECTRUM"

Whilst this is convenient for simple examples, it can become cumbersome when doing particularly complicated calibration which uses a large number of the available inputs.

Config Files

In order to make specifying all of the relevant parameters more convenient, QuartiCal allows users to provide one or more .yaml files containing the necessary arguments.

The .yaml file corresponding to the command above will look like this:

input_ms:
    path: path/to.ms
    sigma_column: SIGMA_SPECTRUM

input_model:
    recipe: MODEL_DATA

If the above parset was named basic.yaml, it could be run by invoking:

goquartical basic.yaml

This simple example only uses a fraction of the available options - unspecified options are populated from the defaults.

Note that multiple .yaml files can be specified in addition to command line arguments. The .yaml files will be consumed in order, while command line arguments will always be consumed last. Consider the following example:

goquartical basic.yaml less_basic.yaml input_ms.path=path/to_different.ms

In this example, the contents of basic.yaml would be augmented (and overwritten in the case of conflicting options) with the contents of less_basic.yaml. Finally, the remaining command line options would be taken into account, overwriting any conflicting values specified in the provided .yaml files. This aims to make configuring QuartiCal as painless and flexible as possible.

Note

Quartical provides a command line utility to generate unpopulated .yaml files. It can be invoked using:

goquartical-config configname.yaml

This will produce a .yaml file with the given name and all available fields.

Dynamic Fields

QuartiCal is exceptionally flexible when it comes to gain calibration. To avoid having too many options, it makes use of dynamically created config fields. This applies to specifying gain terms.

As an example, consider solving for a gain and bandpass (following their usual definitions). To do so, a user would need to tell QuartiCal that there are two gain terms and then provide the relevant arguments for those gains.

The contents of the .yaml would look as follows for this case:

solver:
    terms:
        - G
        - B
    iter_recipe:
        - 25
        - 25

G:
    type: diag_complex
    freq_interval: 0
B:
    type: diag_complex
    time_interval: 0

QuartiCal will automatically know that each term has its own dynamically generated section in the config, labelled by the term name (G or B in this example).

The above can also be specified on the command line using:

solver.terms="[G,B]" solver.iter_recipe="[25,25]" G.type=diag_complex G.freq_interval=0 B.type=diag_complex B.time_interval=0

Note

Lists in .yaml files can be specified in two ways:

solver:
    terms:
        - G
        - B

or

solver:
    terms: [G,B]