UVData

UVData is the main user class for intereferometric data (visibilities). It provides import and export functionality to and from the supported file formats (UVFITS, MeasurementSets, Miriad, uvh5, FHD, MIR) as well as numerous methods for transforming the data (phasing, averaging, selecting, sorting) and can be interacted with directly.

Attributes

The attributes on UVData hold all of the metadata and data required to analyze interferometric data sets. Under the hood, the attributes are implemented as properties based on pyuvdata.parameter.UVParameter objects but this is fairly transparent to users.

UVData objects can be initialized from a file using the pyuvdata.UVData.from_file() class method (as uvd = UVData.from_file(<filename>)) or be initialized as an empty object (as uvd = UVData()). When an empty UVData object is initialized, it has all of these attributes defined but set to None. The attributes can be set by reading in a data file using the pyuvdata.UVData.read() method or by setting them directly on the object. Some of these attributes are required to be set to have a fully defined data set while others are optional. The pyuvdata.UVData.check() method can be called on the object to verify that all of the required attributes have been set in a consistent way.

Note that objects can be in a “metadata only” state where all of the metadata is defined but the data-like attributes (data_array, flag_array, nsample_array) are not. The pyuvdata.UVData.check() method will still pass for metadata only objects.

Note that angle type attributes also have convenience properties named the same thing with _degrees appended through which you can get or set the value in degrees. Similarly location type attributes (which are given in topocentric xyz coordinates) have convenience properties named the same thing with _lat_lon_alt and _lat_lon_alt_degrees appended through which you can get or set the values using latitude, longitude and altitude values in radians or degrees and meters.

Required

These parameters are required to have a sensible UVData object and are required for most kinds of interferometric data files.

