t.rast.aggregate.condition - GRASS GIS manual

NAME

t.rast.aggregate.condition - Aggregate multiple space time raster maps into mosaics with the given granualrity, applying a condition for valid data using r.mapcalc.

KEYWORDS

temporal, aggregation, patch, raster, merge, patching, granularity, strds

SYNOPSIS

t.rast.aggregate.condition

t.rast.aggregate.condition --help

t.rast.aggregate.condition [-ein] input=name [where=sql_query] [mask_label=string] mask_value=string condition_label=string aggregation_labels=string[,string,...] output=name [title=string] [description=string] basename=string [offset=integer] [suffix=string] granularity=string [temporal_buffer=string] [temporal_offset=string] [sampling=name[,name,...]] aggregate_condition=string [nprocs=integer] [region_relation=string] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-e: Extend existing STRDS (requires overwrite flag)
-i: Do not process granules that are incomplete (not completely within the temporal extend of the (selected) maps of the input STRDS)
-n: Register Null maps
--overwrite: Allow output files to overwrite existing files
--help: Print usage summary
--verbose: Verbose module output
--quiet: Quiet module output
--ui: Force launching GUI dialog

Parameters:

input=name [required]: Name of the input space time raster dataset
where=sql_query: WHERE conditions of SQL statement without 'where' keyword used in the temporal GIS framework; Example: start_time > '2001-01-01 12:30:00'
mask_label=string: Semantic label of the mask raster maps
mask_value=string [required]: Value of the mask raster maps representing valid data
condition_label=string [required]: Semantic label of the condition raster maps
aggregation_labels=string[,string,...] [required]: One ore more semantic label(s) of raster map(s) to aggregate
output=name [required]: Name of the output space time raster dataset
title=string: Title of the resulting STRDS
description=string: Description of the resulting STRDS
basename=string [required]: Basename for output raster maps
offset=integer: Offset that is used to create the output map ids, output map id is generated as: basename_ (count + offset); Default: 0
suffix=string: Suffix to add at basename: set 'gran' for granularity, 'time' for the full time format, 'num' for numerical suffix with a specific number of digits (default %05); Default: gran
granularity=string [required]: Aggregation granularity, format absolute time "x years, x months, x weeks, x days, x hours, x minutes, x seconds" or an integer value for relative time
temporal_buffer=string: Temporal buffer around the granule of the aggregation, format absolute time "x years, x months, x weeks, x days, x hours, x minutes, x seconds" or an integer value for relative time
temporal_offset=string: Temporal offset applied to the aggregation granularity, format absolute time "x years, x months, x weeks, x days, x hours, x minutes, x seconds" or an integer value for relative time
sampling=name[,name,...]: The method to be used for sampling the input dataset; Options: equal, overlaps, overlapped, starts, started, finishes, finished, during, contains; Default: contains
aggregate_condition=string [required]: Condition used to identify/select values of maps to aggregate (NULL aware method from r.mapcalc); Options: nmax, nmin, nmode
nprocs=integer: Number of threads for parallel computing; Default: 1
region_relation=string: Process only maps with this spatial relation to the current computational region; Options: overlaps, contains, is_contained

DESCRIPTION
EXAMPLE
- Daily mosaic for Sentinel-3 Fractiona Snow Cover
- 5-day moving window mosaic for Sentinel-3 Fractiona Snow Cover
SEE ALSO
AUTHOR

DESCRIPTION

t.rast.aggregate.condition aggregates raster maps within a space time raster dataset (STRDS) using an r.mapcalc expression. It is written oriented on t.rast.aggregate and provides many of the same options, to control naming of the output raster maps, like: basename, offset, suffix

Which and how many maps are aggregated can be controled using the granularity, temporal_buffer, temporal_offset, and sampling options.

The temporal extent of the resulting raster maps is calculated as follows: new_start_time = adjust_datetime_to_granularity(start_time) + temporal_offset - temporal_buffer
new_end_time = adjust_datetime_to_granularity(start_time) + granularity + temporal_offset + temporal_buffer

For example, if granularity is set to "1 day" and the temporal_buffer is set to "1 day", and the temoral_offset 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 temporal_offset 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".

t.rast.aggregate.condition applies a mask (given in mask_label) while selecting values from raster maps with the given aggregation_labels using a condition raster map (given in the condition_label option). For aggregation, those pixels in the aggregation_labels raster maps are selected, where the pixels in the temporally corresponding (=equal) raster maps with the condition_label meet the aggregate_condition.

The module assumes and requires that the input STRDS is equipped with semantic_labels. semantic_labels are used to compile mapcalculator expressions for each ganule (temporal extent) selected for the given granularity.

Per granule, one raster map is produced for the condition_label, aggregated with the aggregate_condition, plus one map for each of the aggregation_labels. Semantic labels for the output raster maps are condition_label_aggregate_condition for the aggregated condition_label maps and aggregation_label for all aggregated maps from the aggregation_labels.

The use case t.rast.aggregate.condition is written for is to be able to aggregate satellite imagery in space and time, where cloudy pixels are excluded and only selected values are propagated to the output maps. A concrete example, is to aggregate Fractional Sow Cover maps from Sentinel-3 where pixels with the lowes solar angle are selected and a cloud mask is applied at the same time.

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 where option. In addition, input maps can be filtered spatialy using the region_relation option.

If the i-flag is set, only granules that are fully within the temporal extent of the (selected) temporal extent of the input 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 temporal_buffer or temporal_offset or a larger granularity are given, the user should make sure that the temporal extent of the STRDS or the raster maps selected by the where-clause or spatial filter cover at least one granule.

The resulting raster maps can also be registered into an existing Space Time Raster Dataset if the e-flag and --overwrite flags are set.

EXAMPLE

Daily mosaic for Sentinel-3 Fractiona Snow Cover

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:

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 \
  condition_label=S3_solar_zenith aggregate_condition=nmin \
  aggregation_labels=S3_SLSTR_fractional_snow_cover \
  granularity="1 day" 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

5-day moving window mosaic for Sentinel-3 Fractiona Snow Cover

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 >granule end time = start of current day + granularity + temporal_buffer + temporal_offset. Start time in the example is 4 days before the start of each time step (day) where the >granule start time = start of current day - temporal_buffer + temporal_offset.

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

AUTHOR

Stefan Blumentrath, NVE

SOURCE CODE

Available at: t.rast.aggregate.condition source code (history)

Accessed: Sunday May 18 20:35:59 2025