Thinksharp.TimeFlow 1.1.4

Thinksharp.TimeFlow

Introduction

TimeFlow is a lightweight extendable library for working with time series with support for time zones and daylight saving. The core of the library is the TimeSeries type, which holds a list of time point / value pairs. Time points are represented as DateTimeOffsets. The time span between two time points (called frequency) is always identical for the whole time series. Values are represented as nullable decimals.

The first and the last time points of a TimeSeries are exposed by the Start and End properties. The interval between time points is exposed as Frequency property.

TimeSeries objects are immutable. There are some methods for transforming TimeSeries, like ReSample, Slice or Apply. Each of these methods return a new immutable object.

A collection of named time series with the same frequency can be combined to one TimeFrame.

Installation

Usage in .Net Projects

ThinkSharp.TimeFlow can be installed via Nuget

Install-Package Thinksharp.TimeFlow

Usage

Time Series Creation

Time series can be created using the available methods of the static TimeSeries.Factory property. The factory is of type ITimeSeriesFactory, which can be extended via extension methods. Therefore third party libraries may provide advanced factory methods or user can write it's own use-case specific ones.

TimeSeries.Factory.FromValue

// FromValue creates a time series with a defined value for each time point:
var ts = TimeSeries.Factory.FromValue(10,
    new DateTime(2021, 01, 01), // start
    new DateTime(2021, 01, 05), // end
    Period.Day);
 
ts

TimeSeries.Factory.FromValues

// FromValues creates a time series from an enumerable of values:
var values = new decimal?[] {1, 2, 3, 4, 5, 6, 7, 8, 9};
var ts = TimeSeries.Factory.FromValues(values,
    new DateTime(2021, 01, 01), // start
    Period.Day);

ts

TimeSeries.Factory.FromGenerator

// FromGenerator creates a time series with a value created as function of the time point:
var ts = TimeSeries.Factory.FromGenerator(
    new DateTime(2021, 01, 01), // start
    new DateTime(2021, 01, 05), // end
    Period.Day,
    tp => tp.Day); // tp: time point as DateTimeOffset

ts

Time Series Transformation

Combining Time Series via Operators

// time series can be combined using default operators:
var a = TimeSeries.Factory.FromValue(10,
    new DateTime(2021, 01, 01), // start
    new DateTime(2021, 01, 05), // end
    Period.Day);

var b = TimeSeries.Factory.FromGenerator(
    new DateTime(2021, 01, 01), // start   
    new DateTime(2021, 01, 05), // end 
    Period.Day,
    tp => tp.Day);

var tf = new TimeFrame();
tf["a"] = a;
tf["b"] = b;
tf["a + b"] = a + b;
tf["a - b"] = a - b;
tf["a * b"] = a * b;
tf["a / b"] = a / b;
tf["a * 12"] = a * 12;
tf

Combining Time Series via Methods

var a = TimeSeries.Factory.FromValue(1,
	new DateTime(2021, 01, 01), // start
	new DateTime(2021, 01, 05), // end
	Period.Day);

var b = TimeSeries.Factory.FromValue(2,
  new DateTime(2021, 01, 03), // start
  new DateTime(2021, 01, 07), // end
  Period.Day);

var tf = new TimeFrame();
tf["a"] = a;
tf["b"] = b;
tf["apply * 2"] = a.Apply(value => value * 2);

// join left produces a time series with the same time points as the left time series.
// note that nulls will be evaluated to null
tf["JoinLeft r + l"] = a.JoinLeft(b, (l, r) => l + r);

// Use pre defined JoinOperation to ignore nulls
tf["JoinLeft JoinOperation.Add"] = a.JoinLeft(b, JoinOperation.Add);

// join full combines both time series
// note that nulls will be evaluated to null
tf["JoinFull r + l"] = a.JoinFull(b, (left, right) => left + right);

// Use pre defined JoinOperation to ignore nulls
tf["JoinFull JoinOperation.Add"] = a.JoinFull(b, JoinOperation.Add);

// operators behave like full join with JoinOperations to ignore nulls.
tf["a+b"] = a + b;

tf

Slicing

var ts = TimeSeries.Factory.FromGenerator(
    new DateTime(2021, 01, 01), // start
    new DateTime(2021, 01, 05), // end
    Period.Day,
    tp => tp.Day); // 1, 2, 3, 4, 5

var tf = new TimeFrame();
// sliceing by index / count
tf["ts"] = ts;
// slicing by index / count
tf["Slice(0, 2)"] = ts.Slice(0, 2);
// slicing by time range
tf["Slice(2.1, 4.1)"] = ts.Slice(new DateTime(2021, 01, 02), new DateTime(2021, 01, 04));

tf

Re-sampling

var ts = TimeSeries.Factory.FromValue(1,
    new DateTime(2021, 01, 01), // start
    new DateTime(2021, 12, 31), // end
    Period.Day);

// down sampling
var tf = new TimeFrame();
tf["Resample Sum"] = ts.ReSample(Period.Month, AggregationType.Sum);
tf["Resample Mean"] = ts.ReSample(Period.Month, AggregationType.Mean); 
tf

// up-sampling
var tf = new TimeFrame();
tf["Resample Hour Sum"] = ts.ReSample(Period.Hour, AggregationType.Sum);
tf["Resample Hour Mean"] = ts.ReSample(Period.Hour, AggregationType.Mean);
tf

Usage in LINQPad

Thinksharp.TimeFlow.LinqPad provides chart and raw data visualization extensions for LINQPad.

Usage in Excel / WPF

Thinksharp.TimeFlow.Reporting provides chart and advanced reporting functionality for excel and WPF.

Usage in .Net Interactive (Jupiter Notebooks)

Reference Nuget Package Thinksharp.TimeFlow and Thinksharp.TimeFlow.Interactive as well as XPlot.Plotly if you want to use plotting abilities.

#r "nuget: Thinksharp.TimeFlow"
#r "nuget: Thinksharp.TimeFlow.Interactive"
#r "nuget: XPlot.Plotly"
#r "nuget: XPlot.Plotly.Interactive"

License

ThinkSharp.TimeFlow is released under The MIT license (MIT)

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Donation

If you like ThinkSharp.TimeFlow and use it in your project(s), feel free to give me a cup of coffee 😃