docs: align docstrings with napoleon (google) standards

src/scores/continuous.py

@@ -1,36 +1,48 @@
 """
 This module contains methods which may be used for continuous scoring
 """
+from typing import Tuple, Union
+
+import pandas as pd
+import xarray as xr
 
 import scores.utils
 
+OBS_TYPE = Union[xr.Dataset, xr.DataArray, pd.DataFrame, pd.Series]  # pylint: disable=invalid-name
 
-def mse(fcst, obs, reduce_dims=None, preserve_dims=None, weights=None):
-    """
 
-    Returns:
-      - By default an xarray containing a single floating point number representing the mean absolute
-        error for the supplied data. All dimensions will be reduced.
-      - Otherwise: Returns an xarray representing the mean squared error, reduced along
-      the relevant dimensions and weighted appropriately.
+def mse(
+    fcst: OBS_TYPE, obs: OBS_TYPE, reduce_dims: Tuple[str] = None, preserve_dims: Tuple[str] = None, weights=None
+) -> Union[xr.Dataset, xr.DataArray]:
+    """Calculates the mean squared error from xarray objects
+
+    Dimensional reduction is not supported for pandas and the user should
+    convert their data to xarray to formulate the call to the metric. At
+    most one of reduce_dims and preserve_dims may be specified.
+    Specifying both will result in an exception.
 
     Args:
-      - fcst: Forecast or predicted variables in xarray or pandas
-      - obs: Observed variables in xarray or pandas
-      - reduce_dims: Optionally specify which dimensions to reduce when calculating MSE.
-                     All other dimensions will be preserved.
-      - preserve_dims: Optionally specify which dimensions to preserve when calculating MSE. All other
-                       dimensions will be reduced. As a special case, 'all' will allow all dimensions to
-                       be preserved. In this case, the result will be in the same shape/dimensionality as
-                       the forecast, and the errors will be the squared error at each point (i.e. single-value
-                       comparison against observed), and the forecast and observed dimensions must match
-                       precisely.
-      - weights: Not yet implemented. Allow weighted averaging (e.g. by area, by latitude, by population, custom)
-
-    Notes:
-      - Dimensional reduction is not supported for pandas and the user should convert their data to xarray
-        to formulate the call to the metric.
-      - At most one of reduce_dims and preserve_dims may be specified. Specifying both will result in an exception.
+        fcst: Forecast or predicted variables in xarray or pandas
+        obs: Observed variables in xarray or pandas
+        reduce_dims: Optionally specify which dimensions to reduce when
+            calculating MSE. All other dimensions will be preserved.
+        preserve_dims: Optionally specify which dimensions to preserve
+            when calculating MSE. All other dimensions will be reduced.
+            As a special case, 'all' will allow all dimensions to be
+            preserved. In this case, the result will be in the same
+            shape/dimensionality as the forecast, and the errors will be
+            the squared error at each point (i.e. single-value comparison
+            against observed), and the forecast and observed dimensions
+            must match precisely.
+        weights: Not yet implemented. Allow weighted averaging (e.g. by
+            area, by latitude, by population, custom)
+
+    Returns:
+        Union[xr.Dataset, xr.DataArray, pd.Dataframe, pd.Series]: An object containing
+            a single floating point number representing the mean absolute
+            error for the supplied data. All dimensions will be reduced.
+            Otherwise: Returns an object representing the mean squared error,
+            reduced along the relevant dimensions and weighted appropriately.
     """
 
     error = fcst - obs
@@ -52,39 +64,41 @@ def mse(fcst, obs, reduce_dims=None, preserve_dims=None, weights=None):
     return _mse
 
 
-def mae(fcst, obs, reduce_dims=None, preserve_dims=None, weights=None):
-    """**Needs a 1 liner function description**
+def mae(fcst: OBS_TYPE, obs: OBS_TYPE, reduce_dims: Tuple[str] = None, preserve_dims: Tuple[str] = None, weights=None):
+    """Calculates the mean absolute error from xarray or pandas objects.
+
+    A detailed explanation is on [Wikipedia](https://en.wikipedia.org/wiki/Mean_absolute_error)
+
+    Dimensional reduction is not supported for pandas and the user should
+    convert their data to xarray to formulate the call to the metric.
+    At most one of reduce_dims and preserve_dims may be specified.
+    Specifying both will result in an exception.
+
     Args:
-      - fcst: Forecast or predicted variables in xarray or pandas.
-      - obs: Observed variables in xarray or pandas.
-      - reduce_dims: Optionally specify which dimensions to reduce when
-          calculating MAE. All other dimensions will be preserved.
-      - preserve_dims: Optionally specify which dimensions to preserve
-          when calculating MAE. All other dimensions will be reduced.
-          As a special case, 'all' will allow all dimensions to be
-          preserved. In this case, the result will be in the same
-          shape/dimensionality as the forecast, and the errors will be
-          the absolute error at each point (i.e. single-value comparison
-          against observed), and the forecast and observed dimensions
-          must match precisely.
-      - weights: Not yet implemented. Allow weighted averaging (e.g. by
-          area, by latitude, by population, custom).
+        fcst Union[xr.Dataset, xr.DataArray, pd.Dataframe, pd.Series]: Forecast
+            or predicted variables in xarray or pandas.
+        obs (Union[xr.Dataset, xr.DataArray, pd.Dataframe, pd.Series]): Observed
+            variables in xarray or pandas.
+        reduce_dims (Tuple[str]): Optionally specify which dimensions to reduce when
+            calculating MAE. All other dimensions will be preserved.
+        preserve_dims (Tuple[str]): Optionally specify which dimensions to preserve
+            when calculating MAE. All other dimensions will be reduced.
+            As a special case, 'all' will allow all dimensions to be
+            preserved. In this case, the result will be in the same
+            shape/dimensionality as the forecast, and the errors will be
+            the absolute error at each point (i.e. single-value comparison
+            against observed), and the forecast and observed dimensions
+            must match precisely.
+        weights: Not yet implemented. Allow weighted averaging (e.g. by
+            area, by latitude, by population, custom).
 
     Returns:
-      - By default an xarray DataArray containing a single floating
-        point number representing the mean absolute error for the
+        Union[xr.Dataset, xr.DataArray]: By default an xarray DataArray containing
+        a single floating point number representing the mean absolute error for the
         supplied data. All dimensions will be reduced.
 
-        Alternatively, an xarray structure with dimensions preserved as
-        appropriate containing the score along reduced dimensions
-
-    Notes:
-      - Dimensional reduction is not supported for pandas and the user
-        should convert their data to xarray to formulate the call to the metric.
-      - At most one of reduce_dims and preserve_dims may be specified.
-        Specifying both will result in an exception.
-
-    A detailed explanation is on [Wikipedia](https://en.wikipedia.org/wiki/Mean_absolute_error)
+        Alternatively, an xarray structure with dimensions preserved as appropriate
+        containing the score along reduced dimensions
     """
 
     error = fcst - obs

