reorganize utils

.flake8

@@ -14,9 +14,11 @@ per-file-ignores =
 # remove the following lines as functions and input variables are renamed to pep8 style:
     src/pyuvdata/uvdata/uvdata.py: N802
     src/pyuvdata/uvbeam/mwa_beam.py: N802
-    src/pyuvdata/utils.py: N802, N803
-    tests/test_utils.py: D,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 =

.gitignore

@@ -73,7 +73,9 @@ docs/references/_minted*/*.pygtex
 docs/references/_minted*/*.pygstyle
 
 # autogenerated c code
-src/pyuvdata/utils.c
+src/pyuvdata/utils/bls.c
+src/pyuvdata/utils/phasing.c
+src/pyuvdata/utils/coordinates.c
 src/pyuvdata/uvbeam/uvbeam.c
 src/pyuvdata/uvdata/corr_fits.c
 src/pyuvdata/uvdata/src/miriad_wrap.cpp

CHANGELOG.md

@@ -32,6 +32,10 @@ time for each time range or the time_array (if there's a time_array and no time_
 - Added new keyword handling for v.6 of the MIR data format within `MirParser`.
 
 ### Changed
+- Updated minimum optional dependency versions: lunarsky>=0.2.4
+- Restructured `utils.py` into a new submodule `utils` with functions split among
+several submodules. Utility functions used widely are still available from
+pyuvdata.utils, although this access pattern is deprecated for some of them.
 - Modified `UVBeam.interp` to speed up processing when `check_azza_domain=True`.
 - Updated minimum dependencies: setuptools>=64, setuptools_scm>=8.0
 - Restructured to a `src` layout. This should not affect most users, but the

README.md

@@ -157,7 +157,7 @@ Optional:
 * astropy-healpix >= 1.0.2 (for working with beams in HEALPix formats)
 * astroquery >= 0.4.4 (for enabling phasing to ephemeris objects using JPL-Horizons)
 * hdf5plugin >= 3.2.0 (for enabling bitshuffle and other hdf5 compression filters in uvh5 files)
-* lunarsky >=0.2.2 (for working with simulated datasets for lunar telescopes)
+* lunarsky >=0.2.4 (for working with simulated datasets for lunar telescopes)
 * novas and novas_de405 (for using the NOVAS library for astrometry)
 * python-casacore >= 3.5.2 (for working with CASA measurement sets)
 

ci/pyuvdata_min_versions_tests.yml

@@ -23,6 +23,6 @@ dependencies:
   - setuptools_scm==8.0.*
   - pip
   - pip:
-      - lunarsky==0.2.2
+      - lunarsky==0.2.4
       - novas
       - novas_de405

ci/pyuvdata_tests.yml

@@ -23,6 +23,6 @@ dependencies:
   - setuptools_scm>=8.0
   - pip
   - pip:
-      - lunarsky>=0.2.2
+      - lunarsky>=0.2.4
       - novas
       - novas_de405

ci/pyuvdata_tests_mac_arm.yml

@@ -23,4 +23,4 @@ dependencies:
   - setuptools_scm>=8.0
   - pip
   - pip:
-      - lunarsky>=0.2.2
+      - lunarsky>=0.2.4

ci/pyuvdata_tests_windows.yml

@@ -22,4 +22,4 @@ dependencies:
   - setuptools_scm>=8.0
   - pip
   - pip:
-      - lunarsky>=0.2.2
+      - lunarsky>=0.2.4

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,11 @@ 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 Classes
+**************
+
+
 .. autoclass:: pyuvdata.uvdata.fhd.FHD
   :members:
 
@@ -57,12 +65,22 @@ generally do not need to interact with these classes, but developers may need to
 .. autoclass:: pyuvdata.uvdata.uvh5.UVH5
   :members:
 
+
+UVCal Classes
+*************
+
 .. autoclass:: pyuvdata.uvcal.calfits.CALFITS
   :members:
 
+.. autoclass:: pyuvdata.uvcal.calh5.CalH5
+  :members:
+
 .. autoclass:: pyuvdata.uvcal.fhd_cal.FHDCal
   :members:
 
+UVBeam Classes
+**************
+
 .. autoclass:: pyuvdata.uvbeam.beamfits.BeamFITS
   :members:
 
@@ -73,31 +91,43 @@ generally do not need to interact with these classes, but developers may need to
   :members:
 
 
-Mir Parser
-----------
-.. automodule:: pyuvdata.uvdata.mir_parser
-  :members:
+Other Modules and Functions
+---------------------------
 
-.. automodule:: pyuvdata.uvdata.mir_meta_data
-  :members:
+MWA Beam Functions
+******************
+Functions related to constructing the MWA beam from the input files which are in
+a harmonic space.
 
+.. autofunction:: pyuvdata.uvbeam.mwa_beam.P1sin
 
-Functions
-----------
+.. autofunction:: pyuvdata.uvbeam.mwa_beam.P1sin_array
 
-.. autofunction:: pyuvdata.uvdata.fhd.get_fhd_history
 
-.. autofunction:: pyuvdata.uvbeam.mwa_beam.P1sin
+aipy extracts
+*************
 
-.. autofunction:: pyuvdata.uvbeam.mwa_beam.P1sin_array
+.. automodule:: pyuvdata.uvdata.aipy_extracts
+  :members:
 
-.. autofunction:: pyuvdata.uvflag.uvflag.and_rows_cols
 
-.. autofunction:: pyuvdata.uvflag.uvflag.flags2waterfall
+MIR parser
+**********
 
+.. automodule:: pyuvdata.uvdata.mir_parser
+  :members:
 
-aipy extracts
--------------
+MIR metadata
+************
 
-.. automodule:: pyuvdata.uvdata.aipy_extracts
+.. automodule:: pyuvdata.uvdata.mir_meta_data
   :members:
+
+
+UVFlag Functions
+****************
+Flag handling functions.
+
+.. autofunction:: pyuvdata.uvflag.uvflag.and_rows_cols
+
+.. autofunction:: pyuvdata.uvflag.uvflag.flags2waterfall

docs/make_telescope.py

@@ -44,13 +44,6 @@ def write_telescope_rst(write_file=None):
         "`optional`_. The :meth:`pyuvdata.Telescope.check` method can be called\n"
         "on the object to verify that all of the required attributes have been\n"
         "set in a consistent way.\n\n"
-        "Note that angle type attributes also have convenience properties named the\n"
-        "same thing with ``_degrees`` appended through which you can get or set the\n"
-        "value in degrees. Similarly location type attributes (which are given in\n"
-        "geocentric xyz coordinates) have convenience properties named the\n"
-        "same thing with ``_lat_lon_alt`` and ``_lat_lon_alt_degrees`` appended\n"
-        "through which you can get or set the values using latitude, longitude and\n"
-        "altitude values in radians or degrees and meters.\n\n"
     )
     out += "Required\n********\n"
     out += (
@@ -90,7 +83,8 @@ def write_telescope_rst(write_file=None):
         ":class:`astropy.coordinates.EarthLocation` object, which\n"
         "is shown here using the Geodetic representation. Also note that for\n"
         "some telescopes we store csv files giving antenna layout information\n"
-        "which can be used if data files are missing that information.\n\n"
+        "which can be used if data files are missing that information.\n"
+        "We also provide a convenience function to get known telescope locations.\n\n"
     )
 
     known_tel_use = copy.deepcopy(_KNOWN_TELESCOPES)
