com.github.signaflo.timeseries

Class TimeSeries

java.lang.Object

com.github.signaflo.timeseries.TimeSeries

All Implemented Interfaces:

DataSet

public final class TimeSeries
extends Object
implements DataSet

An immutable sequence of observations taken at regular time intervals.

Method Summary

Modifier and Type	Method and Description
TimeSeries	aggregate(TimePeriod timePeriod) Aggregate the time series up to the given time period.
TimeSeries	aggregate(TimeUnit timeUnit) Aggregate the observations in this series to the given time unit.
TimeSeries	aggregateToYears() Aggregate the observations in this series to the yearly level.
double[]	asArray() Retrieve the time series of observations.
List<Double>	asList() retrieve the observations as a list.
double	at(int index) Retrieve the value of the time series at the given index.
double	at(OffsetDateTime dateTime) Retrieve the value of the time series at the given date-time.
double	autoCorrelationAtLag(int k) The correlation of this series with itself at lag k.
double[]	autoCorrelationUpToLag(int k) Every correlation coefficient of this series with itself up to the given lag.
double	autoCovarianceAtLag(int k) The covariance of this series with itself at lag k.
double[]	autoCovarianceUpToLag(int k) Every covariance measure of this series with itself up to the given lag.
TimeSeries	backTransform(double boxCoxLambda) Perform the inverse of the Box-Cox transformation on this series and return the result in a new time series.
TimeSeries	centeredMovingAverage(int m) Return a moving average of order m if m is odd and of order 2 × m if m is even.
double	correlation(DataSet otherData) The unbiased sample correlation of these observations with the observations contained in the given data set.
double	covariance(DataSet otherData) The unbiased sample covariance of these observations with the observations contained in the given data set.
Map<OffsetDateTime,Integer>	dateTimeIndex() Retrieve the mapping of observation times to array indices for this series.
TimeSeries	demean() Remove the mean from this series and return the result as a new time series.
TimeSeries	difference() Difference this time series once at lag 1 and return the result as a new time series.
static double[]	difference(double[] series, int times) Difference the given series the given number of times at lag 1.
static double[]	difference(double[] series, int lag, int times) Difference the given series the given number of times at the given lag.
TimeSeries	difference(int lag) Difference this time series at the given lag and return the result as a new time series.
TimeSeries	difference(int lag, int times) Difference this series the given number of times at the given lag.
boolean	equals(Object o)
static TimeSeries	from(double... series) Create a new time series from the given data without regard to when the observations were made.
static TimeSeries	from(OffsetDateTime startTime, double... series) Create a new time series from the given data with the supplied start time.
static TimeSeries	from(TimePeriod timePeriod, CharSequence startTime, double... series) Create a new time series using the given time period, the time of first observation, and observation data.
static TimeSeries	from(TimePeriod timePeriod, double... series) Create a new time series using the given time period and observation data.
static TimeSeries	from(TimePeriod timePeriod, List<OffsetDateTime> observationTimes, double... series) Create a new time series with the given time period, observation times, and observation data.
static TimeSeries	from(TimePeriod timePeriod, OffsetDateTime startTime, double... series) Create a new time series with the given time period, the time of first observation, and the observation data.
static TimeSeries	from(TimeUnit timeUnit, CharSequence startTime, double... series) Create a new time series using the given unit of time, the time of first observation, and the observation data.
static TimeSeries	from(TimeUnit timeUnit, OffsetDateTime startTime, double... series) Create a new time series using the given unit of time, the time of first observation, and the observation data.
int	hashCode()
double	mean() The mean of the observations.
double	median() The median value of the observations.
TimeSeries	minus(double[] otherSeries) Subtract the given series from this series and return the result as a new time series.
TimeSeries	minus(TimeSeries otherSeries) Subtract the given series from this time series and return the result as a new time series.
TimeSeries	movingAverage(int m) Compute a moving average of order m.
List<OffsetDateTime>	observationTimes() Retrieve the list of observation times for this series.
TimeSeries	plus(DataSet otherData) Add every element of this data set to the corresponding element of the given data set.
void	print() Print a descriptive summary of this time series.
int	size() The size of the data set.
TimeSeries	slice(int start, int end) Return a slice of this time series from start (inclusive) to end (inclusive).
TimeSeries	slice(OffsetDateTime start, OffsetDateTime end) Return a slice of this time series from start (inclusive) to end (inclusive).
OffsetDateTime	startTime() The time at which the first observation was made.
double	stdDeviation() The unbiased sample standard deviation of the observations.
double	sum() The sum of the observations.
double	sumOfSquares() The sum of the squared observations.
TimePeriod	timePeriod() Retrieve the time period at which observations are made for this series.
TimeSeries	times(DataSet otherData) Multiply every element of this data set with the corresponding element of the given data set.
TimeSeries	timeSlice(int start, int end) Return a slice of this time series using R/Julia style indexing.
String	toString()
TimeSeries	transform(double boxCoxLambda) Transform the series using a Box-Cox transformation with the given parameter value.
double	variance() The unbiased sample variance of the observations.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

