Interface LocalDateDoubleTimeSeries

public interface LocalDateDoubleTimeSeries
Interface for all local date timeseries types containingdouble
values.A timeseries is similar to both a
SortedMap
of value keyed by datetime and aList
of datetime to value pairs. As such, the date/times do not have to be evenly spread over time within the series.The distribution of the data will influence which implementation is most appropriate.
Implementations must be immutable and threadsafe beans.
Note that
Double.NaN
is used internally as a sentinel value and is therefore not allowed as a value.


Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description static LocalDateDoubleTimeSeriesBuilder
builder()
Creates an empty builder, used to create timeseries.static java.util.stream.Collector<LocalDateDoublePoint,LocalDateDoubleTimeSeriesBuilder,LocalDateDoubleTimeSeries>
collector()
Returns a collector that can be used to create a timeseries from a stream of points.boolean
containsDate(java.time.LocalDate date)
Checks if this timeseries contains a value for the specified date.java.util.stream.Stream<java.time.LocalDate>
dates()
Returns a stream over the dates of this timeseries.static LocalDateDoubleTimeSeries
empty()
Returns an empty timeseries.LocalDateDoubleTimeSeries
filter(ObjDoublePredicate<java.time.LocalDate> predicate)
Create a new timeseries by filtering this one.void
forEach(java.util.function.ObjDoubleConsumer<java.time.LocalDate> action)
Applies an action to each pair in the time series.java.util.OptionalDouble
get(java.time.LocalDate date)
Gets the value associated with the specified date.default java.time.LocalDate
getEarliestDate()
Get the earliest date contained in this timeseries.default double
getEarliestValue()
Get the value held for the earliest date contained in this timeseries.java.time.LocalDate
getLatestDate()
Get the latest date contained in this timeseries.double
getLatestValue()
Get the value held for the latest date contained in this timeseries.LocalDateDoubleTimeSeries
headSeries(int numPoints)
Gets part of this series as a subseries, choosing the earliest entries.default LocalDateDoubleTimeSeries
intersection(LocalDateDoubleTimeSeries other, java.util.function.DoubleBinaryOperator mapper)
Obtains the intersection of a pair of time series.boolean
isEmpty()
Indicates if this timeseries is empty.LocalDateDoubleTimeSeries
mapDates(java.util.function.Function<? super java.time.LocalDate,? extends java.time.LocalDate> mapper)
Applies an operation to each date in the time series which creates a new date, returning a new time series with the new dates and the points from this time series.LocalDateDoubleTimeSeries
mapValues(java.util.function.DoubleUnaryOperator mapper)
Applies an operation to each value in the time series.static LocalDateDoubleTimeSeries
of(java.time.LocalDate date, double value)
Obtains a timeseries containing a single date and value.default Pair<LocalDateDoubleTimeSeries,LocalDateDoubleTimeSeries>
partition(ObjDoublePredicate<java.time.LocalDate> predicate)
Partition the timeseries into a pair of distinct series using a predicate.default Pair<LocalDateDoubleTimeSeries,LocalDateDoubleTimeSeries>
partitionByValue(java.util.function.DoublePredicate predicate)
Partition the timeseries into a pair of distinct series using a predicate.int
size()
Return the size of this timeseries.java.util.stream.Stream<LocalDateDoublePoint>
stream()
Returns a stream over the points of this timeseries.LocalDateDoubleTimeSeries
subSeries(java.time.LocalDate startInclusive, java.time.LocalDate endExclusive)
Gets part of this series as a subseries between two dates.LocalDateDoubleTimeSeries
tailSeries(int numPoints)
Gets part of this series as a subseries, choosing the latest entries.LocalDateDoubleTimeSeriesBuilder
toBuilder()
Return a builder populated with the values from this series.default LocalDateDoubleTimeSeries
union(LocalDateDoubleTimeSeries other, java.util.function.DoubleBinaryOperator mapper)
Obtains the union of a pair of time series.java.util.stream.DoubleStream
values()
Returns a stream over the values of this timeseries.



Method Detail

empty
static LocalDateDoubleTimeSeries empty()
Returns an empty timeseries. Generally a singleton instance is returned. Returns:
 an empty timeseries

of
static LocalDateDoubleTimeSeries of(java.time.LocalDate date, double value)
Obtains a timeseries containing a single date and value. Parameters:
date
 the singleton datevalue
 the singleton value Returns:
 the timeseries

