A little more utils restructuring, update docs for new structure

.flake8

@@ -15,8 +15,10 @@ per-file-ignores =
     src/pyuvdata/uvdata/uvdata.py: N802
     src/pyuvdata/uvbeam/mwa_beam.py: N802
     src/pyuvdata/utils/coordinates.py: N802, N803
+    src/pyuvdata/utils/io/__init__.py: A005
     tests/utils/test_coordinates.py: D,N802
     tests/__init__.py: D,N802
+    tests/utils/io/__init__.py: A005
 docstring-convention = numpy
 select = C,E,W,T4,B9,F,D,A,N,RST,B
 rst-roles =

docs/developer_docs.rst

@@ -26,6 +26,9 @@ attribute shapes and values.
 .. autoclass:: pyuvdata.parameter.LocationParameter
   :members:
 
+.. autoclass:: pyuvdata.parameter.SkyCoordParameter
+  :members:
+
 .. autoclass:: pyuvdata.uvbase.UVBase
   :members:
 
@@ -36,6 +39,10 @@ specific code. The read and write methods on the user classes convert between
 the user classes and the file-specific classes automatically as needed, so users
 generally do not need to interact with these classes, but developers may need to.
 
+
+UVData
+******
+
 .. autoclass:: pyuvdata.uvdata.fhd.FHD
   :members:
 
@@ -57,12 +64,21 @@ generally do not need to interact with these classes, but developers may need to
 .. autoclass:: pyuvdata.uvdata.uvh5.UVH5
   :members:
 
+UVCal
+*****
+
 .. autoclass:: pyuvdata.uvcal.calfits.CALFITS
   :members:
 
+.. autoclass:: pyuvdata.uvcal.calh5.CalH5
+  :members:
+
 .. autoclass:: pyuvdata.uvcal.fhd_cal.FHDCal
   :members:
 
+UVBeam
+******
+
 .. autoclass:: pyuvdata.uvbeam.beamfits.BeamFITS
   :members:
 
@@ -73,6 +89,159 @@ generally do not need to interact with these classes, but developers may need to
   :members:
 
 
+.. _Developer Docs Utility Functions:
+
+Utility Functions
+-----------------
+Note that we are also listing private functions here (functions that start with
+an underscore). While they are listed here, **they are not considered part of the
+public API, so they can change without notice**. If you find that you need to rely
+one of them let us know in a github issue and we can consider making it part of
+the public API.
+
+
+File I/O Utility Functions
+**************************
+
+Antenna position files
+++++++++++++++++++++++
+
+.. automodule:: pyuvdata.utils.io.antpos
+  :members:
+  :private-members:
+  :undoc-members:
+
+FHD files
++++++++++
+
+.. automodule:: pyuvdata.utils.io.fhd
+  :members:
+  :private-members:
+  :undoc-members:
+
+FITS files
+++++++++++
+
+.. automodule:: pyuvdata.utils.io.fits
+  :members:
+  :private-members:
+  :undoc-members:
+
+HDF5 files
+++++++++++
+
+.. automodule:: pyuvdata.utils.io.hdf5
+  :members:
+  :private-members:
+  :undoc-members:
+
+Measurement Set files
++++++++++++++++++++++
+
+.. automodule:: pyuvdata.utils.io.ms
+  :members:
+  :private-members:
+  :undoc-members:
+
+Array collapse functions for flags
+**********************************
+
+.. automodule:: pyuvdata.utils.array_collapse
+  :members:
+  :private-members:
+  :undoc-members:
+
+Functions for working with baseline numbers
+*******************************************
+
+.. automodule:: pyuvdata.utils.bls
+  :members:
+  :private-members:
+  :undoc-members:
+  :ignore-module-all:
+
+Functions for working with the baseline-time axis
+*************************************************
+
+.. automodule:: pyuvdata.utils.bltaxis
+  :members:
+  :private-members:
+  :undoc-members:
+
+Functions for working with telescope coordinates
+************************************************
+
+.. automodule:: pyuvdata.utils.coordinates
+  :members:
+  :private-members:
+  :undoc-members:
+  :ignore-module-all:
+
+Functions for working with the frequency axis
+*********************************************
+
+.. automodule:: pyuvdata.utils.frequency
+  :members:
+  :private-members:
+  :undoc-members:
+
+Functions for working with history
+**********************************
+
+.. automodule:: pyuvdata.utils.history
+  :members:
+  :private-members:
+  :undoc-members:
+
+Functions for working with phase center catalogs
+************************************************
+
+.. automodule:: pyuvdata.utils.phase_center_catalog
+  :members:
+  :private-members:
+  :undoc-members:
+
+Functions for working with phasing
+**********************************
+
+.. automodule:: pyuvdata.utils.phasing
+  :members:
+  :private-members:
+  :undoc-members:
+
+Functions for working with polarizations
+****************************************
+
+.. automodule:: pyuvdata.utils.pol
+  :members:
+  :private-members:
+  :undoc-members:
+  :ignore-module-all:
+
+Functions for working with baseline redundancies
+************************************************
+
+.. automodule:: pyuvdata.utils.redundancy
+  :members:
+  :private-members:
+  :undoc-members:
+
+Functions for working with times and LSTs
+*****************************************
+
+.. automodule:: pyuvdata.utils.times
+  :members:
+  :private-members:
+  :undoc-members:
+
+General utility functions
+*************************
+
+.. automodule:: pyuvdata.utils.tools
+  :members:
+  :private-members:
+  :undoc-members:
+
 Mir Parser
 ----------
 .. automodule:: pyuvdata.uvdata.mir_parser