from

public static TimeSeries from(@NonNull
                              double... series)

Create a new time series from the given data without regard to when the observations were made. Use this constructor if the dates and times associated with the observations do not matter.

Parameters:

series - the observation data.

Returns:

a new time series from the supplied data.

from

public static TimeSeries from(@NonNull
                              OffsetDateTime startTime,
                              @NonNull
                              double... series)

Create a new time series from the given data with the supplied start time.

Parameters:

startTime - the time of the first observation.

series - the observation data.

Returns:

a new time series from the supplied data.

from

public static TimeSeries from(@NonNull
                              TimePeriod timePeriod,
                              @NonNull
                              double... series)

Create a new time series using the given time period and observation data. This constructor will set the starting observation period to Jan. 1st of year 1. It is useful for when the time period between observations matter, but the actual dates do not.

Parameters:

timePeriod - the period of time between observations.

series - the observation data.

Returns:

a new time series from the supplied data.

from

public static TimeSeries from(@NonNull
                              TimePeriod timePeriod,
                              @NonNull
                              CharSequence startTime,
                              @NonNull
                              double... series)

Create a new time series using the given time period, the time of first observation, and observation data.

Parameters:

timePeriod - the period of time between observations.

startTime - the time of the first observation. The characters must represent either a valid OffsetDateTime or a valid LocalDateTime. If a LocalDateTime, then the default UTC/Greenwich offset, i.e., an offset of 0, will be used.

series - the observation data.

Returns:

a new time series from the supplied data.

from

public static TimeSeries from(@NonNull
                              TimePeriod timePeriod,
                              @NonNull
                              List<OffsetDateTime> observationTimes,
                              @NonNull
                              double... series)

Create a new time series with the given time period, observation times, and observation data.

Parameters:

timePeriod - the period of time between observations.

observationTimes - the observation times.

series - the observation data.

Returns:

a new time series from the supplied data.

from

public static TimeSeries from(@NonNull
                              TimeUnit timeUnit,
                              @NonNull
                              CharSequence startTime,
                              @NonNull
                              double... series)

Create a new time series using the given unit of time, the time of first observation, and the observation data.

Parameters:

timeUnit - the unit of time in which observations are made.

startTime - the time of the first observation. The characters must represent either a valid OffsetDateTime or a valid LocalDateTime. If a LocalDateTime, then the default UTC/Greenwich offset, i.e., an offset of 0, will be used.

series - the observation data.

Returns:

a new time series from the supplied data.

from

public static TimeSeries from(@NonNull
                              TimePeriod timePeriod,
                              @NonNull
                              OffsetDateTime startTime,
                              @NonNull
                              double... series)

Create a new time series with the given time period, the time of first observation, and the observation data.

Parameters:

timePeriod - the period of time between observations.

startTime - the time of the first observation.

