Support multiple spws in UVData.frequency_average

.circleci/config.yml

@@ -114,7 +114,7 @@ jobs:
           command: |
             source ./ci/_activate_current_env.sh
             cd docs
-            python -m pytest -n 2 --doctest-glob="*.rst" -W "error::DeprecationWarning"
+            python -m pytest -n auto --doctest-glob="*.rst" -W "error::DeprecationWarning"
             cd ..
       - save_cache:
           key: deps-{{ .Branch }}-{{ checksum "ci/pyuvdata_tests.yml" }}

CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this project will be documented in this file.
 ## [Unreleased]
 
 ### Added
+- Support for multiple spectral windows in `UVData.frequency_average`, including a new
+parameter `respect_spws` for controlling whether averaging crosses spectral window
+boundaries.
+- Better handling in `UVData.frequency_average` when averaging by a number of channels
+that does not divide evenly into the number of channels in each spectral window.
 - Compatibility with Python 3.11
 
 ### Changed
@@ -20,7 +25,8 @@ All notable changes to this project will be documented in this file.
 methods that mostly wrap other methods.
 - A new `UVCal.new()` method (based on new function `new_uvcal`) that creates a new,
 self-consistent `UVCal` object from scratch from a set of flexible input parameters.
-- A new `UVData.new()` method (based on new function `new_uvdata`) that creates a new, self-consistent `UVData` object from scratch from a set of flexible input parameters.
+- A new `UVData.new()` method (based on new function `new_uvdata`) that creates a new,
+self-consistent `UVData` object from scratch from a set of flexible input parameters.
 - A new `fast_concat` method on `UVCal`.
 - A new generic `read` method on `UVCal` that, like the `read` methods on our other
 objects, supports all file types and a new `from_file` class method to allow one-line

docs/uvdata_tutorial.rst

@@ -768,6 +768,12 @@ c) Resampling a BDA dataset in time
 
 d) Averaging in frequency
 *************************
+The :meth:`pyuvdata.UVData.frequency_average` method takes a number of channels to
+average together. Use the `keep_ragged` parameter to control the handling if the
+number of frequencies in each spectral window does not divide evenly by the number of
+channels to be averaged together. Use the `respect_spws` parameter to control whether
+averaging will be done over spectral window boundaries.
+
 .. code-block:: python
 
   >>> import os
@@ -780,7 +786,7 @@ d) Averaging in frequency
   Channel width:  [122070.3125 122070.3125 122070.3125 122070.3125]
 
   >>> # Average by a factor of 2 in frequency
-  >>> uvd.frequency_average(2)
+  >>> uvd.frequency_average(n_chan_to_avg=2, keep_ragged=True)
   >>> print("Channel width after frequency averaging: ", uvd.channel_width)
   Channel width after frequency averaging:  [244140.625 244140.625]
 
@@ -789,8 +795,7 @@ UVData: Plotting
 Making a simple waterfall plot.
 
 Note: there is now support for reading in only part of a uvfits, uvh5 or miriad file
-(see :ref:`large_files`), so you need not read in the
-entire file to plot one waterfall.
+(see :ref:`large_files`), so you need not read in the entire file to plot one waterfall.
 
 .. code-block:: python
 
@@ -802,7 +807,6 @@ entire file to plot one waterfall.
   >>> filename = os.path.join(DATA_PATH, 'day2_TDEM0003_10s_norx_1src_1spw.uvfits')
   >>> uvd = UVData.from_file(filename, use_future_array_shapes=True)
 
-  >>> # Note that the length of the array along axis=1 is always 1.
   >>> print(uvd.data_array.shape)
   (1360, 64, 4)
   >>> print(uvd.Ntimes)

pyuvdata/utils.py

@@ -544,20 +544,16 @@ def _check_freq_spacing(
                 chanwidth_error = True
     if raise_errors and spacing_error:
         raise ValueError(
-            "The frequencies are not evenly spaced (probably "
-            "because of a select operation) or has differing "
-            "values of channel widths. Some file formats "
-            "(e.g. uvfits, miriad) and methods (frequency_average) "
-            "do not support unevenly spaced frequencies."
+            "The frequencies are not evenly spaced (probably because of a select "
+            "operation) or has differing values of channel widths. Some file formats "
+            "(e.g. uvfits, miriad) do not support unevenly spaced frequencies."
         )
     if raise_errors and chanwidth_error:
         raise ValueError(
-            "The frequencies are separated by more than their "
-            "channel width (probably because of a select operation). "
-            "Some file formats (e.g. uvfits, miriad) and "
-            "methods (frequency_average) do not support "
-            "frequencies that are spaced by more than their "
-            "channel width."
+            "The frequencies are separated by more than their channel width (probably "
+            "because of a select operation). Some file formats (e.g. uvfits, miriad) "
+            "do not support frequencies that are spaced by more than their channel "
+            "width."
         )
 
     return spacing_error, chanwidth_error