    Read Measurement Set POLARIZATION table.

    Parameters
    ----------
    filepath : str
        path to MS (without POLARIZATION suffix)

    Returns
    -------
    pol_dict : dict
        A dictionary with keys matched to the polarization ID, with values "corr_type"
        (ndarray of int, shape (Npols,), matched to polarization code) and "num_corr"
        (ndarray of int, shape (Npols,), tallying the total number of polarization
        entries per record).

    Raises
    ------
    FileNotFoundError
        If no MS file is found with the provided name.


    Write out the polarization information into a CASA table.

    Parameters
    ----------
    filepath : str
        path to MS (without POLARIZATION suffix)
    pol_order : slice or list of int
        Ordering of the polarization axis on write, only used if not writing a
        flex-pol dataset.
    uvobj : UVBase (with matching parameters)
        Optional parameter, can be used to automatically fill the other required
        keywords for this function. Note that the UVBase object must have parameters
        that match by name to the other keywords required here (with the exception of
        flex_pol, which is derived from the presence of the flex_spw_polarization array
        UVParameter).
    polarization_array : ndarray
        Required if uvobj not provided, array containing polarization ID codes (ndarray
        of dtype int and shape (Npols,) if flex_pol=False, otherwise shape (Nspws,)).
    flex_pol : bool
        Required if uvobj not provided, whether or not the supplied polarization_array
        is derived for a flex-pol object (can contain duplicate entries of codes, with
        positions indexed against entries in the spectral window table). Default is
        False.

    Raises
    ------
    FileNotFoundError
        If no main MS table is found when looking at filepath.


    Create a skeleton MS dataset to fill.

    Parameters
    ----------
    filepath : str
        Path to MS to be created.
    make_model_col : bool
        If set to True, will construct a measurement set that contains a MODEL_DATA
        column in addition to the DATA column. Default is False.
    make_model_col : bool
        If set to True, will construct a measurement set that contains a CORRECTED_DATA
        column in addition to the DATA column. Default is False.

    Returns
    -------
    ms_table : casacore Table
        Table object linked to the newly created MS file.


    Create a skeleton MS calibration table to fill.

    Parameters
    ----------
    filepath : str
        Path to MS table to be created.
    delay_table : bool
        Set to False by default, which will create a MS table capable of storing
        complex gains. However, if set to True, the method will instead construct a
        table which can store delay information.


    Interpret an antenna positions file.

    Parameters
    ----------
    antenna_positions_file : str
        Name of the antenna_positions_file, which is assumed to be in DATA_PATH.
        Should be a csv file with the following columns:

            - "name": antenna names
            - "number": antenna numbers
            - "x": x ECEF coordinate relative to the telescope location.
            - "y": y ECEF coordinate relative to the telescope location.
            - "z": z ECEF coordinate relative to the telescope location.

    Returns
    -------
    antenna_names : array of str
        Antenna names.
    antenna_names : array of int
        Antenna numbers.
    antenna_positions : array of float
        Antenna positions in ECEF relative to the telescope location.


    Make axis arrays for fits files.

    Parameters
    ----------
    hdu : astropy.io.fits HDU object
        The HDU to make an axis array for.
    axis : int
        The axis number of interest (1-based).

    Returns
    -------
    ndarray of float
        Array of values for the specified axis.


    Get a dict of table names and HDU numbers from a FITS HDU list.

    Parameters
    ----------
    hdulist : list of astropy.io.fits HDU objects
        List of HDUs to get names for

    Returns
    -------
    dict
        dictionary with table names as keys and HDU number as values.


    Get any extra keywords and return as dict.

    Parameters
    ----------
    header : FITS header object
        header object to get extra_keywords from.
    keywords_to_skip : list of str
        list of keywords to not include in extra keywords in addition to standard
        FITS keywords.

    Returns
    -------
    dict
        dict of extra keywords.


    Check the FHD input files for matching prefixes and folders.

    Parameters
    ----------
    vis_files : str or array-like of str, optional
        FHD visibility save file names, can be data or model visibilities.
    params_file : str
        FHD params save file name.
    obs_file : str
        FHD obs save file name.
    flags_file : str
        FHD flag save file name.
    layout_file : str
        FHD layout save file name.
    layout_file : str
        FHD layout save file name.
    settings_file : str
        FHD settings text file name.
    cal_file : str
        FHD cal save file name.

    Returns
    -------
    A list of file basenames to be used in the object `filename` attribute.


Read in an MS-formatted gains table.


Write out a MS calibration table.


Read data from an FHD cal.sav file.


