com.jstatcom.ts
Class TSDateRange

java.lang.Object
  com.jstatcom.ts.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) .

Author:

Markus Kraetzig

See Also:

TSDate

Constructor Summary

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

TSDateRange(TSDate t1, int numberOfObs)
Creates TSDateRange from specified start date and number of observations.

TSDateRange(TSDate t1, TSDate t2)
Creates TSDateRange from specified start date and end date.

Method Summary

TSDateRange	addPeriodsToStart(int periods) Gets a new TSDateRange range object with the start date shifted by periods.
TSDateRange	commonRange(TSDateRange otherRange) Returns the biggest date range that is common to this range and another range.
double[][]	createSeasDum(boolean centered, boolean all) Creates seasonal dummy series as double[][], see createSeasDumTS(boolean, boolean).
TS[]	createSeasDumTS(boolean centered, boolean all) Creates seasonal dummy series according to the periodicity of this time series.
double[]	createShiftDum(TSDateRange shiftRange) Creates a double[] that is a shift dummy for this range, see createShiftDumTS(java.lang.String, com.jstatcom.ts.TSDateRange).
TS	createShiftDumTS(java.lang.String name, TSDateRange shiftRange) Creates a time series that is a shift dummy for this range.
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).
TS	createTrendShiftDumTS(java.lang.String name, TSDateRange shiftRange) Creates a time series that is a trend shift dummy for this range.
TSDate	dateForIndex(int index) Returns the date corresponding to an index respective to the range.
java.lang.String	encloses(TSDate date) Checks whether a given date is within the range defined by this object.
java.lang.String	encloses(TSDateRange otherRange) Checks whether a given date range is included within the range defined by this object.
boolean	equals(java.lang.Object o) Overrides equals to provide logical comparison of two different TSDateRange objects.
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.
static TSDateRange	getMergedRange(TS[] tsArray) Gets the merged range of all time series in the given array.
int	hashCode() Overrides hashCode(), because equals was overwritten.
int	indexForDate(TSDate date) Computes the index that a date has respective to the range specified by this object, starting with 0.
int[]	indicesForRange(TSDateRange otherRange) Computes the indices that a date range has within the range specified by this object, starting with 0.
TSDate	lowerBound() Gets reference to start date of range.
TSDateRange	mergedRange(TSDateRange otherRange) Returns the merged date range that starts at the earliest start date and ends at the latest enddate.
int	numOfObs() Returns number of observations represented by this range.
int	subPeriodicity() Gets the sub periodicity of this date range.
java.lang.String[]	timeAxisStringArray() This method returns the range represented as an array of Strings, for example {"1960 Q1", "1960 Q2", ...., "1982 Q4"}.
java.lang.String	toString() Returns a string representation of the specified range.
TSDate	upperBound() Gets reference the last date of the range.
static TSDateRange	valueOf(java.lang.String exp) Static initializer that creates a TSDateRange from a string representation.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

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