Skip to contents

Quick Start with dssrip2

Source: vignettes/quickstart.rmd
quickstart.rmd

The R package dssrip2 provides a simple interface to read and write HEC-DSS files.

Settings Java Options

The dssrip2 uses the rJava package, which provides a Java Virtual Machine (JVM) shared by all R packages in a session. The default JVM parameters are very modest and usually insufficient for working with larger DSS files. Before launching dssrip2 (or any other R package that uses rJava, as the JVM is launched by the first package that requires it) you should at least set the JVM total memory parameter. For example, set the JVM total memory to 8000 MB:

options(java.parameters = "-Xmx8000M")

For simplified startup, set the options in your .Rprofile. For more information on setting Java parameters, see the Java Parameters vignette.

Connecting to DSS

Using HEC Monolith

The recommended method of connecting to DSS is to download the HEC Monolith jar files, which provides standalone access to HEC DSS functionality without requiring the installation of the HEC-DSSVue application.

By default, HEC Monolith installs to APPDATA. For simplified startup, you can add the following options to .Rprofile:

options(dss.monolith = TRUE)

Using an existing HEC-DSSVue install

Alternatively, if you have HEC-DSSVue installed on your machine you can call dss_connect() and supply the path to the DSSVue install folder:

library(dssrip2)

dss_connect("C:/Program Files/HEC/HEC-DSSVue")

For simplified startup, you can add the following options to .Rprofile:

options(dss.home = "C:/Program Files/HEC/HEC-DSSVue",
  dss.monolith = FALSE)

Reading DSS data

dssrip2 provides an example dataset:

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

This file contains five datasets:

  1. A daily flow timeseries
  2. A 15-minute stage timeseries
  3. An annual peak flow irregular timeseries
  4. An annual peak stage irregular timeseries
  5. A flow-elevation paired datasets

The DSS catalog can be read into R using dss_catalog():

dss_catalog(exfile, condensed = TRUE)
#> [1] "/BRANDYWINE CREEK/WILMINGTON, DE/FLOW/01Oct1946 - 30Sep2012/1DAY/USGS/"                   
#> [2] "/BRANDYWINE CREEK/WILMINGTON, DE/FLOW-ANNUAL PEAK/30Apr1947 - 30Oct2012/IR-CENTURY/USGS/" 
#> [3] "/BRANDYWINE CREEK/WILMINGTON, DE/FLOW-STAGE///GENERATED DATA PAIRS/"                      
#> [4] "/BRANDYWINE CREEK/WILMINGTON, DE/GAGE HEIGHT/31Aug2012 - 30Sep2012/15MIN/USGS/"           
#> [5] "/BRANDYWINE CREEK/WILMINGTON, DE/STAGE-ANNUAL PEAK/01JAN1900 - 01JAN2000/IR-CENTURY/USGS/"

dss_catalog() supports regex pattern matching to subset the path list:

dss_catalog(exfile, "/.*/.*/FLOW.*/.*/.*/.*/")
#> [1] "/BRANDYWINE CREEK/WILMINGTON, DE/FLOW/01Oct1946 - 30Sep2012/1DAY/USGS/"                  
#> [2] "/BRANDYWINE CREEK/WILMINGTON, DE/FLOW-ANNUAL PEAK/30Apr1947 - 30Oct2012/IR-CENTURY/USGS/"
#> [3] "/BRANDYWINE CREEK/WILMINGTON, DE/FLOW-STAGE///GENERATED DATA PAIRS/"

dssrip2 also provides a variety of functions are provided to assist with manipulating DSS paths:

path = "/BRANDYWINE CREEK/WILMINGTON, DE/FLOW/01Oct1946 - 30Sep2012/1DAY/USGS/"

# split path into parts
dss_parts_split(path)
#>                  A              B    C                     D    E    F
#> 1 BRANDYWINE CREEK WILMINGTON, DE FLOW 01Oct1946 - 30Sep2012 1DAY USGS

# replace path part
dss_parts_replace(path, list(B = "WILMINGTON, DELAWARE"))
#> [1] "/BRANDYWINE CREEK/WILMINGTON, DELAWARE/FLOW/01Oct1946 - 30Sep2012/1DAY/USGS/"

# combine parts into path
dss_parts_combine(list(A = "BASIN", B = "LOCATION", C = "PARAMETER",
  D = "", E = "1DAY", F = "EXAMPLE"))
#> [1] "/BASIN/LOCATION/PARAMETER//1DAY/EXAMPLE/"

