Merge pull request #5 from rebase-energy/slim

Make name required; drop labels/location; unexport TimeSeriesTable; add validate_unit

Author: FreaxMATE

README.md

@@ -13,7 +13,7 @@
 
 <br/>
 
-**TimeDataModel** is a metadata-rich container for time series data. It lets you carry your data *and* its context — name, unit, frequency, timezone, location — as a single, self-describing object, fully interoperable with pandas, NumPy, Polars, and PyArrow.
+**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;
@@ -28,7 +28,7 @@
 | Class | Description |
 | :---- | :---------- |
 | 📈&nbsp;`TimeSeries` | Univariate time series supporting four temporal shapes |
-| 📊&nbsp;`TimeSeriesTable` | Multivariate time series — multiple named columns sharing the same `valid_time` index |
+| 📋&nbsp;`TimeSeriesDescriptor` | Frozen, data-free metadata descriptor — register a series structure before any data exists |
 | 🔷&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`, … |
@@ -54,7 +54,7 @@ data to fully bi-temporal audit trails:
 
 ```python
 import pandas as pd
-from timedatamodel import TimeSeries, TimeSeriesTable, Frequency
+from timedatamodel import TimeSeries, Frequency
 
 # --- Univariate series from a pandas DataFrame ---
 df = pd.DataFrame({
@@ -92,21 +92,19 @@ 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)
-
-# --- Multivariate table — see examples/nb_02_timeseriestable.ipynb ---
 ```
 
 ---
 
 ## ✨ Key Features
 
 - 🔷 **Four data shapes** — from `SIMPLE` point-in-time to `AUDIT` full bi-temporal history;
-- 🏷️ **Rich metadata** — name, unit, frequency, timezone, data type, location, labels, description on every series;
-- 📊 **Multivariate tables** — `TimeSeriesTable` groups co-indexed series with per-column metadata;
+- 🏷️ **Metadata** — name, unit, frequency, timezone, data type, description on every series;
+- 📋 **Descriptor** — `TimeSeriesDescriptor` carries the same metadata without a DataFrame, 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** — attach locations, filter by radius or area, find nearest columns;
-- 📏 **Units** — optional [pint](https://pint.readthedocs.io/) integration for dimensional unit conversion;
+- 🗺️ **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.
 
@@ -136,15 +134,6 @@ pip install -e .[dev]
 
 ---
 
-## 📓 Examples
-
-| # | Notebook | Topic |
-| :--- | :--- | :--- |
-| 01 | [TimeSeries](examples/nb_01_timeseries.ipynb) | Creating, inspecting, and operating on univariate time series |
-| 02 | [TimeSeriesTable](examples/nb_02_timeseriestable.ipynb) | Multivariate tables with per-column metadata and spatial filtering |
-
----
-
 ## 🤝 Contributing
 
 Contributions are welcome! Here are some ways to contribute to **TimeDataModel**:

docs/api.md

@@ -16,14 +16,6 @@
    :show-inheritance:
 ```
 
-## TimeSeriesTable
-
-```{eval-rst}
-.. autoclass:: timedatamodel.TimeSeriesTable
-   :members:
-   :show-inheritance:
-```
-
 ## DataShape
 
 ```{eval-rst}

docs/conf.py

@@ -72,8 +72,6 @@ def setup(app) -> None:
         # TimeSeries internals
         "_clone",
         "_validate_table",
-        # TimeSeriesTable internals
-        "_clone_df",
     ]),
 }
 

docs/examples/index.md

@@ -1,11 +1,5 @@
 # Examples
 
-Step-by-step guides that walk you through the features of timedatamodel.
-Each example is a Jupyter notebook that you can download and run interactively.
-
-```{toctree}
-:maxdepth: 1
-
-timeseries
-timeseriestable
-```
+Notebook examples are being rewritten. In the meantime, see the
+[Quick Start](../usage.md) page and the [Overview](../overview.md) for
+runnable snippets.