From fbd66eb537393ea67b68226a0fcad321dd444d50 Mon Sep 17 00:00:00 2001 From: Aidan Griffiths Date: Thu, 19 Oct 2023 09:32:53 +1100 Subject: [PATCH] docs: rm param types from docstrings --- src/scores/continuous/standard_impl.py | 46 ++++++++++++-------------- src/scores/utils.py | 29 ++++++++-------- 2 files changed, 36 insertions(+), 39 deletions(-) diff --git a/src/scores/continuous/standard_impl.py b/src/scores/continuous/standard_impl.py index aeef93343..f6e6c6549 100644 --- a/src/scores/continuous/standard_impl.py +++ b/src/scores/continuous/standard_impl.py @@ -71,7 +71,7 @@ def rmse( reduce_dims: FlexibleDimensionTypes = None, preserve_dims: FlexibleDimensionTypes = None, weights=None, -): +) -> FlexibleArrayType: """Calculate the Root Mean Squared Error from xarray or pandas objects. A detailed explanation is on [Wikipedia](https://en.wikipedia.org/wiki/Root-mean-square_deviation) @@ -84,13 +84,13 @@ def rmse( Args: - fcst Union[xr.Dataset, xr.DataArray, pd.Dataframe, pd.Series]: Forecast + fcst: Forecast or predicted variables in xarray or pandas. - obs (Union[xr.Dataset, xr.DataArray, pd.Dataframe, pd.Series]): Observed + obs: Observed variables in xarray or pandas. - reduce_dims (Union[str, Iterable[str]): Optionally specify which dimensions to reduce when + reduce_dims: Optionally specify which dimensions to reduce when calculating RMSE. All other dimensions will be preserved. - preserve_dims (Union[str, Iterable[str]): Optionally specify which dimensions to preserve + preserve_dims: Optionally specify which dimensions to preserve when calculating RMSE. 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 @@ -102,7 +102,7 @@ def rmse( area, by latitude, by population, custom) Returns: - Union[xr.Dataset, xr.DataArray, pd.Dataframe, pd.Series]: An object containing + An object containing a single floating point number representing the root mean squared error for the supplied data. All dimensions will be reduced. Otherwise: Returns an object representing the root mean squared error, @@ -122,7 +122,7 @@ def mae( reduce_dims: FlexibleDimensionTypes = None, preserve_dims: FlexibleDimensionTypes = None, weights=None, -): +) -> FlexibleArrayType: """Calculates the mean absolute error from forecast and observed data. A detailed explanation is on [Wikipedia](https://en.wikipedia.org/wiki/Mean_absolute_error) @@ -133,25 +133,23 @@ def mae( Specifying both will result in an exception. Args: - 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 (Union[str, Iterable[str]]): Optionally specify which dimensions - to reduce when calculating MAE. All other dimensions will be preserved. - preserve_dims (Union[str, Iterable[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). + 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). Returns: - Union[xr.Dataset, xr.DataArray, pd.Dataframe, pd.Series]: By default an xarray DataArray containing + 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. diff --git a/src/scores/utils.py b/src/scores/utils.py index 8cd86d5d0..a887cad0e 100644 --- a/src/scores/utils.py +++ b/src/scores/utils.py @@ -44,18 +44,18 @@ def gather_dimensions( obs_dims: Iterable[Hashable], reduce_dims: FlexibleDimensionTypes = None, preserve_dims: FlexibleDimensionTypes = None, -): +) -> Optional[set[Hashable]]: """ Establish which dimensions to reduce when calculating errors but before taking means Args: - fcst_dims (Iterable[str]): Forecast dimensions inputs - obs_dims (Iterable[str]): Observation dimensions inputs. - reduce_dims (Union[str, Iterable[str]]): Dimensions to reduce. - preserve_dims (Union[str, Iterable[str]]): Dimensions to preserve. + fcst_dims: Forecast dimensions inputs + obs_dims: Observation dimensions inputs. + reduce_dims: Dimensions to reduce. + preserve_dims: Dimensions to preserve. Returns: - Tuple[str]: Dimensions based on optional args. + Dimensions based on optional args. Raises: ValueError: When `preserve_dims and `reduce_dims` are both specified. """ @@ -110,15 +110,15 @@ def gather_dimensions( return reduce_dims -def dims_complement(data, dims=None): +def dims_complement(data, dims=None) -> list[str]: """Returns the complement of data.dims and dims Args: - data (Union[xr.Dataset, xr.DataArray]): Input xarray object - dims (Iterable[str]): an Iterable of strings corresponding to dimension names + data: Input xarray object + dims: an Iterable of strings corresponding to dimension names Returns: - List[str]: A sorted list of dimension names, the complement of data.dims and dims + A sorted list of dimension names, the complement of data.dims and dims """ if dims is None: @@ -131,15 +131,15 @@ def dims_complement(data, dims=None): return sorted(list(complement)) -def check_dims(xr_data: XarrayLike, expected_dims: List[str], mode: Optional[str] = None): +def check_dims(xr_data: XarrayLike, expected_dims: list[str], mode: Optional[str] = None): """ Checks the dimensions xr_data with expected_dims, according to `mode`. Args: - xr_data (XarrayLike): if a Dataset is supplied, + xr_data: if a Dataset is supplied, all of its data variables (DataArray objects) are checked. - expected_dims (Iterable[str]): an Iterable of dimension names. - mode (Optional[str]): one of 'equal' (default), 'subset' or 'superset'. + expected_dims: an Iterable of dimension names. + mode: one of 'equal' (default), 'subset' or 'superset'. If 'equal', checks that the data object has the same dimensions as `expected_dims`. If 'subset', checks that the dimensions of the data object is a @@ -163,7 +163,6 @@ def check_dims(xr_data: XarrayLike, expected_dims: List[str], mode: Optional[str ValueError: `expected_dims` cannot be coerced into a set. ValueError: `mode` is not one of 'equal', 'subset', 'superset', 'proper subset', 'proper superset', or 'disjoint' - """ if isinstance(expected_dims, str):