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.
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 (ITRF frame), shape (Nants_telescope, 3), units meters. See the 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; baseline = 2048 * (ant1+1) + (ant2+1) + 2^16.
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.
multi_phase_center: Only relevant if phase_type = “phased”. Specifies the that the data set contains multiple sources within it.
object_name: Name(s) of source(s) or field(s) observed, type string. If multi_phase_center = True, set to “multi”.
phase_type: String indicating phasing type. Allowed values are “drift” and “phased” (n.b., “drift” is not the same as cat_type=”driftscan”, the latter of which _is_ phased to a fixed az-el position).
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).
spw_array: Array of spectral window numbers, shape (Nspws).
telescope_location: Telescope location: xyz in ITRF (earth-centered frame). 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).

Nphase: Required if multi_phase_center = True. Specifies the number of phase centers contained within the data set.
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.
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. 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.
phase_center_app_dec: Required if phase_type = “phased”. Declination of phase center in the topocentric frame of the observatory, units radians. Shape (Nblts,), type = float.
phase_center_app_ra: Required if phase_type = “phased”. Apparent right ascension of phase center in the topocentric frame of the observatory, units radians.Shape (Nblts,), type = float.
phase_center_catalog: Only relevant if multi_phase_center = True. Dictionary that acts as a catalog, containing information on individual phase centers. Keys are the names of the different phase centers in the UVData object. At a minimum, each dictionary must contain the key “cat_type”, which can be either “sidereal” (fixed position in RA/Dec), “ephem” (position in RA/Dec whichmoves with time), “driftscan” (fixed postion in Az/El, NOT the same as phase_type`=”drift”) and “unphased” (baseline coordinates in ENU, but data are not phased, similar to `phase_type`=”drift”). Other typical keyworks include “cat_lon” (longitude coord, e.g. RA), “cat_lat” (latitude coord, e.g. Dec.), “cat_frame” (coordinate frame, e.g. icrs), “cat_epoch” (epoch and equinox of the coordinate frame), “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), “cat_vrad” (rest frame velocity), “info_source” (describes where catalog info came from), and “cat_id” (matched to the parameter `phase_center_id_array. See the documentation of the phase method for more details.
phase_center_dec: Required if phase_type = “phased”. Declination of phase center (see uvw_array), units radians. Can also be accessed using phase_center_dec_degrees.
phase_center_epoch: Required if phase_type = “phased”. Epoch year of the phase applied to the data (eg 2000.)
phase_center_frame: Only relevant if phase_type = “phased”. Specifies the frame the data and uvw_array are phased to. Options are “icrs”, “gcrs”, and “fk5”; default is “icrs”.
phase_center_frame_pa: Required if phase_type = “phased”. 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: Required if multi_phase_center = True. Maps individual indices along the Nblt axis to an entry in phase_center_catalog, with the ID number of individual entries stored as cat_id, along with other metadata. Shape (Nblts), type = int.
phase_center_ra: Required if phase_type = ‘phased’. Right ascension of phase center (see uvw_array), units radians. Can also be accessed using phase_center_ra_degrees.
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.
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 for certain phase_types and others are always optional.

rename_phase_center(old_name, new_name)[source]¶

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

Parameters

old_name (str) – Phase center name for the data to be renamed.
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, if old_name is not found as a key in phase_center_catalog, if new_name already exists as a key in phase_center_catalog, or if attempting to name a source “unphased” (which is reserved).
TypeError – If new_name is not actually a string.

split_phase_center(cat_name, new_name, select_mask, 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

cat_name (str) – Name of the phase center to be split.
new_name (str) – New name for the object.
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).
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 attempting to run the method on a non multi phase center data set, if old_name is not found as a key in phase_center_catalog, if new_name already exists as a key in phase_center_catalog, or if attempting to name a source “unphased” (which is reserved). Also raised if select_mask contains data that doesn’t belong to cat_name, unless setting downselect to 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(catname1, catname2, force_merge=False)[source]¶

Merge two differently named objects into one within a mutli-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

catname1 (str) – String containing the name of the first phase center. Note that this name will be preserved in the UVData object.
catname2 (str) – String containing the name of the second phase center, which will be merged into the first phase center. Note that once the merge is complete, all information about this phase center is removed.
force_merge (bool) – Normally, the method will throw an error if the phase center properties differ for catname1 and catname2. This can be overriden by setting this to True. 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(cat_name=None, hms_format=None, return_str=False, print_table=True)[source]¶

Print out the details of objects in a mutli-phase-ctr data set.

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

cat_name (str) – Optional parameter which, if provided, will cause the method to only return information on the phase center with the matching name. 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)[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.
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()[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 entiries in flex_spw_polarization_array).

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

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

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 ENU (topocentric) 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 ENU (topocentric) 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]¶

