Utility Functions

Commonly used utility functions.

pyuvdata.utils.LatLonAlt_from_XYZ(xyz, frame='ITRS', check_acceptability=True)

Calculate lat/lon/alt from ECEF x,y,z.

Parameters

• xyz (ndarray of float) – numpy array, shape (Npts, 3), with ECEF x,y,z coordinates.

• frame (str) – Coordinate frame of xyz. Valid options are ITRS (default) or MCMF.

• check_acceptability (bool) – Flag to check XYZ coordinates are reasonable.

Returns

• latitude (ndarray or float) – latitude, numpy array (if Npts > 1) or value (if Npts = 1) in radians

• longitude (ndarray or float) – longitude, numpy array (if Npts > 1) or value (if Npts = 1) in radians

• altitude (ndarray or float) – altitude, numpy array (if Npts > 1) or value (if Npts = 1) in meters

pyuvdata.utils.XYZ_from_LatLonAlt(latitude, longitude, altitude, frame='ITRS')

Calculate ECEF x,y,z from lat/lon/alt values.

Parameters

• latitude (ndarray or float) – latitude, numpy array (if Npts > 1) or value (if Npts = 1) in radians

• longitude (ndarray or float) – longitude, numpy array (if Npts > 1) or value (if Npts = 1) in radians

• altitude (ndarray or float) – altitude, numpy array (if Npts > 1) or value (if Npts = 1) in meters

• frame (str) – Coordinate frame of xyz. Valid options are ITRS (default) or MCMF.

Returns

xyz (ndarray of float) – numpy array, shape (Npts, 3), with ECEF x,y,z coordinates.

pyuvdata.utils.rotECEF_from_ECEF(xyz, longitude)

Get rotated ECEF positions such that the x-axis goes through the longitude.

Miriad and uvfits expect antenna positions in this frame (with longitude of the array center/telescope location)

Parameters

• xyz (ndarray of float) – numpy array, shape (Npts, 3), with ECEF x,y,z coordinates.

• longitude (float) – longitude in radians to rotate coordinates to (usually the array center/telescope location).

Returns

ndarray of float – Rotated ECEF coordinates, shape (Npts, 3).

pyuvdata.utils.ECEF_from_rotECEF(xyz, longitude)

Calculate ECEF from a rotated ECEF (Inverse of rotECEF_from_ECEF).

Parameters

• xyz (ndarray of float) – numpy array, shape (Npts, 3), with rotated ECEF x,y,z coordinates.

• longitude (float) – longitude in radians giving the x direction of the rotated coordinates (usually the array center/telescope location).

Returns

ndarray of float – ECEF coordinates, shape (Npts, 3).

pyuvdata.utils.ENU_from_ECEF(xyz, latitude, longitude, altitude, frame='ITRS')

Calculate local ENU (east, north, up) coordinates from ECEF coordinates.

Parameters

• xyz (ndarray of float) – numpy array, shape (Npts, 3), with ECEF x,y,z coordinates.

• latitude (float) – Latitude of center of ENU coordinates in radians.

• longitude (float) – Longitude of center of ENU coordinates in radians.

• altitude (float) – Altitude of center of ENU coordinates in radians.

• frame (str) – Coordinate frame of xyz. Valid options are ITRS (default) or MCMF.

Returns

ndarray of float – numpy array, shape (Npts, 3), with local ENU coordinates

pyuvdata.utils.ECEF_from_ENU(enu, latitude, longitude, altitude, frame='ITRS')

Calculate ECEF coordinates from local ENU (east, north, up) coordinates.

Parameters

• enu (ndarray of float) – numpy array, shape (Npts, 3), with local ENU coordinates.

• latitude (float) – Latitude of center of ENU coordinates in radians.

• longitude (float) – Longitude of center of ENU coordinates in radians.

• altitude (float) – Altitude of center of ENU coordinates in radians.

• frame (str) – Coordinate frame of xyz. Valid options are ITRS (default) or MCMF.

Returns

xyz (ndarray of float) – numpy array, shape (Npts, 3), with ECEF x,y,z coordinates.

pyuvdata.utils.undo_old_uvw_calc(ra, dec, uvw)

Undo the old phasing calculation on uvws in an icrs or gcrs frame.