series - the observation data.

Returns:

a new time series from the supplied data.

from

public static TimeSeries from(@NonNull
                              TimeUnit timeUnit,
                              @NonNull
                              OffsetDateTime startTime,
                              @NonNull
                              double... series)

Create a new time series using the given unit of time, the time of first observation, and the observation data.

Parameters:

timeUnit - the unit of time in which observations are made.

startTime - the time of the first observation.

series - the observation data.

Returns:

a new time series from the supplied data.

difference

public static double[] difference(@NonNull
                                  double[] series,
                                  int lag,
                                  int times)

Difference the given series the given number of times at the given lag.

Parameters:

series - the series to difference.

lag - the lag at which to take differences.

times - the number of times to difference the series at the given lag. Note that this argument may equal 0, in which case a copy of the original series is returned.

Returns:

a new time series differenced the given number of times at the given lag.

Throws:

IllegalArgumentException - if lag is less than 1.

IllegalArgumentException - if times is less than 0.

IllegalArgumentException - if the product of lag and times is greater than the length of the series.

difference

public static double[] difference(double[] series,
                                  int times)

Difference the given series the given number of times at lag 1.

Parameters:

series - the series to difference.

times - the number of times to difference the series.

Returns:

a new time series differenced the given number of times at lag 1.

Throws:

IllegalArgumentException - if times is less than 0.

IllegalArgumentException - if times is greater than the length of the series.

aggregateToYears

public final TimeSeries aggregateToYears()

Aggregate the observations in this series to the yearly level.

Returns:

a new time series with the observations in this series aggregated to the yearly level.

aggregate

public final TimeSeries aggregate(TimeUnit timeUnit)

Aggregate the observations in this series to the given time unit.

Parameters:

timeUnit - The time unit to aggregate up to.

Returns:

a new time series aggregated up to the given time unit.

aggregate

public final TimeSeries aggregate(@NonNull
                                  TimePeriod timePeriod)

Aggregate the time series up to the given time period.

Parameters:

timePeriod - the time period to aggregate up to.

Returns:

A new time series aggregated up to the given time period.

at

public final double at(int index)

Retrieve the value of the time series at the given index. Indexing begins at 0.

Parameters:

index - the index of the value to return.

Returns:

the value of the time series at the given index.

at

public final double at(@NonNull
                       OffsetDateTime dateTime)

Retrieve the value of the time series at the given date-time.

Parameters:

dateTime - the date-time of the value to return.

Returns:

the value of the time series at the given date-time.

Throws:

IllegalArgumentException - if there is no observation at the given date-time.

autoCorrelationAtLag

public final double autoCorrelationAtLag(int k)

The correlation of this series with itself at lag k.

Parameters:

k - the lag to compute the autocorrelation at.

Returns:

the correlation of this series with itself at lag k.

Throws:

IllegalArgumentException - if k is less than 0.

autoCorrelationUpToLag

public final double[] autoCorrelationUpToLag(int k)

Every correlation coefficient of this series with itself up to the given lag.

Parameters:

k - the maximum lag to compute the autocorrelation at.

Returns:

every correlation coefficient of this series with itself up to the given lag.

Throws:

IllegalArgumentException - if k is less than 0.

autoCovarianceAtLag

public final double autoCovarianceAtLag(int k)

The covariance of this series with itself at lag k.

Parameters:

k - the lag to compute the autocovariance at.

Returns:

the covariance of this series with itself at lag k.

Throws:

IllegalArgumentException - if k is less than 0.

autoCovarianceUpToLag

public final double[] autoCovarianceUpToLag(int k)

Every covariance measure of this series with itself up to the given lag.

Parameters:

k - the maximum lag to compute the autocovariance at.

Returns:

every covariance measure of this series with itself up to the given lag.

Throws:

IllegalArgumentException - if k is less than 0.

transform

public final TimeSeries transform(double boxCoxLambda)

Transform the series using a Box-Cox transformation with the given parameter value.