Rearrange polarizations in the event they are not uvfits compatible.

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.

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 appended 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 array of length Nspws that specifies the new order, with values matched to the specral window number given in spw_array. 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 include freq, which will sort channels within a spectral window by frequency. A ‘-‘ can be optionally appended to signify descending order instead of the default ascending order. 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 freq_screen (the latter overrides the former).
ValueError – Raised if select_spw contains values not in spw_array, or if freq_screen 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”.

unphase_to_drift(phase_frame=None, use_ant_pos=True, use_old_proj=False)[source]¶

Convert from a phased dataset to a drift dataset.

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

Parameters

phase_frame (str) – The astropy frame to phase from. Either ‘icrs’ or ‘gcrs’. ‘gcrs’ accounts for precession & nutation, ‘icrs’ also includes abberation. Defaults to using the ‘phase_center_frame’ attribute or ‘icrs’ if that attribute is None.
use_ant_pos (bool) – If True, calculate the uvws directly from the antenna positions rather than from the existing uvws. Default is True.
use_old_proj (bool) – If True, uses the ‘old’ way of calculating baseline projections. Default is False.

Raises

ValueError – If the phase_type is not ‘phased’

phase(ra, dec, epoch='J2000', phase_frame='icrs', 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, allow_rephase=True, orig_phase_frame=None, select_mask=None, cleanup_old_sources=True, use_old_proj=False, fix_old_proj=True)[source]¶

Phase a drift scan dataset to a single ra/dec at a particular epoch.

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

Tested against MWA_Tools/CONV2UVFITS/convutils.

Parameters

ra (float) – The ra to phase to in radians.
dec (float) – The dec 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. Either ‘icrs’ or ‘gcrs’. ‘gcrs’ accounts for precession & nutation, ‘icrs’ accounts for precession, nutation & abberation.
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”, other selections are only permissible if multi_phase_center=True.
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 and driftscan 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 and driftscan 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 if multi_phase_center=True, otherwise object_name set to this value.
lookup_name (bool) – Only used if multi_phase_center=True, 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.
allow_rephase (bool) – If True, allow unphasing and rephasing if this object is already phased.
orig_phase_frame (str) – The original phase frame of this object (to use in unphasing). Only used if the object is already phased, allow_rephase is True and the phase_center_ra/dec of the object does not match ra and dec. Defaults to using the ‘phase_center_frame’ attribute or ‘icrs’ if that attribute is None.
select_mask (ndarray of bool) – Optional mask for selecting which data to operate on along the blt-axis, only used if with multi phase center data sets (i.e., multi_phase_center=True). Shape is (Nblts,).
use_old_proj (bool) – If True, use the “old” method for calculating baseline uvw-coordinates, which involved using astropy to move antenna positions (in ITRF) into the requested reference frame (either GCRS or ICRS). Default is False.
fix_old_proj (bool) – If True, the method will convert a data set with coordinates calculated using the “old” method, correct them, and then produce new coordinates using the “new” method.

Raises

ValueError – If the phase_type is ‘phased’ and allow_rephase is False

phase_to_time(time, phase_frame='icrs', use_ant_pos=True, use_old_proj=False, allow_rephase=True, orig_phase_frame=None, select_mask=None)[source]¶

Phase a drift scan dataset 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. Either ‘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.
allow_rephase (bool) – If True, allow unphasing and rephasing if this object is already phased.
orig_phase_frame (str) – The original phase frame of this object (to use in unphasing). Only used if the object is already phased, allow_rephase is True and the phase_center_ra/dec of the object does not match ra and dec. Defaults to using the ‘phase_center_frame’ attribute or ‘icrs’ if that attribute is None.
select_mask (array_like) – Selection mask for which data should be rephased, only applicable if multi_phase_center=True. 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

ValueError – If the phase_type is not ‘drift’
TypeError – If time is not an astropy.time.Time object or Julian Date as a float

set_uvws_from_antenna_positions(allow_phasing=False, require_phasing=True, orig_phase_frame=None, output_phase_frame='icrs', use_old_proj=False)[source]¶

