com.jstatcom.ts
Class TS

java.lang.Object
  com.jstatcom.ts.TS

public final class TS
extends java.lang.Object

This class pools information about a particular time series:

• name
• observations
• start date
• project

Missing values at the beginning and the end are automatically truncated when the data is set. Every TS object must have at least one observation, the data is therefore initialized with new double[1]. Any attempt to set the data to a zero length array or to null is ignored.

Once a time series is created, it is not possible anymore to change the underlying data, instead, a new TS must be instantiated. The type may be changed. Type changes throw a TS_TYPE_CHANGED PropertyChangeEvent.

This class is thread-safe. All access to mutable data is synchronized.

Author:

A. Benkwitz, Markus Kraetzig

Field Summary

static java.lang.String

TS_TYPE_CHANGED Type changed property event name.

Constructor Summary

TS(double[] newObservations, java.lang.String newName)
Creates a TS object with the type being guessed and the project is the default.

TS(double[] newObservations, java.lang.String newName, TSDate newDate)
Creates a TS object, with the type being guessed and the project is the default.

TS(double[] newObservations, java.lang.String newName, TSDate newDate, TSTypes tsType)
Creates a TS object with the default project.

TS(double[] newObservations, java.lang.String newName, TSDate newDate, TSTypes tsType, TSProject newProject)
Preferred constructor for a TS object with everything explicitely specified.

TS(TS ts)
TS copy-constructor.

Method Summary

void	addPropertyChangeListener(java.beans.PropertyChangeListener listener)
TS	createDiff(int periods) Applies the difference operator to a copy of the series and returns the new series with the name oldName + "_d" + Math.abs(periods).
TS	createLog() Applies the log operator to a copy of the series and returns the new series with the name oldName + "_log".
boolean	equals(java.lang.Object o) Overrides equals() to provide logical comparison of two different TS.
static double[][]	getMergedData(TS[] tsArray) Gets the merged data of all time series in the given array.
int	hashCode() Overrides hashCode, because equals was overwritten.
java.lang.String	name() Returns the identifying name of this time series object.
int	numOfObs() Returns the number of observations.
void	print(java.io.PrintStream p) Prints this object to the argument print stream with the time index and the respective observation next to it.
TSProject	project() Gets project that this TS belongs to.
TSDateRange	range() Returns the TSDateRange defining the beginning and the end of this time series.
void	removePropertyChangeListener(java.beans.PropertyChangeListener listener)
void	setName(java.lang.String newValue) Sets the name of this time series to a new name.
void	setTSProject(TSProject newTSProject) Sets project that this TS belongs to.
void	setTSType(TSTypes newTSType) Sets the type of this time series.
TSDate	start() Returns the date when the first observation in this TS occurs.
java.lang.String	toString() String representation of a timeseries.
TSTypes	type() Gets the type of this time series.
double	valueAt(int i) Returns the observation at index i.
double	valueAt(TSDate date) Returns the observation at a given date.
double[]	values() Returns a copy of the array of observations.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

TS_TYPE_CHANGED

public static final java.lang.String TS_TYPE_CHANGED

Type changed property event name.

See Also:

Constant Field Values

Constructor Detail

TS

public TS(double[] newObservations,
          java.lang.String newName)

Creates a TS object with the type being guessed and the project is the default. For the start date the TSDate default constructor is used.

Parameters:

newObservations - the array of observations

newName - the identifying name

Throws:

java.lang.IllegalArgumentException - if newName is null

TS

public TS(double[] newObservations,
          java.lang.String newName,
          TSDate newDate)

Creates a TS object, with the type being guessed and the project is the default.

Parameters:

newObservations - the array of observations

newName - the identifying name

newDate - the date of the first observation.

Throws:

java.lang.IllegalArgumentException - if newName or newDate is null

TS

public TS(double[] newObservations,
          java.lang.String newName,
          TSDate newDate,
          TSTypes tsType)

Creates a TS object with the default project.

Parameters:

newObservations - the array of observations

newName - the identifying name

