In USGS-R/glmtools: Tools for working with the General Lake Model (GLM)

library(rmarkdown)
options(continue=" ")
options(width=60)
library(knitr)
library(glmtools)

Introduction

This package glmtools provides services in support using the General Lake Model (GLM) in R. GLM is a one-dimensional model that balances fluxes of energy and mass as part of dynamically simulating lake physics. The GLM model has been developed as an initiative of the Global Lake Ecological Observatory Network (GLEON) and in collaboration with the Aquatic Ecosystem Modelling Network (AEMON) that started in 2010. The model was first introduced in Leipzig at the 2nd Lake Ecosystem Modelling Symposium in 2012, and has since developed rapidly with application to numerous lakes within the GLEON network and beyond. Authors: Matthew R Hipsey, Louise C Bruce, David P Hamilton. More information about GLM can be found at http://aed.see.uwa.edu.au/research/models/GLM/.

GLM version 3.0 was released in 2019. More information can be found in Hipsey et al 2019: https://www.geosci-model-dev.net/12/473/2019/gmd-12-473-2019.html.

Running GLM requires three mandatory components (in addition to several optional components). The required components include:

1. A GLM executable for the operating system being used (currently there is support for linux, windows, and mojave mac OSX)
2. A glm3.nml file for version 3.0 or a glm2.nml file for version 2.0-2.2, which is a configuration file for the model (see below for specifics)
3. Appropriate meteorological/hydrological driver data (currently in the form of a comma-delimited time-series file)

The model generates a number of optional outputs, but will always create a .nc (netCDF) file which contains the simulation results.

glmtools has a number of utility functions that help with prepping for model runs, executing the model, and analyzing/visualizing the simulation. glmtools also depends on a companion package GLM3r, which contains the executable GLM for each supported platform and creates a unified interface for running the model across these different platforms. GLM3r will be automatically installed when following the instructions below.

Installation

To install glmtools

Install package with dependencies:

install.packages("glmtools", 
    repos = c("http://owi.usgs.gov/R"),
    dependencies = TRUE)

To install GLM3r

Install package with dependencies:

library(devtools)
install_github(repo = 'GLEON/GLM3r')

Using example data built into the package

Find example data directory

library(glmtools)
GLM3r_folder = system.file('extdata', package = 'GLM3r')
glmtools_folder = system.file('extdata', package = 'glmtools')

List files that are included in the example data

dir(GLM3r_folder)
dir(glmtools_folder)

Running GLM

Find current version of GLM included in the package

glm_version()

Citing GLM

A lot of time went into the development of GLM and it is important to give the authors proper credit. To see a current citation for GLM, use the following command in R:

citation('GLM3r')

Update GLM3r if needed

If GLM3r is out of date with the current version of GLM, it is probably because this package has not been updated recently. If you would like to be able to automatically receive update recommendations via RStudio's "Update" button, you will need to add the "http://owi.usgs.gov/R" repository to your RProfile. This can be done with:

source("http://owi.usgs.gov/R/add_gran_repo.R")
update.packages()

Alternatively, the repos argument to update.packages and install.packages can be manually set to point where GLM3r and glmtools live:

update.packages(repos = c("http://owi.usgs.gov/R"))

Running GLM with example data

The contents of GLM3r_folder (i.e., a glm3.nml file and a .csv file for the meteorological drivers) are all that is needed to run GLM from R with GLM3r. The run_glm() function simply takes a folder path to where the glm3.nml is as an input (the sim_folder argument in run_glm). To run example data, files can be moved to a new directory of the user's choosing, or GLM can be run by pointing it directly at the example folder location:

run_glm(sim_folder = GLM3r_folder)

Note that new output files have been added to the simulation directory:

dir(GLM3r_folder)

Running GLM with user data

To run GLM with user-specified data, the formats of the example data should be followed in order to properly run the simulation. Small differences in the glm3.nml file can result in model failures due to the inability of the model to parse certain kinds of text. When real data are used in a simulation, the user can run GLM in the same way that the example simulations were initiated. For example:

run_glm('~/Documents/my_sim')

Below, there are a number of handy functions that support modifying the input data and model configuration.

Interacting with nml files

The glm3.nml file holds the configuration for the model run. This file can be edited in a text editor as plain text, or glmtools can be used to programatically modify the file, reducing user errors and increasing reproducibility. The structure of the file includes content blocks that are delinated by & and \ and parameter names and their values within those sections. For example:

&glm_setup
   sim_name = 'GLMSimulation'
   max_layers = 200
   min_layer_vol = 0.025
   min_layer_thick = 0.1
   max_layer_thick = 1.5
   Kw = 0.25
   coef_mix_conv = 0.33
   coef_wind_stir = 0.23
   coef_mix_shear = 0.3
   coef_mix_turb = 0.51
   coef_mix_KH = 0.3
   coef_mix_hyp = 0.5
/

Commented text is anything that begins with a !, for example:

!-------------------------------------------------------------------------------
! general model setup
!-------------------------------------------------------------------------------
!
! sim_name         [string]  title of simulation       
! max_layers       [integer] maximum number of layers  
! min_layer_vol    [real]    minimum layer volume (m3 * 1000)      
! min_layer_thick  [real]    minimum layer thickness (m)  
! max_layer_thick  [real]    maximum layer thickness (m) 
! Kw               [real]    background light attenuation (m**-1)
! coef_mix_conv    [real]    mixing efficiency - convective overturn
! coef_wind_stir   [real]    mixing efficiency - wind stirring
! coef_mix_turb    [real]    mixing efficiency - unsteady turbulence effects
! coef_mix_shear   [real]    mixing efficiency - shear production
! coef_mix_KH      [real]    mixing efficiency - hypolimnetic Kelvin-Helmholtz turbulent billows
! coef_mix_hyp     [real]    mixing efficiency - hypolimnetic turbulence
! deep_mixing      [bool]    flag to disable deep-mixing
!
!-------------------------------------------------------------------------------

