Package hec.io

Class TimeSeriesContainer

java.lang.Object
hec.io.DataContainer
hec.io.TimeSeriesContainer
All Implemented Interfaces:
IVerticalDatumOperations<TimeSeriesContainer,mil.army.usace.hec.metadata.VerticalDatumException>, Serializable, Cloneable
Direct Known Subclasses:
TimeSeriesContainerVertDatum
public class TimeSeriesContainer extends DataContainer implements Cloneable, Serializable, IVerticalDatumOperations<TimeSeriesContainer,mil.army.usace.hec.metadata.VerticalDatumException>
This is a simple generic container class that holds time series data, and some related information The purpose of this class is to pass time series data to plot and tabulate functions. The class does not know where the data came from (or is going). It does not contain any reference or connection to any database.
See Also:

  • Field Details

    • values

      public double[] values

    • times

      public int[] times

    • quality

      public int[] quality

    • numberValues

      public int numberValues

    • interval

      @Deprecated public int interval
      Deprecated.
      Do not access this variable directly. The interval may be represented in second, minutes, etc. depending on the timeGranularitySeconds use getTimeIntervalSeconds() instead for consistency
      interval between data points. the resolution of the interval is based on timeGranularitySeconds

    • startTime

      @Deprecated public int startTime
      Deprecated.
      use startHecTime instead, set with setStartTime

    • endTime

      @Deprecated public int endTime
      Deprecated.
      use endHecTime instead, set with setEndTime

    • startHecTime

      public HecTime startHecTime

    • endHecTime

      public HecTime endHecTime

    • units

      public String units
      the Units i.e. CFS

    • type

      public String type

    • precision

      public int precision

    • subLocation

      public String subLocation

    • parameter

      public String parameter
      The C Part of the DSS Path

    • subParameter

      public String subParameter

    • timeZoneID

      public String timeZoneID

    • timeZoneRawOffset

      public int timeZoneRawOffset

    • julianBaseDate

      public int julianBaseDate

    • timeGranularitySeconds

      public int timeGranularitySeconds

    • retrieveAllTimes

      public boolean retrieveAllTimes

    • quality7

      public int[][] quality7

    • sizeEachQuality7

      public int sizeEachQuality7

    • inotes

      public int[][] inotes

    • sizeEachNote

      public int sizeEachNote

    • cnotes

      public String[] cnotes

    • numberDepths

      public int numberDepths

    • profileDepths

      public double[] profileDepths

    • profileValues

      public double[][] profileValues

    • unitsProfileDepths

      public String unitsProfileDepths

    • unitsProfileValues

      public String unitsProfileValues

    • profileLabel

      public String profileLabel

  • Constructor Details

    • TimeSeriesContainer

      public TimeSeriesContainer()
      create new empty TimeSeriesContainer

  • Method Details

    • setUnits

      public void setUnits(String dataUnits)
      set the units (i.e. CFS)
      Parameters:
      dataUnits - the new units

    • getUnits

      public String getUnits()
      get the units
      Returns:
      the data units

    • setType

      public void setType(String dataType)
      set the data type
      Parameters:
      dataType - the new data type

    • getType

      public String getType()
      get the data type
      Returns:
      the data type

    • set

      public int set(double[] dataValues, HecTimeArray hecTimes)
      Sets the data and time arrays, including start and end times, and number of values. Uses the time granularity of the HecTimeArray and will adjust (upwards) if times would exceed capacity. Also, will adjust julian base date if needed. (i.e., you can pass an array of any times, up to 5,000,000 years, and not have to compute the base or granularity yourself.)
      If the start or end time are different than the first and last times in the time array, be sure to set them after this function
      Time Granularity timeGranularityInSecondsMax DaysMax Years
      One second 1 24,855 69
      One minute 60 1,491,308 4,083
      One hour 3600 89,478,485 244,978
      One day 86400 2,147,483,6475,879,489(current limit for TSC)
      One year 31536000 (nominal)(not supported at this time)
      Parameters:
      dataValues -
      hecTimes -
      Returns:
      status 0 = okay, < 0 fail

    • setTimes

      public int setTimes(HecTimeArray hecTimes)
      set the times
      Parameters:
      hecTimes - the new times values
      Returns:
      0 if successful

    • getJulianDateAndTimeGranularity

      public static int[] getJulianDateAndTimeGranularity(HecTimeArray hecTimes, int dataValuesLength)
      Parameters:
      hecTimes -
      Returns:
      [0] julianBaseDate [1] time granularity in seconds, null on error

    • set

      public int set(double[] dataValues, HecTimeArray hecTimes, int julBaseDate, int timeGranularityInSeconds)
      Generally not a public item. Use set(double dataValues[], HecTimeArray hecTimes) instead.
      Sets the data and time arrays, julian base date, and the time granularity in seconds, including start and end times, and number of values.
      Parameters:
      dataValues -
      hecTimes -
      julBaseDate -
      timeGranularityInSeconds -
      Returns:
      status 0 = okay, < 0 fail

    • set

      public int set(HecTimeArray hecTimes, int julBaseDate, int timeGranularityInSeconds)

    • set

      public int set(double[] dataValues, long[] minutes)
      Sets the data and times array, converting long minutes to int minutes, and setting the julian base date and time granularity, if required to keep within int boundary. (i.e., you not have to compute the base or granularity yourself.)
      Parameters:
      dataValues -
      minutes -
      Returns:

    • setValues

      public int setValues(double[] dataValues)
      Sets the data values array. You must set the start / end times and other parameters in other functions.
      Note: This is used only for regular interval data, where a time array is not required. Always use the set(values, times) function when you have a time array.
      Parameters:
      dataValues -
      Returns:
      status 0 = okay, < 0 fail

    • setStartTime

      public void setStartTime(HecTime start)
      Sets the start time, if different than the default start time (the first value in the times array.) This can be used by irregular interval data to show that there is no data between this time and first time in the times array.
      This must be called after setting times array, if not using default
      Parameters:
      start -

    • getStartTime

      public HecTime getStartTime()
      Returns the start time. This may, or may not, be different than the first time in the times array. (usually, it is the same.)
      Returns:
      start time

    • setEndTime

      public void setEndTime(HecTime end)
      Sets the end time, if differnt than the default end time (the last value in the times array.) This can be used by irregular interval data to show that there is no data between the last time in the times array and this value
      This must be called after setting times array, if not using default

    • getEndTime

      public HecTime getEndTime()
      Returns the end time. This may, or may not, be different than the last time in the times array. (usually, it is the same.)
      Returns:
      end time

    • getTimes

      public HecTimeArray getTimes()
      Return the times array as an HecTimeArray. Accounts for julian base date and time granularity.
      Returns:
      time array as HecTimeArray

    • getHecTime

      public HecTime getHecTime(int index)
      Gets the time for an individual ordiante in the times array. Normally this is used when you only want one ordinate's time. If you want multiple times, use getTimes() instead.
      Parameters:
      index -
      Returns:

    • getTimeInterval

      @Deprecated public int getTimeInterval()
      Deprecated.
      use getTimeIntervalSeconds() instead as the resolution of the returned interval is based on the timeGranularitySeconds
      get the time interval that the data is at
      Returns:
      the time interval

    • getTimeIntervalSeconds

      public int getTimeIntervalSeconds()
      get the time interval in seconds that the data is at
      Returns:
      the time interval in seconds

    • getNumberValues

      public int getNumberValues()
      Returns the number of values in the dataset.
      Returns:
      the number of values

    • getValues

      public double[] getValues()
      Return a copy of the data values array
      Returns:
      data values

    • getValue

      public double getValue(int index)
      Returns a single value according to the index.
      Parameters:
      index - the index (0 based) to get the value at
      Returns:

    • getValue

      public double getValue(HecTime time)
      Return the time series value at the specified time, do linear interpolation as necessary.
      Note: A computationally intensive function; please use only when needed (i.e., don't call to retrieve all or most data.)
      Parameters:
      time - time of data
      Returns:
      double value of data at specified time

    • setQuality

      public int setQuality(int[] qualityIn)
      Sets the quality array. This must be the same length as the data values array
      Returns:
      status 0 = okay, < 0 fail

    • getQuality

      public int[] getQuality()
      Return a copy of the quality array
      Returns:
      quality

    • setQuality7

      public int setQuality7(int[][] qualityIn)

    • getQualitySize

      public int getQualitySize()

    • getQuality7

      public int[][] getQuality7()
      Return a copy of the quality array
      Returns:
      quality

    • setCharacterNotes

      public void setCharacterNotes(String[] characterNotes)

    • getCharacterNotes

      public String[] getCharacterNotes()

    • setProfile

      public int setProfile(double[] profileDepths, double[][] profileValues)

    • getProfileNumberDepths

      public int getProfileNumberDepths()

    • getProfileDepths

      public double[] getProfileDepths()

    • getProfileValues

      public double[][] getProfileValues()

    • setProfileDepthsUnits

      public void setProfileDepthsUnits(String unitsProfileDepths)

    • setProfileValuesUnits

      public void setProfileValuesUnits(String unitsProfileValues)

    • setProfileLabel

      public void setProfileLabel(String profileLabel)

    • getProfileDepthsUnits

      public String getProfileDepthsUnits()

    • getProfileValuesUnits

      public String getProfileValuesUnits()

    • getProfileLabel

      public String getProfileLabel()

    • getMinutes

      public int[] getMinutes()
      Gets the times in minutes. Will convert the time array to minutes, if there is a different time granularity (rare). If there is a base date, you must account for it; use getMinutesLong() instead. See usesExtendedDates() to know if this is necessary
      Returns:
      time array in minutes.

    • getMinutesLong

      public long[] getMinutesLong()
      Gets the times in minutes. Will convert the time array to minutes, if there is a different time granularity (rare), and accounts for a base date.
      Returns:

    • getMinutesLong

      public long getMinutesLong(int index)
      Gets the time, in minutes, for a specific ordinate. Accounts for time granularity and base date
      Parameters:
      index -
      Returns:
      time for index

    • getJulianBaseDate

      public int getJulianBaseDate()
      Gets the base date for this object
      Returns:
      julian base date (days from Jan 1, 1900)

    • setJulianBaseDate

      public void setJulianBaseDate(int julBaseDate)
      Set the julain base date (defualt is zero).
      Parameters:
      julBaseDate - *

    • getTimeGranularitySeconds

      public int getTimeGranularitySeconds()
      Gets the time granularity for the time array. This is normally 60 (seconds), but the acceptable values are:
      Time Granularity timeGranularityInSecondsMax DaysMax Years
      One second 1 24,855 69
      One minute 60 1,491,308 4,083
      One hour 3600 89,478,485 244,978
      One day 86400 2,147,483,6475,879,489(current limit for TSC)
      One year 31536000 (nominal)(not supported at this time)
      Returns:

    • setTimeGranularitySeconds

      public void setTimeGranularitySeconds(int timeGranularityInSeconds)
      Sets the time granularity for time time array This is normally 60 (seconds), but the acceptable values are:
      Time Granularity timeGranularityInSecondsMax DaysMax Years
      One second 1 24,855 69
      One minute 60 1,491,308 4,083
      One hour 3600 89,478,485 244,978
      One day 86400 2,147,483,6475,879,489(current limit for TSC)
      One year 31536000 (nominal)(not supported at this time)
      Parameters:
      timeGranularityInSeconds -

    • usesExtendedDates

      public boolean usesExtendedDates()
      Determines if extended dates are used and times in long (or HecTime) need to be used.
      Returns:
      true if so.

    • clone

      public Object clone()
      clone the TimeSerieContainer
      Overrides:
      clone in class Object
      Returns:
      a copy of the TimeSeriesContainer

    • clone

      public void clone(TimeSeriesContainer tsc)
      clone this TimeSeriesContainer into tsc
      Parameters:
      tsc - the filled in TimeSeriesContainer

    • setTimeZoneID

      public void setTimeZoneID(String timeZoneIdentifier)
      Set the DATA time zone identifier. This is not necessarily the location time zone, as many data sets are reported in UTC.
      Parameters:
      timeZoneIdentifier -

    • getTimeZoneID

      public String getTimeZoneID()
      get the DATA time zone identifier. This is not necessarily the location time zone, as many data sets are reported in UTC.
      Returns:
      the time zone identifier

    • convertTimeZone

      public void convertTimeZone(TimeZone toTimezone)
      converts the data, start and end time to a new time zone
      Parameters:
      toTimezone - destination time zone

    • convertTimeZone

      public boolean convertTimeZone(String toTimezoneID, boolean observeDST)
      converts the data, start and end time to a new time zone
      Parameters:
      toTimezoneID - destination time zone
      observeDST - true to observe DST

    • trimToTime

      public boolean trimToTime(HecTime newStartTime, HecTime newEndTime, boolean bShrinkOnly)

    • trimToTime

      public boolean trimToTime(HecTime newStartTime, HecTime newEndTime)

    • getDataSetStats

      public boolean getDataSetStats(TsDataSetStats dataStats)

    • minimumValue

      public double minimumValue()
      get the minimum value of the data
      Returns:

    • maxmimumValue

      @Deprecated public double maxmimumValue()
      Deprecated.
      use maximumValue()
      get the maximum value from the time series values. retained for backwards compatibility
      Returns:
      the maximum value

    • maximumValue

      public double maximumValue()
      get the maximum value from the time series values
      Returns:
      the maximum value

    • mean

      public double mean()
      get the mean value from the time series values
      Returns:
      the mean value

    • getShortName

      public String getShortName()
      Returns the short String representation of the time series id, the location name, version name, parameter name separated by ' ', and if it exists the version date separated by ':'
      Returns:
      String

    • getVersionName

      public String getVersionName()
      Returns the String representation of the DSS Version VERSION - SUB_VERSION or "" if the values are null
      Returns:
      String

    • getParameterName

      public String getParameterName()
      Returns the String representation of the DSS Parameter PARAMETER - SUB_PARAMETER or "" if the values are null
      Returns:
      String

    • getLocationName

      public String getLocationName()
      Returns the String representation of the DSS Location LOCATION - SUB_LOCATION or "" if the values are null
      Returns:
      String

    • setCompressData

      public void setCompressData(boolean compress)

    • compressData

      public boolean compressData()

    • getAsString

      public String getAsString()
      get the TimeSeriesContainer as a String
      Returns:
      the String representation

    • getAsXML

      public String getAsXML()
      get the TimeSeriesContainer as a XML String
      Returns:
      the XML String representation

    • removeAllMissing

      public int removeAllMissing()
      Remove all missing values from the data array, reducing the size of the time, values, and quality arrays. Returns the resultant number of valid values.
      Returns:
      int

    • makeAscending

      public void makeAscending()
      rearrrange time and data arrays so that all times are ascending Remove any undefinded times and reset array sized to reflect Primarily for irregular interval data

    • expandVerticalDatum

      public TimeSeriesContainer expandVerticalDatum()
      Returns a new TimeSeriesContainerVertDatum object constructed from this object and the vertical datum info in the supplementalInfo field of this object. The vertical datum info is removed from the supplementalInfo field of the new object.
      Specified by:
      expandVerticalDatum in interface IVerticalDatumOperations<TimeSeriesContainer,mil.army.usace.hec.metadata.VerticalDatumException>
      Returns:
      Either the new object as described above or a clone of this object. In either case this object is not modified. A clone of this object is returned if it is already a TimeSeriesContainerVertDatum object, if the supplementalInfo field doesn't contain vertical datum information, or if an error occurs during the operation.

    • collapseVerticalDatum

      public TimeSeriesContainer collapseVerticalDatum()
      Returns a new TimeSeriesContainer object constructed from this object, with the TimeSeiresContainerVertDatum.vdc field collapsed into vertical datum info in the supplementalInfo field (overwriting any existing vertical datum info there)
      Specified by:
      collapseVerticalDatum in interface IVerticalDatumOperations<TimeSeriesContainer,mil.army.usace.hec.metadata.VerticalDatumException>
      Returns:
      Either the new object as described above or this object. In either case this object is not modified. This object is returned if it is not a TimeSeriesContainerVertDatum object or an exception occurs during the operation.

    • printToConsole

      public void printToConsole()
      Prints time series data to System.out

    • printToConsole

      public void printToConsole(int maxNumberToPrint)
      Prints time series data to System.out
      Parameters:
      maxNumberToPrint - limit on how many points to print

    • allMissing

      public boolean allMissing()

    • hasValidProfileData

      public boolean hasValidProfileData()

    • setVersionDate

      public void setVersionDate(mil.army.usace.hec.data.timeseries.VersionDate versionDate)
      sets the VersionDate
      Parameters:
      versionDate - the version date to be set

    • getVersionDate

      public mil.army.usace.hec.data.timeseries.VersionDate getVersionDate()
      gets the VersionDate
      Returns:
      VersionDate

    • getFullVersionedName

      public String getFullVersionedName()
      Returns the String representation the time series id, and if it exists the version date separated by ':'
      Returns:
      String

    • getVerticalDatumMetadata

      public Optional<mil.army.usace.hec.metadata.VerticalDatum> getVerticalDatumMetadata()