Calculate UVWs based on antenna_positions.

Parameters

allow_phasing (bool) – Option for phased data. If data is phased and allow_phasing=True, UVWs will be calculated and the visibilities will be rephased. Default is False.
require_phasing (bool) – Option for phased data. If data is phased and require_phasing=True, then the method will throw an error unless allow_phasing=True, otherwise if require_phasing=False and allow_phasing=False, the UVWs will be recalculated but the data will NOT be rephased. This feature should only be used in limited circumstances (e.g., when certain metadata like exact time are not trusted), as misuse can significantly corrupt data.
orig_phase_frame (str) – The astropy frame to phase from. Either ‘icrs’ or ‘gcrs’. Defaults to using the ‘phase_center_frame’ attribute or ‘icrs’ if that attribute is None. Only used if allow_phasing is True and use_old_proj is True.
output_phase_frame (str) – The astropy frame to phase to. Either ‘icrs’ or ‘gcrs’. Only used if allow_phasing is True, and use_old_proj is True.
use_old_proj (bool) – If set to True, uses the ‘old’ method of calculating baseline vectors. Default is False, which will instead use the ‘new’ method.

Raises

ValueError – If data is phased and allow_phasing is False.

Warns

UserWarning – If the phase_type is ‘phased’

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, phase_center_radec=None, unphase_to_drift=False, phase_frame='icrs', orig_phase_frame=None, use_ant_pos=True, verbose_history=False, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, ignore_name=False)[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.

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.
phase_center_radec (array_like of float) – The phase center to phase the files to before adding the objects in radians (in the ICRS frame). Note that if this keyword is not set and the two UVData objects are phased to different phase centers or if one is phased and one is drift, this method will error because the objects are not compatible.
unphase_to_drift (bool) – If True, unphase the objects to drift before combining them.
phase_frame (str) – The astropy frame to phase to. Either ‘icrs’ or ‘gcrs’. ‘gcrs’ accounts for precession & nutation, ‘icrs’ accounts for precession, nutation & abberation. Only used if phase_center_radec is set.
orig_phase_frame (str) – The original phase frame of the data (if it is already phased). Used for unphasing, only if unphase_to_drift or phase_center_radec are set. Defaults to using the ‘phase_center_frame’ attribute or ‘icrs’ if that attribute is None.
use_ant_pos (bool) – If True, calculate the phased or unphased uvws directly from the antenna positions rather than from the existing uvws. Only used if unphase_to_drift or phase_center_radec are set.
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 multi_phase_center=True, otherwise object_name) when combining two UVData objects. Doing so effectively adopts the name found in the first UVData object in the sum. 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, object_name, and extra_keywords. The object_name values are concatenated if they are different. 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, object_name, and extra_keywords. The object_name values are concatenated if they are different. 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 appended 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, 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.
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.
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)[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 drift mode data. If this is False, drift mode data will be phased before resampling and then unphased after resampling. Phasing and unphasing can introduce small errors, but resampling in drift mode may result in unexpected behavior.

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)[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 averaging of drift mode data. If this is False, drift mode data will be phased before resampling and then unphased after resampling. Phasing and unphasing can introduce small errors, but averaging in drift mode may result in more decoherence.

Returns

None

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)[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 drift mode data. If this is False, drift mode data will be phased before resampling and then unphased after resampling. Phasing and unphasing can introduce small errors, but resampling in drift mode may result in unexpected behavior.

Returns

None

frequency_average(n_chan_to_avg, summing_correlator_mode=False, propagate_flags=False)[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 non-equally spaced channels and varying channel widths. It will also 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. If Nfreqs does not divide evenly by this number, the frequencies at the end of the freq_array will be dropped to make it evenly divisable. To control which frequencies are removed, use select before calling this 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).
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.

get_redundancies(tol=1.0, use_antpos=False, include_conjugates=False, include_autos=True, conjugate_bls=False)[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.

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

Uses utility functions to find redundant baselines to the given tolerance, then select on those.

Parameters

tol (float) – Redundancy tolerance in meters, default is 1.0 corresponding to 1 meter.
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.

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

read_fhd(filelist, use_model=False, read_data=True, background_lsts=True, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, check_autos=True, fix_autos=True)[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).
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.
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.
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.

Raises

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, isource=None, irec=None, isb=None, corrchunk=None, pseudo_cont=False, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, allow_flex_pol=True, check_autos=True, fix_autos=True)[source]¶

Read in data from an SMA MIR file.

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

Parameters

filepath (str) – The file path to the MIR folder to read from.
isource (int) – Source code for MIR dataset. The default is None, which selects all sources.
irec (int) – Receiver code for MIR dataset. The default is None, which selects all receivers.
isb (int) – Sideband code for MIR dataset. The default is None, which selects both sidebands.
corrchunk (int) – Correlator chunk code for MIR dataset. The default is None, which selects all chunks.
pseudo_cont (boolean) – Read in only the pseudo-continuuum values. Default is False.
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.
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, antenna_nums=None, ant_str=None, bls=None, polarizations=None, time_range=None, read_data=True, phase_type=None, correct_lat_lon=True, background_lsts=True, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, calc_lst=True, fix_old_proj=False, fix_use_ant_pos=True, check_autos=True, fix_autos=True)[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 visibility and flag data. If set to false, only the metadata will be read in. Setting read_data to False results in an incompletely defined object (check will not pass).
phase_type (str, optional) – Option to specify the phasing status of the data. Options are ‘drift’, ‘phased’ or None. ‘drift’ means the data are zenith drift data, ‘phased’ means the data are phased to a single RA/Dec. Default is None meaning it will be guessed at based on the file contents.
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. 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.

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 data are multi source or have multiple spectral windows. If the metadata are not internally consistent.

read_ms(filepath, data_column='DATA', pol_order='AIPS', background_lsts=True, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, ignore_single_chan=True, raise_error=True, read_weights=True, allow_flex_pol=True, check_autos=True, fix_autos=True)[source]¶

Read in data from a 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) – Option to specify polarizations order convention, options are ‘CASA’ or ‘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. If detected, by default the reader will throw an error. However, if set to False, the reader will simply give a warning, and will use the first value read in the file as the “correct” metadata in the UVData object.
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.

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, use_aoflagger_flags=None, use_cotter_flags=None, remove_dig_gains=True, remove_coarse_band=None, correct_cable_len=None, correct_van_vleck=False, cheby_approx=True, flag_small_auto_ants=True, flag_small_sig_ants=None, 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, read_data=True, data_array_dtype=<class 'numpy.complex64'>, nsample_array_dtype=<class 'numpy.float32'>, background_lsts=True, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, check_autos=True, fix_autos=True)[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.
use_cotter_flags (bool) – Being replaced by use_aoflagger_flags and will be removed in v2.4.
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.
flag_small_sig_ants (bool) – Being replaced with flag_small_auto_ants and will be removed in v2.4.
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. 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. Only used if file_type is ‘mwa_corr_fits’.
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) – Option to phase to the observation pointing center.
read_data (bool) – Read in the visibility and flag data. If set to false, only the basic header info and metadata read in. Setting read_data to False results in a metdata 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).
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.
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.

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, 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, keep_all_metadata=True, read_data=True, background_lsts=True, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, fix_old_proj=None, fix_use_ant_pos=True, check_autos=True, fix_autos=True)[source]¶