@@ -104,6 +98,8 @@ def write_telescope_rst(write_file=None):
     json_obj = json_obj[:-1] + " }"
     out += ".. code-block:: JavaScript\n\n {json_str}\n\n".format(json_str=json_obj)
 
+    out += ".. autofunction:: pyuvdata.telescopes.known_telescope_location\n\n"
+
     t = Time.now()
     t.format = "iso"
     t.out_subfmt = "date"

docs/make_uvcal.py

@@ -53,11 +53,6 @@ def write_uvcal_rst(write_file=None):
         "``delay_array``, ``flag_array``, ``quality_array``) are not. The\n"
         ":meth:`pyuvdata.UVCal.check` method will still pass for metadata only\n"
         "objects.\n\n"
-        "Note location type attributes (which are given in topocentric xyz\n"
-        "coordinates) have convenience properties named the same thing with\n"
-        "``_lat_lon_alt`` and ``_lat_lon_alt_degrees`` appended through which you can\n"
-        "get or set the values using latitude, longitude and altitude values in\n"
-        "radians or degrees and meters.\n\n"
     )
     out += "Required\n********\n"
     out += (

docs/make_uvdata.py

@@ -49,13 +49,9 @@ def write_uvdata_rst(write_file=None):
         "``flag_array``, ``nsample_array``) are not. The\n"
         ":meth:`pyuvdata.UVData.check` method will still pass for metadata only\n"
         "objects.\n\n"
-        "Note that angle type attributes also have convenience properties named the\n"
-        "same thing with ``_degrees`` appended through which you can get or set the\n"
-        "value in degrees. Similarly location type attributes (which are given in\n"
-        "geocentric xyz coordinates) have convenience properties named the\n"
-        "same thing with ``_lat_lon_alt`` and ``_lat_lon_alt_degrees`` appended\n"
-        "through which you can get or set the values using latitude, longitude and\n"
-        "altitude values in radians or degrees and meters.\n\n"
+        "Note that angle type attributes also have convenience properties named\n"
+        "the same thing with ``_degrees`` appended through which you can get or\n"
+        "set the value in degrees.\n\n"
     )
     out += "Required\n********\n"
     out += (