Nants_data: Number of antennas with data present (i.e. number of unique entries in ant_1_array and ant_2_array). May be smaller than the number of antennas in the array.
Nants_telescope: Number of antennas in the array. May be larger than the number of antennas with data.
Nbls: Number of baselines.
Nblts: Number of baseline-times (i.e. number of spectra). Not necessarily equal to Nbls * Ntimes.
Nfreqs: Number of frequency channels.
Nphase: Specifies the number of phase centers contained within the data set.
Npols: Number of polarizations.
Nspws: Number of spectral windows (ie non-contiguous spectral chunks).
Ntimes: Number of times.
ant_1_array: Array of numbers for the first antenna, which is matched to that in the antenna_numbers attribute. Shape (Nblts), type = int.
ant_2_array: Array of numbers for the second antenna, which is matched to that in the antenna_numbers attribute. Shape (Nblts), type = int.
antenna_names: List of antenna names, shape (Nants_telescope), with numbers given by antenna_numbers (which can be matched to ant_1_array and ant_2_array). There must be one entry here for each unique entry in ant_1_array and ant_2_array, but there may be extras as well.
antenna_numbers: List of integer antenna numbers corresponding to antenna_names, shape (Nants_telescope). There must be one entry here for each unique entry in ant_1_array and ant_2_array, but there may be extras as well.Note that these are not indices – they do not need to start at zero or be continuous.
antenna_positions: Array giving coordinates of antennas relative to telescope_location (in frame _telescope_location.frame), shape (Nants_telescope, 3), units meters. See the UVData tutorial page in the documentation for an example of how to convert this to topocentric frame.
baseline_array: Array of baseline numbers, shape (Nblts), type = int; by default baseline = 2048 * ant1 + ant2 + 2^16, though other conventions are available.
channel_width: Width of frequency channels (Hz). If flex_spw = False and future_array_shapes=False, then it is a single value of type = float, otherwise it is an array of shape (Nfreqs), type = float.
flex_spw: Option to construct a “flexible spectral window”, which storesall spectral channels across the frequency axis of data_array. Allows for spectral windows of variable sizes, and channels of varying widths.
freq_array: Array of frequencies, center of the channel, shape (1, Nfreqs) or (Nfreqs,) if future_array_shapes=True, units Hz.
future_array_shapes: Flag indicating that this object is using the future array shapes.
history: String of history, units English.
instrument: Receiver or backend. Sometimes identical to telescope_name.
integration_time: Length of the integration in seconds, shape (Nblts). The product of the integration_time and the nsample_array value for a visibility reflects the total amount of time that went into the visibility. Best practice is for the integration_time to reflect the length of time a visibility was integrated over (so it should vary in the case of baseline-dependent averaging and be a way to do selections for differently integrated baselines).Note that many files do not follow this convention, but it is safe to assume that the product of the integration_time and the nsample_array is the total amount of time included in a visibility.
lst_array: Array of local apparent sidereal times (LAST) at the center of integration, shape (Nblts), units radians.
phase_center_app_dec: Apparent Declination of phase center in the topocentric frame of the observatory, units radians. Shape (Nblts,), type = float.
phase_center_app_ra: Apparent right ascension of phase center in the topocentric frame of the observatory, units radians. Shape (Nblts,), type = float.
phase_center_catalog: Dictionary that acts as a catalog, containing information on individual phase centers. Keys are the catalog IDs of the different phase centers in the object (matched to the parameter phase_center_id_array). At a minimum, each dictionary must contain the keys: ‘cat_name’ giving the phase center name (this does not have to be unique, non-unique values can be used to indicate sets of phase centers that make up a mosaic observation), ‘cat_type’, which can be ‘sidereal’ (fixed position in RA/Dec), ‘ephem’ (position in RA/Dec which moves with time), ‘driftscan’ (fixed postion in Az/El, NOT the same as the old phase_type`=’drift’) or ‘unprojected’ (baseline coordinates in ENU, but data are not phased, similar to the old `phase_type`=’drift’)’cat_lon’ (longitude coord, e.g. RA, either a single value or a one dimensional array of length Npts –the number of ephemeris data points– for ephem type phase centers), ‘cat_lat’ (latitude coord, e.g. Dec., either a single value or a one dimensional array of length Npts –the number of ephemeris data points– for ephem type phase centers), ‘cat_frame’ (coordinate frame, e.g. icrs, must be a frame supported by astropy). Other optional keys include ‘cat_epoch’ (epoch and equinox of the coordinate frame, not needed for frames without an epoch (e.g. ICRS) unless the there is proper motion), ‘cat_times’ (times for the coordinates, only used for ‘ephem’ types), ‘cat_pm_ra’ (proper motion in RA), ‘cat_pm_dec’ (proper motion in Dec), ‘cat_dist’ (physical distance to the source in parsec, useful if parallax is important, either a single value or a one dimensional array of length Npts –the number of ephemeris data points– for ephem type phase centers.), ‘cat_vrad’ (rest frame velocity in km/s, either a single value or a one dimensional array of length Npts –the number of ephemeris data points– for ephem type phase centers.), and ‘info_source’ (describes where catalog info came from). See the documentation of the `phase method for more details.
phase_center_frame_pa: Position angle between the hour circle (which is a great circle that goes through the target postion and both poles) in the apparent/topocentric frame, and the frame given in the phase_center_frame attribute.Shape (Nblts,), type = float.
phase_center_id_array: Maps individual indices along the Nblt axis to a key in phase_center_catalog, which maps to a dict containing the other metadata for each phase center.Shape (Nblts), type = int.
polarization_array: Array of polarization integers, shape (Npols). AIPS Memo 117 says: pseudo-stokes 1:4 (pI, pQ, pU, pV); circular -1:-4 (RR, LL, RL, LR); linear -5:-8 (XX, YY, XY, YX). NOTE: AIPS Memo 117 actually calls the pseudo-Stokes polarizations “Stokes”, but this is inaccurate as visibilities cannot be in true Stokes polarizations for physical antennas. We adopt the term pseudo-Stokes to refer to linear combinations of instrumental visibility polarizations (e.g. pI = xx + yy). A value of 0 indicates that the polarization is different for different spectral windows and is only allowed if flex_spw_polarization_array is defined (not None).
spw_array: Array of spectral window numbers, shape (Nspws).
telescope_location: Telescope location: xyz position in specified frame (default ITRS). Can also be accessed using telescope_location_lat_lon_alt or telescope_location_lat_lon_alt_degrees properties.
telescope_name: Name of telescope or array (string).
time_array: Array of times, center of integration, shape (Nblts), units Julian Date.
uvw_array: Projected baseline vectors relative to phase center, shape (Nblts, 3), units meters. Convention is: uvw = xyz(ant2) - xyz(ant1).Note that this is the Miriad convention but it is different from the AIPS/FITS convention (where uvw = xyz(ant1) - xyz(ant2)).
vis_units: Visibility units, options are: “uncalib”, “Jy” or “K str”.

Optional

These parameters are defined by one or more file standard but are not always required. Some of them are required depending on the phase_type (as noted below).

antenna_diameters: Array of antenna diameters in meters. Used by CASA to construct a default beam if no beam is supplied.
blt_order: Ordering of the data array along the blt axis. A tuple with the major and minor order (minor order is omitted if order is “bda”). The allowed values are: time ,baseline ,ant1 ,ant2 ,bda.
blts_are_rectangular: Whether the baseline-time axis is rectangular. If not provided, the rectangularity will be determined from the data. This is a non-negligibleoperation, so if you know it, it can be provided.
data_array: Array of the visibility data, shape: (Nblts, 1, Nfreqs, Npols) or (Nblts, Nfreqs, Npols) if future_array_shapes=True, type = complex float, in units of self.vis_units.
dut1: DUT1 (google it) AIPS 117 calls it UT1UTC.
earth_omega: Earth’s rotation rate in degrees per day.
eq_coeffs: Per-antenna and per-frequency equalization coefficients.
eq_coeffs_convention: Convention for how to remove eq_coeffs from data.
extra_keywords: Any user supplied extra keywords, type=dict. Keys should be 8 character or less strings if writing to uvfits or miriad files. Use the special key “comment” for long multi-line string comments.
filename: List of strings containing the unique basenames (not the full path) of input files.
flag_array: Boolean flag, True is flagged, same shape as data_array.
flex_spw_id_array: Required if flex_spw = True and will always be required starting in version 3.0. Maps individual channels along the frequency axis to individual spectral windows, as listed in the spw_array. Shape (Nfreqs), type = int.
flex_spw_polarization_array: Optional, only used if flex_spw = True. Allows for labeling individual spectral windows with different polarizations. If set, Npols must be set to 1 (i.e., only one polarization per spectral window allowed). Shape (Nspws), type = int.
gst0: Greenwich sidereal time at midnight on reference date.
nsample_array: Number of data points averaged into each data element, NOT required to be an integer, type = float, same shape as data_array.The product of the integration_time and the nsample_array value for a visibility reflects the total amount of time that went into the visibility. Best practice is for the nsample_array to be used to track flagging within an integration_time (leading to a decrease of the nsample array value below 1) and LST averaging (leading to an increase in the nsample array value). So datasets that have not been LST averaged should have nsample array values less than or equal to 1.Note that many files do not follow this convention, but it is safe to assume that the product of the integration_time and the nsample_array is the total amount of time included in a visibility.
rdate: Date for which the GST0 applies.
scan_number_array: Optional when reading a MS. Retains the scan number when reading a MS. Shape (Nblts), type = int.
time_axis_faster_than_bls: If blts are rectangular, this variable specifies whether the time axis isthe fastest-moving virtual axis. Various reading/indexing functions benefit from knowing this, so if it is known, it should be provided.
timesys: We only support UTC.
uvplane_reference_time: FHD thing we do not understand, something about the time at which the phase center is normal to the chosen UV plane for phasing.
x_orientation: Orientation of the physical dipole corresponding to what is labelled as the x polarization. Options are ‘east’ (indicating east/west orientation) and ‘north (indicating north/south orientation).

Methods

class pyuvdata.UVData[source]

A class for defining a radio interferometer dataset.

UVParameter objects: For full list see the documentation on ReadTheDocs: http://pyuvdata.readthedocs.io/en/latest/. Some are always required, some are required only for flex_spw data and others are always optional.

static new(**kwargs)[source]

Initialize a new UVData object from keyword arguments.

Returns:

obj (UVData object) – A UVData object with the specified metadata.

Other Parameters:

freq_array (ndarray of float) – Array of frequencies in Hz.
polarization_array (sequence of int or str) – Array of polarization integers or strings (eg. ‘xx’ or ‘ee’)
antenna_positions (ndarray of float or dict of ndarray of float) – Array of antenna positions in ECEF coordinates in meters. If a dict, keys are antenna names or numbers and values are antenna positions in ECEF coordinates in meters.
telescope_location (astropy EarthLocation or MoonLocation) – Location of the telescope.
telescope_name (str) – Name of the telescope.
times (ndarray of float, optional) – Array of times in Julian Date. These may be the unique times of the data if each baseline observes the same set of times, otherwise they should be an Nblts-length array of each time observed by each baseline. It is recommended to set the do_blt_outer parameter to specify whether to apply the times to each baseline.
antpairs (sequence of 2-tuples of int or 2D array of int, optional) – Antenna pairs in the data. If an ndarray, must have shape (Nants, 2). These may be the unique antpairs of the data if each antpair observes the same set of times, otherwise they should be an Nblts-length array of each antpair at each time. It is recommended to set the do_blt_outer parameter to specify whether to apply the times to each baseline. If not provided, use all unique antpairs determined from the antenna_numbers.
do_blt_outer (bool, optional) – If True, the final time_array and baseline_array will contain len(times)*len(antpairs) entries (one for each pair cartesian product of times and antpairs). If False, the final time_array and baseline_array will be the same as the input times and antpairs. If not provided, it will be set to True if times and antpairs are different lengths and all unique, otherwise it will be set to False.
integration_time (float or ndarray of float, optional) – Integration time in seconds. If not provided, it will be derived from the time_array, as the difference between successive times (with the last time-diff appended). If not provided and the number of unique times is one, then a warning will be raised and the integration time set to 1 second. If a float is provided, it will be used for all integrations. If an ndarray is provided, it must have the same shape as time_array (or unique_times, if that is what is provided).
channel_width (float or ndarray of float, optional) – Channel width in Hz. If not provided, it will be derived from the freq_array, as the difference between successive frequencies (with the last frequency-diff appended). If a float is provided, it will be used for all channels. If not provided and freq_array is length-one, the channel_width will be set to 1 Hz (and a warning issued). If an ndarray is provided, it must have the same shape as freq_array.
antenna_names (list of str, optional) – List of antenna names. If not provided, antenna numbers will be used to form the antenna_names, according to the antname_format. antenna_names need not be provided if antenna_positions is a dict with string keys.
antenna_numbers (list of int, optional) – List of antenna numbers. If not provided, antenna names will be used to form the antenna_numbers, but in this case the antenna_names must be strings that can be converted to integers. antenna_numbers need not be provided if antenna_positions is a dict with integer keys.
blts_are_rectangular (bool, optional) – Set to True if the time_array and antpair_array are rectangular, i.e. if they are formed from the outer product of a unique set of times/antenna pairs. If not provided, it will be inferred from the provided arrays.
data_array (ndarray of complex, optional) – Array of data. If not provided, and empty=True it will be initialized to all zeros. Otherwise a purely metadata-only object will be created. It must have shape (Nblts, Nfreqs, Npols)
flag_array (ndarray of bool, optional) – Array of flags. If not provided, and empty=True it will be initialized to all False. Otherwise a purely metadata-only object will be created. It must have shape (Nblts, Nfreqs, Npols)
nsample_array (ndarray of float, optional) – Array of nsamples. If not provided, and empty=True it will be initialized to all zeros. Otherwise a purely metadata-only object will be created. It must have shape (Nblts, Nfreqs, Npols)
flex_spw_id_array (ndarray of int, optional) – Array of spectral window IDs, one for each frequency. If not provided, it will be initialized to all zeros. It must have shape (Nfreqs,).
history (str, optional) – History string to be added to the object. Default is a simple string containing the date and time and pyuvdata version.
instrument (str, optional) – Instrument name. Default is the telescope_name.
vis_units (str, optional) – Visibility units. Default is ‘uncalib’. Must be one of ‘Jy’, ‘K str’, or ‘uncalib’.
antname_format (str, optional) – Format string for antenna names. Default is ‘{0:03d}’.
empty (bool, optional) – Set to True to create an empty (but not metadata-only) UVData object. Default is False.
time_axis_faster_than_bls (bool, optional) – Set to True if the time axis is faster than the baseline axis, under the assumption that the blt axis is rectangular. This sets the blt order in the case that unique times and unique baselines are provided, otherwise it is inferred from the provided arrays.
phase_center_catalog (dict, optional) – Dictionary of phase center information. Each key is a source id, and each value is a dictionary. By default, a single phase center is assumed, at zenith, assumed to be unprojected.
phase_center_id_array (ndarray of int, optional) – Array of phase center ids. If not provided, it will be initialized to the first id found in phase_center_catalog. It must have shape (Nblts,).
x_orientation (str) – Orientation of the x-axis. Options are ‘east’, ‘north’, ‘e’, ‘n’, ‘ew’, ‘ns’.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.
ellipsoid (str) – Ellipsoid to use for lunar coordinates. Must be one of “SPHERE”, “GSFC”, “GRAIL23”, “CE-1-LAM-GEO” (see lunarsky package for details). Default is “SPHERE”. Only used if telescope_location is a MoonLocation.
All other keyword parameters are set on the UVData object as attributes.

rename_phase_center(catalog_identifier, new_name)[source]

Rename a phase center/catalog entry within a multi phase center data set.

Parameters:

catalog_identifier (str or int or list of int) – Unique identifier of a phase center to be renamed. If supplied as a str, will be matched against the phase center name. Otherwise if an int or list of int, assumed to be the catalog ID number(s).
new_name (str) – New name for the phase center.

Raises:

ValueError – If attempting to run the method on a non multi phase center data set, or if catalog_identifier is not found in phase_center_catalog.
TypeError – If new_name is not actually a string or if catalog_identifier is not a string or an integer.

split_phase_center(catalog_identifier, new_name=None, select_mask=None, new_id=None, downselect=False)[source]

Rename the phase center (but preserve other properties) of a subset of data.

Allows you to rename a subset of the data phased to a particular phase center, marked by a different name than the original. Useful when you want to phase to one position, but want to differentiate different groups of data (e.g., marking every other integration to make jackknifing easier).

Parameters:

catalog_identifier (str or int) – Unique identifier of a phase center to be renamed. If supplied as a str, will be matched against the phase center name. Otherwise if an int, assumed to be the catalog ID number.
new_name (str) – Name for the “split” portion of the phase center. Optional argument, default is to use the same name as the existing phase center.
select_mask (array_like) – Selection mask for which data should be identified as belonging to the phase center labeled by new_name. Any array-like able to be used as an index is suitable – the most typical is an array of bool with length Nblts, or an array of ints within the range (-Nblts, Nblts).
new_id (int) – Catalog ID to assign to the new phase center. Optional argument, a unique value will be automatically assigned if not provided.
downselect (bool) – If selecting data that is not marked as belonging to cat_name, normally an error is thrown. By setting this to True, select_mask will be modified to exclude data not marked as belonging to cat_name.

Raises:

ValueError – If catalog_identifier is not an int or string or if it is not found as a cat_name in phase_center_catalog or if it is a string and is found multiple times. If new_id is not an int or already exists in the catalog. If new_name is not a string. If select_mask contains data that doesn’t belong to catalog_identifier, unless downselect is True.
IndexError – If select_mask is not a valid indexing array.
UserWarning – If all data for cat_name was selected (in which case rename_phase_center is called instead), or if no valid data was selected.

merge_phase_centers(catalog_identifier, force_merge=False, ignore_name=False)[source]

Merge two differently named objects into one within a multi-phase-ctr data set.

Recombines two different objects into a single catalog entry – useful if having previously used split_phase_center or when multiple objects with different names share the same source parameters.

Parameters:

catalog_identifier (str or int or list of str or int) – Unique identifier(s) of a phase center to be merged. If supplied as strings, will be matched against the phase center name. Otherwise if supplied as integers, assumed to be the catalog ID number(s).
force_merge (bool) – Normally, the method will throw an error if the phase center properties differ for the catalogs listed in catalog_identifier. This can be overriden by setting this to True. Default is False.
ignore_name (bool) – When comparing phase centers, all attributes are normally checked. However, if set to True, the catalog name (“cat_name”) will be ignored when performing the comparison. Default is False.

Raises:

ValueError – If catname1 or catname2 are not found in the UVData object, of if their properties differ (and force_merge is not set to True).
UserWarning – If forcing the merge of two objects with different properties.

print_phase_center_info(catalog_identifier=None, hms_format=None, return_str=False, print_table=True)[source]

Print out the details of the phase centers.

Prints out an ASCII table that contains the details of the phase_center_catalog attribute, which acts as the internal source catalog for UVData objects.

Parameters:

catalog_identifier (str or int or list of str or int) – Optional parameter which, if provided, will cause the method to only return information on the phase center(s) with the matching name(s) or catalog ID number(s). Default is to print out information on all catalog entries.
hms_format (bool) – Optional parameter, which if selected, can be used to force coordinates to be printed out in Hours-Min-Sec (if set to True) or Deg-Min-Sec (if set to False) format. Default is to print out in HMS if all the objects have coordinate frames of icrs, gcrs, fk5, fk4, and top; otherwise, DMS format is used.
return_str (bool) – If set to True, the method returns an ASCII string which contains all the table infrmation. Default is False.
print_table (bool) – If set to True, prints the table to the terminal window. Default is True.

Returns:

table_str (bool) – If return_str=True, an ASCII string containing the entire table text

Raises:

ValueError – If cat_name matches no keys in phase_center_catalog.

property data_like_parameters: Iterate defined parameters which are data-like (not metadata-like).

property metadata_only

Property that determines whether this is a metadata only object.

An object is metadata only if data_array, nsample_array and flag_array are all None.

use_future_array_shapes()[source]

Change the array shapes of this object to match the planned future shapes.

This method sets allows users to convert to the planned array shapes changes before the changes go into effect. This method sets the future_array_shapes parameter on this object to True.

use_current_array_shapes()[source]

Change the array shapes of this object to match the current future shapes.

This method sets allows users to convert back to the current array shapes. This method sets the future_array_shapes parameter on this object to False.

known_telescopes()[source]

Get a list of telescopes known to pyuvdata.

This is just a shortcut to uvdata.telescopes.known_telescopes()

Returns:: list of str – List of names of known telescopes

set_telescope_params(overwrite=False, warn=True)[source]

Set telescope related parameters.

If the telescope_name is in the known_telescopes, set any missing telescope-associated parameters (e.g. telescope location) to the value for the known telescope.

Parameters:: overwrite (bool) – Option to overwrite existing telescope-associated parameters with the values from the known telescope.
Raises:: ValueError – if the telescope_name is not in known telescopes

set_lsts_from_time_array(background=False, astrometry_library=None)[source]

Set the lst_array based from the time_array.

Parameters:

background (bool, False) – When set to True, start the calculation on a threading.Thread in the background and return the thread to the user.
astrometry_library (str) – Library used for calculating the LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.

Returns:

proc (None or threading.Thread instance) – When background is set to True, a thread is returned which must be joined before the lst_array exists on the UVData object.

remove_flex_pol(combine_spws=True)[source]

Convert a flex-pol UVData object into one with a standard polarization axis.

This will convert a flexible-polarization dataset into one with standard polarization handling, which is required for some operations or writing in certain filetypes. Note that depending on how it is used, this can inflate the size of data-like parameters by up to a factor of Nspws (the true value depends on the number of unique entries in flex_spw_polarization_array).

convert_to_flex_pol()[source]

Convert a regular UVData object into a flex-polarization object.

This effectively combines the frequency and polarization axis with polarization changing slowest. Saving data to uvh5 files this way can speed up some kinds of data access.

check(check_extra=True, run_check_acceptability=True, check_freq_spacing=False, strict_uvw_antpos_check=False, allow_flip_conj=False, check_autos=False, fix_autos=False, lst_tol=3.63610260832152e-07)[source]

Add some extra checks on top of checks on UVBase class.

Check that required parameters exist. Check that parameters have appropriate shapes and optionally that the values are acceptable.

Parameters:

check_extra (bool) – If true, check all parameters, otherwise only check required parameters.
run_check_acceptability (bool) – Option to check if values in parameters are acceptable.
check_freq_spacing (bool) – Option to check if frequencies are evenly spaced and the spacing is equal to their channel_width. This is not required for UVData objects in general but is required to write to uvfits and miriad files.
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.
allow_flip_conj (bool) – If set to True, and the UVW coordinates do not match antenna positions, check and see if flipping the conjugation of the baselines (i.e, multiplying the UVWs by -1) resolves the apparent discrepancy – and if it does, fix the apparent conjugation error in uvw_array and data_array. Default is False.
check_autos (bool) – Check whether any auto-correlations have non-zero imaginary values in data_array (which should not mathematically exist). Default is False.
fix_autos (bool) – If auto-correlations with imaginary values are found, fix those values so that they are real-only in data_array. Default is True.
lst_tol (float or None) – Tolerance level at which to test LSTs against their expected values. If provided as a float, must be in units of radians. If set to None, the default precision tolerance from the lst_array parameter is used (1 mas). Default value is 75 mas, which is set by the predictive uncertainty in IERS calculations of DUT1 (RMS is of order 1 ms, with with a 5-sigma threshold for detection is used to prevent false issues from being reported), which for some observatories sets the precision with which these values are written.

Returns:

bool – True if check passes

Raises:

ValueError – if parameter shapes or types are wrong or do not have acceptable values (if run_check_acceptability is True)

copy(metadata_only=False)[source]

Make and return a copy of the UVData object.

Parameters:: metadata_only (bool) – If True, only copy the metadata of the object.
Returns:: UVData – Copy of self.

baseline_to_antnums(baseline)[source]

Get the antenna numbers corresponding to a given baseline number.

Parameters:

baseline (int or array_like of int) – baseline number

Returns:

int or array_like of int – first antenna number(s)
int or array_like of int – second antenna number(s)

antnums_to_baseline(ant1, ant2, attempt256=False, use_miriad_convention=False)[source]

Get the baseline number corresponding to two given antenna numbers.

Parameters:

ant1 (int or array_like of int) – first antenna number
ant2 (int or array_like of int) – second antenna number
attempt256 (bool) – Option to try to use the older 256 standard used in many uvfits files (will use 2048 standard if there are more than 256 antennas).
use_miriad_convention (bool) – Option to use the MIRIAD convention where BASELINE id is bl = 256 * ant1 + ant2 if ant2 < 256, otherwise bl = 2048 * ant1 + ant2 + 2**16. Note MIRIAD uses 1-indexed antenna IDs, but this code accepts 0-based.

Returns:

int or array of int – baseline number corresponding to the two antenna numbers.

antpair2ind(ant1, ant2=None, ordered=True)[source]

Get indices along the baseline-time axis for a given antenna pair.

This will search for either the key as specified, or the key and its conjugate.

Parameters:

ant1, ant2 (int) – Either an antenna-pair key, or key expanded as arguments, e.g. antpair2ind( (10, 20) ) or antpair2ind(10, 20)
ordered (bool) – If True, search for antpair as provided, else search for it and its conjugate.

Returns:

inds (ndarray of int-64) – indices of the antpair along the baseline-time axis.

get_ants()[source]

Get the unique antennas that have data associated with them.

Returns:: ndarray of int – Array of unique antennas with data associated with them.

get_baseline_nums()[source]

Get the unique baselines that have data associated with them.

Returns:: ndarray of int – Array of unique baselines with data associated with them.

get_antpairs()[source]

Get the unique antpair tuples that have data associated with them.

Returns:: list of tuples of int – list of unique antpair tuples (ant1, ant2) with data associated with them.

get_pols()[source]

Get the polarizations in the data.

Returns:: list of str – list of polarizations (as strings) in the data.

get_antpairpols()[source]

Get the unique antpair + pol tuples that have data associated with them.

Returns:: list of tuples of int – list of unique antpair + pol tuples (ant1, ant2, pol) with data associated with them.

get_feedpols()[source]

Get the unique antenna feed polarizations in the data.

Returns:: list of str – list of antenna feed polarizations (e.g. [‘X’, ‘Y’]) in the data.
Raises:: ValueError – If any pseudo-Stokes visibilities are present

get_data(key1, key2=None, key3=None, squeeze='default', force_copy=False)[source]

Get the data corresonding to a baseline and/or polarization.

Parameters:

key1, key2, key3 (int or tuple of ints) – Identifier of which data to get, can be passed as 1, 2, or 3 arguments or as a single tuple of length 1, 2, or 3. These are collectively called the key.

If key is length 1:

if (key < 5) or (type(key) is str):
interpreted as a polarization number/name, get all data for that pol.

else:
interpreted as a baseline number, get all data for that baseline.

if key is length 2: interpreted as an antenna pair, get all data
for that baseline.

if key is length 3: interpreted as antenna pair and pol (ant1, ant2, pol),
get all data for that baseline, pol. pol may be a string or int.
squeeze (str) – string specifying how to squeeze the returned array. Options are: ‘default’: squeeze pol and spw dimensions if possible; ‘none’: no squeezing of resulting numpy array; ‘full’: squeeze all length 1 dimensions.
force_copy (bool) – Option to explicitly make a copy of the data.

Returns:

ndarray – copy (or if possible, a read-only view) of relevant section of data. If data exists conjugate to requested antenna pair, it will be conjugated before returning.

get_flags(key1, key2=None, key3=None, squeeze='default', force_copy=False)[source]

Get the flags corresonding to a baseline and/or polarization.

Parameters:

key1, key2, key3 (int or tuple of ints) – Identifier of which data to get, can be passed as 1, 2, or 3 arguments or as a single tuple of length 1, 2, or 3. These are collectively called the key.

If key is length 1:

if (key < 5) or (type(key) is str):
interpreted as a polarization number/name, get all flags for that pol.

else:
interpreted as a baseline number, get all flags for that baseline.

if key is length 2: interpreted as an antenna pair, get all flags
for that baseline.

if key is length 3: interpreted as antenna pair and pol (ant1, ant2, pol),
get all flags for that baseline, pol. pol may be a string or int.
squeeze (str) – string specifying how to squeeze the returned array. Options are: ‘default’: squeeze pol and spw dimensions if possible; ‘none’: no squeezing of resulting numpy array; ‘full’: squeeze all length 1 dimensions.
force_copy (bool) – Option to explicitly make a copy of the data.

Returns:

ndarray – copy (or if possible, a read-only view) of relevant section of flags.

get_nsamples(key1, key2=None, key3=None, squeeze='default', force_copy=False)[source]

Get the nsamples corresonding to a baseline and/or polarization.

Parameters:

key1, key2, key3 (int or tuple of ints) – Identifier of which data to get, can be passed as 1, 2, or 3 arguments or as a single tuple of length 1, 2, or 3. These are collectively called the key.

If key is length 1:

if (key < 5) or (type(key) is str):
interpreted as a polarization number/name, get all nsamples for that pol.

else:
interpreted as a baseline number, get all nsamples for that baseline.

if key is length 2: interpreted as an antenna pair, get all nsamples
for that baseline.

if key is length 3: interpreted as antenna pair and pol (ant1, ant2, pol),
get all nsamples for that baseline, pol. pol may be a string or int.
squeeze (str) – string specifying how to squeeze the returned array. Options are: ‘default’: squeeze pol and spw dimensions if possible; ‘none’: no squeezing of resulting numpy array; ‘full’: squeeze all length 1 dimensions.
force_copy (bool) – Option to explicitly make a copy of the data.

Returns:

ndarray – copy (or if possible, a read-only view) of relevant section of nsample_array.

get_times(key1, key2=None, key3=None)[source]

Get the times for a given antpair or baseline number.

Meant to be used in conjunction with get_data function.

Parameters:

key1, key2, key3 (int or tuple of ints) – Identifier of which data to get, can be passed as 1, 2, or 3 arguments or as a single tuple of length 1, 2, or 3. These are collectively called the key.

If key is length 1:

if (key < 5) or (type(key) is str):: interpreted as a polarization number/name, get all times.
else:: interpreted as a baseline number, get all times for that baseline.

if key is length 2: interpreted as an antenna pair, get all times

for that baseline.

if key is length 3: interpreted as antenna pair and pol (ant1, ant2, pol),

get all times for that baseline.

Returns:

ndarray – times from the time_array for the given antpair or baseline.

get_lsts(key1, key2=None, key3=None)[source]

Get the LSTs for a given antpair or baseline number.

Meant to be used in conjunction with get_data function.

Parameters:

key1, key2, key3 (int or tuple of ints) – Identifier of which data to get, can be passed as 1, 2, or 3 arguments or as a single tuple of length 1, 2, or 3. These are collectively called the key.

If key is length 1:

if (key < 5) or (type(key) is str):: interpreted as a polarization number/name, get all times.
else:: interpreted as a baseline number, get all times for that baseline.

if key is length 2: interpreted as an antenna pair, get all times

for that baseline.

if key is length 3: interpreted as antenna pair and pol (ant1, ant2, pol),

get all times for that baseline.

Returns:

ndarray – LSTs from the lst_array for the given antpair or baseline.

get_ENU_antpos(center=False, pick_data_ants=False)[source]

Get antenna positions in East, North, Up coordinates in units of meters.

Parameters:

center (bool) – If True, subtract median of array position from antpos
pick_data_ants (bool) – If True, return only antennas found in data

Returns:

antpos (ndarray) – Antenna positions in East, North, Up coordinates in units of meters, shape=(Nants, 3)
ants (ndarray) – Antenna numbers matching ordering of antpos, shape=(Nants,)

set_data(data, key1, key2=None, key3=None)[source]

Set the data array to some values provided by the user.

Parameters:

data (ndarray of complex) – The data to overwrite into the data_array. Must be the same shape as the target indices.
key1, key2, key3 (int or tuple of ints) – Identifier of which data to set, can be passed as 1, 2, or 3 arguments or as a single tuple of length 1, 2, or 3. These are collectively called the key.

If key is length 1:

if (key < 5) or (type(key) is str):
interpreted as a polarization number/name, get all data for that pol.

else:
interpreted as a baseline number, get all data for that baseline.

if key is length 2: interpreted as an antenna pair, get all data
for that baseline.

if key is length 3: interpreted as antenna pair and pol (ant1, ant2, pol),
get all data for that baseline, pol. pol may be a string or int.

Returns:

None

Raises:

ValueError: – If more than 3 keys are passed, if the requested indices are conjugated in the data, if the data array shape is not compatible with the indices.

set_flags(flags, key1, key2=None, key3=None)[source]

Set the flag array to some values provided by the user.

Parameters:

flag (ndarray of boolean) – The flags to overwrite into the fkag_array. Must be the same shape as the target indices.
key1, key2, key3 (int or tuple of ints) – Identifier of which flags to set, can be passed as 1, 2, or 3 arguments or as a single tuple of length 1, 2, or 3. These are collectively called the key.

If key is length 1:

if (key < 5) or (type(key) is str):
interpreted as a polarization number/name, set all flags for that pol.

else:
interpreted as a baseline number, set all flags for that baseline.

if key is length 2: interpreted as an antenna pair, set all flags
for that baseline.

if key is length 3: interpreted as antenna pair and pol (ant1, ant2, pol),
set all flags for that baseline, pol. pol may be a string or int.

Returns:

None

Raises:

ValueError: – If more than 3 keys are passed, if the requested indices are conjugated in the data, if the data array shape is not compatible with the indices.

set_nsamples(nsamples, key1, key2=None, key3=None)[source]

Set the nsamples array to some values provided by the user.

Parameters:

nsamples (ndarray of float) – The nsamples to overwrite into the nsample_array. Must be the same shape as the target indices.
key1, key2, key3 (int or tuple of ints) – Identifier of which nsamples to set, can be passed as 1, 2, or 3 arguments or as a single tuple of length 1, 2, or 3. These are collectively called the key.

If key is length 1:

if (key < 5) or (type(key) is str):
interpreted as a polarization number/name, set all data for that pol.

else:
interpreted as a baseline number, set all nsamples for that baseline.

if key is length 2: interpreted as an antenna pair, set all nsamples
for that baseline.

if key is length 3: interpreted as antenna pair and pol (ant1, ant2,
pol), set all nsamples for that baseline, pol. pol may be a string or int.

Returns:

None

Raises:

ValueError: – If more than 3 keys are passed, if the requested indices are conjugated in the data, if the data array shape is not compatible with the indices.

antpairpol_iter(squeeze='default')[source]

Iterate the data for each antpair, polarization combination.

Parameters:

squeeze (str) – string specifying how to squeeze the returned array. Options are: ‘default’: squeeze pol and spw dimensions if possible; ‘none’: no squeezing of resulting numpy array; ‘full’: squeeze all length 1 dimensions.

Yields:

key (tuple) – antenna1, antenna2, and polarization string
data (ndarray of complex) – data for the ant pair and polarization specified in key

conjugate_bls(convention='ant1<ant2', use_enu=True, uvw_tol=0.0)[source]

Conjugate baselines according to one of the supported conventions.

This will fail if only one of the cross pols is present (because conjugation requires changing the polarization number for cross pols).

Parameters:

convention (str or array_like of int) – A convention for the directions of the baselines, options are: ‘ant1<ant2’, ‘ant2<ant1’, ‘u<0’, ‘u>0’, ‘v<0’, ‘v>0’ or an index array of blt indices to conjugate.
use_enu (bool) – Use true antenna positions to determine uv location (as opposed to uvw array). Only applies if convention is ‘u<0’, ‘u>0’, ‘v<0’, ‘v>0’. Set to False to use uvw array values.
uvw_tol (float) – Defines a tolerance on uvw coordinates for setting the u>0, u<0, v>0, or v<0 conventions. Defaults to 0m.

Raises:

ValueError – If convention is not an allowed value or if not all conjugate pols exist.

reorder_pols(order='AIPS', run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False)[source]

Arrange polarization axis according to desired order.

Parameters:

order (str) – Either a string specifying a canonical ordering (‘AIPS’ or ‘CASA’) or an index array of length Npols that specifies how to shuffle the data (this is not the desired final pol order). CASA ordering has cross-pols in between (e.g. XX,XY,YX,YY) AIPS ordering has auto-pols followed by cross-pols (e.g. XX,YY,XY,YX) Default (‘AIPS’) will sort by absolute value of pol values.
run_check (bool) – Option to check for the existence and proper shapes of parameters after reordering.
check_extra (bool) – Option to check optional parameters as well as required ones.
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after reordering.
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.

Raises:

ValueError – If the order is not one of the allowed values.

set_rectangularity(force: bool = False) → None[source]

Set the rectangularity attributes of the object.

Parameters:: force (bool, optional) – Whether to force setting the rectangularity attributes, even if they are unset. Default is to leave them unset if they are not already set, but otherwise just ensure correctness.
Returns:: None

reorder_blts(order='time', minor_order=None, autos_first=False, conj_convention=None, uvw_tol=0.0, conj_convention_use_enu=True, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False)[source]

Arrange baseline-times axis according to desired order.

If the specified order is an index type, it will be the slowest changing index along the baseline-time axis (the minor order will be the next slowest). If the conj_convention is set, this method can also conjugate some baselines using the conjugate_bls method.

Parameters:

order (str or array_like of int) – A string describing the desired order along the blt axis or an index array of length Nblts that specifies the new order. If a string, the options are: time, baseline, ant1, ant2, bda. If this is time, baseline, ant1, ant2 then this will be the slowest changing index.
minor_order (str) – Optionally specify a secondary ordering. Default depends on how order is set: if order is ‘time’, this defaults to baseline, if order is ant1, or ant2 this defaults to the other antenna, if order is baseline the only allowed value is time. Ignored if order is bda or an integer array. If this is the same as order, it is reset to the default. This will be the next slowest changing index.
autos_first (bool) – If True, sort the autos before all the crosses. The autos and crosses will each be sorted according to the order and minor order keywords. Ignored if order is an integer array.
conj_convention (str or array_like of int) – Optionally conjugate baselines to make the baselines have the desired orientation. See conjugate_bls for allowed values and details.
uvw_tol (float) – If conjugating baselines, sets a tolerance for determining the signs of u,v, and w, and whether or not they are zero. See conjugate_bls for details.
conj_convention_use_enu (bool) – If conj_convention is set, this is passed to conjugate_bls, see that method for details.
run_check (bool) – Option to check for the existence and proper shapes of parameters after reordering.
check_extra (bool) – Option to check optional parameters as well as required ones.
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after reordering.
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.

Raises:

ValueError – If parameter values are inappropriate

reorder_freqs(spw_order=None, channel_order=None, select_spw=None, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False)[source]

Arrange frequency axis according to desired order.

Can be applied across the entire frequency axis, or just a subset.

Parameters:

spw_order (str or array_like of int) – A string describing the desired order of spectral windows along the frequecy axis. Allowed strings include number (sort on spectral window number) and freq (sort on median frequency). A ‘-’ can be prepended to signify descending order instead of the default ascending order, e.g., if you have SPW #1 and 2, and wanted them ordered as [2, 1], you would specify -number. Alternatively, one can supply an index array of length Nspws that specifies how to shuffle the spws (this is not the desired final spw order). Default is to apply no sorting of spectral windows.
channel_order (str or array_like of int) – A string describing the desired order of frequency channels within a spectral window. Allowed strings are “freq” and “-freq”, which will sort channels within a spectral window by ascending or descending frequency respectively. Alternatively, one can supply an index array of length Nfreqs that specifies the new order. Default is to apply no sorting of channels within a single spectral window. Note that proving an array_like of ints will cause the values given to spw_order and select_spw to be ignored.
select_spw (int or array_like of int) – An int or array_like of ints which specifies which spectral windows to apply sorting. Note that setting this argument will cause the value given to spw_order to be ignored.
run_check (bool) – Option to check for the existence and proper shapes of parameters after reordering.
check_extra (bool) – Option to check optional parameters as well as required ones.
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after reordering.
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.

Returns:

None

Raises:

UserWarning – Raised if providing arguments to select_spw and channel_order (the latter overrides the former).
ValueError – Raised if select_spw contains values not in spw_array, or if channel_order is not the same length as freq_array.

remove_eq_coeffs()[source]

Remove equalization coefficients from the data.

Some telescopes, e.g. HERA, apply per-antenna, per-frequency gain coefficients as part of the signal chain. These are stored in the eq_coeffs attribute of the object. This method will remove them, so that the data are in “unnormalized” raw units.

Parameters:: None
Returns:: None
Raises:: ValueError – Raised if eq_coeffs or eq_coeffs_convention are not defined on the object, or if eq_coeffs_convention is not one of “multiply” or “divide”.

unproject_phase(use_ant_pos=True, select_mask=None, cat_name='unprojected')[source]

Undo phasing to get back to an unprojected state.

See the phasing memo under docs/references for more documentation.

Parameters:

use_ant_pos (bool) – If True, calculate the uvws directly from the antenna positions rather than from the existing uvws. Default is True.
select_mask (ndarray of bool) – Optional mask for selecting which data to operate on along the blt-axis. Shape is (Nblts,).
cat_name (str) – Name for the newly unprojected entry in the phase_center_catalog.

Raises:

ValueError – If the object is alread unprojected.

phase(lon=None, lat=None, epoch='J2000', phase_frame='icrs', ra=None, dec=None, cat_type=None, ephem_times=None, pm_ra=None, pm_dec=None, dist=None, vrad=None, cat_name=None, lookup_name=False, use_ant_pos=True, select_mask=None, cleanup_old_sources=True)[source]

Phase data to a new direction, supports sidereal, ephemeris and driftscan types.

Can be used to phase all or a subset of the baseline-times. Types of phase centers (cat_type) that are supported include:

sidereal (fixed RA/Dec)

ephem (RA/Dec that moves with time)

driftscan (fixed az/el position)

See the phasing memo under docs/references for more documentation.

Tested against MWA_Tools/CONV2UVFITS/convutils.

Parameters:

lon (float) – The longitude coordinate (e.g. RA or Azimuth) to phase to in radians.
lat (float) – The latitude coordinate (e.g. Dec or Altitude) to phase to in radians.
epoch (astropy.time.Time object or str) – The epoch to use for phasing. Either an astropy Time object or the string “J2000” (which is the default). Note that the epoch is only used to evaluate the ra & dec values, if the epoch is not J2000, the ra & dec values are interpreted as FK5 ra/dec values and transformed to J2000, the data are then phased to the J2000 ra/dec values.
phase_frame (str) – The astropy frame to phase to, any astropy-supported frame is allowed unless use_old_proj is True, in which case it can only be ‘icrs’ or ‘gcrs’. ‘gcrs’ accounts for precession & nutation, ‘icrs’ accounts for precession, nutation & abberation.
ra (float) – An alias for lon.
dec (float) – An alias for lat.
cat_type (str) – Type of phase center to be added. Must be one of: “sidereal” (fixed RA/Dec), “ephem” (RA/Dec that moves with time), “driftscan” (fixed az/el position). Default is “sidereal”.
ephem_times (ndarray of float) – Only used when cat_type=”ephem”. Describes the time for which the values of cat_lon and cat_lat are caclulated, in units of JD. Shape is (Npts,).
pm_ra (float) – Proper motion in RA, in units of mas/year. Only used for sidereal phase centers.
pm_dec (float) – Proper motion in Dec, in units of mas/year. Only used for sidereal phase centers.
dist (float or ndarray of float) – Distance of the source, in units of pc. Only used for sidereal and ephem phase centers. Expected to be a float for sidereal phase centers, and an ndarray of floats of shape (Npts,) for ephem phase centers.
vrad (float or ndarray of float) – Radial velocity of the source, in units of km/s. Only used for sidereal and ephem phase centers. Expected to be a float for sidereal phase centers, and an ndarray of floats of shape (Npts,) for ephem phase centers.
cat_name (str) – Name of the phase center being phased to, required.
lookup_name (bool) – Allows the user to lookup phase center infomation in phase_center_catalog (for the entry matching cat_name). Setting this to True will ignore the values supplied to the ra, dec, epoch, phase_frame, pm_ra, pm_dec, dist, vrad.
use_ant_pos (bool) – If True, calculate the uvws directly from the antenna positions rather than from the existing uvws.
select_mask (ndarray of bool) – Optional mask for selecting which data to operate on along the blt-axis. Shape is (Nblts,). Ignored if use_old_proj is True.

Raises:

ValueError – If the cat_name is None.

phase_to_time(time, phase_frame='icrs', use_ant_pos=True, select_mask=None)[source]

Phase to the ra/dec of zenith at a particular time.

See the phasing memo under docs/references for more documentation.

Parameters:

time (astropy.time.Time object or float) – The time to phase to, an astropy Time object or a float Julian Date
phase_frame (str) – The astropy frame to phase to, any astropy-supported frame is allowed unless use_old_proj is True, in which case it can only be ‘icrs’ or ‘gcrs’. ‘gcrs’ accounts for precession & nutation, ‘icrs’ accounts for precession, nutation & abberation.
use_ant_pos (bool) – If True, calculate the uvws directly from the antenna positions rather than from the existing uvws.
select_mask (array_like) – Selection mask for which data should be rephased. Any array-like able to be used as an index is suitable – the most typical is an array of bool with length Nblts, or an array of ints within the range (-Nblts, Nblts).

Raises:

TypeError – If time is not an astropy.time.Time object or Julian Date as a float

set_uvws_from_antenna_positions(update_vis=True)[source]

Calculate UVWs based on antenna_positions.

Parameters:: update_vis (bool) – Option to update visibilities based on the new uvws (only has an effect if visibilities have been phased). This should only be set to False in limited circumstances (e.g., when certain metadata like exact times are not trusted), as misuse can significantly corrupt data.

update_antenna_positions(new_positions=None, delta_antpos=False, update_vis=True)[source]

Update antenna positions and associated (meta)data.

This method will update the antenna positions for a UVData object, and correspondingly will adjust the uvw-coordinates for each of the baselines, as well as the phases of the visibilities (if requested).

Parameters:

new_positions (dict) – Dictionary containing new antenna positions, where the key is the antenna number (which should match to an entry in UVData.antenna_numbers), and the value is a 3-element array corresponding to the ECEF/MCMF position relative to the array center.
delta_antpos (bool) – When set to True, uvws are updated by calculating the difference between the old and new antenna positions. This option should be used with care, and should only be used when warranted (e.g., antenna positions are stored with higher precision than the baselines). Default is False.
update_vis (bool) – Option to update visibilities based on the new uvws (only has an effect if visibilities have been phased). This should only be set to False in limited circumstances (e.g., when certain metadata like exact times are not trusted), as misuse can significantly corrupt data.

fix_phase(use_ant_pos=True)[source]

Fix the data to be consistent with the new phasing method.

This is a simple utility function for updating UVW coordinates calculated using the ‘old’ phasing algorithm with those calculated by the ‘new’ algorithm. Note that this step is required for using the new methods with data phased using the phase methiod prior to pyuvdata v2.2.

Parameters:: use_ant_pos (bool) – Use the antenna positions for determining UVW coordinates. Default is True.

fast_concat(other, axis, inplace=False, verbose_history=False, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, ignore_name=None)[source]

Concatenate two UVData objects along specified axis with almost no checking.

Warning! This method assumes all the metadata along other axes is sorted the same way. The __add__ method is much safer, it checks all the metadata, but it is slower. Some quick checks are run, but this method doesn’t make any guarantees that the resulting object is correct.

Note that if objects have different phasing (different phase_center_catalogs) they can still be combined and the phasing information will be preserved. However, the phase center ID numbers may be changed on any of the objects passed into this method.

Parameters:

other (UVData object or list of UVData objects) – UVData object or list of UVData objects which will be added to self.
axis (str) – Axis to concatenate files along. This enables fast concatenation along the specified axis without the normal checking that all other metadata agrees. Allowed values are: ‘blt’, ‘freq’, ‘polarization’.
inplace (bool) – If True, overwrite self as we go, otherwise create a third object as the sum of the two.
verbose_history (bool) – Option to allow more verbose history. If True and if the histories for the objects are different, the combined object will keep all the history of all input objects (if many objects are combined this can lead to very long histories). If False and if the histories for the objects are different, the combined object will have the history of the first object and only the parts of the other object histories that are unique (this is done word by word and can result in hard to interpret histories).
run_check (bool) – Option to check for the existence and proper shapes of parameters after combining objects.
check_extra (bool) – Option to check optional parameters as well as required ones.
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after combining objects.
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.
ignore_name (bool) – Option to ignore the name of the phase center (cat_name in phase_center_catalog) when combining two UVData objects. If set to True, phase centers that are the same up to their name will be combined with the name set to the name found in the first UVData object in the sum. If set to False, phase centers that are the same up to the name will be kept as separate phase centers. Default is False.

Raises:

ValueError – If other is not a UVData object, axis is not an allowed value or if self and other are not compatible.

sum_vis(other, inplace=False, difference=False, verbose_history=False, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, override_params=None)[source]

Sum visibilities between two UVData objects.

By default requires that all UVParameters are the same on the two objects except for history, data_array, and extra_keywords. If keys in extra_keywords have different values the values from the first object are taken.

Parameters:

other (UVData object) – Another UVData object which will be added to self.
difference (bool) – If True, differences the visibilities of the two UVData objects rather than summing them.
inplace (bool) – If True, overwrite self as we go, otherwise create a third object as the sum of the two.
verbose_history (bool) – Option to allow more verbose history. If True and if the histories for the two objects are different, the combined object will keep all the history of both input objects (this can lead to long histories). If False and if the histories for the two objects are different, the combined object will have the history of the first object and only the parts of the second object history that are unique (this is done word by word and can result in hard to interpret histories).
run_check (bool) – Option to check for the existence and proper shapes of parameters after combining objects.
check_extra (bool) – Option to check optional parameters as well as required ones.
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after combining objects.
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.
override_params (array_like of strings) – List of object UVParameters to omit from compatibility check. Overridden parameters will not be compared between the objects, and the values for these parameters will be taken from the first object.

Returns:

UVData Object – If inplace parameter is False.

Raises:

ValueError – If other is not a UVData object, or if self and other are not compatible.

diff_vis(other, inplace=False, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, override_params=None)[source]

Difference visibilities between two UVData objects.

By default requires that all UVParameters are the same on the two objects except for history, data_array, and extra_keywords. If keys in extra_keywords have different values the values from the first object are taken.

Parameters:

other (UVData object) – Another UVData object which will be added to self.
inplace (bool) – If True, overwrite self as we go, otherwise create a third object as the sum of the two.
run_check (bool) – Option to check for the existence and proper shapes of parameters after combining objects.
check_extra (bool) – Option to check optional parameters as well as required ones.
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after combining objects.
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.
override_params (array_like of strings) – List of object UVParameters to omit from compatibility check. Overridden parameters will not be compared between the objects, and the values for these parameters will be taken from the first object.

Returns:

UVData Object – If inplace parameter is False.

Raises:

ValueError – If other is not a UVData object, or if self and other are not compatible.

parse_ants(ant_str, print_toggle=False)[source]

Get antpair and polarization from parsing an aipy-style ant string.

Used to support the select function. Generates two lists of antenna pair tuples and polarization indices based on parsing of the string ant_str. If no valid polarizations (pseudo-Stokes params, or combinations of [lr] or [xy]) or antenna numbers are found in ant_str, ant_pairs_nums and polarizations are returned as None.

Parameters:

ant_str (str) – String containing antenna information to parse. Can be ‘all’, ‘auto’, ‘cross’, or combinations of antenna numbers and polarization indicators ‘l’ and ‘r’ or ‘x’ and ‘y’. Minus signs can also be used in front of an antenna number or baseline to exclude it from being output in ant_pairs_nums. If ant_str has a minus sign as the first character, ‘all,’ will be added to the beginning of the string. See the tutorial for examples of valid strings and their behavior.
print_toggle (bool) – Boolean for printing parsed baselines for a visual user check.

Returns:

ant_pairs_nums (list of tuples of int or None) – List of tuples containing the parsed pairs of antenna numbers, or None if ant_str is ‘all’ or a pseudo-Stokes polarizations.
polarizations (list of int or None) – List of desired polarizations or None if ant_str does not contain a polarization specification.

select(antenna_nums=None, antenna_names=None, ant_str=None, bls=None, frequencies=None, freq_chans=None, times=None, time_range=None, lsts=None, lst_range=None, polarizations=None, blt_inds=None, phase_center_ids=None, catalog_names=None, inplace=True, keep_all_metadata=True, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False)[source]

Downselect data to keep on the object along various axes.

Axes that can be selected along include antenna names or numbers, antenna pairs, frequencies, times and polarizations. Specific baseline-time indices can also be selected, but this is not commonly used. The history attribute on the object will be updated to identify the operations performed.

Parameters:

antenna_nums (array_like of int, optional) – The antennas numbers to keep in the object (antenna positions and names for the removed antennas will be retained unless keep_all_metadata is False). This cannot be provided if antenna_names is also provided.
antenna_names (array_like of str, optional) – The antennas names to keep in the object (antenna positions and names for the removed antennas will be retained unless keep_all_metadata is False). This cannot be provided if antenna_nums is also provided.
bls (list of tuple, optional) – A list of antenna number tuples (e.g. [(0, 1), (3, 2)]) or a list of baseline 3-tuples (e.g. [(0, 1, ‘xx’), (2, 3, ‘yy’)]) specifying baselines to keep in the object. For length-2 tuples, the ordering of the numbers within the tuple does not matter. For length-3 tuples, the polarization string is in the order of the two antennas. If length-3 tuples are provided, polarizations must be None.
ant_str (str, optional) – A string containing information about what antenna numbers and polarizations to keep in the object. Can be ‘auto’, ‘cross’, ‘all’, or combinations of antenna numbers and polarizations (e.g. ‘1’, ‘1_2’, ‘1x_2y’). See tutorial for more examples of valid strings and the behavior of different forms for ant_str. If ‘1x_2y,2y_3y’ is passed, both polarizations ‘xy’ and ‘yy’ will be kept for both baselines (1, 2) and (2, 3) to return a valid pyuvdata object. An ant_str cannot be passed in addition to any of antenna_nums, antenna_names, bls args or the polarizations parameters, if it is a ValueError will be raised.
frequencies (array_like of float, optional) – The frequencies to keep in the object, each value passed here should exist in the freq_array.
freq_chans (array_like of int, optional) – The frequency channel numbers to keep in the object.
times (array_like of float, optional) – The times to keep in the object, each value passed here should exist in the time_array. Cannot be used with time_range, lsts, or lst_array.
time_range (array_like of float, optional) – The time range in Julian Date to keep in the object, must be length 2. Some of the times in the object should fall between the first and last elements. Cannot be used with times.
lsts (array_like of float, optional) – The local sidereal times (LSTs) to keep in the object, each value passed here should exist in the lst_array. Cannot be used with times, time_range, or lst_range.
lst_range (array_like of float, optional) – The local sidereal time (LST) range in radians to keep in the object, must be of length 2. Some of the LSTs in the object should fall between the first and last elements. If the second value is smaller than the first, the LSTs are treated as having phase-wrapped around LST = 2*pi = 0, and the LSTs kept on the object will run from the larger value, through 0, and end at the smaller value.
polarizations (array_like of int or str, optional) – The polarizations numbers to keep in the object, each value passed here should exist in the polarization_array. If passing strings, the canonical polarization strings (e.g. “xx”, “rr”) are supported and if the x_orientation attribute is set, the physical dipole strings (e.g. “nn”, “ee”) are also supported.
blt_inds (array_like of int, optional) – The baseline-time indices to keep in the object. This is not commonly used.
phase_center_ids (array_like of int, optional) – Phase center IDs to keep on the object (effectively a selection on baseline-times). Cannot be used with catalog_names.
catalog_names (str or array-like of str, optional) – The names of the phase centers (sources) to keep in the object, which should match exactly in spelling and capitalization. Cannot be used with phase_center_ids.
inplace (bool) – Option to perform the select directly on self or return a new UVData object with just the selected data (the default is True, meaning the select will be done on self).
keep_all_metadata (bool) – Option to keep all the metadata associated with antennas, even those that do do not have data associated with them after the select option.
run_check (bool) – Option to check for the existence and proper shapes of parameters after downselecting data on this object (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after downselecting data on this object (the default is True, meaning the acceptable range check will be done).
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.

Returns:

UVData object or None – None is returned if inplace is True, otherwise a new UVData object with just the selected data is returned

Raises:

ValueError – If any of the parameters are set to inappropriate values.

upsample_in_time(max_int_time, blt_order='time', minor_order='baseline', summing_correlator_mode=False, allow_drift=False, astrometry_library=None)[source]

Resample to a shorter integration time.

This method will resample a UVData object such that all data samples have an integration time less than or equal to the max_int_time. The new samples are copied from the original samples (not interpolated).

Parameters:

max_int_time (float) – Maximum integration time to upsample to in seconds.
blt_order (str) – Major baseline ordering for output object. Default is “time”. See the documentation on the reorder_blts method for more info.
minor_order (str) – Minor baseline ordering for output object. Default is “baseline”.
summing_correlator_mode (bool) – Option to split the flux from the original samples into the new samples rather than duplicating the original samples in all the new samples (undoing an integration rather than an average) to emulate undoing the behavior in some correlators (e.g. HERA).
allow_drift (bool) – Option to allow resampling of unprojected or driftscan data. If this is False, unprojected or driftscan data will be phased to the ra/dec of zenith before resampling and then unprojected or rephased to a driftscan after resampling. Note that resampling unprojected or driftscan phased data may result in unexpected behavior.
astrometry_library (str) – Library to use for calculating the LSTs after upsampling. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location is a MoonLocation object, in which case the default is astropy.

Returns:

None

downsample_in_time(min_int_time=None, n_times_to_avg=None, blt_order='time', minor_order='baseline', keep_ragged=True, summing_correlator_mode=False, allow_drift=False, astrometry_library=None)[source]

Average to a longer integration time.

This method will average a UVData object either by an integer factor (by setting n_times_to_avg) or by a factor that can differ by baseline-time sample such that after averaging, the samples have an integration time greater than or equal to the min_int_time (up to the tolerance on the integration_time).

Note that if the integrations for a baseline do not divide evenly by the n_times_to_avg or into the specified min_int_time, the final integrations for that baseline may have integration times less than min_int_time or be composed of fewer input integrations than n_times_to_avg. This behavior can be controlled with the keep_ragged argument. The new samples are averages of the original samples (not interpolations).

Parameters:

min_int_time (float) – Minimum integration time to average the UVData integration_time to in seconds.
n_times_to_avg (int) – Number of time integrations to average together.
blt_order (str) – Major baseline ordering for output object. Default is “time”. See the documentation on the reorder_blts method for more details.
minor_order (str) – Minor baseline ordering for output object. Default is “baseline”.
keep_ragged (bool) – When averaging baselines that do not evenly divide into min_int_time, or that have a number of integrations that do not evenly divide by n_times_to_avg, keep_ragged controls whether to keep the (averaged) integrations corresponding to the remaining samples (keep_ragged=True), or discard them (keep_ragged=False).
summing_correlator_mode (bool) – Option to integrate the flux from the original samples rather than average the flux to emulate the behavior in some correlators (e.g. HERA).
allow_drift (bool) – Option to allow resampling of unprojected or driftscan data. If this is False, unprojected or driftscan data will be phased to the ra/dec of zenith before resampling and then unprojected or rephased to a driftscan after resampling. Note that resampling unprojected or driftscan phased data may result in unexpected behavior.
astrometry_library (str) – Library to use for calculating the LSTs after downsampling. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location is a MoonLocation object, in which case the default is astropy.

Returns:

None

Raises:

ValueError – If neither or both of min_int_time and n_times_to_avg are set. If there’s only one time on the object. If min_int_time is more than 100 time the max integration time. If n_times_to_avg is not an integer.

resample_in_time(target_time, only_downsample=False, only_upsample=False, blt_order='time', minor_order='baseline', keep_ragged=True, summing_correlator_mode=False, allow_drift=False, astrometry_library=None)[source]

Intelligently upsample or downsample a UVData object to the target time.

Parameters:

target_time (float) – The target integration time to resample to, in seconds.
only_downsample (bool) – Option to only call bda_downsample.
only_upsample (bool) – Option to only call bda_upsample.
blt_order (str) – Major baseline ordering for output object. Default is “time”. See the documentation on the reorder_blts method for more details.
minor_order (str) – Minor baseline ordering for output object. Default is “baseline”.
keep_ragged (bool) – When averaging baselines that do not evenly divide into min_int_time, keep_ragged controls whether to keep the (summed) integrations corresponding to the remaining samples (keep_ragged=True), or discard them (keep_ragged=False). Note this option only applies to the bda_downsample method.
summing_correlator_mode (bool) – Option to integrate or split the flux from the original samples rather than average or duplicate the flux from the original samples to emulate the behavior in some correlators (e.g. HERA).
allow_drift (bool) – Option to allow resampling of unprojected or driftscan data. If this is False, unprojected or driftscan data will be phased to the ra/dec of zenith before resampling and then unprojected or rephased to a driftscan after resampling. Note that resampling unprojected or driftscan phased data may result in unexpected behavior.
astrometry_library (str) – Library to use for calculating the LSTs after resampling. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location is a MoonLocation object, in which case the default is astropy.

Returns:

None

frequency_average(n_chan_to_avg, summing_correlator_mode=False, propagate_flags=False, respect_spws=True, keep_ragged=None)[source]

Average in frequency.

Does a simple average over an integer number of input channels, leaving flagged samples out of the average.

In the future, this method will support setting the frequency to the true mean of the averaged non-flagged frequencies rather than the simple mean of the input channel frequencies. For now it does not.

Parameters:

n_chan_to_avg (int) – Number of channels to average together. See the keep_ragged parameter for the handling if the number of frequencies per spectral window does not divide evenly by this number.
summing_correlator_mode (bool) – Option to integrate the flux from the original samples rather than average the flux from the original samples to emulate the behavior in some correlators (e.g. HERA).
propagate_flags (bool) – Option to flag an averaged entry even if some of its contributors are not flagged. The averaged result will still leave the flagged samples out of the average, except when all contributors are flagged.
respect_spws (bool) – Option to respect spectral window boundaries when averaging. If True, do not average across spectral window boundaries. Setting this to False will result in the averaged object having a single spectral window.
keep_ragged (bool) – If the number of frequencies in each spectral window (or Nfreqs if respect_spw=False) does not divide evenly by n_chan_to_avg, this option controls whether the frequencies at the end of the spectral window will be dropped to make it evenly divisable (keep_ragged=False) or will be combined into a smaller frequency bin (keep_ragged=True). Note that if ragged frequencies are kept, the final averaged object will have future_array_shapes=True because it will have varying channel widths.

get_redundancies(tol=1.0, use_antpos=False, include_conjugates=False, include_autos=True, conjugate_bls=False, use_grid_alg=None)[source]

Get redundant baselines to a given tolerance.

This can be used to identify redundant baselines present in the data, or find all possible redundant baselines given the antenna positions.

Parameters:

tol (float) – Redundancy tolerance in meters (default 1m).
use_antpos (bool) – Use antenna positions to find all possible redundant groups for this telescope (default False). The returned baselines are in the ‘u>0’ convention.
include_conjugates (bool) – Option to include baselines that are redundant under conjugation. Only used if use_antpos is False.
include_autos (bool) – Option to include autocorrelations in the full redundancy list. Only used if use_antpos is True.
conjugate_bls (bool) – If using antenna positions, this will conjugate baselines on this object to correspond with those in the returned groups.
use_grid_alg (bool) – Option to use the gridding based algorithm (developed by the HERA team) to find redundancies rather than the older clustering algorithm.

Returns:

baseline_groups (list of lists of int) – List of lists of redundant baseline numbers
vec_bin_centers (list of ndarray of float) – List of vectors describing redundant group uvw centers
lengths (list of float) – List of redundant group baseline lengths in meters
conjugates (list of int, or None, optional) – List of indices for baselines that must be conjugated to fit into their redundant groups. Will return None if use_antpos is True and include_conjugates is True Only returned if include_conjugates is True

Notes

If use_antpos is set, then this function will find all redundant baseline groups for this telescope, under the u>0 antenna ordering convention. If use_antpos is not set, this function will look for redundant groups in the data.

compress_by_redundancy(method='select', tol=1.0, inplace=True, keep_all_metadata=True, use_grid_alg=False)[source]

Downselect or average to only have one baseline per redundant group.

Either select the first baseline in the redundant group or average over the baselines in the redundant group. When averaging, only unflagged data are averaged and the nsample_array reflects the amount of unflagged data that was averaged over. In the case that all the data for a particular visibility to be averaged is flagged, all the flagged data is averaged (with an nsample value that represents all the data) but the flag array is set to True for that visibility.

Parameters:

tol (float) – Redundancy tolerance in meters, default is 1.0 corresponding to 1 meter. This specifies what tolerance to use when identifying baselines as redundant.
method (str) – Options are “select”, which just keeps the first baseline in each redundant group or “average” which averages over the baselines in each redundant group and assigns the average to the first baseline in the group.
inplace (bool) – Option to do selection on current object.
keep_all_metadata (bool) – Option to keep all the metadata associated with antennas, even those that do not remain after the select option.
use_grid_alg (bool) – Option to use the gridding based algorithm (developed by the HERA team) to find redundancies rather than the older clustering algorithm.

Returns:

UVData object or None – if inplace is False, return the compressed UVData object

inflate_by_redundancy(tol=1.0, blt_order='time', blt_minor_order=None, use_grid_alg=False)[source]

Expand data to full size, copying data among redundant baselines.

Note that this method conjugates baselines to the ‘u>0’ convention in order to inflate the redundancies.

Parameters:

tol (float) – Redundancy tolerance in meters, default is 1.0 corresponding to 1 meter.
blt_order (str) – string specifying primary order along the blt axis (see reorder_blts)
blt_minor_order (str) – string specifying minor order along the blt axis (see reorder_blts)
use_grid_alg (bool) – Option to use the gridding based algorithm (developed by the HERA team) to find redundancies rather than the older clustering algorithm.

read_fhd(filelist, **kwargs)[source]

Read in data from a list of FHD files.

Parameters:

filelist (array_like of str) – The list/array of FHD save files to read from. Must include at least one polarization file, a params file, a layout file and a flag file. An obs file is also required if read_data is False.
use_model (bool) – Option to read in the model visibilities rather than the dirty visibilities (the default is False, meaning the dirty visibilities will be read).
background_lsts (bool) – When set to True, the lst_array is calculated in a background thread.
read_data (bool) – Read in the visibility, nsample and flag data. If set to False, only the metadata will be read in. Setting read_data to False results in a metadata only object. If read_data is False, an obs file must be included in the filelist. Note that if read_data is False, Npols is derived from the obs file and reflects the number of polarizations used in the FHD run. If read_data is True, Npols is given by the number of visibility data files provided in filelist.
run_check (bool) – Option to check for the existence and proper shapes of parameters after after reading in the file (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after reading in the file (the default is True, meaning the acceptable range check will be done).
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.
check_autos (bool) – Check whether any auto-correlations have non-zero imaginary values in data_array (which should not mathematically exist). Default is True.
fix_autos (bool) – If auto-correlations with imaginary values are found, fix those values so that they are real-only in data_array. Default is True.
use_future_array_shapes (bool) – Option to convert to the future planned array shapes before the changes go into effect by removing the spectral window axis.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.

Raises:

IOError – If root file directory doesn’t exist.
ValueError – If required files are missing or multiple files for any polarization are included in filelist. If there is no recognized key for visibility weights in the flags_file.

read_mir(filepath, **kwargs)[source]

Read in data from an SMA MIR file.

Note that with the exception of filepath, most of the remaining parameters are used to sub-select a range of data.

Parameters:

filepath (str) – The file path to the MIR folder to read from.
antenna_nums (array_like of int, optional) – The antennas numbers to include when reading data into the object (antenna positions and names for the removed antennas will be retained unless keep_all_metadata is False). This cannot be provided if antenna_names is also provided.
antenna_names (array_like of str, optional) – The antennas names to include when reading data into the object (antenna positions and names for the removed antennas will be retained unless keep_all_metadata is False). This cannot be provided if antenna_nums is also provided.
bls (list of tuple, optional) – A list of antenna number tuples (e.g. [(0, 1), (3, 2)]) specifying baselines to include when reading data in to the object.
time_range (array_like of float, optional) – The time range in Julian Date to include when reading data into the object, must be length 2. Some of the times in the file should fall between the first and last elements.
lst_range (array_like of float, optional) – The local sidereal time (LST) range in radians to keep in the object, must be of length 2. Some of the LSTs in the object should fall between the first and last elements. If the second value is smaller than the first, the LSTs are treated as having phase-wrapped around LST = 2*pi = 0, and the LSTs kept on the object will run from the larger value, through 0, and end at the smaller value.
polarizations (array_like of int, optional) – The polarizations numbers to include when reading data into the object, each value passed here should exist in the polarization_array.
catalog_names (str or array-like of str) – The names of the phase centers (sources) to include when reading data into the object, which should match exactly in spelling and capitalization.
corrchunk (int or array-like of int) – Correlator “chunk” (spectral window) to include when reading data into the object, where 0 corresponds to the pseudo-continuum channel.
receivers (str or array-like of str) – The names of the receivers (“230”, “240”, “345”, “400”) to include when reading data into the object.
sidebands (str or array-like of str) – The names of the sidebands (“l” for lower, “u” for upper) to include when reading data into the object.
select_where (tuple or list of tuples, optional) – Argument to pass to the MirParser.select method, which will downselect which data is read into the object.
apply_flags (bool) – If set to True, apply “wideband” flags to the visibilities, which are recorded by the realtime system to denote when data are expected to be bad (e.g., antennas not on source, dewar warm). Default it true.
apply_tsys (bool) – If set to False, data are returned as correlation coefficients (normalized by the auto-correlations). Default is True, which instead scales the raw visibilities and forward-gain of the antenna to produce values in Jy (uncalibrated).
apply_dedoppler (bool) – If set to True, data will be corrected for any doppler-tracking performed during observations, and brought into the topocentric rest frame (default for UVData objects). Default is False.
pseudo_cont (boolean) – Read in only pseudo-continuum values. Default is false.
rechunk (int) – Number of channels to average over when reading in the dataset. Optional argument, typically required to be a power of 2.
compass_soln (str) – Optional argument, specifying the path of COMPASS-derived flagging and bandpass gains solutions, which are applied prior to any potential spectral averaging (as triggered by using the rechunk keyword).
swarm_only (bool) – By default, only SMA SWARM data is loaded. If set to false, this will also enable loading of older ASIC data.
codes_check (bool) – Option to check the cross-check the internal metadata codes, and deselect data without valid matches, useful for automatically handling various data recording issues. Default is True.
run_check (bool) – Option to check for the existence and proper shapes of parameters before writing the file.
check_extra (bool) – Option to check optional parameters as well as required ones.
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters before writing the file.
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvw coordinates match antenna positions does not pass.
allow_flex_pol (bool) – If only one polarization per spectral window is read (and the polarization differs from window to window), allow for the UVData object to use “flexible polarization”, which compresses the polarization-axis of various attributes to be of length 1, sets the flex_spw_polarization_array attribute to define the polarization per spectral window. Default is True.
check_autos (bool) – Check whether any auto-correlations have non-zero imaginary values in data_array (which should not mathematically exist). Default is True.
fix_autos (bool) – If auto-correlations with imaginary values are found, fix those values so that they are real-only in data_array. Default is True.

read_miriad(filepath, **kwargs)[source]

Read in data from a miriad file.

Parameters:

filepath (str) – The miriad root directory to read from.
antenna_nums (array_like of int, optional) – The antennas numbers to read into the object.
bls (list of tuple, optional) – A list of antenna number tuples (e.g. [(0, 1), (3, 2)]) or a list of baseline 3-tuples (e.g. [(0, 1, ‘xx’), (2, 3, ‘yy’)]) specifying baselines to include when reading data into the object. For length-2 tuples, the ordering of the numbers within the tuple does not matter. For length-3 tuples, the polarization string is in the order of the two antennas. If length-3 tuples are provided, polarizations must be None.
ant_str (str, optional) – A string containing information about what antenna numbers and polarizations to include when reading data into the object. Can be ‘auto’, ‘cross’, ‘all’, or combinations of antenna numbers and polarizations (e.g. ‘1’, ‘1_2’, ‘1x_2y’). See tutorial for more examples of valid strings and the behavior of different forms for ant_str. If ‘1x_2y,2y_3y’ is passed, both polarizations ‘xy’ and ‘yy’ will be kept for both baselines (1, 2) and (2, 3) to return a valid pyuvdata object. An ant_str cannot be passed in addition to any of antenna_nums, bls or polarizations parameters, if it is a ValueError will be raised.
polarizations (array_like of int or str, optional) – List of polarization integers or strings to read-in. e.g. [‘xx’, ‘yy’, …]
time_range (list of float, optional) – len-2 list containing min and max range of times in Julian Date to include when reading data into the object. e.g. [2458115.20, 2458115.40]
read_data (bool) – Read in the uvws, times, visibility and flag data. If set to False, only the metadata that can be read quickly (without reading the data) will be read in. For Miriad, some of the normally required metadata are not fast to read in (e.g. uvws, times) so will not be read in if this keyword is False. Therefore, setting read_data to False results in an incompletely defined object (check will not pass).
phase_type (str, optional) – Deprecated, use the projected parameter insted. Option to specify the phasing status of the data. Options are ‘drift’, ‘phased’ or None. ‘drift’ is the same as setting the projected parameter to False, ‘phased’ is the same as setting the projected parameter to True. Ignored if projected is set.
projected (bool or None) – Option to force the dataset to be labelled as projected or unprojected regardless of the evidence in the file. The default is None which means that the projection will be set based on the file contents. Be careful setting this keyword unless you are confident about the contents of the file.
correct_lat_lon (bool) – Option to update the latitude and longitude from the known_telescopes list if the altitude is missing.
background_lsts (bool) – When set to True, the lst_array is calculated in a background thread.
run_check (bool) – Option to check for the existence and proper shapes of parameters after after reading in the file (the default is True, meaning the check will be run). Ignored if read_data is False.
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked). Ignored if read_data is False.
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after reading in the file (the default is True, meaning the acceptable range check will be done). Ignored if read_data is False.
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.
calc_lst (bool) – Recalculate the LST values that are present within the file, useful in cases where the “online” calculate values have precision or value errors. Default is True.
fix_old_proj (bool) – Applies a fix to uvw-coordinates and phasing, assuming that the old phase method was used prior to writing the data, which had errors of the order of one part in 1e4 - 1e5. See the phasing memo for more details.
fix_use_ant_pos (bool) – If setting fix_old_proj to True, use the antenna positions to derive the correct uvw-coordinates rather than using the baseline vectors. Default is True.
check_autos (bool) – Check whether any auto-correlations have non-zero imaginary values in data_array (which should not mathematically exist). Default is True.
fix_autos (bool) – If auto-correlations with imaginary values are found, fix those values so that they are real-only in data_array. Default is True.
use_future_array_shapes (bool) – Option to convert to the future planned array shapes before the changes go into effect by removing the spectral window axis.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.

Raises:

IOError – If root file directory doesn’t exist.
ValueError – If incompatible select keywords are set (e.g. ant_str with other antenna selectors, times and time_range) or select keywords exclude all data or if keywords are set to the wrong type. If the metadata are not internally consistent.

read_ms(filepath, **kwargs)[source]

Read in a casa measurement set.

Parameters:

filepath (str) – The measurement set root directory to read from.
data_column (str) – name of CASA data column to read into data_array. Options are: ‘DATA’, ‘MODEL’, or ‘CORRECTED_DATA’
pol_order (str or None) – Option to specify polarizations order convention, options are ‘CASA’, ‘AIPS’, or None (no reordering). Default is ‘AIPS’.
background_lsts (bool) – When set to True, the lst_array is calculated in a background thread.
run_check (bool) – Option to check for the existence and proper shapes of parameters after after reading in the file (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after reading in the file (the default is True, meaning the acceptable range check will be done).
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.
ignore_single_chan (bool) – Some measurement sets (e.g., those from ALMA) use single channel spectral windows for recording pseudo-continuum channels or storing other metadata in the track when the telescopes are not on source. Because of the way the object is strutured (where all spectral windows are assumed to be simultaneously recorded), this can significantly inflate the size and memory footprint of UVData objects. By default, single channel windows are ignored to avoid this issue, although they can be included if setting this parameter equal to True.
raise_error (bool) – The measurement set format allows for different spectral windows and polarizations to have different metdata for the same time-baseline combination, but UVData objects do not. It also allows for timescales that are not supported by astropy. If any of these problems are detected, by default the reader will throw an error. However, if set to False, the reader will simply give a warning and try to do the best it can. If the problem is with differing metadata, it will use the first value read in the file as the “correct” metadata in the UVData object. If the problem is with the timescale, it will just assume UTC.
read_weights (bool) – Read in the weights from the MS file, default is True. If false, the method will set the nsamples_array to the same uniform value (namely 1.0).
allow_flex_pol (bool) – If only one polarization per spectral window is read (and the polarization differs from window to window), allow for the UVData object to use “flexible polarization”, which compresses the polarization-axis of various attributes to be of length 1, sets the flex_spw_polarization_array attribute to define the polarization per spectral window. Default is True.
check_autos (bool) – Check whether any auto-correlations have non-zero imaginary values in data_array (which should not mathematically exist). Default is True.
fix_autos (bool) – If auto-correlations with imaginary values are found, fix those values so that they are real-only in data_array. Default is True.
use_future_array_shapes (bool) – Option to convert to the future planned array shapes before the changes go into effect by removing the spectral window axis.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.

Raises:

IOError – If root file directory doesn’t exist.
ValueError – If the data_column is not set to an allowed value. If the data are have multiple subarrays or are multi source or have multiple spectral windows. If the data have multiple data description ID values.

read_mwa_corr_fits(filelist, **kwargs)[source]

Read in MWA correlator gpu box files.

The default settings remove some of the instrumental effects in the bandpass by dividing out the coarse band shape (for legacy data only) and the digital gains, and applying a cable length correction. If the desired output is raw correlator data, set remove_dig_gains=False, remove_coarse_band=False, correct_cable_len=False, and phase_to_pointing_center=False.

Parameters:

filelist (list of str) – The list of MWA correlator files to read from. Must include at least one fits file and only one metafits file per data set.
use_aoflagger_flags (bool) – Option to use aoflagger mwaf flag files. Defaults to true if aoflagger flag files are submitted.
remove_dig_gains (bool) – Option to divide out digital gains.
remove_coarse_band (bool) – Option to divide out coarse band shape.
correct_cable_len (bool) – Option to apply a cable delay correction.
correct_van_vleck (bool) – Option to apply a van vleck correction.
cheby_approx (bool) – Only used if correct_van_vleck is True. Option to implement the van vleck correction with a chebyshev polynomial approximation.
flag_small_auto_ants (bool) – Only used if correct_van_vleck is True. Option to completely flag any antenna for which the autocorrelation falls below a threshold found by the Van Vleck correction to indicate bad data. Specifically, the threshold used is 0.5 * integration_time * channel_width. If set to False, only the times and frequencies at which the auto is below the threshold will be flagged for the antenna.
phase_to_pointing_center (bool) – Option to phase to the observation pointing center.
propagate_coarse_flags (bool) – Option to propagate flags for missing coarse channel integrations across frequency.
flag_init (bool) – Set to True in order to do routine flagging of coarse channel edges, start or end integrations, or the center fine channel of each coarse channel. See associated keywords.
edge_width (float) – Only used if flag_init is True. The width to flag on the edge of each coarse channel, in hz. Errors if not equal to integer multiple of channel_width. Set to 0 for no edge flagging.
start_flag (float or str) – Only used if flag_init is True. The number of seconds to flag at the beginning of the observation. Set to 0 for no flagging. Default is ‘goodtime’, which uses information in the metafits file to determine the length of time that should be flagged. Errors if input is not a float or ‘goodtime’. Errors if float input is not equal to an integer multiple of the integration time.
end_flag (floats) – Only used if flag_init is True. The number of seconds to flag at the end of the observation. Set to 0 for no flagging. Errors if not equal to an integer multiple of the integration time.
flag_dc_offset (bool) – Only used if flag_init is True. Set to True to flag the center fine channel of each coarse channel.
remove_flagged_ants (bool) – Option to perform a select to remove antennas flagged in the metafits file. If correct_van_vleck and flag_small_auto_ants are both True then antennas flagged by the Van Vleck correction are also removed.
background_lsts (bool) – When set to True, the lst_array is calculated in a background thread.
read_data (bool) – Read in the visibility, nsample and flag data. If set to False, only the metadata will be read in. Setting read_data to False results in a metadata only object.
data_array_dtype (numpy dtype) – Datatype to store the output data_array as. Must be either np.complex64 (single-precision real and imaginary) or np.complex128 (double-precision real and imaginary).
nsample_array_dtype (numpy dtype) – Datatype to store the output nsample_array as. Must be either np.float64 (double-precision), np.float32 (single-precision), or np.float16 (half-precision). Half-precision is only recommended for cases where no sampling or averaging of baselines will occur, because round-off errors can be quite large (~1e-3).
run_check (bool) – Option to check for the existence and proper shapes of parameters after after reading in the file (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after reading in the file (the default is True, meaning the acceptable range check will be done).
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.
check_autos (bool) – Check whether any auto-correlations have non-zero imaginary values in data_array (which should not mathematically exist). Default is True.
fix_autos (bool) – If auto-correlations with imaginary values are found, fix those values so that they are real-only in data_array. Default is True.
use_future_array_shapes (bool) – Option to convert to the future planned array shapes before the changes go into effect by removing the spectral window axis.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.

Raises:

ValueError – If required files are missing or multiple files metafits files are included in filelist. If files from different observations are included in filelist. If files in fileslist have different fine channel widths If file types other than fits, metafits, and mwaf files are included in filelist.

read_uvfits(filename, **kwargs)[source]

Read in header, metadata and data from a uvfits file.

Parameters:

filename (str) – The uvfits file to read from.
antenna_nums (array_like of int, optional) – The antennas numbers to include when reading data into the object (antenna positions and names for the removed antennas will be retained unless keep_all_metadata is False). This cannot be provided if antenna_names is also provided. Ignored if read_data is False.
antenna_names (array_like of str, optional) – The antennas names to include when reading data into the object (antenna positions and names for the removed antennas will be retained unless keep_all_metadata is False). This cannot be provided if antenna_nums is also provided. Ignored if read_data is False.
bls (list of tuple, optional) – A list of antenna number tuples (e.g. [(0, 1), (3, 2)]) or a list of baseline 3-tuples (e.g. [(0, 1, ‘xx’), (2, 3, ‘yy’)]) specifying baselines to include when reading data into the object. For length-2 tuples, the ordering of the numbers within the tuple does not matter. For length-3 tuples, the polarization string is in the order of the two antennas. If length-3 tuples are provided, polarizations must be None. Ignored if read_data is False.
ant_str (str, optional) – A string containing information about what antenna numbers and polarizations to include when reading data into the object. Can be ‘auto’, ‘cross’, ‘all’, or combinations of antenna numbers and polarizations (e.g. ‘1’, ‘1_2’, ‘1x_2y’). See tutorial for more examples of valid strings and the behavior of different forms for ant_str. If ‘1x_2y,2y_3y’ is passed, both polarizations ‘xy’ and ‘yy’ will be kept for both baselines (1, 2) and (2, 3) to return a valid pyuvdata object. An ant_str cannot be passed in addition to any of antenna_nums, antenna_names, bls args or the polarizations parameters, if it is a ValueError will be raised. Ignored if read_data is False.
frequencies (array_like of float, optional) – The frequencies to include when reading data into the object, each value passed here should exist in the freq_array.
freq_chans (array_like of int, optional) – The frequency channel numbers to include when reading data into the object. Ignored if read_data is False.
times (array_like of float, optional) – The times to include when reading data into the object, each value passed here should exist in the time_array. Cannot be used with time_range, lsts, or lst_array.
time_range (array_like of float, optional) – The time range in Julian Date to keep in the object, must be length 2. Some of the times in the object should fall between the first and last elements. Cannot be used with times.
lsts (array_like of float, optional) – The local sidereal times (LSTs) to keep in the object, each value passed here should exist in the lst_array. Cannot be used with times, time_range, or lst_range.
lst_range (array_like of float, optional) – The local sidereal time (LST) range in radians to keep in the object, must be of length 2. Some of the LSTs in the object should fall between the first and last elements. If the second value is smaller than the first, the LSTs are treated as having phase-wrapped around LST = 2*pi = 0, and the LSTs kept on the object will run from the larger value, through 0, and end at the smaller value.
polarizations (array_like of int, optional) – The polarizations numbers to include when reading data into the object, each value passed here should exist in the polarization_array. Ignored if read_data is False.
blt_inds (array_like of int, optional) – The baseline-time indices to include when reading data into the object. This is not commonly used. Ignored if read_data is False.
phase_center_ids (array_like of int, optional) – Phase center IDs to include when reading data into the object (effectively a selection on baseline-times). Cannot be used with catalog_names.
catalog_names (str or array-like of str, optional) – The names of the phase centers (sources) to include when reading data into the object, which should match exactly in spelling and capitalization. Cannot be used with phase_center_ids.
keep_all_metadata (bool) – Option to keep all the metadata associated with antennas, even those that do not have data associated with them after the select option.
read_data (bool) – Read in the visibility, nsample and flag data. If set to False, only the metadata will be read in. Setting read_data to False results in a metadata only object.
background_lsts (bool) – When set to True, the lst_array is calculated in a background thread.
run_check (bool) – Option to check for the existence and proper shapes of parameters after after reading in the file (the default is True, meaning the check will be run). Ignored if read_data is False.
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked). Ignored if read_data is False.
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after reading in the file (the default is True, meaning the acceptable range check will be done). Ignored if read_data is False.
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.
fix_old_proj (bool) – Applies a fix to uvw-coordinates and phasing, assuming that the old phase method was used prior to writing the data, which had errors of the order of one part in 1e4 - 1e5. See the phasing memo for more details. Default is False.
fix_use_ant_pos (bool) – If setting fix_old_proj to True, use the antenna positions to derive the correct uvw-coordinates rather than using the baseline vectors. Default is True.
check_autos (bool) – Check whether any auto-correlations have non-zero imaginary values in data_array (which should not mathematically exist). Default is True.
fix_autos (bool) – If auto-correlations with imaginary values are found, fix those values so that they are real-only in data_array. Default is True.
use_future_array_shapes (bool) – Option to convert to the future planned array shapes before the changes go into effect by removing the spectral window axis.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.

Raises:

IOError – If filename doesn’t exist.
ValueError – If incompatible select keywords are set (e.g. ant_str with other antenna selectors, times and time_range) or select keywords exclude all data or if keywords are set to the wrong type. If the metadata are not internally consistent or missing.

read_uvh5(filename, **kwargs)[source]

Read in data from a UVH5 file.

Parameters:

filename (str) – The UVH5 file to read from.
antenna_nums (array_like of int, optional) – The antennas numbers to include when reading data into the object (antenna positions and names for the removed antennas will be retained unless keep_all_metadata is False). This cannot be provided if antenna_names is also provided. Ignored if read_data is False.
antenna_names (array_like of str, optional) – The antennas names to include when reading data into the object (antenna positions and names for the removed antennas will be retained unless keep_all_metadata is False). This cannot be provided if antenna_nums is also provided. Ignored if read_data is False.
bls (list of tuple, optional) – A list of antenna number tuples (e.g. [(0, 1), (3, 2)]) or a list of baseline 3-tuples (e.g. [(0, 1, ‘xx’), (2, 3, ‘yy’)]) specifying baselines to include when reading data into the object. For length-2 tuples, the ordering of the numbers within the tuple does not matter. For length-3 tuples, the polarization string is in the order of the two antennas. If length-3 tuples are provided, polarizations must be None. Ignored if read_data is False.
ant_str (str, optional) – A string containing information about what antenna numbers and polarizations to include when reading data into the object. Can be ‘auto’, ‘cross’, ‘all’, or combinations of antenna numbers and polarizations (e.g. ‘1’, ‘1_2’, ‘1x_2y’). See tutorial for more examples of valid strings and the behavior of different forms for ant_str. If ‘1x_2y,2y_3y’ is passed, both polarizations ‘xy’ and ‘yy’ will be kept for both baselines (1, 2) and (2, 3) to return a valid pyuvdata object. An ant_str cannot be passed in addition to any of antenna_nums, antenna_names, bls args or the polarizations parameters, if it is a ValueError will be raised. Ignored if read_data is False.
frequencies (array_like of float, optional) – The frequencies to include when reading data into the object, each value passed here should exist in the freq_array. Ignored if read_data is False.
freq_chans (array_like of int, optional) – The frequency channel numbers to include when reading data into the object. Ignored if read_data is False.
times (array_like of float, optional) – The times to include when reading data into the object, each value passed here should exist in the time_array. Cannot be used with time_range, lsts, or lst_array.
time_range (array_like of float, optional) – The time range in Julian Date to include when reading data into the object, must be length 2. Some of the times in the file should fall between the first and last elements. Cannot be used with times.
lsts (array_like of float, optional) – The local sidereal times (LSTs) to keep in the object, each value passed here should exist in the lst_array. Cannot be used with times, time_range, or lst_range.
lst_range (array_like of float, optional) – The local sidereal time (LST) range in radians to keep in the object, must be of length 2. Some of the LSTs in the object should fall between the first and last elements. If the second value is smaller than the first, the LSTs are treated as having phase-wrapped around LST = 2*pi = 0, and the LSTs kept on the object will run from the larger value, through 0, and end at the smaller value.
polarizations (array_like of int, optional) – The polarizations numbers to include when reading data into the object, each value passed here should exist in the polarization_array. Ignored if read_data is False.
blt_inds (array_like of int, optional) – The baseline-time indices to include when reading data into the object. This is not commonly used. Ignored if read_data is False.
phase_center_ids (array_like of int, optional) – Phase center IDs to include when reading data into the object (effectively a selection on baseline-times). Cannot be used with catalog_names.
catalog_names (str or array-like of str, optional) – The names of the phase centers (sources) to include when reading data into the object, which should match exactly in spelling and capitalization. Cannot be used with phase_center_ids.
keep_all_metadata (bool) – Option to keep all the metadata associated with antennas, even those that do not have data associated with them after the select option.
read_data (bool) – Read in the visibility, nsample and flag data. If set to False, only the metadata will be read in. Setting read_data to False results in a metadata only object.
data_array_dtype (numpy dtype) – Datatype to store the output data_array as. Must be either np.complex64 (single-precision real and imaginary) or np.complex128 (double- precision real and imaginary). Only used if the datatype of the visibility data on-disk is not ‘c8’ or ‘c16’.
multidim_index (bool) – If True, attempt to index the HDF5 dataset simultaneously along all data axes. Otherwise index one axis at-a-time. This only works if data selection is sliceable along all but one axis. If indices are not well-matched to data chunks, this can be slow.
remove_flex_pol (bool) – If True and if the file is a flex_pol file, convert back to a standard UVData object.
background_lsts (bool) – When set to True, the lst_array is calculated in a background thread.
run_check (bool) – Option to check for the existence and proper shapes of parameters after after reading in the file (the default is True, meaning the check will be run). Ignored if read_data is False.
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked). Ignored if read_data is False.
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after reading in the file (the default is True, meaning the acceptable range check will be done). Ignored if read_data is False.
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.
fix_old_proj (bool) – Applies a fix to uvw-coordinates and phasing, assuming that the old phase method was used prior to writing the data, which had errors of the order of one part in 1e4 - 1e5. See the phasing memo for more details. Default is to apply the correction if the attributes phase_center_app_ra and phase_center_app_dec are missing (as they were introduced alongside the new phasing method).
fix_use_ant_pos (bool) – If setting fix_old_proj to True, use the antenna positions to derive the correct uvw-coordinates rather than using the baseline vectors. Default is True.
check_autos (bool) – Check whether any auto-correlations have non-zero imaginary values in data_array (which should not mathematically exist). Default is True.
fix_autos (bool) – If auto-correlations with imaginary values are found, fix those values so that they are real-only in data_array. Default is True.
use_future_array_shapes (bool) – Option to convert to the future planned array shapes before the changes go into effect by removing the spectral window axis.
blt_order (tuple of str or “determine”, optional) – The order of the baseline-time axis in the file. This can be determined, or read directly from file, however since it has been optional in the past, many existing files do not contain it in the metadata. Some reading operations are significantly faster if this is known, so providing it here can provide a speedup. Default is to try and read it from file, and if not there, just leave it as None. Set to “determine” to auto-detect the blt_order from the metadata (takes extra time to do so).
blts_are_rectangular (bool, optional) – Whether the baseline-time axis is rectangular. This can be read from metadata in new files, but many old files do not contain it. If not provided, the rectangularity will be determined from the data. This is a non-negligible operation, so if you know it, it can be provided here to speed up reading.
time_axis_faster_than_bls (bool, optional) – If blts are rectangular, this variable specifies whether the time axis is the fastest-moving virtual axis. Various reading functions benefit from knowing this, so if it is known, it can be provided here to speed up reading. It will be determined from the data if not provided.
recompute_nbls (bool, optional) – Whether to recompute the number of unique baselines from the data. Before v1.2 of the UVH5 spec, it was possible to have an incorrect number of baselines in the header without error, so this provides an opportunity to rectify it. Old HERA files (< March 2023) may have this issue, but in this case the correct number of baselines can be computed more quickly than by fully re=computing, and so we do this.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.

Returns:

None

Raises:

IOError – If filename doesn’t exist.
ValueError – If the data_array_dtype is not a complex dtype. If incompatible select keywords are set (e.g. ant_str with other antenna selectors, times and time_range) or select keywords exclude all data or if keywords are set to the wrong type.

read(filename, axis=None, file_type=None, read_data=True, skip_bad_files=False, background_lsts=True, astrometry_library=None, ignore_name=False, use_future_array_shapes=False, allow_rephase=None, make_multi_phase=False, antenna_nums=None, antenna_names=None, ant_str=None, bls=None, catalog_names=None, frequencies=None, freq_chans=None, times=None, time_range=None, lsts=None, lst_range=None, polarizations=None, blt_inds=None, phase_center_ids=None, keep_all_metadata=True, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, check_autos=True, fix_autos=True, phase_type=None, projected=None, correct_lat_lon=True, calc_lst=True, fix_old_proj=None, fix_use_ant_pos=True, use_model=False, data_column='DATA', pol_order='AIPS', ignore_single_chan=True, raise_error=True, read_weights=True, allow_flex_pol=True, multidim_index=False, remove_flex_pol=True, blt_order: tuple[str] | ~typing.Literal['determine'] | None = None, blts_are_rectangular: bool | None = None, time_axis_faster_than_bls: bool | None = None, data_array_dtype=<class 'numpy.complex128'>, use_aoflagger_flags=None, remove_dig_gains=True, remove_coarse_band=True, correct_cable_len=None, correct_van_vleck=False, cheby_approx=True, flag_small_auto_ants=True, propagate_coarse_flags=True, flag_init=True, edge_width=80000.0, start_flag='goodtime', end_flag=0.0, flag_dc_offset=True, remove_flagged_ants=True, phase_to_pointing_center=False, nsample_array_dtype=<class 'numpy.float32'>, corrchunk=None, receivers=None, sidebands=None, mir_select_where=None, apply_tsys=True, apply_flags=True, apply_dedoppler=False, pseudo_cont=False, rechunk=None, compass_soln=None, swarm_only=True, codes_check=True, recompute_nbls: bool | None = None)[source]

Read a generic file into a UVData object.

This method supports a number of different types of files. Universal parameters (required and optional) are listed directly below, followed by parameters used by all file types related to phasing, selecting on read (partial read) and checking. Each file type also has its own set of optional parameters that are listed at the end of this docstring.

Parameters:

filename (str or array_like of str) – The file(s) or list(s) (or array(s)) of files to read from.
file_type (str) – One of [‘uvfits’, ‘miriad’, ‘ms’, ‘uvh5’, ‘fhd’, ‘mwa_corr_fits’, ‘mir’] or None. If None, the code attempts to guess what the file type is. For miriad and ms types, this is based on the standard directory structure. For FHD, uvfits and uvh5 files it’s based on file extensions (FHD: .sav, .txt; uvfits: .uvfits; uvh5: .uvh5). Note that if a list of datasets is passed, the file type is determined from the first dataset.
axis (str) – Axis to concatenate files along. This enables fast concatenation along the specified axis without the normal checking that all other metadata agrees. This method does not guarantee correct resulting objects. Please see the docstring for fast_concat for details. Allowed values are: ‘blt’, ‘freq’, ‘polarization’. Only used if multiple files are passed.
read_data (bool) – Read in the data. Not used if file_type is ‘ms’ or ‘mir’. If set to False, only the metadata will be read in. Setting read_data to False results in a metdata only object.
skip_bad_files (bool) – Option when reading multiple files to catch read errors such that the read continues even if one or more files are corrupted. Files that produce errors will be printed. Default is False (files will not be skipped).
background_lsts (bool) – When set to True, the lst_array is calculated in a background thread.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.
ignore_name (bool) – Only relevant when reading in multiple files, which are concatenated into a single UVData object. Option to ignore the name of the phase center when combining multiple files, which would otherwise result in an error being raised because of attributes not matching. Doing so effectively adopts the name found in the first file read in. Default is False.
use_future_array_shapes (bool) – Option to convert to the future planned array shapes before the changes go into effect by removing the spectral window axis.

Phasing:

allow_rephase (bool) – Deprecated, and has no effect. Will be removed in version 2.6.
make_multi_phase (bool) – Deprecated, and has no effect. Will be removed in version 2.6.

Selecting:

antenna_nums (array_like of int, optional) – The antennas numbers to include when reading data into the object (antenna positions and names for the removed antennas will be retained unless keep_all_metadata is False). This cannot be provided if antenna_names is also provided.
antenna_names (array_like of str, optional) – The antennas names to include when reading data into the object (antenna positions and names for the removed antennas will be retained unless keep_all_metadata is False). This cannot be provided if antenna_nums is also provided.
ant_str (str, optional) – A string containing information about what antenna numbers and polarizations to include when reading data into the object. Can be ‘auto’, ‘cross’, ‘all’, or combinations of antenna numbers and polarizations (e.g. ‘1’, ‘1_2’, ‘1x_2y’). See tutorial for more examples of valid strings and the behavior of different forms for ant_str. If ‘1x_2y,2y_3y’ is passed, both polarizations ‘xy’ and ‘yy’ will be kept for both baselines (1, 2) and (2, 3) to return a valid pyuvdata object. An ant_str cannot be passed in addition to any of antenna_nums, antenna_names, bls args or the polarizations parameters, if it is a ValueError will be raised.
bls (list of tuple, optional) – A list of antenna number tuples (e.g. [(0, 1), (3, 2)]) or a list of baseline 3-tuples (e.g. [(0, 1, ‘xx’), (2, 3, ‘yy’)]) specifying baselines to include when reading data into the object. For length-2 tuples, the ordering of the numbers within the tuple does not matter. For length-3 tuples, the polarization string is in the order of the two antennas. If length-3 tuples are provided, polarizations must be None.
catalog_names (str or array-like of str, optional) – The names of the phase centers (sources) to include when reading data into the object, which should match exactly in spelling and capitalization. Cannot be used with phase_center_ids.
frequencies (array_like of float, optional) – The frequencies to include when reading data into the object, each value passed here should exist in the freq_array.
freq_chans (array_like of int, optional) – The frequency channel numbers to include when reading data into the object. Ignored if read_data is False.
times (array_like of float, optional) – The times to include when reading data into the object, each value passed here should exist in the time_array in the file. Cannot be used with time_range, lsts, or lst_array.
time_range (array_like of float, optional) – The time range in Julian Date to include when reading data into the object, must be length 2. Some of the times in the file should fall between the first and last elements. Cannot be used with times.
lsts (array_like of float, optional) – The local sidereal times (LSTs) to keep in the object, each value passed here should exist in the lst_array. Cannot be used with times, time_range, or lst_range.
lst_range (array_like of float, optional) – The local sidereal time (LST) range in radians to keep in the object, must be of length 2. Some of the LSTs in the object should fall between the first and last elements. If the second value is smaller than the first, the LSTs are treated as having phase-wrapped around LST = 2*pi = 0, and the LSTs kept on the object will run from the larger value, through 0, and end at the smaller value.
polarizations (array_like of int, optional) – The polarizations numbers to include when reading data into the object, each value passed here should exist in the polarization_array.
blt_inds (array_like of int, optional) – The baseline-time indices to include when reading data into the object. This is not commonly used.
phase_center_ids (array_like of int, optional) – Phase center IDs to include when reading data into the object (effectively a selection on baseline-times). Cannot be used with catalog_names.
keep_all_metadata (bool) – Option to keep all the metadata associated with antennas, even those that do not have data associated with them after the select option.

Checking:

run_check (bool) – Option to check for the existence and proper shapes of parameters after after reading in the file (the default is True, meaning the check will be run). Ignored if read_data is False.
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked). Ignored if read_data is False.
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after reading in the file (the default is True, meaning the acceptable range check will be done). Ignored if read_data is False.
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.
check_autos (bool) – Check whether any auto-correlations have non-zero imaginary values in data_array (which should not mathematically exist). Default is True.
fix_autos (bool) – If auto-correlations with imaginary values are found, fix those values so that they are real-only in data_array. Default is True.

Miriad:

phase_type (str, optional) – Deprecated, use the projected parameter insted. Option to specify the phasing status of the data. Options are ‘drift’, ‘phased’ or None. ‘drift’ is the same as setting the projected parameter to False, ‘phased’ is the same as setting the projected parameter to True. Ignored if projected is set.
projected (bool or None) – Option to force the dataset to be labelled as projected or unprojected regardless of the evidence in the file. The default is None which means that the projection will be set based on the file contents. Be careful setting this keyword unless you are confident about the contents of the file.
correct_lat_lon (bool) – Option to update the latitude and longitude from the known_telescopes list if the altitude is missing.
calc_lst (bool) – Recalculate the LST values that are present within the file, useful in cases where the “online” calculate values have precision or value errors. Default is True.
fix_old_proj (bool) – Applies a fix to uvw-coordinates and phasing, assuming that the old phase method was used prior to writing the data, which had errors of the order of one part in 1e4 - 1e5. See the phasing memo for more details. Default is False.
fix_use_ant_pos (bool) – If setting fix_old_proj to True, use the antenna positions to derive the correct uvw-coordinates rather than using the baseline vectors. Default is True.
UVFITS
——
fix_old_proj (bool) – Applies a fix to uvw-coordinates and phasing, assuming that the old phase method was used prior to writing the data, which had errors of the order of one part in 1e4 - 1e5. See the phasing memo for more details. Default is False.
fix_use_ant_pos (bool) – If setting fix_old_proj to True, use the antenna positions to derive the correct uvw-coordinates rather than using the baseline vectors. Default is True.

FHD:

use_model (bool) – Option to read in the model visibilities rather than the dirty visibilities (the default is False, meaning the dirty visibilities will be read).

MS:

data_column (str) – name of CASA data column to read into data_array. Options are: ‘DATA’, ‘MODEL’, or ‘CORRECTED_DATA’.
pol_order (str or None) – Option to specify polarizations order convention, options are ‘CASA’, ‘AIPS’, or None (no reordering). Default is ‘AIPS’.
ignore_single_chan (bool) – Option to ignore single channel spectral windows in measurement sets to limit object size. Some measurement sets (e.g., those from ALMA) use single channel spectral windows for recording pseudo-continuum channels or storing other metadata in the track when the telescopes are not on source. Because of the way the object is strutured (where all spectral windows are assumed to be simultaneously recorded), this can significantly inflate the size and memory footprint of UVData objects. By default, single channel windows are ignored to avoid this issue, they can be included by setting this parameter to True.
raise_error (bool) – The measurement set format allows for different spectral windows and polarizations to have different metdata for the same time-baseline combination, but UVData objects do not. It also allows for timescales that are not supported by astropy. If any of these problems are detected, by default the reader will throw an error. However, if set to False, the reader will simply give a warning and try to do the best it can. If the problem is with differing metadata, it will use the first value read in the file as the “correct” metadata in the UVData object. If the problem is with the timescale, it will just assume UTC.
read_weights (bool) – Read in the weights from the MS file. If false, the method will set the nsamples_array to the same uniform value (namely 1.0).
allow_flex_pol (bool) – If only one polarization per spectral window is read (and the polarization differs from window to window), allow for the UVData object to use “flexible polarization”, which compresses the polarization-axis of various attributes to be of length 1, sets the flex_spw_polarization_array attribute to define the polarization per spectral window. Default is True.

UVH5:

multidim_index (bool) – If True, attempt to index the HDF5 dataset simultaneously along all data axes. Otherwise index one axis at-a-time. This only works if data selection is sliceable along all but one axis. If indices are not well-matched to data chunks, this can be slow.
remove_flex_pol (bool) – If True and if the file is a flex_pol file, convert back to a standard UVData object.
data_array_dtype (numpy dtype) – Datatype to store the output data_array as. Must be either np.complex64 (single-precision real and imaginary) or np.complex128 (double- precision real and imaginary). Only used if the datatype of the visibility data on-disk is not ‘c8’ or ‘c16’.
blt_order (tuple of str or “determine”, optional) – The order of the baseline-time axis in the file. This can be determined, or read directly from file, however since it has been optional in the past, many existing files do not contain it in the metadata. Some reading operations are significantly faster if this is known, so providing it here can provide a speedup. Default is to try and read it from file, and if not there, just leave it as None. Set to “determine” to auto-detect the blt_order from the metadata (takes extra time to do so).
blts_are_rectangular (bool, optional) – Whether the baseline-time axis is rectangular. This can be read from metadata in new files, but many old files do not contain it. If not provided, the rectangularity will be determined from the data. This is a non-negligible operation, so if you know it, it can be provided here to speed up reading.
time_axis_faster_than_bls (bool, optional) – If blts are rectangular, this variable specifies whether the time axis is the fastest-moving virtual axis. Various reading functions benefit from knowing this, so if it is known, it can be provided here to speed up reading. It will be determined from the data if not provided.
recompute_nbls (bool, optional) – Whether to recompute the number of unique baselines from the data. Before v1.2 of the UVH5 spec, it was possible to have an incorrect number of baselines in the header without error, so this provides an opportunity to rectify it. Old HERA files (< March 2023) may have this issue, but in this case the correct number of baselines can be computed more quickly than by fully re=computing, and so we do this.
fix_old_proj (bool) – Applies a fix to uvw-coordinates and phasing, assuming that the old phase method was used prior to writing the data, which had errors of the order of one part in 1e4 - 1e5. See the phasing memo for more details. Default is False, unless reading a UVH5 file that is missing the phase_center_app_ra and phase_center_app_dec attributes (as these were introduced at the same time as the new phase method), in which case the default is True.
fix_use_ant_pos (bool) – If setting fix_old_proj to True, use the antenna positions to derive the correct uvw-coordinates rather than using the baseline vectors. Default is True.

MWA FITS:

use_aoflagger_flags (bool) – Option to use aoflagger mwaf flag files. Defaults to true if aoflagger flag files are submitted.
remove_dig_gains (bool) – Option to divide out digital gains.
remove_coarse_band (bool) – Option to divide out coarse band shape.
correct_cable_len (bool) – Flag to apply cable length correction.
correct_van_vleck (bool) – Flag to apply a van vleck correction.
cheby_approx (bool) – Option to implement the van vleck correction with a chebyshev polynomial approximation. Set to False to run the integral version of the correction. Only used if correct_van_vleck is True.
flag_small_auto_ants (bool) – Option to completely flag any antenna for which the autocorrelation falls below a threshold found by the Van Vleck correction to indicate bad data. Specifically, the threshold used is 0.5 * integration_time * channel_width. If set to False, only the times and frequencies at which the auto is below the threshold will be flagged for the antenna. Only used if correct_van_vleck is True.
propogate_coarse_flags (bool) – Option to propogate flags for missing coarse channel integrations across frequency.
flag_init (bool) – Set to True in order to do routine flagging of coarse channel edges, start or end integrations, or the center fine channel of each coarse channel. See associated keywords below.
edge_width (float) – Only used if flag_init is True. Set to the width to flag on the edge of each coarse channel, in hz. Errors if not equal to integer multiple of channel_width. Set to 0 for no edge flagging.
start_flag (float or str) – Only used if flag_init is True. The number of seconds to flag at the beginning of the observation. Set to 0 for no flagging. Default is ‘goodtime’, which uses information in the metafits file to determine the length of time that should be flagged. Errors if input is not a float or ‘goodtime’. Errors if float input is not equal to an integer multiple of the integration time.
end_flag (floats) – Only used if flag_init is True. Set to the number of seconds to flag at the end of the observation. Set to 0 for no flagging. Errors if not an integer multiple of the integration time.
flag_dc_offset (bool) – Only used if flag_init is True. Set to True to flag the center fine channel of each coarse channel.
remove_flagged_ants (bool) – Option to perform a select to remove antennas flagged in the metafits file. If correct_van_vleck and flag_small_auto_ants are both True then antennas flagged by the Van Vleck correction are also removed.
phase_to_pointing_center (bool) – Flag to phase to the pointing center. Cannot be set if phase_center_radec is set to a value.
data_array_dtype (numpy dtype) – Datatype to store the output data_array as. Must be either np.complex64 (single-precision real and imaginary) or np.complex128 (double- precision real and imaginary).
nsample_array_dtype (numpy dtype) – Datatype to store the output nsample_array as. Must be either np.float64 (double-precision), np.float32 (single-precision), or np.float16 (half-precision). Half-precision is only recommended for cases where no sampling or averaging of baselines will occur, because round-off errors can be quite large (~1e-3).

MIR:

corrchunk (int or array-like of int) – Correlator “chunk” (spectral window) to include when reading data into the object, where 0 corresponds to the pseudo-continuum channel.
receivers (str or array-like of str) – The names of the receivers (“230”, “240”, “345”, “400”) to include when reading data into the object.
sidebands (str or array-like of str) – The names of the sidebands (“l” for lower, “u” for upper) to include when reading data into the object.
mir_select_where (tuple or list of tuples, optional) – Argument to pass to the MirParser.select method, which will downselect which data is read into the object.
apply_flags (bool) – If set to True, apply “wideband” flags to the visibilities, which are recorded by the realtime system to denote when data are expected to be bad (e.g., antennas not on source, dewar warm). Default it true.
apply_tsys (bool) – If set to False, data are returned as correlation coefficients (normalized by the auto-correlations). Default is True, which instead scales the raw visibilities and forward-gain of the antenna to produce values in Jy (uncalibrated).
apply_dedoppler (bool) – If set to True, data will be corrected for any doppler-tracking performed during observations, and brought into the topocentric rest frame (default for UVData objects). Default is False.
allow_flex_pol (bool) – If only one polarization per spectral window is read (and the polarization differs from window to window), allow for the UVData object to use “flexible polarization”, which compresses the polarization-axis of various attributes to be of length 1, sets the flex_spw_polarization_array attribute to define the polarization per spectral window. Default is True.
swarm_only (bool) – By default, only SMA SWARM data is loaded. If set to false, this will also enable loading of older ASIC data.
compass_soln (str) – Optional argument, specifying the path of COMPASS-derived flagging and bandpass gains solutions, which are applied prior to any potential spectral averaging (as triggered by using the rechunk keyword).
codes_check (bool) – Option to check the cross-check the internal MIR metadata, and deselect data without valid matches, useful for automatically handling various data recording issues. Default is True. Note this is different than the various checks done on the UVData object itself (controlled by other keywords listed here).

Raises:

ValueError – If the file_type is not set and cannot be determined from the file name. If incompatible select keywords are set (e.g. ant_str with other antenna selectors, times and time_range) or select keywords exclude all data or if keywords are set to the wrong type. If phase_center_radec is not None and is not length 2.

classmethod from_file(filename, **kwargs)[source]

Initialize a new UVData object by reading the input file.

This method supports a number of different types of files. Universal parameters (required and optional) are listed directly below, followed by parameters used by all file types related to phasing, selecting on read (partial read) and checking. Each file type also has its own set of optional parameters that are listed at the end of this docstring.

Parameters:

filename (str or array_like of str) – The file(s) or list(s) (or array(s)) of files to read from.
file_type (str) – One of [‘uvfits’, ‘miriad’, ‘ms’, ‘uvh5’, ‘fhd’, ‘mwa_corr_fits’, ‘mir’] or None. If None, the code attempts to guess what the file type is. For miriad and ms types, this is based on the standard directory structure. For FHD, uvfits and uvh5 files it’s based on file extensions (FHD: .sav, .txt; uvfits: .uvfits; uvh5: .uvh5). Note that if a list of datasets is passed, the file type is determined from the first dataset.
axis (str) – Axis to concatenate files along. This enables fast concatenation along the specified axis without the normal checking that all other metadata agrees. This method does not guarantee correct resulting objects. Please see the docstring for fast_concat for details. Allowed values are: ‘blt’, ‘freq’, ‘polarization’. Only used if multiple files are passed.
read_data (bool) – Read in the data. Not used if file_type is ‘ms’ or ‘mir’. If set to False, only the metadata will be read in. Setting read_data to False results in a metdata only object.
skip_bad_files (bool) – Option when reading multiple files to catch read errors such that the read continues even if one or more files are corrupted. Files that produce errors will be printed. Default is False (files will not be skipped).
background_lsts (bool) – When set to True, the lst_array is calculated in a background thread.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.
ignore_name (bool) – Only relevant when reading in multiple files, which are concatenated into a single UVData object. Option to ignore the name of the phase center when combining multiple files, which would otherwise result in an error being raised because of attributes not matching. Doing so effectively adopts the name found in the first file read in. Default is False.
use_future_array_shapes (bool) – Option to convert to the future planned array shapes before the changes go into effect by removing the spectral window axis.

Phasing:

allow_rephase (bool) – Deprecated, and has no effect. Will be removed in version 2.6.
make_multi_phase (bool) – Deprecated, and has no effect. Will be removed in version 2.6.

Selecting:

antenna_nums (array_like of int, optional) – The antennas numbers to include when reading data into the object (antenna positions and names for the removed antennas will be retained unless keep_all_metadata is False). This cannot be provided if antenna_names is also provided.
antenna_names (array_like of str, optional) – The antennas names to include when reading data into the object (antenna positions and names for the removed antennas will be retained unless keep_all_metadata is False). This cannot be provided if antenna_nums is also provided.
ant_str (str, optional) – A string containing information about what antenna numbers and polarizations to include when reading data into the object. Can be ‘auto’, ‘cross’, ‘all’, or combinations of antenna numbers and polarizations (e.g. ‘1’, ‘1_2’, ‘1x_2y’). See tutorial for more examples of valid strings and the behavior of different forms for ant_str. If ‘1x_2y,2y_3y’ is passed, both polarizations ‘xy’ and ‘yy’ will be kept for both baselines (1, 2) and (2, 3) to return a valid pyuvdata object. An ant_str cannot be passed in addition to any of antenna_nums, antenna_names, bls args or the polarizations parameters, if it is a ValueError will be raised.
bls (list of tuple, optional) – A list of antenna number tuples (e.g. [(0, 1), (3, 2)]) or a list of baseline 3-tuples (e.g. [(0, 1, ‘xx’), (2, 3, ‘yy’)]) specifying baselines to include when reading data into the object. For length-2 tuples, the ordering of the numbers within the tuple does not matter. For length-3 tuples, the polarization string is in the order of the two antennas. If length-3 tuples are provided, polarizations must be None.
catalog_names (str or array-like of str, optional) – The names of the phase centers (sources) to include when reading data into the object, which should match exactly in spelling and capitalization. Cannot be used with phase_center_ids.
frequencies (array_like of float, optional) – The frequencies to include when reading data into the object, each value passed here should exist in the freq_array.
freq_chans (array_like of int, optional) – The frequency channel numbers to include when reading data into the object. Ignored if read_data is False.
times (array_like of float, optional) – The times to include when reading data into the object, each value passed here should exist in the time_array in the file. Cannot be used with time_range, lsts, or lst_array.
time_range (array_like of float, optional) – The time range in Julian Date to include when reading data into the object, must be length 2. Some of the times in the file should fall between the first and last elements. Cannot be used with times.
lsts (array_like of float, optional) – The local sidereal times (LSTs) to keep in the object, each value passed here should exist in the lst_array. Cannot be used with times, time_range, or lst_range.
lst_range (array_like of float, optional) – The local sidereal time (LST) range in radians to keep in the object, must be of length 2. Some of the LSTs in the object should fall between the first and last elements. If the second value is smaller than the first, the LSTs are treated as having phase-wrapped around LST = 2*pi = 0, and the LSTs kept on the object will run from the larger value, through 0, and end at the smaller value.
polarizations (array_like of int, optional) – The polarizations numbers to include when reading data into the object, each value passed here should exist in the polarization_array.
blt_inds (array_like of int, optional) – The baseline-time indices to include when reading data into the object. This is not commonly used.
phase_center_ids (array_like of int, optional) – Phase center IDs to include when reading data into the object (effectively a selection on baseline-times). Cannot be used with catalog_names.
keep_all_metadata (bool) – Option to keep all the metadata associated with antennas, even those that do not have data associated with them after the select option.

Checking:

run_check (bool) – Option to check for the existence and proper shapes of parameters after after reading in the file (the default is True, meaning the check will be run). Ignored if read_data is False.
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked). Ignored if read_data is False.
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after reading in the file (the default is True, meaning the acceptable range check will be done). Ignored if read_data is False.
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.
check_autos (bool) – Check whether any auto-correlations have non-zero imaginary values in data_array (which should not mathematically exist). Default is True.
fix_autos (bool) – If auto-correlations with imaginary values are found, fix those values so that they are real-only in data_array. Default is True.