@@ -82,10 +251,8 @@ Mir Parser
   :members:
 
 
-Functions
-----------
-
-.. autofunction:: pyuvdata.uvdata.fhd.get_fhd_history
+Other Functions
+---------------
 
 .. autofunction:: pyuvdata.uvbeam.mwa_beam.P1sin
 

docs/functions.rst

@@ -0,0 +1,50 @@
+Useful Functions
+================
+There are some functions that interact with multiple types of objects to apply
+calibrations solutions and flagging to other objects.
+
+.. autofunction:: pyuvdata.uvcalibrate
+
+.. autofunction:: pyuvdata.apply_uvflag
+
+
+Utility Functions
+-----------------
+Some of our utility functions are widely used. The most commonly used ones are
+noted here, for others see the developer docs: :ref:`developer docs utility functions`.
+
+.. autofunction:: pyuvdata.utils.baseline_to_antnums
+.. autofunction:: pyuvdata.utils.antnums_to_baseline
+
+.. autofunction:: pyuvdata.utils.LatLonAlt_from_XYZ
+.. autofunction:: pyuvdata.utils.XYZ_from_LatLonAlt
+.. autofunction:: pyuvdata.utils.rotECEF_from_ECEF
+.. autofunction:: pyuvdata.utils.ECEF_from_rotECEF
+.. autofunction:: pyuvdata.utils.ENU_from_ECEF
+.. autofunction:: pyuvdata.utils.ECEF_from_ENU
+
+.. autofunction:: pyuvdata.utils.polstr2num
+.. autofunction:: pyuvdata.utils.polnum2str
+.. autofunction:: pyuvdata.utils.jstr2num
+.. autofunction:: pyuvdata.utils.jnum2str
+.. autofunction:: pyuvdata.utils.conj_pol
+.. autofunction:: pyuvdata.utils.x_orientation_pol_map
+.. autofunction:: pyuvdata.utils.parse_polstr
+.. autofunction:: pyuvdata.utils.parse_jpolstr
+
+.. autofunction:: pyuvdata.utils.get_lst_for_time
+
+.. autofunction:: pyuvdata.utils.uvw_track_generator
+
+.. autofunction:: pyuvdata.utils.collapse
+
+Polarization Dictionaries
+-------------------------
+We also define some useful dictionaries for mapping polarizations:
+
+  * ``pyuvdata.utils.POL_STR2NUM_DICT``: maps visibility polarization strings to polarization integers
+  * ``pyuvdata.utils.POL_NUM2STR_DICT``: maps visibility polarization integers to polarization strings
+  * ``pyuvdata.utils.JONES_STR2NUM_DICT``: maps calibration polarization strings to polarization integers
+  * ``pyuvdata.utils.JONES_NUM2STR_DICT``: maps calibration polarization strings to polarization integers
+  * ``pyuvdata.utils.CONJ_POL_DICT``: maps how visibility polarizations change when antennas are swapped (visibilities are conjugated)
+  * ``pyuvdata.utils.XORIENTMAP``: maps x_orientation strings to cannonical names

