listobs

listobs(vis, selectdata=True, spw='', field='', antenna='', uvrange='', timerange='', correlation='', scan='', intent='', feed='', array='', observation='', verbose=True, listfile='', listunfl=False, cachesize=50, overwrite=False)[source]

List the summary of a data set 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

    selectdata = True
    • field (string=’’) - Selection based on field names or field index numbers. Default is all.

    • spw (string=’’) - Selection based on spectral-window/frequency/channel.

    • antenna (string=’’) - Selection based on antenna/baselines. Default is all.

    • timerange (string=’’) - Selection based on time range. Default is entire range.

    • correlation (string=’’) - Selection based on correlation. Default is all.

    • scan (string=’’) - Selection based on scan numbers. Default is all.

    • intent (string=’’) - Selection based on observation intent. Default is all.

    • feed (string=’’) - Selection based on multi-feed numbers: Not yet implemented

    • array (string=’’) - Selection based on (sub)array numbers. Default is all.

    • uvrange (string=’’) - Selection based on uv range. Default: entire range. Default units: meters.

    • observation (string=’’) - Selection based on observation ID. Default is all.

  • 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).

    listfile != ''
    • overwrite (bool=False) - If True, tacitly overwrite listfile if it exists.

  • 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.

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 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).

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
# 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

No additional development details

Parameter Details

Detailed descriptions of each function parameter

vis (path) - Name of input visibility file (MS)
selectdata (bool=True) - Data selection parameters
spw (string='') - Selection based on spectral-window/frequency/channel.
field (string='') - Selection based on field names or field index numbers. Default is all.
antenna (string='') - Selection based on antenna/baselines. Default is all.
uvrange (string='') - Selection based on uv range. Default: entire range. Default units: meters.
timerange (string='') - Selection based on time range. Default is entire range.
correlation (string='') - Selection based on correlation. Default is all.
scan (string='') - Selection based on scan numbers. Default is all.
intent (string='') - Selection based on observation intent. Default is all.
feed (string='') - Selection based on multi-feed numbers: Not yet implemented
array (string='') - Selection based on (sub)array numbers. Default is all.
observation (string='') - Selection based on observation ID. Default is all.
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).
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.
overwrite (bool=False) - If True, tacitly overwrite listfile if it exists.