Check if any time parameter is defined in this but not in other or vice-versa.


        Create a new UVCal object.

        All parameters are passed through to
        the :func:`~pyuvdata.uvcal.initializers.new_uvcal` function.

        Returns
        -------
        UVCal
            A new UVCal object.


        Set the wide_band parameter and adjust required parameters.

        This method should not be called directly by users; instead it is called
        by the file-reading methods to indicate that an object is a wide-band
        calibration solution which supports gain or delay values per spectral window.


Set cal_type to 'gain' and adjust required parameters.


Set cal_type to 'delay' and adjust required parameters.


Set cal_style to 'sky' and adjust required parameters.


Set cal_style to 'redundant' and adjust required parameters.


List of strings giving the required data-like parameters.


        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 a regular UVCal object into one with flex-Jones enabled.

        This is an internal helper function, which is not designed to be called by
        users, but rather individual read/write functions for the UVCal object.
        This will convert a regular UVCal object into one that uses flexible
        Jones arrays, which allows for each spectral window to have its own unique
        Jones vector/code, useful for storing data more compactly when different
        windows have different Jones values recorded. Note that at this time,
        only one Jones code per-spw is allowed -- if more than one Jones code
        is found to have unflagged data in a given spectral window, then an error is
        returned.


        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.


        Check if the spectral windows are contiguous.

        This checks the flex_spw_id_array to make sure that all channels for each
        spectral window are together in one block, versus being interspersed (e.g.,
        channel #1 and #3 is in spw #1, channels #2 and #4 are in spw #2).

        Parameters
        ----------
        raise_errors : bool or None
            If set to True, then the function will raise an error if checks are failed.
            If set to False, then a warning is raised instead. If set to None, then
            no errors or warnings are raised.


        Check if frequencies are evenly spaced.

        This is a requirement for writing calfits files.

        Parameters
        ----------
        raise_errors : bool or None
            If set to True, then the function will raise an error if checks are failed.
            If set to False, then a warning is raised instead. If set to None, then
            no errors or warnings are raised.

        Returns
        -------
        spacing_error : bool
            Flag that channel spacings or channel widths are not equal.
        chanwidth_error : bool
            Flag that channel spacing does not match channel width.


        Check if Jones terms are evenly spaced.

        This is a requirement for calfits files.

        Parameters
        ----------
        raise_errors : bool
            If set to True, then the function will raise an error if checks are failed.
            If set to False, then a warning is raised instead. If set to None, then
            no errors or warnings are raised.


        Check if times are evenly spaced.

        This is a requirement for calfits files.

        Parameters
        ----------
        raise_errors : bool
            If set to True, then the function will raise an error if checks are failed.
            If set to False, then a warning is raised instead. If set to None, then
            no errors or warnings are raised.


        Add an entry to the internal object/source catalog or find a matching one.

        This is a helper function for identifying a adding a phase center to the
        internal catalog, contained within the attribute `phase_center_catalog`, unless
        a phase center already exists that matches the passed parameters. If a matching
        phase center is found, the catalog ID associated with that phase center is
        returned.

        Parameters
        ----------
        cat_name : str
            Name of the phase center to be added.
        cat_type : str
            Type of phase center to be added. Must be one of:
                "sidereal" (fixed RA/Dec),
                "ephem" (RA/Dec that moves with time),
                "driftscan" (fixed az/el position),
                "unprojected" (no w-projection, equivalent to the old
                `phase_type` == "drift").
        cat_lon : float or ndarray
            Value of the longitudinal coordinate (e.g., RA, Az, l) in radians of the
            phase center. No default unless `cat_type="unprojected"`, in which case the
            default is zero. Expected to be a float for sidereal and driftscan phase
            centers, and an ndarray of floats of shape (Npts,) for ephem phase centers.
        cat_lat : float or ndarray
            Value of the latitudinal coordinate (e.g., Dec, El, b) in radians of the
            phase center. No default unless `cat_type="unprojected"`, in which case the
            default is pi/2. Expected to be a float for sidereal and driftscan phase
            centers, and an ndarray of floats of shape (Npts,) for ephem phase centers.
        cat_frame : str
            Coordinate frame that cat_lon and cat_lat are given in. Only used
            for sidereal and ephem targets. Can be any of the several supported frames
            in astropy (a limited list: fk4, fk5, icrs, gcrs, cirs, galactic).
        cat_epoch : str or float
            Epoch of the coordinates, only used when cat_frame = fk4 or fk5. Given
            in units of fractional years, either as a float or as a string with the
            epoch abbreviation (e.g, Julian epoch 2000.0 would be J2000.0).
        cat_times : ndarray of floats
            Only used when `cat_type="ephem"`. Describes the time for which the values
            of `cat_lon` and `cat_lat` are calculated, in units of JD. Shape is (Npts,).
        cat_pm_ra : float
            Proper motion in RA, in units of mas/year. Only used for sidereal phase
            centers.
        cat_pm_dec : float
            Proper motion in Dec, in units of mas/year. Only used for sidereal phase
            centers.
        cat_dist : float or ndarray of float
            Distance of the source, in units of pc. Only used for sidereal and ephem
            phase centers. Expected to be a float for sidereal and driftscan phase
            centers, and an ndarray of floats of shape (Npts,) for ephem phase centers.
        cat_vrad : float or ndarray of float
            Radial velocity of the source, in units of km/s. Only used for sidereal and
            ephem phase centers. Expected to be a float for sidereal and driftscan phase
            centers, and an ndarray of floats of shape (Npts,) for ephem phase centers.
        info_source : str
            Optional string describing the source of the information provided. Used
            primarily in UVCal to denote when an ephemeris has been supplied by the
            JPL-Horizons system, user-supplied, or read in by one of the various file
            interpreters. Default is 'user'.
        force_update : bool
            Normally, `_add_phase_center` will throw an error if there already exists a
            phase_center with the given cat_id. However, if one sets
            `force_update=True`, the method will overwrite the existing entry in
            `phase_center_catalog` with the parameters supplied. Note that doing this
            will _not_ update other attributes of the `UVCal` object. Default is False.
        cat_id : int
            An integer signifying the ID number for the phase center, used in the
            `phase_center_id_array` attribute. If a matching phase center entry exists
            already, that phase center ID will be returned, which may be different than
            the value specified to this parameter. The default is for the method to
            assign this value automatically.

        Returns
        -------
        cat_id : int
            The unique ID number for the phase center that either matches the specified
            parameters or was added to the internal catalog. If a matching entry was
            found, this may not be the value passed to the `cat_id` parameter. This
            value is used in the `phase_center_id_array` attribute to denote which
            source a given baseline-time corresponds to.

        Raises
        ------
        ValueError
            If attempting to add a non-unique source name or if adding a sidereal
            source without coordinates.


        Remove objects dictionaries and names that are no longer in use.

        Goes through the `phase_center_catalog` attribute in of a UVCal object and
        clears out entries that are no longer being used, and appropriately updates
        `phase_center_id_array` accordingly. This function is not typically called
        by users, but instead is used by other methods.


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


        Consolidate phase center catalogs with a reference or another object.

        This is a helper method which updates the phase_center_catalog and related
        parameters to make this object consistent with a reference catalog or with
        another object so the second object can be added or concatenated to this object.
        If both `reference_catalog` and `other` are provided, both this object and the
        one passed to `other` will have their catalogs updated.

        Parameters
        ----------
        reference_catalog : dict
            A reference catalog to make this object consistent with.
        other : UVCal or UVData object
            Nominally a UVCal object which self needs to be consistent with because it
            will be added to self. The phase_center_catalog from other is used as the
            reference catalog if the reference_catalog is None. If `reference_catalog`
            is also set, the phase_center_catalog on other will also be modified to be
            consistent with the `reference_catalog`. Note that a UVData object can also
            be supplied (in order to ensure consistency between two related objects).
        ignore_name : bool
            Option to ignore the name of the phase center (`cat_name` in
            `phase_center_catalog`) when identifying matching phase centers. If set to
            True, phase centers that are the same up to their name will be combined with
            the name set to the reference catalog name or the name found in the first
            UVCal object. If set to False, phase centers that are the same up to the
            name will be kept as separate phase centers. Default is False.


        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.
        check_jones_spacing :  bool
            Option to check if Jones terms are evenly spaced. This is not required for
            UVCal objects in general but is required to write to calfits files.
        check_time_spacing :  bool
            Option to check if times are evenly spaced. This is not required for
            UVCal objects in general but is required to write to calfits files.
        raise_spacing_errors : bool or None
            If set to True, then the function will raise an error if spacing checks are
            failed. If set to False, then a warning is raised instead. If set to None,
            then no errors or warnings are raised.
        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)


        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.


        Check if this UVCal has the requested antenna or polarization.

        Parameters
        ----------
        antnum : int
            Antenna number to check.
        jpol : str or int
            Antenna polarization string or integer to check.

        Returns
        -------
        bool
            Boolean indicator of whether the antenna and/or antenna
            polarization is present on this object.


        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.


        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


        Slice a data array given a data key.

        Parameters
        ----------
        key : int or length 2 tuple of ints or int and str
            Antenna or antenna and polarization to get slice for. If it's a length
            2 tuple, the second value must be an antenna polarization int or string
            parsable by jpol2ind.
        data_array : :class: numpy ndarray
            Array to get slice of. Must have the shape of the gain_array or delay_array.
        squeeze_pol : bool
            Option to squeeze pol dimension if possible.

        Returns
        -------
        :class: numpy ndarray
            Slice of the data_array for the key.


        Parse key inputs and return a standard antenna-polarization key.

        Parameters
        ----------
        ant : int or length 2 tuple of ints or int and str
            Antenna or antenna and polarization to get key 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
            Antenna polarization int or string parsable by jpol2ind. Only used
            if `ant` is an integer.

        Returns
        -------
        tuple
            Standard key tuple.


        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.


        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.


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


        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.
        warn_spacing : bool
            Option to raise warnings about spacing that would prevent writing to
            calfits file-format. Default is False.


        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`.
        invert : bool
            Normally records matching given criteria are what are included in the
            subsequent object. However, if set to True, these records are excluded
            instead. Default is False.
        strict : bool or None
            Normally, select will warn when no records match a one element of a
            parameter, as long as *at least one* element matches with what is in the
            object. However, if set to True, an error is thrown if any element
            does not match. If set to None, then neither errors nor warnings are raised.
            Default is False.
        warn_spacing : bool
            Option to raise warnings about spacing that would prevent writing to
            calfits file-format. Default is False.

        Returns
        -------
        ant_inds : list of int
            list of antenna indices to keep. Can be None (to keep everything).
        time_inds : list of int
            list of time indices to keep. Can be None (to keep everything).
        spw_inds : list of int
            list of spw indices to keep. Can be None (to keep everything).
        freq_inds : list of int
            list of frequency indices to keep. Can be None (to keep everything).
        pol_inds : list of int
            list of polarization indices to keep. Can be None (to keep everything).
        history_update_string : str
            string to append to the end of the history.


        Perform select based on indexing arrays.

        Parameters
        ----------
        ant_inds : list of int
            list of antenna indices to keep. Can be None (to keep everything).
        time_inds : list of int
            list of time indices to keep. Can be None (to keep everything).
        freq_inds : list of int
            list of frequency indices to keep. Can be None (to keep everything).
        jones_inds : list of int
            list of jones indices to keep. Can be None (to keep everything).
        history_update_string : str
            string to append to the end of the history.


        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`.
        invert : bool
            Normally records matching given criteria are what are included in the
            subsequent object. However, if set to True, these records are excluded
            instead. Default is False.
        strict : bool or None
            Normally, select will warn when no records match a one element of a
            parameter, as long as *at least one* element matches with what is in the
            object. However, if set to True, an error is thrown if any element
            does not match. If set to None, then neither errors nor warnings are raised.
            Default is False.
        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).
        warn_spacing : bool
            Option to raise warnings about spacing that would prevent writing to
            calfits file-format. Default is False.


        Initialize this object based on a UVData object.

        Parameters
        ----------
        uvdata : UVData object
            The UVData object to initialize from.
        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.


        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.
        default_mount_type : str
            If not recorded in the data set or telescope is unknown to pyuvdata, the
            `Telescope.mount_type` parameter is automatically set to "other". However,
            users can specify a different default by passing an argument here.
        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 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.
        default_mount_type : str
            If not recorded in the data set or telescope is unknown to pyuvdata, the
            `Telescope.mount_type` parameter is automatically set to "other". However,
            users can specify a different default by passing an argument here.
        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 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.
        default_mount_type : str
            If not recorded in the data set or telescope is unknown to pyuvdata, the
            `Telescope.mount_type` parameter is automatically set to "other". However,
            users can specify a different default by passing an argument here.
        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 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 [-5, -6] (linear pols) 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.
        default_mount_type : str
            If not recorded in the data set or telescope is unknown to pyuvdata, the
            `Telescope.mount_type` parameter is automatically set to "other". However,
            users can specify a different default by passing an argument here.
        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 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.
        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.
        default_mount_type : str
            If not recorded in the data set or telescope is unknown to pyuvdata, the
            `Telescope.mount_type` parameter is automatically set to "other". However,
            users can specify a different default by passing an argument here.

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

        MSCal
        -----
        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 [-5, -6] (linear pols) 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.