Miriad:

phase_type (str, optional) – Deprecated, use the projected parameter insted. Option to specify the phasing status of the data. Options are ‘drift’, ‘phased’ or None. ‘drift’ is the same as setting the projected parameter to False, ‘phased’ is the same as setting the projected parameter to True. Ignored if projected is set.
projected (bool or None) – Option to force the dataset to be labelled as projected or unprojected regardless of the evidence in the file. The default is None which means that the projection will be set based on the file contents. Be careful setting this keyword unless you are confident about the contents of the file.
correct_lat_lon (bool) – Option to update the latitude and longitude from the known_telescopes list if the altitude is missing.
calc_lst (bool) – Recalculate the LST values that are present within the file, useful in cases where the “online” calculate values have precision or value errors. Default is True.
fix_old_proj (bool) – Applies a fix to uvw-coordinates and phasing, assuming that the old phase method was used prior to writing the data, which had errors of the order of one part in 1e4 - 1e5. See the phasing memo for more details. Default is False.
fix_use_ant_pos (bool) – If setting fix_old_proj to True, use the antenna positions to derive the correct uvw-coordinates rather than using the baseline vectors. Default is True.
UVFITS
——
fix_old_proj (bool) – Applies a fix to uvw-coordinates and phasing, assuming that the old phase method was used prior to writing the data, which had errors of the order of one part in 1e4 - 1e5. See the phasing memo for more details. Default is False.
fix_use_ant_pos (bool) – If setting fix_old_proj to True, use the antenna positions to derive the correct uvw-coordinates rather than using the baseline vectors. Default is True.

