Provided by: grass-doc_7.6.1-3_all bug

NAME

       t.rast.mapcalc   - Performs spatio-temporal mapcalc expressions on temporally sampled maps
       of space time raster datasets.

KEYWORDS

       temporal, algebra, raster, time

SYNOPSIS

       t.rast.mapcalc
       t.rast.mapcalc --help
       t.rast.mapcalc [-ns]  inputs=name[,name,...]  expression=string   [method=name[,name,...]]
       output=name  basename=basename   [nprocs=integer]    [--overwrite]   [--help]  [--verbose]
       [--quiet]  [--ui]

   Flags:
       -n
           Register Null maps

       -s
           Check the spatial topology of temporally  related  maps  and  process  only  spatially
           related 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:
       inputs=name[,name,...] [required]
           Name of the input space time raster datasets

       expression=string [required]
           Spatio-temporal mapcalc expression

       method=name[,name,...]
           The method to be used for sampling the input dataset
           Options: start, during, overlap, contain, equal, follows, precedes
           Default: equal

       output=name [required]
           Name of the output space time raster dataset

       basename=basename [required]
           Basename for output raster maps
           A  numerical  suffix  separated  by  an underscore will be attached to create a unique
           identifier

       nprocs=integer
           Number of r.mapcalc processes to run in parallel
           Default: 1

DESCRIPTION

       t.rast.mapcalc performs spatio-temporal mapcalc expressions on maps of temporally  sampled
       space  time raster datasets (STRDS). Spatial and temporal operators and internal variables
       are available in  the  expression  string.  The  description  of  the  spatial  operators,
       functions  and  internal variables is available in the r.mapcalc manual page. The temporal
       functions are described in detail below.

       This module expects several parameters. All space time raster datasets that are referenced
       in  the mapcalc expression must be listed in the input option. The first space time raster
       dataset that is listed as input will be used to temporally sample  all  other  space  time
       raster  datasets.  The temporal sampling method can be chosen using the method option. The
       order of the STRDS’s in the mapcalc expression can  be  different  to  the  order  of  the
       STRDS’s  in the input option. The resulting space time raster dataset must be specified in
       the output option together with the basename of generated raster maps that are  registered
       in  the  resulting  STRDS. Empty maps resulting from map-calculation are not registered by
       default. This behavior can be changed with the -n flag. The flag -s can be used to  assure
       that  only  spatially  related  maps in the STRDS’s are processed. Spatially related means
       that temporally related maps overlap in their spatial extent.

       The module t.rast.mapcalc supports parallel processing. The option  nprocs  specifies  the
       number of processes that can be started in parallel.

       A  mapcalc  expression  must  be  provided  to process the temporal sampled maps. Temporal
       internal variables are available in  addition  to  the  r.mapcalc  spatial  operators  and
       functions:

       The supported internal variables for relative and absolute time are:

           ·   td()  -  This  internal  variable  represents  the size of the current sample time
               interval in days and fraction of days for absolute time, and in relative units  in
               case of relative time.

           ·   start_time()  -  This internal variable represents the time difference between the
               start time of the sample space time raster dataset  and  the  start  time  of  the
               current sample interval or instance.  The time is measured in days and fraction of
               days for absolute time, and in relative units in case of relative time.

           ·   end_time() - This internal variable represents the  time  difference  between  the
               start time of the sample space time raster dataset and the end time of the current
               sample interval. The time is measured in days and fraction of  days  for  absolute
               time,  and  in  relative  units  in case of relative time.  The end_time() will be
               represented by null() in case of a time instance.

       The supported internal variables for the current sample interval or instance for  absolute
       time are:

           ·   start_doy() - Day of year (doy) from the start time [1 - 366]

           ·   start_dow() - Day of week (dow) from the start time [1 - 7], the start of the week
               is Monday == 1

           ·   start_year() - The year of the start time [0 - 9999]

           ·   start_month() - The month of the start time [1 - 12]

           ·   start_week() - Week of year of the start time [1 - 54]

           ·   start_day() - Day of month from the start time [1 - 31]

           ·   start_hour() - The hour of the start time [0 - 23]

           ·   start_minute() - The minute of the start time [0 - 59]

           ·   start_second() - The second of the start time [0 - 59]

           ·   end_doy() - Day of year (doy) from the end time [1 - 366]

           ·   end_dow() - Day of week (dow) from the end time [1 - 7], the start of the week  is
               Monday == 1

           ·   end_year() - The year of the end time [0 - 9999]

           ·   end_month() - The month of the end time [1 - 12]

           ·   end_woy() - Week of year (woy) of the end time [1 - 54]

           ·   end_day() - Day of month from the start time [1 - 31]

           ·   end_hour() - The hour of the end time [0 - 23]

           ·   end_minute() - The minute of the end time [0 - 59]

           ·   end_second() - The second of the end time [0 - 59].
       The  end_*  functions  are  represented  by  the  null() internal variable in case of time
       instances.

