#
# stub function definition file for docstring parsing
#
[docs]def getantposalma(outfile='', overwrite=False, asdm='', tw='', snr='default', search='both_latest', hosts=['https://asa.alma.cl/uncertainties-service/uncertainties/versions/last/measurements/casa/'], firstintegration=True, nretry=0, rdelay=3.0):
r"""
Retrieve antenna positions by querying ALMA web service.
[`Description`_] [`Examples`_] [`Development`_] [`Details`_]
Parameters
- outfile_ (path='') - Name of output file to which to write retrieved antenna positions.
- overwrite_ (bool=False) - Overwrite a file by the same name if it exists?
- asdm_ (string='') - The associated ASDM UID.
- tw_ (string='') - Optional time window in which to consider baseline measurements in the database, when calculating the antenna positions.
- snr_ (variant='default') - Optional signal-to-noise. Must be either "default" or a non-negative number.
- search_ (string='both_latest') - Search algorithm to use.
- hosts_ (stringVec=['https://asa.alma.cl/uncertainties-service/uncertainties/versions/last/measurements/casa/']) - Priority-ranked list of hosts to query.
- firstintegration_ (bool=True) - If True, exclude the calibrations with the first integration flag to find the positions in the database
- nretry_ (int=0) - Number of times to retry after failure.
- rdelay_ (float=3.0) - Delay between retries (in seconds).
.. _Description:
Description
.. warning:: **WARNING**: This task should be considered experimental
since the values returned by the JAO service are in the process of
being validated.
This task retrieves ALMA antenna positions via a web service which runs
on an ALMA-hosted server. The antenna positions are with respect to ITRF.
The user must specify the value of the outfile parameter. This parameter
is the name of the file to which the antenna positions will be written.
This file can then be read by gencal so that it can use the most up to
date antenna positions for the observation.
The web service is described by the server development team and can be
found `at this location <https://asw.alma.cl/groups/ASW/-/packages/843>`__.
The input parameters are discussed in detail below.
outfile is required to be specified. It is the name of the file to which to
write antenna positions.
overwrite If False and a file with the same name exists, and exception
will be thrown. If true, an existing file with the same name will be
overwriten.
asdm is required to be specified. It is the associated ASDM UID in the
form uid://A002/Xc02418/X29c8.
tw is an optional parameter. It is time window in which the antenna positions
are required, specified as a comma separated pair. Times are UTC and are
expressed in YY-MM-DDThh:mm:ss.sss format. The end time must be later than
the begin time.
snr is an optional parameter. If changed from the default value "default",
it must be a nonnegative number representing the signal-to-noise ratio. Antenna
positions which have corrections less than this value will not be written.
Setting to 0 will result in all antenna positions being returned. If not
specified (ie if the parameter is set to the default value of "default"),
the default snr as defined by the web service will be used.
The server side default value may change over time as determined by the server
side (non-CASA) team. As of this writing (March 2025), the web service team has
not provided publicly facing documentation on the details of how the default
value is chosen. The most recent information they have provided to us is that
the default value is 5.0.
tw and search are optional parameters and are coupled as follows. search
indicates the search algorithm to use to find the desired antenna positions.
Supported values of this parameter at the time of writing are 'both_latest'
and 'both_closest'. The task passes the value of the search parameter verbatim to
the web service, meaning that users can take advantage of new search algorithms
as the web service team brings them online. The default algorithm used is
'both_latest'. In general, the search is limited in time to the specified
value of tw (time window). For 'both_latest', the last updated position for each
antenna within the specified time window, or, if tw is not specified, within
30 days after the observation will be returned, taking into account snr if
specified, if provided. For 'both_closest', if tw is not specified, the position
of each antenna closest in time to the observation, within 30 days (before
or after the observation) will be returned, subject to the value of snr if it
is specified.
hosts is a required parameter. It is a list of hosts to query, in order of
priority, to obtain positions. The first server to respond with a valid result is
the only one that is used. That response will be written and no additional
hosts will be queried.
firstintegration is an optional boolean parameter. If True, excludes measurements
flagged as “firstintegration”. If False, includes measurements flagged as
“firstintegration”. The default value is True.
nretry is an optional parameter. It is the number of times to retry a query. For
each retry, all the hosts are retried. This continues until either a valid result
is obtained or the number of retries is exhausted. The parameter must be nonnegative.
rdelay is used only if nretry is greater than zero. It is the delay, in seconds,
between retries. It must be a positive number. If it is less than 0.5, it is set
to 0.5 internally to acoid DoS attacks on the servers.
The format of the returned file is a two element dictionary encoded in json. The
two keys of this dictionary are "data" and "metadata". The value associated with
the "data" key is a dictionary that contains antenna names as keys, with each
value being a three element list of x, y, and z ITRF coordinates. The value
associated with the "metadata" key is a dictionary containing various, possibly
useful metadata that describe the task and/or were used when the task was run. The
following code may be used to load these data structures into python variables.
::
import ast, json
...
with open("outfile.json", "r") as f:
res_dict = json.load(f)
antpos_dict = res_dict["data"]
metadata_dict = res_dict["metadata"]
The metadata dictionary will include a "product_code" key which will have the
value "antposalma" to indicate the type of data product contained in the file.
.. _Examples:
Examples
Get antenna positions which have positions with a signal-to-noise ratio
greater than 5.
::
getantposalma(
outfile='my_ant_pos.json', asdm='valid ASDM name here', snr=5,
hosts=['tbd1.alma.cl', 'tbd2.alma.cl'], firstintegration=True
)
.. _Development:
Development
No additional development details
.. _Details:
Parameter Details
Detailed descriptions of each function parameter
.. _outfile:
| ``outfile (path='')`` - Name of output file to which to write antenna positions. If a file by this name already exists, it will be silently overwritten. The written file will be in JSON format.
| default: none
| Example: outfile='my_alma_antenna_positions.json'
.. _overwrite:
| ``overwrite (bool=False)`` - Overwrite a file by the same name if it exists? If False and a file
| with the same name exists, and exception will be thrown.
.. _asdm:
| ``asdm (string='')`` - The associated ASDM UID. The ASDM is not required to be on the file system; this value is simply passed to the web service.
| default: ''
| Example:asdm='uid://A002/X10ac6bc/X896d'
.. _tw:
| ``tw (string='')`` - Optional time window in which to consider baseline measurements in the database, when calculating the antenna positions. Format is of the form begin_time,end_time, where times must be specified in YYYY-MM-DDThh:mm:ss.sss format and end_time must be later than begin time. Times should be UTC.
| Example: tw='2023-03-14T00:40:20,2023-03-20T17:58:20'
.. _snr:
| ``snr (variant='default')`` - Optional signal-to-noise. Must be either "default" or a non-negative number. Antenna positions which have corrections with S/N less than this value will not be retrieved nor written. If not specified, the default value used by the web service will be used, and that may change over time.
| default: "default" (the current default value as defined by the web service will be used)
| Example: snr=5.0
.. _search:
| ``search (string='both_latest')`` - Search algorithm to use. Supported values are "both_latest" and "both_closest". For "both_latest", the last updated position for each antenna within 30 days after the observation will be returned, taking into account snr if specified. If provided, tw will override the 30 day default value. For "both_closest", the position of each antenna closest in time to the observation, within 30 days (before or after the observation) will be returned, subject to the value of snr if it is specified. If specified, the value of tw will override the default 30 days. The default algorithm to use will be "both_latest".
| Example: search="both_closest"
.. _hosts:
| ``hosts (stringVec=['https://asa.alma.cl/uncertainties-service/uncertainties/versions/last/measurements/casa/'])`` - Priority-ranked list of hosts to query to obtain positions. Only one server that returns a list of antenna positions is required. That response will be written and no additional hosts will be queried.
| Example: hosts=["server1.alma.cl", "server2.alma.cl"]
.. _firstintegration:
| ``firstintegration (bool=True)`` - If True, the first integration calibrations in the database are excluded from the analysis to estimate the antenna positions. If False, the first integration calibrations are used to estimate the antenna positions.
.. _nretry:
| ``nretry (int=0)`` - Number of times to retry query upon failure. All servers are requeried during each retry until a query is successful or the number of retries is reached. Must be nonnegative. 0 means do not retry.
.. _rdelay:
| ``rdelay (float=3.0)`` - Delay between retries (in seconds). All servers will be retried after this delay until a query is successful or the specified number of retries has been reached. Must be positive. For values less than 0.5, the value is automatically set to 0.5 to avoid DoS attacks.
"""
pass