UVCal Class

UVCal is the main user class for calibration solutions. It provides import and export functionality to all supported file formats (calfits) and can be interacted with directly.

class pyuvdata.UVCal[source]

A class defining calibration solutions.

Currently supported file types: calfits

UVParameter objects

(http://pyuvdata.readthedocs.io/en/latest/uvcal_parameters.html). Some are always required, some are required for certain cal_types and others are always optional.

Type

For full list see UVCal Parameters

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

set_telescope_params(overwrite=False)[source]

Set telescope related parameters.

If the telescope_name is in the known_telescopes, set the telescope location to the value for the known telescope. Also set the antenna positions if they are not set on the object and are available for the 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.

check(check_extra=True, run_check_acceptability=True, check_freq_spacing=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 UVCal objects in general but is required to write to calfits files.

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 UVCal object.

Parameters

metadata_only (bool) – If True, only copy the metadata of the object.

Returns

UVCal – Copy of self.

ant2ind(antnum)[source]

Get the index in data arrays for an antenna number.

Parameters

antnum (int) – Antenna number to get index for.

Returns

int – Antenna index in data arrays.

jpol2ind(jpol)[source]

Get the index in data arrays for an antenna polarization.

Parameters

jpol (int or str) – Antenna polarization to get index for.

Returns

int – Antenna polarization index in data arrays

get_gains(ant, jpol=None, squeeze_pol=True)[source]

Get the gain associated with an antenna and/or polarization.

Parameters
  • ant (int or length 2 tuple of ints or int and str) – Antenna or antenna and polarization to get gains for. If it’s a length 2 tuple, the second value must be an antenna polarization int or string parsable by jpol2ind.

  • jpol (int or str, optional) – Instrumental polarization to request. Ex. ‘Jxx’

  • squeeze_pol (bool) – Option to squeeze pol dimension if possible.

Returns

complex ndarray – Gain solution of shape (Nfreqs, Ntimes, Npol) or (Nfreqs, Ntimes) if jpol is set or if squeeze_pol is True and Njones = 1.

get_flags(ant, jpol=None, squeeze_pol=True)[source]

Get the flags associated with an antenna and/or polarization.

Parameters
  • ant (int or length 2 tuple of ints or int and str) – Antenna or antenna and polarization to get gains for. If it’s a length 2 tuple, the second value must be an antenna polarization int or string parsable by jpol2ind.

  • jpol (int or str, optional) – Instrumental polarization to request. Ex. ‘Jxx’

  • squeeze_pol (bool) – Option to squeeze pol dimension if possible.

Returns

boolean ndarray – Flags of shape (Nfreqs, Ntimes, Npol) or (Nfreqs, Ntimes) if jpol is set or if squeeze_pol is True and Njones = 1.

get_quality(ant, jpol=None, squeeze_pol=True)[source]

Get the qualities associated with an antenna and/or polarization.

Parameters
  • ant (int or length 2 tuple of ints or int and str) – Antenna or antenna and polarization to get gains for. If it’s a length 2 tuple, the second value must be an antenna polarization int or string parsable by jpol2ind.

  • jpol (int or str, optional) – Instrumental polarization to request. Ex. ‘Jxx’

  • squeeze_pol (bool) – Option to squeeze pol dimension if possible.

Returns

float ndarray – Qualities of shape (Nfreqs, Ntimes, Npol) or (Nfreqs, Ntimes) if jpol is not None or if squeeze_pol is True and Njones = 1.

convert_to_gain(freq_array=None, channel_width=None, delay_convention='minus', run_check=True, check_extra=True, run_check_acceptability=True)[source]

Convert non-gain cal_types to gains.

For the delay cal_type the gain is calculated as:

gain = 1 * exp((+/-) * 2 * pi * j * delay * frequency) where the (+/-) is dictated by the delay_convention

Parameters
  • delay_convention (str) – Exponent sign to use in the conversion, can be “plus” or “minus”.

  • freq_array (array of float) – Frequencies to convert to gain at, units Hz. Not providing a freq_array is deprecated, but until version 3.0, if it is not provided and freq_array exists on the object, freq_array will be used.

  • run_check (bool) – Option to check for the existence and proper shapes of parameters after converting.

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

select(antenna_nums=None, antenna_names=None, frequencies=None, freq_chans=None, spws=None, times=None, jones=None, run_check=True, check_extra=True, run_check_acceptability=True, inplace=True)[source]

Downselect data to keep on the object along various axes.

Axes that can be selected along include antennas, frequencies, times and antenna polarization (jones).

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). 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). This cannot be provided if antenna_nums is also provided.

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

  • spws (array_like of in, optional) – The spectral window numbers to keep in the object. If this is not a wide-band object and frequencies or freq_chans is not None, frequencies that match any of the specifications will be kept (i.e. the selections will be OR’ed together).

  • times (array_like of float, optional) – The times to keep in the object, each value passed here should exist in the time_array.

  • jones (array_like of int or str, optional) – The antenna polarizations numbers to keep in the object, each value passed here should exist in the jones_array. If passing strings, the canonical polarization strings (e.g. “Jxx”, “Jrr”) are supported and if the x_orientation attribute is set, the physical dipole strings (e.g. “Jnn”, “Jee”) are also supported.

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

  • inplace (bool) – Option to perform the select directly on self or return a new UVCal object with just the selected data (the default is True, meaning the select will be done on self).

read_calfits(filename, read_data=True, run_check=True, check_extra=True, run_check_acceptability=True)[source]

Read in data from calfits file(s).

Parameters
  • filename (str or list of str) – The calfits file(s) to read from.

  • read_data (bool) – Read in the gains or delays, quality arrays and flag arrays. If set to False, only the metadata will be read in. Setting read_data to False results in a metadata only object.

  • run_check (bool) – Option to check for the existence and proper shapes of parameters after reading in 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 after reading in the file.

read_fhd_cal(cal_file, obs_file, layout_file=None, settings_file=None, raw=True, read_data=True, extra_history=None, run_check=True, check_extra=True, run_check_acceptability=True)[source]

Read data from an FHD cal.sav file.

Parameters
  • cal_file (str or list of str) – The cal.sav file or list of files to read from.

  • obs_file (str or list of str) – The obs.sav file or list of files to read from.

  • layout_file (str) – The FHD layout file. Required for antenna_positions to be set.

  • settings_file (str or list of str, optional) – The settings_file or list of files to read from. Optional, but very useful for provenance.

  • raw (bool) – Option to use the raw (per antenna, per frequency) solution or to use the fitted (polynomial over phase/amplitude) solution. Default is True (meaning use the raw solutions).

  • read_data (bool) – Read in the gains, quality array 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. Note that if read_data is False, metadata is derived entirely from the obs_file, which may result in slightly different values than if it is derived from the cal file.

  • extra_history (str or list of str, optional) – String(s) to add to the object’s history parameter.

  • run_check (bool) – Option to check for the existence and proper shapes of parameters after reading in 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 after reading in the file.

write_calfits(filename, run_check=True, check_extra=True, run_check_acceptability=True, clobber=False)[source]

Write the data to a calfits file.

Parameters
  • filename (str) – The calfits file to write to.

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

  • clobber (bool) – Option to overwrite the filename if the file already exists.

Raises

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