Flint: A Time Series Library for Apache Spark
The ability to analyze time series data at scale is critical for the success of finance and IoT applications based on Spark. Flint is Two Sigma's implementation of highly optimized time series operations in Spark. It performs truly parallel and rich analyses on time series data by taking advantage of the natural ordering in time series data to provide locality-based optimizations.
Flint is an open source library for Spark based around the TimeSeriesRDD, a time series aware data structure, and a collection of time series utility and analysis functions that use TimeSeriesRDDs. Unlike DataFrame and Dataset, Flint's TimeSeriesRDDs can leverage the existing ordering properties of datasets at rest and the fact that almost all data manipulations and analysis over these datasets respect their temporal ordering properties. It differs from other time series efforts in Spark in its ability to efficiently compute across panel data or on large scale high frequency data.
Requirements
| Dependency | Version |
|---|---|
| Spark Version | 2.3 and 2.4 |
| Scala Version | 2.12 |
| Python Version | 3.5 and above |
How to install
Scala artifact is published in maven central:
https://mvnrepository.com/artifact/com.twosigma/flint
Python artifact is published in PyPi:
https://pypi.org/project/ts-flint
Note you will need both Scala and Python artifact to use Flint with PySpark.
How to build
To build from source:
Scala (in top-level dir):
sbt assemblyNoTest
Python (in python subdir):
python setup.py install
or
pip install .
Python bindings
The python bindings for Flint, including quickstart instructions, are documented at python/README.md. API documentation is available at http://ts-flint.readthedocs.io/en/latest/.
Getting Started
Starting Point: TimeSeriesRDD and TimeSeriesDataFrame
The entry point into all functionalities for time series analysis in Flint is TimeSeriesRDD (for Scala) and TimeSeriesDataFrame (for Python). In high level, a TimeSeriesRDD contains an OrderedRDD which could be used to represent a sequence of ordering key-value pairs. A TimeSeriesRDD uses Long to represent timestamps in nanoseconds since epoch as keys and InternalRows as values for OrderedRDD to represent a time series data set.
Create TimeSeriesRDD
Applications can create a TimeSeriesRDD from an existing RDD, from an OrderedRDD, from a DataFrame, or from a single csv file.
As an example, the following creates a TimeSeriesRDD from a gzipped CSV file with header and specific datetime format.
import com.twosigma.flint.timeseries.CSV
val tsRdd = CSV.from(
sqlContext,
"file://foo/bar/data.csv",
header = true,
dateFormat = "yyyyMMdd HH:mm:ss.SSS",
codec = "gzip",
sorted = true
)
To create a TimeSeriesRDD from a DataFrame, you have to make sure the DataFrame contains a column named "time" of type LongType.
import com.twosigma.flint.timeseries.TimeSeriesRDD
import scala.concurrent.duration._
val df = ... // A DataFrame whose rows have been sorted by their timestamps under "time" column
val tsRdd = TimeSeriesRDD.fromDF(dataFrame = df)(isSorted = true, timeUnit = MILLISECONDS)
One could also create a TimeSeriesRDD from a RDD[Row] or an OrderedRDD[Long, Row] by providing a schema, e.g.
import com.twosigma.flint.timeseries._
import scala.concurrent.duration._
val rdd = ... // An RDD whose rows have sorted by their timestamps
val tsRdd = TimeSeriesRDD.fromRDD(
rdd,
schema = Schema("time" -> LongType, "price" -> DoubleType)
)(isSorted = true,
timeUnit = MILLISECONDS
)
It is also possible to create a TimeSeriesRDD from a dataset stored as parquet format file(s). The TimeSeriesRDD.fromParquet() function provides the option to specify which columns and/or the time range you are interested, e.g.
import com.twosigma.flint.timeseries._
import scala.concurrent.duration._
val tsRdd = TimeSeriesRDD.fromParquet(
sqlContext,
path = "hdfs://foo/bar/"
)(isSorted = true,
timeUnit = MILLISECONDS,
columns = Seq("time", "id", "price"), // By default, null for all columns
begin = "20100101", // By default, null for no boundary at begin
end = "20150101" // By default, null for no boundary at end
)
Group functions
A group function is to group rows with nearby (or exactly the same) timestamps.
groupByCycleA function to group rows within a cycle, i.e. rows with exactly the same timestamps. For example,
val priceTSRdd = ...
// A TimeSeriesRDD with columns "time" and "price"
// time price
// -----------
// 1000L 1.0
// 1000L 2.0
// 2000L 3.0
// 2000L 4.0
// 2000L 5.0
val results = priceTSRdd.groupByCycle()
// time rows
// ------------------------------------------------
// 1000L [[1000L, 1.0], [1000L, 2.0]]
// 2000L [[2000L, 3.0], [2000L, 4.0], [2000L, 5.0]]
groupByIntervalA function to group rows whose timestamps fall into an interval. Intervals could be defined by anotherTimeSeriesRDD. Its timestamps will be used to defined intervals, i.e. two sequential timestamps define an interval. For example,
val priceTSRdd = ...
// A TimeSeriesRDD with columns "time" and "price"
// time price
// -----------
// 1000L 1.0
// 1500L 2.0
// 2000L 3.0
// 2500L 4.0
val clockTSRdd = ...
// A TimeSeriesRDD with only column "time"
// time
// -----
// 1000L
// 2000L
// 3000L
val results = priceTSRdd.groupByInterval(clockTSRdd)
// time rows
// ----------------------------------
// 1000L [[1000L, 1.0], [1500L, 2.0]]
// 2000L [[2000L, 3.0], [2500L, 4.0]]
addWindowsFor each row, this function adds a new column whose value for a row is a list of rows within itswindow.
val priceTSRdd = ...
// A TimeSeriesRDD with columns "time" and "price"
// time price
// -----------
// 1000L 1.0
// 1500L 2.0
// 2000L 3.0
// 2500L 4.0
val result = priceTSRdd.addWindows(Window.pastAbsoluteTime("1000ns"))
// time price window_past_1000ns
// ------------------------------------------------------
// 1000L 1.0 [[1000L, 1.0]]
// 1500L 2.0 [[1000L, 1.0], [1500L, 2.0]]
// 2000L 3.0 [[1000L, 1.0], [1500L, 2.0], [2000L, 3.0]]
// 2500L 4.0 [[1500L, 2.0], [2000L, 3.0], [2500L, 4.0]]
Temporal Join Functions
A temporal join function is a join function defined by a matching criteria over time. A tolerance in temporal join matching criteria specifies how much it should look past or look futue.
leftJoinA function performs the temporal left-join to the rightTimeSeriesRDD, i.e. left-join using inexact timestamp matches. For each row in the left, append the most recent row from the right at or before the same time. An example to join twoTimeSeriesRDDs is as follows.
val leftTSRdd = ...
val rightTSRdd = ...
val result = leftTSRdd.leftJoin(rightTSRdd, tolerance = "1day")
futureLeftJoinA function performs the temporal future left-join to the rightTimeSeriesRDD, i.e. left-join using inexact timestamp matches. For each row in the left, appends the closest future row from the right at or after the same time.
val result = leftTSRdd.futureLeftJoin(rightTSRdd, tolerance = "1day")
Summarize Functions
Summarize functions are the functions to apply summarizer(s) to rows within a certain period, like cycle, interval, windows, etc.
summarizeCyclesA function computes aggregate statistics of rows that are within a cycle, i.e. rows share a timestamp.
val volTSRdd = ...
// A TimeSeriesRDD with columns "time", "id", and "volume"
// time id volume
// ------------
// 1000L 1 100
// 1000L 2 200
// 2000L 1 300
// 2000L 2 400
val result = volTSRdd.summarizeCycles(Summary.sum("volume"))
// time volume_sum
// ----------------
// 1000L 300
// 2000L 700
Similarly, we could summarize over intervals, windows, or the whole time series data set. See
summarizeIntervalssummarizeWindowsaddSummaryColumns
One could check timeseries.summarize.summarizer for different kinds of summarizer(s), like ZScoreSummarizer, CorrelationSummarizer, NthCentralMomentSummarizer etc.
Contributing
In order to accept your code contributions, please fill out the appropriate Contributor License Agreement in the cla folder and submit it to [email protected].
Disclaimer
Apache Spark is a trademark of The Apache Software Foundation. The Apache Software Foundation is not affiliated, endorsed, connected, sponsored or otherwise associated in any way to Two Sigma, Flint, or this website in any manner.
© Two Sigma Open Source, LLC
3.9k Dec 30, 2022
2.5k Dec 28, 2022
757 Dec 31, 2022
4.1k Dec 29, 2022
23.6k Jan 3, 2023
2k Jan 2, 2023
1.3k Dec 22, 2022
5.2k Jan 4, 2023
2.5k Jan 6, 2023
438 Dec 17, 2022
216 Dec 30, 2022
401 Jan 8, 2023
1.6k Dec 31, 2022
1.6k Dec 29, 2022
18 Jan 4, 2022
1 Nov 23, 2021
2.3k Jan 5, 2023
15.4k Jan 7, 2023
7k Jan 6, 2023