# GRASS version

If there are problems with GRASS functions (e.g. dlls not found on Windows or other error messages / warnings on Linux) try installing a slightly older Grass version instead of the most recent one (currently e.g. Grass 7.6 or 7.4 instead of 7.8). openSTARS depends on several other R packages providing GIS functionality and particularly for linking R to Grass. It might be possible that not all changes of the newest Grass version have already been implemented in all these packages resulting in errors and warnings.

# Special settings for MAC OS

GRASS 7 does not run on Mac with system integrity check (http://grassmac.wikidot.com) and it needs to be disbaled. Additionally, GRASS addons (r.hydrodem etc.) need to be installed system-wide (see below how to install them using GRASS GUI).

# Errors when installing from github

When using the folliwing command in RStudio, this may result in an error:

      devtools::install_github("MiKatt/openSTARS", ref = "dev")

    Error: (converted from warning) Setting LC_CTYPE failed, using "C"
    Execution halted
    Error in i.p(...) :
    (converted from warning) installation of package ‘/tmp/RtmpMsIim5/file65bc33ff2831/openSTARS_1.2.0.tar.gz’ had non-zero exit status

Try the follwing: Quit RStudio, start R from a console and run the command there. It should install without error. Close R in the console (using q()), restart RStudio and continue.

# Errors and warnings on WINDOWS systems

Most problems occur because GRASS, which is called by the openSTARS package functions via package rgrass7, cannot find certain files, i.e. because some path and system variables are not set. The easiest solution is to install a stand-alone version of GRASS, i.e. not within QGIS or OSGeo.

### Setting PATH and SYSTEM variables

Alternatively, the following PATH and system variables must be set correctly (examples below assume that GRASS was installed under QGIS). This can be done globally (see instructions in the internet how to set such variables in your specific Windows version) or temporarily in the R session as follows

- Path to iconv.dll and other necessary *.dll files; this must be set before the initGRASS command: Sys.setenv(PATH = paste0(“C:/Program Files/QGIS 2.18/bin”, “;”, Sys.getenv(“PATH”)))
- System variable GRASS_PYTHON; this must be set after initGRASS: Sys.setenv(GRASS_PYTHON=“C:/Program Files/QGIS 2.18/bin/python.exe”)
- System variable PYTHONHOME; this must be set after initGRASS: Sys.setenv(PYTHONHOME=“C:/Program Files/QGIS 2.18/apps/Python27”)
- System variable GDAL_DATA; this must be set after initGRASS: Sys.setenv(GDAL_DATA=“C:/Program Files/QGIS 2.18/share/gdal”)

      # GRASS in QGIS installation
      #set Path; must be done BEFORE initGRASS
      Sys.setenv(PATH=paste0("C:/Program Files/QGIS 2.18/bin",";", Sys.getenv("PATH")))
      initGRASS(gisBase = "c:/Program Files/QGIS 2.18/apps/grass/grass-7.0.5",
                home = tempdir(),
                gisDbase = "C:/GRASSDB"
               )
      # set System Variables; must be done AFTER initGRASS
      Sys.setenv(GRASS_PYTHON="C:/Program Files/QGIS 2.18/bin/python.exe")
      Sys.setenv(PYTHONHOME="C:/Program Files/QGIS 2.18/apps/Python27")
      Sys.setenv(GDAL_DATA="C:/Program Files/QGIS 2.18/share/gdal")

### Specific messages

Problem Popup window:

The program can't start because iconv.dll is missing from your computer. Try reinstalling the program to fix this problem. And similar messages for other *.dll files.

Solution Check, if the missing file(s) are somewhere ‘close’ to the GRASS installation; e.g., if Grass was installed with QGIS, GRASS might be located under C:\Program Files\QGIS 2.18\apps\grass\grass-7.0.5 and iconv.dll can be found in C:\Program Files\QGIS 2.18\bin. Set the PATH variable to the latter folder. (See instructions in the internet how to set the PATH variable in your specific Windows version.)

If this does not help, try a stand-alone installation of GRASS (https://grass.osgeo.org/). The missing dll files will then probably be located in a folder called 'extrabin' within the GRASS directory and will be found automatically.

\

Problem Popup window:

The program can't start because libgrass_gis.7.2.0.dll is missing from your computer. Try reinstalling the program to fix this problem.

Solution Close R (to close the GRASS session) and open GRASS, or open GRASS and select a different location than the one used in R. In the GRASS GUI go to 'Settings'/'Addons extension'/'Install extensions from addons' and (re-) install r.hydrodem which can be found under 'raster'.

\

Problem Popup window: The program can't start because libgrass_dbmibase.7.2.0.dll is missing from your computer. Try reinstalling the program to fix this problem.

Solution Close R (to close the GRASS session) and open GRASS or open GRASS and select a different location than the one used in R. In the GRASS GUI go to 'Settings'/'Addons extension'/'Install extensions from addons' and (re-) install r.stream.order which can be found under 'raster'.

\

Problem Popup window: The program can't start because libgrass_vector.7.2.0.dll is missing from your computer. Try reinstalling the program to fix this problem.

Solution Close R (to close the GRASS session) and open GRASS or open GRASS and select a different location than the one used in R. In the GRASS GUI go to 'Settings'/'Addons extension'/'Install extensions from addons' and (re-) install r.stream.basins which can be found under 'raster'.

\

Problem Popup window: The program can't start because libgrass_segment.7.0.5.dll is missing from your computer. Try reinstalling the program to fix this problem.

Solution Close R (to close the GRASS session) and open GRASS or open GRASS and select a different location than the one used in R. In the GRASS GUI go to 'Settings'/'Addons extension'/'Install extensions from addons' and (re-) install r.stream.distance which can be found under 'raster'.

\

Problem Warning message in R console: Datum your_datum not recognised by GRASS and no parameters found

E.g. your_datum = North_American_1983_HARN

Solution Find a folder called 'gdal' containing files including coordinate_axis.csv ‘close’ to or in the GRASS installation; e.g., if Grass was installed with QGIS, GRASS might be located under C:\Program Files\QGIS 2.18\apps\grass\grass-7.0.5 and the folder gdal can be found in C:\Program Files\QGIS 2.18\share\gdal. Create a System Variable GDAL_DATA and set it to this path. (See instructions in the internet how to create and set the system variables in your specific Windows version.)

\

Problem Error and warning messages in R console: ERROR 4: Unable to open EPSG support file gcs.csv. Try setting the GDAL_DATA environment variable to point to the directory containing EPSG csv files. ERROR: Unable to translate EPSG code Warning message: running command 'g.proj.exe -c epsg=your_code had status 1

Solution Find a folder called 'gdal' containing files including coordinate_axis.csv ‘close’ to or in the GRASS installation; e.g., if Grass was installed with QGIS, GRASS might be located under C:\Program Files\QGIS 2.18\apps\grass\grass-7.0.5 and the folder gdal can be found in C:\Program Files\QGIS 2.18\share\gdal. Create a System Variable GDAL_DATA and set it to this path. (See instructions in the internet how to create and set the system variables in your specific Windows version.)

\

Problem Error in R console: Warning 1: Cannot find pcs.csv Warning 1: Cannot find datum.csv or gdal_datum.csv Warning 1: Cannot find ellipsoid.csv Warning 1: Cannot find prime_meridian.csv

Solution Find a folder called gdal containing files including coordinate_axis.csv ‘close’ to or in the GRASS installation; e.g., if Grass was installed with QGIS, GRASS might be located under C:\Program Files\QGIS 2.18\apps\grass\grass-7.0.5 and the folder gdal can be found in C:\Program Files\QGIS 2.18\share\gdal. Create a System Variable GDAL_DATA and set it to this path. (See instructions in the internet how to create and set the system variables in your specific Windows version.)

\

Problem Error in R console: Error : XML content does not seem to be XML: The system cannot find the path specified.' In addition: Warning message: running command 'v.db.renamecolumn.bat –interface-description' had status 1 Error in parseGRASS(cmd, legacyExec = legacyExec) : v.db.renamecolumn not parsed

Solution Find the file python.exe ‘close’ to the GRASS installation; e.g., if Grass was installed with QGIS, GRASS might be located under C:\Program Files\QGIS 2.18\apps\grass\grass-7.0.5 and the file python.exe can be found in C:\Program Files\QGIS 2.18\bin. Create a System Variable GRASS_PYTHON and set it to the complete path of this file (e.g. C:\Program Files\QGIS 2.18\bin\python.exe). (See instructions in the internet how to create and set the system variables in your specific Windows version.)

\

Problem Error in R console: Error : XML content does not seem to be XML: 'ImportError: No module named site' In addition: Warning message: running command 'v.db.renamecolumn.bat –interface-description' had status 1 Error in parseGRASS(cmd, legacyExec = legacyExec) : v.db.renamecolumn not parsed

Solution Find the folder Python27 ‘close’ to the GRASS installation; e.g., if Grass was installed with QGIS, GRASS might be located under C:\Program Files\QGIS 2.18\apps\grass\grass-7.0.5 and the folder can be found in C:\Program Files\QGIS 2.18\apps\Python27. Create a System Variable PYTHONHOME and set it this path. (See instructions in the internet how to create and set the system variables in your specific Windows version.)

# Messages and warnings in specific functions

## Message when using `setup_grass_environment` or `import_data`

Warning in R console: WARNING: Over-riding projection check. Windows does not recognize the projection of the DEM raster. It will be overwritten with the one of the observation sites ( your working directory ). Please verify that the projections match.

GRASS usually checks if all files that are imported into a mapset have the same projection. However, under Windows, this check would always results in an error. Therefore, the check is disabled under Windows and the user is asked to make sure that all sources come from the same projection manually (e.g. using another GIS).

## Message in `setup_grass_environment`

Problem Message in R console when setting up the GRASS environment:

`'sites' is no longer a parameter of setup_grass_environment (see help). The function will still execute normally. Please update your code.`

The function `setup_grass_environment` has been updated; the `sites` parameter is deprecated.

## Warning message in `derive_streams`

Problem Message in R console when deriving the streams from the DEM:

`WARNING: Stream network may be too dense`

The parameter `accum_threshold` (i.e. minimum number of cells that will initiate a new stream) is probably too small; try to increase it and check if all desired small streams are constructed.

## Error message in `calc_edges`

Problem Message in R console when using `calc_edges`:

`Error in execGRASS("r.stream.basins", flags = c("overwrite", "quiet"), : The command: r.stream.basins --overwrite --quiet direction=dirs stream_rast=streams_r basins=rca produced an error (1) during execution: ERROR: Stream and direction maps probably do not match`

The stream network was too dense. Please increase the parameter `accum_threshold` in `derive_streams`. Then, run `correct_compl_junctions` again, if necessary, and `calc_edges`.

# Messages you do not need to worry about

In the R console when using function `setup_grass_environment`:

    Trying to open with OGR…
    ...succeeded.
    Default region was updated to the new projection, but if you have multiple
    mapsets `g.region -d` should be run in each to update the region from the
    default
    Projection information updated

It is the intention of this function is to update the projection.

\

In the R console when using function `correct_compl_junctions`:

    WARNING: <number> points found, but not requested to be exported. Verify 'type' parameter.

In this function, the streams are imported and exported during the processing. At one stage, only the lines are exported but no points. These points were created automatically when extracting the streams from the DEM but are not needed.

\

In various functions:

    WARNING: Vector map <name> already exists and will be overwritten
    WARNING: Raster map <name> already exists and will be overwritten

This happens if e.g. the function has already been executed in the same GRASS locations. Existing maps are overwritten and all changes that might have been conducted are lost. However, usually this is not a problem and everything can be reconstructed if needed by just executing all functions again. If maps are manually changed they should be saved under a different name to prevent automatic overwriting.

\

In the R console when using function `calc_edges`:

    WARNING: No features selected, nothing to edit

In this function, point features that were created automatically when extracting the streams from the DEM but are not needed are deleted. This warning appears if `correct_compl_junctions` has been executed before and the points have already been deleted.

\

In the R console when using function `calc_sites`:

    WARNING: Width for column <name> set to 255 (was not specified by OGR), some strings may be truncated!

Or in `export_ssn`:

    Warning 1: Field site_id of width 255 truncated to 254.

This message appears when maps are exported to ESRI shape files, which cannot handle attribute fields with more than 254 characters. Typically, there is no need to worry because all fields should be shorter anyway. If the original shape files contained large fields with e.g. notes or other text, they may be truncated in the exported files.