FHD:

use_model (bool) – Option to read in the model visibilities rather than the dirty visibilities (the default is False, meaning the dirty visibilities will be read).

MS:

data_column (str) – name of CASA data column to read into data_array. Options are: ‘DATA’, ‘MODEL’, or ‘CORRECTED_DATA’.
pol_order (str or None) – Option to specify polarizations order convention, options are ‘CASA’, ‘AIPS’, or None (no reordering). Default is ‘AIPS’.
ignore_single_chan (bool) – Option to ignore single channel spectral windows in measurement sets to limit object size. Some measurement sets (e.g., those from ALMA) use single channel spectral windows for recording pseudo-continuum channels or storing other metadata in the track when the telescopes are not on source. Because of the way the object is strutured (where all spectral windows are assumed to be simultaneously recorded), this can significantly inflate the size and memory footprint of UVData objects. By default, single channel windows are ignored to avoid this issue, they can be included by setting this parameter to True.
raise_error (bool) – The measurement set format allows for different spectral windows and polarizations to have different metdata for the same time-baseline combination, but UVData objects do not. It also allows for timescales that are not supported by astropy. If any of these problems are detected, by default the reader will throw an error. However, if set to False, the reader will simply give a warning and try to do the best it can. If the problem is with differing metadata, it will use the first value read in the file as the “correct” metadata in the UVData object. If the problem is with the timescale, it will just assume UTC.
read_weights (bool) – Read in the weights from the MS file. If false, the method will set the nsamples_array to the same uniform value (namely 1.0).
allow_flex_pol (bool) – If only one polarization per spectral window is read (and the polarization differs from window to window), allow for the UVData object to use “flexible polarization”, which compresses the polarization-axis of various attributes to be of length 1, sets the flex_spw_polarization_array attribute to define the polarization per spectral window. Default is True.

