R-Console

R is a freely available scripting language and environment for statistical computing developed by the R Foundation and supplemented by an active user community which provides a vast variety of statistical and graphical procedures. The R-Console has been built into Hydro GeoAnalyst to leverage the extensive data science libraries available in R.

Please Note: The R-Console is meant to be a light-weight utility that provides a direct connection to your project data rather than a replacement for more comprehensive integrated development environments (IDE) for R such as RStudio. As the R programming language is well documented at the R-Project website and other sites, the documentation provided in this section is limited to descriptions of the functionality of the R-Console and a few distinct differences between the version of R used in the R-Console module of Hydro GeoAnalyst and standard R.

The R-Console module is divided into four separate panes:

1.Input pane: a workspace to develop and input R scripts,

2.Output pane: outputs from scripts will appear here,

3.Project Data pane: allows you to easily add list variables containing values from a project database field from a given station group, and

4.Parameters pane: allows you to easily add list variables containing parameter values from a given sample set.

Input Pane

The Input pane provides a workspace to develop R scripts. The Input pane includes the tools described above as well as a status bar that provides a line and column counter for the location of the cursor.

R-Console Toolbar

The R-Console contains the following controls:

• New Script: creates a new empty script.

• Rename: allows you to rename the current script.

• Save: saves changes to the current script.

• Save As: saves changes as a new script.

• Export to File: saves the script as an external file.

• Run: runs the entire script.

• Parse: parses Hydro GeoAnalyst-specific commands (e.g. the list constructors built using the interface) into the raw data that can be run in native R interfaces such as RGui or RStudio.

• Stop: stops a running script.

• Clear: clears variables in active memory from previous script runs

Differences between R-Console scripts and standard R scripts

There are several differences between the R scripts available in the Hydro GeoAnalyst R-Console and standard R-scripts:

•Multi-line commands: multi-line commands in many implementations of R do not require a line-continuation character. In the case of R-Console, a '+' must be placed in the first column of each continued line. To facilitate this, you can press <SHIFT>+<ENTER> to continue a line and a '+' will be added for you. An example of a continued line from the third script in the HGA+ Demo Project Tutorial tutorial is shown below:

chart1 <- ggplot(df, aes(x=X, y=Y)) +

+ geom_point() +

+ ggtitle("Monitoring Well Coordinates") +

+ labs(x = "Easting (m)", y = "Northing (m)")

•Comments: similar to standard R, the '#' symbol defines a code comment and text following this character will not be interpreted as part of the script. furthermore, comments in the R-Console can also be in any column of the script; however, unlike other implementations of R they cannot interrupt multi-line commands without causing an error.

•Output: by default, most implementations of R echo commands from the script. Given the potential for large datasets in Hydro GeoAnalyst, the echo has been disabled in R-Console so that script performance is not degraded. The output pane only displays information that is passed through the print() command.

•Project Data variables: R-Console includes custom commands that allow Hydro GeoAnalyst to inject project data into R. In this process, each script is interpreted in two passes, the first by Hydro GeoAnalyst to convert these custom commands (this is equivalent to the parse button), the second pass is the interpretation of the R script itself. An example from the second script in the HGA+ Demo Project Tutorial tutorial is shown below:

R-Console script with project data

Sample = c(SAMPLE[Name,SampleSet(5)])

Equivalent Parsed R-script with project data

Sample = c("1-2004-1", "1-2004-31", "1-2005-2", "1-2006-3", "1-2007-4", "1-2008-5", "1-2009-6", "1-2010-7", "MW-1-92", "MW-1-94", "3-2004-75", "3-2004-8", "3-2005-9", "3-2006-10", "3-2007-11", "3-2008-12", "3-2009-13", "3-2010-14", "3-2010-81", "MW-3-92", "MW-3-94", "MW-3-98", "2-2004-15", "2-2005-16", "2-2007-18", "2-2008-19", "2-2009-20", "2-2009-80", "2-2010-21", "2-2010-51", "OW-2-92", "OW-2-95", "OW-2-97", "4-2004-22", "4-2004-52", "4-2005-23", "4-2006-24", "4-2007-25", "4-2008-26", "4-2009-27", "4-2009-57", "4-2010-28", "4-2010-29", "4-2010-30", "4-2010-58", "OW-4-93", "OW-4-94", "OW-4-97")

For more information, see the sections on the Project Data pane and the Parameter Pane.

Output Pane

The Output pane displays output from R scripts that have run. The Output pane contains one button, (the Clear button), which clears any output from the pane, and a status bar at the bottom of the pane which provides information (e.g. whether a script is running or how long scripts have taken to run). As described above, in order to improve the performance and runtimes of scripts, the Output pane only broadcasts information from print() commands.

Project Data Pane: Adding a Project Data Variable

The Project data pane includes a hierarchical tree of the database structure organized by data categories > tables > fields. The pane also includes controls:

• Collapse tree: collapses the Project data tree

• Search: searches the project database using the search term in the input box to the left

• Clear Search: clears the search bar

• Show Tooltips: toggles whether tooltips are shown when hovering the mouse pointer over a given entry in the tree

Double-clicking a field in the project tree opens the New field variable window:

The following inputs are included in the window:

•Variable name: the name that will be used in the script, by default, this will be the name of the selected field

•Fields: allows you to select a field that will be

•Filter: allows you to constrain the data using one of the following options:

oGet all data: returns all data in the table from the selected field

oActive Station Group: data will be limited to the active station group

oSpecific Station Group: data will be limited to the selected station group in the Project Explorer using the accompanying dropdown menu

oSpecific station: data will be limited to the selected station; the browse button will invoke a Station picker

Click the button to add the new list variable subject to the constraints listed above.

Parameter Pane: Adding a parameter variable

A parameter picker is included in the R-Console module to facilitate adding a list variable to your script that includes the values of the selected parameter for a specified sample set.

The parameter picker includes a parameter group dropdown menu containing:

•Automatic parameter groups: station parameters, sample parameters, analyzed parameters, cations, anions, ions, calculated parameters, and parameters used in a standard; and

•Custom parameter groups: parameter groups created in the Parameter Group Editor

If you wish to add a parameter variable, use the parameter group dropdown menu and/or the filter bar to find the desired parameter. Once you've located the parameter, you can select it by double-clicking it and the new parameter variable window will appear:

The following inputs are included in the window:

•Variable name: the name that will be used in the script, by default, this will be the name of the selected parameter

•Parameter: the parameter that you selected; you can change the parameter if you need to by selecting the button

•Unit: the unit that will be used for the parameter (from the same unit category as the parameter)

•Sample Set: allows you to select the sample set for which the variable applies

Click the button to add the new parameter list variable to your script at the current cursor location in the Input window.