Commits

David Mehringer authored 8bee9ba3c37
new doc updates
No tags

casatasks/src/private/task_getantposalma.py

Modified
39 39 hosts=['tbd1.alma.cl', 'tbd2.alma.cl']
40 40 ):
41 41 r"""
42 42 Retrieve antenna positions by querying ALMA web service.
43 43
44 44 [`Description`_] [`Examples`_] [`Development`_] [`Details`_]
45 45
46 46
47 47 Parameters
48 48 - outfile_ (path='') - Name of output file to which to write retrieved antenna positions.
49 + - overwrite_ (bool=False) - Overwrite a file by the same name if it exists?
49 50 - asdm_ (string='') - The associated ASDM name. Must be specified
50 - - tw_ (string='') - Optional time window to which to limit search for antenna positions.
51 + - tw_ (string='') - Optional time window in which to consider baseline measurements in the database, when calculating the antenna positions.
51 52 - snr_ (float=0) - Optional signal-to-noise.
52 53 - search_ (string='both_latest') - Search algorithm to use.
53 - - hosts_ (stringVec=['tbd1.alma.cl', 'tbd2.alma.cl']) - Priority-ranked list of hosts to query.
54 + - hosts_ (stringVec=['https://asa.alma.cl/uncertainties-service/uncertainties/versions/last/measurements/casa/']) - Priority-ranked list of hosts to query.
54 55
55 56
56 57
57 58
58 59 .. _Description:
59 60
60 61 Description
61 -Antpos retrieves ALMA antenna positions via a web service which runs on an
62 -ALMA-hosted server. The antenna positions are with respect to ITRF. The
63 -user must specify the value of the outfile parameter. This parameter is
64 -the name of the file to which the antenna positions will be written. This
65 -file can then be read by gencal so that it can use the most up to date
66 -antenna positions for the observation.
62 +
63 +.. warning:: **WARNING**: This task should be considered experimental
64 + since the values returned by the JAO service are in the process of
65 + being validated.
66 +
67 +This task retrieves ALMA antenna positions via a web service which runs
68 +on an ALMA-hosted server. The antenna positions are with respect to ITRF.
69 +The user must specify the value of the outfile parameter. This parameter
70 +is the name of the file to which the antenna positions will be written.
71 +This file can then be read by gencal so that it can use the most up to
72 +date antenna positions for the observation.
73 +
74 +The web service is described by the server development team and can be
75 +found `at this location <https://asw.alma.cl/groups/ASW/-/packages/843>`__.
67 76
68 77 The input parameters are discussed in detail below.
69 78
70 79 outfile is required to be specified. It is the name of the file to which to
71 -write antenna positions. If a file with the same name exists it will be
72 -silently overwritten.
80 +write antenna positions.
81 +
82 +overwrite If False and a file with the same name exists, and exception
83 +will be thrown. If true, an existing file with the same name will be
84 +overwriten.
85 +
86 +asdm is required to be specified. It is the associated ASDM UID in the
87 +form uid://A002/Xc02418/X29c8.
73 88
74 -asdm is required to be specified. It is the associated ASDM name.
75 89 tw is an optional parameter. It is time window in which the antenna positions
76 90 are required, specified as a comma separated pair. Times are UTC and are
77 91 expressed in YY-MM-DDThh:mm:ss.sss format. The end time must be later than
78 92 the begin time.
79 93
80 94 snr is an optional parameter. It is the signal-to-noise ratio. Antenna
81 95 positions which have corrections less than this value will not be written.
82 96 If not specified, positions of all antennas will be written.
83 97
84 -search is an optional parameter, It is the search algorithm to use.
85 -Supported values are 'both_latest' and 'both_closest'. For 'both_latest',
86 -the last updated position for each antenna within 30 days after the
87 -observation will be returned, taking into account snr if specified. If provided,
88 -
89 -tw will override the 30 day default value. For 'both_closest', the position
98 +tw and search are optional parameters and are coupled as follows. search
99 +indicates the search algorithm to use to find the desired antenna positions.
100 +Supported values of this parameter at the time of writing are 'both_latest'
101 +and 'both_closest'. The task passes the value of the search parameter verbatim to
102 +the web service, meaning that users can take advantage of new search algorithms
103 +as the web service team brings them online. The default algorithm used is
104 +'both_latest'. In general, the search is limited in time to the specified
105 +value of tw (time window). However, in the case that tw is not specified, the
106 +following rules apply. For 'both_latest', the last updated position for each
107 +antenna within the specified time window, or, if tw is not specified, within
108 +30 days after the observation will be returned, taking into account snr if
109 +specified, if provided.
110 +
111 +For 'both_closest', if tw is not specified, the position
90 112 of each antenna closest in time to the observation, within 30 days (before
91 -or after the observation will be returned, subject to the value of snr if it
92 -is specified. If specified, the value of tw will override the default 30 days.
93 -The default algorithm used is 'both_latest'.
113 +or after the observation) will be returned, subject to the value of snr if it
114 +is specified.
94 115
95 -hostss is a required parameter. It is a list of hosts to query, in order of
116 +hosts is a required parameter. It is a list of hosts to query, in order of
96 117 priority, to obtain positions. The first server to respond with a valid result is
97 118 the only one that is used. That response will be written and no additional
98 -hostss will be queried.
119 +hosts will be queried.
120 +
121 +The format of the returned file is a two element list encoded in json. The first
122 +element is a stringfied dictionary that contains antenna names as keys, with each
123 +value being a three element list of x, y, and z coordinates in ITRF. The second
124 +element is a dictionary containing various (possibly helpful) metadata that were
125 +used when the task was run. The following code may be used to load these data
126 +structures into python variables.
127 +
128 + ::
129 +
130 + import ast, json
131 + ...
132 + with open("outfile.json", "r") as f:
133 + antpos_str, md_dict = json.load(f)
134 + antpos_dict = ast.literal_eval(antpos_str)
99 135
100 136
101 137 .. _Examples:
102 138
103 139 Examples
104 140 Get antenna positions which have positions with a signal-to-noise ratio
105 141 greater than 5.
106 142
107 143 ::
108 144
109 - antpos(
145 + getantposalma(
110 146 outfile='my_ant_pos.json', asdm='valid ASDM name here', snr=5,
111 147 hosts=['tbd1.alma.cl', 'tbd2.alma.cl']
112 148 )
113 149
114 150
115 151 .. _Development:
116 152
117 153 Development
118 154 No additional development details
119 155
125 161
126 162 Parameter Details
127 163 Detailed descriptions of each function parameter
128 164
129 165 .. _outfile:
130 166
131 167 | ``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.
132 168 | default: none
133 169 | Example: outfile='my_alma_antenna_positions.json'
134 170
171 +.. _overwrite:
172 +
173 +| ``overwrite (bool=False)`` - Overwrite a file by the same name if it exists? If False and a file
174 +| with the same name exists, and exception will be thrown.
175 +
135 176 .. _asdm:
136 177
137 -| ``asdm (string='')`` - The associated ASDM name. Must be specified
178 +| ``asdm (string='')`` - The associated ASDM name. Must be specified. The ASDM is not required to be on the file system; its value is simply passed to the web service.
138 179 | default: ''
139 -| Example:asdm='uid___A002_X10ac6bc_X896d
180 +| Example:asdm='uid://A002/X10ac6bc/X896d'
140 181
141 182 .. _tw:
142 183
143 -| ``tw (string='')`` - Optional time window to which to limit search for 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.
184 +| ``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.
144 185 | Example: tw='2023-03-14T00:40:20,2023-03-20T17:58:20'
145 186
146 187 .. _snr:
147 188
148 189 | ``snr (float=0)`` - Optional signal-to-noise. Antenna positions which have corrections with S/N less than this value will not be retrieved nor written. If not specified, positions of all antennas will be written.
149 190 | default: 0 (no snr constraint will be used)
150 191 | Example: snr=5.0
151 192
152 193 .. _search:
153 194
154 195 | ``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".
155 196 | Example: search="both_closest"
156 197
157 198 .. _hosts:
158 199
159 -| ``hosts (stringVec=['tbd1.alma.cl', 'tbd2.alma.cl'])`` - 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.
200 +| ``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.
160 201 | Example: hosts=["server1.alma.cl", "server2.alma.cl"]
161 202
162 203
163 204 """
164 205 if not outfile:
165 206 raise ValueError("Parameter outfile must be specified")
166 207 md = {"outfile": outfile}
167 208 if not overwrite and os.path.exists(outfile):
168 209 raise RuntimeError(
169 210 f"A file or directory named {outfile} already exists and overwrite "

Everything looks good. We'll let you know here if there's anything you should know about.

Add shortcut