README.md 1.95 KB
Newer Older
Aurélien Campéas's avatar
Aurélien Campéas committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
# TSHISTORY

This is a library to store/retrieve pandas timeseries to/from a
postgres database, tracking their successive versions.


# Principles

There are many ways to represent timeseries in a relational database,
and `tshistory` provides two things:

* a base python API which abstracts away the underlying storage

* a postgres model, which uses JSONB fields to store the bulk of the
  series data.

The core idea of tshistory is to handle successive versions of
timeseries as they grow in time, allowing to get older states of any
series.

Series state can be indexed by either a timestamp (which typically
matches the moment a new insertion took place) or a `changeset id`
which denotes the exact change leading to a given version.


# Basic usage


Complete usage is shown in the test suite. However here's a simple
example:

```python
 from datetime import datetime
 from sqlalchemy import create_engine
 import pandas as pd
 from tshistory.tsio import TimeSerie

 engine = create_engine('postgres://me:password@localhost/mydb')
 tsh = TimeSerie()

 serie = pd.Series([1, 2, 3],
                  pd.date_range(start=datetime(2017, 1, 1),
                                freq='D', periods=3))
 # db insertion
 tsh.insert(engine, serie, 'my_serie', 'aurelien@campeas.fr')

 # db retrieval
 assert tsh.get(engine, 'my_serie') == serie
```

This is good. Now, let's add more:

```python
 serie = pd.Series([7, 8, 9],
                  pd.date_range(start=datetime(2017, 1, 3),
                                freq='D', periods=3))
 # db insertion
 tsh.insert(engine, serie, 'my_serie', 'aurelien@campeas.fr')

 # db retrieval
 stored = tsh.get(engine, 'my_serie')

 assert """
2017-01-01    1
2017-01-02    2
2017-01-03    7
2017-01-04    8
2017-01-04    9
Freq: D
""".strip() == stored.to_string().strip()
```

It is important to note that the third value was replaced, and the two
last values were just appended.