Coverage for /wheeldirectory/casa-6.7.0-12-py3.10.el8/lib/py/lib/python3.10/site-packages/casatasks/sdcal.py: 56%
27 statements
« prev ^ index » next coverage.py v7.6.4, created at 2024-10-31 17:39 +0000
1##################### generated by xml-casa (v2) from sdcal.xml #####################
2##################### 29a5e4b9883214251585a252bf79c0b8 ##############################
3from __future__ import absolute_import
4import numpy
5from casatools.typecheck import CasaValidator as _val_ctor
6_pc = _val_ctor( )
7from casatools.coercetype import coerce as _coerce
8from casatools.errors import create_error_string
9from .private.task_sdcal import sdcal as _sdcal_t
10from casatasks.private.task_logging import start_log as _start_log
11from casatasks.private.task_logging import end_log as _end_log
12from casatasks.private.task_logging import except_log as _except_log
14class _sdcal:
15 """
16 sdcal ---- MS SD calibration task
19 Task sdcal implements a single-dish data calibration scheme similar to that of
20 interferometry, i.e., generate calibration tables (caltables) and apply them.
21 Available calibration modes are:
22 'ps', 'otfraster', 'otf' for sky calibration
23 'tsys' for Tsys calibration
24 Each mode generates a caltable.
25 Caltables can be applied to the data by combining calibration
26 modes with the keyword 'apply'.
28 Calibration is applicable for fast moving source even like the moon which moves
29 quickly outside of the field of view (see the note of 'otf' mode in below).
31 Calibration mode must be set in accordance with the observing mode
32 of the data. Use case for each mode is as follows:
33 'ps': position switch (including OTF) with explicit
34 reference (OFF) spectra
35 'otfraster': raster OTF scan without explicit OFFs
36 'otf': non-raster OTF (e.g. double-circle) scan without explicit OFFs
38 So, if the data contains explicit reference spectra, 'ps' should
39 be used. Otherwise, 'otfraster' or 'otf' should be used.
40 In 'otfraster' and 'otf' modes, an edge marker automatically marks spectra from
41 specific regions of the observation pattern as reference (OFF) spectra.
42 These specific regions are:
43 - in 'otfraster' mode: regions near the beginning and the end of the raster
44 scan lines.
45 - in 'otf' mode: regions near the periphery of the observation pattern.
46 Note: The 'otfraster' mode is designed for OTF observations without explicit OFF
47 spectra. However, it should work even if explicit reference spectra exist.
48 In that case, these spectra are ignored and spectra marked by edge marker are
49 used as reference.
50 Note: Detection of periphery scans in 'otf' mode is available for fast moving
51 sources, e.g., Sun, Moon. It is often the case antennas keep track of source motion
52 during the observations of moving sources so that the source is always at the map center.
53 In order to handle such observations, pheriphery search is done in the source frame
54 for known moving sources, in which the source is always at a rest position.
56 Apart from the way reference spectra are selected, the procedure to derive
57 calibrated spectra is the same for all modes. Selected (or preset)
58 OFF integrations are separated based on continuity in time domain,
59 averaged in each segment, and then interpolated to timestamps for ON
60 integrations. Effectively, it means that OFF integrations are
61 averaged by each OFF spectrum for 'ps' mode, averaged by either ends
62 of each raster row for 'otfraster' mode. The formula for calibrated
63 spectrum is
65 Tsys * (ON - OFF) / OFF.
69 --------- parameter descriptions ---------------------------------------------
71 infile name of input SD dataset (must be MS)
72 calmode SD calibration mode
73 fraction fraction of the OFF data to mark
74 noff number of the OFF data to mark
75 width width of the pixel for edge detection
76 elongated whether observed area is elongated in one direction or not
77 applytable (List of) sky and/or tsys tables
78 interp Interpolation type in time[,freq]. Valid options for time are "nearest", "linear", and "cubic", while valid options for frequency include "nearest", "linear", "cspline", or any numeric string that indicates an order of polynomial interpolation. You can specify interpolation type for time and frequency separately by joining two of the above options by comma (e.g., "linear,cspline").
79 spwmap A dictionary indicating spw combinations to apply Tsys calibration to target. The key should be spw for Tsys calibration and its associated value must be a list of science spws to be applied.
80 outfile name of output file (See a WARNING in help)
81 overwrite overwrite the output file if already exists
82 field select data by field IDs and names, e.g. "3C2*" ("" = all)
83 spw select data by spw IDs (spectral windows), e.g., "3,5,7" ("" = all)
84 scan select data by scan numbers, e.g. "21~23" (""=all)
85 intent select data by observation intent, e.g. "OBSERVE_TARGET#ON_SOURCE" (""=all)
86 [1;42mRETURNS[1;m void
88 --------- examples -----------------------------------------------------------
91 Keyword arguments:
92 infile -- Name of input SD dataset
93 calmode -- Calibration mode. If you want to generate calibration table
94 or apply existing calibration tables, set calmode to a simple
95 string. If you want to calibrate data on-the-fly, set calmode
96 to a composite (comma-separated) string. So far, sky calibration has
97 three types, 'ps', 'otfraster' and 'otf'. If observation is
98 configured to observe reference position, calmode must be
99 'ps'. Otherwise, 'otfraster' or 'otf' should be used.
100 options: 'ps','otfraster','otf','tsys','apply'
101 default: 'ps'
102 example: Here is an example for composite calmode.
103 'ps,apply' (do sky cal and apply)
104 'ps,tsys,apply' (do sky and Tsys cal and apply)
105 >>> calmode expandable parameter
106 fraction -- Edge marker parameter of 'otfraster'.
107 Specify a number of OFF integrations (at each
108 side of the raster rows in 'otfraster' mode)
109 as a fraction of total number of integrations.
110 In 'otfraster' mode, number of integrations
111 to be marked as OFF, n_off, is determined by
112 the following formula,
114 n_off = floor(fraction * n),
116 where n is number of integrations per raster
117 row. Note that n_off from both sides will be
118 marked as OFF so that twice of specified
119 fraction will be marked at most. For example,
120 if you specify fraction='10%', resultant
121 fraction of OFF integrations will be 20% at
122 most.
123 default: '10%'
124 options: '20%' in string style or float value less
125 than 1.0 (e.g. 0.15).
126 'auto' is available only for 'otfraster'.
127 noff -- Edge marking parameter for 'otfraster'.
128 It is used to specify a number of OFF spectra near
129 edge directly. Value of noff comes before setting
130 by fraction. Note that n_off from both sides will
131 be marked as OFF so that twice of specified noff
132 will be marked at most.
133 default: -1 (use fraction)
134 options: any positive integer
136 applytable -- List of sky/Tsys calibration tables you want to
137 apply.
138 default: ''
139 interp -- Interpolation method in time and frequency axis.
140 Set comma separated method strings if you want
141 to use different interpolation in time and
142 frequency.
143 options: 'linear', 'nearest', 'cspline', 'cubic',
144 any numeric string indicating an order
145 of polynomial.
146 Note that 'cubic' is available for time only,
147 and that 'cspline' and numeric strings are
148 available for frequency only.
149 default: '' (linear in time and frequency)
150 example: 'linear,cspline' (linear in time, cubic
151 spline in frequency)
152 'linear,3' (linear in time, third order
153 polynomial in frequency)
154 'nearest' (nearest in time and frequency)
155 spwmap -- Dictionary defining transfer of Tsys calibration.
156 Key must be spw for Tsys and its value must be
157 a list of spws for science target.
158 default: {}
159 example: {1: [5,6], 3: [7,8]}
160 Tsys in spw 1 is transferred to spws 5 and 6
161 while Tsys in spw 3 is to spws 7 and 8.
162 field -- select data by field IDs and names
163 default: '' (use all fields)
164 example: field='3C2*' (all names starting with 3C2)
165 field='0,4,5~7' (field IDs 0,4,5,6,7)
166 field='0,3C273' (field ID 0 or field named 3C273)
167 this selection is in addition to the other selections to data
168 spw -- select data by spw IDs (spectral windows)
169 NOTE this task only supports spw ID selction and ignores channel
170 selection.
171 default: '' (use all spws and channels)
172 example: spw='3,5,7' (spw IDs 3,5,7; all channels)
173 spw='<2' (spw IDs less than 2, i.e., 0,1; all channels)
174 spw='30~45GHz' (spw IDs with the center frequencies in range 30-45GHz; all channels)
175 this selection is in addition to the other selections to data
176 NOTE spw input must be '' (''= all) in calmode='tsys'.
177 scan -- select data by scan numbers
178 default: '' (use all scans)
179 example: scan='21~23' (scan IDs 21,22,23)
180 this selection is in addition to the other selections to data
181 NOTE scan input must be '' (''= all) in calmode='tsys'.
182 outfile -- Name of output file
183 NOTE if you omit and calmode doesn't include 'apply', the task
184 will use default outfile name based on infile and predefined
185 suffix ('_sky' for sky, '_tsys' for Tsys).
186 default: '' (<infile>_<suffix> for calibration)
187 overwrite -- overwrite the output file if already exists
188 options: (bool) True,False
189 default: False
190 NOTE this parameter is ignored when outform='ASCII'
193 DESCRIPTION:
195 Task sdcal is an implementation of a calibration scheme like as
196 interferometry, i.e., generate caltables and apply them. Available
197 calibration modes are 'ps', 'otfraster', 'otf', and 'tsys'.
198 Those modes generates caltables for sky or Tsys calibration.
199 The caltables can be applied to the data by using calmode 'apply'.
201 First three calibration modes, 'ps', 'otfraster', and 'otf',
202 generate sky calibration tables. The user should choose appropriate
203 calibration mode depending on the data. Use case for each mode is
204 as follows:
206 'ps': position switch (including OTF) with explicit
207 reference (OFF) spectra
208 'otfraster': raster OTF scan without explicit OFFs
209 'otf': fast-scan observation with Lissajous or
210 double-circle trajectory
212 So, if the data contains explicit reference spectra, 'ps' should
213 be used. The 'otfraster' mode is appropriate for raster OTF.
214 For non-raster OTF data, 'otf' mode is available to support fast-
215 scanning observation. In 'otfraster' mode, the task first try to
216 find several integrations near edge as OFF spectra, then the data
217 are calibrated using those OFFs. If the observing pattern is raster,
218 you should use the 'otfraster' mode to calibrate data.
219 The 'otfraster' mode is designed for OTF observations without
220 explicit OFF spectra. However, these modes should work even if
221 explicit reference spectra exist. In this case, these spectra will be
222 ignored and spectra near edges detected by edge marker will be used as
223 reference. In 'otf' mode, the task detects integrations near edges of
224 observed area, and detected integrations are regarded as OFFs.
225 This mode is specifically designed for fast-scan mode, which takes
226 the data contiguously by moving antenna along trajectory that
227 imitates random spatial data sampling, which is implemented as
228 either Lissajous or double-circle pattern.
231 Except for how to choose OFFs, the procedure to derive calibrated
232 spectra is common for the above three modes. Selected (or preset) OFF
233 integrations are separated by its continuity in time domain, averaged in
234 each segment, then interpolated to timestamps for ON integrations.
235 Effectively, it means that OFF integrations are averaged by each
236 OFF spectrum for 'ps' mode, averaged by either ends of each raster
237 row for 'otfraster' mode. The formula for calibrated spectrum
238 is
240 Tsys * (ON - OFF) / OFF.
242 You can calibrate data on-the-fly like sdcal task by setting
243 calmode to a composite calmode string separated by comma.
244 For example, calmode='ps,apply' means doing sky calibration and
245 apply it on-the-fly. In this case, caltable is generated as a
246 temporary plain table and will be deleted at the end.
247 Allowed calibration modes in this task is as follows:
249 ps
250 generate sky caltable using 'ps' mode
251 otfraster
252 generate sky caltable using 'otfraster' mode
253 otf
254 generate sky caltable using 'otf' mode
255 tsys
256 generate tsys caltable
257 apply
258 apply caltables specified by applytable parameter
259 ps,apply
260 generate temporary sky caltable using 'ps' mode and
261 apply it. also apply caltables specified by applytable
262 ps,tsys,apply
263 generate temporary sky caltable using 'ps' mode as well
264 as temporary tsys caltable, and apply them.
265 otfraster,apply
266 generate temporary sky caltable using 'otfraster' mode
267 and apply it. also apply caltables specified by applytable
268 otfraster,tsys,apply
269 generate temporary sky caltable using 'otfraster' mode
270 as well as temporary tsys caltable, and apply them.
271 otf,apply
272 generate temporary sky caltable using 'otf' mode
273 and apply it. also apply caltables specified by applytable
274 otf,tsys,apply
275 generate temporary sky caltable using 'otf' mode
276 as well as temporary tsys caltable, and apply them.
278 There are several control parameters for sky/Tsys calibration and
279 application of caltables. See the above parameter description.
281 In ALMA, Tsys measurement is usually done using different spectral
282 setup from spectral windows for science target. In this case, sdcal
283 transfers Tsys values to science spectral windows in the application
284 stage. To do that, the user has to give a list of spectral windows for
285 Tsys measurement as well as mapping between spectral windows for Tsys
286 measurement and scicence target. These can be specified by parameters
287 'tsysspw' and 'spwmap', which are defined as subparameters of 'calmode'.
288 For example, suppose that Tsys measurements for science windows 17, 19,
289 21, and 23 are done in spw 9, 11, 13, and 15, respectively.
290 In this case, tsysspw and spwmap should be specified as follows:
292 tsysspw = '9,11,13,15'
293 spwmap = {9:[17],11:[19],13:[21],15:[23]}
295 Below is an example of full specification of task parameters for calmode
296 of 'ps,tsys,apply':
298 default(sdcal)
299 infile = 'foo.ms'
300 calmode = 'ps,tsys,apply'
301 spw = ''
302 tsysspw = '9,11,13,15'
303 spwmap = {9:[17],11:[19],13:[21],15:[23]}
304 sdcal()
306 Note that, in contrast to applycal task, spwmap must be a dictionary
307 with Tsys spectral window as key and a list of corresponding science
308 spectral window as value. Note also that the parameter 'spw' should
309 not be used to specify a list of spectral windows for Tsys measurement.
310 It is intended to select data to be calibrated so that the list should
311 contain spectral windows for both science target and Tsys measurement.
312 The task will fail if you use 'spw' instead of 'tsysspw'.
315 For Tsys calibration, the user is able to choose whether Tsys is
316 averaged in spectral axis or not. If tsysavg is False (default),
317 resulting Tsys is spectral value. On the other hand, when tsysavg
318 is True, Tsys is averaged in spectral axis before output. The channel
319 range for averaging is whole channels by default. If channel range is
320 specified by tsysspw string, it is used for averaging. The user can
321 specify channel range with ms selection syntax. For example,
323 tsysspw = '1:0~100'
325 specifies spw 1 for Tsys calibration and channel range between channel
326 0 and 100 for averaging. You can specify more than one ranges per spw.
328 tsysspw = '1:0~100;200~400'
330 In this case, selected ranges are between 0 and 100 plus 200 and 400.
331 Note that even if multiple ranges are selected, the task average whole
332 ranges together and output single averaged value. You can specify multiple
333 spws by separating comma.
335 tsysspw = '1:0~100,3:400~500'
336 Note that specified channel range is ignored if tsysavg is False.
340 """
342 _info_group_ = """single dish"""
343 _info_desc_ = """ MS SD calibration task"""
345 def __call__( self, infile='', calmode='ps', fraction='10%', noff=int(-1), width=float(0.5), elongated=False, applytable='', interp='', spwmap={ }, outfile='', overwrite=False, field='', spw='', scan='', **kwargs ):
346 schema = {'infile': {'type': 'cReqPath', 'coerce': _coerce.expand_path}, 'calmode': {'type': 'cStr', 'coerce': _coerce.to_str, 'allowed': [ 'apply', 'ps,apply', 'otf,apply', 'ps,tsys,apply', 'tsys,apply', 'tsys', 'otf,tsys,apply', 'otf', 'otfraster', 'otfraster,tsys,apply', 'ps', 'otfraster,apply' ]}, 'fraction': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'noff': {'type': 'cInt'}, 'width': {'type': 'cFloat', 'coerce': _coerce.to_float}, 'elongated': {'type': 'cBool'}, 'applytable': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'interp': {'type': 'cStr', 'coerce': _coerce.to_str}, 'spwmap': {'type': 'cVariant', 'coerce': [_coerce.to_variant]}, 'outfile': {'type': 'cStr', 'coerce': _coerce.to_str}, 'overwrite': {'type': 'cBool'}, 'field': {'type': 'cStr', 'coerce': _coerce.to_str}, 'spw': {'type': 'cStr', 'coerce': _coerce.to_str}, 'scan': {'type': 'cStr', 'coerce': _coerce.to_str}, 'intent': {'type': 'cStr', 'coerce': _coerce.to_str}}
347 doc = dict( {'infile': infile, 'calmode': calmode, 'fraction': fraction, 'noff': noff, 'width': width, 'elongated': elongated, 'applytable': applytable, 'interp': interp, 'spwmap': spwmap, 'outfile': outfile, 'overwrite': overwrite, 'field': field, 'spw': spw, 'scan': scan}, **kwargs)
348 assert _pc.validate(doc,schema), create_error_string(_pc.errors)
349 _logging_state_ = _start_log( 'sdcal', [ 'infile=' + repr(_pc.document['infile']), 'calmode=' + repr(_pc.document['calmode']), 'fraction=' + repr(_pc.document['fraction']), 'noff=' + repr(_pc.document['noff']), 'width=' + repr(_pc.document['width']), 'elongated=' + repr(_pc.document['elongated']), 'applytable=' + repr(_pc.document['applytable']), 'interp=' + repr(_pc.document['interp']), 'spwmap=' + repr(_pc.document['spwmap']), 'outfile=' + repr(_pc.document['outfile']), 'overwrite=' + repr(_pc.document['overwrite']), 'field=' + repr(_pc.document['field']), 'spw=' + repr(_pc.document['spw']), 'scan=' + repr(_pc.document['scan']), '**kwargs=' + repr(kwargs) ] )
350 task_result = None
351 try:
352 task_result = _sdcal_t( _pc.document['infile'], _pc.document['calmode'], _pc.document['fraction'], _pc.document['noff'], _pc.document['width'], _pc.document['elongated'], _pc.document['applytable'], _pc.document['interp'], _pc.document['spwmap'], _pc.document['outfile'], _pc.document['overwrite'], _pc.document['field'], _pc.document['spw'], _pc.document['scan'], **kwargs )
353 except Exception as exc:
354 _except_log('sdcal', exc)
355 raise
356 finally:
357 task_result = _end_log( _logging_state_, 'sdcal', task_result )
358 return task_result
360sdcal = _sdcal( )