Read in header, metadata and data from a single 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. 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 in the file. Cannot be used with time_range.
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.
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 and flag data. If set to false, only the basic header info and metadata read in. Setting read_data to False results in a metdata 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.

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 data are multi source or have multiple spectral windows. If the metadata are not internally consistent or missing.

read_uvh5(filename, 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, keep_all_metadata=True, read_data=True, data_array_dtype=<class 'numpy.complex128'>, multidim_index=False, background_lsts=True, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, fix_old_proj=None, fix_use_ant_pos=True, check_autos=True, fix_autos=True)[source]¶

Read 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 in the file. Cannot be used with time_range.
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.
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 and flag data. If set to false, only the basic header info and metadata will be read in. Setting read_data to False results in an incompletely defined object (check will not pass).
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) – [Only for HDF5] 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.
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.

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, allow_rephase=True, phase_center_radec=None, unphase_to_drift=False, phase_frame='icrs', phase_epoch=None, orig_phase_frame=None, phase_use_ant_pos=True, antenna_nums=None, antenna_names=None, ant_str=None, bls=None, frequencies=None, freq_chans=None, times=None, polarizations=None, blt_inds=None, time_range=None, keep_all_metadata=True, read_data=True, phase_type=None, correct_lat_lon=True, use_model=False, data_column='DATA', pol_order='AIPS', data_array_dtype=<class 'numpy.complex128'>, nsample_array_dtype=<class 'numpy.float32'>, use_aoflagger_flags=None, use_cotter_flags=None, remove_dig_gains=True, remove_coarse_band=None, correct_cable_len=None, correct_van_vleck=False, cheby_approx=True, flag_small_auto_ants=True, flag_small_sig_ants=None, 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, skip_bad_files=False, multidim_index=False, background_lsts=True, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, isource=None, irec=None, isb=None, corrchunk=None, pseudo_cont=False, lsts=None, lst_range=None, calc_lst=True, fix_old_proj=None, fix_use_ant_pos=True, make_multi_phase=False, ignore_name=False, allow_flex_pol=True, check_autos=True, fix_autos=True)[source]¶