These commented lines are ignored by the model. There are advantages to using R to both run the model and modify the model parameters, including increased efficiency and the reproducibility aspects mentioned above.

Reading nml files into R

glmtools reads nml files into memory using the read_nml function. This function returns an R list() that is of class nml (this object class is used to support special functions to this list, including a pretty print(nml) output). glmtools automatically parses the glm3.nml document and converts the contents into the appropriate types in R (for example, .true. becomes TRUE in R) To read the example nml into memory:

eg_nml <- read_nml(nml_file = file.path(glmtools_folder,'glm3.nml'))

and display the nml contents within R:

eg_nml

See that eg_nml is an nml object, but behaves just like a list in R:

class(eg_nml)
names(eg_nml)
eg_nml[[1]][1:4]

Getting information from nml

Even though the nml is basically just an R list, there are a number of convienence functions that help get data out of the list structure. For finding a value from a parameter, just specify the name of the parameter and use the get_nml_value() function:

# water clarity
get_nml_value(eg_nml, 'Kw')

or get values from a parameter that has a vector of values:

# initial conditions for depths
get_nml_value(eg_nml, 'the_depths')

Changing nml contents

Likewise, nml values can be easily modified with the helper function set_nml():

# water clarity
eg_nml <- set_nml(eg_nml, 'Kw', 1.4)
# note how the value is now changed:
get_nml_value(eg_nml, 'Kw')

set_nml() can use a parameter name and a corresponding value, or it can accept a list to set multiple parameters at once:

eg_nml <- set_nml(eg_nml, arg_list = list('Kw' = 1.2, 'max_layers' = 480))
get_nml_value(eg_nml, 'max_layers')

But the nml object is still just in memory for the R session. In order for these changes to have an impact on the simulations, the nml needs to be written to file

Writing modified nml files

The nml object can be easily written to a user-specified location by using the write_nml() function:

# define a location for the file to be written to. Here it will overwrite the existing `nml` file:
write_path <- file.path(GLM3r_folder,'glm3.nml')
write_nml(eg_nml, file = write_path)

A new simulation can be run with the modified nml file:

run_glm(GLM3r_folder)

Visualizing GLM output

plotting water temperatures

nc_file <- file.path(GLM3r_folder, 'output/output.nc')
plot_var(nc_file = nc_file, var_name = 'temp')

plotting multiple variables

sim_vars(file = nc_file)
plot_var(nc_file = nc_file, var_name = c('temp','u_mean'))

Validating the model against field observations

# sim_folder <- run_example_sim(verbose = FALSE)
nc_file <- file.path(glmtools_folder, 'output/output.nc')
field_file <- file.path(glmtools_folder, 'LakeMendota_field_data_hours.csv')

create a diagnostic output within R for thermocline depth:

thermo_values <- compare_to_field(nc_file, field_file,
                          metric = 'thermo.depth', as_value = TRUE)

Do the same for water temperatures vs field observations:

temp_rmse <- compare_to_field(nc_file, field_file,
                          metric = 'water.temperature', as_value = FALSE)
print(paste(temp_rmse,'deg C RMSE'))

Plotting comparision of water temperature vs field observations:

plot_var_compare(nc_file, field_file, precision = 'hours', var_name = 'temp') ## makes a plot!

There are many ways to customize these graphs

plot_var_compare(nc_file, field_file, var_name = 'temp',interval = 2, precision = 'hours', 
                 legend.title = 'Temp degC',text.size = 14,obs.color = 'black',obs.shape = 17,
                 zlim = c(0,40),color.palette = 'BrBG') 

Compare lake elevation with field measurements:

field_file <- file.path(glmtools_folder, 'LakeMendota_stage_USGS05428000.csv')

plot_compare_stage(nc_file, field_file) ##makes a plot!

glmtools function index

| Function | Title | | ------------- |:-------------| | calibrate_sim | Calibrates GLM-AED2 variables to improve fit between observed and simulated data | | compare_to_field | compare metric for GLM vs field observations | | get_evaporation | get evaporation from GLM simulation | | get_hypsography | retrieve hypsography information | | get_ice | get ice depth from GLM simulation | | get_nml_value | gets a nml value according to an arg_name | | get_surface_height | get surface height from GLM simulation | | get_var | get a variable from a GLM simulation | | get_wind | get wind speed from GLM simulation | | model_diagnostics | run diagnostics on model results | | plot_var_compare | Plot matching heatmaps for modeled and observed variables | | plot_var_nc | plot variables from a GLM simulation | | plot_var_df | plot variables from a data.frame | | read_field_obs | read in field data into a data.frame | | read_nml | read in a GLM simulation *.nml file | | resample_sim | get subset of time from a generic timeseries data.frame | | resample_to_field | match GLM water temperatures with field observations | | set_nml | sets values in nml object | | sim_metrics | get possible metrics for comparing GLM outputs to field | | summarize_sim | creates GLM simulation summary outputs | | validate_sim | run diagnostics on model results vs observations | | write_nml | write GLM *.nml for a GLM simulation |

Running AED with GLM (Aquatic EcoDynamics model)

coming soon

USGS-R/glmtools documentation built on March 26, 2024, 5:43 p.m.