This code expects phased uvws or positions in the same frame that ra/dec are in (e.g. icrs or gcrs) and returns unphased ones in the same frame.

Parameters

• ra (float) – Right ascension of phase center.

• dec (float) – Declination of phase center.

• uvw (ndarray of float) – Phased uvws or positions relative to the array center, shape (Nlocs, 3).

Returns

unphased_uvws (ndarray of float) – Unphased uvws or positions relative to the array center, shape (Nlocs, 3).

pyuvdata.utils.old_uvw_calc(ra, dec, initial_uvw)

Calculate old uvws from unphased ones in an icrs or gcrs frame.

This method should not be used and is only retained for testing the undo_old_uvw_calc method, which is needed for fixing phases.

This code expects input uvws or positions relative to the telescope location in the same frame that ra/dec are in (e.g. icrs or gcrs) and returns phased ones in the same frame.

Parameters

• ra (float) – Right ascension of phase center.

• dec (float) – Declination of phase center.

• initial_uvw (ndarray of float) – Unphased uvws or positions relative to the array center, shape (Nlocs, 3).

Returns

uvw (ndarray of float) – uvw array in the same frame as initial_uvws, ra and dec.

pyuvdata.utils.uvcalibrate(uvdata, uvcal, inplace=True, prop_flags=True, Dterm_cal=False, flip_gain_conj=False, delay_convention='minus', undo=False, time_check=True, ant_check=True)

Calibrate a UVData object with a UVCal object.

Parameters

• uvdata (UVData object) – UVData object to calibrate.

• uvcal (UVCal object) – UVCal object containing the calibration.

• inplace (bool, optional) – if True edit uvdata in place, else return a calibrated copy

• prop_flags (bool, optional) – if True, propagate calibration flags to data flags and doesn’t use flagged gains. Otherwise, uses flagged gains and does not propagate calibration flags to data flags.

• Dterm_cal (bool, optional) – Calibrate the off-diagonal terms in the Jones matrix if present in uvcal. Default is False. Currently not implemented.

• flip_gain_conj (bool, optional) – This function uses the UVData ant_1_array and ant_2_array to specify the antennas in the UVCal object. By default, the conjugation convention, which follows the UVData convention (i.e. ant2 - ant1), is that the applied gain = ant1_gain * conjugate(ant2_gain). If the other convention is required, set flip_gain_conj=True.

• delay_convention (str, optional) – Exponent sign to use in conversion of ‘delay’ to ‘gain’ cal_type if the input uvcal is not inherently ‘gain’ cal_type. Default to ‘minus’.

• undo (bool, optional) – If True, undo the provided calibration. i.e. apply the calibration with flipped gain_convention. Flag propagation rules apply the same.

• time_check (bool) – Option to check that times match between the UVCal and UVData objects if UVCal has a single time or time range. Times are always checked if UVCal has multiple times.

• ant_check (bool) – Option to check that all antennas with data on the UVData object have calibration solutions in the UVCal object. If this option is set to False, uvcalibrate will proceed without erroring and data for antennas without calibrations will be flagged.

Returns

UVData, optional – Returns if not inplace

pyuvdata.utils.apply_uvflag(uvd, uvf, inplace=True, unflag_first=False, flag_missing=True, force_pol=True)

Apply flags from a UVFlag to a UVData instantiation.

Note that if uvf.Nfreqs or uvf.Ntimes is 1, it will broadcast flags across that axis.

Parameters

• uvd (UVData object) – UVData object to add flags to.

• uvf (UVFlag object) – A UVFlag object in flag mode.

• inplace (bool) – If True overwrite flags in uvd, otherwise return new object

• unflag_first (bool) – If True, completely unflag the UVData before applying flags. Else, OR the inherent uvd flags with uvf flags.

• flag_missing (bool) – If input uvf is a baseline type and antpairs in uvd do not exist in uvf, flag them in uvd. Otherwise leave them untouched.

• force_pol (bool) – If True, broadcast flags to all polarizations if they do not match. Only works if uvf.Npols == 1.

Returns

UVData – If not inplace, returns new UVData object with flags applied

pyuvdata.utils.get_lst_for_time(jd_array, latitude, longitude, altitude, astrometry_library=None, frame='itrs')

Get the local apparent sidereal time for a set of jd times at an earth location.

