UVBeam Class

UVBeam is the main user class for beam models. It provides import and export functionality to supported file formats and can be interacted with directly.

class pyuvdata.UVBeam[source]

A class for defining a radio telescope antenna beam.

UVParameter objects

(http://pyuvdata.readthedocs.io/en/latest/uvbeam_parameters.html). Some are always required, some are required for certain beam_types, antenna_types and pixel_coordinate_systems and others are always optional.

Type

For full list see UVBeam Parameters

check(check_extra=True, run_check_acceptability=True)[source]

Check that all required parameters are set reasonably.

Check that required parameters exist and have appropriate shapes. Optionally check if the values are acceptable.

Parameters
  • check_extra (bool) – Option to check optional parameters as well as required ones.

  • run_check_acceptability (bool) – Option to check if values in required parameters are acceptable.

peak_normalize()[source]

Convert to peak normalization.

efield_to_power(calc_cross_pols=True, keep_basis_vector=False, run_check=True, check_extra=True, run_check_acceptability=True, inplace=True)[source]

Convert E-field beam to power beam.

Parameters
  • calc_cross_pols (bool) – If True, calculate the crossed polarization beams (e.g. ‘xy’ and ‘yx’), otherwise only calculate the same polarization beams (e.g. ‘xx’ and ‘yy’).

  • keep_basis_vector (bool) – If True, keep the directionality information and just multiply the efields for each basis vector separately (caution: this is not what is standardly meant by the power beam).

  • inplace (bool) – Option to apply conversion directly on self or to return a new UVBeam object.

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

  • run_check_acceptability (bool) – Option to check acceptable range of the values of required parameters after converting to power.

  • check_extra (bool) – Option to check optional parameters as well as required ones.

efield_to_pstokes(inplace=True, run_check=True, check_extra=True, run_check_acceptability=True)[source]

Convert E-field to pseudo-stokes power.

Following https://arxiv.org/pdf/1802.04151.pdf, using the equation:

M_ij = Tr(sigma_i J sigma_j J^*)

where sigma_i and sigma_j are Pauli matrices.

Parameters
  • inplace (bool) – Option to apply conversion directly on self or to return a new UVBeam object.

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

  • run_check_acceptability (bool) – Option to check acceptable range of the values of required parameters after converting to power.

  • check_extra (bool) – Option to check optional parameters as well as required ones.

interp(az_array=None, za_array=None, az_za_grid=False, healpix_nside=None, healpix_inds=None, freq_array=None, freq_interp_tol=1.0, polarizations=None, return_bandpass=False, reuse_spline=False, spline_opts=None, new_object=False, run_check=True, check_extra=True, run_check_acceptability=True)[source]

Interpolate beam to given frequency, az & za locations or Healpix pixel centers.

Parameters
  • az_array (array_like of floats, optional) – Azimuth values to interpolate to in radians, either specifying the azimuth positions for every interpolation point or specifying the azimuth vector for a meshgrid if az_za_grid is True.

  • za_array (array_like of floats, optional) – Zenith values to interpolate to in radians, either specifying the zenith positions for every interpolation point or specifying the zenith vector for a meshgrid if az_za_grid is True.

  • az_za_grid (bool) – Option to treat the az_array and za_array as the input vectors for points on a mesh grid.

  • healpix_nside (int, optional) – HEALPix nside parameter if interpolating to HEALPix pixels.

  • healpix_inds (array_like of int, optional) – HEALPix indices to interpolate to. Defaults to all indices in the map if healpix_nside is set and az_array and za_array are None.

  • freq_array (array_like of floats, optional) – Frequency values to interpolate to.

  • freq_interp_tol (float) – Frequency distance tolerance [Hz] of nearest neighbors. If all elements in freq_array have nearest neighbor distances within the specified tolerance then return the beam at each nearest neighbor, otherwise interpolate the beam.

  • polarizations (list of str) – polarizations to interpolate if beam_type is ‘power’. Default is all polarizations in self.polarization_array.

  • new_object (bool) – Option to return a new UVBeam object with the interpolated data, if possible. Note that this is only possible for Healpix pixels or if az_za_grid is True and az_array and za_array are evenly spaced or for frequency only interpolation.

  • reuse_spline (bool) – Save the interpolation functions for reuse. Only applies for az_za_simple interpolation.

  • spline_opts (dict) – Provide options to numpy.RectBivariateSpline. This includes spline order parameters kx and ky, and smoothing parameter s. Only applies for az_za_simple interpolation.

  • run_check (bool) – Only used if new_object is True. Option to check for the existence and proper shapes of required parameters on the new object.

  • check_extra (bool) – Only used if new_object is True. Option to check optional parameters as well as required ones on the new object.

  • run_check_acceptability (bool) – Only used if new_object is True. Option to check acceptable range of the values of required parameters on the new object.

Returns

  • array_like of float or complex or a UVBeam object – Either an array of interpolated values or a UVBeam object if new_object is True. The shape of the interpolated data will be: (Naxes_vec, Nspws, Nfeeds or Npols, Nfreqs or freq_array.size if freq_array is passed, Npixels/(Naxis1, Naxis2) or az_array.size if az/za_arrays are passed)

  • interp_basis_vector (array_like of float, optional) – an array of interpolated basis vectors (or self.basis_vector_array if az/za_arrays are not passed), shape: (Naxes_vec, Ncomponents_vec, Npixels/(Naxis1, Naxis2) or az_array.size if az/za_arrays are passed)

  • interp_bandpass (array_like of float, optional) – The interpolated bandpass, only returned if return_bandpass is True. shape: (Nspws, freq_array.size)

to_healpix(nside=None, run_check=True, check_extra=True, run_check_acceptability=True, inplace=True)[source]

Convert beam to the healpix coordinate system.

The interpolation is done using the interpolation method specified in self.interpolation_function.

Note that this interpolation isn’t perfect. Interpolating an Efield beam and then converting to power gives a different result than converting to power and then interpolating at about a 5% level.

Parameters
  • nside (int) – The nside to use for the Healpix map. If not specified, use the nside that gives the closest resolution that is higher than the input resolution.

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

  • 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 required parameters after combining objects

  • inplace (bool) – Option to perform the select directly on self or return a new UVBeam object.

get_beam_area(pol='pI')[source]

Compute the integral of the beam in units of steradians.

Pseudo-Stokes ‘pI’ (I), ‘pQ’(Q), ‘pU’(U), ‘pV’(V) beam and linear dipole ‘XX’, ‘XY’, ‘YX’ and ‘YY’ are supported. See Equations 4 and 5 of Moore et al. (2017) ApJ 836, 154 or arxiv:1502.05072 and Kohn et al. (2018) or https://arxiv.org/pdf/1802.04151.pdf for details.

Parameters

pol (str or int) – polarization string or integer, Ex. a pseudo-stokes pol ‘pI’, or a linear pol ‘XX’.

Returns

omega (float) – Integral of the beam across the sky, units: steradians.

get_beam_sq_area(pol='pI')[source]

Compute the integral of the beam^2 in units of steradians.

Pseudo-Stokes ‘pI’ (I), ‘pQ’(Q), ‘pU’(U), ‘pV’(V) beam and linear dipole ‘XX’, ‘XY’, ‘YX’ and ‘YY’ are supported. See Equations 4 and 5 of Moore et al. (2017) ApJ 836, 154 or arxiv:1502.05072 for details.

Parameters

pol (str or int) – polarization string or integer, Ex. a pseudo-stokes pol ‘pI’, or a linear pol ‘XX’.

Returns

omega (float) – Integral of the beam^2 across the sky, units: steradians.

select(axis1_inds=None, axis2_inds=None, pixels=None, frequencies=None, freq_chans=None, feeds=None, polarizations=None, inplace=True, run_check=True, check_extra=True, run_check_acceptability=True)[source]

Downselect data to keep on the object along various axes.

Axes that can be selected along include image axis indices or pixels (if healpix), frequencies and feeds or polarizations (if power).

The history attribute on the object will be updated to identify the operations performed.

Parameters
  • axis1_indss (array_like of int, optional) – The indices along the first image axis to keep in the object. Cannot be set if pixel_coordinate_system is “healpix”.

  • axis2_inds (array_like of int, optional) – The indices along the second image axis to keep in the object. Cannot be set if pixel_coordinate_system is “healpix”.

  • pixels (array_like of int, optional) – The healpix pixels to keep in the object. Cannot be set if pixel_coordinate_system is not “healpix”.

  • frequencies (array_like of float, optional) – The frequencies to keep in the object.

  • freq_chans (array_like of int, optional) – The frequency channel numbers to keep in the object.

  • feeds (array_like of str, optional) – The feeds to keep in the object. If the x_orientation attribute is set, the physical dipole strings (e.g. “n”, “e”) are also supported. Cannot be set if the beam_type is “power”.

  • polarizations (array_like of int or str, optional) – The polarizations to keep in the object. Cannot be set if the beam_type is “efield”. If passing strings, the canonical polarization strings (e.g. “xx”, “rr”) are supported and if the x_orientation attribute is set, the physical dipole strings (e.g. “nn”, “ee”) are also supported.

  • inplace (bool) – Option to perform the select directly on self or return a new UVBeam object, which is a subselection of self.

  • run_check (bool) – Option to check for the existence and proper shapes of required parameters after downselecting data on this object.

  • 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 required parameters after downselecting data on this object.

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

Read in data from a beamfits file.

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

  • run_check (bool) – Option to check for the existence and proper shapes of required parameters after reading in the file.

  • check_extra (bool) – Option to check optional parameters as well as required ones.

  • run_check_acceptabilit (bool) – Option to check acceptable range of the values of required parameters after reading in the file.

read_cst_beam(filename, beam_type='power', feed_pol=None, rotate_pol=None, frequency=None, telescope_name=None, feed_name=None, feed_version=None, model_name=None, model_version=None, history=None, x_orientation=None, reference_impedance=None, extra_keywords=None, frequency_select=None, run_check=True, check_extra=True, run_check_acceptability=True)[source]

Read in data from a cst file.

Parameters
  • filename (str) – Either a settings yaml file or a cst text file or list of cst text files to read from. If a list is passed, the files are combined along the appropriate axes.

    Settings yaml files must include the following keywords:

    - telescope_name (str)
    - feed_name (str)
    - feed_version (str)
    - model_name (str)
    - model_version (str)
    - history (str)
    - frequencies (list(float))
    - cst text filenames (list(str)) – path relative to yaml file
    - feed_pol (str) or (list(str))

    and they may include the following optional keywords:

    - x_orientation (str): Optional but strongly encouraged!
    - ref_imp (float): beam model reference impedance
    - sim_beam_type (str): e.g. ‘E-farfield’
    - all other fields will go into the extra_keywords attribute

    More details and an example are available in the docs (cst_settings_yaml.rst). Specifying any of the associated keywords to this function will override the values in the settings file.

  • beam_type (str) – What beam_type to read in (‘power’ or ‘efield’).

  • feed_pol (str) – The feed or polarization or list of feeds or polarizations the files correspond to. Defaults to ‘x’ (meaning x for efield or xx for power beams).

  • rotate_pol (bool) – If True, assume the structure in the simulation is symmetric under 90 degree rotations about the z-axis (so that the y polarization can be constructed by rotating the x polarization or vice versa). Default: True if feed_pol is a single value or a list with all the same values in it, False if it is a list with varying values.

  • frequency (float or list of float, optional) – The frequency or list of frequencies corresponding to the filename(s). This is assumed to be in the same order as the files. If not passed, the code attempts to parse it from the filenames.

  • telescope_name (str, optional) – The name of the telescope corresponding to the filename(s).

  • feed_name (str, optional) – The name of the feed corresponding to the filename(s).

  • feed_version (str, optional) – The version of the feed corresponding to the filename(s).

  • model_name (str, optional) – The name of the model corresponding to the filename(s).

  • model_version (str, optional) – The version of the model corresponding to the filename(s).

  • history (str, optional) – A string detailing the history of the filename(s).

  • x_orientation (str, optional) – Orientation of the physical dipole corresponding to what is labelled as the x polarization. Options are “east” (indicating east/west orientation) and “north” (indicating north/south orientation)

  • reference_impedance (float, optional) – The reference impedance of the model(s).

  • extra_keywords (dict, optional) – A dictionary containing any extra_keywords.

  • frequency_select (list of float, optional) – Only used if the file is a yaml file. Indicates which frequencies to include (only read in files for those frequencies)

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

read_mwa_beam(h5filepath, delays=None, amplitudes=None, pixels_per_deg=5, freq_range=None, run_check=True, check_extra=True, run_check_acceptability=True)[source]

Read in the full embedded element MWA beam.

Note that the azimuth convention in for the UVBeam object is different than the azimuth convention in the mwa_pb repo. In that repo, the azimuth convention is changed from the native FEKO convention (the FEKO convention is the same as the UVBeam convention). The convention in the mwa_pb repo has a different zero point and a different direction (so it is in a left handed coordinate system).

Parameters
  • h5filepath (str) – path to input h5 file containing the MWA full embedded element spherical harmonic modes. Download via wget http://cerberus.mwa128t.org/mwa_full_embedded_element_pattern.h5

  • delays (array of ints) – Array of MWA beamformer delay steps. Should be shape (n_pols, n_dipoles).

  • amplitudes (array of floats) – Array of dipole amplitudes, these are absolute values (i.e. relatable to physical units). Should be shape (n_pols, n_dipoles).

  • pixels_per_deg (float) – Number of theta/phi pixels per degree. Sets the resolution of the beam.

  • freq_range (array_like of float) – Range of frequencies to include in Hz, defaults to all available frequencies. Must be length 2.

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

read(filename, file_type=None, skip_bad_files=False, beam_type='power', feed_pol=None, rotate_pol=None, frequency=None, telescope_name=None, feed_name=None, feed_version=None, model_name=None, model_version=None, history=None, x_orientation=None, reference_impedance=None, extra_keywords=None, frequency_select=None, delays=None, amplitudes=None, pixels_per_deg=5, freq_range=None, run_check=True, check_extra=True, run_check_acceptability=True)[source]

Read a generic file into a UVBeam object.

Some parameters only apply to certain file types.

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

    For cst yaml files only:

    Settings yaml files must include the following keywords:

    - telescope_name (str)
    - feed_name (str)
    - feed_version (str)
    - model_name (str)
    - model_version (str)
    - history (str)
    - frequencies (list(float))
    - cst text filenames (list(str)) – path relative to yaml file
    - feed_pol (str) or (list(str))

    and they may include the following optional keywords:

    - x_orientation (str): Optional but strongly encouraged!
    - ref_imp (float): beam model reference impedance
    - sim_beam_type (str): e.g. ‘E-farfield’
    - all other fields will go into the extra_keywords attribute

    More details and an example are available in the docs (cst_settings_yaml.rst). Specifying any of the associated keywords to this function will override the values in the settings file.

  • file_type (str) – One of [‘mwa_beam’, ‘beamfits’, ‘cst’] or None. If None, the code attempts to guess what the file type is. based on file extensions (mwa_beam: .hdf5, .h5; cst: .yaml, .txt; beamfits: .fits, .beamfits). Note that if a list of datasets is passed, the file type is determined from the first dataset.

  • beam_type (str) – What beam_type to read in (‘power’ or ‘efield’). Only applies to cst file types.

  • feed_pol (str) – The feed or polarization or list of feeds or polarizations the files correspond to. Defaults to ‘x’ (meaning x for efield or xx for power beams). Only applies to cst file types.

  • rotate_pol (bool) – If True, assume the structure in the simulation is symmetric under 90 degree rotations about the z-axis (so that the y polarization can be constructed by rotating the x polarization or vice versa). Default: True if feed_pol is a single value or a list with all the same values in it, False if it is a list with varying values. Only applies to cst file types.

  • frequency (float or list of float, optional) – The frequency or list of frequencies corresponding to the filename(s). This is assumed to be in the same order as the files. If not passed, the code attempts to parse it from the filenames. Only applies to cst file types.

  • telescope_name (str, optional) – The name of the telescope corresponding to the filename(s). Only applies to cst file types.

  • feed_name (str, optional) – The name of the feed corresponding to the filename(s). Only applies to cst file types.

  • feed_version (str, optional) – The version of the feed corresponding to the filename(s). Only applies to cst file types.

  • model_name (str, optional) – The name of the model corresponding to the filename(s). Only applies to cst file types.

  • model_version (str, optional) – The version of the model corresponding to the filename(s). Only applies to cst file types.

  • history (str, optional) – A string detailing the history of the filename(s). Only applies to cst file types.

  • x_orientation (str, optional) – Orientation of the physical dipole corresponding to what is labelled as the x polarization. Options are “east” (indicating east/west orientation) and “north” (indicating north/south orientation) Only applies to cst file types.

  • reference_impedance (float, optional) – The reference impedance of the model(s). Only applies to cst file types.

  • extra_keywords (dict, optional) – A dictionary containing any extra_keywords. Only applies to cst file types.

  • frequency_select (list of float, optional) – Only used if the file is a yaml file. Indicates which frequencies to include (only read in files for those frequencies) Only applies to cst file types.

  • delays (array of ints) – Array of MWA beamformer delay steps. Should be shape (n_pols, n_dipoles). Only applies to mwa_beam type files.

  • amplitudes (array of floats) – Array of dipole amplitudes, these are absolute values (i.e. relatable to physical units). Should be shape (n_pols, n_dipoles). Only applies to mwa_beam type files.

  • pixels_per_deg (float) – Number of theta/phi pixels per degree. Sets the resolution of the beam. Only applies to mwa_beam type files.

  • freq_range (array_like of float) – Range of frequencies to include in Hz, defaults to all available frequencies. Must be length 2. Only applies to mwa_beam type files.

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

Raises

ValueError – If the file_type is not set and cannot be determined from the file name.

classmethod from_file(filename, file_type=None, skip_bad_files=False, beam_type='power', feed_pol=None, rotate_pol=None, frequency=None, telescope_name=None, feed_name=None, feed_version=None, model_name=None, model_version=None, history=None, x_orientation=None, reference_impedance=None, extra_keywords=None, frequency_select=None, delays=None, amplitudes=None, pixels_per_deg=5, freq_range=None, run_check=True, check_extra=True, run_check_acceptability=True)[source]

Initialize a new UVBeam object by reading the input file(s).

Some parameters only apply to certain file types.

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

    For cst yaml files only:

    Settings yaml files must include the following keywords:

    - telescope_name (str)
    - feed_name (str)
    - feed_version (str)
    - model_name (str)
    - model_version (str)
    - history (str)
    - frequencies (list(float))
    - cst text filenames (list(str)) – path relative to yaml file
    - feed_pol (str) or (list(str))

    and they may include the following optional keywords:

    - x_orientation (str): Optional but strongly encouraged!
    - ref_imp (float): beam model reference impedance
    - sim_beam_type (str): e.g. ‘E-farfield’
    - all other fields will go into the extra_keywords attribute

    More details and an example are available in the docs (cst_settings_yaml.rst). Specifying any of the associated keywords to this function will override the values in the settings file.

  • file_type (str) – One of [‘mwa_beam’, ‘beamfits’, ‘cst’] or None. If None, the code attempts to guess what the file type is. based on file extensions (mwa_beam: .hdf5, .h5; cst: .yaml, .txt; beamfits: .fits, .beamfits). Note that if a list of datasets is passed, the file type is determined from the first dataset.

  • beam_type (str) – What beam_type to read in (‘power’ or ‘efield’). Only applies to cst file types.

  • feed_pol (str) – The feed or polarization or list of feeds or polarizations the files correspond to. Defaults to ‘x’ (meaning x for efield or xx for power beams). Only applies to cst file types.

  • rotate_pol (bool) – If True, assume the structure in the simulation is symmetric under 90 degree rotations about the z-axis (so that the y polarization can be constructed by rotating the x polarization or vice versa). Default: True if feed_pol is a single value or a list with all the same values in it, False if it is a list with varying values. Only applies to cst file types.

  • frequency (float or list of float, optional) – The frequency or list of frequencies corresponding to the filename(s). This is assumed to be in the same order as the files. If not passed, the code attempts to parse it from the filenames. Only applies to cst file types.

  • telescope_name (str, optional) – The name of the telescope corresponding to the filename(s). Only applies to cst file types.

  • feed_name (str, optional) – The name of the feed corresponding to the filename(s). Only applies to cst file types.

  • feed_version (str, optional) – The version of the feed corresponding to the filename(s). Only applies to cst file types.

  • model_name (str, optional) – The name of the model corresponding to the filename(s). Only applies to cst file types.

  • model_version (str, optional) – The version of the model corresponding to the filename(s). Only applies to cst file types.

  • history (str, optional) – A string detailing the history of the filename(s). Only applies to cst file types.

  • x_orientation (str, optional) – Orientation of the physical dipole corresponding to what is labelled as the x polarization. Options are “east” (indicating east/west orientation) and “north” (indicating north/south orientation) Only applies to cst file types.

  • reference_impedance (float, optional) – The reference impedance of the model(s). Only applies to cst file types.

  • extra_keywords (dict, optional) – A dictionary containing any extra_keywords. Only applies to cst file types.

  • frequency_select (list of float, optional) – Only used if the file is a yaml file. Indicates which frequencies to include (only read in files for those frequencies) Only applies to cst file types.

  • delays (array of ints) – Array of MWA beamformer delay steps. Should be shape (n_pols, n_dipoles). Only applies to mwa_beam type files.

  • amplitudes (array of floats) – Array of dipole amplitudes, these are absolute values (i.e. relatable to physical units). Should be shape (n_pols, n_dipoles). Only applies to mwa_beam type files.

  • pixels_per_deg (float) – Number of theta/phi pixels per degree. Sets the resolution of the beam. Only applies to mwa_beam type files.

  • freq_range (array_like of float) – Range of frequencies to include in Hz, defaults to all available frequencies. Must be length 2. Only applies to mwa_beam type files.

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

Raises

ValueError – If the file_type is not set and cannot be determined from the file name.

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

Write the data to a beamfits file.

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

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

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