Initialize a new UVCal object by reading the input file.


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


        Write the data to a MS calibration table.

        Parameters
        ----------
        filename : str
            The measurement set to write to.
        clobber : bool
            Option to overwrite the file if it already exists.


        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.


Read data from a calfits file.


Check if the file has a given antenna number or antenna number-pol key.


Convert the file to a UVData object.

        The object will be metadata-only.


        Read header information from a UVH5 file.

        This is an internal function called by the user-space methods.
        Properties of the UVData object are updated as the file is processed.

        Parameters
        ----------
        meta : FastCalH5Meta, h5py.File or h5py.Group
            A FastCalH5Meta or object that contains the header information.
        background_lsts : bool
            When set to True, the lst_array is calculated in a background thread.
        run_check_acceptability : bool
            Option to check that LSTs match the times given the telescope_location.
        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


        Read the data-size arrays (gain/delay arrays, flags, qualities) from a file.

        This is an internal function to read just the calibration solutions, flags, and
        qualities from the CalH5 file. This is separated from full read so that
        header/metadata and data can be read independently. See the
        documentation of `read_calh5` for a full description of most of the
        descriptions of parameters. Below we only include a description of args
        unique to this function.

        Parameters
        ----------
        dgrp : h5py datagroup
            The HDF5 datagroup containing the datasets. Should be "/Data" for
            UVH5 files conforming to spec.

        Returns
        -------
        None

        Raises
        ------
        ValueError
            This is raised if the data array read from the file is not a complex
            datatype (np.complex64 or np.complex128).


