Metadata-Version: 2.4
Name: tslite-og
Version: 2.1.0
Summary: The original lightweight time-series library. Since 2009.
Author: Gunnar Leffler
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/gunnarleffler/tslite
Project-URL: Repository, https://github.com/gunnarleffler/tslite
Project-URL: Issues, https://github.com/gunnarleffler/tslite/issues
Project-URL: Changelog, https://github.com/gunnarleffler/tslite/blob/master/CHANGELOG.md
Keywords: timeseries,time-series,hydrology,environmental,sqlite
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dateutil>=2.8
Provides-Extra: numpy
Requires-Dist: numpy>=1.24; extra == "numpy"
Dynamic: license-file

# tslite-OG

```text
 _       _ _ _
| |_ ___| (_) |_ ___
| __/ __| | | __/ _ \
| |_\__ \ | | ||  __/
 \__|___/_|_|\__\___| v2.1.0
 a lightweight timeseries library
```

**The original lightweight time-series library. Since 2009.**

Small enough to understand. Flexible enough for real-world data.

tslite works with timestamp/value observations, whether they arrive regularly,
contain gaps, or turn up out of order. It provides arithmetic, filtering,
interpolation, moving windows, statistics, and SQLite storage without requiring
a DataFrame or NumPy.

## Background

I started tslite in 2009 to work with time series in an elegant, practical way.
I've maintained and used it ever since, particularly for engineering and
hydrological data. Real observations are messy: the goal is accurate calculations
with explicit, useful ways to handle that mess.

The project remains **tslite** on GitHub and in Python. Its PyPI distribution is
**tslite-og**—a distinct package name for the original library's modern continuation.
It is still a single Python module, not a framework.

## Installation

Requires Python 3.11 or newer.

```sh
pip install tslite-og
# Or:
uv add tslite-og
```

```python
import tslite
```

NumPy is optional, needed only for the NumPy-based filters:

```sh
pip install 'tslite-og[numpy]'
```

## Start with observations

```python
from datetime import datetime
from tslite import timeseries

flow = timeseries([
    (datetime(2024, 1, 1, 2), 12),
    (datetime(2024, 1, 1, 0), 2),
    (datetime(2024, 1, 1, 1), 4),
])

# Observations are sorted; inserting an existing timestamp replaces its value.
print(flow.values())                  # [2.0, 4.0, 12.0]
print(flow.globalAverage()[1])        # 6.0
print(flow.runningTotal().values())   # [2.0, 6.0, 18.0]
print(flow.firstdifference().values())  # [2.0, 8.0]
```

Calculations return new series, so transformations can be chained:

```python
adjusted = flow.mul(1.5).add(2)
high_flow = flow.cullBelow(3)  # Keep values greater than 3.

print(adjusted.values())   # [5.0, 8.0, 20.0]
print(high_flow.values())  # [4.0, 12.0]
```

## Moving windows

Intervals accept strings such as `"30m"`, `"2h"`, or `"1d6h"`, as well as
`datetime.timedelta` objects. Moving averages weight observations equally and
include both window endpoints.

```python
print(flow.movingaverage("2h").values())        # [2.0, 3.0, 6.0]
print(flow.centerMovingAverage("2h").values())  # [3.0, 6.0, 8.0]

# Require complete windows instead of averaging available edge observations.
print(flow.movingaverage("2h", require_full_window=True).values())  # [6.0]
```

## Make a grid and select matching data

```python
grid = timeseries.createRegular(
    start=datetime(2024, 1, 1, 0),
    end=datetime(2024, 1, 1, 4),
    interval="2h",
)
selected = grid.cut(flow)
print(selected.values())  # [2.0, 12.0]
```

`grid.cut(flow)` keeps **flow's values at exact grid timestamps**. It doesn't
invent missing observations. Use interpolation or filling when that's intended.

## Compare messy data explicitly

```python
from datetime import timedelta

shifted = flow.timeshift(timedelta(milliseconds=1))

assert flow != shifted                       # Exact timestamps and values.
assert flow.same_data(shifted)                # Compare values, ignoring timestamps.
assert flow.is_close(shifted, time_tolerance="0.001s")
```

`is_close()` accepts timestamp, absolute-value, and relative-value tolerances:

```python
matches = flow.is_close(
    shifted,
    time_tolerance="1s",
    value_tolerance=0.001,
    relative_tolerance=0.0001,
)
```

Observations are compared in order; lengths must match. No hidden realignment
or interpolation occurs.

## Store observations in SQLite

```python
import sqlite3

with sqlite3.connect("observations.sqlite3") as connection:
    flow.saveSQLITE3(connection, "flow")
    if flow.status != "OK":
        raise RuntimeError(flow.status)

    loader = timeseries()
    recent = loader.loadSQLITE3(
        connection, "flow",
        start_time=datetime(2024, 1, 1, 1),
    )
    if loader.status != "OK":
        raise RuntimeError(loader.status)

print(recent.values())  # [4.0, 12.0]
```

Saves insert new timestamps and update only changed values. Existing caller
transactions remain under the caller's control. SQLite preserves timestamps as
integer microseconds. Binary, TSV, and JSON helpers are also available.

Ready for more? Read the [tslite manual](doc/tslite.md) for public methods,
worked examples, time conventions, and storage. See the [changelog](CHANGELOG.md)
when upgrading.

## Development and documentation

```sh
uv sync --extra numpy
uv run pytest
```

Documentation is ordinary Markdown: this introduction and the
[manual](doc/tslite.md). No site generator needed. The manual explains public
methods with examples; source docstrings provide quick help inside Python.

Tests include executable README/manual examples, small numerical calculations,
and read-only historical fixtures. Run all supported Python versions and verify
locally built packages with:

```sh
uv run python scripts/verify_release.py
```

See the [changelog](CHANGELOG.md) for changes and migration details.
Source: [github.com/gunnarleffler/tslite](https://github.com/gunnarleffler/tslite).

## License

[Apache License 2.0](LICENSE).
