earth2studio.statistics.spread_skill_ratio

class earth2studio.statistics.spread_skill_ratio(ensemble_dimension, reduction_dimensions, ensemble_weights=None, reduction_weights=None, ensemble_batch_update=False, reduction_batch_update=False)

Metric for calculating the spread/skill ratio of an ensemble forecast.

Specifically, the spread is defined as the standard deviation of the ensemble forecast. The skill is defined as the rmse of the ensemble mean prediction. The ratio of these two quantities is defined as the spread/skill ratio.

Parameters:

• ensemble_dimension (str) – The dimension over which the spread and skill are calculated over. This should usually be “ensemble”.

• reduction_dimensions (list[str]) – Dimensions to reduce (mean) the spread/skill ratio over. This is commonly done over time but can also be the globe or some region. Example: [‘time’, ‘lat’, ‘lon’]

• ensemble_weights (torch.Tensor | None, optional) – A one-dimensional tensor containing weights to assign to the ensemble_dimension, by default None.

• reduction_weights (torch.Tensor, optional) – A tensor containing weights to assign to the reduction dimensions. Note that these weights must have the same number of dimensions as passed in reduction_dimensions. Example: if reduction_dimensions = [‘lat’, ‘lon’] then assert weights.ndim == 2. Ignored if None, by default None.

• ensemble_batch_update (bool, optional) – Whether to applying batch updates to the ensemble mean and variance components of the spread and skill with each invocation of __call__. This is particularly useful when ensemble data is recieved in a stream of batches. Each invocation of __call__ will return the running spread/skill ratio., by default False.

• reduction_batch_update (bool, optional) – Whether to applying batch updates to the reduction rmse and averaging components of the spread/skill with each invocation of __call__. This is particularly useful when time data is recieved in a stream of batches., by default False.

__call__(x, x_coords, y, y_coords)

Apply metric to data x and y, checking that their coordinates are broadcastable. While reducing over reduction_dims.

If batch_update was passed True upon metric initialization then this method returns the running sample RMSE over all seen batches.

Parameters:

• x (torch.Tensor) – The ensemble forecast input tensor. This is the tensor over which the ensemble mean and spread are calculated with respect to.

• x_coords (CoordSystem) – Ordered dict representing coordinate system that describes the x tensor. reduction_dimensions must be in coords.

• y (torch.Tensor) – The observation input tensor.

• y_coords (CoordSystem) – Ordered dict representing coordinate system that describes the y tensor. reduction_dimensions must be in coords.

Returns:

Returns root mean squared error tensor with appropriate reduced coordinates.

Return type:

tuple[torch.Tensor, CoordSystem]