Collections
HEC-DSS supports time series ensembles through the use of "collections", a group of similar datasets for the same time window. Typically, ensembles are historical or statistical conditions applied to current conditions for (short term) future conditions. For example, all historical precipitation for current month can be used a future precipitation for a hydrology model to obtain a potential flow dataset for each year.
A collection is implemented by using an F Part naming convention which starts with "C:" followed by the collection sequence, the pipe symbol "|" and then the regular F part. The sequence character string must be 6 characters long and may be simple integers or alpha-numeric strings, but must be unique within the collection and sortable. Characters following the separator will be the same for all members in the collection. DSS is able to identify a member of a collection by its F Part string.
An example collection pathname is:
/YUBA/SMARTSVILLE/FLOW/01JAN1997/1HOUR/C:000042|OPERATION A/
An example collection plot (spaghetti plot) is:
HEC-DSS links collection records together so that you can get a list of all the pathnames in a collection quickly. A collection list is where the only difference in the pathnames (including the D part) is the collection sequence, which is the number (or string) between the C: and | in the F part of the pathname. You will still need to read/write each collection record separately, even though the collection records are linked automatically.
Collections are not limited to time series data; they are only based on the F part of the pathname following the collection sequence. Currently, the HEC Java library contains classes to read, manipulate and display collection sets. For example, an entire collection set can be read or written at one time using the Java classes. For the C API, each collection recored has to be read or written individually.
Functions to handle Collections in the C API include:
zsetCollectionSequence
char* zsetCollectionSequence(char* pathname, int sequenceNumber)
Returns a new (malloc'ed) collection pathname formed from the supplied pathname and sequence number. The input pathname can be either a collection pathname or a regular (non-collection) pathname. Remember to free the return pathname when done.
zcollectionCat
int zcollectionCat(long long *ifltab, const char *seedPathname, zStructCatalog *catStruct)
Returns all pathnames in a collection, given one of the pathnames in that collection. The pathnames are returned in zStructCatalog and the number of pathnames is the return parameter. Avoid using wild characters in the seed pathname.
Example: Time-Series Collection
#include <stdio.h>
#include <string.h>
#include "heclib.h"
// Example time series collection
// We are going to create a collection set from existing data
// The collection set can be displayed or mainpulated by the Java classes
int ExampleCollection()
{
long long ifltab[250];
zStructTimeSeries *tss1, *tss2;
zStructCatalog *catStruct;
char *pathname;
int status, I, numberPaths, versionNumber;
// Be sure that the file exists
versionNumber = zgetFileVersion("C:/temp/Sample7.dss");
if (versionNumber == 0) {
printf("This example requires that the file C:/temp/Sample7.dss exists.\n");
printf("It should be copied and converted from the Sample.dss file included with HEC-DSSVue.\n");
return -1;
}
status = zopen(ifltab, "C:/temp/Sample7.dss");
if (status != STATUS_OKAY) return status;
// Get a sorted list of the pathnames for historical maximum temperature records
// (See the catalog documentation for more info.)
catStruct = zstructCatalogNew();
numberPaths = zcatalog(ifltab, "//SACRAMENTO/TEMP-MAX/*/1DAY/OBS/", catStruct, 1);
if (numberPaths < 1) {
printf("This example requires that the file C:/temp/Sample7.dss exists.\n");
zstructFree(catStruct);
return -1;
}
// Read each year of data, shift to the year 3000 and change the F part to a collection sequence
for (i = 0; i < numberPaths; i++) {
tss1 = zstructTsNew(catStruct→pathnameList[i]);
status = ztsRetrieve(ifltab, tss1, 0, 0, 0);
if (status != STATUS_OKAY) {
printf("Retrieval of record %s failed. status: %d\n", catStruct->pathnameList[i], status);
zstructFree(tss1);
zstructFree(catStruct);
zclose(ifltab);
return -1;
}
// Create a pathname with the collection sequence
pathname = zsetCollectionSequence(catStruct->pathnameList[i], i);
// Create a new struct with the year 3000 dates (never reuse a ts struct!)
tss2 = zstructTsCloneNewTimes(tss1, pathname, "01Jan3000", "2400", "", "");
if (i < (numberPaths - 1)) free(pathname);
zstructFree(tss1);
// Truncate any leap years to 365
if (tss2->numberValues > 365)tss2->numberValues = 365;
status = ztsStore(ifltab, tss2, 0);
if (status != STATUS_OKAY) {
printf("Storage of record %s failed. status: %d\n", pathname, status);
zstructFree(tss2);
zstructFree(catStruct);
zclose(ifltab);
return -1;
}
zstructFree(tss1);
zstructFree(tss2);
}
zstructFree(catStruct);
// Now get a list of the collection pathnames
// Need a seed pathname, one of the pathnames in the collection group
zpathnameSetPart(pathname, strlen(pathname) + 1, "01Jan3000", 4);
catStruct = zstructCatalogNew();
numberPaths = zcollectionCat(ifltab, pathname, catStruct);;
free(pathname);
printf("There were %d pathnames found for this collection\n", numberPaths);
if (numberPaths > 0) {
if (numberPaths > 5) numberPaths = 5;
printf("The first %d pathnames in the collection are:\n", numberPaths);
for (i = 0; i < numberPaths; i++) {
printf(" %s\n", catStruct→pathnameList[i]);
}
}
// Now retrieve the data to do something with
// Note, often you may need to set a time window.
// For example, if you had two months of hourly data,
// it might be 20April3000 to 30June3000, using zstructTsNewTimes
if (catStruct->numberPathnames > 0) {
for (i = 0; i < catStruct->numberPathnames; i++) {
tss2 = zstructTsNew(catStruct→pathnameList[i]);
status = ztsRetrieve(ifltab, tss2, 0, 0, 0);
if (status != STATUS_OKAY) {
return;
}
// Do something with the data here
zstructFree(tss2);
}
}
zstructFree(catStruct);
zclose(ifltab);
return 0;
}There were 133 pathnames found for this collection
The first 5 pathnames in the collection are:
//SACRAMENTO/TEMP-MAX/01Jan3000/1Day/C:000000|OBS/
//SACRAMENTO/TEMP-MAX/01Jan3000/1Day/C:000001|OBS/
//SACRAMENTO/TEMP-MAX/01Jan3000/1Day/C:000002|OBS/
//SACRAMENTO/TEMP-MAX/01Jan3000/1Day/C:000003|OBS/
//SACRAMENTO/TEMP-MAX/01Jan3000/1Day/C:000004|OBS/