Read in data from a CalH5 file.


        Write data to the header datagroup of a CalH5 file.

        Parameters
        ----------
        header : h5py datagroup
            The datagroup to write the header information to. For a UVH5 file
            conforming to the spec, it should be "/Header"

        Returns
        -------
        None


Write an in-memory UVCal object to a CalH5 file.


r"""Create a new UVCal object with default parameters.

    Parameters
    ----------
    cal_style : str
        Calibration style. Options are 'sky' or 'redundant'.
    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).
    telescope : pyuvdata.Telescope
        Telescope object containing the telescope-related metadata including
        telescope name and location, x_orientation and antenna names, numbers
        and positions.
    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)
    update_telescope_from_known : bool
        If set to True, then the method will fill in any missing fields/information on
        the Telescope object if the name is recognized. Default is True.
    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.
    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.

    Returns
    -------
    UVCal
        A new UVCal object with default parameters.


Construct a UVCal object with default attributes from 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 :func:`new_uvcal` to construct the UVCal object.

    Parameters
    ----------
    uvdata : UVData
        UVData object to use as a template.
    cal_type : str
        Calibration type. Must be 'gain' or 'delay'. Default 'gain'.
        Note that in contrast to :func:`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)``.


Read in a FEKO ffe file.


    Create the Legendre function flavors for FF expansion using spherical waves.

    Note this is not vectorized so is a bit slow, but it handles the special
    case of theta = 0 and pi. We primarily use the vectorized version
    (`P1sin_array`), but call this to handle the special cases.

    See:
    Calculating Far-Field Radiation Based on FEKO Spherical Wave Coefficients,
    draft 10 June 2015.
    Available at pyuvdata/docs/references/Far_field_spherical_FEKO_draft2.pdf
    This memo gives a full description of the equations implemented here,
    including descriptions of the approximations and numerical approaches used.
    In line comments below are helpful reminders, but see the memo for the full
    detail.
    Also see Sokolowski, M. et al, "Calibration and Stokes Imaging with Full
    Embedded Element Primary Beam Model for the Murchison Widefield Array",
    PASA, 2017 (10.1017/pasa.2017.54) for details specific to the MWA.

    Parameters
    ----------
    nmax : int
        Maximum n from FEKO Q1mn and Q2mn, n must be >=1
    theta : float
        The argument of the cosine or sine function used in the associated
        Legendre functions, in radians.

    Returns
    -------
    P_sin : array of float
        P_{n}^{abs(m)}(cos(theta))/sin(theta) with FEKO order M,N.
        Shape (nmax ** 2 + 2 * nmax).
    P1 : array of float
        P_{n}^{abs(m)+1}(cos(theta)) with FEKO order M,N.
        Shape (nmax ** 2 + 2 * nmax).


    Calculate P^abs(m)_n(cos(theta))/sin(theta) and P^(abs(m)+1)_n(cos(theta)).

    Similar to the "P1sin" function, but calculates for all theta in one go.
    At the end of the function, patches are made using the original P1sin function
    to solve the 0/0 issue.

    Parameters
    ----------
    nmax : int
        Maximum n from FEKO Q1mn and Q2mn, n must be >=1
    theta : array of float
        The argument of the cosine or sine functions used in the associated
        Legendre functions, in radians.

    Returns
    -------
    P_sin : array of float
        P_{n}^{abs(m)}(cos(theta))/sin(theta) with FEKO order M,N.
        Shape (nmax ** 2 + 2 * nmax, theta.size).
    P1 : array of float
        P_{n}^{abs(m)+1}(cos(theta)) with FEKO order M,N.
        Shape (nmax ** 2 + 2 * nmax, theta.size).


        Get metadata (frequencies, polarizations, dipole numbers) from input file.

        Parameters
        ----------
        h5filepath : str
            path to input h5 file containing the MWA full embedded element spherical
            harmonic modes.

        Returns
        -------
        freqs_hz : array of int
            Frequencies in Hz present in the file.
        pol_names : list of str
            Polarizations present in the file.
        dipole_names :
            Dipoles names present in the file.
        max_length : dict
            Dictionary keyed on pol and freq, giving max number of modes in the
            file for each pol and freq.


        Get beam modes from input file and save as a dict to the object.

        Parameters
        ----------
        h5filepath : str
            path to input h5 file containing the MWA full embedded element spherical
            harmonic modes.
        freqs_hz : array of int
            Frequencies in Hz to get modes for. Must be present in the file.
        pol_names : list of str
            Polarizations  to get modes for. Must be present in the file.
        dipole_names : array of str
            Dipoles names present in the file.
        max_length : dict
            Dictionary keyed on pol and freq, giving max number of modes in the
            file for each pol and freq.
        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).

        Returns
        -------
        beam_modes : dict
            A multi-level dict keyed on (in order) pol, freq, mode name (Q1, Q2, M, N).


        Calculate full Jones matrix response (E-field) of beam on a regular az/za grid.

        Parameters
        ----------
        freqs_hz : array of int
            Frequencies in Hz to get modes for. Must be present in the file.
        pol_names : list of str
            Polarizations  to get modes for. Must be present in the file.
        beam_modes : dict
            A multi-level dict keyed on (in order) pol, freq, mode name (Q1, Q2, M, N).
        phi_arr : float or array of float
            azimuth angles (radians), east through north.
        theta_arr : float or array of float
            zenith angles (radian)

        Returns
        -------
        jones : array of float
            jones vectors, shape (Npol, 2, Nfreq, Nphi, Ntheta), e.g.
                [J_11=Xtheta J_12=Xphi]
                [J_21=Ytheta J_21=Yphi]


Read in the full embedded element MWA beam.


        Extract frequency from the filename.

        Assumes the file name contains a substring with the frequency channel
        in MHz that the data represents.
        e.g. "HERA_Sim_120.87MHz.txt" should yield 120.87e6

        Parameters
        ----------
        fname : str
            Filename to parse.

        Returns
        -------
        float
            Frequency extracted from filename in Hz.


        Read in data from a cst file.

        Parameters
        ----------
        filename : str
            The cst file to read from.
        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).
        feed_array : str or array-like of str
            Feeds to define this beam for, e.g. x & y or r & l. Only used for power
            beams (feeds are set by feed_pol for efield beams).
        feed_angle : float or array-like of float
            Position angle of a given feed, units of radians. A feed angle of 0 is
            typically oriented toward zenith for steerable antennas, otherwise toward
            north for fixed antennas (e.g., HERA, LWA). More details on this can be
            found on the "Conventions" page of the docs. Must match shape of feed_pol
            for efield beams, or feed_angle 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.
        mount_type : str
            Antenna mount type, which describes the optics of the antenna in question.
            Supported options include: "alt-az" (primary rotates in azimuth and
            elevation), "equatorial" (primary rotates in hour angle and declination)
            "orbiting" (antenna is in motion, and its orientation depends on orbital
            parameters), "x-y" (primary rotates first in the plane connecting east,
            west, and zenith, and then perpendicular to that plane),
            "alt-az+nasmyth-r" ("alt-az" mount with a right-handed 90-degree tertiary
            mirror), "alt-az+nasmyth-l" ("alt-az" mount with a left-handed 90-degree
            tertiary mirror), "phased" (antenna is "electronically steered" by
            summing the voltages of multiple elements, e.g. MWA), "fixed" (antenna
            beam pattern is fixed in azimuth and elevation, e.g., HERA), and "other"
            (also referred to in some formats as "bizarre"). See the "Conventions"
            page of the documentation for further details.
        frequency : float or list of float
            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
            The name of the telescope corresponding to the filename(s).
        feed_name : str
            The name of the feed corresponding to the filename(s).
        feed_version : str
            The version of the feed corresponding to the filename(s).
        model_name : str
            The name of the model corresponding to the filename(s).
        model_version : str
            The version of the model corresponding to the filename(s).
        history : str
            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.
        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.
        check_auto_power : bool
            For power beams, check whether the auto polarization beams have non-zero
            imaginary values in the data_array (which should not mathematically exist).
        fix_auto_power : bool
            For power beams, if auto polarization beams with imaginary values are found,
            fix those values so that they are real-only in data_array.


        Create a new UVBeam object.

        All parameters are passed through to
        the :func:`~pyuvdata.uvbeam.initializers.new_uvbeam` function.

        Returns
        -------
        UVBeam
            A new UVBeam object.


Set parameters depending on pixel_coordinate_system.


Set beam_type to 'efield' and adjust required parameters.


Set beam_type to 'power' and adjust required parameters.


Set antenna_type to 'simple' and adjust required parameters.


Set antenna_type to 'phased_array' and adjust required parameters.


Remove imaginary component of auto polarization power beams.


        Check for complex auto polarization power beams.

        Parameters
        ----------
        fix_auto_power : bool
            If auto polarization power beams with imaginary values are found,
            fix those values so that they are real-only in data_array.
        warn_tols : tuple of float
            Tolerances (relative, absolute) to use in comparing max imaginary part of
            auto polarization power beams to zero (passed to numpy.isclose). If the max
            imaginary part is close to zero within the tolerances and fix_auto_power is
            True, silently fix them to be zero and do not warn.


        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.
        check_auto_power : bool
            For power beams, check whether the auto polarization beams have non-zero
            imaginary values in the data_array (which should not mathematically exist).
        fix_auto_power : bool
            For power beams, if auto polarization beams with imaginary values are found,
            fix those values so that they are real-only in data_array. Ignored if
            check_auto_power is False.


Convert to peak normalization.


        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.


        Calculate Pauli matrices for pseudo-Stokes conversion.

        Derived from https://arxiv.org/pdf/1401.2095.pdf, the Pauli
        indices are reordered from the quantum mechanical
        convention to an order which gives the ordering of the pseudo-Stokes vector
        ['pI', 'pQ', 'pU, 'pV'].

        Parameters
        ----------
        pol_index : int
            Polarization index for which the Pauli matrix is generated, the index
            must lie between 0 and 3 ('pI': 0, 'pQ': 1, 'pU': 2, 'pV':3).

        Returns
        -------
        array of float
            Pauli matrix for pol_index. Shape: (2, 2)


        Generate Mueller components.

        Following https://arxiv.org/pdf/1802.04151.pdf. Using equation:

                Mij = Tr(J sigma_i J^* sigma_j)

        where sigma_i and sigma_j are Pauli matrices.

        Parameters
        ----------
        jones : array of float
            Jones matrices containing the electric field for the dipole arms
            or linear polarizations. Shape: (Npixels, 2, 2) for Healpix beams or
            (Naxes1 * Naxes2, 2, 2) otherwise.
        pol_index1 : int
            Polarization index referring to the first index of Mij (i).
        pol_index2 : int
            Polarization index referring to the second index of Mij (j).

        Returns
        -------
        array of float
            Mueller array containing the Mij values, shape: (Npixels,) for Healpix beams
            or (Naxes1 * Naxes2,) otherwise.


        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.


        Interpolate function along frequency axis.

        Parameters
        ----------
        freq_array : array_like of floats
            Frequency values to interpolate to.
        kind : str
            Interpolation method to use frequency.
            See scipy.interpolate.interp1d for details.

        Returns
        -------
        interp_data : array_like of float or complex
            The array of interpolated data values, shape: (Naxes_vec, Nfeeds or Npols,
            freq_array.size, Npixels or (Naxis2, Naxis1))
        interp_bandpass : array_like of float
            The interpolated bandpass. shape: (freq_array.size)
        interp_coupling_matrix : array_like of complex, optional
            The interpolated coupling matrix. Only returned if antenna_type is
            "phased_array".
            shape: (Nelements, Nelements, Nfeeds, Nfeeds, freq_array.size)


        Handle "interp" inputs prior to calling "_interp_freq".

        This helper function that is used by the az_za and healpix beam
        interpolation methods. Prior to performing interpolation along the
        azimuth/zenith angle axes, this function checks if the provided frequency
        array is not None. If it is not None, it performs frequency interpolation
        using "_interp_freq". If the frequency array is None, it returns the
        intrinsic data array and bandpass array.


Check if the interpolation domain is covered by the intrinsic data array.


Prepare coordinate data for interpolation functions.


Prepare inputs for polarized interpolation functions.


Prepare basis vector array for interpolation functions.


        Interpolate in az_za coordinate system using RectBivariateSpline.

        Uses the :func:`scipy.interpolate.RectBivariateSpline` function to perform
        interpolation in the azimuth-zenith angle coordinate system.

        Parameters
        ----------
        az_array : array_like of floats
            Azimuth values to interpolate to in radians, specifying the azimuth
            positions for every interpolation point (same length as `za_array`).
        za_array : array_like of floats
            Zenith values to interpolate to in radians, specifying the zenith
            positions for every interpolation point (same length as `az_array`).
        freq_array : array_like of floats
            Frequency values to interpolate to.
        freq_interp_kind : str
            Interpolation method to use frequency.
            See scipy.interpolate.interp1d for details.
        polarizations : list of str
            polarizations to interpolate if beam_type is 'power'.
            Default is all polarizations in self.polarization_array.
        reuse_spline : bool
            Option to save the interpolation functions for reuse, default is False.
        spline_opts : dict, optional
            Option to specify (kx, ky, s) for numpy.RectBivariateSpline. Note that
            this parameter is ignored if this function has been called previously
            on this object instance and reuse_spline is True.
        check_azza_domain : bool
            Whether to check the domain of az/za to ensure that they are covered by the
            intrinsic data array. Checking them can be quite computationally expensive.
        return_basis_vector : bool
            Whether to return the interpolated basis vectors. Prior to v3.1.1 these
            were always returned. Now they are not by default.

        Returns
        -------
        interp_data : array_like of float or complex
            The array of interpolated data values,
            shape: (Naxes_vec, Nfeeds or Npols, freq_array.size, az_array.size)
        interp_basis_vector : array_like of float
            The array of interpolated basis vectors,
            shape: (Naxes_vec, Ncomponents_vec, az_array.size)
        interp_bandpass : array_like of float
            The interpolated bandpass. shape: (freq_array.size,)
        interp_coupling_matrix : array_like of complex, optional
            The interpolated coupling matrix. Only returned if antenna_type is
            "phased_array".
            shape: (Nelements, Nelements, Nfeeds, Nfeeds, freq_array.size)


        Interpolate in az_za coordinate system using map_coordinates.

        Uses the :func:`scipy.ndimage.map_coordinates` function to perform
        interpolation in the azimuth-zenith angle coordinate system.

        Parameters
        ----------
        az_array : array_like of floats
            Azimuth values to interpolate to in radians, specifying the azimuth
            positions for every interpolation point (same length as `za_array`).
        za_array : array_like of floats
            Zenith values to interpolate to in radians, specifying the zenith
            positions for every interpolation point (same length as `az_array`).
        freq_array : array_like of floats
            Frequency values to interpolate to.
        freq_interp_kind : str
            Interpolation method to use frequency.
            See scipy.interpolate.interp1d for details.
        polarizations : list of str
            polarizations to interpolate if beam_type is 'power'.
            Default is all polarizations in self.polarization_array.
        reuse_spline : bool
            Save the interpolation functions for reuse.
        spline_opts : dict, optional
            Option to specify (kx, ky, s) for numpy.RectBivariateSpline. Note that
            this parameter is ignored if this function has been called previously
            on this object instance and reuse_spline is True.
        check_azza_domain : bool
            Whether to check the domain of az/za to ensure that they are covered by the
            intrinsic data array. Checking them can be quite computationally expensive.
        return_basis_vector : bool
            Whether to return the interpolated basis vector. Default is False as of
            v3.1.1, but was previously True.

        Returns
        -------
        interp_data : array_like of float or complex
            The array of interpolated data values,
            shape: (Naxes_vec, Nfeeds or Npols, freq_array.size, az_array.size)
        interp_basis_vector : array_like of float
            The array of interpolated basis vectors,
            shape: (Naxes_vec, Ncomponents_vec, az_array.size)
        interp_bandpass : array_like of float
            The interpolated bandpass. shape: (freq_array.size,)
        interp_coupling_matrix : array_like of complex, optional
            The interpolated coupling matrix. Only returned if antenna_type is
            "phased_array".
            shape: (Nelements, Nelements, Nfeeds, Nfeeds, freq_array.size)


        Interpolate in Healpix coordinate system with a simple bilinear function.

        Parameters
        ----------
        az_array : array_like of floats
            Azimuth values to interpolate to in radians, specifying the azimuth
            positions for every interpolation point (same length as `za_array`).
        za_array : array_like of floats
            Zenith values to interpolate to in radians, specifying the zenith
            positions for every interpolation point (same length as `az_array`).
        freq_array : array_like of floats
            Frequency values to interpolate to.
        freq_interp_kind : str
            Interpolation method to use frequency.
            See scipy.interpolate.interp1d for details.
        polarizations : list of str
            polarizations to interpolate if beam_type is 'power'.
            Default is all polarizations in self.polarization_array.
        return_basis_vector : bool
            Whether to return the interpolated basis vectors. Prior to v3.1.1 these
            were always returned. Now they are not by default.

        Returns
        -------
        interp_data : array_like of float or complex
            The array of interpolated data values,
            shape: (Naxes_vec, Nfeeds or Npols, Nfreqs, az_array.size)
        interp_basis_vector : array_like of float
            The array of interpolated basis vectors,
            shape: (Naxes_vec, Ncomponents_vec, az_array.size)
        interp_bandpass : array_like of float
            The interpolated bandpass. shape: (freq_array.size,)
        interp_coupling_matrix : array_like of complex, optional
            The interpolated coupling matrix. Only returned if antenna_type is
            "phased_array".
            shape: (Nelements, Nelements, Nfeeds, Nfeeds, freq_array.size)