This function calculates the local apparent sidereal time (LAST), given a UTC time and a position on the Earth, using either the astropy or NOVAS libraries. It is important to note that there is an apporoximate 20 microsecond difference between the two methods, presumably due to small differences in the apparent reference frame. These differences will cancel out when calculating coordinates in the TOPO frame, so long as apparent coordinates are calculated using the same library (i.e., astropy or NOVAS). Failing to do so can introduce errors up to ~1 mas in the horizontal coordinate system (i.e., AltAz).

Parameters

• jd_array (ndarray of float) – JD times to get lsts for.

• latitude (float) – Latitude of location to get lst for in degrees.

• longitude (float) – Longitude of location to get lst for in degrees.

• altitude (float) – Altitude of location to get lst for in meters.

• astrometry_library (str) – Library used for running the LST calculations. Allowed options are ‘erfa’ (which uses the pyERFA), ‘novas’ (which uses the python-novas library), and ‘astropy’ (which uses the astropy utilities). Default is erfa unless the telescope_location is a MoonLocation object, in which case the default is astropy.

• frame (str) – Reference frame for latitude/longitude/altitude. Options are itrs (default) or mcmf.

Returns

ndarray of float – LASTs in radians corresponding to the jd_array.

pyuvdata.utils.polstr2num(pol: Union[str, Iterable[str]], x_orientation: Optional[str] = None)

Convert polarization str to number according to AIPS Memo 117.

Prefer ‘pI’, ‘pQ’, ‘pU’ and ‘pV’ to make it clear that these are pseudo-Stokes, not true Stokes, but also supports ‘I’, ‘Q’, ‘U’, ‘V’.

Parameters

• pol (str) – polarization string

• x_orientation (str, optional) – Orientation of the physical dipole corresponding to what is labelled as the x polarization (“east” or “north”) to allow for converting from E/N strings. See corresonding parameter on UVData for more details.

Returns

int – Number corresponding to string

Raises

ValueError – If the pol string cannot be converted to a polarization number.

Warns

UserWarning – If the x_orientation not recognized.

pyuvdata.utils.polnum2str(num, x_orientation=None)

Convert polarization number to str according to AIPS Memo 117.

Uses ‘pI’, ‘pQ’, ‘pU’ and ‘pV’ to make it clear that these are pseudo-Stokes, not true Stokes

Parameters

• num (int) – polarization number

• x_orientation (str, optional) – Orientation of the physical dipole corresponding to what is labelled as the x polarization (“east” or “north”) to convert to E/N strings. See corresonding parameter on UVData for more details.

Returns

str – String corresponding to polarization number

Raises

ValueError – If the polarization number cannot be converted to a polarization string.

Warns

UserWarning – If the x_orientation not recognized.

pyuvdata.utils.jstr2num(jstr, x_orientation=None)

Convert jones polarization str to number according to calfits memo.

Parameters

• jstr (str or array_like of str) – antenna (jones) polarization string(s) to convert.

• x_orientation (str, optional) – Orientation of the physical dipole corresponding to what is labelled as the x polarization (“east” or “north”) to allow for converting from E/N strings. See corresonding parameter on UVData for more details.

Returns

int or list of int – antenna (jones) polarization number(s) corresponding to the input string(s)

Raises

ValueError – If the jones string cannot be converted to a polarization number.

Warns

UserWarning – If the x_orientation not recognized.

pyuvdata.utils.jnum2str(jnum, x_orientation=None)

Convert jones polarization number to str according to calfits memo.

Parameters

• num (int or array_like of int) – antenna (jones) polarization number(s) to convert to strings

• x_orientation (str, optional) – Orientation of the physical dipole corresponding to what is labelled as the x polarization (“east” or “north”) to convert to E/N strings. See corresonding parameter on UVData for more details.

Returns

str or list of str – antenna (jones) polarization string(s) corresponding to number

Raises

ValueError – If the jones polarization number cannot be converted to a jones polarization string.

Warns

UserWarning – If the x_orientation not recognized.

pyuvdata.utils.parse_polstr(polstr, x_orientation=None)

Parse a polarization string and return pyuvdata standard polarization string.

See utils.POL_STR2NUM_DICT for options.

Parameters

• polstr (str) – polarization string

• x_orientation (str, optional) – Orientation of the physical dipole corresponding to what is labelled as the x polarization (“east” or “north”) to allow for converting from E/N strings. See corresonding parameter on UVData for more details.