UVH5:

multidim_index (bool) – If True, attempt to index the HDF5 dataset simultaneously along all data axes. Otherwise index one axis at-a-time. This only works if data selection is sliceable along all but one axis. If indices are not well-matched to data chunks, this can be slow.
remove_flex_pol (bool) – If True and if the file is a flex_pol file, convert back to a standard UVData object.
data_array_dtype (numpy dtype) – Datatype to store the output data_array as. Must be either np.complex64 (single-precision real and imaginary) or np.complex128 (double- precision real and imaginary). Only used if the datatype of the visibility data on-disk is not ‘c8’ or ‘c16’.
blt_order (tuple of str or “determine”, optional) – The order of the baseline-time axis in the file. This can be determined, or read directly from file, however since it has been optional in the past, many existing files do not contain it in the metadata. Some reading operations are significantly faster if this is known, so providing it here can provide a speedup. Default is to try and read it from file, and if not there, just leave it as None. Set to “determine” to auto-detect the blt_order from the metadata (takes extra time to do so).
blts_are_rectangular (bool, optional) – Whether the baseline-time axis is rectangular. This can be read from metadata in new files, but many old files do not contain it. If not provided, the rectangularity will be determined from the data. This is a non-negligible operation, so if you know it, it can be provided here to speed up reading.
time_axis_faster_than_bls (bool, optional) – If blts are rectangular, this variable specifies whether the time axis is the fastest-moving virtual axis. Various reading functions benefit from knowing this, so if it is known, it can be provided here to speed up reading. It will be determined from the data if not provided.
recompute_nbls (bool, optional) – Whether to recompute the number of unique baselines from the data. Before v1.2 of the UVH5 spec, it was possible to have an incorrect number of baselines in the header without error, so this provides an opportunity to rectify it. Old HERA files (< March 2023) may have this issue, but in this case the correct number of baselines can be computed more quickly than by fully re=computing, and so we do this.
fix_old_proj (bool) – Applies a fix to uvw-coordinates and phasing, assuming that the old phase method was used prior to writing the data, which had errors of the order of one part in 1e4 - 1e5. See the phasing memo for more details. Default is False, unless reading a UVH5 file that is missing the phase_center_app_ra and phase_center_app_dec attributes (as these were introduced at the same time as the new phase method), in which case the default is True.
fix_use_ant_pos (bool) – If setting fix_old_proj to True, use the antenna positions to derive the correct uvw-coordinates rather than using the baseline vectors. Default is True.