Read a generic file into a UVData object.

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’, ‘fhd’, ‘ms’, ‘uvh5’] 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.
allow_rephase (bool) – Allow rephasing of phased file data so that data from files with different phasing can be combined.
phase_center_radec (array_like of float) – The phase center to phase the files to before adding the objects in radians (in the ICRS frame). If set to None and multiple files are read with different phase centers, the phase center of the first file will be used.
unphase_to_drift (bool) – Unphase the data from the files before combining them.
phase_frame (str) – The astropy frame to phase to. Either ‘icrs’ or ‘gcrs’. ‘gcrs’ accounts for precession & nutation, ‘icrs’ accounts for precession, nutation & abberation. Only used if phase_center_radec is set.
orig_phase_frame (str) – The original phase frame of the data (if it is already phased). Used for unphasing, only if unphase_to_drift or phase_center_radec are set. Defaults to using the ‘phase_center_frame’ attribute or ‘icrs’ if that attribute is None.
phase_use_ant_pos (bool) – If True, calculate the phased or unphased uvws directly from the antenna positions rather than from the existing uvws. Only used if unphase_to_drift or phase_center_radec are set.
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)]) 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, 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 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.
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.
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.
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 data. Only used if file_type is ‘uvfits’, ‘miriad’ or ‘uvh5’. If set to False, only the metadata will be read in. Setting read_data to False results in a metdata only object.
phase_type (str, optional) – Option to specify the phasing status of the data. Only used if file_type is ‘miriad’. Options are ‘drift’, ‘phased’ or None. ‘drift’ means the data are zenith drift data, ‘phased’ means the data are phased to a single RA/Dec. Default is None meaning it will be guessed at based on the file contents.
correct_lat_lon (bool) – Option to update the latitude and longitude from the known_telescopes list if the altitude is missing. Only used if file_type is ‘miriad’.
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). Only used if file_type is ‘fhd’.
data_column (str) – name of CASA data column to read into data_array. Options are: ‘DATA’, ‘MODEL’, or ‘CORRECTED_DATA’. Only used if file_type is ‘ms’.
pol_order (str) – Option to specify polarizations order convention, options are ‘CASA’ or ‘AIPS’. Only used if file_type is ‘ms’.
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’. Only used if file_type is ‘uvh5’ or ‘mwa_corr_fits’.
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). Only used if file_type is ‘mwa_corr_fits’.
use_aoflagger_flags (bool) – Option to use aoflagger mwaf flag files. Defaults to true if aoflagger flag files are submitted.
use_cotter_flags (bool) – Being replaced by use_aoflagger_flags and will be removed in v2.4.
remove_dig_gains (bool) – Only used if file_type is ‘mwa_corr_fits’. Option to divide out digital gains.
remove_coarse_band (bool) – Only used if file_type is ‘mwa_corr_fits’. Option to divide out coarse band shape.
correct_cable_len (bool) – Flag to apply cable length correction. Only used if file_type is ‘mwa_corr_fits’.
correct_van_vleck (bool) – Flag to apply a van vleck correction. Only used if file_type is ‘mwa_corr_fits’.
cheby_approx (bool) – Only used if file_type is ‘mwa_corr_fits’ and correct_van_vleck is True. Option to implement the van vleck correction with a chebyshev polynomial approximation. Set to False to run the integral version of the correction.
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. Only used if file_type is ‘mwa_corr_fits’.
flag_small_sig_ants (bool) – Being replaced by flag_small_auto_ants and will be removed in v2.4.
propogate_coarse_flags (bool) – Option to propogate flags for missing coarse channel integrations across frequency. Only used if file_type is ‘mwa_corr_fits’.
flag_init (bool) – Only used if file_type is ‘mwa_corr_fits’. 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 file_type is ‘mwa_corr_fits’ and 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 file_type is ‘mwa_corr_fits’ and 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 file_type is ‘mwa_corr_fits’ and flag_init is True. Set to True to flag the center fine channel of each coarse channel. Only used if file_type is ‘mwa_corr_fits’.
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. Only used if file_type is ‘mwa_corr_fits’.
phase_to_pointing_center (bool) – Flag to phase to the pointing center. Only used if file_type is ‘mwa_corr_fits’. Cannot be set if phase_center_radec is not None.
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).
multidim_index (bool) – [Only for HDF5] 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.
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.
isource (int) – Source code for MIR dataset
irec (int) – Receiver code for MIR dataset
isb (int) – Sideband code for MIR dataset
corrchunk (int) – Correlator chunk code for MIR dataset
pseudo_cont (boolean) – Read in only pseudo-continuuum values in MIR dataset. Default is false.
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.
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. Only applies to MIRIAD files.
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.
make_multi_phase (bool) – Option to make the output a multi phase center dataset, capable of holding data on multiple phase centers. By default, this is only done if reading in a file with multiple sources.
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.
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. Only applicable for MIR and MS filetypes, otherwise this argument is ignored. 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.

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 the data are multi source or have multiple spectral windows. If phase_center_radec is not None and is not length 2.