src/scores/probability/checks.py

@@ -1,36 +1,40 @@
 """
-This module contains methods which make assertions at runtime about the state of various data 
+This module contains methods which make assertions at runtime about the state of various data
 structures and values
 """
+from typing import Union
 
 import numpy as np
 import xarray as xr
 
 
 def coords_increasing(da: xr.DataArray, dim: str):
     """
-    Returns True if coordinates along `dim` dimension of `da` are increasing,
-    False otherwise. No in-built raise if `dim` is not a dimension of `da`.
+    Args:
+        da (xr.DataArray): Input data
+        dim (str): Dimension to check if increasing
+    Returns:
+        (bool): True of False based on if the coordinates along the specified
+        dimension are increasing. No in-built raise if `dim` is not a dimension of `da`.
     """
     result = (da[dim].diff(dim) > 0).all()
     return result
 
 
 def cdf_values_within_bounds(cdf: xr.DataArray) -> bool:
-    """
-    Checks that 0 <= cdf <= 1. Ignores NaNs.
+    """Checks that 0 <= cdf <= 1. Ignores NaNs.
 
     Args:
-        cdf: array of CDF values
+        cdf (xr.DataArray): array of CDF values
 
     Returns:
-        `True` if `cdf` values are all between 0 and 1 whenever values are not NaN,
-        or if all values are NaN; and `False` otherwise.
+        (bool): `True` if `cdf` values are all between 0 and 1 whenever values are not NaN,
+            or if all values are NaN; and `False` otherwise.
     """
     return cdf.count() == 0 or ((cdf.min() >= 0) & (cdf.max() <= 1))
 
 
-def check_nan_decreasing_inputs(cdf, threshold_dim, tolerance):
+def check_nan_decreasing_inputs(cdf: xr.DataArray, threshold_dim: str, tolerance: Union[int, float]):
     """Checks inputs to `nan_decreasing_cdfs` and `_decreasing_cdfs`."""
 
     if threshold_dim not in cdf.dims: