The DSS-R interface project. (dssrip)

dssrip is a package of R functions to read/write data from HEC-DSS file by making calls to the Java methods exposed in HEC-DSSVue's scripting capability.

Provided under MIT license without warranty.

Install Instructions:

R Libraries: If you haven't already, install the rJava, plyr, reshape2, stringr, and devtools packages.

DSSVue: You need to have a default install of HEC-DSSVue, or download the copy here for 64-bit use. dssrip is now packaged with a file called "jar_config.json" that helps find the appropriate libraries depending on the HEC program used to supply the .jar files. Setting the R option dss_override_location to the directory containing the HEC-DSSVue.exe file from the previously mentioned copy is the quickest way to get dssrip up and running.

Finally, to install dssrip , use the devtools package's install_github function.

devtools::install_github("eheisman/dssrip", INSTALL_opts = "--no-multiarch", ref="tidyup")

The '--no-multiarch' parameter is required to force it to install only the current architecture. If you do not have the options set to point to a version of the javaHeclib.dll file with the same architecture as the version of R that you are running, the install will fail. If you need to use both 64-bit and 32-bit R, you will have to install it once for each version.

Note: for DSS installed elsewhere than Program files

Set the following in your .Rprofile, or run before you install and/or load dssrip:

  options(dss_override_location="c:\\programs\\HEC-DSSVue-v3.0.00.212\\")

Options to help with loading dssrip

Other options that can be used to help the package load correctly by pointing to the correct DSS .jar and library files:

• dss_jvm_parameters string passed to JVM when initialized, allowing memory settings to be altered or other JVM start-up options set. This is untested.
• dss_override_location file path to force dssrip to load a particular set of dss libraries. It will look for all configurations using only this location.
• dss_config_filename filename that points to a jar_config.json file external to the package's default configuration.
• dss_allowed_states list, defaults to c('tested'), filters config file to only allowed states.
• dss_default_config, string, forces to only use config going by this name.

Usage:

Load dssrip as a library with require(dssrip) or library(dssrip.

myFile = opendss(dssFilename) to open a DSS file or to create a new one.

From the returned hecdss object, either accompanying functions can be used to read data, or DSSVue's Jython API can be called. See Chapter 8 of the DSS-Vue manual for a detailed list of Jython API calls.

Several convenience functions for reading timeseries and paried data containers have been added, a brief summary presented below:

getPaths - useful for getting the list of paths in a DSS file and searching through these paths by wildcards or regex strings.

getFullTSC - returns an xts object with the requested data.

getFullDT - similar to getFullTSC, but returns a data.table.

getColumnsByName - read a column from a PairedDataContainer.

TODO List:

• Implement a 'safe' HecDss$get() method that handles a non-existent/'empty' path more gracefully, such as warn if null.
• Implement write methods for TimeSeriesContainers (from xts or data.frame) and PairedDataContainers (from data.frame).

Known Issues:

• dssrip must be loaded before any other packages that require rJava so that dssrip can initialize a JVM with the correct options. This isn't 'nice' behavior, but at the moment it is required. This issue can be mostly resolved by loading dssrip before other packages that depend on rJava, such as XLConnect.
• Time series import does not handle timezones well, xts objects often default to assuming the file is in GMT. This may be a larger issue with how R handles timezones on Windows.
• data.table and rJava both imported and have a naming conflict on the J() function. At the moment the rJava version masks the data.table version, the reverse may be more useful.

Hydroutils

The plotting and misc hydrology functions of this package has been moved to their own package, hydroutils.