---
title: "Error and Warning Messages"
author: "Mira Kattwinkel"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Error and Warning Messages}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r echo=FALSE}
knitr::opts_chunk$set(
  eval = TRUE,
  warning = FALSE,
  message = FALSE,
  collapse = TRUE,
  comment = "#>"
)
```

<!-- ## Error when running the examples -->
<!-- **_Problem_** Error message in R console when running `import_data`on the examples files. -->

<!-- **_Solution_** Please update to the latest version of openSTARS (v 1.1.0). A bug in the example files was fixed. -->

<!-- (a) Install openSTARS from github -->
<!-- ```{r install_gh, eval=FALSE} -->
<!-- # install.packages("devtools") -->
<!-- devtools::install_github("MiKatt/openSTARS") -->
<!-- ``` -->

<!-- (b) Download a fixed version of the example shape file for  -->
<!-- monitoring sites ('sites_nc') from <https://github.com/MiKatt/openSTARS/tree/master/inst/extdata/nc>  -->
<!-- and place them into the library folder ('.../openSTARS/extdata/nc/'). -->

<!-- (c) Open sites_nc.shp from the library folder in a GIS program (e.g. QGIS, GRASS -->
<!-- might not work), open the attributes table, sort the 'value' column and start  -->
<!-- editing. Replace all empty cells with an arbitrary integer value. Save and close. -->

# 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:
```{r github_install, eval = FALSE}
  devtools::install_github("MiKatt/openSTARS", ref = "dev")
```

```text
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")

```{r windows settings, eval = FALSE}
  # 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. 