Returns

str – AIPS Memo 117 standard string

Raises

ValueError – If the pol string cannot be converted to a polarization number.

Warns

UserWarning – If the x_orientation not recognized.

pyuvdata.utils.parse_jpolstr(jpolstr, x_orientation=None)

Parse a Jones polarization string and return pyuvdata standard jones string.

See utils.JONES_STR2NUM_DICT for options.

Parameters

jpolstr (str) – Jones polarization string

Returns

str – calfits memo standard string

Raises

ValueError – If the jones string cannot be converted to a polarization number.

Warns

UserWarning – If the x_orientation not recognized.

pyuvdata.utils.conj_pol(pol)

Return the polarization for the conjugate baseline.

For example, (1, 2, ‘xy’) = conj(2, 1, ‘yx’). The returned polarization is determined by assuming the antenna pair is reversed in the data, and finding the correct polarization correlation which will yield the requested baseline when conjugated. Note this means changing the polarization for linear cross-pols, but keeping auto-pol (e.g. xx) and Stokes the same.

Parameters

pol (str or int) – Polarization string or integer.

Returns

cpol (str or int) – Polarization as if antennas are swapped (type matches input)

pyuvdata.utils.reorder_conj_pols(pols)

Reorder multiple pols, swapping pols that are conjugates of one another.

For example (‘xx’, ‘xy’, ‘yx’, ‘yy’) -> (‘xx’, ‘yx’, ‘xy’, ‘yy’) This is useful for the _key2inds function in the case where an antenna pair is specified but the conjugate pair exists in the data. The conjugated data should be returned in the order of the polarization axis, so after conjugating the data, the pols need to be reordered. For example, if a file contains antpair (0, 1) and pols ‘xy’ and ‘yx’, but the user requests antpair (1, 0), they should get: [(1x, 0y), (1y, 0x)] = [conj(0y, 1x), conj(0x, 1y)]

Parameters

pols (array_like of str or int) – Polarization array (strings or ints).

Returns

conj_order (ndarray of int) – Indices to reorder polarization array.

pyuvdata.utils.baseline_to_antnums(baseline, Nants_telescope)

Get the antenna numbers corresponding to a given baseline number.

Parameters

• baseline (int or array_like of ints) – baseline number

• Nants_telescope (int) – number of antennas

Returns

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

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

pyuvdata.utils.antnums_to_baseline(ant1, ant2, Nants_telescope, attempt256=False)

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

• Nants_telescope (int) – number of antennas

• attempt256 (bool) – Option to try to use the older 256 standard used in many uvfits files. If there are antenna numbers >= 256, the 2048 standard will be used unless there are antenna numbers >= 2048 or Nants_telescope > 2048. In that case, the 2147483648 standard will be used. Default is False.

Returns

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

pyuvdata.utils.baseline_index_flip(baseline, Nants_telescope)

Change baseline number to reverse antenna order.

pyuvdata.utils.get_baseline_redundancies(baselines, baseline_vecs, tol=1.0, include_conjugates=False)

Find redundant baseline groups.

Parameters

• baselines (array_like of int) – Baseline numbers, shape (Nbls,)

• baseline_vecs (array_like of float) – Baseline vectors in meters, shape (Nbls, 3)

• tol (float) – Absolute tolerance of redundancy, in meters.

• include_conjugates (bool) – Option to include baselines that are redundant when flipped.

Returns

• baseline_groups (list of lists of int) – list of lists of redundant baseline numbers

• vec_bin_centers (list of array_like of float) – List of vectors describing redundant group centers

• lengths (list of float) – List of redundant group baseline lengths in meters

• baseline_ind_conj (list of int) – List of baselines that are redundant when reversed. Only returned if include_conjugates is True

pyuvdata.utils.get_antenna_redundancies(antenna_numbers, antenna_positions, tol=1.0, include_autos=False)

Find redundant baseline groups based on antenna positions.

Parameters

• antenna_numbers (array_like of int) – Antenna numbers, shape (Nants,).

• antenna_positions (array_like of float) – Antenna position vectors in the ENU (topocentric) frame in meters, shape (Nants, 3).

• tol (float) – Redundancy tolerance in meters.

• include_autos (bool) – Option to include autocorrelations.