classmethod from_file(filename, axis=None, file_type=None, allow_rephase=True, phase_center_radec=None, unphase_to_drift=False, phase_frame='icrs', phase_epoch=None, orig_phase_frame=None, phase_use_ant_pos=True, antenna_nums=None, antenna_names=None, ant_str=None, bls=None, frequencies=None, freq_chans=None, times=None, polarizations=None, blt_inds=None, time_range=None, keep_all_metadata=True, read_data=True, phase_type=None, correct_lat_lon=True, use_model=False, data_column='DATA', pol_order='AIPS', data_array_dtype=<class 'numpy.complex128'>, nsample_array_dtype=<class 'numpy.float32'>, use_aoflagger_flags=None, use_cotter_flags=None, remove_dig_gains=True, remove_coarse_band=None, correct_cable_len=None, correct_van_vleck=False, cheby_approx=True, flag_small_auto_ants=True, flag_small_sig_ants=None, 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, skip_bad_files=False, multidim_index=False, background_lsts=True, run_check=True, check_extra=True, run_check_acceptability=True, strict_uvw_antpos_check=False, isource=None, irec=None, isb=None, corrchunk=None, pseudo_cont=False, lsts=None, lst_range=None, calc_lst=True, fix_old_proj=None, fix_use_ant_pos=True, make_multi_phase=False, ignore_name=False, allow_flex_pol=True, check_autos=True, fix_autos=True)[source]¶

