#
# stub function definition file for docstring parsing
#
[docs]def listobs(vis, selectdata=True, spw='', field='', antenna='', uvrange='', timerange='', correlation='', scan='', intent='', feed='', array='', observation='', verbose=True, listfile='', listunfl=False, cachesize=50, overwrite=False):
r"""
Get the summary of a MeasurementSet and list it in the logger or in a file
[`Description`_] [`Examples`_] [`Development`_] [`Details`_]
Parameters
- vis_ (path) - Name of input visibility file (MS)
- selectdata_ (bool=True) - Data selection parameters
.. raw:: html
<details><summary><i> selectdata = True </i></summary>
- field_ ({string, stringVec}='') - Selection based on field names or field index numbers. Default is all.
- spw_ ({string, stringVec}='') - Selection based on spectral-window/frequency/channel.
- antenna_ ({string, stringVec}='') - Selection based on antenna/baselines. Default is all.
- timerange_ ({string, stringVec}='') - Selection based on time range. Default is entire range.
- correlation_ ({string, stringVec}='') - Selection based on correlation. Default is all.
- scan_ ({string, stringVec}='') - Selection based on scan numbers. Default is all.
- intent_ ({string, stringVec}='') - Selection based on observation intent. Default is all.
- feed_ ({string, stringVec}='') - Selection based on multi-feed numbers: Not yet implemented
- array_ ({string, stringVec}='') - Selection based on (sub)array numbers. Default is all.
- uvrange_ ({string, stringVec}='') - Selection based on uv range. Default: entire range. Default units: meters.
- observation_ ({string, int}='') - Selection based on observation ID. Default is all.
.. raw:: html
</details>
- verbose_ (bool=True) - Controls level of information detail reported. True reports more than False.
- listfile_ (string='') - Name of disk file to write output. Default is none (output is written to logger only).
.. raw:: html
<details><summary><i> listfile != '' </i></summary>
- overwrite_ (bool=False) - If True, tacitly overwrite listfile if it exists.
.. raw:: html
</details>
- listunfl_ (bool=False) - List unflagged row counts? If true, it can have significant negative performance impact.
- cachesize_ (double=50) - EXPERIMENTAL. Maximum size in megabytes of cache in which data structures can be held.
.. _Returns:
Returns
obs (dict) - MeasurementSet metainformation, including per field
and per scan information
.. _Description:
Description
This task reports various metadata related to an MS. The listing is
sent to the logger or can be saved to a file. Standard MS selection
parameters can be used to limit the listing (see `Visibility Data
Selections
<../../notebooks/visibility_data_selection.ipynb>`__
for details). The task also returns a dictionary with the metadata;
see Examples for the content and structure of the dictionary. Note
that the dictionary does not include antenna related metadata, as
well as other details that are included in the output log or file,
when using verbose=True, such as the per-subscan integration
times. The report included in the dictionary is closer to the
information listed when using verbose=False.
The report begins with information such as the observer, the
project ID, the number of records, the length of the observation,
and minimum and maxiumum timestamp of the records included.
Following this are several tables summarizing metadata. There is a
table which summarizes scan data (only if verbose = True), a table
that summarizes field data, a table that summarizes spectral
window data, a table that summarizes source data (only if verbose
= True), and a table that summarizes antenna data. If verbose =
False, the antenna summary will only list antenna and station
names. If verbose = True, additional information such as the
diameter, latitude and longitude, position relative to the array
center, and the ITRF geocentric coordinates for each antenna will
be listed.
Should the MS have multiple array IDs and/or multiple observation
IDs, the report will list all of these tables for each array
ID/observation ID pair.
Note: The 'Average Interval (s)' column in the scan table is the
average of the MS's *INTERVAL* column for each scan.
Note: Time is provided in Modified Julian Date. The CASA/casacore reference epoch (0 time) for timestamps in MeasurementSets is always the MJD epoch (1858/11/17).
.. rubric:: Description of algorithm to calculate the number of unflagged rows
The number of unflagged rows is only computed and reported in the
scan and field table if *listunfl=True*. Computing these
quantities can have a negative performance impact, especially for
large datasets. The number of unflagged rows (the *nUnflRows*
columns in the scans and fields portions of the listing) is
calculated by summing the fractional unflagged bandwidth for each
row (and hence why the number of unflagged rows, in general, is
not an integer). Thus a row which has half of its total bandwidth
flagged contributes 0.5 rows to the unflagged row count. A row
with 20 of 32 channels of homogeneous width contributes 20/32 =
0.625 rows to the unflagged row count. A row with a value of False
in the *FLAG_ROW* column is not counted in the number of unflagged
rows.
**WARNING** *:* The *'listfile'* is adjusted for visual/manual inspection but not for precise programmatic use in scripts. Values in the listfile have been processed and formatted, and some of the original information has been lost and/or distorted. For this reason, if a user or script needs some particular values from the MS, those values should be taken form the dict rather than taking them manually (or loading them with a parser) from the text file. The dictionary values are floating point values in IEEE double precision (decimal) format, reflecting the real machine precision.
.. _Examples:
Examples
::
# generate standard listobs listing
listobs(vis="my.ms")
::
# generate listobs listing with more detail
listobs(vis="my.ms", verbose=True)
::
# save the listobs output into a text file
listobs(vis="my.ms", verbose=True, listfile="my.listobs.out")
::
# Get metadata and print it
metadata = listobs(vis="uid__X02_X3d737_X1_01_small.ms")
print(metadata)
::
{'BeginTime': 55248.126073333326, 'EndTime': 55248.130800000006, 'IntegrationTime': 408.38400173187256,
'field_0': {'code': 'none', 'direction': {'m0': {'unit': 'rad', 'value': 1.4433872913993107},
'm1': {'unit': 'rad', 'value': 0.2361430477948328},
'refer': 'J2000', 'type': 'direction'},
'name': 'J0530+135'},
'field_1': {'code': 'none',
'direction': {'m0': {'unit': 'rad', 'value': 0.0},
'm1': {'unit': 'rad', 'value': 0.0},
'refer': 'J2000', 'type': 'direction'},
'name': 'Mars'},
'nfields': 2, 'numrecords': 1080,
'scan_1': {'0': {'BeginTime': 55248.126073333326,
'EndTime': 55248.12846666667, 'FieldId': 0,
'FieldName': 'J0530+135', 'IntegrationTime': 3.0240000000000187,
'SpwIds': np.array([0, 1], dtype=np.int32),
'StateId': 0, 'nRow': 600, 'scanId': 1}},
'scan_2': {'0': {'BeginTime': 55248.12877055556, 'EndTime': 55248.13014111111,
'FieldId': 1, 'FieldName': 'Mars',
'IntegrationTime': 3.023999999999993,
'SpwIds': np.array([0, 1], dtype=np.int32),
'StateId': 5, 'nRow': 360, 'scanId': 2}}, 'timeref': 'UTC'}}
.. _Development:
Development
No additional development details
.. _Details:
Parameter Details
Detailed descriptions of each function parameter
.. _vis:
| ``vis (path)`` - Name of input visibility file (MS)
.. _selectdata:
| ``selectdata (bool=True)`` - Data selection parameters
.. _spw:
| ``spw ({string, stringVec}='')`` - Selection based on spectral-window/frequency/channel.
.. _field:
| ``field ({string, stringVec}='')`` - Selection based on field names or field index numbers. Default is all.
.. _antenna:
| ``antenna ({string, stringVec}='')`` - Selection based on antenna/baselines. Default is all.
.. _uvrange:
| ``uvrange ({string, stringVec}='')`` - Selection based on uv range. Default: entire range. Default units: meters.
.. _timerange:
| ``timerange ({string, stringVec}='')`` - Selection based on time range. Default is entire range.
.. _correlation:
| ``correlation ({string, stringVec}='')`` - Selection based on correlation. Default is all.
.. _scan:
| ``scan ({string, stringVec}='')`` - Selection based on scan numbers. Default is all.
.. _intent:
| ``intent ({string, stringVec}='')`` - Selection based on observation intent. Default is all.
.. _feed:
| ``feed ({string, stringVec}='')`` - Selection based on multi-feed numbers: Not yet implemented
.. _array:
| ``array ({string, stringVec}='')`` - Selection based on (sub)array numbers. Default is all.
.. _observation:
| ``observation ({string, int}='')`` - Selection based on observation ID. Default is all.
.. _verbose:
| ``verbose (bool=True)`` - Controls level of information detail reported. True reports more than False.
.. _listfile:
| ``listfile (string='')`` - Name of disk file to write output. Default is none (output is written to logger only).
.. _listunfl:
| ``listunfl (bool=False)`` - List unflagged row counts? If true, it can have significant negative performance impact.
.. _cachesize:
| ``cachesize (double=50)`` - EXPERIMENTAL. Maximum size in megabytes of cache in which data structures can be held.
.. _overwrite:
| ``overwrite (bool=False)`` - If True, tacitly overwrite listfile if it exists.
"""
pass