vic: VIC model run for each gridcells

In VICmodel: The Variable Infiltration Capacity (VIC) Model

Description

Run the VIC model for each gridcells by providing several meteorological and vegetation (optional) forcing data and land surface parameters (soil, vegetation, snowband (optional), lake (optional)).

Usage

vic(forcing, soil, veg, output_info = NULL, veglib = NULL,
  snowband = NULL, lake = NULL, forcing_veg = NULL,
  veg_force_types = c("albedo", "LAI", "fcanopy"), parall = FALSE)

## S3 method for class 'vic_output'
print(x, ...)

Arguments

forcing	meteorological forcing data. Must be a list of numeral matrix with the name of one of "PREC", "TEMP", "SW", "LW", "WIND", "VP" and "PRESS". See details.
soil	soil parameter data. Must be a data frame or numeral matrix.
veg	vegetation parameters. Must be a list containing several matrixs. See details.
output_info	A list containing output contents and timescales (optional). See details.
veglib	Vegetation library parameters (optional). Would using the library of the NLDAS and GLDAS when not provided.
snowband	A data frame or numeral matrix containing snow band parameters (optional). See details.
lake	A dataframe or numeric matrix containing lake parameters (optional).
forcing_veg	Vegetation forcing data (optional). See details.
veg_force_types	Type names of vegetation forcing data. Must be provided when using vegetation forcing data.
parall	Determined if run the VIC parallely. If it is TRUE, registerDoParallel() in package doParallel is need to be used before run the VIC.
x	Return of vic for print.
...	Other arguments to print.

Details

Function vic is used to run the VIC model in a "classic" style (Run the model gridcell by gridcell). Meteorological forcing data, soil parameters and vegetation parameters are the basic necessary inputs for the VIC model.

Value

A list containing output tables, time table and model settings.

VIC in R supports multiple "output tables" with different output timescales. For example, you can put soil moisture and soil temperature in a table with monthly timescale and put runoff, baseflow in another table with daily timescale.

You can use print() to print the summary of the returns. The returns includes:

output	One or several "output tables" and each of them containing several output variables, which is determined by the output_info parameter. The name of the "table" would also be which output_info determined. Each "table" containing several numerial matrices corresponding to the output variables. Each row of the matrices is output data for a time step while each column is output data for a gridcell.
timetable	Containing initiation time, model running time and final (orgnizate outputs) time of the VIC model running.
global_options	Global options setted for this model run.
output_infos	Output settings determined by the output_info parameter.

Forcing data

Parameter forcing must be a list containing several numeral matrixs that containing forcing data. Name of each matrix (similar to key in dictionary in Python) must be the specific type names including "PREC", "TEMP", "SW", "LW", "WIND", "VP" and "PRESS", indicating precipitation [mm], air temperature [degree C], shortwave radiation [W], longwave radiation [W], wind speed [m/s], vapor pressure [kPa], and atmospheric pressure [kPa]. All of those types are necessary to run the VIC model except "LW" and "PRESS". Each row of the matrixs is corresponding to a time step while each column of the matrixs is corresponding to a gridcell, which other must be the same as those in soil parameter.

Longwave radiation (LW) and atmospheric pressure (PRESS) could be estimated via other forcing data when not supplied. Longwave radiation would be estimated using the Konzelmann formula (Konzelmann et al., 1996) while atmospheric pressure would be estimated based on the method of VIC 4.0.6, by assuming the sea level pressure is a constant of 101.3 kPa.

Soil parameters

Parameter soil must be a numeric data frame or matrix that containing soil parameters. The style of this is the same as the soil parameter file of the classic VIC, that is, each row restores the parameter of a cell while each column restores one type of parameter. Detail see http://vic.readthedocs.io/en/master/Documentation/Drivers/Classic/SoilParam/ in the official VIC documentation webside.

Vegetation parameter

Parameter veg must be a list containing several numeral matrixs that Those matrixs restore the vegetation parameters that are corresponding to each gridcells, and those order must be the same as the soil parameters. Each row of the matrix restores the parameters of a vegetation type while each column restores a type of parameter. Each row should be like:

c(veg_type, area_fract, rootzone_1_depth,
  rootzone_1_fract, rootzone_2_depth, rootzone_2_fract, ...)

