# Temporal masking

deterministic probabilistic

The computation of many metrics are based on a time step by time step
evaluation before a temporal summary statistic is calculated across study
period. If metrics are required for several sub-periods in a given study
period, and these sub-periods happen to overlap, computing these metrics on
each sub-period separately could result in computing the same time step by
time step computation several times. To avoid these redundant computations,
`evalhyd`

offers a temporal masking functionality where a mask is applied
on the given study period to generate temporal subsets (i.e. sub-periods).
This way, the time step by time step computations are performed once,
before the temporal summary statistic is performed for each sub-period
including the relevant time steps.

A temporal mask consists in a vector of boolean values of the same length
as the study period where `True`

(or `1`

) values indicate time steps to
include in the temporal subset, and `False`

(or `0`

) values indicate time
steps to exclude in the temporal subset.

To illustrate, let’s look at the simple dataset provided below.

```
time index 0 1 2 3 4 5
observations 351 367 377 378 330 324
predictions 312 335 358 342 327 327
mask True True False True False True
```

In this example, the mask provided will result in only considering the time
steps at indices `0`

, `1`

, `3`

, and `5`

in the observations and in the
predictions for the computation of the desired metrics.

As a result, the two following calls to `evalhyd`

yield the same result:

```
>>> import evalhyd
>>> import numpy as np
>>> (
... evalhyd.evald(
... q_obs=np.array([351, 367, 377, 378, 330, 324]),
... q_prd=np.array([312, 335, 358, 342, 327, 327]),
... metrics=["NSE"],
... t_msk=np.array([[[True, True, False, True, False, True]]])
... )
... == evalhyd.evald(
... q_obs=np.array([351, 367, 378, 324]),
... q_prd=np.array([312, 335, 342, 327]),
... metrics=["NSE"]
... )
... )
True
```

```
> all(
+ evalhyd::evald(
+ q_obs = c(351, 367, 377, 378, 330, 324),
+ q_prd = c(312, 335, 358, 342, 327, 327),
+ metrics = c("NSE"),
+ t_msk = array(c(TRUE, TRUE, FALSE, TRUE, FALSE, TRUE), dim = c(1, 1, 6))
+ )[[1]]
+ == evalhyd::evald(
+ q_obs = c(351, 367, 378, 324),
+ q_prd = c(312, 335, 342, 327),
+ metrics = c("NSE")
+ )[[1]]
+ )
[1] TRUE
```

Tip

If temporal masks cannot be easily generated by the user, conditional masking may be an easier alternative.