GRASS-Wiki - User contributions [en]

PostGIS

2017-01-23T03:12:36Z

⚠️Matmar: \*output=PG:dbname=pgis_nc*\

When accessing [http://www.postgis.net PostGIS] data in GRASS you can
* [[#Import into GRASS|import]] PostGIS (simple features) data into GRASS topological format or,
* [[#Link to GRASS|link]] PostGIS data as GRASS vector maps

See also [[Working with external data in GRASS 7|working with external data in GRASS 7]].
__TOC__
== Help pages ==

* {{cmd|vectorintro|desc=Vector data processing in GRASS GIS}} help page
* {{cmd|databaseintro|desc=Database management in GRASS GIS}} help page
* {{cmd|sql|desc=SQL support in GRASS GIS}} help page

* {{cmd|grass-pg|desc=PostgreSQL DB driver in GRASS}} help page
* {{cmd|grass-odbc|desc=ODBC DB driver in GRASS}} help page

== Import into GRASS ==

# {{cmd|v.in.ogr}} - imports geometry data from PostGIS into native GRASS vector format, attributes are stored using default DB settings (see {{cmd|db.connect}} for details)
# {{cmd|v.clean}} - clean up data after import

''Note 1:'' There is a fundamental difference between the PostGIS format which is
non-topological (OGC simple feature-based) and the internal GRASS format which is topological and
which, thus, does not really allow for overlapping polygons. You can
digitize them, but they are not really useful...

''Note 2:'' GRASS 7 allows also reading and writing topological PostGIS data (see [http://www.postgis.org/documentation/manual-2.0/Topology.html PostGIS Topology] for details).

{{YouTube|JoqIkL2VRVc|desc=Importing PostGIS layers into GRASS}}

== Link to GRASS ==

* input maps: {{cmd|v.external}}
**GRASS 7 supports also write access to the map links, see [[Working with external data in GRASS 7#Vector data|working with external data in GRASS 7]] for details
* output maps: {{cmd|v.external.out}}

You can register a PostGIS table in GRASS using {{cmd|v.external}}. The command below creates a link to the table 'lakes' located in database 'pgis_nc'.

# list available PG tables
v.external input="PG:host=myserver user= myuser dbname=pgis_nc" -l

# link PG table into GRASS GIS as vector map
v.external input="PG:host=myserver user= myuser dbname=pgis_nc" layer=lakes

The command creates in the current mapset new vector map 'lakes', the module also builds pseudo-topology for this map,

To link a PostGIS table from non-public schema

v.external input=PG:<connection sting> layer=<schema>.<layer> output=<layer>

''Important note:'' In GRASS 6 the created links area ''read-only''. GRASS 7 also allows to modify linked layers directly via OGR or PostGIS data provider, see [[Working with external data in GRASS 7#Vector data|working with external data in GRASS 7]] for details.

{{YouTube|eB3_SmE3E9Q|desc=Link PostGIS layers as GRASS vector maps}}

== Export to PostGIS ==

To export GRASS vector map layer as PostGIS table use {{cmd|v.out.ogr}}, eg.

v.out.ogr in=lakes@PERMANENT output=PG:dbname=pgis_nc format=PostgreSQL type=area

In GRASS 7 exists also specialized module {{cmd|v.out.postgis}} which allows to export GRASS vector data as simple features (similarly to {{cmd|v.out.ogr}}) or in topological format (see [[PostGIS Topology]] for defails).

Note that exporting data can be quite time-consuming task, especially when input vector map attributes are stored in DBF format. It's recommended to store attribute data in {{cmd|grass-sqlite|desc=SQLite format}} rather then in old-fashioned {{cmd|grass-dbf|desc=DBF format}}.

{{YouTube|DTMmmcVpJKk|desc=Creating model which exports all GRASS vector maps from given mapset to PostGIS database}}
{{YouTube|uStN3F6ZZoc|desc=Creating model which exports all GRASS vector maps from given mapset to PostGIS database (including schema)

1) create schema with name of input mapset

2) copy vector maps from selected mapset to the current and stores their attributes in SQLite database

3) exports GRASS vector maps to the selected PostGIS database
}}

See also [[wxGUI Graphical Modeler]].

== Direct access to PostGIS data (GRASS 7 only) ==

''Important note:'' Direct read/write access is available only in GRASS 7.

=== Direct read access ===

GRASS 7 allows to access PostGIS data directly via virtual mapset called 'OGR'. In this case parameter <tt>map</tt> or <tt>input</tt> is used for OGR data source and <tt>layer</tt> for table. In the command bellow is accessed PostGIS table 'lakes' from database 'pgis_nc'.

v.info map=PG:dbname=pgis_nc@OGR layer=lakes

To access table from non-public schema (or schemas which are not in the search path), type

<pre>
v.info map=PG:<OGR data source> layer=<schema>.<table>
</pre>

When accessing external data directly you don't need to create a map link by {{cmd|v.external}}. The major drawback of direct read access is that the pseudo-topology is built each time when accessing the data. From this point of view the direct access is useful when accessing data once or few times, otherwise is better to link the data by {{cmd|v.external}}.

=== Direct write access ===

GRASS 7 allows to write output vector map directly via OGR library. For defining output vector data format is designed {{cmd|v.external.out}} module. For example

v.external.out input=PG:dbname=pgis_nc format=PostgreSQL

causes that output vector data are written in PostGIS format in the database 'pgis_nc'. GRASS also creates automatically for every PostGIS table a new vector map in the current mapset as the link to the PostGIS table.

PostGIS data can be accessed by the map link or directly as described in the section above. For example

v.extract input=lakes out=reservoir where="FTYPE = 'RESERVOIR'"

v.info map=reservoir
# or
v.info map=PG:dbname=pgis_nc@OGR layer=reservoir

To switch back to GRASS native format enter

v.external.out -r

== See also ==

* [[Working with external data in GRASS 7]]
* [[PostGIS Topology]]

== External links ==

* [http://www.surfaces.co.il/?p=645 Tutorial by Micha Silver]
* [http://www.postgis.org PostGIS]
* [http://gdal.org/ogr OGR library]
* [http://www.dimensionaledge.com/main/postgis/viewshed-analysis-in-postgis-using-plr-and-grass/ Viewshed analysis in PostGIS using PL/R and GRASS] (blog post by Mark Wynter)
* [https://strk.kbt.io/projects/rttopo/ RT Topology Library]

[[Category: FAQ]]
[[Category: Vector]]

GRASS GIS Standardized Sample Datasets

2015-10-13T08:48:35Z

⚠️Matmar: ulr updated

{{ToModify}}

See {{twiki|SampleDataset|Trac wiki page}} for the development of the dataset.

== List of datasets ==

'''Already published:'''
* [http://grass.osgeo.org/download/sample-data/ North Carolina GRASS Sample Location] (2007, map names partially standardized, content partially standardized, currently used dataset, to be deprecated)
* [http://geodati.fmach.it/gfoss_geodata/libro_gfoss/ Piemonte, Italy] (2012, map names not standardized, content not standardized, work in progress, see below)
* Spearfish, USA (to be phased out, 1986)

'''Planning - Future standardized datasets'''
* [http://trac.osgeo.org/grass/wiki/SampleDataset GRASS GIS North Carolina USA Sample Dataset] (reference for other datasets, under development)
* [http://trac.osgeo.org/grass/wiki/SampleDataset/Italy/Piemont GRASS GIS Piemonte Italy Sample Dataset]
* [http://trac.osgeo.org/grass/wiki/SampleDataset/World GRASS GIS World Sample Dataset]

== Examples ==

=== Computing slope and aspect ===

Compute slope, aspect and profile curvature of the terrain:

g.region raster=elevation
r.slope.aspect elevation=elevation slope=slope aspect=aspect pcurvature=profile_curvature



[[File:std_dataset_nc_stripe.png|thumb|North Carolina (USA) dataset|700px]]
[[File:std_dataset_it_stripe.png|thumb|Piemonte (Italy) dataset|700px]]
[[File:std_dataset_pr_stripe.png|thumb|Puerto Rico dataset|700px]]
[[File:std_dataset_cz_stripe.png|thumb|Czech Republic dataset|700px]]

=== Visualizing shaded relief ===

Visualize digital elevation model with shaded relief:

g.region raster=elevation
r.relief input=elevation output=shade
d.shade shade=shade color=elevation

<gallery mode=packed>
File:std_dataset_nc_shaded_elevation.png|North Carolina, USA
File:std_dataset_piemonte_shaded_elevation.png|Piemonte, Italy
</gallery>

== Where are the datasets used ==

* [http://grass.osgeo.org/grass70/manuals/ GRASS GIS manual] (currently using original, not fully compliant North Carolina GRASS Sample Location)
* [http://courses.ncsu.edu/gis582/common/ NCSU Geospatial Modeling and Analysis course] and other [http://geospatial.ncsu.edu/osgeorel/courses.html NCSU OSGeoREL courses] (currently using original, not fully compliant North Carolina GRASS Sample Location)

== Tools to help with managing a dataset ==

* [http://grass.osgeo.org/grass70/manuals/g.rename.html g.rename] for changing names of individual raster and vector maps
* [http://grass.osgeo.org/grass70/manuals/addons/g.rename.many.html g.rename.many] for renaming large amount of maps (to standard names or to/from different language)
* [http://grass.osgeo.org/grass70/manuals/addons/r.in.proj.html r.in.proj] and [http://grass.osgeo.org/grass70/manuals/addons/v.in.proj.html v.in.proj] for importing data with different coordinate system
* Python script [https://trac.osgeo.org/grass/browser/grass-addons/tools/std_dataset_display.py std_dataset_display.py] for generating some maps and images

== Contact ==

If you are interested in producing a dataset for your region, please contact [https://lists.osgeo.org/mailman/listinfo/grass-user grass-user] mailing list or [[User:Wenzeslaus|Vaclav Petras]].

Temporal data processing

2015-04-15T19:17:11Z

⚠️Matmar: cla==cla_test

== Introduction ==

TGRASS is the temporal enabled GRASS GIS. It is available from [http://grass.osgeo.org/grass7/ GRASS GIS 7] onwards.
TGRASS is completely metadata based, and managing temporal and spatial extent including temporal topology.

== Terminology Overview ==

* Space time raster datasets (strds) are designed to manage raster map time series. Modules that process strds have the naming prefix ''t.rast''.
* Space time 3D raster datasets (str3ds) are designed to manage 3D raster map time series. Modules that process str3ds have the naming prefix ''t.rast3d''.
* Space time vector datasets (stvds) are designed to manage vector map time series. Modules that process stvds have the naming prefix ''t.vect''.

== Example workflow for a Chlorophyll-a MODIS time series ==

The following examples are based on a series of MODIS L3 Chlorophyll-a product that is freely available at the [http://oceancolor.gsfc.nasa.gov/cgi/l3?sen=A&per=MO&prd=CHL_chlor_a ocean color] site. So, say we download the SMI 8-day composite product at 4.6 km resolution for the period 2003-2013. That is a 506 set of images, 46 per year. Data comes as compressed HDF4 files. Chlorophyll products filenames look like this:

A20030012003008.L3m_8D_CHL_chlor_a_4km

A: MODIS/Aqua
2003: Year at start
001: Julian day at start
2003: Year at end
008: Julian day at end
L3m: Level 3 data, mapped (Projection: Plate carrée)
8D: 8 day composition
CHL: Chlorophyll a concentration product
chlor_a: algorithm used 10^(a0 + a1*X + a2*X^2 + a3*X^3 + a4*X^4)
4km: 4.6km pixel size (8640x4320 image, 2.5 minute resolution)

We now decompress files and check metadata

<source lang="bash">
# Go to where the data is and decompress
find -iname '*.bz2' -exec bzip2 -d {} \;
# Check file meta-data (GDAL utilities)
gdalinfo A20030012003008.L3m_8D_CHL_chlor_a_4km
</source>

Next step is to import all 506 images into GRASS. You can use r.in.gdal or r.external for that.
Note that global Cl-a images as downloaded from [http://oceancolor.gsfc.nasa.gov/cgi/l3?sen=A&per=MO&prd=CHL_chlor_a ocean color] site are ~150 mb each (disk space issues!). Here, 3 different options:

* import global images (506 images, 150 Mb each) with r.in.gdal, resize to study area and remove global files
* set projection and extension, and resize to study area with gdal_translate, and import already resized images with r.in.gdal
* import global images (506 images, 150 Mb each) with r.external, resize to study area and remove global files, as showed next:

<source lang="bash">
# define region extension
g.region -p n=-38 s=-55 w=-70 e=-56

suffix=_tmp
for map in *chlor*; do
r.external input=$map output=${map}${suffix} -o ;
r.mapcalc expression="$map=${map}${suffix}" ;
g.remove rast=${map}${suffix} ;
done
</source>

=== Time series processing ===

Once we have maps inside GRASS we can start the temporal processing. If this is the first time you'll use temporal modules,
you need to run

<source lang="bash">
t.connect -d
</source>

to set the default temporal GIS database connection for the current mapset. The default TGIS database of type sqlite3
is located in the PERMANENT mapset directory. Temporal GIS content from all created mapsets will be stored there.

=== 1. Creating a STRDS and registering maps ===

First step is to create a space time dataset by means of [http://grass.osgeo.org/grass71/manuals/t.create.html t.create]. Let us create a strds for the Chlorophyll-a (Cl-a) time series. We need to define the type (raster, 3D raster or vector), if the time is absolute or relative and, the name of the space time dataset.

<source lang="bash">
t.create type=strds temporaltype=absolute output=cla_test title="Chlorophyll-a concentration" \
description="MODIS L3 Chlorophyll-a concentration for Argentinian sea"
</source>

Then, we register our 506 raster maps in the strds using [http://grass.osgeo.org/grass71/manuals/t.register.html t.register]. This module assigns time stamps to raster, 3D raster and vector maps and register them into space time datasets. Existing timestamps can be read and used by t.register.

This module supports absolute and relative time. Maps can be registered by command line argument (a list of comma separated map names) or using an input file. The start time, end time and a temporal increment can be provided by command line or in the input file. End time and increment are mutual exclusive. Maps can be registered in several space time datasets using the same timestamp.

Start time and end time with absolute time must be provided using the format yyyy-mm-dd HH:MM:SS +HHMM. It is also supported to specify the date yyyy-mm-dd only. In case of relative time the temporal unit (years, months, days, hours, minutes or seconds) must be provided. The relative start time, end time and the increment are integers.

<source lang="bash">
t.register -i type=rast input=cla_test maps=`g.list rast pat=*_chlor_* sep=,`\
start="2003-01-01" increment="8 days"
</source>

This would have been the simplest solution, but 8-day products have a problem, the last image of each year is not a product of an 8-day composition, but 4 or 5-day. Then, when using the increment parameter, dates are not set properly.
The solution was to create a list of maps, with their respective start and end date. As the filenames contain information regarding year and DOY (day of year), we can use the following Python script to read filenames and transform DOY to calendar dates (Thanks Soeren!).

<source lang="python">
# in python
from os import walk
f = []
for (dirpath, dirnames, filenames) in walk("/path/to/the/maps"):
f.extend(filenames)
break
# to order the list
f.sort()

input_list=[]

import datetime
for map_name in f:
start_year = int(map_name[1:5])
start_day = int(map_name[5:8])
end_year = int(map_name[8:12])
end_day = int(map_name[12:15])
start = datetime.datetime(start_year, 1, 1) + datetime.timedelta(start_day - 1)
end = datetime.datetime(int(end_year), 1, 1) + datetime.timedelta(end_day)
map_list = map_name + '|' + str(start) + '|' + str(end)
print map_list
input_list.append(map_list)

print input_list

txt = '\n' .join(input_list)
f = open("input_list_cla.txt","w")
f.write(txt)
f.close()
</source>

Using the number of characters in the filenames and datetime library in Python, you can convert DOY in the filenames into start_time and end_time as in the list you need to pass to t.register. The resulting list looks like this:

A20030012003008.L3m_8D_CHL_chlor_a_4km_arg|2003-01-01 00:00:00|2003-01-09 00:00:00
A20030092003016.L3m_8D_CHL_chlor_a_4km_arg|2003-01-09 00:00:00|2003-01-17 00:00:00
A20030172003024.L3m_8D_CHL_chlor_a_4km_arg|2003-01-17 00:00:00|2003-01-25 00:00:00
...
A20133452013352.L3m_8D_CHL_chlor_a_4km_arg|2013-12-11 00:00:00|2013-12-19 00:00:00
A20133532013360.L3m_8D_CHL_chlor_a_4km_arg|2013-12-19 00:00:00|2013-12-27 00:00:00
A20133612013365.L3m_8D_CHL_chlor_a_4km_arg|2013-12-27 00:00:00|2014-01-01 00:00:00

and then, the command would be:

<source lang="bash">
t.register --o type=rast input=cla file=input_list_cla.txt
</source>

We can also set a color palette for all maps in the strds with:

<source lang="bash">
t.rast.colors input=cla color=name_of_color_table
</source>

=== 2. Getting some basic info and statistics ===

We now check the space time data sets we have in our mapset with:

<source lang="bash">
t.list type=strds
</source>

and list information about our recently created strds. See [http://grass.osgeo.org/grass71/manuals/t.info.html t.info] for additional uses.

<source lang="bash">
t.info type=strds input=cla
</source>

+-------------------- Space Time Raster Dataset -----------------------------+
| |
+-------------------- Basic information -------------------------------------+
| Id: ........................ cla@clorofila
| Name: ...................... cla
| Mapset: .................... clorofila
| Creator: ................... veroandreo
| Temporal type: ............. absolute
| Creation time: ............. 2014-04-29 14:23:00.579342
| Modification time:.......... 2014-05-12 09:15:08.917309
| Semantic type:.............. mean
+-------------------- Absolute time -----------------------------------------+
| Start time:................. 2003-01-01 00:00:00
| End time:................... 2014-01-01 00:00:00
| Granularity:................ 1 day
| Temporal type of maps:...... interval
+-------------------- Spatial extent ----------------------------------------+
| North:...................... -38.0
| South:...................... -55.0
| East:.. .................... -55.0
| West:....................... -70.0
| Top:........................ 0.0
| Bottom:..................... 0.0
+-------------------- Metadata information ----------------------------------+
| Raster register table:...... raster_map_register_91ba57d5f0924f4fa0bd7176a1b39b2f
| North-South resolution min:. 0.041667
| North-South resolution max:. 0.041667
| East-west resolution min:... 0.041667
| East-west resolution max:... 0.041667
| Minimum value min:.......... 0.02925
| Minimum value max:.......... 0.26472
| Maximum value min:.......... 5.2104
| Maximum value max:.......... 99.953934
| Aggregation type:........... None
| Number of registered maps:.. 506
|
| Title:
| Chlorophyll-a
| Description:
| Concentracion de Clorofila a
| Command history:
| # 2014-04-29 14:23:00
| t.create type="strds" temporaltype="absolute"
| output="cla" title="Chlorophyll-a"
| description="Concentracion de Clorofila a" --o
| # 2014-04-29 14:23:23
| t.register --o type="rast" input="cla"
| file="map_list"
|
+----------------------------------------------------------------------------+

Now, we get univariate statistics from the non-null cells for each registered raster map of the strds. For that matter we use [http://grass.osgeo.org/grass71/manuals/t.rast.univar.html t.rast.univar] which, by default, returns the name of the map, the start and end date of dataset and the following values: mean, minimum and maximum vale, mean_of_abs, standard deviation, variance, coeff_var, number of null cells, total number of cell.

<source lang="bash">
t.rast.univar input=cla
</source>

In Linux-based systems you can send the output to a text file using

<source lang="bash">
t.rast.univar input=cla > stats_cla
</source>

=== 3. Listing maps and selections ===

The module [http://grass.osgeo.org/grass71/manuals/t.rast.list.html t.rast.list] allows you to list registered maps of a strds and provides several options to achieve what you want. For example, you can select different granules and also perform different queries by means of the where parameter. Some examples are:

<source lang="bash">
t.rast.list input=cla method=gran granule="1 month"
# this will give one image every one month, 3 months, 1 year, or whatever granule you choose

t.rast.list input=cla order=min columns=id,name,start_time,min where="min <= '0.05'"
# this will order by minimum value all the maps in the strds that have a minimum value lower than or equal to 0.05

t.rast.list input=cla order=max columns=name,start_time,max where="max > '10.0'"
# maps ordered by maximum value in which maximum value is higher than 10.

t.rast.list input=cla where="start_time >= '2003-01' and start_time <= '2003-06'"
# all the maps in the first 6 month of the time series
</source>

In the where parameter you can use sql datetime functions. Then, to get for example, all maps which start date is in January, we can do:

<source lang="bash">
t.rast.list input=cla where="strftime('%m', start_time)='01'"

# or

t.rast.list input=cla \
where='start_time >= datetime(start_time, "start of year") and start_time <= datetime(start_time, "start of year", "1 month")'
</source>

If you have monthly (instead of 8-day products) data and you want to list all January maps, then you can do:

<source lang="bash">
t.rast.list input=cla_orig where="start_time=datetime(start_time, 'start of year', ' 0 month')"
</source>

=== 4. Visualization ===

There are different visualization options for strds.

* [http://grass.osgeo.org/grass71/manuals/g.gui.timeline.html g.gui.timeline] allows to compare temporal datasets by displaying their temporal extents in a plot.

<source lang="bash">
# only temporal extent
g.gui.timeline inputs=cla
# temporal and spatio-temporal extent
g.gui.timeline -3 inputs=cla
</source>

[[Image:Cla strds.png|center|thumb|560px|Temporal and spatio-temporal extent of cla strds.]]

* [http://grass.osgeo.org/grass71/manuals/g.gui.tplot.html g.gui.tplot] allows to see the values of one or more temporal datasets for a queried point defined by a coordinate pair.

Steps to use this module are:

# Select strds
# Select pair of coordinates (east,north) or point in the map
# Hit Run
# Customize as desired
# Save

[[Image:Output gguitplot.png|center|thumb|800px|Time series plot (Chlorophyll vs Time) for a certain coordinate pair in the study area]]

* [http://grass.osgeo.org/grass71/manuals/g.gui.animation.html g.gui.animation] is the tool for animating a series of raster and vector maps or a space time raster or vector dataset.

<source lang="bash">
g.gui.animation strds=cla
</source>

=== 5. Aggregation ===

For aggregations of data with different methods and different granularities, there are two very useful commands:

* [http://grass.osgeo.org/grass71/manuals/t.rast.series.html t.rast.series] that performs different aggregation algorithms from r.series on all or a subset of raster maps in a strds, and

* [http://grass.osgeo.org/grass71/manuals/t.rast.series.html t.rast.aggregate] that temporally aggregates the maps in a strds by a user defined granularity.

With these modules it is very simple to get maps of basic statistical parameters for different temporal granules, and this permits the analysis of the spatio-temporal variability of the variable of interest.

Some examples:

<source lang="bash">
# yearly aggregation
t.rast.aggregate input=cla output=cla_yearly_average \
base=cla_yearly_average granularity="1 years" \
method=average sampling=start

# yearly aggregation with corresponding methods (output: 7 strds with 11 maps each)
for method in average median mode minimum maximum stddev range ;
do
t.rast.aggregate input=cla output=cla_yearly_${method} \
base=cla_yearly_${method} granularity="1 years" \
method=${method} sampling=start
done
</source>

With the where parameter, we can select all 8-day products which start_time is 01 (January) over the years. Like this we can get the so-known climatologies.

<source lang="bash">
t.rast.series input=cla method=average where="strftime('%m', start_time)='01'" output=january_average
</source>

Generalizing a bit, we can:

<source lang="bash">
# climatologies for every month
for i in 01 02 03 04 05 06 07 08 09 10 11 12 ; do
for m in average median mode stddev range minimum maximum ; do
t.rast.series input=cla method=${m} where="strftime('%m', start_time)='${i}'" output=${m}_${i}
done
done
</source>

Using climatologies previously obtained, we'll now estimate monthly anomalies in the mean, max and min Cl-a concentration. First, we need to monthly aggregate data, and then do the difference between the monthly climatology and each respective monthly aggregate. We'll do the aggregation for the average, minimum and maximum of Cl-a concentration (from 506 input maps in
cla strds, we'll get 132 maps in each monthly aggregated new strds).

<source lang="bash">
# monthly aggregates (132 maps)

for method in average minimum maximum ; do
t.rast.aggregate input=cla output=cla_monthly_${method} base=cla_monthly_${method} \
granularity="1 months" method=${method} sampling=contains
done

# January anomalies in mean, min and max Cl-a

t.rast.list -s input=cla_monthly_average where="start_time=datetime(start_time, 'start of year', '0 month')" columns=name

for m in average minimum maximum ; do
for i in 1 13 25 37 49 61 73 85 97 109 121 ; do # these numbers correspond to all january monthly aggregates
r.mapcalc expression="Jan_${m}_anomaly_${i}=cla_monthly_${m}_${i}-01_${m}"
done
done
</source>

You can also use t.rast.list for looping, the same way you use [http://grass.osgeo.org/grass71/manuals/g.list.html g.list]:

<source lang="bash">
for map in `t.rast.list -s input=cla_monthly_average where="start_time=datetime(start_time, 'start of year', '0 month')" columns=name`;
do
r.mapcalc expression="anomaly_${map}=${map}-01_average"
done
</source>

Say we now need to know the date of the maximum value of Cl-a concentration over all the study period and/or on a yearly basis:

<source lang="bash">
# map index for the overall maximum Cl-a value
t.rast.series input=cla method=max_raster output=cla_max_index

# map index for the yearly maximum Cl-a value
t.rast.aggregate input=cla granularity="1 year" method=max_raster output=yearly_max_index basename=yearly_max_index
</source>

The outputs show (pixelwise) the map index in which the maximum value of Cl-a occurs (from 1 to 506 and from 1 to 46, for the whole time series and on a yearly basis, respectively). For relative time this is maybe enough, but you may then want to reclassify data to get DOY, for example. In that case, you may use [http://grass.osgeo.org/grass71/manuals/r.reclass.html r.reclass].

If you already have monthly data, you can get climatologies quite simply as follows:

<source lang="bash">
# January averages
t.rast.series input=cla_monthly method=average where=start_time=datetime(start_time, 'start of year', '0 month') output=jan_average
</source>

=== 6. Spatio-temporal algebra with STRDS ===

The module [http://grass.osgeo.org/grass71/manuals/t.rast.mapcalc.html t.rast.mapcalc] allows us to perform spatio-temporal mapcalc expressions on temporally sampled maps of strds. There are spatial and temporal operators available for the "expression" string. Spatial operators, functions and internal variables are those used in [http://grass.osgeo.org/grass71/manuals/r.mapcalc.html r.mapcalc]. Temporal internal variables supported for both relative and absolute time include: td(), start_time() and end_time(). There are also several very useful internal variables supported especially for absolute time of the current sample interval or instance, e.g.: start_doy(), start_year(), start_month() and so on (see [http://grass.osgeo.org/grass71/manuals/t.rast.mapcalc.html t.rast.mapcalc] manual site for further details and examples).

Some examples now. Say we did some analysis and decided that we will only consider values higher than 0.05. Then, we need to set all values below that threshold to null.

<source lang="bash">
t.rast.mapcalc input=cla expression="if(cla < 0.05, null(), cla)" output=cla_corrected basename=cla_corrected
</source>

or we may also want to take negative erroneous values to the knowm minimum of the strds, so:

<source lang="bash">
t.rast.series input=cla method=minimum output=min_cla
t.rast.mapcalc input=cla expression="if(cla < 0.0, min_cla, cla)" output=cla_corrected basename=cla_corrected
</source>

We may also need to reclassify all maps in the strds according to a certain threshold, e.g.: a certain level of Cl-a that indicates bloom conditions, in order to get bloom frequency afterwards:

<source lang="bash">
# reclassify
t.rast.mapcalc -n input=cla output=cla_bloom basename=cla_bloom expression="if(cla > 0.75, 1, null())"
# bloom frequency
t.rast.series input=cla_bloom output=bloom_freq method=count
</source>

Do you remember we wanted to get the DOY of maximum Cl-a value before? Well, here's another way of doing it...

<source lang="bash">
# overall maximum value
t.rast.series input=cla method=maximum output=max_cla
# new strds with DOY of overall maximum
t.rast.mapcalc -n inputs=cla output=date_max_cla expression="if(cla == max_cla,start_doy(),null())" basename=date_max_cla
# map with DOY of overall maximum
t.rast.series input=date_max_cla method=maximum output=max_cla_date
# remove date_max_cla strds (we were only interested in the resulting aggregated map)
t.remove -rf inputs=date_max_cla
</source>

In the development version of GRASS GIS, there's also a [http://grass.osgeo.org/grass71/manuals/t.rast.mapcalc2.html t.rast.mapcalc2] module that allows for temporal and spatial operations on strds by means of temporal raster algebra. The module expects an expression as input parameter in the following form:

'''"result = expression"'''

The statement structure is similar to r.mapcalc, the result is the name of a new strds that will contain the result of the calculation given as expression. Expressions can be any valid or nested combination of temporal operations and spatial overlay or buffer functions that are provided by the temporal algebra. See the manual for further details and explanations.

We'll use this module to estimate the rate of change (slope) between every pair of maps in the "cla" strds. The result will be a new strds consisting of maps with the slope value between every consecutive pair of maps in the original strds

<source lang="bash">
t.rast.mapcalc2 expression="slope_cla = (cla[1]-cla[0])/8.0" basename=slope_cla
# we set 8 as fixed denominator, because products are 8-day compositions
</source>

we can then use any of the aggregation modules that we saw before to get the maximum or minimumm rate of change for different granularities.

=== 7. Subseting and something else ===

[http://grass.osgeo.org/grass71/manuals/t.rast.extract.html t.rast.extract] is another really useful module in temporal GRASS. It allows to extract a subset of a strds and store it in a different strds. You use the "where" condition to do the subset, but you can also specify a r.mapcalc sub-expression that performs operations on all maps of the selected subset. If no r.mapcalc expression is defined, the selected maps are simply registered in the new output strds.

Say we need to need to know in how many maps of the strds min values are below a threshold, and not only that, but you also want to know how many pixels per map meet that condition. Then, we can do

<source lang="bash">
t.rast.extract input=cla where="min <= '0.05'" output=cla_less_05 basename=cla_less_05 expression="if(cla<0.05,1,null())"
</source>

to extract those maps with a minimum value lower than 0.05, and in the same step put 1 in every cell meeting the criterium and null everywhere else. To get a count of maps and pixels meeting the condition we may use:

<source lang="bash">
# univariate stistics to get the count per map
t.rast.univar input=cla_less_05
# count map of cells with min value < 0.05
t.rast.series input=cla_less_05 output=count_cla_less_05 method=count
</source>

=== 8. Importing / Exporting strds ===

Say we now need to do some processing in R (e.g.: run [http://menugget.blogspot.com.ar/2012/10/dineof-data-interpolating-empirical.html DINEOF] to fill gaps in data), so we need to export our strds, hence we use [http://grass.osgeo.org/grass71/manuals/t.rast.export.html t.rast.export].

<source lang="bash">
t.rast.export input=cla output=cla4R compression=gzip
</source>

After we have done our analysis we can import the whole strds back to GRASS again, exporting it from R with read/write.tgrass from [http://cran.r-project.org/web/packages/spacetime/index.html spacetime] R package and using [http://grass.osgeo.org/grass71/manuals/t.rast.import.html t.rast.import] in GRASS.

<source lang="bash">
t.rast.import input=cla_from_R.tar.gz output=cla_from_R base=new_map extrdir=/tmp
</source>

=== 9. Neighborhood analysis ===

[http://grass.osgeo.org/grass71/manuals/t.rast.neighbors.html t.rast.neighbors] performs a neighborhood analysis for each map in a space time raster dataset. This module supports a subset of the options already available in r.neighbors. Both, size of the neighborhood and aggregation method can be chosen. As an example, we'll estimate mean Cl-a concentration in a 3x3 neighborhood for every map in the strds.

<source lang="bash">
t.rast.neighbors input=cla output=cla_smoth base=cla_smooth method=average size=3
</source>

=== 10. Filling and reconstructing gappy data - HANTS ===

[http://grass.osgeo.org/grass70/manuals/addons/r.hants.html r.hants] is an add-on not strictly within the temporal modules, but really useful when working with this kind of data, particularly with gappy data. Here's a simple example for generating a list of temporally oredered maps to use as input in r.hants, running HANTS and getting a map of dominant frequencies, afterwards. See the manual for further information on paramenter setting and explanations.

<source lang="bash">
# use t.rast.list to create a list of temporally ordered maps
t.rast.list input=cla order=start_time columns=name -s > map_list

# a hants run
r.hants file=map_list nf=5 fet=0.1 dod=11 base_period=46 suffix=_hants amplitude=amp_hants phase=pha_hants

# dominant frequency map (0 means the dominant freq is 1, 1 that dominant freq is 2, and so on...)
r.series input=`g.list rast pat=amp_hants* sep=,` output=dominant_freq_hants method=max_raster
</source>

=== 11. TODO ===

(add some more)

== FAQ ==
=== Aggregation with defined granularity ===

''Q: I need to aggregate a strds with a granularity of 1 year, but shifting the start day one month in each run, i.e.: changing the start_time to 2003-02-01, 2003-03-01, 2003-04-01 and so on... My question is: if i recursively change start_time with the 'where' parameter, will the module t.rast.aggregate "aggregate" to the next february, march, april (what i'd wish) or just till the end of 2003?''

A: If you specify a granularity of a year, then the start time to perform the aggregation will always be shifted to the 1st January of the current year and the end time the 1st January of the next year (eg. 2002-01-01 - 2003-01-01). If you wish to aggregate a full year but shifting one month forward then simply use a granularity of 12 months.

=== Listing maps with specific start month ===

''Q: I have a strds with 506 maps that correspond to 8-day composite products. I need to sequentially list all maps which "start_month" is January, February and so on... to use them as input in {{cmd|r.series|version=70}} (or {{cmd|t.rast.series|version=70}}). How can I achieve that?''

A: You can use the [https://www.sqlite.org/lang_datefunc.html datetime functionality of SQLite] to perform this task, this should work for January:

<source lang="bash">
t.rast.list input=cla_null_mayor65 \
where='start_time >= datetime(start_time, "start of year") and
start_time <= datetime(start_time, "start of year", "1 month")'
</source>

== Expert tricks ==

BE CAREFUL. THIS IS NOT RECOMMENDED TO NEW USERS.

=== Creating a TGRASS DB with data from a different mapset ===

TGRASS is designed to only work with data present in the current mapset.
An '''expert user''' may override this in order to register data from another mapset in his/her TGRASS database.

To achieve this, the following two internal variables must be set:
<source lang="bash">
g.gisenv set="TGIS_DISABLE_MAPSET_CHECK=True"
g.gisenv set="TGIS_DISABLE_TIMESTAMP_WRITE=True"
</source>

in order to disable the mapset check and the writing of the timestamps of each map to the map metadata in the spatial database as text files. These variables can be set mapset specific.

Settings these variables "True" should (hopefully, because yet partially untested) allow the registration of maps outside the current mapset, even if you do not have the permission to modify the maps.

A warning will be printed if these variables are set True.

BUT, be aware that this feature '''can lead to the corruption of the temporal database''' and unwanted side effects. You can mess up the temporal database if you are not 100% sure what you are doing. It is no longer possible to access the timestamp information of these maps using the C-libraries, because the timestamp information is not available in the map metadata text files.

=== More expert tricks ===

Perhaps to be added...

== Online tutorials and courses ==

* [http://www.geostat-course.org/Topic_Gebbert The temporal GRASS GIS framework: Introduction and application] by Soeren Gebbert (2012)
* [http://fatra.cnr.ncsu.edu/temporal-grass-workshop/ Spatio-temporal data handling and visualization in GRASS GIS] - FOSS4G 2014 workshop by Vaclav Petras, Anna Petrasova, Helena Mitasova, Markus Neteler

== References ==
* Gebbert, S., Pebesma, E., 2014. ''TGRASS: A temporal GIS for field based environmental modeling''. Environmental Modelling & Software 53, 1-12 (http://dx.doi.org/10.1016/j.envsoft.2013.11.001 DOI])

== See also ==
* Introduction: [http://www.slideshare.net/Luis_de_Sousa/presentation-soeren GRASS as a Temporal GIS] by Sören Gebbert (slides)
* [http://grass.osgeo.org/grass70/manuals/temporalintro.html Introduction to temporal modules] (GRASS GIS manual)
* [http://grass.osgeo.org/grass70/manuals/temporal.html Available temporal modules] (GRASS GIS manual)
* [http://trac.osgeo.org/grass/wiki/Grass7/TemporalExtension Temporal Extension] (background info in trac)
* [[GRASS GSoC 2013 Temporal GIS Algebra for raster and vector data in GRASS]]

[[Category: Documentation]]
[[Category:Temporal]]