Setting boxCoxLambda equal to 0 corresponds to the natural logarithm while values other than 0 correspond to power transforms.

See the definition given here.

Parameters:

boxCoxLambda - the parameter to use for the transformation.

Returns:

a new time series transformed using the given Box-Cox parameter.

Throws:

IllegalArgumentException - if boxCoxLambda is not strictly between -1 and 2.

backTransform

public final TimeSeries backTransform(double boxCoxLambda)

Perform the inverse of the Box-Cox transformation on this series and return the result in a new time series.

Parameters:

boxCoxLambda - the Box-Cox transformation parameter to use for the inversion.

Returns:

a new time series with the inverse Box-Cox transformation applied.

Throws:

IllegalArgumentException - if boxCoxLambda is not strictly between -1 and 2.

movingAverage

public final TimeSeries movingAverage(int m)

Compute a moving average of order m.

Parameters:

m - the order of the moving average.

Returns:

a new time series with the smoothed observations.

centeredMovingAverage

public final TimeSeries centeredMovingAverage(int m)

Return a moving average of order m if m is odd and of order 2 × m if m is even.

Parameters:

m - the order of the moving average.

Returns:

a centered moving average of order m.

demean

public final TimeSeries demean()

Remove the mean from this series and return the result as a new time series.

Returns:

a new time series representing this time series with its mean removed.

difference

public final TimeSeries difference(int lag,
                                   int times)

Difference this series the given number of times at the given lag.

Parameters:

lag - the lag at which to take differences.

times - the number of times to difference the series at the given lag.

Returns:

a new time series differenced the given number of times at the given lag.

Throws:

IllegalArgumentException - if lag is less than 1.

IllegalArgumentException - if times is less than 0.

IllegalArgumentException - if the product of lag and times is greater than the length of the series.

difference

public final TimeSeries difference(int lag)

Difference this time series at the given lag and return the result as a new time series.

Parameters:

lag - the lag at which to take differences.

Returns:

a new time series differenced at the given lag.

Throws:

IllegalArgumentException - if lag is less than 1.

IllegalArgumentException - if lag is greater than the size of this series.

difference

public final TimeSeries difference()

Difference this time series once at lag 1 and return the result as a new time series.

Returns:

a new time series differenced once at lag 1.

minus

public final TimeSeries minus(@NonNull
                              TimeSeries otherSeries)

Subtract the given series from this time series and return the result as a new time series. Note that if the other series is empty, then this series is returned. However, in all other cases in which the two series differ in size, an IllegalArgumentException is thrown.

Parameters:

otherSeries - the series to subtract from this one.

Returns:

The difference between this series and the given series.

Throws:

IllegalArgumentException - if the other series is non-empty and the two series differ in size.

minus

public final TimeSeries minus(@NonNull
                              double[] otherSeries)

Subtract the given series from this series and return the result as a new time series. Note that if the other series is empty, then this series is returned. However, in all other cases in which the two series differ in size, an IllegalArgumentException is thrown.

Parameters:

otherSeries - the series to subtract from this one.

Returns:

The difference between this series and the given series.

Throws:

IllegalArgumentException - if the other series is non-empty and the two series differ in size.

slice

public final TimeSeries slice(int start,
                              int end)

Return a slice of this time series from start (inclusive) to end (inclusive).

Parameters:

start - the beginning index of the slice. The value at the index is included in the returned TimeSeries.

end - the ending index of the slice. The value at the index is included in the returned TimeSeries.

Returns:

a slice of this time series from start (inclusive) to end (inclusive).

slice

public final TimeSeries slice(@NonNull
                              OffsetDateTime start,
                              @NonNull
                              OffsetDateTime end)

Return a slice of this time series from start (inclusive) to end (inclusive).

Parameters:

start - the beginning date and time of the slice. The value at the given date-time is included in the returned time series.

end - the ending date and time of the slice. The value at the given date-time is included in the returned time series.