which is similar to the veg param file of the classic VIC. If the source of LAI, fcanopy or albedo is set to veg params, it must be follow by a sequence of param value for each month in a year. The rows of veg would be similar as:

c(veg_type, area_fract, rootzone_1_depth,
  rootzone_1_fract, rootzone_2_depth, rootzone_2_fract,
  LAI_Jan, LAI_Feb, LAI_Mar, ..., LAI_Dec,
  fcan_Jan, fcan_Feb, fcan_Mar, ..., fcan_Dec,
  albedo_Jan, albedo_Feb, albedo_Mar, ..., albedo_Dec)

Output information (Optional)

Parameter output_info is used to determine the output variables, output timescale (monthly, daily, sub-daily, or each 6 days, etc.), aggregration of data (mean, sum, max, min, start or end) when output timescale is larger than input timescale. It should be a list like that:

output_info <- list(timescale = 'timescale', aggpar = aggpar,
                    outvars = c('OUT_TYPE_1', 'OUT_TYPE_2', 'OUT_TYPE_3', ...),
                    aggtypes = c('aggtype_1', 'aggtype_2', 'aggtype_3'))

And a output table (a list containing the output variables in matrix form) named "output" would be returned. You can obtain the variables use code like res$output$OUT_.... Names of the items in the list (e.g. timescale, outvars) must be those specified as follows:

timescale	Output timescale, including 'never', 'step', 'second', 'minute', 'hour', 'day', 'month', 'year', 'date', and 'end'. 'never' means never output, 'step' means use the input timestep, 'date' means output at a specific date, and 'end' means output at the last timestep.
aggpar	If 'timescale' is set to those except 'never', 'date' and 'end', it determined the intervals of the timescale to pass before output. If 'timescale' is 'day' and 'aggpar' is 6, that means data outputs per 6 days. If 'timescale' is 'date', it should be a Date type and it could be generated use as.Date('YYYY-mm-dd').
outvars	A sequence of names of output data types. The available data types please see the VIC official documentation website at http://vic.readthedocs.io/en/master/Documentation/OutputVarList/.
aggtypes	Optional. A sequence of string determine how to aggregrate the output data when output timescale is larger than input timescale, Including 'avg' (average), 'begin', 'end', 'max', 'min', 'sum', 'default'. Each string in it must be corresponding to those in 'outvars'. If input timescale is daily, while output timescale is monthly, and aggtype is 'begin', it would output the data of the first day of each month.

If multiple output timescales are used, the outputs could be divided into several lists and take them into a list as input, e.g.:

out_info <- list(
  wb = list(timescale = 'hour', aggpar = 6,
            outvars = c('OUT_RUNOFF', 'OUT_BASEFLOW', 'OUT_SOIL_MOIST'),
            aggtypes = c('sum', 'sum', 'end')),
  eb = list(timescale = 'day', aggpar = 1,
            outvars = c('OUT_SWE', 'OUT_SOIL_TEMP'),
            aggtypes = c('avg', 'min'))
)

This would return two output tables named "wb" and "eb" respectively.

Vegetation library (Optional)

Parameter veglib is a matrix or a numeric dataframe of a vegetation parameter library. Each row determines a type of vegetation while each column determines a parameter, including ovetstory (or not), LAI for each month in a year, etc. If not provided, it would use the default vegetation library of the NASA Landsurface Data Assimination System (LDAS) (Rodell et al., 2004), which contains 11 types of vegetation with the vegetation classification of UMD.

Snowband (elevation band) (Optional)

Parameter snowband is a matrix or a numeric dataframe determines the elevation band information for each gridcells. Each row determines the band information of a gridcell while a column determines the values of the elevation band parameters. This devide a single gridcell into several parts with dfferent elevation to run individually, to further consider the sub-gridcell heterogeneity of elevation and the resulted heterogeneity air temperature in a gridcell with higher variation of elevation. The information of elevation bands includes area fraction, mean elevation and fraction of precipitation falled to the gridcell of each elevation band of the gridcell. The order of the rows must be coresponding to the gridcells determined in the soil parameters. Each row should be like:

c(GRID_ID, AFRAC_1, AFRAC_2, ..., AFRAC_n, ELEV_1, ELEV_2, ..., ELEV_n,
  PFRAC_1, PFRAC_2, ..., PFRAC_n)

