notebook_intro.qmd

---
title: "Part 1: Intro to GRASS GIS"
subtitle: "Basic notions, interfaces and temporal framework"
author: "Veronica Andreo"
date: '`r Sys.Date()`'
editor: 
  markdown: 
    wrap: 80
---

## GRASS GIS general stuff

- **GRASS GIS** (Geographic Resources Analysis Support System), a FOSS suite
used for geospatial data management and analysis, image processing, graphics
and maps, spatial modeling, and visualization.
- Originally developed by the U.S. Army Construction Engineering Research
Laboratories for land management and environmental planning (1982-1995).
- First *User Manual* published on July 29th, 1983... **GRASS is becoming 40 this year!**
- More history: <https://grass.osgeo.org/about/history/>
- Free and open source, you can use, modify, improve, share
- Strong user community, commercial support
- Large amount of tools: 500+ [core modules](#modules), 400+ [addons](#addons)
- GUI and CLI interfaces
- Python API and libraries - the latest `grass.jupyter` library can be tried
[online](https://mybinder.org/v2/gh/OSGeo/grass/8.2.2?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fjupyter_example.ipynb)
- Connection with R, QGIS, WPS, etc.
- Different data types supported:
[raster](https://grass.osgeo.org/grass-stable/manuals/rasterintro.html)
(including [satellite
imagery](https://grass.osgeo.org/grass-stable/manuals/imageryintro.html)),
[3D raster or
voxel](https://grass.osgeo.org/grass-stable/manuals/raster3dintro.html),
[vector](https://grass.osgeo.org/grass-stable/manuals/vectorintro.html) and
[space-time
datasets](https://grass.osgeo.org/grass-stable/manuals/temporalintro.html)

### Open GRASS for the first time

As of version 8.0, GRASS has modified its startup to make it more user friendly:

![](assets/img/studio/grass_start.png){width="85%" fig-align="center"}

From the **Data** catalog tab you can manage several actions and if 
you do not yet have imported data into the GRASS database, the 
software creates the directory structure or database automatically.

### Database

- **GRASS database** (directory with projects): When running GRASS GIS for the
  first time, a folder named "grassdata" is automatically created. Depending
  on the operating system, it can be found in `$HOME` (\*nix) or
  `My Documents` (MS Windows).
- **Location** (a project): A location is defined by its coordinate reference
  system (CRS). The location that is automatically created is in WGS84
  (EPSG:4326). If you have data in another CRS, you should ideally create a
  new location.
- **Mapset** (a subproject): Each location can have many mapsets to manage
  different aspects or sub-regions of a project. When creating a new location,
  GRASS GIS automatically creates a special mapset called *PERMANENT* where
  the central data of the project (e.g., base maps, road network, dem, etc.)
  can be stored.


![](assets/img/studio/grass_database.png){width="60%" fig-align="center"}


::: callout-note
More info: <https://grass.osgeo.org/grass-stable/manuals/grass_database.html>.
:::

### Computational region

Another fundamental concept of GRASS GIS (and very useful when working with
raster data) is that of the **computational region**. It refers to the boundary
configuration of the analysis area and spatial resolution (raster). The
**computational region** can be defined and modified with the command
[g.region](https://grass.osgeo.org/grass-stable/manuals/g.region.html) to the
extent of a vector map, a raster or manually to some area of interest. The
*output raster maps will have an extent and spatial resolution equal to the
computational region*, while vector maps are always processed at their original
extent.

![](assets/img/studio/region.png){width="60%" fig-align="center"}


::: callout-note
For more details, see the wiki on [Computational Region](https://grasswiki.osgeo.org/wiki/Computational_region).
:::

### Modules and extensions

GRASS has more than [500
modules](https://grass.osgeo.org/grass-stable/manuals/full_index.html) for the
most varied tasks:

| Prefix                                                                   | Function class | Type of command         | Example                                                                                                                |
|------------------|:--------------|:--------------|:--------------------------------|
| [g.\*](https://grass.osgeo.org/grass-stable/manuals/full_index.html#g)   | general        | general data management | [g.rename](https://grass.osgeo.org/grass-stable/manuals/g.rename.html): renames map                                    |
| [d.\*](https://grass.osgeo.org/grass-stable/manuals/full_index.html#d)   | display        | graphical output        | [d.rast](https://grass.osgeo.org/grass-stable/manuals/d.rast.html): display raster map                                 |
| [r.\*](https://grass.osgeo.org/grass-stable/manuals/full_index.html#r)   | raster         | raster processing       | [r.mapcalc](https://grass.osgeo.org/grass-stable/manuals/r.mapcalc.html): map algebra                                  |
| [v.\*](https://grass.osgeo.org/grass-stable/manuals/full_index.html#r)   | vector         | vector processing       | [v.clean](https://grass.osgeo.org/grass-stable/manuals/v.clean.html): topological cleaning                             |
| [i.\*](https://grass.osgeo.org/grass-stable/manuals/full_index.html#i)   | imagery        | imagery processing      | [i.pca](https://grass.osgeo.org/grass-stable/manuals/i.pca.html): Principal Components Analysis on imagery group       |
| [r3.\*](https://grass.osgeo.org/grass-stable/manuals/full_index.html#r3) | voxel          | 3D raster processing    | [r3.stats](https://grass.osgeo.org/grass-stable/manuals/r3.stats.html): voxel statistics                               |
| [db.\*](https://grass.osgeo.org/grass-stable/manuals/full_index.html#db) | database       | database management     | [db.select](https://grass.osgeo.org/grass-stable/manuals/db.select.html): select value(s) from table                   |
| [ps.\*](https://grass.osgeo.org/grass-stable/manuals/full_index.html#ps) | postscript     | PostScript map creation | [ps.map](https://grass.osgeo.org/grass-stable/manuals/ps.map.html): PostScript map creation                            |
| [t.\*](https://grass.osgeo.org/grass-stable/manuals/full_index.html#t)   | temporal       | space-time datasets     | [t.rast.aggregate](https://grass.osgeo.org/grass-stable/manuals/t.rast.aggregate.html): raster time series aggregation |

Extensions or [**add-ons**](https://grass.osgeo.org/grass-stable/manuals/addons/) 
can be installed from the [central GitHub repository](https://github.com/OSGeo/grass-addons)
or from *other users' GitHub* (or similar repositories) using the command
[g.extension](https://grass.osgeo.org/grass-stable/manuals/g.extension.html).
For example:

``` bash
 # install an extension from the GRASS GIS repository
 g.extension extension=r.hants
 
 # install an extension from another GitHub repository
 g.extension extension=r.change.stats \
   url=https://github.com/mundialis/r.change.stats
```

### Graphical User Interface (GUI)

![](assets/img/studio/Single_Window_GUI.png){width="870px" fig-align="center"}


### Command line

![](assets/img/studio/grass_command_line.png){width="65%" fig-align="center"}


## GRASS + {{< fa brands python >}}

There are different Python libraries delivered with GRASS GIS, we'll use 2 of 
them:

- `grass.script` which provides Python interface to launch GRASS GIS modules in scripts
- `grass.jupyter` which offers classes and setup functions for running GRASS GIS in Jupyter Notebooks

Other Python libraries delivered with GRASS GIS include: pygrass, the temporal 
framework, the testing framework, among others.


We can use Python within GRASS GUI, within Jupyter notebooks, or from our 
preferred IDE. See the options within the GUI:

![](assets/img/studio/grass_and_python_gui.png)

::: {.callout-note}
See <https://grass.osgeo.org/grass-stable/manuals/libpython/index.html> for further 
details.
:::


## GRASS + {{< fa brands r-project >}} through `rgrass` package

We can use [R within a GRASS GIS
session](https://grasswiki.osgeo.org/wiki/R_statistics/rgrass7#R_within_GRASS)
or use [GRASS GIS within an R
session](https://grasswiki.osgeo.org/wiki/R_statistics/rgrass7#GRASS_within_R).
We'll explore this further in the last part of this session.

![](assets/img/studio/RwithinGRASS_and_Rstudio_from_grass.png)


## Demo session overview

Habitat suitability mapping for the Asian tiger mosquito in Northern Italy based
on variables derived from daily LST data

- **GRASS**
    - Import species records
    - Create random background points
    - Create different environmental layers from daily LST data
- **R**
    - Read data from GRASS into R
    - Model species distribution
    - Model evaluation
    - Visualization of results

![](assets/img/lecture/workflow_sdm_other.png){width="85%" fig-align="center"}


### Data for the session

<img src="assets/img/studio/aedes_albopictus.jpg" width="30%" align="right"/>

- Records of *Aedes albopictus* (Asian tiger mosquito) in Northern Italy
  downloaded from [GBIF](https://www.gbif.org/)
- Average daily MODIS LST reconstructed by 
  [mundialis GmbH & Co. KG](https://www.mundialis.de/en/) based on @metz_new_2017:
    - 1 km spatial resolution
    - Converted to Celsius degrees

<img src="assets/img/studio/lst_north_italy_2014.png" width="40%" align="right" padding-right="15px"/>


### Get the sample location

- Create a folder named `grass_ncsu_2023`
- Within `grass_ncsu_2023` create a folder named `grassdata`
- Download and unzip [eu_laea location with LST mapset](https://drive.google.com/file/d/1z1b2NLC4Z6yzz_57RddTdRRK_gUkd7fU/view?usp=sharing)
and unzip within your `grassdata` folder
- Download [mosquito data](https://github.com/veroandreo/grass_ncsu_2023/raw/main/data/aedes_albopictus.gpkg) and drop it within `grass_ncsu_2023`

The `grass_ncsu_2023` folder's tree should look like this:

```         
  grass_ncsu_2023/
  ├── aedes_albopictus.gpkg
  └── grassdata
      └── eu_laea
          ├── italy_LST_daily
          └── PERMANENT

```

# GRASS GIS HELP!!!

- [g.manual](https://grass.osgeo.org/grass76/manuals/g.manual.html):
  in the main GUI under Help or just pressing *F1*
- `--help` or `--h` flag after the module name in the terminal
- [GRASS website](https://grass.osgeo.org/): rich [learn](https://grass.osgeo.org/learn/) section with links to videos, tutorials, courses, books, etc.
- [GRASS wiki](https://grasswiki.osgeo.org/wiki/GRASS-Wiki): examples,
  explanations on particular modules or tasks,
  [tutorials](https://grasswiki.osgeo.org/wiki/Category:Tutorial),
  applications, etc.
- grass-user mailing list: [subscribe](https://lists.osgeo.org/mailman/listinfo/grass-user) and post or check the [archives](https://lists.osgeo.org/pipermail/grass-user/)
- GRASS Gitter chat: <https://gitter.im/grassgis/community>
- Link to source code and history in each module manual page, eg., 
[t.rast.algebra](https://grass.osgeo.org/grass-stable/manuals/t.rast.algebra.html)

![](assets/img/studio/source_code_link.png){width="650px" fig-align="center"}


## Other (very) useful links

- [GRASS intro workshop held at NCSU](https://ncsu-osgeorel.github.io/grass-intro-workshop/)
- [Unleash the power of GRASS GIS at US-IALE 2017](https://grasswiki.osgeo.org/wiki/Unleash_the_power_of_GRASS_GIS_at_US-IALE_2017)
- [Temporal data processing wiki](https://grasswiki.osgeo.org/wiki/Temporal_data_processing)
- [GRASS GIS and R for time series processing wiki](https://grasswiki.osgeo.org/wiki/Temporal_data_processing/GRASS_R_raster_time_series_processing)
- [GRASS GIS temporal workshop at NCSU](http://ncsu-geoforall-lab.github.io/grass-temporal-workshop/)
- [GRASS GIS course in Jena](https://training.gismentors.eu/grass-gis-workshop-jena/index.html)
- [GRASS GIS course IRSAE](http://training.gismentors.eu/grass-gis-irsae-winter-course-2018/index.html)
- [GRASS GIS course in Argentina](https://gitlab.com/veroandreo/curso-grass-gis-rioiv)

# References

:::{#refs}

:::