Private parameters for program NCALIB
This document contains an overview of the parameter interface of the program NCALIB. The program also uses a number of public interfaces; references to these are also listed. show parameters that The remainder of the document describes the individual parameters in alphabetical order. This description centers on the Help texts, which have been designed to guide the user to the proper choice at each junction, even if his knowledge of the overall workings of the program is only superficial.
See also:
Prompt: Type of Selfcal desired
Expected input: Character *8: 1 value
Selfcal is the generic name for all methods that use a source model in combination with your visibilities to estimate the telecope gain/phase corrections. Since you have selected a model, NCALIB assumes that you want to use it, by doing a Selfcal. (If you had not, it would propose a REDUNdancy-only solution.)
The alternative you have here is to use the source model to recover the unknown position shift that scans suffer when they are processed with the redundancy constraints only (REDUN solution). In this operation the source model is only used as a position reference. The telescope phases are shifted by an amount that is a linear function of position along the array; the telescope gains do not change at all.
To summarise, the choices you have are:
SELFCAL use the model to constrain in position a redundancy solution
that will be made now
ALIGN use the model to constrain a redundancy solution that was made
earlier
Prompt: Redundant-baseline difference allowed (metres)
Expected input: Real: 1 value
Specify the maximum difference between baselines for them still to be considered identical in Redundancy calculations.
Prompt: Increments to telescope X positions (mm) |
Expected input: Real: 1 to 14 values
Specify the X telescope corrections in mm, one value per telescope.
The correction will be added as an HA-dependent phase to the OTH telescope corrections. It can only be undone by either zeroing the entire OTH corrections by means of the SET ZERO option (which will destroy whatever other corrections have been stored there), or by inserting the same BASEL_DX value with opposite sign.
The default value 0,0,...0,0 leaves the corrections unchanged.
Prompt: Increments to telescope Y positions (mm) |
Expected input: Real: 1 to 14 values
Specify 14 Y telescope corrections in mm, one value per telescope.
The correction will be added as an HA-dependent phase to the OTH telescope corrections. It can only be undone by either zeroing the entire OTH corrections by means of the SET ZERO option (which will destroy whatever other corrections have been stored there), or by inserting the same BASEL_DY value with opposite sign.
The default value 0,0,...0,0 leaves the corrections unchanged.
Prompt: increments to telescope Z positions (mm) |
Expected input: Real: 1 to 14 values
Specify the Z telescope corrections in mm, one value per telescope.
The correction will be added as an HA-dependent phase to the OTH telescope corrections. It can only be undone by either zeroing the entire OTH corrections by means of the SET ZERO option (which will destroy whatever other corrections have been stored there), or by inserting the same BASEL_DZ value with opposite sign.
The default value 0,0,...0,0 leaves the corrections unchanged.
Expected input: Real: 1 value
Specify the baseline-pole declination correction in degrees.
The correction will be added as an HA-dependent phase to the OTH telescope corrections. It can only be undone by either zeroing the entire OTH corrections by means of the SET ZERO option (which will destroy whatever other corrections have been stored there), or by inserting the same BASEL_POLE value with opposite sign..
The default value 0 leaves the corrections unchanged.
Prompt: Copy with equal length?
Expected input: Yes/No: 1 value
If YES, all calibrators specified with USE_SCN_SETS will be made of equal length, that is: the number of HA scans used for each calibrator will be the same (and equal to the smallest number available).
This is necessary when calibrators have frequencies that have been offset (plus and minus respectively) to the observing frequency of the target source.
Prompt: Iterations, gain deviation, relative mean error: 3 values|
Expected input: Real: 1 to 3 values
Specify:
- the maximum number of iterations in the complex solution;
- the relative allowable gain deviation for successive complex solutions;
- the mean error allowed per scan, relative to the average mean error
for all scans already solved.
Prompt: Clock correction (sec)
Expected input: Real: 1 value
Specify the clock correction in seconds to be applied to data. The new value will be ADDED to the existing one.
Prompt: Complex solution (YES/NO)?
Expected input: Yes/No: 1 value
Specify if you want a complex solution of gains-plus-phases.
Prompt: Complex solution only (YES/NO)?
Expected input: Yes/No: 1 value
Specify if you want ONLY a complex solution.
Note: will only work if an initial guess for the gains (e.g. from a calibrator) has been specified
Prompt: Continuity in solution (YES/NO)?
Expected input: Yes/No: 1 value
Specify if you want continuity in gain solution. If not, the initial guess for the solution will be 0 (gain) and the forced phases (phase), else the solution found in a previous scan.
Prompt: Shift rate (dl/dt, dm/dt, arcsec/day)
Expected input: Real: 1 to 2 values
Specify the SHIFT rate in arcsec per sidereal day to be applied to the data whenever the DE_APPLY SHIFT correction is requested.
This parameter is used for a first-order approximation to the proper motion of a solar-system object through the formula:
Total shift = SHIFT + DSHIFT * (HA-HAB)
where hour angles are measured as fractions of a full circle and HAB is the starting HA of the sector..
Prompt: Extinction-1: quadratic's coefficients|
Expected input: Real: 1 to 3 values
Specify the coefficients A, B and C in the quadratic representation of the zenith extinction oefficient as a function of frequency F in GHz:
EXT= (1+A) + B*F +C*F*F
Prompt: Faraday-rotation data file
Expected input: Character: 1 value
Specify the name of a file with Faraday rotation data. The file must be an ASCII file with lines
<hour angle in degrees>, <faraday rotation in degrees at 1GHz>
The file will be used to calculate Faraday rotation values for each scan by interpolation between the values in this file and scaling to the observing frequency. The calculated values will be stored in the scans as corrections.
Prompt: Weight for points flagged with WGT flag
Expected input: Real: 1 value
The WGT flag directs NCALIB to multiply the data weight with an additional weighing factor.
You may use this feature to reduce the weight of data affected by interference without rejecting it completely. The effect of this in a Selfcal solution is that it prevents the interference from bad interferometers to infect the healthy ones.
A value of 1 will give all interferometers the weight they have in the .SCN file.
Prompt: Manual constraints for gain (1st value)|-
Expected input: Yes/No: 1 to 2 values
Specify if you want to force the constraint equations for the align solution. If you reply NO, the program will determine them by itself from the interferometers selected.
Your first reply refers to Gain, the second one to Phase.
Prompt: Define phase-zeroes
Expected input: Real: 1 to 14 values
Define initial phase zeros per telescope.
This is useful for pathological cases where NCALIB on its own cannot correctly resolve the 360-deg phase ambiguities.
Prompt: Increment to frequency correction (MHz)
Expected input: Real: 1 value
Specify the 'frequency correction' in MHz.
This is an idiosyncratic way of representing a correction to the metric scale of the interferometer array: A scale correction with a factor (1+x) is represented by correcting the nominal observing frequency F with an additive term -x.F.
Clearly this does not represent a real frequency shift since the observing frequency is precisely defined by the settings of local-oscillator frequencies and fringe-stopping parameters during the observation.
The correction will be ADDED as an hour-angle-dependent phase to the OTH telescope corrections, and can only be undone by either zeroing these corrections, or inserting the same BASEL_POLE value with opposite sign.
Prompt: Gain grouping
Expected input: Integer: 1 to 14 values
Define the telescope groups for which the gains will be solved independently.
To solve e.g. separate gains for the 10 fixed telescopes (0 through 9) and the 4 movable ones (A through D), specify:
1,1,1,1,1,1,1,1,1,1, 2,2,2,2
* means one group containing all telescopes (i.e. 1,1,...,1,1).
Prompt: Gain reference telescopes
Expected input: Integer: 1 to 14 values
Define the telescopes to be used as reference for renormalising the telescope gains.
Your reply should be an array of values (separated by commas) for telescopes 0 through D; 1 means that you select the telescope, 0 that you don't. Trailing 0s may be omitted.
A wildcard ('*') means 'all', i.e. 1,1,1,1,1,1,1,1,1,1,1,1,1,1
Example:
0,1,0,1,0 means 'use telescopes 1 and 3 as reference'
NOTES:
Renormalisation adjusts the gains so that the average for the fixed telescopes selected equals that for the moving telescopes. If either group is absent from yous selection, the average gain of the other group is made 0.
Consequently, proper gain renormalisation is possible only for the 'standard' WSRT configuration: If there are any fixed-fixed or movable-movable interferometers, a message will be given and the operation aborted.
You may, however, insist by putting a -1 instead of any of the 1s in your reply. The renormalisation will then be performed as if the fixed-movable interferometers were absent, and a warning given that the gain corrections for those interferometers are jeopardized.
Prompt: Gain corrections X (factors) |
Expected input: Real: 1 to 14 values
Specify the X gain corrections per telescope as factors (1= no change).
The values you give will be multiplied with the existing gain factors if you choose SET option MULT, they will replace the existing factors if you choose SET option MANUAL.
Prompt: Interferometer gain corrections XX (factors) |
Expected input: Real: 1 value
Specify the gain corrections for XX as factors (1= no change). You will be prompted for values, which will OVERWRITE the existing interferometer gain corrections.
Prompt: interferometer gain corrections XY (factors) |
Expected input: Real: 1 value
Specify the gain corrections for XY as factors (1= no change). You will be prompted for values, which will OVERWRITE the existing interferometer gain corrections.
Prompt: Gain corrections Y (factors) |
Expected input: Real: 1 to 14 values
Specify the Y gain corrections per telescope as factors (1= no change).
The values you give will be multiplied with the existing gain factors if you choose SET option MULT, they will replace the existing factors if you choose SET option MANUAL.
Prompt: interferometer gain corrections YX (factors) |
Expected input: Real: 1 value
Specify the gain corrections for YX as factors (1= no change). You will be prompted for values, which will OVERWRITE the existing interferometer corrections.
Prompt: interferometer gain corrections YY (factors) |
Expected input: Real: 1 value
Specify the gain corrections for YY as factors (1= no change). You will be prompted for values, which will OVERWRITE the existing interferometer corrections.
Prompt: Integration time (sec)
Expected input: Real: 1 value
Specify the time interval over which you want to integrate (if possible) before calibrating. The value you specify will be rounded down to a multiple of the hour-angle interval between successive scans.
'*' and '0' mean do not integrate, i.e. calibrate per scan.
The largest value allowed is 3600 (= 1 hour).
Prompt: additive interferometer corrections cos,sin XX (W.U.) |
Expected input: Real: 1 to 2 values
Specify the additive interferometer corrections for XX in Westerbork Units (W.U.). The values you specify will OVERWRITE any existing values.
Prompt: additive interferometer corrections cos,sin XY (W.U.) |
Expected input: Real: 1 to 2 values
Specify the additive interferometer corrections for XY in Westerbork Units (W.U.). The values you specify will OVERWRITE any existing values.
Prompt: additive interferometer corrections cos,sin YX (W.U.) |
Expected input: Real: 1 to 2 values
Specify the additive interferometer corrections for YX in Westerbork Units (W.U.). The values you specify will OVERWRITE any existing values.
Prompt: additive interferometer corrections cos,sin YY (W.U.) |
Expected input: Real: 1 to 2 values
Specify the additive interferometer corrections for YY in Westerbork Units (W.U.). The values you specify will OVERWRITE any existing values.
Prompt: Ionospheric refraction data file
Expected input: Character: 1 value
Specify the name of a file with ionospheric refraction data. The file must be an ASCII file with lines
<hour angle in degrees>, <refraction in degrees/km at 1GHz>
The file will be used to calculate ionospheric refraction for each scan by interpolation between the values in this file and scaling to the observing frequency. The calculated values will be stored in the scans as corrections.
Prompt: Centre, halfwidth (metres)
Expected input: Real: 1 to 2 values
Specify the centre and the halfpower-halfwidth in metres of the model weight function to be applied.
Only positive values are accepted. Note that the function you define may extend over negative baselines but actual baselines are positive by definition.
Prompt: Type of weight function|
Expected input: Character *10: 1 value
MWEIGHT_TYPE and MWEIGHT_DATA allow you to weigh baselines according to their lengths, in order to take advantage of source characteristics that are a priori known. The defaults for these parameters give all baselines the same weight.
This parameter selects the form of the weighting function; its position and half-width will be defined by MWEIGHT_DATA. The following shapes can be chosen:
STEP a step function: 1 out to some radius, 0 beyond GAUSSIAN a Gaussian TRIANGLE a triangular function: linearly decreasing from 1 to 0
Each of these can be prefixed with an 'I' to invert it, i.e. ISTEP means
'1 minus STEP'
Prompt: Type of action
Expected input: Character *12: 1 value
Specify type of action to perform:
REDUNDANCY create telescope corrections by solving the
redundancy/align/selfcal equations
POLAR operations on polarisation corrections
SET operations on all other corrections
SHOW show (in logfile) average corrections in specified sector(s) QUIT finish
Prompt: SET action (others)|
Expected input: Character *6: 1 value
Specify action to perform to ADD corrections into the OTHer telescope
corrections:
MULT set an extra gain factor (multiply existing values)
DX add telescope X correction in selected scans
DY add telescope Y correction in selected scans
DZ add telescope Z correction in selected scans
POLE add baseline pole correction in selected scans
FREQ add frequency offset correction in selected scans
QUIT exit SET
Prompt: Phase grouping
Expected input: Integer: 1 to 14 values
Define the telescope groups for which the phases will be solved independently.
To solve e.g. separate gains for the 10 fixed telescopes (0 through 9) and the 4 movable ones (A through D), specify:
1,1,1,1,1,1,1,1,1,1, 2,2,2,2
* means one group containing all telescopes (i.e. 1,1,...,1,1). Up to 14 groups may be defined.
Prompt: Phase reference telescopes
Expected input: Integer: 1 to 14 values
Define the telescopes to use as reference for renormalising the telescope phases.
Your reply should be an array of values (separated by commas) for telescopes 0 through D; 1 means that you select the telescope, 0 that you don't. Trailing 0s may be omitted.
A wildcard ('*') means 'all', i.e. 1,1,1,1,1,1,1,1,1,1,1,1,1,1
Example:
0,1,0,1,0 means 'use telescopes 1 and 3 as reference
Prompt: Phase corrections X (deg) |
Expected input: Real: 1 to 14 values
Specify the X phase corrections to be added per telescope (0 = no change).
The values you give will be added to the existing OTHer phases if you choose SET option MULT, they will replace the existing phases if you choose SET option MANUAL.
Prompt: interferometer phase corrections XX (deg) |
Expected input: Real: 1 value
Specify the phase corrections for XX. You will be prompted for values, which will OVERWRITE the existing interferometer corrections.
Prompt: interferometer phase corrections XY (deg) |
Expected input: Real: 1 value
Specify the phase corrections for XY. You will be prompted for values, which will OVERWRITE the existing interferometer corrections.
Prompt: Phase corrections Y (deg) |
Expected input: Real: 1 to 14 values
Specify the Y phase corrections to be added per telescope (0 = no change).
The values you give will be added to the existing OTHer phases if you choose SET option MULT, they will replace the existing phases if you choose SET option MANUAL.
Prompt: interferometer phase corrections YX (deg) |
Expected input: Real: 1 value
Specify the phase corrections for YX. You will be prompted for values, which will OVERWRITE the existing interferometer corrections.
Prompt: interferometer phase corrections YY (deg) |
Expected input: Real: 1 value
Specify the phase corrections for YY. You will be prompted for values, which will OVERWRITE the existing interferometer corrections.
Prompt: action on polarisation corrections|
Expected input: Character *8: 1 value
Specify action to perform on polarisation corrections:
Calculate corrections from calibrator visibilities. The new correction values are ADDED to existing ones:
CALC calculate dipole corrections
VZERO select the set of operations dealing with the phase-zero
difference ('PZD') between the X and Y channel groups
Copy/set corrections. The new corrections values generally OVERWRITE the existing ones:
COPY create dipole corrections in target sectors by copying them
from one source sector
SET set dipole corrections manually
ZERO zero dipole corrections
Inspection:
SHOW show dipole corrections
EDIT edit dipole corrections
Other:
QUIT exit from POLAR
Prompt: Dipole orthogonalities (deg)|
Expected input: Real: 1 to 14 values
Specify the deviations from orthogonality in the dual-dipole assemblies per telescope in degrees.
Prompt: Dipole positions (deg)|
Expected input: Real: 1 to 14 values
Specify the position angles of the dual-dipole assemblies per telescope in degrees.
Prompt: X-dipole ellipticities (Expected input: Real: 1 to 14 values
Specify the X-dipole ellipticities per telescope in %
Prompt: Y-dipole ellipticities (Expected input: Real: 1 to 14 values
Specify the Y-dipole ellipticities per telescope in %
Prompt: More details? (YES/NO)
Expected input: Yes/No: 1 value
Specify if you want to specify details of the solution procedure yourself rather than relying on NCALIB's expert defaults.
Prompt: Refraction-1: quadratic's coefficients|
Expected input: Real: 1 to 3 values
Specify the coefficients A, B and C in the quadratic representation of the refraction coefficient as a function of frequency F in GHz:
EXT= (1+A) + B*F +C*F*F
Prompt: Save the interferometer residuals as interferometer errors?
Expected input: Yes/No: 1 value
If YES, the interferometer residuals after Selfcal, Align or Redun will be saved for later use as Multiplicative Interferometer errors.
Prompt: SET action|
Expected input: Character *8: 1 value
Specify action to perform to alter correction values.
Note: POLARISATION corrections are NOT included here. They must be handled
sparately through the POLAR main option.
These option write correction values in (a) set(s) of target sectors (selected by the SCN_<xxx> parameters). These corrections are copied/calulated from corrections /data in the same file or another one (USE_SCN_<xxx> parameters). The calculations will use all source sectors you specify to obtain a single set of corrections. Unless stated otherwise below, the new values will be ADDED to the existing ones in each of the target sectors.
Transfer of corrections from a reference source:
COPY copy all corrections from somewhere else
(all corrections in the input set(s) are averaged)
CCOPY copy corrections from surrounding (in time) observations
in the input sets with the same frequency channel
(corrections for the two input sets are averaged).
ICOPY copy all MIFR corrections from somewhere else
(all corrections in the input set(s) are averaged)
LINE copy all corrections from corresponding continuum channel
Initialisation:
ZERO zero corrections
MANUAL copy input values into the OTH telescope corrections for
selected scans
INIT make an initial estimate of telescope corrections and shift the
present values accordingly
RENORM renormalise telescope corrections
Manual-input actions. Each option represents a correction type for which
your values will be requested.
- For the following actions, your values will OVERWRITE the existing ones:
EXT set extinction in selected scans
REF set refraction in selected scans
IREF set ionospheric refraction in selected scans
FAR set Faraday rotation in selected scans
IFR set additive interferometer corrections in selected scans
MIFR set multiplicative interferometer corrections in selected scans
CLK set clock correction in selected scans
SHIFT set (de-apply) coordinate shift in selected sectors
QUIT exit SET
Prompt: Shift to de-apply to data (arcsec)
Expected input: Real: 1 to 2 values
Specify the l,m shift in arcsec to be applied to data whenever the DE_APPLY SHIFT correction is requested. (Ignore the 'de-apply) in the prompt.)
In the case where the shift is time-dependent (e.g. for a planet) it is approximated by a linear function
Total shift = SHIFT + DSHIFT * (HA-HAB)
In this case the SHIFT you specify here is the value at the meridian, DSHIFT is a second parameter for which you will be prompted.
Prompt: Levels of terminal (1st value)| and log (2nd value) output
Expected input: Integer: 1 to 2 values
Specify the level of the type and print output you want:
0 none
1 sector numbers, errors and summary of results only (the summary in the
log file includes phase constraints and solution details which are not
shown on the terminal)
2 detailed report (several pages) per integration interval (parameter
HA_INTEGRATION) - intended primarily for debugging purposes
Prompt: Solve for gain, phase (YES/NO, 2 values)?
Expected input: Yes/No: 1 to 2 values
Specify if you want solutions for gain and for phase.
Prompt: Input .SCN-file name
Expected input: Character *80: 1 value
Specify the input .SCN file from which the corrections should be calculated or
copied. A wildcard value ('*') indicates the same as the output .SCN file.
Prompt: Sets of input .SCN-file sectors: grp.obs.fld.chn.seq|
Expected input: Character *32: 1 to 64 values
Specify the .SCN-file sectors to be used as input in the calculations.
Prompt: VZERO action
Expected input: Character *8: 1 value
This branch of NCALIB implements methods to define the unknown X-Y phase-zero
difference ('PZD') in the parallel-dipole configuration.
Correction values may be saved in an arbitrary selection of target sectors, selected by the SCN_<xxx> parameters. The new corrections are OTH telescope phases which will be ADDED to any existing ones in each of the sectors you specify for output.
In determining the corrections, the program uses a collection of input sectors, which may coincide with the target sectors or be selected by the USE_SCN_ parameters (for the COPY option). It is assumed that the source for these is a calibrator with significant Stokes U and 'negligibly' small Stokes V. If this condition is not fulfilled, the result will be meaningless.
The PZD is a phase value that is ADDED to the existing OTH phase correction of the X channels. For this reason, you must be cautious to
- avoid more than one COPY to the same target data and
- avoid ruining a calibrator observation by doing an APPLY on it. (If
you should do this by accident, use MANUAL to restore the observation
to its previous state.)
Specify action to perform:
Actions recommended for routine use:
CALC calculate PZD from the selected node and sectors (SCN_
parameters) and display it with its mean error. Use this option
to check if a calibrator observation is suitable for
determining the PZD.
COPY as APPLY, but use X-Y phase-difference value derived from
a calibrator observation (USE_SCN_<xxx> parameters). Use this
option to set the correction for your observations
MANUAL manually input phase-difference value
Other actions:
SCAN as CALC, but per individual scan
APPLY as CALC, then apply the correction to the sectors selected
(SCN_<xxx> parameters).
NOTE that once you have performed this operation, a CALC or COPY
operation on the same input data will yield PZD=0, so these
data can no longer be used to calibrate another observation.
ASK as APPLY, but display and ask for confirmation before modifying
the existing values
QUIT exit from VZERO
Prompt: X-Y phase-zero difference 'PZD' (deg)
Expected input: Real: 1 value
Specify the 'phase-zero difference' (PZD) in degrees.
In the parallel-dipole configuration, performing a Redundancy or Selfcal fit of telescope errors to the visibilities introduces an unknown phase offset for the set of telescope X channels and another unknown phase offset for the Y dipoles. For correctly determining Stokes U and V, the (equally unknown) difference between these must be corrected for.
This is a tricky problem and you should remain suspicious of the results that you get.
Prompt: Relative minimum weight accepted
Expected input: Real: 1 value
Specify the minimum relative weight of a data point that is still acceptable.
The weight is relative to the maximum weight in the same scan, and in most cases can be seen as the minimum data amplitude accepted as fraction of the maximum in the scan.
Prompt: Corrections (plural) to be zeroed |
Expected input: Character *8: 1 to 12 values
Specify any number of corrections you want to zero:
Generic:
ALL or * All corrections
NONE None of the corrections: Return to previous prompt
Telescope gains and phases:
RED Redundancy telescope corrections
ALG Align telescope corrections
OTH 'Other' telescope gain/phase corrections
Interferometer gains and phases:
IFR Additive interferometer corrections
MIFR Multiplicative interferometer corrections
Corrections for the instrument as a whole:
EXT Extinction correction
REF Refraction correction
IREF Ionospheric refraction correction
FAR Faraday rotation
CLK Clock correction
SHIFT Coordinate shifts (de-apply)
You may restrict the above to phase-only or gain-only by appending AT THE END of your reply either of:
NOGAIN Zero only phases
NOPHASE Zero only gain
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.