GRID_ID is the id of the grid; AFRAC_i means area fraction of each elevation band; ELEV_i is their mean elevation; PFRAC_i is there precipitation fraction. n is the number of elevation bands for each gridcell and is determined by 'nbands' in the global options. This can be set used veg_param('nbands', n).

Vegetation forcing data (Optional)

Parameter forcing_veg must be a list containing several 3D numeral arrays that containing vegetation forcing data such as LAI, albedo and fraction of canopy. Different to parameter forcing, each 3D array in the list is the vegetation forcing data for a single gridcell, and the order of the 3D arrays must be corresponding to the order of the gridcells determined in the soil parameter.

The dimensions of a 3D array are represents:

[timestep, vegetation tile, forcing type].

That is, the first dimension determines the data of the timesteps, the second dimension determines the data for the different vegetation tiles in this gridcell that determined by the vegetation parameters, while the third dimension determined the data of different forcing data type (LAI, albedo or fcanopy), which should be corresponding to the parameter veg_force_types.

References

Hamman, J. J., Nijssen, B., Bohn, T. J., Gergel, D. R., and Mao, Y. (2018), The Variable Infiltration Capacity model version 5 (VIC-5): infrastructure improvements for new applications and reproducibility, Geosci. Model Dev., 11, 3481-3496, <doi:10.5194/gmd-11-3481-2018>.

Konzelmann, T, Van de Wal, R.S.W., Greuell, W., Bintanja, R., Henneken, E.A.C., Abe-Ouchi, A., 1996. Parameterization of global and longwave incoming radiation for the Greenland Ice Sheet. Global Planet. Change, 9:143-164, <doi:10.1016/0921-8181(94)90013-2>.

Liang, X., Lettenmaier, D. P., Wood, E. F., and Burges, S. J. (1994), A simple hydrologically based model of land surface water and energy fluxes for general circulation models, J. Geophys. Res., 99(D7), 14415-14428, <doi:10.1029/94JD00483>.

Liang, X., and Xie, Z., 2001: A new surface runoff parameterization with subgrid-scale soil heterogeneity for land surface models, Advances in Water Resources, 24(9-10), 1173-1193.

Rodell, M., Houser, P.R., Jambor, U., Gottschalck, J., Mitchell, K., Meng, C.-J., Arsenault, K., Cosgrove, B., Radakovich, J., Bosilovich, M., Entin, J.K., Walker, J.P., Lohmann, D., and Toll, D. (2004), The Global Land Data Assimilation System, Bull. Amer. Meteor. Soc., 85(3), 381-394.

Examples

# This is a sample data to run VIC.
data(STEHE)

forcing <- STEHE$forcing
soil <- STEHE$soil
veg <- STEHE$veg

# Set the global options for a 7-days run.
vic_param('start_year', 1949)
vic_param('start_month', 1)
vic_param('start_day', 1)
vic_param('end_year', 1949)
vic_param('end_month', 1)
vic_param('end_day', 7)
vic_param('step_per_day', 24)
vic_param('snow_step_per_day', 24)
vic_param('runoff_step_per_day', 24)

# Run VIC.
outputs <- vic(forcing, soil, veg)
print(outputs)

# Use user defind outputs and snowband parameters.
vic_param('nbands', 5)
band <- STEHE$snowbands

out_info <- list(
  wb = list(timescale = 'hour', aggpar = 6,
            outvars = c('OUT_RUNOFF', 'OUT_BASEFLOW', 'OUT_SOIL_MOIST'),
            aggtypes = c('sum', 'sum', 'end')),
  eb = list(timescale = 'day', aggpar = 1,
            outvars = c('OUT_SWE', 'OUT_SOIL_TEMP'),
            aggtypes = c('avg', 'min'))
)

outputs <- vic(forcing, soil, veg, snowband = band, output_info = out_info)
print(outputs)

# Example of parallelization

library(doParallel)
registerDoParallel(cores=4)
outputs <- vic(forcing, soil, veg, snowband = band, parall = TRUE)
stopImplicitCluster()
print(outputs)

VICmodel documentation built on May 1, 2019, 9:09 p.m.