ch.agent.t2.timeseries

Interface TimeAddressable<T>

Type Parameters:

T - the value type

All Superinterfaces:

Iterable<Observation<T>>

All Known Subinterfaces:

TimeIndexable<T>

All Known Implementing Classes:

AbstractTimeSeries, RegularTimeSeries, SparseTimeSeries

public interface TimeAddressable<T>
extends Iterable<Observation<T>>

A TimeAddressable is the most general time series, a collection of objects of a given type, each one associated to a distinct time index. This definition allows the elements of the collection to be irregularly spaced on the time axis.

Author:

Jean-Paul Vetterli

Method Summary

Modifier and Type	Method and Description
TimeIndexable<T>	asIndexable() Return an indexable time series corresponding to this one.
TimeAddressable<T>	copy() Return a copy of the time series.
T	get(long index) Return the value at the given numerical time index.
TimeAddressable<T>	get(long first, long last) Return a new time series corresponding to the range between two numerical time indexes.
TimeAddressable<T>	get(Range range) Return a time series constructed from the given range of this series.
T	get(TimeIndex time) Return the value identified by the given time index.
Observation<T>	getFirst(TimeIndex time) Return the observation at or after the given time.
long	getFirstIndex() Return the numerical time index of the first element, or -1 when there is no data.
Observation<T>	getLast(TimeIndex time) Return the observation at or before the given time.
long	getLastIndex() Return the numerical time index of the last element, or -1 when there is no data.
T	getMissingValue() Return the object representing missing values.
Range	getRange() Return the range of the time series.
int	getSize() Return the number of values.
TimeDomain	getTimeDomain() Return the time domain of the time series.
Class<T>	getType() Return the type of he observations.
int	getValueCount() Return the number of non-missing values.
boolean	isIndexable() Return true if the time series implements TimeIndexable.
boolean	isMissing(T value) Return true if the given value is missing.
Iterator<Observation<T>>	iterator() Returns an iterator over the Observations in the time series ordered by increasing time index.
TimeAddressable<T>	makeEmptyCopy() Make a copy of the time series but without the values.
void	put(long time, T value) Put a value identified by a numerical time index into the time series.
void	put(long time, T[] values) Put an array of values identified with the numerical time index of its first element into the time series.
void	put(TimeAddressable<T> values, UpdateReviewer<T> reviewer) Conditionally put all values from another time series into this time series.
void	put(TimeIndex time, T value) Put a value identified by a time index into the time series.
void	put(TimeIndex time, T[] values) Put an array of values identified with time index of its first element into the time series.
void	remove(TimeIndex time) Remove the value identified by the time index.
boolean	setRange(Range range) Set the range to the intersection of the current range with the given range.

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Method Detail

iterator

Iterator<Observation<T>> iterator()

Returns an iterator over the Observations in the time series ordered by increasing time index. This iterator does not return any missing value.

Specified by:

iterator in interface Iterable<Observation<T>>

Returns:

an iterator over the time series

isIndexable

boolean isIndexable()

Return true if the time series implements TimeIndexable.

Returns:

true if the time series is indexable

isMissing

boolean isMissing(T value)

Return true if the given value is missing.

Returns:

true if the argument is the missing value

getMissingValue

T getMissingValue()

Return the object representing missing values.

Returns:

an object of the value type

get

T get(long index)
throws T2Exception

Return the value at the given numerical time index. Return the missing value object when there is no value. There is no value either when the given index is out of range or when there is a hole in the range at the requested position.

Parameters:

index - a number

Returns:

a value

Throws:

T2Exception

get

T get(TimeIndex time)
throws T2Exception

Return the value identified by the given time index. Return the missing value object when there is no value. There is no value either when the given index is out of range or when there is a hole in the range at the requested position.

Parameters:

time - a non-null time index

Returns:

a value

Throws:

T2Exception

getLast

Observation<T> getLast(TimeIndex time)
                throws T2Exception

Return the observation at or before the given time. When the argument is null, return the last observation. Return null when the wanted observation cannot be found. When not null, the result will not contain a missing value (this is a special rule of this method, not a general rule for Observation objects).

Parameters:

time - a time index

Returns:

an observation or null

Throws:

T2Exception

getFirst

Observation<T> getFirst(TimeIndex time)
                 throws T2Exception

Return the observation at or after the given time. When the argument is null, return the first observation. Return null when the wanted observation cannot be found. When not null, the result will not contain a missing value (this is a special rule of this method, not a general rule for Observation objects).

