{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting Started with TimeDataModel\n",
    "\n",
    "TimeDataModel is a lightweight Python data model for time series data. It gives you structured, metadata-rich time series objects with seamless bridges to pandas, numpy, and polars. This notebook walks you through the basics: creating a `TimeSeriesList`, inspecting it, and converting it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installation\n",
    "\n",
    "```bash\n",
    "pip install timedatamodel\n",
    "\n",
    "# With optional extras\n",
    "pip install timedatamodel[polars]   # polars support\n",
    "pip install timedatamodel[geo]      # GeoArea support via shapely\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating your first TimeSeriesList\n",
    "\n",
    "A `TimeSeriesList` needs a frequency, timestamps, and values. You can optionally attach metadata like a name, unit, and data type."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "from datetime import datetime, timedelta, timezone\n\nimport timedatamodel as tdm\n\nbase = datetime(2024, 1, 15, tzinfo=timezone.utc)\ntimestamps = [base + timedelta(hours=i) for i in range(24)]\nvalues = [\n    120.0, 115.0, 108.0, 105.0, 102.0, 100.0,\n    110.0, 135.0, 160.0, 175.0, 180.0, 178.0,\n    172.0, 170.0, 168.0, 165.0, 175.0, 190.0,\n    200.0, 195.0, 180.0, 165.0, 145.0, 130.0,\n]\n\nts = tdm.TimeSeriesList(\n    tdm.Frequency.PT1H,\n    timezone=\"UTC\",\n    timestamps=timestamps,\n    values=values,\n    name=\"power\",\n    unit=\"MW\",\n    description=\"Hourly power output from wind farm Alpha\",\n    data_type=tdm.DataType.OBSERVATION,\n)"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Rich notebook display\n",
    "\n",
    "Simply evaluate a `TimeSeriesList` in a cell to see its HTML representation — metadata and a data preview with head/tail rows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ts"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## DataPoints and iteration\n",
    "\n",
    "Each element in a `TimeSeriesList` is a `DataPoint` — a named tuple of `(timestamp, value)`. You can index, slice, and iterate."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "dp = ts[0]\nprint(f\"First point: {dp}\")\nprint(f\"  timestamp = {dp.timestamp}\")\nprint(f\"  value     = {dp.value}\")"
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ts[:3]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for dp in ts.head(4):\n",
    "    print(f\"{dp.timestamp:%H:%M}  {dp.value:>6.1f} MW\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Inspecting properties\n",
    "\n",
    "A `TimeSeriesList` exposes handy properties for quick inspection."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(f\"Length:      {len(ts)} points\")\n",
    "print(f\"Begin:       {ts.begin}\")\n",
    "print(f\"End:         {ts.end}\")\n",
    "print(f\"Duration:    {ts.duration}\")\n",
    "print(f\"Has missing: {ts.has_missing}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating from DataPoints\n",
    "\n",
    "You can also construct a `TimeSeriesList` from a list of `DataPoint` objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": "data = [\n    tdm.DataPoint(datetime(2024, 1, 15, h, tzinfo=timezone.utc), v)\n    for h, v in [(0, 5.2), (1, 5.8), (2, 6.1), (3, 5.5)]\n]\n\nts_temp = tdm.TimeSeriesList(\n    tdm.Frequency.PT1H,\n    data=data,\n    name=\"temperature\",\n    unit=\"°C\",\n)\nts_temp"
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "In this notebook you learned how to:\n",
    "\n",
    "- Create a `TimeSeriesList` with metadata (name, unit, data type)\n",
    "- View its rich display in a notebook\n",
    "- Access individual `DataPoint` elements via indexing, slicing, and iteration\n",
    "- Inspect basic properties: `begin`, `end`, `duration`, `has_missing`\n",
    "\n",
    "Next up: **nb_02** shows how to use numpy and pandas to transform time series data."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.14.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}