View source for From GRASS GIS novice to power user (workshop at FOSS4G Boston 2017)

[[File:Foss4g boston 2017 logo.png|right|none]]
[[File:Grassgis logo colorlogo text whitebg.png|400px|right|none]]

Description: Do you want to use GRASS GIS, but never understood what that location and mapset are? Do you struggle with the computational region? Or perhaps you used GRASS GIS already but you wonder what g.region -a does? Maybe you were never comfortable with GRASS command line? In this workshop, we will explain and practice all these functions and answer questions more advanced users may have. We will help you decide when to use graphical user interface and when to use the power of command line. We will go through simple examples of vector, raster, and image processing functionality and we will try couple of new and old tools such as vector network analysis or image segmentation which might be the reason you want to use GRASS GIS. We aim this workshop at absolute beginners without prior knowledge of GRASS GIS, but we hope it can be useful also to current users looking for deeper understanding of basic concepts or the curious ones who want to try the latest additions to GRASS GIS.

Format and requirements: Participants should bring their laptops with GRASS GIS 7. Beginners are encouraged to try using the latest OSGeo-Live virtual machine. There are no special requirements. Just have your laptop with GRASS GIS or OSGeo-Live virtual machine with you.

Authors: [[User:Annakrat|Anna Petrasova]] from North Carolina State University (NCSU), Giuseppe Amatulli from Yale University, and [[User:Wenzeslaus|Vaclav Petras]] from NCSU

== Preparation ==

=== Software ===

'''OSGeo-Live'''

All needed software is included.

''' Ubuntu '''

Install GRASS GIS from packages:
<pre>
sudo add-apt-repository ppa:ubuntugis/ubuntugis-unstable
sudo apt-get update
sudo apt-get install grass
</pre>

''' Linux '''

For other Linux distributions other then Ubuntu, please try to find GRASS GIS in their package managers.

'''MS Windows'''

