#
# 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 for an EB by querying ALMA Antenna Position web service.
[`Description`_] [`Examples`_] [`Development`_] [`Details`_]
Parameters
- outfile_ (path='') - Name of output file to which to write retrieved antenna positions. Required.
- overwrite_ (bool=False) - When True, overwrite the outfile if it exists.
- asdm_ (string='') - The associated ASDM UID. Required.
- tw_ (string='') - The time window to search the positions. By default this is 30 days before and after the observation date.
- snr_ (variant='default') - The signal-to-noise to filter the positions. Must be either "default" or a non-negative number. Default is set by the web service and is currently 5.
- search_ (string='both_latest') - The search algorithm to use. Options are "both_latest", "both_closest", and "auto".
- 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 positions 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
This task retrieves the antenna positions for an ALMA Execution Block
via the web service Antenna Position Endpoint in the Uncertainties
database (\https://asa.alma.cl/uncertainties-service/uncertainties/versions/last/measurements/casa/),
which runs on an ALMA JAO hosted server. For a basic
run, the user must specify the outfile and the asdm, using the default
values for the other parameters. The antenna positions stored in the output
file can then be read by gencal so that the data reduction of the observation
can use the most up to date antenna positions. The web service is
described in a document that can be found
`here <https://confluence.alma.cl/spaces/PD/pages/285805344/Antenna+Positions+Uncertainties+Public+Docs>`__
(ALMA Antenna Positions Endpoint). That document gives the full set of available search options, including the meaning of "auto", as well
as the current default "snr" value used when not explicitly given to this task.
The input parameters are discussed in detail below. Additional details on how each parameter is used
by the web service can be found in the ALMA Antenna Positions Endpoint document linked above.
Specific behavior is set by the web service and not implemented by this task.
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,
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 an exception will be thrown unless the overwrite parameter is False. The written file will be in JSON format. A non-empty value is required.
| default: none
| Example: outfile='my_alma_antenna_positions.json'
.. _overwrite:
| ``overwrite (bool=False)`` - If outfile already exists and overwrite is True then that file will be overwritten. If False and a file
| with the same name exists an 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: ''. A non-empty string value is required.
| Example:asdm='uid://A002/X10ac6bc/X896d'
.. _tw:
| ``tw (string='')`` - The 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. The end time must be later than the begin time. The default value when not supplied is 30 days before and after the observation date.
| Example: tw='2023-03-14T00:40:20,2023-03-20T17:58:20'
.. _snr:
| ``snr (variant='default')`` - The signal-to-noise to filter the positions. 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. Setting this to 0 will result in all antenna positions being returned. If not specified, the default value of the web service is used. The current default value is 5 but that value may be changed at any time by the web service. See the documentation for the web service at the link in the Description for more details.
| default: "default" (the current default value of the web service will be used, currently that value is 5)
| Example: snr=5.0
.. _search:
| ``search (string='both_latest')`` - The search algorithm to use. Supported values are "both_latest", "both_closest", and "auto". The task passes this value 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 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. For "both_closest", the position of each antenna closest in time to the observation, within the time window or within 30 days before or after the observation if tw is not specified, will be returned, subject to the value of snr if it is specified. The exact meaning of "auto" is set by the web service, see the link the Description for the current specifics. At the time this documentation was produced "auto" uses "both_latest" for observations before Cycle 9 and "both_closest" for observations from Cycle 9 onward.
| 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. Hosts are queried in the order given. The first host that responds with a valid result is used. No additional hosts are queried after a valid result is returned. Note that this is the full URL to the web service to use, not simply a hostname.
.. _firstintegration:
| ``firstintegration (bool=True)`` - If True, the first integration positions in the database are excluded from the analysis to estimate the antenna positions. If False, the first integration positions are used to estimate the antenna positions. Default value is True.
.. _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