newDate - the date of the first observation.

tsType - the type or null if it should be automatically defined

Throws:

java.lang.IllegalArgumentException - if newName or newDate is null

TS

public TS(double[] newObservations,
          java.lang.String newName,
          TSDate newDate,
          TSTypes tsType,
          TSProject newProject)

Preferred constructor for a TS object with everything explicitely specified.

Parameters:

newObservations - the array of observations

newName - the identifying name

newDate - the date of the first observation.

tsType - the type or null if it should be automatically defined

newProject - the time series project

Throws:

java.lang.IllegalArgumentException - if newName or newDate is null

TS

public TS(TS ts)

TS copy-constructor.

Parameters:

ts - the TS to copy

Method Detail

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)

createDiff

public TS createDiff(int periods)

Applies the difference operator to a copy of the series and returns the new series with the name oldName + "_d" + Math.abs(periods). If periods is the same as the sub periodicity and the sub periodicity > 1, the new name is oldName + "_dseas".

Parameters:

periods - the number of lags of the part being subtracted from the original series, it may also be < 0

Returns:

the differenced time series or null if the operation failed.

createLog

public TS createLog()

Applies the log operator to a copy of the series and returns the new series with the name oldName + "_log".

Returns:

TS the logged time series or null, if the operation failed.

equals

public boolean equals(java.lang.Object o)

Overrides equals() to provide logical comparison of two different TS.

Overrides:

equals in class java.lang.Object

Parameters:

o - the object to compare

Returns:

true if name, start, all observations and type are the same, false otherwise

values

public double[] values()

Returns a copy of the array of observations.

Returns:

copied data array

valueAt

public double valueAt(int i)

Returns the observation at index i.

Parameters:

i - the index to retrieve the data from

Returns:

the respective observation if i is within the range of this time series, otherwise Double.NaN

valueAt

public double valueAt(TSDate date)

Returns the observation at a given date.

Parameters:

date - the TSDate for the observation, if it is invalid, then Double.NaN is returned

Returns:

the respective observation if date is within the range of this time series, otherwise Double.NaN

getMergedData

public static double[][] getMergedData(TS[] tsArray)

Gets the merged data 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 data starting from the earliest till the latest observation over all time series in the array, filled with Double.NaN if no observation is available for a series in the array at a certain date

Throws:

java.lang.IllegalArgumentException - if one TS is null or if sub periodicities are different

name

public java.lang.String name()

Returns the identifying name of this time series object.

Returns:

the name of this series

numOfObs

public int numOfObs()

Returns the number of observations.

Returns:

number of observations.

start

public TSDate start()

Returns the date when the first observation in this TS occurs.

Returns:

the date of the first observation.

range

public TSDateRange range()

Returns the TSDateRange defining the beginning and the end of this time series.

Returns:

the range for the observations

project

public TSProject project()

Gets project that this TS belongs to.

Returns:

the current project

type

public TSTypes type()

Gets the type of this time series.

Returns:

the type of this series

See Also:

setTSType(com.jstatcom.ts.TSTypes)

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

print

public void print(java.io.PrintStream p)

Prints this object to the argument print stream with the time index and the respective observation next to it.

Parameters:

p - the stream to print to

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)

setName

public void setName(java.lang.String newValue)

Sets the name of this time series to a new name. The name must not be null or empty. The name must begin either with '_' .

Parameters:

newValue - the new name.

Throws:

java.lang.IllegalArgumentException - if newValue is null, empty or if it does not start with a letter or '_'

setTSProject

public void setTSProject(TSProject newTSProject)

Sets project that this TS belongs to.

Parameters:

newTSProject - the new project

setTSType

public void setTSType(TSTypes newTSType)

Sets the type of this time series. If the argument is null, the type is determined internally to be either deterministic or endogenous.

Parameters:

newTSType - the new type of the TS

See Also:

type()

toString

public java.lang.String toString()

String representation of a timeseries. Do not use for comparisons, implementation might change without notice.

Overrides:

toString in class java.lang.Object

Returns:

a string representing this series