Package com.opengamma.strata.collect.timeseries

Interface LocalDateDoubleTimeSeries

  • public interface LocalDateDoubleTimeSeries
    Interface for all local date time-series types containing double values.

    A time-series is similar to both a SortedMap of value keyed by date-time and a List of date-time 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 thread-safe beans.

    Note that Double.NaN is used internally as a sentinel value and is therefore not allowed as a value.

    • Method Detail

      • empty

        static LocalDateDoubleTimeSeries empty()
        Returns an empty time-series. Generally a singleton instance is returned.
        Returns:
        an empty time-series

      • of

        static LocalDateDoubleTimeSeries of​(LocalDate date,
                                    double value)
        Obtains a time-series containing a single date and value.
        Parameters:
        date - the singleton date
        value - the singleton value
        Returns:
        the time-series

      • builder

        static LocalDateDoubleTimeSeriesBuilder builder()
        Creates an empty builder, used to create time-series.

        The builder has methods to create and modify a time-series.

        Returns:
        the time-series builder

      • size

        int size()
        Return the size of this time-series.
        Returns:
        the size of the time-series

      • isEmpty

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

      • containsDate

        boolean containsDate​(LocalDate date)
        Checks if this time-series 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

        OptionalDouble get​(LocalDate date)
        Gets the value associated with the specified date.

        The result is an OptionalDouble which avoids the need to handle null or exceptions. Use isPresent() to check whether the value is present. Use orElse(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 LocalDate getEarliestDate()
        Get the earliest date contained in this time-series.

        If the time-series is empty then NoSuchElementException will be thrown.

        Returns:
        the earliest date contained in this time-series
        Throws:
        NoSuchElementException - if the time-series is empty

      • getEarliestValue

        default double getEarliestValue()
        Get the value held for the earliest date contained in this time-series.

        If the time-series is empty then NoSuchElementException will be thrown.

        Returns:
        the value held for the earliest date contained in this time-series
        Throws:
        NoSuchElementException - if the time-series is empty

      • getLatestDate

        LocalDate getLatestDate()
        Get the latest date contained in this time-series.

        If the time-series is empty then NoSuchElementException will be thrown.

        Returns:
        the latest date contained in this time-series
        Throws:
        NoSuchElementException - if the time-series is empty

      • getLatestValue

        double getLatestValue()
        Get the value held for the latest date contained in this time-series.

        If the time-series is empty then NoSuchElementException will be thrown.

        Returns:
        the value held for the latest date contained in this time-series
        Throws:
        NoSuchElementException - if the time-series is empty

      • subSeries

        LocalDateDoubleTimeSeries subSeries​(LocalDate startInclusive,
                                    LocalDate endExclusive)
        Gets part of this series as a sub-series between two dates.

        The date-times do not have to match exactly. The sub-series contains all entries between the two dates using a half-open interval. The start date is included, the end date is excluded. The dates may be before or after the end of the time-series.

        To obtain the series before a specific date, used LocalDate.MIN as the first argument. To obtain the series from a specific date, used LocalDate.MAX as the second argument.

        Parameters:
        startInclusive - the start date, inclusive
        endExclusive - the end date, exclusive
        Returns:
        the sub-series between the dates
        Throws:
        IllegalArgumentException - if the end is before the start

      • headSeries

        LocalDateDoubleTimeSeries headSeries​(int numPoints)
        Gets part of this series as a sub-series, choosing the earliest entries.

        The sub-series 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 time-series is returned.

        Parameters:
        numPoints - the number of items to select, zero or greater
        Returns:
        the sub-series of the requested size starting with the earliest entry
        Throws:
        IllegalArgumentException - if the number of items is less than zero

      • tailSeries

        LocalDateDoubleTimeSeries tailSeries​(int numPoints)
        Gets part of this series as a sub-series, choosing the latest entries.

        The sub-series 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 time-series is returned.

        Parameters:
        numPoints - the number of items to select, zero or greater
        Returns:
        the sub-series of the requested size ending with the latest entry
        Throws:
        IllegalArgumentException - if the number of items is less than zero

      • stream

        Stream<LocalDateDoublePoint> stream()
        Returns a stream over the points of this time-series.

        This provides access to the entire time-series.

        Returns:
        a stream over the points of this time-series

      • dates

        Stream<LocalDate> dates()
        Returns a stream over the dates of this time-series.

        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 time-series

      • values

        DoubleStream values()
        Returns a stream over the values of this time-series.

        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 time-series

      • forEach

        void forEach​(ObjDoubleConsumer<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​(Function<? super LocalDate,​? extends 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​(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<LocalDate> predicate)
        Create a new time-series by filtering this one.

        The time-series 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,
                                               DoubleBinaryOperator mapper)
        Obtains the intersection of a pair of time series.

        This returns a time-series with the intersection of the dates of the two inputs. The operator is invoked to combine the values.

        Parameters:
        other - the time-series to combine with
        mapper - the function to be used to combine the values
        Returns:
        a new time-series containing the dates in common between the input series with their values combined together using the function

      • union

        default LocalDateDoubleTimeSeries union​(LocalDateDoubleTimeSeries other,
                                        DoubleBinaryOperator mapper)
        Obtains the union of a pair of time series.

        This returns a time-series with the union of the dates of the two inputs. When the same date occurs in both time-series, the operator is invoked to combine the values.

        Parameters:
        other - the time-series to combine with
        mapper - the function to be used to combine the values
        Returns:
        a new time-series containing the dates in common between the input series with their values combined together using the function

      • partition

        default Pair<LocalDateDoubleTimeSeries,​LocalDateDoubleTimeSeries> partition​(ObjDoublePredicate<LocalDate> predicate)
        Partition the time-series into a pair of distinct series using a predicate.

        Points in the time-series 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 time-series
        Returns:
        a Pair containing two time-series. 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​(DoublePredicate predicate)
        Partition the time-series into a pair of distinct series using a predicate.

        Points in the time-series 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 time-series
        Returns:
        a Pair containing two time-series. 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 time-series.

        Returns:
        a builder containing the point from this time-series