dssrip2 provides the function dss_read() to read DSS datasets into R. The output format is automatically deduced from the DSS data type:

  • DSS regular and irregular time series are converted into two-column data frames.
  • DSS paired datasets are converted into two-column (or more) data frames.
  • DSS grid data is converted into SpatRasters (see package:terra for more information).
# read in a regular timeseries
dss_read(exfile, "/BRANDYWINE CREEK/WILMINGTON, DE/FLOW//1DAY/USGS/")
#>     datetime flow
#> 1 1946-10-02  235
#> 2 1946-10-03  220
#> 3 1946-10-04  210
#> 4 1946-10-05  200
#> 5 1946-10-06  195
#>  [ reached 'max' / getOption("max.print") -- omitted 24102 rows ]

# read in a single chunk of a regular timeseries
dss_read(exfile, "/BRANDYWINE CREEK/WILMINGTON, DE/FLOW/01JAN1948/1DAY/USGS/",
  full = FALSE)
#>     datetime flow
#> 1 1948-01-02  522
#> 2 1948-01-03 2780
#> 3 1948-01-04 1030
#> 4 1948-01-05  590
#> 5 1948-01-06  518
#>  [ reached 'max' / getOption("max.print") -- omitted 361 rows ]

# read in irregular timeseries
dss_read(exfile, "/BRANDYWINE CREEK/WILMINGTON, DE/FLOW-ANNUAL PEAK//IR-CENTURY/USGS/")
#>     datetime flow-annual peak
#> 1 1947-05-01             4730
#> 2 1948-09-11             5160
#> 3 1948-12-31             4940
#> 4 1950-08-04             4610
#> 5 1950-11-26            11500
#>  [ reached 'max' / getOption("max.print") -- omitted 62 rows ]

# read in a paired dataset
dss_read(exfile, "/BRANDYWINE CREEK/WILMINGTON, DE/FLOW-STAGE///GENERATED DATA PAIRS/")
#>   flow stage
#> 1 2000  5.00
#> 2 3260  6.24
#> 3 3470  6.36
#> 4 3470  6.43
#> 5 3680  6.62
#>  [ reached 'max' / getOption("max.print") -- omitted 62 rows ]

Writing DSS data

dssrip2 Also provides write support for time series and paired data containers. As with reading data, dssrip2 determines the appropriate DSS dataset type from the structure of the supplied input.

outfile = tempfile(fileext = ".dss")

dss_create(outfile)

# create a regular timeseries from the LakeHuron dataset
data(LakeHuron)
lake_huron = data.frame(date = as.Date(sprintf("%d-10-01",
  time(LakeHuron))), elev = as.vector(LakeHuron))
lake_huron_path = "/GREAT LAKES/LAKE HURON/ELEV//1YEAR/R DATASET/"

# additional attributes are required to write DSS data
lake_huron = dss_add_attributes(lake_huron, list(units = "feet",
  type = "INST"))

dss_write(lake_huron, outfile, lake_huron_path)
#> Warning: Converting supplied timestamps to 'POSIXct' class, using default
#> timezone Etc/GMT+0

# create an irregular timeseries from the airquality dataset
data(airquality)
aq = do.call(rbind, lapply(split(airquality, airquality$Month),
  function(x)
    x[which.max(x$Temp), ]))
temps = data.frame(date = as.Date(sprintf("1973-%d-%d",
  aq$Month, aq$Day)), temperature = aq$Temp)
temps_path = "/NEW YORK/NEW YORK CITY/TEMPERATURE//IR-YEAR/R DATASET/"

# additional attributes
temps = dss_add_attributes(temps, list(units = "degrees F",
  type = "INST"))

dss_write(temps, outfile, temps_path)
#> Warning: Converting supplied timestamps to 'POSIXct' class, using default
#> timezone Etc/GMT+0

# create paired dataset from the Loblolly dataset
data(Loblolly)
growth = reshape(Loblolly, direction = "wide", idvar = "age", timevar = "Seed")
names(growth) = gsub("height.", "seed_", names(growth))
growth_path = "//LOBLOLLY PINES/AGE-HEIGHT///R DATASET/"

# additional attributes
growth = dss_add_attributes(growth, list(xunits = "years",
  yunits = "feet", xtype = "UNT", ytype = "UNT"))

dss_write(growth, outfile, growth_path)

It is good practice to close a DSS file once you are finished working with it. For the most part, dssrip2 will call the file’s $done() method at the completion of every operation to implicitly close the file, but you can also explicitly close a file:

dss_close(outfile)

# or close all open/implicitly closed files
dss_close_all()

That’s it!