docs/make_index.py

@@ -52,7 +52,7 @@ def write_index_rst(readme_file=None, write_file=None):
         "   telescope\n"
         "   fast_uvh5_meta\n"
         "   fast_calh5_meta\n"
-        "   utility_functions\n"
+        "   functions\n"
         "   developer_docs\n"
     )
 

src/pyuvdata/parameter.py

@@ -31,7 +31,7 @@
     hasmoon = False
 
 
-__all__ = ["UVParameter", "AngleParameter", "LocationParameter"]
+__all__ = ["UVParameter", "AngleParameter", "LocationParameter", "SkyCoordParameter"]
 
 
 def _get_generic_type(expected_type, strict_type_check=False):
@@ -1228,6 +1228,17 @@ def __init__(
         )
 
     def __eq__(self, other, *, silent=False):
+        """
+        Test if classes match and values are within tolerances.
+
+        Parameters
+        ----------
+        other : UVParameter or subclass
+            The other UVParameter to compare with this one.
+        silent : bool
+            When set to False (default), descriptive text is printed out when parameters
+            do not match. If set to True, this text is not printed.
+        """
         if not issubclass(self.value.__class__, SkyCoord) or not issubclass(
             other.value.__class__, SkyCoord
         ):

src/pyuvdata/telescopes.py

@@ -20,8 +20,8 @@
 from . import parameter as uvp
 from . import utils
 from .data import DATA_PATH
-from .utils.file_io import antpos
-from .utils.file_io import hdf5 as hdf5_utils
+from .utils.io import antpos
+from .utils.io import hdf5 as hdf5_utils
 from .uvbase import UVBase
 
 __all__ = ["Telescope", "known_telescopes", "known_telescope_location", "get_telescope"]

src/pyuvdata/utils/__init__.py

@@ -22,9 +22,9 @@
 from . import bls  # noqa
 from . import bltaxis  # noqa
 from . import coordinates  # noqa
-from . import file_io  # noqa
 from . import frequency  # noqa
 from . import history  # noqa
+from . import io  # noqa
 from . import phase_center_catalog  # noqa
 from . import phasing  # noqa
 from . import pol  # noqa
@@ -63,7 +63,7 @@ def _fits_gethduaxis(hdu, axis):
     """
     Make axis arrays for fits files.
 
-    Deprecated. Use pyuvdata.utils.file_io.fits._gethduaxis.
+    Deprecated. Use pyuvdata.utils.io.fits._gethduaxis.
 
     Parameters
     ----------
@@ -78,11 +78,11 @@ def _fits_gethduaxis(hdu, axis):
         Array of values for the specified axis.
 
     """
-    from .file_io.fits import _gethduaxis
+    from .io.fits import _gethduaxis
 
     warnings.warn(
         "The _fits_gethduaxis function has moved, please import it as "
-        "pyuvdata.utils.file_io.fits._gethduaxis. This warnings will become an "
+        "pyuvdata.utils.io.fits._gethduaxis. This warnings will become an "
         "error in version 3.2",
         DeprecationWarning,
     )
@@ -94,7 +94,7 @@ def _fits_indexhdus(hdulist):
     """
     Get a dict of table names and HDU numbers from a FITS HDU list.
 
-    Deprecated. Use pyuvdata.utils.file_io.fits._indexhdus.
+    Deprecated. Use pyuvdata.utils.io.fits._indexhdus.
 
     Parameters
     ----------
@@ -107,11 +107,11 @@ def _fits_indexhdus(hdulist):
         dictionary with table names as keys and HDU number as values.
 
     """
-    from .file_io.fits import _indexhdus
+    from .io.fits import _indexhdus
 
     warnings.warn(
         "The _fits_indexhdus function has moved, please import it as "
-        "pyuvdata.utils.file_io.fits._indexhdus. This warnings will become an "
+        "pyuvdata.utils.io.fits._indexhdus. This warnings will become an "
         "error in version 3.2",
         DeprecationWarning,
     )