Parameters:

time - a time index

Returns:

an observation or null

Throws:

T2Exception

get

TimeAddressable<T> get(long first,
                       long last)
                throws T2Exception

Return a new time series corresponding to the range between two numerical time indexes. The result is never null. When there is no data corresponding to the arguments, an empty time series is returned.

Parameters:

first - a numerical time index giving the lower bound of the wanted range

last - a numerical time index giving the upper bound of the wanted range

Returns:

a time series

Throws:

T2Exception

get

TimeAddressable<T> get(Range range)
                throws T2Exception

Return a time series constructed from the given range of this series. The result is never null. When there is no data corresponding to the arguments, an empty time series is returned.

Parameters:

range - a non-null range

Returns:

a time series

Throws:

T2Exception

put

void put(TimeIndex time,
         T value)
  throws T2Exception

Put a value identified by a time index into the time series. The value can only be null when null was defined to represent missing values.

Parameters:

time - a non-null time index

value - a value

Throws:

T2Exception

put

void put(TimeIndex time,
         T[] values)
  throws T2Exception

Put an array of values identified with time index of its first element into the time series. Values elements can only be null when null was defined to represent missing values.

Parameters:

time - a non-null time index

values - a non-null array of values

Throws:

T2Exception

put

void put(long time,
         T value)
  throws T2Exception

Put a value identified by a numerical time index into the time series. The value can only be null when null was defined to represent missing values.

Parameters:

time - a numerical time index

value - a value

Throws:

T2Exception

put

void put(long time,
         T[] values)
  throws T2Exception

Put an array of values identified with the numerical time index of its first element into the time series. Values elements can only be null when null was defined to represent missing values. .

Parameters:

time - a numerical time index

values - a non-null array of values

Throws:

T2Exception

put

void put(TimeAddressable<T> values,
         UpdateReviewer<T> reviewer)
  throws T2Exception

Conditionally put all values from another time series into this time series. The condition is that, if not null, the reviewer accepts all new values. With a null reviewer, all values are always accepted.

Important note. When the implementation of the values time series does not explicitly represent missing values (see SparseTimeSeries for example), this method cannot be relied upon for "deleting" values of the target.

Parameters:

values - a non-null time series

reviewer - a reviewer

Throws:

T2Exception

remove

void remove(TimeIndex time)
     throws T2Exception

Remove the value identified by the time index.

Parameters:

time - a non-null time index

Throws:

T2Exception

getSize

int getSize()

Return the number of values. Missing values are included. Note that in a sparse time series the result is not always the same as the range size.

Returns:

the number of values

getValueCount

int getValueCount()

Return the number of non-missing values.

Returns:

the number of non-missing values

getRange

Range getRange()

Return the range of the time series. The range is the empty range when there is no data. Modifying the range returned by this method does not have any effect on the range of the time series.

Returns:

a copy of the range of the time series

getFirstIndex

long getFirstIndex()

Return the numerical time index of the first element, or -1 when there is no data. To get the time of the first element as a TimeIndex, use getRange().

Returns:

the index of the first element

getLastIndex

long getLastIndex()

Return the numerical time index of the last element, or -1 when there is no data. To get the time of the last element as a TimeIndex, use getRange().

Returns:

the index of the last element

setRange

boolean setRange(Range range)
          throws T2Exception

Set the range to the intersection of the current range with the given range. If the intersection is empty, all values are removed. A null range parameter is interpreted as a request to clear all values. Returns true if the range was modified.

Parameters:

range - the new range will be the intersection of the current range with this one

Returns:

true if the range was modified

Throws:

T2Exception

getTimeDomain

TimeDomain getTimeDomain()

Return the time domain of the time series.

Returns:

a time domain

getType

Class<T> getType()

Return the type of he observations.

Returns:

a time domain

asIndexable

TimeIndexable<T> asIndexable()
                      throws T2Exception

Return an indexable time series corresponding to this one. Return the time series itself if it is already indexable. If not, create an indexable time series using values of the current time series. The operation throws an exception when a run of missing values exceeds a certain threshold, or if the range is too large to be represented with a 32 bit integer.

Returns:

an indexable time series

Throws:

T2Exception

copy

TimeAddressable<T> copy()
                 throws T2Exception

Return a copy of the time series.

Returns:

a copy of the time series

Throws:

T2Exception

makeEmptyCopy

TimeAddressable<T> makeEmptyCopy()

Make a copy of the time series but without the values.

Returns:

an empty copy of the time series