# Utility Functions¶

Commonly used utility functions.

`utils.``LatLonAlt_from_XYZ`(xyz, check_acceptability=True)[source]

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.

• 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

`utils.``XYZ_from_LatLonAlt`(latitude, longitude, altitude)[source]

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

Returns

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

`utils.``rotECEF_from_ECEF`(xyz, longitude)[source]

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

`utils.``ECEF_from_rotECEF`(xyz, longitude)[source]

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

`utils.``ENU_from_ECEF`(xyz, latitude, longitude, altitude)[source]

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.

Returns

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

`utils.``ECEF_from_ENU`(enu, latitude, longitude, altitude)[source]

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.

Returns

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

`utils.``phase_uvw`(ra, dec, initial_uvw)[source]

Calculate phased uvws/positions from unphased ones in an icrs or gcrs frame.

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.

Note that this code is nearly identical to ENU_from_ECEF, except that it uses an arbitrary phasing center rather than a coordinate center.

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.

`utils.``unphase_uvw`(ra, dec, uvw)[source]

Calculate unphased uvws/positions from phased ones 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).

`utils.``uvcalibrate`(uvdata, uvcal, inplace=True, prop_flags=True, flag_missing=True, Dterm_cal=False, delay_convention='minus', undo=False)[source]

Calibrate a UVData object with a UVCal object.

Parameters
• uvdata (UVData object)

• uvcal (UVCal object)

• inplace (bool, optional) – if True edit uvdata in place, else deepcopy

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

• flag_missing (bool, optional) – if True, flag baselines in uvdata if a participating antenna or polarization is missing in uvcal.

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

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

Returns

UVData, optional – Returns if not inplace

`utils.``apply_uvflag`(uvd, uvf, inplace=True, unflag_first=False, flag_missing=True, force_pol=True)[source]

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

`utils.``get_lst_for_time`(jd_array, latitude, longitude, altitude)[source]

Get the lsts for a set of jd times at an earth location.

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.

Returns

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

`utils.``polstr2num`(pol, x_orientation=None)[source]

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.

`utils.``polnum2str`(num, x_orientation=None)[source]

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.

`utils.``jstr2num`(jstr, x_orientation=None)[source]

Convert jones polarization str to number according to calfits memo.

Parameters
• jstr (str) – antenna (jones) 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 – antenna (jones) polarization number corresponding to string

Raises

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

Warns

UserWarning – If the x_orientation not recognized.

`utils.``jnum2str`(jnum, x_orientation=None)[source]

Convert jones polarization number to str according to calfits memo.

Parameters
• num (int) – antenna (jones) 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 – antenna (jones) polarization string 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.

`utils.``parse_polstr`(polstr, x_orientation=None)[source]

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.

`utils.``parse_jpolstr`(jpolstr, x_orientation=None)[source]

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.

`utils.``conj_pol`(pol)[source]

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)

`utils.``reorder_conj_pols`(pols)[source]

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.

`utils.``baseline_to_antnums`(baseline, Nants_telescope)[source]

Get the antenna numbers corresponding to a given baseline number.

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

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

`utils.``antnums_to_baseline`(ant1, ant2, Nants_telescope, attempt256=False)[source]

Get the baseline number corresponding to two given antenna numbers.

Parameters
• ant1 (int or array_like of int) – first antenna number

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

• Nant_telescope (int) – number of antennas

• attempt256 (bool) – Option to try to use the older 256 standard used in many uvfits files (will use 2048 standard if there are more than 256 antennas). Default is False.

Returns

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

`utils.``baseline_index_flip`(baseline, Nants_telescope)[source]

Change baseline number to reverse antenna order.

`utils.``get_baseline_redundancies`(baselines, baseline_vecs, tol=1.0, with_conjugates=False)[source]

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 shape (Nbls, 3)

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

• with_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 with_conjugates is True

`utils.``get_antenna_redundancies`(antenna_numbers, antenna_positions, tol=1.0, include_autos=False)[source]

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.

`utils.``collapse`(arr, alg, weights=None, axis=None, return_weights=False)[source]

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

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

`utils.``mean_collapse`(arr, weights=None, axis=None, return_weights=False)[source]

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.

`utils.``absmean_collapse`(arr, weights=None, axis=None, return_weights=False)[source]

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.

`utils.``quadmean_collapse`(arr, weights=None, axis=None, return_weights=False)[source]

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.

`utils.``or_collapse`(arr, weights=None, axis=None, return_weights=False)[source]

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

`utils.``and_collapse`(arr, weights=None, axis=None, return_weights=False)[source]

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