Utility Functions

Commonly used utility functions.

utils.LatLonAlt_from_XYZ(xyz)

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

Parameters

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

Returns

tuple of latitude, longitude, altitude numpy arrays (if Npts > 1) or

values (if Npts = 1) in radians & meters

utils.XYZ_from_LatLonAlt(latitude, longitude, altitude)

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

Parameters

• latitude – latitude in radians, can be a single value or a vector of length Npts

• longitude – longitude in radians, can be a single value or a vector of length Npts

• altitude – altitude in meters, can be a single value or a vector of length Npts

Returns

numpy array, shape (Npts, 3) (if Npts > 1) or (3,) (if Npts = 1), with ECEF x,y,z coordinates

utils.rotECEF_from_ECEF(xyz, longitude)

Calculate a rotated ECEF from ECEF such that the x-axis goes through the specified longitude.

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

Parameters

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

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

Returns

numpy array, shape (Npts, 3), with rotated ECEF coordinates

utils.ECEF_from_rotECEF(xyz, longitude)

Calculate ECEF from a rotated ECEF such that the x-axis goes through the specified longitude. (Inverse of rotECEF_from_ECEF)

Parameters

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

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

Returns

numpy array, shape (Npts, 3), with ECEF coordinates

utils.ENU_from_ECEF(xyz, latitude, longitude, altitude)

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

Parameters

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

• latitude – latitude of center of ENU coordinates in radians

• longitude – longitude of center of ENU coordinates in radians

• altitude – altitude of center of ENU coordinates in radians

Returns

numpy array, shape (Npts, 3), with local ENU coordinates

utils.ECEF_from_ENU(enu, latitude, longitude, altitude)

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

Parameters

• enu – numpy array, shape (Npts, 3), with local ENU coordinates

• latitude – latitude of center of ENU coordinates in radians

• longitude – longitude of center of ENU coordinates in radians

Returns

numpy array, shape (Npts, 3), with ECEF x,y,z coordinates

utils.phase_uvw(ra, dec, xyz)

This code expects xyz locations relative to the telescope location in the same frame that ra/dec are in (e.g. icrs or gcrs) and returns uvws 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 – right ascension to phase to in desired frame

• dec – declination to phase to in desired frame

• xyz – locations relative to the array center in desired frame, shape (Nlocs, 3)

Returns

uvw array in the same frame as xyz, ra and dec

utils.unphase_uvw(ra, dec, uvw)

This code expects uvw locations in the same frame that ra/dec are in (e.g. icrs or gcrs) and returns relative xyz values in the same frame.

Parameters

• ra – right ascension data are phased to

• dec – declination data are phased to

• uvw – phased uvw values

Returns

xyz locations relative to the array center in the phased frame

utils.get_lst_for_time(jd_array, latitude, longitude, altitude)

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

Parameters

• jd_array – an array of JD times to get lst for

• latitude – latitude of location to get lst for in degrees

• longitude – longitude of location to get lst for in degrees

• altitude – altitude of location to get lst for in meters

Returns

an array of lst times corresponding to the jd_array

utils.polstr2num(pol, x_orientation=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.

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.

utils.jstr2num(jstr, x_orientation=None)

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)

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)

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)

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)

Returns 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 – Polarization (str or int)

Returns

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

utils.reorder_conj_pols(pols)

Reorders a list of 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 – Polarization array (strings or ints)

Returns

conj_order – Indices to reorder polarization axis

utils.baseline_to_antnums(baseline, Nants_telescope)

Get the antenna numbers corresponding to a given baseline number.

Parameters

• baseline – integer baseline number

• Nant_telescope – integer number of antennas

Returns

tuple with the two antenna numbers corresponding to the baseline.

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

Get the baseline number corresponding to two given antenna numbers.

Parameters

• ant1 – first antenna number (integer)

• ant2 – second antenna number (integer)

• Nant_telescope – integer number of antennas

• attempt256 – 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

integer baseline number corresponding to the two antenna numbers.

utils.get_baseline_redundancies(baselines, baseline_vecs, tol=1.0, with_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 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)

Find redundant baseline groups based on antenna positions.

Include all possible redundant baselines 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

utils.collapse(arr, alg, weights=None, axis=None, return_weights=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 below.

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

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

• return_weights (Bool) – Whether to return sum of weights. Default is False.

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

Function to average 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 to process

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

• axis - axis keyword to pass to np.sum

• return_weights - whether to return sum of weights. Default is False.

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

Function to average absolute value :Parameters: * arr - array to process

• weights - weights for average

• axis - axis keyword to pass to np.mean

• return_weights - whether to return sum of weights. Default is False.

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

Function to average in quadrature :Parameters: * arr - array to process

• weights - weights for average

• axis - axis keyword to pass to np.mean

• return_weights - whether to return sum of weights. Default is False.

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

Function to collapse axes using OR operation :Parameters: * arr - boolean array to process

• weights - NOT USED, but kept for symmetry with other averaging functions

• axis - axis or axes over which to OR

• return_weights - whether to return dummy weights array. NOTE – the dummy weights will simply be an array of ones. Default is False.

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

Function to collapse axes using AND operation :Parameters: * arr - boolean array to process

• weights - NOT USED, but kept for symmetry with other averaging functions

• axis - axis or axes over which to AND

• return_weights - whether to return dummy weights array. NOTE – the dummy weights will simply be an array of ones. Default is False.