Returns:

a slice of this time series from start (inclusive) to end (inclusive).

timeSlice

public final TimeSeries timeSlice(int start,
                                  int end)

Return a slice of this time series using R/Julia style indexing.

Parameters:

start - the beginning time index of the slice. The value at the time index is included in the returned time series.

end - the ending time index of the slice. The value at the time index is included in the returned time series.

Returns:

a slice of this time series from start (inclusive) to end (inclusive) using R/Julia style indexing.

print

public final void print()

Print a descriptive summary of this time series.

asList

public final List<Double> asList()

retrieve the observations as a list.

Returns:

the observations as a list.

timePeriod

public final TimePeriod timePeriod()

Retrieve the time period at which observations are made for this series.

Returns:

the time period at which observations are made for this series.

startTime

public final OffsetDateTime startTime()

The time at which the first observation was made.

Returns:

the time at which the first observation was made.

observationTimes

public final List<OffsetDateTime> observationTimes()

Retrieve the list of observation times for this series.

Returns:

the list of observation times for this series.

dateTimeIndex

public final Map<OffsetDateTime,Integer> dateTimeIndex()

Retrieve the mapping of observation times to array indices for this series.

Returns:

the mapping of observation times to array indices for this series.

asArray

public final double[] asArray()

Retrieve the time series of observations.

Specified by:

asArray in interface DataSet

Returns:

the time series of observations.

sum

public double sum()

Description copied from interface: DataSet

The sum of the observations.

Specified by:

sum in interface DataSet

Returns:

the sum of the observations.

sumOfSquares

public double sumOfSquares()

Description copied from interface: DataSet

The sum of the squared observations.

Specified by:

sumOfSquares in interface DataSet

Returns:

the sum of the squared observations.

mean

public double mean()

Description copied from interface: DataSet

The mean of the observations.

Specified by:

mean in interface DataSet

Returns:

the mean of the observations.

median

public double median()

Description copied from interface: DataSet

The median value of the observations.

Specified by:

median in interface DataSet

Returns:

the median value of the observations.

size

public int size()

Description copied from interface: DataSet

The size of the data set.

Specified by:

size in interface DataSet

Returns:

the size of the data set.

times

public TimeSeries times(@NonNull
                        DataSet otherData)

Description copied from interface: DataSet

Multiply every element of this data set with the corresponding element of the given data set.

Specified by:

times in interface DataSet

Parameters:

otherData - The data to multiply by.

Returns:

A new data set containing every element of this data set multiplied by the corresponding element of the given data set.

plus

public TimeSeries plus(@NonNull
                       DataSet otherData)

Description copied from interface: DataSet

Add every element of this data set to the corresponding element of the given data set.

Specified by:

plus in interface DataSet

Parameters:

otherData - The data to add to.

Returns:

A new data set containing every element of this data set added to the corresponding element of the given data set.

variance

public double variance()

Description copied from interface: DataSet

The unbiased sample variance of the observations.

Specified by:

variance in interface DataSet

Returns:

the unbiased sample variance of the observations.

stdDeviation

public double stdDeviation()

Description copied from interface: DataSet

The unbiased sample standard deviation of the observations.

Specified by:

stdDeviation in interface DataSet

Returns:

the unbiased sample standard deviation of the observations.

covariance

public double covariance(DataSet otherData)

Description copied from interface: DataSet

The unbiased sample covariance of these observations with the observations contained in the given data set.

Specified by:

covariance in interface DataSet

Parameters:

otherData - the data to compute the covariance with.

Returns:

the unbiased sample covariance of these observations with the observations contained in the given data set.

correlation

public double correlation(DataSet otherData)

Description copied from interface: DataSet

The unbiased sample correlation of these observations with the observations contained in the given data set.

Specified by:

correlation in interface DataSet

Parameters:

otherData - the data to compute the correlation coefficient with.

Returns:

the unbiased sample correlation of these observations with the observations contained in the given data set.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object