timedatamodel

KO | EN

gitlite — search

#javascript #python #ai #golang #android #machine-learning #rust #macos #nodejs #windows #awesome #kubernetes #vue #pytorch

(★ 9)

A lightweight Pythonic data model for time series data, interoperable with NumPy, Pandas and Polars.

timedatamodel 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# TimeDataModel

**A lightweight Pythonic data model for time series data, interoperable with NumPy, Pandas and Polars.**

</div>

<br/>

**TimeDataModel** is a metadata-rich container for time series data. It lets you carry your data *and* its context — name, unit, frequency, timezone — as a single, self-describing object, fully interoperable with pandas, NumPy, Polars, and PyArrow.

**⬇️ [Installation](#installation)**
&ensp;|&ensp;
**📖 [Documentation](https://timedatamodel.readthedocs.io/en/latest/)**
&ensp;|&ensp;
**🚀 [Examples](https://timedatamodel.readthedocs.io/en/latest/examples/index.html)**

---

## 🧱 Core Data Classes

| Class | Description |
| :---- | :---------- |
| 📈&nbsp;`TimeSeries` | Univariate time series supporting four temporal shapes; the underlying DataFrame is optional, so the same class also serves as a metadata-only descriptor for catalog/registration use |
| 🔷&nbsp;`DataShape` | Enum that selects which timestamp columns are present: `SIMPLE`, `VERSIONED`, `CORRECTED`, or `AUDIT` |
| ⏱️&nbsp;`Frequency` | ISO 8601 duration-based frequencies (`PT1H`, `P1D`, `P1M`, …) |
| 🏷️&nbsp;`DataType` | Hierarchical taxonomy: `ACTUAL` → `OBSERVATION`, `DERIVED`; `CALCULATED` → `FORECAST`, `SIMULATION`, … |
| 🗺️&nbsp;`GeoLocation` / `GeoArea` | Geographic point and polygon types with distance, bearing, and containment |

---

## 📐 Data Shapes

`TimeSeries` supports four **temporal shapes** to model everything from simple point-in-time
data to full audit trails:

---

## 🚀 Quick Start

```python
import pandas as pd
from timedatamodel import TimeSeries, Frequency

# --- Univariate series from a pandas DataFrame ---
df = pd.DataFrame({
    "valid_time": pd.date_range("2024-01-01", periods=24, freq="h", tz="UTC"),
    "value": [100.0 + i * 2.5 for i in range(24)],
})

ts = TimeSeries.from_pandas(
    df,
    frequency=Frequency.PT1H,
    name="wind_power",
    unit="MW",
)

print(ts)
# TimeSeries ─────────────────────────
#   Name        wind_power
#   Shape       SIMPLE
#   Rows        24
#   Frequency   PT1H
#   Timezone    UTC
#   Unit        MW
#  ──────────────────────────────────────────
#                  wind_power
#  2024-01-01 00:00   100.0
#  2024-01-01 01:00   102.5
#  ...

# --- Unit conversion (requires pint extra) ---
ts_kw = ts.convert_unit("kW")

# --- Format conversions ---
df_pd  = ts.to_pandas()       # pd.DataFrame with datetime index
df_pl  = ts.to_polars()       # pl.DataFrame
cols   = ts.to_list()         # dict[str, list] — column-oriented
arr    = ts.to_numpy()        # dict[str, np.ndarray] — column-oriented (requires numpy)
tbl    = ts.to_pyarrow()      # pa.Table (requires pyarrow)
```

---

## ✨ Key Features

- 🔷 **Four data shapes** — from `SIMPLE` point-in-time to `AUDIT` full audit history;
- 🏷️ **Metadata** — name, unit, frequency, timezone, data type, description on every series;
- 📋 **Metadata-only mode** — construct `TimeSeries(df=None, …)` to declare a series' structure before any data exists, for catalog/registration use;
- 🔄 **Format conversions** — `to_pandas`, `to_polars`, `to_list`, `to_numpy`, `to_pyarrow` with lazy optional-dependency checks;
- 📊 **Coverage bar** — `coverage_bar()` renders null coverage as a binned SVG in Jupyter or Unicode blocks in terminal;
- 🗺️ **Geospatial primitives** — `GeoLocation` and `GeoArea` for use by consumer layers;
- 📏 **Units** — optional [pint](https://pint.readthedocs.io/) integration for dimensional unit conversion and validation;
- ⚡ **Polars-powered** — backed by the Polars compute engine for high-performance in-memory processing;
- 🐍 **Type-safe** — full type hints with PEP 561 support.

---

## ⬇️ Installation

Install the **stable** release:
```bash
pip install timedatamodel
```

Install with **optional dependencies**:
```bash
pip install timedatamodel[pandas]    # pandas interop (includes pyarrow for tz-aware columns)
pip install timedatamodel[pint]      # unit conversion
pip install timedatamodel[geo]       # geospatial support (shapely)
pip install timedatamodel[all]       # all optional extras
```

Install in editable mode for **development**:
```bash
git clone https://github.com/rebase-energy/timedatamodel.git
cd TimeDataModel
pip install -e .[dev]
```

---

## 🤝 Contributing

Contributions are welcome! Here are some ways to contribute to **TimeDataModel**:

* Propose new features or extend existing classes;
* Improve documentation or add example notebooks;
* Report bugs or suggest features via [GitHub Issues](https://github.com/rebase-energy/timedatamodel/issues).

---

## 📄 Licence

This project uses the [MIT Licence](LICENSE).

timedatamodel

timedatamodel 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

timedatamodel

timedatamodel 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README