t.rast.aggregate.condition: implement moving window, refactor, ruff

src/temporal/t.rast.aggregate.condition/t.rast.aggregate.condition.html

@@ -9,7 +9,22 @@ <h2>DESCRIPTION</h2>
 
 <p>
 Which and how many maps are aggregated can be controled using the
-<b>granularity</b> and <b>sampling</b> options.
+<b>granularity</b>, <b>temporal_buffer</b>, <b>temporal_offset</b>,
+and <b>sampling</b> options.<p> The temporal extent of the resulting
+raster maps is calculated as follows:
+<em>new_start_time</em> = adjust_datetime_to_granularity(start_time) +
+<em>temporal_offset</em> - <em>temporal_buffer</em><br>
+<em>new_end_time</em> = adjust_datetime_to_granularity(start_time) + 
+<em>granularity</em> + <em>temporal_offset</em> + <em>temporal_buffer</em>
+
+<p>
+For example, if <b>granularity</b> is set to "1 day" and the
+<b>temporal_buffer</b> is set to "1 day", and the <b>temoral_offset</b> is
+not given or 0, the granule for a raster map with the start_time 
+"2024-12-12 13:45" will have a start_time of "2024-12-11 00:00"
+and an end_time of "2024-12-14 00:00". If the <b>temporal_offset</b> is
+set to "-1 day", the start_time will be "2024-12-10 00:00" and the end_time
+will be "2024-12-13 00:00".
 
 <p>
 <em>t.rast.aggregate.condition</em> applies a mask (given in <b>mask_label</b>) while
@@ -22,8 +37,8 @@ <h2>DESCRIPTION</h2>
 <p>
 The module assumes and requires that the input STRDS is equipped with
 <em>semantic_labels</em>. <em>semantic_labels</em> are used to compile
-mapcalculator expressions for each ganule and temporal extent selected
-for the given granule.
+mapcalculator expressions for each ganule (temporal extent) selected
+for the given granularity.
 
 <p>
 Per granule, one raster map is produced for the <b>condition_label</b>,
@@ -44,21 +59,31 @@ <h2>DESCRIPTION</h2>
 <p>
 Both input and output of this module is a single space time raster dataset.
 A subset of the input space time raster dataset can be selected using the
-<b>where</b> option. In addition, input maps can be filtered spatially using
+<b>where</b> option. In addition, input maps can be filtered spatialy using
 the <b>region_relation</b> option.
 
+<p>
+If the <b>i-flag</b> is set, only granules that are fully within the
+temporal extent of the (selected) temporal extent of the <b>input</b>
+STRDS are processed. Granules that start before the temporal extent of
+the input maps or end after the temporal extent of the input maps are
+being skipped. If <b>temporal_buffer</b> or <b>temporal_offset</b> or a larger
+<b>granularity</b> are given, the user should make sure that the temporal
+extent of the STRDS or the raster maps selected by the <b>where</b>-clause
+or spatial filter cover at least one granule.
+
 <p>
 The resulting raster maps can also be registered into an existing
 Space Time Raster Dataset if the <b>e-flag</b> and <b>--overwrite</b> flags
 are set.
 
 
 <h2>EXAMPLE</h2>
-The example uses the North Carolina extra time series of MODIS Land Surface Temperature
-maps (<a href="https://grass.osgeo.org/download/data/">download</a>).
-(The mapset has to be unzip in one of the North Carolina locations.)
-<p>
-Patching the MODIS Land Surface Temperature for 2016 (filling missing pixels by subsequent maps in the time series):
+
+<h3>Daily mosaic for Sentinel-3 Fractiona Snow Cover</h3>
+Patching the Sentinel-3 Fractional Snow Cover (FSC) to daily mosaics, filling missing
+pixels from other maps within the same granule (day), and selecting pixels with the lowest
+solar zenith angle if more FSC maps contain valid values for the same pixel:
 <div class="code"><pre>
 t.rast.aggregate.condition input=Sentinel_3_SLSTR_FSC output=Sentinel_3_SLSTR_FSC_daily \
   --overwrite --verbose -e mask_label=S3_SLSTR_cloud_mask mask_value=0 \
@@ -73,6 +98,31 @@ <h2>EXAMPLE</h2>
 t.info Sentinel_3_SLSTR_FSC
 </pre></div>
 
+<h3>5-day moving window mosaic for Sentinel-3 Fractiona Snow Cover</h3>
+Patching the Sentinel-3 Fractional Snow Cover (FSC) to 5-day mosaics, filling missing
+pixels from other maps within the same granule, and selecting pixels with the lowest
+solar zenith angle if more FSC maps contain valid values for the same pixel. The 
+granule is a 5-day period (granularity + 2 * temporal_buffer), placed as a moving
+window in relation to each time step (granularity) in the SpaceTimeRasterDataset. 
+End time in the example is at the end of each time step (day) where the 
+<em>>granule end time = start of current day + granularity + temporal_buffer +
+temporal_offset</em>. Start time in the example is 4 days before the start of each
+time step (day) where the <em>>granule start time = start of current day -
+temporal_buffer + temporal_offset</em>.
+<div class="code"><pre>
+t.rast.aggregate.condition input=Sentinel_3_SLSTR_FSC output=Sentinel_3_SLSTR_FSC_5days_running \
+  --overwrite --verbose -e -i mask_label=S3_SLSTR_cloud_mask mask_value=0 \
+  condition_label=S3_solar_zenith aggregate_condition=nmin \
+  aggregation_labels=S3_SLSTR_fractional_snow_cover \
+  granularity="1 day" temporal_buffer="2 days" temporal_offset="-2 days" \
+  basename=S3_SLSTR_FSC title="Sentinel-3 SLSTR FSC daily" \
+  description="Daily Fractional Snow Cover measurements from Seninel-3 SLSTR instrument" \
+  region_relation=contains \
+  where="start_time >= '2023-01' and start_time <= '2023-12'" \
+  nprocs=8
+t.info Sentinel_3_SLSTR_FSC
+</pre></div>
+
 <h2>SEE ALSO</h2>
 
 <em>