Overview of HEC API Scripting Part 1 and 2: DSS Files, DataContainer, HecTime, HecMath
This report delves into the HEC API scripting involving DSS files, DataContainer, HecTime, and HecMath. It covers important classes, accessing files, and the distinction between DataContainers and HecMath objects. Additionally, it compares Python and Java, highlighting their differences in interpreted vs. compiled code, object-oriented programming approaches, and library functionalities. The use of Jython, which compiles Python code into Java byte-code, is also discussed. Detailed information on DSS data formats, pathnames, and ranges is provided, along with insights into the HEC Java API for working with HEC-DSS files, time series data, and more.
Download Presentation
Please find below an Image/Link to download the presentation.
The content on the website is provided AS IS for your information and personal use only. It may not be sold, licensed, or shared on other websites without obtaining consent from the author. Download presentation by click this link. If you encounter any issues during the download, it is possible that the publisher has removed the file from their server.
Presentation Transcript
HEC API SCRIPTING PART 1 AND 2: DSS FILES, DATACONTAINER, HECTIME, HECMATH Evan Heisman, PE Eric Novotny, PhD USACE IWR-HEC The views, opinions and findings contained in this report are those of the authors(s) and should not be construed as an official Department of the Army position, policy or decision, unless so designated by other official documentation.
2 OUTLINE Overview of HEC DSS API Important Classes Accessing files DataContainers vs HecMath objects HecTime
3 PYTHON VS JAVA Python is interpreted, compiled to a byte-code at runtime. Java is compiled to a byte-code prior to runtime. Java has a very strict form of Object Oriented Programming (OOP), Python is OOP but lets you easily write functional or procedural code Each has a standard library with helpful functions. Jython has all of Java s, most of Python s.
4 PYTHON VS JYTHON Jython compiles Python code to Java byte-code, runs inside the Java Virtual Machine Jython uses Python syntax and library Jython 2.5 ~= Python 2.5 Jython 2.7 ~= Python 2.7 Jython has access to Java s libraries Import from Java s library as if Python modules.
5 DSS DATA FORMATS Pathnames: /A/B/C/D/E/F/ /watershed/location/parameter/date/interval/version/ Watershed (A Part) Often name for a river or blank Location (B Part) physical location (gage name, resv. name) model s location name (junction/node/component name) Parameter (C Part) ELEV, STAGE, STOR, FLOW, FLOW-MAX
6 DSS DATA FORMATS Range / Date (D Part) For time-series data, the start date of the values or the range of values contained (for a combined record) Interval (E Part) Time step between values, or irregular block size. 1DAY, 1HOUR, IR-DECADE Records broken up differently depending on interval Version (F Part) Usually the source or model the data came from (USGS-RAW, CC:WY1929:RESSIM-FLOODMODEL1)
7 DSSVUE
8 SCRIPTING API The HEC Java API used by all HEC Java applications provides common functionality Reading/writing HEC-DSS files Working with time series, gridded data, and rating curves Generating plots and tables Documentation included with HEC-DSSVue at link specified below CWMS-Vue and HEC-DSSVue provides API for accessing user interface and creating plugins Documentation available by selecting Help Help from the menu bar or pressing F1 https://www.hec.usace.army.mil/confluence/dssdocs/dssvueum/ in your default browser HEC-ResSim to build utility scripts in model or to script model behavior in rules and state variables HEC-ResSim-specific API documentation provided in the HEC-ResSim script editor; ResSim JavaDocs CWMS CAVI to access watershed and forecast information, interact w/ user interface, and be executed in the program sequence during forecast computes CWMS CAVI-specific API documentation provided in the CWMS CAVI script editor Other languages with good Java support, like R and Matlab can be linked to it
9 HEC-DSSVUE AND CWMS-VUE SCRIPTING HEC-DSSVue scripts normally work with data in local HEC-DSS files, but have the full Python- and Java-provided APIs as well as the HEC-provided APIs available to perform any type of task CWMS-Vue scripts have the following additional capabilities when logged in Ability to work with HEC-DSS files on the CWMS server (remote files) Ability to work with data in the CWMS database The DBAPI module provides access to the CWMS database using methods that mimic those used to access HEC-DSS files Online help for scripting with HEC-DSSVue or CWMS-Vue is available by pressing F1 at the main program window or selecting Help Help from the main program window menu bar
11 HEC CLASSES HecDss dealing with files DataContainer: TimeSeriesContainer timeseries PairedDataContainer - curves HecMath: math operations TimeSeriesMath PairedDataMath HecTime - timestamps Plot and Tablulate create custom plots, adjust properties
12 DSS (HEC.HECMATH.DSS) To read and write dss files, you must use the the java objects DSS and DSSFile and their methods which were designed to interact with DSS files. To open a DSS file: from hec.hecmath import DSS myFile = DSS.open(str fileName) myFile = DSS.open(str fileName, str timeWindow) # limits to data within timeWindow myFile = DSS.open(str fileName, str startTime, str endTime) # another way Returns a DSSFile object The file handle for the DSSFile opened NOTE DSS is a static class. You do not need to create an object of type hec.hecmath.DSS in order to use it.
TIMESERIESCONTAINER OBJECTS 13 TimeSeriesContainer is a subclass of DataContainer. It is a simple, generic container class that holds time series data and some related information. Since most of the member data is public, the class includes few methods for accessing and manipulating the data. DataContainer and TimeSeriesContainer objects are described in detail in the HEC- DSSVue User s Manual TimeSeriesContainer Data Only Used for Plotting Use get() & put() HecDss methods tsContainer = dssFile.get( /A/B/C/D/E/F/ ) dssFile.put(tsContainer)
14 TIMESERIESCONTAINER OBJECTS
15 TIME SERIES CONTAINER TimeSeriesContainers have Properties not Methods: tsc.watershed = Green River tsc.location = OakVile tsc.parameter = Stage tsc.version = OBS tsc.units = FEET tsc.type = INST-VAL tsc.interval = 60 tsc.values = [Values List] tsc.times = [int list from HecTimes] tsc.startTime = times[0] tsc.endTime = times[-1] tsc.numberValues = len(values)
16 HECMATH OBJECTS AnHecMath object represents data that can be stored in an HEC-DSS file (aka, a dataset). The subclasses of HecMath are: PairedDataMath represents lookup tables (e.g., ratings) TimeSeriesMath represents time series data TimeSeriesMath objects have many methods that allow manipulation or analysis of the whole time series, but they do not allow access to individual data values.4
17 TIME SERIES MATH Use a TimeSeriesContainer to set the data in a TimeSeriesMath Object: tsMath.setData(tsContainer) TimeSeriesMath objects use Methods: setLocation(string location) setParameter(string parameter) setPathname(string pathname) setTimeInterval(string interval) setType(string type) setUnits(string units) setVersion(string version) setWatershed(string watershed)
18 HECMATH OBJECTS TimeSeriesMath.getData()returns a reference to the TimeSeriesContainer object contained in the TimeSeriesMath object. NOTE TimeSeriesMath also has a getTimeSeriesContainer() method, but it returns a copy of the data in the TimeSeriesMath object so changes to the copy do not affect the TimeSeriesMath object s data. TimeSeriesMath objects may be created from TimeSeriesContainer objects by using the constructor: tsMath = TimeSeriesMath(tsContainer) TimeSeriesMath Data and Methods Used for Math Functions Use read() & write() HecDss methods tsMath = dssFile.read( /A/B/C/D/E/F/ ) dssFile.write(tsMath)
19 TIMESERIESMATH METHODS HecMath methods, which include TimeSeriesMath methods, are indexed and described in detail in the HEC-DSSVue User s Manual.
21 DATACONTAINER AND HECMATH COMPARISON Read from file Write to file Timeseries series of values with associated timestamps: flow, stage, storage Paired Data paired points or sets of curves, e.g. rating curves stage-damage tables HecMath myFile.read(pathname) myFile.read(pathname, timeWindow) myFile.write(HecMath object) myTsMath = TimeSeriesMath.createInstance(myTSC) # OR myTsMath = TimeSeriesMath() myTsMath.setData(myTSC) myPdMath.interpolate(xVal) Returns HecMath newTsMath = myTsMath.add(otherTsMath) maxVal = newTsMath.max() summaryHydrograph = newTsMath.cyclicAnalysis() DataContainer myFile.get(pathname) myFile.get(pathname, True), whole timeseries if D-part is blank myFile.put(DataContainer object) myTSC = myTsMath.getData() myPDC.xOrdinates = [ ] # single list myTSC.values = [ ] myTSC.times = [ ] myPDC.yOrdinates = [[ ],[ ]] # list of lists Returns DataContainer Can use HecMath constructors and static methods to convert # you could do this maxVal = max(myTSC.values)
22 HECTIME METHODS The HecTime class and its methods are described in detail in the HEC-DSSVue User s Manual (also available from HEC-DSSVue Help menu).
23 HECTIME CLASS Useful for manipulating timestamps Functions to add/subtract time, compare times, find where a timestamp is on a calendar (e.g. get month or day of week) Internally wraps an integer (typically minutes since midnight Dec 31st 1900) Integer is what gets stored in TimeSeriesContainer.times Day of midnight value depends on TimeSeriesContainer s type
24 HECTIME OBJECTS An HecTime object represents a specific date and time. HecTime objects are initialized to specific resolutions SECOND_INCREMENT MINUTE_INCREMENT (default) HOUR_INCREMENT DAY_INCREMENT The specific resolution affects how time is calculated when added and how it is reported. Granularity In Seconds Granularity in Minutes Granularity in Hours Granularity in Days SECOND_INCREMENT 1 MINUTE_INCREMENT 60 1 HOUR_INCREMENT 3600 60 1 DAY_INCREMENT 86400 1440 24 1
25 HECTIME OBJECTS HecTime objects have an internal value that specifies the time as an offset in resolution units from a base date. For resolution units of minutes, hours or days, the base date is 31 December 1899 00:00 (Thus, 01Jan1900 at 0000 is day 1). For resolution units of seconds, the base date is 19Jan1970 at 0000 (which is the UNIX epoch). For dates before the base date, the offset is negative. The HecTime folder in the APIs tree provides a list of the the HecTime methods and gives you access to the javadocs for HecTime.
26 CLASSES WITH SIMILAR FUNCTIONALITY HEC-ResSim sRunTimeStep vs HecTime RunTimeStep uses integer to track model timestep HecTime used to manipulate and examine values HecTime vs java.time or python modules time/datetime User preference, HecTime expected by many HEC API calls Different methods and fields, cannot substitute one for another in API calls
27 CLASSES WITH SIMILAR FUNCTIONALITY TSRecordvsTimeSeriesContainervsTimeSeriesMath TSRecord (interface) TSRecordImpl (class) internal to ResSim for model variables and state variables TimeSeriesContainer and TimeSeriesMath Inherits from DataContainer / HecMath Used in DSSVue and other programs Allow manipulation of values directly for TSC, or with math functions for TSM
28 REVIEW hec.hecmath.DSS class to call DSS.open(filename) Use this class to manipulate whole files e.g. bulk copy records read/write HecMath to do mathematical operations get/put DataContainer (TimeSeriesContainer / PairedDataContainer) to access metadata/values HecTime to do calculations with timestamps
