Remove average_by argument and add documentation and examples for aggregate_by

Author: leosaffin

huracanpy/tc/_ace.py

@@ -12,18 +12,40 @@
 def ace(
     wind,
     aggregate_by=None,
-    average_by=None,
     threshold=34 * units("knots"),
     wind_units="m s-1",
 ):
-    r"""Calculate accumulate cyclone energy (ACE) for each track
+    r"""Calculate accumulate cyclone energy (ACE)
 
     .. math:: \mathrm{ACE} = 10^{-4} \sum v_\mathrm{max}^2 \quad (v_\mathrm{max} \ge 34 \mathrm{kn})
 
+    By default, this function will return the "ACE" for each individual point in `wind`.
+    To calculate more useful quantities of ACE, use the `aggregate_by` keyword.
+
+    For example, to calculate the ACE of each individual track, doing
+
+    >>> ace_by_track = huracanpy.tc.ace(tracks.wind, aggregate_by=tracks.track_id)
+
+    will return a DataArray with track_id as a coordinate and the sum of ACE for each
+    track as the data. Note that this is equivalent to using groupby:
+
+    >>> ace_by_point = huracanpy.tc.ace(tracks.wind)
+    >>> ace_by_track = ace_by_point.groupby(tracks.track_id).sum()
+
+    To calculate the average ACE by track, you can do
+
+    >>> ace_by_track_mean = ace_by_track.mean()
+
+    Similarly to calculate a climatological mean ACE by year, run
+
+    >>> climatological_ace = huracanpy.tc.ace(tracks.wind, aggregate_by=tracks.time.dt.year).mean()
+
     Parameters
     ----------
     wind : array_like
         Maximum velocity of a tropical cyclone associated with the tracks dataset
+    aggregate_by : array_like
+        Variable to take the sum of ACE values across. Must have the same length as wind
     threshold : scalar, default=34 knots
         ACE is set to zero below this threshold wind speed. The default argument is in
         knots. To pass an argument with units, use :py:mod:`metpy.units`, otherwise any
@@ -45,9 +67,6 @@ def ace(
     if aggregate_by is not None:
         ace_values = ace_values.groupby(aggregate_by).sum()
 
-    if average_by is not None:
-        ace_values = ace_values.groupby(average_by).sum().mean()
-
     return ace_values
 
 
@@ -56,7 +75,6 @@ def pace(
     wind=None,
     model=None,
     aggregate_by=None,
-    average_by=None,
     threshold_wind=None,
     threshold_pressure=None,
     wind_units="m s-1",
@@ -90,6 +108,9 @@ def pace(
     pressure : array_like
     wind : array_like, optional
     model : str, class, or object, optional
+    aggregate_by : array_like
+        Variable to take the sum of PACE values across. Must have the same length as
+        pressure/wind. For examples, see the documentation for `huracanpy.tc.ace`
     threshold_wind : scalar, optional
     threshold_pressure : scalar, optional
     wind_units : str, default="m s-1"
@@ -115,9 +136,6 @@ def pace(
     if aggregate_by is not None:
         pace_values = pace_values.groupby(aggregate_by).sum()
 
-    if average_by is not None:
-        pace_values = pace_values.groupby(average_by).sum().mean()
-
     return pace_values, model