Returns

• baseline_groups (list of lists of int) – list of lists of redundant baseline numbers

• vec_bin_centers (list of array_like of float) – List of vectors describing redundant group centers

• lengths (list of float) – List of redundant group baseline lengths in meters

Notes

The baseline numbers refer to antenna pairs (a1, a2) such that the baseline vector formed from ENU antenna positions, blvec = enu[a1] - enu[a2] is close to the other baselines in the group.

This is achieved by putting baselines in a form of the u>0 convention, but with a tolerance in defining the signs of vector components.

To guarantee that the same baseline numbers are present in a UVData object, UVData.conjugate_bls('u>0', uvw_tol=tol), where tol is the tolerance used here.

pyuvdata.utils.collapse(arr, alg, weights=None, axis=None, return_weights=False, return_weights_square=False)

Parent function to collapse an array with a given algorithm.

Parameters

• arr (array) – Input array to process.

• alg (str) – Algorithm to use. Must be defined in this function with corresponding subfunction above.

• weights (ndarray, optional) – weights for collapse operation (e.g. weighted mean). NOTE: Some subfunctions do not use the weights. See corresponding doc strings.

• axis (int or tuple, optional) – Axis or axes to collapse. Default is all.

• return_weights (bool) – Whether to return sum of weights.

• return_weights_square (bool) – Whether to return the sum of the squares of the weights. Default is False.

pyuvdata.utils.mean_collapse(arr, weights=None, axis=None, return_weights=False, return_weights_square=False)

Collapse by averaging data.

This is similar to np.average, except it handles infs (by giving them zero weight) and zero weight axes (by forcing result to be inf with zero output weight).

Parameters

• arr (array) – Input array to process.

• weights (ndarray, optional) – weights for average. If none, will default to equal weight for all non-infinite data.

• axis (int or tuple, optional) – Axis or axes to collapse (passed to np.sum). Default is all.

• return_weights (bool) – Whether to return sum of weights.

• return_weights_square (bool) – Whether to return the sum of the square of the weights. Default is False.

pyuvdata.utils.absmean_collapse(arr, weights=None, axis=None, return_weights=False, return_weights_square=False)

Collapse by averaging absolute value of data.

Parameters

• arr (array) – Input array to process.

• weights (ndarray, optional) – weights for average. If none, will default to equal weight for all non-infinite data.

• axis (int or tuple, optional) – Axis or axes to collapse (passed to np.sum). Default is all.

• return_weights (bool) – Whether to return sum of weights.

• return_weights_square (bool) – whether to return the sum of the squares of the weights. Default is False.

pyuvdata.utils.quadmean_collapse(arr, weights=None, axis=None, return_weights=False, return_weights_square=False)

Collapse by averaging in quadrature.

Parameters

• arr (array) – Input array to process.

• weights (ndarray, optional) – weights for average. If none, will default to equal weight for all non-infinite data.

• axis (int or tuple, optional) – Axis or axes to collapse (passed to np.sum). Default is all.

• return_weights (bool) – Whether to return sum of weights.

• return_weights_square (bool) – whether to return the sum of the squares of the weights. Default is False.

pyuvdata.utils.or_collapse(arr, weights=None, axis=None, return_weights=False, return_weights_square=False)

Collapse using OR operation.

Parameters

• arr (array) – Input array to process.

• weights (ndarray, optional) – NOT USED, but kept for symmetry with other collapsing functions.

• axis (int or tuple, optional) – Axis or axes to collapse (take OR over). Default is all.

• return_weights (bool) – Whether to return dummy weights array. NOTE: the dummy weights will simply be an array of ones

• return_weights_square (bool) – NOT USED, but kept for symmetry with other collapsing functions.

pyuvdata.utils.and_collapse(arr, weights=None, axis=None, return_weights=False, return_weights_square=False)

Collapse using AND operation.

Parameters

• arr (array) – Input array to process.

• weights (ndarray, optional) – NOT USED, but kept for symmetry with other collapsing functions.

• axis (int or tuple, optional) – Axis or axes to collapse (take AND over). Default is all.

• return_weights (bool) – Whether to return dummy weights array. NOTE: the dummy weights will simply be an array of ones

• return_weights_square (bool) – NOT USED, but kept for symmetry with other collapsing functions.