Download the standalone GRASS GIS binaries from [https://grass.osgeo.org/ grass.osgeo.org].

'''Mac OS'''

Install GRASS GIS using [https://brew.sh/ Homebrew] [https://github.com/OSGeo/homebrew-osgeo4mac osgeo4mac]:
<pre>
brew tap osgeo/osgeo4mac
brew install grass7
</pre>

Note that the 3D view may not be accessible.

=== Data ===
== GRASS GIS introduction ==
Here we provide an overview of the GRASS GIS project: [https://grass.osgeo.org grass.osgeo.org] for first time users. It's not necessary to have a full understanding of how to use GRASS GIS. Here we introduce main concepts necessary for running the tutorial:


==== Structure of the GRASS GIS Spatial Database ====
GRASS uses unique database terminology and structure ([https://grass.osgeo.org/grass72/manuals/grass_database.html GRASS database]) that are important to understand for the set up of this tutorial, as you will need to place the required data (e.g. Location) in a specific GRASS database. In the following we review important terminology and give step by step directions on how to download and place your data in the correct location.


* A '''GRASS GIS Spatial Database''' (''GRASS database'') consists of directory with specific Locations (projects) where data (data layers/maps) are stored.
* '''Location''' is a directory with data related to one geographic location or a project. All data within one Location has the same coordinate reference system.
* '''Mapset''' is a collection of maps within Location, containing data related to a specific task, user or a smaller project.

<center><gallery perrow=1 widths=500 heights=250>Image:Grass database.png|GRASS GIS database schema|</gallery></center>

==== Creating a GRASS database for the tutorial ====
If you are running GRASS GIS from OSGeoLive, you already have nc_spm_08_grass7 dataset (sample GRASS Location for North Carolina).
Otherwise, please download the [https://grass.osgeo.org/sampledata/north_carolina/nc_spm_08_grass7.zip sample GRASS Location for North Carolina], noting where the files are located.
Now, create (unless you already have it) a directory named <tt>grassdata</tt> (GRASS database) in your home folder (or Documents),
unzip the downloaded data into this directory. You should now have a Location <tt>nc_spm_08_grass7</tt> in <tt>grassdata</tt>.

<center><gallery perrow=1 widths=500 heights=250>Image:GRASS_startup_ncspm.png|GRASS GIS 7.2 startup dialog with North Carolina sample dataset</gallery></center>

==== Displaying and exploring data ====

Now that we have the data in the correct GRASS database, we can launch the Graphical User Interface (GUI) in Mapset ''user1''.

The GUI interface allows you to display raster, vector data as well as navigate through zooming in and out. More advanced exploration and visualization is also possible using, e.g., queries and adding legend. The screenshots below depicts how you can add different map layers (left) and display the metadata of your data layers.

<center><gallery perrow=2  widths=500 heights=250>
Image:Wxgui_add_elev_lid.png|Add raster map layer
Image:Wxgui_add_legend_elev_lid.png|Add raster legend
Image:GRASS FUTURES wxGUI display.png|Layer Manager and Map Display overview. Annotations show how to add raster layer, query, add legend.
Image:wxGUI_metadata_rinfo.png|Show raster map metadata by right click on layer
</gallery></center>

To have a better overview of our raster and vector data, we can use Data tab in Layer Manager. From there we can search for data by name and when we right click at the item, we can select from different actions. In this way we can easily copy or remove data, add them to display, or switch between mapsets. Note that by default for safety reasons you can modify data only in current location and mapset. By unlocking you allow editing other mapsets as well.
<center><gallery perrow=2  widths=600 heights=300>Image:GRASS GIS 7.3 data catalog.png| GRASS GIS Data Catalog</gallery></center>

=== GRASS GIS modules ===

One of the advantages of GRASS is the diversity and number of modules that let you analyze all manner of spatial and temporal. GRASS GIS has over [https://grass.osgeo.org/grass70/manuals/full_index.html 500 different modules] in the core distribution and over [https://grass.osgeo.org/grass70/manuals/addons/ 230 addon modules] that can be used to prepare and analyze data layers.

GRASS functionality is available through ''modules'' (tools, functions). Modules respect the following naming conventions: 

<center>
  {| class="wikitable"
|-
! Prefix !! Function !! Example
|-
| r.* || raster processing || ''{{cmd|r.mapcalc}}'': map algebra
|-
| v.* || vector processing  || ''{{cmd|v.clean}}'': topological cleaning
|-
| i.* || imagery processing  || ''{{cmd|i.segment}}'': object recognition
|-
| db.* || database management || ''{{cmd|db.select}}'': select values from table
|-
| r3.* || 3D raster processing  || ''{{cmd|r3.stats}}'': 3D raster statistics
|-
| t.* || temporal data processing  || ''{{cmd|t.rast.aggregate}}'': temporal aggregation
|-
| g.* || general data management || ''{{cmd|g.rename}}'': renames map
|-
| d.* || display ||''{{cmd|d.rast}}'': display raster map
|}</center>

These are the main groups of modules. There is few more for specific purposes. Note also that some modules have multiple dots in their names. This often suggests further grouping. For example, modules staring with ''v.net.'' deal with vector network analysis.

The name of the module helps to understand its function, for example ''v.in.lidar'' starts with ''v'' so it deals with vector maps, the name follows with ''in'' which indicates that the module is for importing the data into GRASS GIS Spatial Database and finally ''lidar'' indicates that it deals with lidar point clouds.

==== Finding and running a module ====

To find a module for your analysis, type the term into the search box into the ''Modules'' tab in the ''Layer Manager'', then keep pressing Enter until you find your module. 

Alternatively, you can just browse through the module tree in the ''Modules'' tab. You can also browse through the main menu. For example, to find information about a raster map, use: ''Raster → Reports and statistics → Basic raster metadata''.

<center><gallery perrow=3 widths=380 heights=190>
Image:wxGUI_module_search.png|Search for a module in module tree (searches in names, descriptions and keywords)
Image:wxGUI_menu_rinfo.png|Modules can be also found in the main menu
</gallery></center>

==== Running a module as a command ====

If you already know the name of the module, you can just use it in the command line. The GUI offers a Command console tab with command line specifically build for running GRASS GIS modules. If you type module name there, you will get suggestions for automatic completion of the name. After pressing Enter, you will get GUI dialog for the module.

<center><gallery perrow=3 widths=380 heights=190>
Image:wxGUI_console_completion.png|Automatic suggestions when typing name of the module: By typing prefix r. we make a list of modules starting with that prefix to show up.
</gallery></center>

You can use the command line to run also whole commands for example when you get a command, i.e. module and list of parameters, in the instructions.

==== Command line vs. GUI interface====
GRASS modules can be executed either through a GUI or command line interface. The GUI offers a user-friendly approach to executing modules where the user can navigate to data layers that they would like to analyze and modify processing options with simple check boxes. The GUI also offers an easily accessible manual on how to execute a model. The command line interface allows users to execute a module using command prompts specific to that module. This is handy when you are running similar analyses with minor modification or are familiar with the module commands for quick efficient processing. In this workshop we provide module prompts that can be copy and pasted into the command line for our workflow, but you can use both GUI and command line depending on personal preference. Look how {{cmd|wxGUI.modules|version=72|desc=GUI and command line interface}} represent the same tool.

==== Module parameters ====

<center><gallery perrow=3 widths=380 heights=190>
Image:Wxgui_module_parameters_r_neighbors.png|Module dialog
</gallery></center>

The same analysis can be done using the following command:

 r.neighbors -c input=elevation output=elev_smooth size=5

Conversely, you can fill the GUI dialog parameter by parameter when you have the command.

=== Computational region ===

Before we use a module to compute a new raster map, we must set properly computational region. All raster computations will be performed in the specified extent and with the given resolution.

Computational region is an important raster concept in GRASS GIS. In GRASS a computational region can be set, subsetting larger extent data for quicker testing of analysis or analysis of specific regions based on administrative units. We provide a few points to keep in mind when using the computational region function:
* defined by region extent and raster resolution
* applies to all raster operations
* persists between GRASS sessions, can be different for different mapsets
* advantages: keeps your results consistent, avoid clipping, for computationally demanding tasks set region to smaller extent, check your result is good and then set the computational region to the entire study area and rerun analysis
* run <code>g.region -p</code> or in menu ''Settings'' - ''Region'' - ''Display region'' to see current region settings

<center><gallery perrow=3 widths=380 heights=190>
Image:Computational_region_two_rasters.png|Computational region concept: A raster with large extent (blue) is displayed as well as another raster with smaller extent (green). The computational region (red) is now set to match the smaller raster, so all the computations are limited to the smaller raster extent even if the input is the larger raster. (Not shown on the image: Also the resolution, not only the extent, matches the resolution of the smaller raster.)
Image:WxGUI set region.png|Simple ways to set computational region from GUI. On the left, set region to match raster map. On the right, select the highlighted option and then set region by drawing rectangle.
Image:Wxgui_computational_region_set_from_raster.png|Set computational region (extent and resolution) to match a raster (''Layers'' tab in the ''Layer Manager'')
</gallery></center>

The numeric values of computational region can be checked using:

 g.region -p

After executing the command you will get something like this:

 north:      220750
 south:      220000
 west:       638300
 east:       639000
 nsres:      1
 ewres:      1
 rows:       750
 cols:       700
 cells:      525000

Computational region can be set also using a vector map. In that case, only extent is set (as vector map does not have any resolution - at least not in the way raster map does). In GUI, this can be done in the same way as for the raster map. In the command line, it looks like this:

 g.region vector=lakes

Resolution can be set separately using the <code>res</code> parameter of the {{cmd|g.region}} module. The units are the units of the current location, in our case meters. This can be done in the ''Resolution'' tab of the {{cmd|g.region}} dialog or in the command line in the following way (using also the <code>-p</code> flag to print the new values):

 g.region res=3 -p

The new resolution may be slightly modified in this case to fit into the extent which we are not changing. However, often we want the resolution to be the exact value we provide and we are fine with a slight modification of the extent. That's what <code>-a</code> flag is for.

The following example command will use the extent from the vector named <code>lakes</code>, use resolution <code>10</code>, modify the extent to align it to this 10 meter resolution, and print the values of this new computational region settings:

 g.region vector=lakes res=10 -a -p

=== Running modules ===

Find the module for computing slope and aspect in menu or the module tree under ''Raster → Terrain analysis → Slope'' and aspect or simply run {{cmd|r.slope.aspect}}.

<center><gallery perrow=3 widths=380 heights=190>
Image:r_slope_aspect_1_required.png|Select input elevation raster map.
Image:r_slope_aspect_2_outputs.png|Enter names of output raster maps. Note also the corresponding command at the bottom of the GUI dialog.
Image:r_slope_aspect_3_manual.png|Use manual included in the GUI dialog to refer to details
Image:r_slope_aspect_4_run.png|Press Run (1) to compute. When computed result is added to Layer Manager and Map Display. Use Close (2) to close the window.
</gallery></center>


=== 3D view ===
We can explore our study area in 3D view.
# Add <tt>elev_lid792_1m</tt> and uncheck or remove any other layers.
# Set computational region to this raster. Switch to 3D view (in the right corner on Map Display).
# Adjust the view (perspective, height, vertical exaggeration)
# In ''Data'' tab, set ''Fine mode resolution'' to 1 and set <tt>slope</tt> (computed in the previous step) as the color of the surface.
# When finished, switch back to 2D view.
[[File:Elevation_slope_3D_view.png|800px|thumb|center| 3D visualization of elev_lid792_1m DEM with slope draped over]]

== GRASS working environment and working directory ==

== Create location and mapset (from GUI and from command line) ==

== Move data to and from GRASS database ==

== Move data between locations and mapsets ==

== Perform basic raster and vector operations ==

== Try out some of the more advanced and latest features ==

=== Network analysis ===

=== Segmentation ===

{{cmd|i.segment}}, {{addonCmd|i.superpixels.slic}}

Next steps and alternative workflows can involve: {{addonCmd|i.segment.hierarchical}}, {{addonCmd|i.segment.uspo}} and {{addonCmd|i.segment.stats}}.

=== Hydrology ===

=== Running processes in command line on HPC ===

 grass7 -c path/to/database/location/mapset
 grass7 path/to/database/location/mapset --exec script.py params
 rm path/to/database/location/mapset