Add temporal resampling

CHANGES.md

@@ -1,3 +1,8 @@
+## Changes in 1.1.0 (under development)
+
+- Added `resample_in_time` for temporal resampling of 3d dataset.
+
+
 ## Changes in 1.0.0
 
 - Added algorithm for **affine transformation**.

docs/api.md

@@ -3,6 +3,7 @@
 ::: xcube_resampling.affine_transform_dataset
 ::: xcube_resampling.reproject_dataset
 ::: xcube_resampling.rectify_dataset
+::: xcube_resampling.resample_in_time
 ::: xcube_resampling.utils
 ::: xcube_resampling.gridmapping.GridMapping
 ::: xcube_resampling.constants

docs/guide.md

@@ -267,6 +267,32 @@ where *V1*, *V2*, *V3*, *V4* are the pixel values of the points in the source da
 
 ---
 
+### Temporal Resampling
+
+The function [`resample_in_time`](api.md/#xcube_resampling.resample_in_time)
+allows resampling of a dataset along its **time axis**. Under the hood, it applies
+[`xarray.DataArray.resample`](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.resample.html)
+to each data variable that includes a time dimension. A valid time coordinate must
+be present in the dataset.
+
+#### Frequency and Mode Selection
+
+The argument `frequency` specifies the **target temporal frequency**, following the
+same conventions as the `freq` argument in [`xarray.groupers.TimeResampler`](https://docs.xarray.dev/en/stable/generated/xarray.groupers.TimeResampler.html).
+
+The function automatically compares the target frequency with the dataset’s native
+temporal resolution and determines whether to perform:
+
+- **Aggregation** (downsampling), or
+- **Interpolation** (upsampling)
+
+unless specific `interp_methods` or `agg_methods` are provided by the user.
+
+If the dataset shows **high temporal irregularity** — defined as a **coefficient of
+variation (CV = std/mean)** greater than 5% — the user
+must explicitly specify either `interp_methods` or `agg_methods`, since the function
+cannot reliably infer the appropriate mode.
+
 #### Interpolation
 
 When interpolation is required,

docs/index.md

@@ -53,6 +53,14 @@ criteria below.
 With `resample_in_space`, users do **not** need to worry about selecting the right
 algorithm—the function determines and applies it automatically.
 
+### `resample_in_time` — the gateway to Temporal Resampling of Gridded datasets
+
+The **central function** for resampling in the temporal domain is
+[`resample_in_time`](api.md/#xcube_resampling.resample_in_time) which handles both up
+and downsampling of a dataset in the `time` dimension.
+
+👉 For usage examples and details, see the [User Guide](guide.md).
+
 
 ## License