Initialize a new UVData object by reading the input file.

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’, ‘fhd’, ‘ms’, ‘uvh5’] 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.
allow_rephase (bool) – Allow rephasing of phased file data so that data from files with different phasing can be combined.
phase_center_radec (array_like of float) – The phase center to phase the files to before adding the objects in radians (in the ICRS frame). If set to None and multiple files are read with different phase centers, the phase center of the first file will be used.
unphase_to_drift (bool) – Unphase the data from the files before combining them.
phase_frame (str) – The astropy frame to phase to. Either ‘icrs’ or ‘gcrs’. ‘gcrs’ accounts for precession & nutation, ‘icrs’ accounts for precession, nutation & abberation. Only used if phase_center_radec is set.
orig_phase_frame (str) – The original phase frame of the data (if it is already phased). Used for unphasing, only if unphase_to_drift or phase_center_radec are set. Defaults to using the ‘phase_center_frame’ attribute or ‘icrs’ if that attribute is None.
phase_use_ant_pos (bool) – If True, calculate the phased or unphased uvws directly from the antenna positions rather than from the existing uvws. Only used if unphase_to_drift or phase_center_radec are set.
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)]) 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, 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 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.
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.
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.
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 data. Only used if file_type is ‘uvfits’, ‘miriad’ or ‘uvh5’. If set to False, only the metadata will be read in. Setting read_data to False results in a metdata only object.
phase_type (str, optional) – Option to specify the phasing status of the data. Only used if file_type is ‘miriad’. Options are ‘drift’, ‘phased’ or None. ‘drift’ means the data are zenith drift data, ‘phased’ means the data are phased to a single RA/Dec. Default is None meaning it will be guessed at based on the file contents.
correct_lat_lon (bool) – Option to update the latitude and longitude from the known_telescopes list if the altitude is missing. Only used if file_type is ‘miriad’.
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). Only used if file_type is ‘fhd’.
data_column (str) – name of CASA data column to read into data_array. Options are: ‘DATA’, ‘MODEL’, or ‘CORRECTED_DATA’. Only used if file_type is ‘ms’.
pol_order (str) – Option to specify polarizations order convention, options are ‘CASA’ or ‘AIPS’. Only used if file_type is ‘ms’.
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’. Only used if file_type is ‘uvh5’ or ‘mwa_corr_fits’.
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). Only used if file_type is ‘mwa_corr_fits’.
use_aoflagger_flags (bool) – Only used if file_type is ‘mwa_corr_fits’. Option to use aoflagger mwaf flag files. Defaults to true if aoflagger flag files are submitted.
use_cotter_flags (bool) – Being replaced by use_aoflagger_flags and will be removed in v2.4.
remove_dig_gains (bool) – Only used if file_type is ‘mwa_corr_fits’. Option to divide out digital gains.
remove_coarse_band (bool) – Only used if file_type is ‘mwa_corr_fits’. Option to divide out coarse band shape.
correct_cable_len (bool) – Flag to apply cable length correction. Only used if file_type is ‘mwa_corr_fits’.
correct_van_vleck (bool) – Flag to apply a van vleck correction. Only used if file_type is ‘mwa_corr_fits’.
cheby_approx (bool) – Only used if file_type is ‘mwa_corr_fits’ and correct_van_vleck is True. Option to implement the van vleck correction with a chebyshev polynomial approximation. Set to False to run the integral version of the correction.
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. Only used if file_type is ‘mwa_corr_fits’.
flag_small_sig_ants (bool) – Being replaced by flag_small_auto_ants and will be removed in v2.4.
propogate_coarse_flags (bool) – Option to propogate flags for missing coarse channel integrations across frequency. Only used if file_type is ‘mwa_corr_fits’.
flag_init (bool) – Only used if file_type is ‘mwa_corr_fits’. 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 file_type is ‘mwa_corr_fits’ and 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 file_type is ‘mwa_corr_fits’ and 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 file_type is ‘mwa_corr_fits’ and flag_init is True. Set to True to flag the center fine channel of each coarse channel. Only used if file_type is ‘mwa_corr_fits’.
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. Only used if file_type is ‘mwa_corr_fits’.
phase_to_pointing_center (bool) – Flag to phase to the pointing center. Only used if file_type is ‘mwa_corr_fits’. Cannot be set if phase_center_radec is not None.
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).
multidim_index (bool) – [Only for HDF5] 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.
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.
isource (int) – Source code for MIR dataset
irec (int) – Receiver code for MIR dataset
isb (int) – Sideband code for MIR dataset
corrchunk (int) – Correlator chunk code for MIR dataset
pseudo_cont (boolean) – Read in only pseudo-continuuum values in MIR dataset. Default is false.
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.
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. Only applies to MIRIAD files.
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.
make_multi_phase (bool) – Option to make the output a multi phase center dataset, capable of holding data on multiple phase centers. By default, this is only done if reading in a file with multiple sources.
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.
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. Only applicable for MIR and MS filetypes, otherwise this argument is ignored. 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.

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 the data are multi source or have multiple spectral windows. 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, 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 drift scan data to zenith of the first timestamp.
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, spoof_nonessential=False, 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)[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.
spoof_nonessential (bool) – Option to spoof the values of optional UVParameters that are not set but are required for uvfits files.
write_lst (bool) – Option to write the LSTs to the metadata (random group parameters).
force_phase (: bool) – Option to automatically phase drift scan 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.

Raises

ValueError – The phase_type of the object is “drift” and the 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. Any of [‘antenna_positions’, ‘gst0’, ‘rdate’, ‘earth_omega’, ‘dut1’, ‘timesys’] are not set on the object and spoof_nonessential is False. 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 meaning no filter or compression. Dataset must be chunked.
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 meaning no filter or compression. Dataset must be chunked.
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, 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.
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.
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.

last updated: 2022-02-16