builder
static LocalDateDoubleTimeSeriesBuilder builder()
Creates an empty builder, used to create timeseries.The builder has methods to create and modify a timeseries.
 Returns:
 the timeseries builder

collector
static java.util.stream.Collector<LocalDateDoublePoint,LocalDateDoubleTimeSeriesBuilder,LocalDateDoubleTimeSeries> collector()
Returns a collector that can be used to create a timeseries from a stream of points. Returns:
 the timeseries collector

size
int size()
Return the size of this timeseries. Returns:
 the size of the timeseries

isEmpty
boolean isEmpty()
Indicates if this timeseries is empty. Returns:
 true if the timeseries contains no entries

containsDate
boolean containsDate(java.time.LocalDate date)
Checks if this timeseries contains a value for the specified date. Parameters:
date
 the date to check for Returns:
 true if there is a value associated with the date

get
java.util.OptionalDouble get(java.time.LocalDate date)
Gets the value associated with the specified date.The result is an
OptionalDouble
which avoids the need to handle null or exceptions. UseisPresent()
to check whether the value is present. UseorElse(double)
to default a missing value. Parameters:
date
 the date to get the value for Returns:
 the value associated with the date, optional empty if the date is not present

getEarliestDate
default java.time.LocalDate getEarliestDate()
Get the earliest date contained in this timeseries.If the timeseries is empty then
NoSuchElementException
will be thrown. Returns:
 the earliest date contained in this timeseries
 Throws:
java.util.NoSuchElementException
 if the timeseries is empty

getEarliestValue
default double getEarliestValue()
Get the value held for the earliest date contained in this timeseries.If the timeseries is empty then
NoSuchElementException
will be thrown. Returns:
 the value held for the earliest date contained in this timeseries
 Throws:
java.util.NoSuchElementException
 if the timeseries is empty

getLatestDate
java.time.LocalDate getLatestDate()
Get the latest date contained in this timeseries.If the timeseries is empty then
NoSuchElementException
will be thrown. Returns:
 the latest date contained in this timeseries
 Throws:
java.util.NoSuchElementException
 if the timeseries is empty

getLatestValue
double getLatestValue()
Get the value held for the latest date contained in this timeseries.If the timeseries is empty then
NoSuchElementException
will be thrown. Returns:
 the value held for the latest date contained in this timeseries
 Throws:
java.util.NoSuchElementException
 if the timeseries is empty

subSeries
LocalDateDoubleTimeSeries subSeries(java.time.LocalDate startInclusive, java.time.LocalDate endExclusive)
Gets part of this series as a subseries between two dates.The datetimes do not have to match exactly. The subseries contains all entries between the two dates using a halfopen interval. The start date is included, the end date is excluded. The dates may be before or after the end of the timeseries.
To obtain the series before a specific date, used
LocalDate.MIN
as the first argument. To obtain the series from a specific date, usedLocalDate.MAX
as the second argument. Parameters:
startInclusive
 the start date, inclusiveendExclusive
 the end date, exclusive Returns:
 the subseries between the dates
 Throws:
java.lang.IllegalArgumentException
 if the end is before the start

headSeries
LocalDateDoubleTimeSeries headSeries(int numPoints)
Gets part of this series as a subseries, choosing the earliest entries.The subseries contains the earliest part of the series up to the specified number of points. If the series contains less points than the number requested, the whole timeseries is returned.
 Parameters:
numPoints
 the number of items to select, zero or greater Returns:
 the subseries of the requested size starting with the earliest entry
 Throws:
java.lang.IllegalArgumentException
 if the number of items is less than zero

tailSeries
LocalDateDoubleTimeSeries tailSeries(int numPoints)
Gets part of this series as a subseries, choosing the latest entries.The subseries contains the latest part of the series up to the specified number of points. If the series contains less points than the number requested, the whole timeseries is returned.
 Parameters:
numPoints
 the number of items to select, zero or greater Returns:
 the subseries of the requested size ending with the latest entry
 Throws:
java.lang.IllegalArgumentException
 if the number of items is less than zero

stream
java.util.stream.Stream<LocalDateDoublePoint> stream()
Returns a stream over the points of this timeseries.This provides access to the entire timeseries.
 Returns:
 a stream over the points of this timeseries

dates
java.util.stream.Stream<java.time.LocalDate> dates()
Returns a stream over the dates of this timeseries.This is most useful to summarize the dates in the stream, such as calculating the maximum or minimum date, or searching for a specific value.
 Returns:
 a stream over the dates of this timeseries