MWA FITS:

use_aoflagger_flags (bool) – Option to use aoflagger mwaf flag files. Defaults to true if aoflagger flag files are submitted.
remove_dig_gains (bool) – Option to divide out digital gains.
remove_coarse_band (bool) – Option to divide out coarse band shape.
correct_cable_len (bool) – Flag to apply cable length correction.
correct_van_vleck (bool) – Flag to apply a van vleck correction.
cheby_approx (bool) – Option to implement the van vleck correction with a chebyshev polynomial approximation. Set to False to run the integral version of the correction. Only used if correct_van_vleck is True.
flag_small_auto_ants (bool) – Option to completely flag any antenna for which the autocorrelation falls below a threshold found by the Van Vleck correction to indicate bad data. Specifically, the threshold used is 0.5 * integration_time * channel_width. If set to False, only the times and frequencies at which the auto is below the threshold will be flagged for the antenna. Only used if correct_van_vleck is True.
propogate_coarse_flags (bool) – Option to propogate flags for missing coarse channel integrations across frequency.
flag_init (bool) – Set to True in order to do routine flagging of coarse channel edges, start or end integrations, or the center fine channel of each coarse channel. See associated keywords below.
edge_width (float) – Only used if flag_init is True. Set to the width to flag on the edge of each coarse channel, in hz. Errors if not equal to integer multiple of channel_width. Set to 0 for no edge flagging.
start_flag (float or str) – Only used if flag_init is True. The number of seconds to flag at the beginning of the observation. Set to 0 for no flagging. Default is ‘goodtime’, which uses information in the metafits file to determine the length of time that should be flagged. Errors if input is not a float or ‘goodtime’. Errors if float input is not equal to an integer multiple of the integration time.
end_flag (floats) – Only used if flag_init is True. Set to the number of seconds to flag at the end of the observation. Set to 0 for no flagging. Errors if not an integer multiple of the integration time.
flag_dc_offset (bool) – Only used if flag_init is True. Set to True to flag the center fine channel of each coarse channel.
remove_flagged_ants (bool) – Option to perform a select to remove antennas flagged in the metafits file. If correct_van_vleck and flag_small_auto_ants are both True then antennas flagged by the Van Vleck correction are also removed.
phase_to_pointing_center (bool) – Flag to phase to the pointing center. Cannot be set if phase_center_radec is set to a value.
data_array_dtype (numpy dtype) – Datatype to store the output data_array as. Must be either np.complex64 (single-precision real and imaginary) or np.complex128 (double- precision real and imaginary).
nsample_array_dtype (numpy dtype) – Datatype to store the output nsample_array as. Must be either np.float64 (double-precision), np.float32 (single-precision), or np.float16 (half-precision). Half-precision is only recommended for cases where no sampling or averaging of baselines will occur, because round-off errors can be quite large (~1e-3).

