Documentation of 'com.jstatcom.ts.TSDateRange' Java class
TSDateRange
Skip navigation links
com.jstatcom.ts

Class TSDateRange


  • public final class TSDateRange
extends java.lang.Object
    Holds a range for possible TSDate objects defined as [lowerBound, upperBound] and provides checks against it. The class can be used by classes that allow to specify a date that needs to be validated.

    This class is immutable by design, see (Joshua Bloch, "Effective Java", Item 13) .

    See Also:
    TSDate

    • Constructor Detail

      • TSDateRange

        public TSDateRange()
        Creates a default range starting from the default TSDate with 100 observations.

      • TSDateRange

        public TSDateRange(TSDate t1,
                   int numberOfObs)
        Creates TSDateRange from specified start date and number of observations.
        Parameters:
        t1 -
        numberOfObs - the number of observations within the range
        Throws:
        java.lang.IllegalArgumentException - if numberOfObs <= 0

      • TSDateRange

        public TSDateRange(TSDate t1,
                   TSDate t2)
        Creates TSDateRange from specified start date and end date.
        Parameters:
        t1 - the TSDate to start from (inklusive)
        t2 - the TSDate to end with (inklusive)
        Throws:
        java.lang.IllegalArgumentException - if upperBound is earlier than lowerBound or sub periodicities do not match

    • Method Detail

      • addPeriodsToStart

        public TSDateRange addPeriodsToStart(int periods)
        Gets a new TSDateRange range object with the start date shifted by periods.
        Parameters:
        periods - the number of periods to shift the start date, can be negative, which results in an earlier start, 0 creates a copy of this
        Returns:
        a new range object with the same end date and a new start date
        Throws:
        java.lang.IllegalArgumentException - if new range would be invalid

      • commonRange

        public TSDateRange commonRange(TSDateRange otherRange)
        Returns the biggest date range that is common to this range and another range. If the two ranges do not overlap with at least a single date or if the sub periodicities do not match, null is returned.

        The function is symmetric in the sense that x.commonRange(y).equals(y.commonRange(x)).

        Parameters:
        otherRange - the range to be checked
        Returns:
        common range, null if no common range exists
        Throws:
        java.lang.IllegalArgumentException - if argument is null

      • createSeasDum

        public double[][] createSeasDum(boolean centered,
                                boolean all)
        Creates seasonal dummy series as double[][], see createSeasDumTS(boolean, boolean).
        Parameters:
        centered - the sum over all dummy elements at every time index is 0, if this is true, then all is ignored (and false)
        all - if true then sub periodicity dummies are created, if false then sub periodicity - 1 dummies are created
        Returns:
        dummy data as double[][],null if sub periodicity == 1 or if not enough observations

      • createSeasDumTS

        public TS[] createSeasDumTS(boolean centered,
                            boolean all)
        Creates seasonal dummy series according to the periodicity of this time series. The returned array contains the single dummy series as elements, where the 1st dummy is set to 1 always at the first possible sub period (for example Q1 for quarterly data) and the others respectively in ascending order.

        If the number of observations of this time series is less than the sub periodicity then null is returned, because the resulting array could contain a zero vector.

        Parameters:
        centered - the sum over all dummy elements at every time index is 0, if this is true, then all is ignored (and false)
        all - if true then sub periodicity dummies are created, if false then sub periodicity - 1 dummies are created
        Returns:
        array with the single dummy series, null if sub periodicity == 1 or if not enough observations

      • createShiftDum

        public double[] createShiftDum(TSDateRange shiftRange)
        Creates a double[] that is a shift dummy for this range, see createShiftDumTS(java.lang.String, com.jstatcom.ts.TSDateRange).
        Parameters:
        shiftRange - the range within this range to specify the shift
        Returns:
        the created shift dummy as double[]
        Throws:
        java.lang.IllegalArgumentException - if shiftRange is not a valid range for this range

      • createTrendShiftDum

        public double[] createTrendShiftDum(TSDateRange shiftRange)
        Creates a double[] that is a trend shift dummy for this range, see createTrendShiftDumTS(java.lang.String, com.jstatcom.ts.TSDateRange).
        Parameters:
        shiftRange - the range within this range to specify the trend shift
        Returns:
        the created trend shift dummy as double[]
        Throws:
        java.lang.IllegalArgumentException - if shiftRange is not a valid range for this range

      • createTrendShiftDumTS

        public TS createTrendShiftDumTS(java.lang.String name,
                                TSDateRange shiftRange)
        Creates a time series that is a trend shift dummy for this range. A trend shift dummy has zeros outside the shift range and values [index + 1] within the shift range.
        Parameters:
        name - the name of the new TS
        shiftRange - the range within this range to specify the trend shift
        Returns:
        the created trend shift dummy
        Throws:
        java.lang.IllegalArgumentException - if name is null or empty, or if shiftRange is not a valid range for this range

      • createShiftDumTS

        public TS createShiftDumTS(java.lang.String name,
                           TSDateRange shiftRange)
        Creates a time series that is a shift dummy for this range. A shift dummy has zeros outside the shift range and values [1] within the shift range.
        Parameters:
        name - the name of the new TS
        shiftRange - the range within this range to specify the shift
        Returns:
        the created shift dummy
        Throws:
        java.lang.IllegalArgumentException - if name is null or empty, or if shiftRange is not a valid range for this range

      • encloses

        public java.lang.String encloses(TSDate date)
        Checks whether a given date is within the range defined by this object. If not, an error message is returned.
        Parameters:
        date - the date to check for
        Returns:
        null if within range, error string otherwise

      • encloses

        public java.lang.String encloses(TSDateRange otherRange)
        Checks whether a given date range is included within the range defined by this object. If not, an error message is returned.
        Parameters:
        otherRange - the range to check for
        Returns:
        null if within range, error string otherwise

      • equals

        public boolean equals(java.lang.Object o)
        Overrides equals to provide logical comparison of two different TSDateRange objects.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - object to compare with
        Returns:
        true if start and end dates are both equal, false otherwise

      • format

        public java.lang.String format(java.lang.String description,
                               int space)
        Gets a nicely formatted version of this date range with a description and the number of observations, for example
        sample range: [1960 Q3, 1982 Q4], T = 90
        with "sample range:" as description.
        Parameters:
        description - a desriptive string that will be put in front
        space - the number of spaces between description and the rest, useful for alignment, should be greater than 0, otherwise will be set to 0
        Returns:
        the formatted string

      • dateForIndex

        public TSDate dateForIndex(int index)
        Returns the date corresponding to an index respective to the range.
        Parameters:
        index - can also specify value outside the range
        Returns:
        the date for the index

      • indexForDate

        public int indexForDate(TSDate date)
        Computes the index that a date has respective to the range specified by this object, starting with 0.
        Parameters:
        date - the TSDate to compute the index for
        Returns:
        0 if date is equal to lower bound, difference of periods otherwise
        Throws:
        java.lang.IllegalArgumentException - if subPeriodicities do not match or if date is null

      • indicesForRange

        public int[] indicesForRange(TSDateRange otherRange)
        Computes the indices that a date range has within the range specified by this object, starting with 0.
        Parameters:
        otherRange - the range to compute the bounds for
        Returns:
        array with int[0] = index of lower bound within this range, int[1] = index of upper bound within this range
        Throws:
        java.lang.IllegalArgumentException - if sub periodicities do not match or if otherRange is not in the defined range, because this usually means a programming error

      • lowerBound

        public TSDate lowerBound()
        Gets reference to start date of range.
        Returns:
        the date this range starts from

      • getMergedRange

        public static TSDateRange getMergedRange(TS[] tsArray)
        Gets the merged range of all time series in the given array. The merge range starts from the earliest start date till the latest end date of all series.
        Parameters:
        tsArray - an array of TS objects
        Returns:
        the range starting from the earliest till the latest observation over all time series in the array
        Throws:
        java.lang.IllegalArgumentException - if one TS is null or if sub periodicities are different

      • numOfObs

        public int numOfObs()
        Returns number of observations represented by this range. Every range object contains at least one observation.
        Returns:
        the number of obervations within this range

      • subPeriodicity

        public int subPeriodicity()
        Gets the sub periodicity of this date range. It quantifies the number of sub periods which constitute one main period.
        Returns:
        the sub periodicity

      • upperBound

        public TSDate upperBound()
        Gets reference the last date of the range.
        Returns:
        the date this range ends with

      • hashCode

        public int hashCode()
        Overrides hashCode(), because equals was overwritten. The algorithm was taken from (Joshua Bloch, "Effective Java", Item 8) .
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        hash code

      • mergedRange

        public TSDateRange mergedRange(TSDateRange otherRange)
        Returns the merged date range that starts at the earliest start date and ends at the latest enddate. If the sub periodicities do not match, null is returned.

        The function is symmetric in the sense that x.mergedRange(y).equals(y.mergedRange(x)).

        Parameters:
        otherRange - the range to merge with
        Returns:
        the merged range
        Throws:
        java.lang.IllegalArgumentException - if argument is null or if sub periodicities do not match

      • timeAxisStringArray

        public java.lang.String[] timeAxisStringArray()
        This method returns the range represented as an array of Strings, for example {"1960 Q1", "1960 Q2", ...., "1982 Q4"}.
        Returns:
        time axis as string array

      • toString

        public java.lang.String toString()
        Returns a string representation of the specified range. Do not use for comparisons, but use equals instead.
        Overrides:
        toString in class java.lang.Object
        Returns:
        string representing this range

      • valueOf

        public static TSDateRange valueOf(java.lang.String exp)
        Static initializer that creates a TSDateRange from a string representation. The string should be constructed as TSDate string , TSDate string, and can optionally be enclosed with [ ], for example
        • [1960 Q1, 1982 Q4]
        • 1970, 2003
        • 1953 6/12, 1994 1/12
        • 1/1/60 (5), 10/3/73 (5)
        The information about the sub periodicity must be contained in the strings, therefore 1960.1, 1982.4 is NOT possible, because it is not unique. For the string representation of a TSDate object, see the documentation of its valueOf method.
        Parameters:
        exp - the string to parse to a TSDateRange
        Returns:
        a TSDateRange object created from exp
        Throws:
        java.lang.IllegalArgumentException - if object could not be constructed from given string or if exp == null
        See Also:
        TSDate
Skip navigation links

DMelt 3.0 © DataMelt by jWork.ORG

You see the box below because you did not login.