getcalmodvla

getcalmodvla(outfile='', overwrite=False, source='', direction='', band='', obsdate='0', refdate='0', hosts=['http://obs.vla.nrao.edu/calmodvla'])[source]

Retrieve calibrator brightness distributions from a VLA web service.

[Description] [Examples] [Development] [Details]

Parameters

outfile (path=’’) - The name of the output component list to be written. Must be specified
overwrite (bool=False) - Overwrite a file or directory of the same name as outfile if it exists.
source (string=’’) - The calibrator name.
direction (string=’’) - The direction of the calibrator
band (string=’’) - The receiver band for which the source structure is needed
obsdate (variant=’0’) - The observation date
refdate (variant=’0’) - The reference date after which new database entries will be ignored.
hosts (stringVec=[’http://obs.vla.nrao.edu/calmodvla’]) - List of hostnames to use when querying the web service.

Description

This task retrieves VLA-specific calibrator information via a web service and writes this information as a component list so that it may be used by applications downstream.

One of either a calibrator name or direction may be specified. The names ‘3C48’, ‘3C138’, ‘3C147’, and ‘3C286’ are currently supported by the web service. A direction is specified as ‘FRAME LONGITUDE LATITUDE’, so for example “J2000 01:37:41.1 33.09.32” for 3C48. Latitude and longitude may be specified in their familiar sexigesimal forms, or as angular quantities which must include units (eg ‘33.15deg’). If a direction is specified, the web service will attempt to find a supported calibrator near (as defined by the web service) that position. If one cannot be found, the web server will return an error code and the task will throw an exception.

The observing band must be specified. For the VLA, supported bands are ‘P’. ‘L’, ‘S’, ‘C’, ‘X’, ‘U’, ‘K’, ‘A’, and ‘Q’.

The observation date must be specified as either an MJD (assumed if the value is a number) or a date of the form “YYYY-MM-DD” (assumed if the value is specified as a string).

A reference date may be specified. If so, the specification rules for the observation date also hold for this parameter, Specifying this parameter allows older versions of the data and/or algorithms to be retrieved, thus allowing historical reproducibility even after data and algorithms may have been updated. This input represents the latest date for which versioned data and algorithms should be used.

A prioritized list of servers may be specified in the hosts parameter. Each server is queried in turn until a successful response is received, in which case no more servers are queried, or the list is exhausted, in which case an exception is thrown. Note that this list is not strictly limited to domain names but can include paths as well. The portion of the URL constructed by the task from the input parameters is just the query string, so if a path precedes the query string, that can (and should) be included in the hosts parameter. For example, the default value is [’http://obs.vla.nrao.edu/calmodvla’], which includes the ‘calmodvla’ path that precedes the query string. The task constructs the query string and appends it to the host string, separating the two with a ‘?’. So, in this case, the URL that is queried is http://obs.vla.nrao.edu/calmodvla?[task-constructed-query-string].

If successful, the task will write a component list generated from the data returned by the web service which represents the brightness distribution for the specified calibrator for the specified band at the specified date (with the reference date applied if one is specified). This component list, being a CASA table, will include the table keyword “web_service”. The value of this keyword will be a dictionary containing the inputs specified in the task, the response of the web service (usually a very long JSON string), the URL that was used to make the query, and other possibly useful metadata.

Examples

# get the intensity distribution of 3C48 at Q band on MJD 55000
getcalmodevla(
    outfile='3C48.cl', source='3C48', band='Q', obsdate=55000,
    hosts=['http://some-host-that-works.nrao.edu']
)   

# the same thing, but do not use any data or algorithms that were
# created after MJD 56000
getcalmodevla(
    outfile='3C48.cl', source='3C48', band='Q', obsdate=55000,
    refdate=56000, hosts=['http://some-host-that-works.nrao.edu']
)   

# get the same information as the first query based on 3C48's direction,
# not its name
getcalmodevla(
    outfile='3C48.cl', direction='J2000 01h37m41.1s 33.155deg', band='Q',
    obsdate=55000, hosts=['http://some-host-that-works.nrao.edu']
)   

Development

Parameter Details: Detailed descriptions of each function parameter

outfile (path='') - The name of the output component list to be written. Must be specified

Default: none, must be specified

Example: outfile=”3c273.cl”

overwrite (bool=False) - Overwrite a file or directory of the same name of outfile if it exists. If overwrite=False and a file or directory of the same name as outfile exists, an exception will be thrown.

source (string='') - The calibrator name. The case-insensitive names

“3C48”, “3C286”, “3C138”,
and “3C147” are supported. Exactly one of source
or direction must be specified.

direction (string='') - An alternative to source. It is the direction of the calibrator. The supported

formats are of the form “EPOCH LONGITUDE LATITUDE”, eg

“J2000 12:34:56 -12.34.56”.
“J2000 19h53m50 40d06m00”
“B1950 292.5deg -40.0deg”
“ICRS 13:05:27.2780 -049.28.04.458”
“GALACTIC 47.5rad -60.22rad”
Only astronomical coordinate systems should be used; eg AZEL is right out. The web service
will attempt to locate a known calibrator near this direction, where “near” is defined by
the web service team. Exactly one of source or direction must be specified.

band (string='') - A string representing the case-insensitive code of

the band for which the data are required. For the VLA,

supported codes are “P”, “L”, “S”, “C”, “X”, “U”, “K”, “A”, and “Q”.

obsdate (variant='0') - The date for which to obtain the calibrator information. If numeric,

is assumed to be an MJD. If a string, is assumed to be a date and must

be of the form “YYYY-MM-DD”.

refdate (variant='0') - The reference date after which new database entries will be ignored. If numeric,

is assumed to be an MJD. If a string, is assumed to be a date and must
be of the form “YYYY-MM-DD”. Used to support
historical reproducibility. A non-positive value will result in this parameter being ignored,
and the most recent entry will be used (which may be later than obsdate).

hosts (stringVec=['http://obs.vla.nrao.edu/calmodvla']) - List of hostnames to use when querying the web service. They will be queried in

order until a successful response is received.