MIR:

corrchunk (int or array-like of int) – Correlator “chunk” (spectral window) to include when reading data into the object, where 0 corresponds to the pseudo-continuum channel.
receivers (str or array-like of str) – The names of the receivers (“230”, “240”, “345”, “400”) to include when reading data into the object.
sidebands (str or array-like of str) – The names of the sidebands (“l” for lower, “u” for upper) to include when reading data into the object.
mir_select_where (tuple or list of tuples, optional) – Argument to pass to the MirParser.select method, which will downselect which data is read into the object.
apply_flags (bool) – If set to True, apply “wideband” flags to the visibilities, which are recorded by the realtime system to denote when data are expected to be bad (e.g., antennas not on source, dewar warm). Default it true.
apply_tsys (bool) – If set to False, data are returned as correlation coefficients (normalized by the auto-correlations). Default is True, which instead scales the raw visibilities and forward-gain of the antenna to produce values in Jy (uncalibrated).
apply_dedoppler (bool) – If set to True, data will be corrected for any doppler-tracking performed during observations, and brought into the topocentric rest frame (default for UVData objects). Default is False.
allow_flex_pol (bool) – If only one polarization per spectral window is read (and the polarization differs from window to window), allow for the UVData object to use “flexible polarization”, which compresses the polarization-axis of various attributes to be of length 1, sets the flex_spw_polarization_array attribute to define the polarization per spectral window. Default is True.
swarm_only (bool) – By default, only SMA SWARM data is loaded. If set to false, this will also enable loading of older ASIC data.
compass_soln (str) – Optional argument, specifying the path of COMPASS-derived flagging and bandpass gains solutions, which are applied prior to any potential spectral averaging (as triggered by using the rechunk keyword).
codes_check (bool) – Option to check the cross-check the internal MIR metadata, and deselect data without valid matches, useful for automatically handling various data recording issues. Default is True. Note this is different than the various checks done on the UVData object itself (controlled by other keywords listed here).

