UVCal
UVCal is the main user class for calibration solutions for interferometric data sets. It provides import and export functionality to and from the supported file formats (calfits, FHD) as well as methods for transforming the data (converting types, selecting, sorting) and can be interacted with directly.
Attributes
The attributes on UVCal hold all of the metadata and data required to
work with calibration solutions for 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.
Starting in version 3.0, metadata that is associated with the telescope
(as opposed to the data set) is stored in a pyuvdata.Telescope
object (see Telescope) as the telescope
attribute on a
UVCal object. This includes metadata related to the telescope location,
antenna names, numbers and positions as well as other telescope metadata.
UVCal objects can be initialized in many ways: from a file using the
pyuvdata.UVCal.from_file()
class method
(as uvc = UVCal.from_file(<filename>)
), from arrays in memory using
the pyuvdata.UVCal.new()
class method, from a
pyvdata.UVData
object using the
pyuvdata.UVCal.initialize_from_uvdata()
class method, or as an
empty object (as cal = UVCal()
).
When an empty UVCal 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.UVCal.read()
method or by setting them
directly on the object. Some of these attributes are required to be
set to have a fully defined calibration data set while others are
optional. The pyuvdata.UVCal.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 (gain_array
,
delay_array
, flag_array
, quality_array
) are not. The
pyuvdata.UVCal.check()
method will still pass for metadata only
objects.
Required
These parameters are required to have a well-defined UVCal object and are required for most kinds of uv cal files.
- Nants_data
Number of antennas that have data associated with them (i.e. length of ant_array), which may be smaller than the numberof antennas in the telescope (i.e. length of antenna_numbers).
- Nfreqs
Number of frequency channels
- Njones
Number of Jones calibration parameters (Number of Jones matrix elements calculated in calibration).
- Nspws
Number of spectral windows (ie non-contiguous spectral chunks).
- Ntimes
Number of times with different calibrations calculated (if a calibration is calculated over a range of integrations, this gives the number of separate calibrations along the time axis).
- ant_array
Array of integer antenna numbers that appear in self.gain_array, with shape (Nants_data,). This array is ordered to match the inherent ordering of the zeroth axis of self.gain_array.
- cal_style
Style of calibration. Values are sky or redundant.
- cal_type
cal type parameter. Values are delay or gain.
- channel_width
Width of frequency channels (Hz). Array of shape (Nfreqs,), type = float.Should not be set if wide_band=True.
- flag_array
Array of flags to be applied to calibrated data (logical OR of input and flag generated by calibration). True is flagged. Shape: (Nants_data, Nfreqs, Ntimes, Njones) if wide_band=False or (Nants_data, Nspws, Ntimes, Njones) if wide_band=True, type = bool.
- flex_spw_id_array
Required for non-wide-band objects. Maps individual channels along the frequency axis to individual spectral windows, as listed in the spw_array. Shape (Nfreqs), type = int.
- freq_array
Array of frequencies, center of the channel, shape (Nfreqs,) , units Hz.Should not be set if wide_band=True.
- gain_convention
The convention for applying the calibration solutions to data.Values are “divide” or “multiply”, indicating that to calibrate one should divide or multiply uncalibrated data by gains. Mathematically this indicates the alpha exponent in the equation: calibrated data = gain^alpha * uncalibrated data. A value of “divide” represents alpha=-1 and “multiply” represents alpha=1.
- history
String of history, units English
- integration_time
Integration time of a calibration solution, units seconds. Shape (Ntimes), type float. Should be the total integration time of the data that went into calculating the calibration solution (i.e. the visibility integration time for calibration solutions that are calculated per visibility integration, the sum of the integration times that go into a calibration solution that was calculated over a range of integration times).
- jones_array
Array of antenna polarization integers, shape (Njones). linear pols -5:-8 (jxx, jyy, jxy, jyx).circular pols -1:-4 (jrr, jll. jrl, jlr).unknown 0.
- spw_array
Array of spectral window numbers, shape (Nspws).
- telescope
pyuvdata.Telescope
object containing the telescope metadata.- wide_band
Option to support ‘wide-band’ calibration solutions with gains or delays that apply over a range of frequencies rather than having distinct values at each frequency. Delay type cal solutions are always ‘wide-band’. If it is True several other parameters are affected: the data-like arrays have a spw axis that is Nspws long rather than a frequency axis that is Nfreqs long; the freq_range parameter is required and the freq_array and channel_width parameters should not be set.
Optional
These parameters are defined by one or more file standard but are not always required. Some of them are required depending on the cal_type or cal_style (as noted below).
- Nphase
Specifies the number of phase centers contained within the calibration solution catalog.
- Nsources
Number of sources used.
- baseline_range
Range of baselines used for calibration.
- delay_array
Required if cal_type = “delay”. Array of delays with units of seconds. Shape: (Nants_data, Nspws, Ntimes, Njones), type=float.
- diffuse_model
Name of diffuse model.
- extra_keywords
Any user supplied extra keywords, type=dict. Keys should be 8 character or less strings if writing to calfits 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.
- flex_jones_array
Optional parameter that allows for labeling individual spectral windows with different polarizations. If set, Njones must be set to 1 (i.e., only one Jones vector per spectral window allowed). Shape (Nspws), type = int.
- freq_range
Required if cal_type=’delay’ or wide_band=True. Frequency range that solutions are valid for, with [start_frequency, end_frequency] provided for each spectral window. Array of shape (Nspws, 2). Units are Hz.Should not be set if cal_type=’gain’ and wide_band=False.
- gain_array
Required if cal_type = “gain”. Array of gains, shape: (Nants_data, Nfreqs, Ntimes, Njones) if wide_band=False, or (Nants_data, Nspws, Ntimes, Njones) if wide_band=True, type = complex float.
- gain_scale
The gain scale of the calibration, which indicates the units of the calibrated visibilities. For example, Jy or K str.
- git_hash_cal
Commit hash of calibration software (from git_origin_cal) used to generate solutions.
- git_origin_cal
Origin (on github for e.g) of calibration software. Url and branch.
- lst_array
Array of lsts, center of integration, shape (Ntimes), units radians. Should only be set cal solutions were calculated per integration (rather than over a range of integrations). Only one of lst_range and lst_array should be set.
- lst_range
LST range (in JD) that cal solutions are valid for. This should be an array with shape (Ntimes, 2) where the second axis gives the start_lst and end_lst (in that order) in radians. Should only be set if the cal solutions apply over a range of times. Only one of lst_range and lst_array should be set.
- observer
Name of observer who calculated solutions in this file.
- phase_center_catalog
Optional parameter, similar to the UVData parameter of the same name. Dictionary that acts as a catalog, containing information on individual phase centers. Keys are the catalog IDs of the different phase centers in the object (matched to the parameter
phase_center_id_array
). At a minimum, each dictionary must contain the keys: ‘cat_name’ giving the phase center name (this does not have to be unique, non-unique values can be used to indicate sets of phase centers that make up a mosaic observation), ‘cat_type’, which can be ‘sidereal’ (fixed position in RA/Dec), ‘ephem’ (position in RA/Dec which moves with time), ‘driftscan’ (fixed postion in Az/El, NOT the same as the oldphase_type
= ‘drift’) or ‘unprojected’ (baseline coordinates in ENU, but data are not phased, similar to the oldphase_type
= ‘drift’) ‘cat_lon’ (longitude coord, e.g. RA, either a single value or a one dimensional array of length Npts –the number of ephemeris data points– for ephem type phase centers), ‘cat_lat’ (latitude coord, e.g. Dec., either a single value or a one dimensional array of length Npts –the number of ephemeris data points– for ephem type phase centers), ‘cat_frame’ (coordinate frame, e.g. icrs, must be a frame supported by astropy). Other optional keys include ‘cat_epoch’ (epoch and equinox of the coordinate frame, not needed for frames without an epoch (e.g. ICRS) unless the there is proper motion), ‘cat_times’ (times for the coordinates, only used for ‘ephem’ types), ‘cat_pm_ra’ (proper motion in RA), ‘cat_pm_dec’ (proper motion in Dec), ‘cat_dist’ (physical distance to the source in parsec, useful if parallax is important, either a single value or a one dimensional array of length Npts –the number of ephemeris data points– for ephem type phase centers.), ‘cat_vrad’ (rest frame velocity in km/s, either a single value or a one dimensional array of length Npts –the number of ephemeris data points– for ephem type phase centers.), and ‘info_source’ (describes where catalog info came from). Most typically used with MS calibration tables.- phase_center_id_array
Optional parameter, similar to the UVData parameter of the same name. Maps individual indices along the Ntimes axis to a key in phase_center_catalog, which maps to a dict containing the other metadata for each phase center. Used to specify where the data were phased to when calibration tables were derived. Most typically used when reading MS calibration tables. Shape (Nblts), type = int.
- pol_convention
The convention for how instrumental polarizations (e.g. XX and YY) are converted to Stokes parameters. Options are ‘sum’ and ‘avg’, corresponding to I=XX+YY and I=(XX+YY)/2 (for linear instrumental polarizations) respectively. This parameter is not required, for backwards-compatibility reasons, but is highly recommended. If pol_convention is set, gain_scale should also be set.
- quality_array
Array of qualities of calibration solutions.Shape: (Nants_data, Nfreqs, Ntimes, Njones) if wide_band=False or (Nants_data, Nspws, Ntimes, Njones) if wide_band=True, type = float.
- ref_antenna_array
Optional argument, only used if cal_style = “sky”. Allows one to specifya different phase reference antenna per time interval. Shape (Ntimes,), type=int.
- ref_antenna_name
Required if cal_style = “sky”. Phase reference antenna.
- scan_number_array
Optional when reading an MS cal table. Retains the scan number when reading a measurement set. Shape (Nblts), type = int.
- sky_catalog
Required if cal_style = “sky”. Name of calibration catalog.
- time_array
Array of calibration solution times, center of integration, shape (Ntimes), units Julian Date. Should only be set cal solutions were calculated per integration (rather than over a range of integrations). Only one of time_range and time_array should be set.
- time_range
Time range (in JD) that cal solutions are valid for. This should be an array with shape (Ntimes, 2) where the second axis gives the start_time and end_time (in that order) in JD. Should only be set if the cal solutions apply over a range of times. Only one of time_range and time_array should be set.
- total_quality_array
Array of qualities of the calibration for entire arrays. The shape depends on cal_type, if the cal_type is ‘gain’, the shape is: (Nfreqs, Ntimes, Njones) if wide_band=False, or (Nspws, Ntimes, Njones) if wide_band=True. If the cal_type is ‘delay’, the shape is (Nspws, Ntimes, Njones), type = float.
Methods
- class pyuvdata.UVCal[source]
A class defining calibration solutions for interferometric data.
- 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 cal_types and cal_styles and others are always optional.
- static new(**kwargs)[source]
Create a new UVCal object.
All parameters are passed through to the
new_uvcal()
function.- Returns:
UVCal – A new UVCal object.
- Other Parameters:
time_array (ndarray of float) – Array of times of the center of the integrations, in Julian Date. Only one of time_array or time_range should be supplied.
time_range (ndarray of float) – Array of start and stop times for calibrations solutions, in Julian Date. A two-dimensional array with shape (Ntimes, 2) where the second axis gives the start time and stop time (in that order). Only one of time_array or time_range should be supplied.
cal_style (str) – Calibration style. Options are ‘sky’ or ‘redundant’.
freq_array (ndarray of float, optional) – Array of frequencies in Hz. If given, the freq_range parameter is ignored, and the cal type is assumed to be “gain”.
freq_range (ndarray of float, optional) – Frequency ranges in Hz. Must be given if
freq_array
is not given. If given, the calibration is assumed to be wide band. The array shape should be (Nspws, 2)gain_convention (str) – Gain convention. Options are ‘divide’ or ‘multiply’.
jones_array (ndarray of int or str) – Array of Jones polarization integers. If a string, options are ‘linear’ or ‘circular’ (which will be converted to the appropriate Jones integers as length-4 arrays).
cal_type (str, optional) – Calibration type. Options are ‘delay’, ‘gain’. Forced to be ‘gain’ if
freq_array
is given, and by default set to ‘delay’ if not.integration_time (float or ndarray of float, optional) – Integration time in seconds. If not provided, it will be derived from the time_array or time_range. If derived from the time_array, it will be the difference between successive times (with the last time-diff appended), if the number of unique times is one, then a warning will be raised and the integration time set to 1 second. If derived from the time_range it will be the difference between the start and stop times for each range. If a float is provided, it will be used for all integrations. If an ndarray is provided, it must have the same shape as time_array or the first axis of time_range.
channel_width (float or ndarray of float, optional) – Channel width in Hz. If not provided, it will be derived from the freq_array, as the difference between successive frequencies (with the last frequency-diff appended). If a float is provided, it will be used for all channels. If not provided and freq_array is length-one, the channel_width will be set to 1 Hz (and a warning issued). If an ndarray is provided, it must have the same shape as freq_array.
telescope (pyuvdata.Telescope) – Telescope object containing the telescope-related metadata including telescope name and location, x_orientation and antenna names, numbers and positions.
telescope_location (EarthLocation or MoonLocation object) – Deprecated. Telescope location as an astropy EarthLocation object or MoonLocation object. Not required or used if a Telescope object is passed to telescope.
telescope_name (str) – Deprecated. Telescope name. Not required or used if a Telescope object is passed to telescope.
x_orientation (str) – Deprecated. Orientation of the x-axis. Options are ‘east’, ‘north’, ‘e’, ‘n’, ‘ew’, ‘ns’. Not required or used if a Telescope object is passed to telescope.
antenna_positions (ndarray of float or dict of ndarray of float) – Deprecated. Array of antenna positions in ECEF coordinates in meters. If a dict, keys can either be antenna numbers or antenna names, and values are position arrays. Keys are interpreted as antenna numbers if they are integers, otherwise they are interpreted as antenna names if strings. You cannot provide a mix of different types of keys. Not required or used if a Telescope object is passed to telescope.
antenna_names (list of str, optional) – Deprecated. List of antenna names. Not required or used if a Telescope object is passed to telescope or if antenna_positions is a dict with string keys. Otherwise, if not provided, antenna numbers will be used to form the antenna_names, according to the antname_format
antenna_numbers (list of int, optional) – Deprecated. List of antenna numbers. Not required or used if a Telescope object is passed to telescope or if antenna_positions is a dict with integer keys. Otherwise, if not provided, antenna names will be used to form the antenna_numbers, but in this case the antenna_names must be strings that can be converted to integers.
antname_format (str, optional) – Deprecated. Format string for antenna names. Default is ‘{0:03d}’.
ant_array (ndarray of int, optional) – Array of antenna numbers actually found in data (in the order of the data in gain_array etc.)
flex_spw_id_array (ndarray of int, optional) – Array of spectral window IDs. If not provided, it will be set to an array of zeros and only one spw will be used.
ref_antenna_name (str, optional) – Name of reference antenna. Only required for sky calibrations.
sky_catalog (str, optional) – Name of sky catalog. Only required for sky calibrations.
empty (bool, optional) – If True, create an empty UVCal object, i.e. add initialized data arrays (eg. gain_array). By default, this function creates a metadata-only object. You can pass in data arrays directly to the constructor if you want to create a fully-populated object.
data (dict of array_like, optional) – Dictionary containing optional data arrays. Possible keys are: ‘gain_array’, ‘delay_array’, ‘quality_array’, ‘flag_array’, and ‘total_quality_array’. If any entry is provided, the output will contain all necessary data-like arrays. Any key not provided in this case will be set to default “empty” values (e.g. all ones for gains, all False for flags) if they are required or None if they are not required (i.e. total_quality_array).
history (str, optional) – History string to be added to the object. Default is a simple string containing the date and time and pyuvdata version.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.
**kwargs – All other keyword arguments are added to the object as attributes.
- 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.
- remove_flex_jones(*, combine_spws=True)[source]
Convert a flex-Jones UVCal object into one with a standard Jones axis.
This will convert a flexible-Jones dataset into one with standard polarization handling, which is required for some operations or writing in certain filetypes. Note that depending on how it is used, this can inflate the size of data-like parameters by up to a factor of Nspws (the true value depends on the number of unique entries in flex_jones_array).
- Parameters:
combine_spws (bool) – If set to True, the method will attempt to recombine multiple windows carrying different Jones vectors/information into a single (multi-Jones) spectral window. Functionally, this is the inverse of what is done in the convert_to_flex_jones method. If set to False, the method will effectively “inflate” the jones-axis of UVCal parameters such that all windows have the same Jones codes (though the added entries will be flagged and will carry no calibration information). Default is True.
- convert_to_flex_jones()[source]
Convert a regular UVCal object into a flex-Jones object.
This effectively combines the frequency and polarization axis with polarization changing slowest. Saving data to uvh5 files this way can speed up some kinds of data access.
- set_telescope_params(*, warn=True, overwrite=False, run_check=True, check_extra=True, run_check_acceptability=True)[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, astrometry_library=None)[source]
Set the lst_array or lst_range from the time_array or time_range.
- Parameters:
background (bool, False) – When set to True, start the calculation on a threading.Thread in the background and return the thread to the user.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.
- Returns:
proc (None or threading.Thread instance) – When background is set to True, a thread is returned which must be joined before the lst_array exists on the UVCal object.
- print_phase_center_info(catalog_identifier=None, *, hms_format=None, return_str=False, print_table=True)[source]
Print out the details of the phase centers.
Prints out an ASCII table that contains the details of the phase_center_catalog attribute, which acts as the internal source catalog for UVCal objects.
- Parameters:
catalog_identifier (str or int or list of str or int) – Optional parameter which, if provided, will cause the method to only return information on the phase center(s) with the matching name(s) or catalog ID number(s). Default is to print out information on all catalog entries.
hms_format (bool) – Optional parameter, which if selected, can be used to force coordinates to be printed out in Hours-Min-Sec (if set to True) or Deg-Min-Sec (if set to False) format. Default is to print out in HMS if all the objects have coordinate frames of icrs, gcrs, fk5, fk4, and top; otherwise, DMS format is used.
return_str (bool) – If set to True, the method returns an ASCII string which contains all the table infrmation. Default is False.
print_table (bool) – If set to True, prints the table to the terminal window. Default is True.
- Returns:
table_str (bool) – If return_str=True, an ASCII string containing the entire table text
- Raises:
ValueError – If cat_name matches no keys in phase_center_catalog.
- check(*, check_extra=True, run_check_acceptability=True, check_freq_spacing=False, lst_tol=3.63610260832152e-07)[source]
Add some extra checks on top of checks on UVBase class.
Check that required parameters exist. Check that parameters have appropriate shapes and optionally that the values are acceptable.
- Parameters:
check_extra (bool) – If true, check all parameters, otherwise only check required parameters.
run_check_acceptability (bool) – Option to check if values in parameters are acceptable.
check_freq_spacing (bool) – Option to check if frequencies are evenly spaced and the spacing is equal to their channel_width. This is not required for UVCal objects in general but is required to write to calfits files.
lst_tol (float or None) – Tolerance level at which to test LSTs against their expected values. If provided as a float, must be in units of radians. If set to None, the default precision tolerance from the lst_array parameter is used (1 mas). Default value is 75 mas, which is set by the predictive uncertainty in IERS calculations of DUT1 (RMS is of order 1 ms, with with a 5-sigma threshold for detection is used to prevent false issues from being reported), which for some observatories sets the precision with which these values are written.
- Returns:
bool – True if check passes
- Raises:
ValueError – if parameter shapes or types are wrong or do not have acceptable values (if run_check_acceptability is True)
- copy(*, metadata_only=False)[source]
Make and return a copy of the 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, Njones) 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, Njones) 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, Njones) or (Nfreqs, Ntimes) if jpol is not None or if squeeze_pol is True and Njones = 1.
- get_time_array()[source]
Get a time array of calibration solution times.
Times are for the center of the integration, shape (Ntimes), units in Julian Date. If a time_range is defined on the object, the times are the mean of the start and stop times for each range. Otherwise return the time_array (which can be None).
- get_lst_array(*, astrometry_library=None)[source]
Get an lst array of calibration solution lsts.
LSTs are for the center of the integration, shape (Ntimes), units in radians. If an lst_range is defined on the object, the lsts are the LST of the mean of the start and stop times for each range. Otherwise return the lst_array (which can be None).
- Parameters:
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.
- reorder_antennas(order='number', *, run_check=True, check_extra=True, run_check_acceptability=True)[source]
Arrange the antenna axis according to desired order.
- Parameters:
order (str or array like of int) – If a string, allowed values are “name” and “number” to sort on the antenna name or number respectively. A ‘-’ can be prepended to signify descending order instead of the default ascending order (e.g. “-number”). An array of integers of length Nants representing indexes along the existing ant_array can also be supplied to sort in any desired order (note these are indices into the ant_array not antenna numbers).
- Returns:
None
- Raises:
ValueError – Raised if order is not an allowed string or is an array that does not contain all the required numbers.
- reorder_freqs(*, spw_order=None, channel_order=None, select_spw=None, run_check=True, check_extra=True, run_check_acceptability=True)[source]
Arrange the frequency axis according to desired order.
- Parameters:
spw_order (str or array_like of int) – A string describing the desired order of spectral windows along the frequecy axis. Allowed strings include number (sort on spectral window number) and freq (sort on median frequency). A ‘-’ can be prepended to signify descending order instead of the default ascending order, e.g., if you have SPW #1 and 2, and wanted them ordered as [2, 1], you would specify -number. Alternatively, one can supply an index array of length Nspws that specifies how to shuffle the spws (this is not the desired final spw order). Default is to apply no sorting of spectral windows.
channel_order (str or array_like of int) – A string describing the desired order of frequency channels within a spectral window. Allowed strings are “freq” and “-freq”, which will sort channels within a spectral window by ascending or descending frequency respectively. Alternatively, one can supply an index array of length Nfreqs that specifies the new order. Default is to apply no sorting of channels within a single spectral window. Note that proving an array_like of ints will cause the values given to spw_order and select_spw to be ignored.
select_spw (int or array_like of int) – An int or array_like of ints which specifies which spectral windows to apply sorting. Note that setting this argument will cause the value given to spw_order to be ignored.
- Returns:
None
- Raises:
ValueError – Raised if select_spw contains values not in spw_array, or if channel_order is not the same length as freq_array.
- reorder_times(order='time', *, run_check=True, check_extra=True, run_check_acceptability=True)[source]
Arrange the time axis according to desired order.
- Parameters:
order (str or array like of int) – If a string, allowed value is “time” or “-time” to sort on the time in ascending or descending order respectively. An array of integers of length Ntimes representing indexes along the existing time_array or time_range can also be supplied to sort in any desired order.
- Returns:
None
- Raises:
ValueError – Raised if order is not an allowed string or is an array that does not contain all the required indices.
- reorder_jones(order='name', *, run_check=True, check_extra=True, run_check_acceptability=True)[source]
Arrange the jones element axis according to desired order.
- Parameters:
order (str or array like of int) – If a string, allowed values are “name” and “number” to sort on the jones element name or number respectively. A ‘-’ can be prepended to signify descending order instead of the default ascending order (e.g. “-number”). An array of integers of length Njones representing indexes along the existing jones_array can also be supplied to sort in any desired order.
- Returns:
None
- Raises:
ValueError – Raised if order is not an allowed string or is an array that does not contain all the required indices.
- convert_to_gain(*, freq_array, channel_width, 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. Required, shape (Nfreqs,).
channel_width (array of float) – Channel widths for each channel, units Hz. Required, shape (Nfreqs,).
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.
- fast_concat(other, axis, *, ignore_name=None, inplace=False, verbose_history=False, run_check=True, check_extra=True, run_check_acceptability=True)[source]
Concatenate two UVCal 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 (UVCal object or list of UVCal objects) – UVCal object or list of UVCal 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: ‘antenna’, ‘time’, ‘freq’, ‘spw’, ‘jones’ (‘freq’ is not allowed for delay or wideband objects and ‘spw’ is only allowed for wideband objects).
ignore_name (bool) – Option to ignore the name of the phase center (cat_name in phase_center_catalog) when combining two UVCal objects. If set to True, phase centers that are the same up to their name will be combined with the name set to the name found in the first UVCal object in the sum. If set to False, phase centers that are the same up to the name will be kept as separate phase centers. Default is False.
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 (if many objects are combined in succession this can lead to very 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.
- select(*, antenna_nums=None, antenna_names=None, frequencies=None, freq_chans=None, spws=None, times=None, time_range=None, lsts=None, lst_range=None, jones=None, phase_center_ids=None, catalog_names=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 or be contained in a time_range on the object.
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.
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.
phase_center_ids (array_like of int, optional) – Phase center IDs to keep on the object (effectively a selection on baseline-times). Cannot be used with catalog_names.
catalog_names (str or array-like of str, optional) – The names of the phase centers (sources) to keep in the object, which should match exactly in spelling and capitalization. Cannot be used with phase_center_ids.
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).
- classmethod initialize_from_uvdata(uvdata, *, gain_convention, cal_style, metadata_only=True, **kwargs)[source]
Initialize this object based on a UVData object.
Internally, this function takes whatever default parameters it can from the UVData object, and then overwrites them with any parameters passed in as kwargs. It then uses
new_uvcal()
to construct the UVCal object.- Parameters:
uvdata (UVData object) – The UVData object to initialize from.
gain_convention (str) – Gain convention. Options are ‘divide’ or ‘multiply’.
cal_style (str) – Calibration style. Options are ‘sky’ or ‘redundant’.
metadata_only (bool) – Option to only initialize the metadata. If False, this method also initializes the data-like arrays to zeros/ones as appropriate (or False for the flag_array) with the appropriate sizes.
- Returns:
UVCal – A new UVCal object with default parameters.
- Other Parameters:
cal_type (str) – Calibration type. Must be ‘gain’ or ‘delay’. Default ‘gain’. Note that in contrast to
new_uvcal()
, this function sets the default to ‘gain’, instead of trying to set it based on the input freq_range.jones_array (array_like of int or str, optional) – Array of Jones polarizations. Taken from UVData object is possible (i.e. it is single-polarization data), otherwise must be specified. May be specified as ‘circular’ or ‘linear’ to indicate all circular or all linear polarizations.
wide_band (bool) – Whether the calibration is wide-band (i.e. one calibration parameter per spectral window instead of per channel). Automatically set to True if cal_type is ‘delay’, otherwise the default is False. Note that if wide_band is True, the freq_range parameter is required.
include_uvdata_history (bool) – Whether to include the UVData object’s history in the UVCal object’s history. Default is True.
spw_array (array_like of int, optional) – Array of spectral window numbers. This will be taken from the UVData object if at all possible. The only time it is useful to pass this in explicitly is if
wide_band=True
and the spectral windows desired are not just(0, ..., Nspw-1)
.time_array (ndarray of float) – Array of times of the center of the integrations, in Julian Date. Only one of time_array or time_range should be supplied.
time_range (ndarray of float) – Array of start and stop times for calibrations solutions, in Julian Date. A two-dimensional array with shape (Ntimes, 2) where the second axis gives the start time and stop time (in that order). Only one of time_array or time_range should be supplied.
freq_array (ndarray of float, optional) – Array of frequencies in Hz. If given, the freq_range parameter is ignored, and the cal type is assumed to be “gain”.
freq_range (ndarray of float, optional) – Frequency ranges in Hz. Must be given if
freq_array
is not given. If given, the calibration is assumed to be wide band. The array shape should be (Nspws, 2)integration_time (float or ndarray of float, optional) – Integration time in seconds. If not provided, it will be derived from the time_array or time_range. If derived from the time_array, it will be the difference between successive times (with the last time-diff appended), if the number of unique times is one, then a warning will be raised and the integration time set to 1 second. If derived from the time_range it will be the difference between the start and stop times for each range. If a float is provided, it will be used for all integrations. If an ndarray is provided, it must have the same shape as time_array or the first axis of time_range.
channel_width (float or ndarray of float, optional) – Channel width in Hz. If not provided, it will be derived from the freq_array, as the difference between successive frequencies (with the last frequency-diff appended). If a float is provided, it will be used for all channels. If not provided and freq_array is length-one, the channel_width will be set to 1 Hz (and a warning issued). If an ndarray is provided, it must have the same shape as freq_array.
telescope (pyuvdata.Telescope) – Telescope object containing the telescope-related metadata including telescope name and location, x_orientation and antenna names, numbers and positions.
telescope_location (EarthLocation or MoonLocation object) – Deprecated. Telescope location as an astropy EarthLocation object or MoonLocation object. Not required or used if a Telescope object is passed to telescope.
telescope_name (str) – Deprecated. Telescope name. Not required or used if a Telescope object is passed to telescope.
x_orientation (str) – Deprecated. Orientation of the x-axis. Options are ‘east’, ‘north’, ‘e’, ‘n’, ‘ew’, ‘ns’. Not required or used if a Telescope object is passed to telescope.
antenna_positions (ndarray of float or dict of ndarray of float) – Deprecated. Array of antenna positions in ECEF coordinates in meters. If a dict, keys can either be antenna numbers or antenna names, and values are position arrays. Keys are interpreted as antenna numbers if they are integers, otherwise they are interpreted as antenna names if strings. You cannot provide a mix of different types of keys. Not required or used if a Telescope object is passed to telescope.
antenna_names (list of str, optional) – Deprecated. List of antenna names. Not required or used if a Telescope object is passed to telescope or if antenna_positions is a dict with string keys. Otherwise, if not provided, antenna numbers will be used to form the antenna_names, according to the antname_format
antenna_numbers (list of int, optional) – Deprecated. List of antenna numbers. Not required or used if a Telescope object is passed to telescope or if antenna_positions is a dict with integer keys. Otherwise, if not provided, antenna names will be used to form the antenna_numbers, but in this case the antenna_names must be strings that can be converted to integers.
antname_format (str, optional) – Deprecated. Format string for antenna names. Default is ‘{0:03d}’.
ant_array (ndarray of int, optional) – Array of antenna numbers actually found in data (in the order of the data in gain_array etc.)
flex_spw_id_array (ndarray of int, optional) – Array of spectral window IDs. If not provided, it will be set to an array of zeros and only one spw will be used.
ref_antenna_name (str, optional) – Name of reference antenna. Only required for sky calibrations.
sky_catalog (str, optional) – Name of sky catalog. Only required for sky calibrations.
empty (bool, optional) – If True, create an empty UVCal object, i.e. add initialized data arrays (eg. gain_array). By default, this function creates a metadata-only object. You can pass in data arrays directly to the constructor if you want to create a fully-populated object.
data (dict of array_like, optional) – Dictionary containing optional data arrays. Possible keys are: ‘gain_array’, ‘delay_array’, ‘quality_array’, ‘flag_array’, and ‘total_quality_array’. If any entry is provided, the output will contain all necessary data-like arrays. Any key not provided in this case will be set to default “empty” values (e.g. all ones for gains, all False for flags) if they are required or None if they are not required (i.e. total_quality_array).
history (str, optional) – History string to be added to the object. Default is a simple string containing the date and time and pyuvdata version.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.
**kwargs – All other keyword arguments are added to the object as attributes.
- read_calfits(filename, **kwargs)[source]
Read in data from calfits file(s).
- Parameters:
filename (str) – The calfits file 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.
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 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.
use_future_array_shapes (bool) – Defunct option, will result in an error in version 3.2.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.
- read_calh5(filename, **kwargs)[source]
Read in data from calh5 file(s).
- Parameters:
filename (string, path, FastCalH5Meta, h5py.File) – The CalH5 file to read from. A file name or path or a FastCalH5Meta or h5py File object. Must contains a “/Header” group for CalH5 files conforming to spec.
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). 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). This cannot be provided if antenna_nums is also provided. 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.
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 include when reading data into 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.
jones (array_like of int, optional) – The jones 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.
phase_center_ids (array_like of int, optional) – Phase center IDs to keep on the object (effectively a selection on baseline-times). Cannot be used with catalog_names.
catalog_names (str or array-like of str, optional) – The names of the phase centers (sources) to keep in the object, which should match exactly in spelling and capitalization. Cannot be used with phase_center_ids.
read_data (bool) – Read in the data-like arrays (gains/delays, flags, qualities). If set to False, only the metadata will be read in. Setting read_data to False results in a metadata only object.
background_lsts (bool) – When set to True, the lst_array is calculated in a background thread.
run_check (bool) – Option to check for the existence and proper shapes of parameters after after reading in the file (the default is True, meaning the check will be run). Ignored if read_data is False.
check_extra (bool) – Option to check optional parameters as well as required ones (the default is True, meaning the optional parameters will be checked). Ignored if read_data is False.
run_check_acceptability (bool) – Option to check acceptable range of the values of parameters after reading in the file (the default is True, meaning the acceptable range check will be done). Ignored if read_data is False.
use_future_array_shapes (bool) – Option to convert to the future planned array shapes before the changes go into effect by removing the spectral window axis.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.
- Returns:
None
- Raises:
IOError – If filename doesn’t exist.
ValueError – If incompatible select keywords are set (e.g. times and time_range) or select keywords exclude all data or if keywords are set to the wrong type.
- read_fhd_cal(cal_file, *, obs_file, layout_file=None, settings_file=None, **kwargs)[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. If read_data is False, a settings file must be provided.
background_lsts (bool) – When set to True, the lst_array is calculated in a background thread.
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.
use_future_array_shapes (bool) – Defunct option, will result in an error in version 3.2.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.
- read_ms_cal(filename, **kwargs)[source]
Read in data from an MS calibration table.
- Parameters:
filename (str) – The measurement set to read from.
run_check (bool) – Option to check for the existence and proper shapes of parameters after reading in the file.
default_x_orientation (str) – By default, if not found on read, the x_orientation parameter will be set to “east” and a warning will be raised. However, if a value for default_x_orientation is provided, it will be used instead and the warning will be suppressed.
default_jones_array (ndarray of int) – By default, if not found on read, the jones_array parameter will be set to [0, 0] (unknown pol type) and a warning will be raised. However, if a value for default_jones_array is provided, it will be used instead and the warning will be suppressed.
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.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.
- read(filename, *, axis=None, file_type=None, read_data=True, background_lsts=True, use_future_array_shapes=None, astrometry_library=None, antenna_nums=None, antenna_names=None, frequencies=None, freq_chans=None, spws=None, times=None, time_range=None, lsts=None, lst_range=None, jones=None, phase_center_ids=None, catalog_names=None, run_check=True, check_extra=True, run_check_acceptability=True, obs_file=None, layout_file=None, settings_file=None, raw=True, extra_history=None)[source]
Read a generic file into a UVCal object.
This method supports a number of different types of files. Universal parameters (required and optional) are listed directly below, followed by parameters used by all file types related to selecting and checking. Each file type also has its own set of optional parameters that are listed at the end of this docstring.
- Parameters:
filename (str or array_like of str) – The file(s) or list(s) (or array(s)) of files to read from.
file_type (str) – One of [‘calfits’, ‘fhd’] or None. If None, the code attempts to guess what the file type is based on file extensions (FHD: .sav, .txt; uvfits: .calfits). 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: ‘antenna’, ‘time’, ‘freq’, ‘spw’, ‘jones’ (‘freq’ is not allowed for delay or wideband objects and ‘spw’ is only allowed for wideband objects). Only used if multiple files are passed.
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.
background_lsts (bool) – When set to True, the lst_array is calculated in a background thread.
use_future_array_shapes (bool) – Defunct option, will result in an error in version 3.2.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.
- Selecting:
antenna_nums (array_like of int, optional) – The antennas numbers to include when reading data into the object (antenna positions and names for the removed antennas will be retained). 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). This cannot be provided if antenna_nums is also provided. 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.
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 include when reading data into 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.
jones (array_like of int, optional) – The jones 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.
phase_center_ids (array_like of int, optional) – Phase center IDs to keep on the object (effectively a selection on baseline-times). Cannot be used with catalog_names.
catalog_names (str or array-like of str, optional) – The names of the phase centers (sources) to keep in the object, which should match exactly in spelling and capitalization. Cannot be used with phase_center_ids.
- Checking:
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.
- FHD:
obs_file (str or list of str) – The obs.sav file or list of files to read from. This is required for FHD files.
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).
- classmethod from_file(filename, **kwargs)[source]
Initialize a new UVCal object by reading the input file.
This method supports a number of different types of files. Universal parameters (required and optional) are listed directly below, followed by parameters used by all file types related to selecting and checking. Each file type also has its own set of optional parameters that are listed at the end of this docstring.
- Parameters:
filename (str or array_like of str) – The file(s) or list(s) (or array(s)) of files to read from.
file_type (str) – One of [‘calfits’, ‘fhd’] or None. If None, the code attempts to guess what the file type is based on file extensions (FHD: .sav, .txt; uvfits: .calfits). 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: ‘antenna’, ‘time’, ‘freq’, ‘spw’, ‘jones’ (‘freq’ is not allowed for delay or wideband objects and ‘spw’ is only allowed for wideband objects). Only used if multiple files are passed.
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.
background_lsts (bool) – When set to True, the lst_array is calculated in a background thread.
use_future_array_shapes (bool) – Defunct option, will result in an error in version 3.2.
astrometry_library (str) – Library used for calculating LSTs. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location frame is MCMF (on the moon), in which case the default is astropy.
- Selecting:
antenna_nums (array_like of int, optional) – The antennas numbers to include when reading data into the object (antenna positions and names for the removed antennas will be retained). 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). This cannot be provided if antenna_nums is also provided. 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.
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 include when reading data into 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.
jones (array_like of int, optional) – The jones 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.
phase_center_ids (array_like of int, optional) – Phase center IDs to keep on the object (effectively a selection on baseline-times). Cannot be used with catalog_names.
catalog_names (str or array-like of str, optional) – The names of the phase centers (sources) to keep in the object, which should match exactly in spelling and capitalization. Cannot be used with phase_center_ids.
- Checking:
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.
- FHD:
obs_file (str or list of str) – The obs.sav file or list of files to read from. This is required for FHD files.
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).
- 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.
- write_calh5(filename, **kwargs)[source]
Write the data to a calh5 file.
Write an in-memory UVCal object to a CalH5 file.
- Parameters:
filename (str) – The CalH5 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 gain_array or delay. Default is None (no filter/compression). In addition to the normal HDF5 filter values, the user may specify “bitshuffle” which will set the compression to 32008 for bitshuffle and will set the compression_opts to (0, 2) to allow bitshuffle to automatically determine the block size and to use the LZF filter after bitshuffle. Using bitshuffle requires having the hdf5plugin package installed. Dataset must be chunked to use compression.
flags_compression (str) – HDF5 filter to apply when writing the flags_array. Default is the LZF filter. Dataset must be chunked.
quality_compression (str) – HDF5 filter to apply when writing the quality_array and/or total_quality_array if they are defined. Default is the LZF filter. Dataset must be chunked.
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.
- Returns:
None
- Raises:
IOError – If the file located at filename already exists and clobber=False, an IOError is raised.
Notes
The HDF5 library allows for the application of “filters” when writing data, which can provide moderate to significant levels of compression for the datasets in question. Testing has shown that for some typical cases of UVData objects (empty/sparse flag_array objects, and/or uniform nsample_arrays), the built-in LZF filter provides significant compression for minimal computational overhead.
last updated: 2025-02-05