#
# stub function definition file for docstring parsing
#
[docs]def getcalmodvla(outfile='', overwrite=False, source='', direction='', band='', obsdate='0', refdate='0', hosts=['http://obs.vla.nrao.edu/calmodvla']):
r"""
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:
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:
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:
Development
.. _Details:
Parameter Details
Detailed descriptions of each function parameter
.. _outfile:
| ``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:
| ``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:
| ``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:
| ``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:
| ``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:
| ``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:
| ``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:
| ``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.
"""
pass