NOTES

       We will discuss the internal work of t.rast.mapcalc with an example. Imagine we  have  two
       STRDS as input, each one of monthly granularity. The first one A has 6 raster maps (a3 ...
       a8) with a temporal range from March to August. The second STRDS B has 12 raster maps  (b1
       ...  b12)  ranging from January to December. The value of the raster maps is the number of
       the month from their interval start time. Dataset A will be used to sample  dataset  B  to
       create  a  dataset  C.  We want to add all maps with equal time stamps if the month of the
       start time is May or June, otherwise we multiply  the  maps.  The  command  will  look  as
       follows:

       t.rast.mapcalc input=A,B output=C basename=c method=equal \
           expression="if(start_month() == 5 || start_month() == 6, (A + B), (A * B))"

       The resulting raster maps in dataset C can be listed with t.rast.list:

       name    start_time              min     max
       c_1     2001-03-01 00:00:00     9.0     9.0
       c_2     2001-04-01 00:00:00     16.0    16.0
       c_3     2001-05-01 00:00:00     10.0    10.0
       c_4     2001-06-01 00:00:00     12.0    12.0
       c_5     2001-07-01 00:00:00     49.0    49.0
       c_6     2001-08-01 00:00:00     64.0    64.0

       Internally  the  spatio-temporal expression will be analyzed for each time interval of the
       sample dataset A, the temporal functions will be replaced by numerical values,  the  names
       of  the  space time raster datasets will be replaced by the corresponding raster maps. The
       final expression will be passed to r.mapcalc, resulting in 6 runs:

       r.mapcalc expression="c_1 = if(3 == 5 || 3 == 6, (a3 + b3), (a3 * b3))"
       r.mapcalc expression="c_2 = if(4 == 5 || 4 == 6, (a4 + b4), (a4 * b4))"
       r.mapcalc expression="c_3 = if(5 == 5 || 5 == 6, (a5 + b5), (a5 * b5))"
       r.mapcalc expression="c_4 = if(6 == 5 || 6 == 6, (a6 + b6), (a6 * b6))"
       r.mapcalc expression="c_5 = if(7 == 5 || 7 == 6, (a7 + b7), (a7 * b7))"
       r.mapcalc expression="c_6 = if(8 == 5 || 8 == 6, (a8 + b8), (a8 * b8))"

EXAMPLE

       The following command creates a new space time raster dataset  january_under_0  that  will
       set  to  null  all cells with temperature above zero in the January maps while keeping all
       the rest as in the original time series. This  will  change  the  maximum  values  of  all
       January maps in the new STRDS as compared to the original one, tempmean_monthly.
       t.rast.mapcalc input=tempmean_monthly output=january_under_0 basename=january_under_0 \
           expression="if(start_month() == 1 && tempmean_monthly > 0, null(), tempmean_monthly)"
       # print minimum and maximum only for January in the new strds
       t.rast.list january_under_0 columns=name,start_time,min,max | grep 01-01
       name|start_time|min|max
       january_under_0_01|2009-01-01 00:00:00|-3.380823|-7e-06
       january_under_0_13|2010-01-01 00:00:00|-5.266929|-0.000154
       january_under_0_25|2011-01-01 00:00:00|-4.968747|-6.1e-05
       january_under_0_37|2012-01-01 00:00:00|-0.534994|-0.014581
       # print minimum and maximum only for January in the original strds,
       # note that the maximum is different
       t.rast.list tempmean_monthly columns=name,start_time,min,max | grep 01-01
       2009_01_tempmean|2009-01-01 00:00:00|-3.380823|7.426054
       2010_01_tempmean|2010-01-01 00:00:00|-5.266929|5.71131
       2011_01_tempmean|2011-01-01 00:00:00|-4.968747|4.967295
       2012_01_tempmean|2012-01-01 00:00:00|-0.534994|9.69511

SEE ALSO

        r.mapcalc, t.register, t.rast.list, t.info

       Temporal data processing Wiki

AUTHOR

       Sören Gebbert, Thünen Institute of Climate-Smart Agriculture

       Last changed: $Date: 2017-12-01 15:09:57 +0100 (Fri, 01 Dec 2017) $

SOURCE CODE

       Available at: t.rast.mapcalc source code (history)

       Main index | Temporal index | Topics index | Keywords index | Graphical index | Full index

       © 2003-2019 GRASS Development Team, GRASS GIS 7.6.1 Reference Manual