Raises:

ValueError – If the file_type is not set and cannot be determined from the file name. If incompatible select keywords are set (e.g. ant_str with other antenna selectors, times and time_range) or select keywords exclude all data or if keywords are set to the wrong type. If phase_center_radec is not None and is not length 2.

write_miriad(filepath, clobber=False, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, no_antnums=False, calc_lst=False, check_autos=True, fix_autos=False)[source]

Write the data to a miriad file.

Parameters:

filename (str) – The miriad root directory to write to.
clobber (bool) – Option to overwrite the filename if the file already exists.
run_check (bool) – Option to check for the existence and proper shapes of parameters after before writing the file (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters before writing the file (the default is True, meaning the acceptable range check will be done).
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.
no_antnums (bool) – Option to not write the antnums variable to the file. Should only be used for testing purposes.
calc_lst (bool) – Recalculate the LST values upon writing the file. This is done to perform higher-precision accounting for the difference in MIRAD timestamps vs pyuvdata (the former marks the beginning of an integration, the latter marks the midpoint). Default is False, which instead uses a simple formula for correcting the LSTs, expected to be accurate to approximately 0.1 µsec precision.
check_autos (bool) – Check whether any auto-correlations have non-zero imaginary values in data_array (which should not mathematically exist). Default is True.
fix_autos (bool) – If auto-correlations with imaginary values are found, fix those values so that they are real-only in data_array. Default is False.

Raises:

ValueError – If the frequencies are not evenly spaced or are separated by more than their channel width or if the UVData object is a metadata only object.
TypeError – If any entry in extra_keywords is not a single string or number.

write_mir(filepath)[source]

Write the data to a mir file.

Parameters:

filename (str) – The mir root directory to write to.

Raises:

ValueError – If the UVData object is a metadata only object.
NotImplementedError – Method is not fully implemented yet, and thus will raise an error

write_ms(filename, force_phase=False, flip_conj=False, clobber=False, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, check_autos=True, fix_autos=False)[source]

Write a CASA measurement set (MS).

Parameters:

filename (str) – The measurement set file path to write to (a measurement set is really a folder with many files).
force_phase (bool) – Option to automatically phase unprojected data to zenith of the first timestamp.
flip_conj (bool) – If set to True, and the UVW coordinates are flipped (i.e., multiplied by -1) and the visibilities are complex conjugated prior to write, such that the data are written with the “opposite” conjugation scheme to what UVData normally uses. Note that this is only needed for specific subset of applications that read MS-formated data, and should only be used by expert users. Default is False.
clobber (bool) – Option to overwrite the file if it already exists.
run_check (bool) – Option to check for the existence and proper shapes of parameters before writing the file.
check_extra (bool) – Option to check optional parameters as well as required ones.
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters before writing the file.
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.
check_autos (bool) – Check whether any auto-correlations have non-zero imaginary values in data_array (which should not mathematically exist). Default is True.
fix_autos (bool) – If auto-correlations with imaginary values are found, fix those values so that they are real-only in data_array. Default is False.

Raises:

ValueError – If the UVData object is a metadata only object.

write_uvfits(filename, write_lst=True, force_phase=False, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, check_autos=True, fix_autos=False, use_miriad_convention=False)[source]

Write the data to a uvfits file.

If using this method to write out a data set for import into CASA, users should be aware that the importuvifts task does not currently support reading in data sets where the number of antennas is > 255. If writing out such a data set for use in CASA, we suggest using the measurement set writer (UVData.write_ms) instead.

Parameters:

filename (str) – The uvfits file to write to.
write_lst (bool) – Option to write the LSTs to the metadata (random group parameters).
force_phase (: bool) – Option to automatically phase unprojected data to zenith of the first timestamp.
run_check (bool) – Option to check for the existence and proper shapes of parameters after before writing the file (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters before writing the file (the default is True, meaning the acceptable range check will be done).
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.
check_autos (bool) – Check whether any auto-correlations have non-zero imaginary values in data_array (which should not mathematically exist). Default is True.
fix_autos (bool) – If auto-correlations with imaginary values are found, fix those values so that they are real-only in data_array. Default is False.
use_miriad_convention (bool) – Option to use the MIRIAD baseline convention, and write to BASELINE column. This mode is required for UVFITS files with >256 antennas to be readable by MIRIAD, and supports up to 2048 antennas. The MIRIAD baseline ID is given by bl = 256 * ant1 + ant2 if ant2 < 256, otherwise bl = 2048 * ant1 + ant2 + 2**16. Note MIRIAD uses 1-indexed antenna IDs, but this code accepts 0-based.

Raises:

ValueError – Any blts are unprojected and force_phase keyword is not set. If the frequencies are not evenly spaced or are separated by more than their channel width. The polarization values are not evenly spaced. If the timesys parameter is not set to “UTC”. If the UVData object is a metadata only object.
TypeError – If any entry in extra_keywords is not a single string or number.

write_uvh5(filename, clobber=False, chunks=True, data_compression=None, flags_compression='lzf', nsample_compression='lzf', data_write_dtype=None, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, check_autos=True, fix_autos=False)[source]

Write a completely in-memory UVData object to a UVH5 file.

Parameters:

filename (str) – The UVH5 file to write to.
clobber (bool) – Option to overwrite the file if it already exists.
chunks (tuple or bool) – h5py.create_dataset chunks keyword. Tuple for chunk shape, True for auto-chunking, None for no chunking. Default is True.
data_compression (str) – HDF5 filter to apply when writing the data_array. Default is None (no filter/compression). In addition to the normal HDF5 filter values, the user may specify “bitshuffle” which will set the compression to 32008 for bitshuffle and will set the compression_opts to (0, 2) to allow bitshuffle to automatically determine the block size and to use the LZF filter after bitshuffle. Using bitshuffle requires having the hdf5plugin package installed. Dataset must be chunked to use compression.
flags_compression (str) – HDF5 filter to apply when writing the flags_array. Default is “lzf” for the LZF filter. Dataset must be chunked.
nsample_compression (str) – HDF5 filter to apply when writing the nsample_array. Default is “lzf” for the LZF filter. Dataset must be chunked.
data_write_dtype (numpy dtype) – datatype of output visibility data. If ‘None’, then the same datatype as data_array will be used. Otherwise, a numpy dtype object must be specified with an ‘r’ field and an ‘i’ field for real and imaginary parts, respectively. See uvh5.py for an example of defining such a datatype.
run_check (bool) – Option to check for the existence and proper shapes of parameters after before writing the file (the default is True, meaning the check will be run).
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked).
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters before writing the file (the default is True, meaning the acceptable range check will be done).
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.
check_autos (bool) – Check whether any auto-correlations have non-zero imaginary values in data_array (which should not mathematically exist). Default is True.
fix_autos (bool) – If auto-correlations with imaginary values are found, fix those values so that they are real-only in data_array. Default is False.

Raises:

ValueError – If the UVData object is a metadata only object.

initialize_uvh5_file(filename, clobber=False, chunks=True, data_compression=None, flags_compression='lzf', nsample_compression='lzf', data_write_dtype=None)[source]

Initialize a UVH5 file on disk with the header metadata and empty data arrays.

Parameters:

filename (str) – The UVH5 file to write to.
clobber (bool) – Option to overwrite the file if it already exists.
chunks (tuple or bool) – h5py.create_dataset chunks keyword. Tuple for chunk shape, True for auto-chunking, None for no chunking. Default is True.
data_compression (str) – HDF5 filter to apply when writing the data_array. Default is None (no filter/compression). In addition to the normal HDF5 filter values, the user may specify “bitshuffle” which will set the compression to 32008 for bitshuffle and will set the compression_opts to (0, 2) to allow bitshuffle to automatically determine the block size and to use the LZF filter after bitshuffle. Using bitshuffle requires having the hdf5plugin package installed. Dataset must be chunked to use compression.
flags_compression (str) – HDF5 filter to apply when writing the flags_array. Default is “lzf” for the LZF filter. Dataset must be chunked.
nsample_compression (str) – HDF5 filter to apply when writing the nsample_array. Default is “lzf” for the LZF filter. Dataset must be chunked.
data_write_dtype (numpy dtype) – datatype of output visibility data. If ‘None’, then the same datatype as data_array will be used. Otherwise, a numpy dtype object must be specified with an ‘r’ field and an ‘i’ field for real and imaginary parts, respectively. See uvh5.py for an example of defining such a datatype.

Notes

When partially writing out data, this function should be called first to initialize the file on disk. The data is then actually written by calling the write_uvh5_part method, with the same filename as the one specified in this function. See the tutorial for a worked example.

write_uvh5_part(filename, data_array, flags_array, nsample_array, check_header=True, antenna_nums=None, antenna_names=None, ant_str=None, bls=None, frequencies=None, freq_chans=None, times=None, time_range=None, lsts=None, lst_range=None, polarizations=None, blt_inds=None, phase_center_ids=None, catalog_names=None, add_to_history=None, run_check_acceptability=True, fix_autos=False)[source]

Write data to a UVH5 file that has already been initialized.

Parameters:

filename (str) – The UVH5 file to write to. It must already exist, and is assumed to have been initialized with initialize_uvh5_file.
data_array (ndarray) – The data to write to disk. A check is done to ensure that the dimensions of the data passed in conform to the ones specified by the “selection” arguments.
flags_array (ndarray) – The flags array to write to disk. A check is done to ensure that the dimensions of the data passed in conform to the ones specified by the “selection” arguments.
nsample_array (ndarray) – The nsample array to write to disk. A check is done to ensure that the dimensions of the data passed in conform to the ones specified by the “selection” arguments.
check_header (bool) – Option to check that the metadata present in the header on disk matches that in the object.
antenna_nums (array_like of int, optional) – The antennas numbers to include when writing data into the file (antenna positions and names for the removed antennas will be retained). This cannot be provided if antenna_names is also provided.
antenna_names (array_like of str, optional) – The antennas names to include when writing data into the file (antenna positions and names for the removed antennas will be retained). This cannot be provided if antenna_nums is also provided.
bls (list of tuple, optional) – A list of antenna number tuples (e.g. [(0, 1), (3, 2)]) or a list of baseline 3-tuples (e.g. [(0, 1, ‘xx’), (2, 3, ‘yy’)]) specifying baselines to include when writing data into the file. For length-2 tuples, the ordering of the numbers within the tuple does not matter. For length-3 tuples, the polarization string is in the order of the two antennas. If length-3 tuples are provided, polarizations must be None.
ant_str (str, optional) – A string containing information about what antenna numbers and polarizations to include writing data into the file. Can be ‘auto’, ‘cross’, ‘all’, or combinations of antenna numbers and polarizations (e.g. ‘1’, ‘1_2’, ‘1x_2y’). See tutorial for more examples of valid strings and the behavior of different forms for ant_str. If ‘1x_2y,2y_3y’ is passed, both polarizations ‘xy’ and ‘yy’ will be kept for both baselines (1, 2) and (2, 3) to return a valid pyuvdata object. An ant_str cannot be passed in addition to any of antenna_nums, antenna_names, bls args or the polarizations parameters, if it is a ValueError will be raised.
frequencies (array_like of float, optional) – The frequencies to include when writing data into the file, each value passed here should exist in the freq_array.
freq_chans (array_like of int, optional) – The frequency channel numbers to include writing data into the file.
times (array_like of float, optional) – The times to include when writing data into the file, each value passed here should exist in the time_array. Cannot be used with time_range, lsts, or lst_array.
time_range (array_like of float, optional) – The time range in Julian Date to include when writing data to the file, must be length 2. Some of the times in the object should fall between the first and last elements. Cannot be used with times.
lsts (array_like of float, optional) – The local sidereal times (LSTs) to keep in the object, each value passed here should exist in the lst_array. Cannot be used with times, time_range, or lst_range.
lst_range (array_like of float, optional) – The local sidereal time (LST) range in radians to keep in the object, must be of length 2. Some of the LSTs in the object should fall between the first and last elements. If the second value is smaller than the first, the LSTs are treated as having phase-wrapped around LST = 2*pi = 0, and the LSTs kept on the object will run from the larger value, through 0, and end at the smaller value.
polarizations (array_like of int, optional) – The polarizations numbers to include when writing data into the file, each value passed here should exist in the polarization_array.
blt_inds (array_like of int, optional) – The baseline-time indices to include when writing data into the file. This is not commonly used.
phase_center_ids (array_like of int, optional) – Phase center IDs to include when writing data into the file (effectively a selection on baseline-times). Cannot be used with catalog_names.
catalog_names (str or array-like of str, optional) – The names of the phase centers (sources) to include when writing data to the file, which should match exactly in spelling and capitalization. Cannot be used with phase_center_ids.
add_to_history (str) – String to append to history before write out. Default is no appending.
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters before writing the file (the default is True, meaning the acceptable range check will be done).
strict_uvw_antpos_check (bool) – Option to raise an error rather than a warning if the check that uvws match antenna positions does not pass.
fix_autos (bool) – Force the auto-correlations to be real-only values in data_array. Default is False.

normalize_by_autos(skip_autos=True, invert=False)[source]

Normalize cross-correlations by auto-correlation data.

Normalizes the cross-correlations by the geometric mean of the autocorrelations that make up the antenna pair for a given baseline. Useful for converting arbitrarily-scaled data into correlation coefficients (which can sometimes be more readily converted to a flux scale).

Parameters:

skip_autos (bool) – If set to True, the method will skip over records which correspond to the auto-correlations (which would otherwise simply be equal to all ones), which can be useful if intending to undo or redo the normalization at some point later. Default is True.
invert (bool) – If set to True, will multiply by the geometric mean of the autos instead of dividing by it. Useful for undoing previous normalizations (which also requires setting skip_autos=True on previous calls).

last updated: 2024-03-25