values
java.util.stream.DoubleStream values()
Returns a stream over the values of this timeseries.This is most useful to summarize the values in the stream, such as calculating the maximum, minimum or average value, or searching for a specific value.
 Returns:
 a stream over the values of this timeseries

forEach
void forEach(java.util.function.ObjDoubleConsumer<java.time.LocalDate> action)
Applies an action to each pair in the time series.This is generally used to apply a mathematical operation to the values. For example, the operator could multiply each value by a constant, or take the inverse.
base.forEach((date, value) > System.out.println(date + "=" + value));
 Parameters:
action
 the action to be applied to each pair

mapDates
LocalDateDoubleTimeSeries mapDates(java.util.function.Function<? super java.time.LocalDate,? extends java.time.LocalDate> mapper)
Applies an operation to each date in the time series which creates a new date, returning a new time series with the new dates and the points from this time series.This operation creates a new time series with the same data but the dates moved.
The operation must not change the dates in a way that reorders them. The mapped dates must be in ascending order or an exception is thrown.
updatedSeries = timeSeries.mapDates(date > date.plusYears(1));
 Parameters:
mapper
 the operation applied to each date in the time series Returns:
 a copy of this time series with new dates

mapValues
LocalDateDoubleTimeSeries mapValues(java.util.function.DoubleUnaryOperator mapper)
Applies an operation to each value in the time series.This is generally used to apply a mathematical operation to the values. For example, the operator could multiply each value by a constant, or take the inverse.
multiplied = base.mapValues(value > value * 3);
 Parameters:
mapper
 the operator to be applied to the values Returns:
 a copy of this series with the mapping applied to the original values

filter
LocalDateDoubleTimeSeries filter(ObjDoublePredicate<java.time.LocalDate> predicate)
Create a new timeseries by filtering this one.The timeseries can be filtered by both date and value. Note that if filtering by date range is required, it is likely to be more efficient to use
subSeries(LocalDate, LocalDate)
as that avoids traversal of the whole series. Parameters:
predicate
 the predicate to use to the filter the elements of the series Returns:
 a filtered version of the series

intersection
default LocalDateDoubleTimeSeries intersection(LocalDateDoubleTimeSeries other, java.util.function.DoubleBinaryOperator mapper)
Obtains the intersection of a pair of time series.This returns a timeseries with the intersection of the dates of the two inputs. The operator is invoked to combine the values.
 Parameters:
other
 the timeseries to combine withmapper
 the function to be used to combine the values Returns:
 a new timeseries containing the dates in common between the input series with their values combined together using the function

union
default LocalDateDoubleTimeSeries union(LocalDateDoubleTimeSeries other, java.util.function.DoubleBinaryOperator mapper)
Obtains the union of a pair of time series.This returns a timeseries with the union of the dates of the two inputs. When the same date occurs in both timeseries, the operator is invoked to combine the values.
 Parameters:
other
 the timeseries to combine withmapper
 the function to be used to combine the values Returns:
 a new timeseries containing the dates in common between the input series with their values combined together using the function

partition
default Pair<LocalDateDoubleTimeSeries,LocalDateDoubleTimeSeries> partition(ObjDoublePredicate<java.time.LocalDate> predicate)
Partition the timeseries into a pair of distinct series using a predicate.Points in the timeseries which match the predicate will be put into the first series, whilst those points which do not match will be put into the second.
 Parameters:
predicate
 predicate used to test the points in the timeseries Returns:
 a
Pair
containing two timeseries. The first is a series made of all the points in this series which match the predicate. The second is a series made of the points which do not match.

partitionByValue
default Pair<LocalDateDoubleTimeSeries,LocalDateDoubleTimeSeries> partitionByValue(java.util.function.DoublePredicate predicate)
Partition the timeseries into a pair of distinct series using a predicate.Points in the timeseries whose values match the predicate will be put into the first series, whilst those points whose values do not match will be put into the second.
 Parameters:
predicate
 predicate used to test the points in the timeseries Returns:
 a
Pair
containing two timeseries. The first is a series made of all the points in this series which match the predicate. The second is a series made of the points which do not match.

toBuilder
LocalDateDoubleTimeSeriesBuilder toBuilder()
Return a builder populated with the values from this series.This can be used to mutate the timeseries.
 Returns:
 a builder containing the point from this timeseries

