DSS R Interface Project (2)

A rewrite of dssrip. Supports reading and writing time series and paired data to DSS. Read/write support for DSS grid data is planned.

Supported Operating Systems:

• Windows
• Linux
• MacOS

Supported HEC-DSSVue versions:

• HEC-DSSVue 2.0.1

Setup

You can install the {dssrip2} directly using

remotes::install_github("mkoohafkan/dssrip2")

To build the vignettes on install, use the argument build_vignettes = TRUE.

Monolith

{dssrip2} can connect to HEC-Monolith libraries using

dss_install_monolith()
dss_connect(monolith = TRUE)

If the option dss.monolith is set to TRUE, {dssrip2} will interpret the dss.home option as the HEC-Monolith directory path. By default, {dssrip2} will install HEC-Monolith to %LOCALAPPDATA% (Windows) or ~/.dssrip2/monolith (Unix), but this can be overridden. dss_connect() will retrieve the path using getOption("dss.home") if no path is provided.

To use Monolith automatically, set the following options in your R profile:

options(dss.monolith = TRUE)

Existing HEC-DSSVue install

If you don't want to use the HEC-Monolith libraries, {dssrip2} can connect to an existing HEC-DSSVue program installation instead. To use this option, both a 64-bit install of HEC-DSSVue and a 64-bit JDK are required. To load DSS functionality, call

library(dssrip2)
dss_connect("path/to/HEC-DSSVue")

If the option dss.monolith is set to FALSE (the default), {dssrip2} will interpret the dss.home option as the HEC-DSSVue application directory path.

To use an HEC-DSSVue installation automatically, set the following option in your R profile:

options(
  # replace with the install path on your machine
  dss.home = "C:/Program Files/HEC/HEC-DSSVue"
)

DSS Messaging

To suppress messages from DSS, use

dss_connect(message_level = 1L)

# or after calling dss_connect()
dss_message_level(1L)

If no message level is provided, dss_message_level() will retrieve the level using getOption("dss.messagelevel"). You can also set this option in your .Rprofile:

options(
  dss.messagelevel = 1L
)

Usage

Creating Files

{dssrip2} can create DSS version 6 and 7 files:

tf1 = tempfile(fileext = ".dss")
tf2 = tempfile(fileext = ".dss")

# create a DSS-7 file (default behavior)
dss_create(tf1)
# create a DSS-6 file
dss_create(tf2, version = 6)

{dssrip2} also provides methods to convert between DSS versions:

tf3 = tempfile(fileext = ".dss")
dss_convert(tf2, tf3)

Reading data

{dssrip2} automatically detects the data type being read, so the same function call can be used for reading time series and paired data.

exfile = system.file("extdata/example.dss", package = "dssrip2")

# time series
dss_read(exfile, "/BRANDYWINE CREEK/WILMINGTON, DE/FLOW/01JAN1946/1DAY/USGS/")

# paired data
dss_read(exfile, "/BRANDYWINE CREEK/WILMINGTON, DE/FLOW-STAGE///GENERATED DATA PAIRS/")

DSS files will usually close on their own after some period of inactivity, but it is best practice for users to explicitly close the file when they are finished:

dss_close(exfile)
# or close all files opened by dssrip2 with dss_close_all()

Writing data

{dssrip2} deduces the data type to write based on the supplied R object, so the same function call can be used for reading time series and paired data. However, writing DSS objects requires additional attributes that must be explicitly supplied by the user:

tf = tempfile(fileext = ".dss")
dss_create(tf)

# time series
data(Nile)
nile = data.frame(datetime = as.Date(sprintf("%d-10-01", time(Nile))),
  flow = as.vector(Nile) * 1e8)
nile = dss_add_attributes(nile, list(units = "cubic meters",
  type = "PER-CUM"))
path = "//NILE RIVER/VOLUME//1YEAR/R DATASET/"
dss_write(nile, tf, path)

# paired data
data(CO2)
uptake = reshape(CO2[c("Plant", "conc", "uptake")],
  direction = "wide", idvar = "conc", timevar = "Plant")
names(uptake) = gsub("uptake.", "", names(uptake))
uptake = dss_add_attributes(uptake, list(xtype = "LINEAR",
  ytype = "LINEAR", xunits = "mL/L", yunits = "umol/m^2"))
path = "//PLANT CO2 UPTAKE/CONCENTRATION-UPTAKE///R DATASET/"
dss_write(uptake, tf, path)