# TimeSeries Daten

Arbeiten mit Zeitreihen-Daten in Questra Data.

## Zeitreihen-Werte laden

### Als Dictionary

```python
from datetime import datetime

result = client.list_timeseries_values(
    inventory_name="Stromzaehler",
    namespace_name="Energie",
    timeseries_property="messwerte_Energie",
    from_time=datetime(2025, 1, 1),
    to_time=datetime(2025, 12, 31)
)

# Ergebnis: {item_id: {"item": {...}, "values": [TimeSeriesValue, ...]}}
for item_id, data in result.items():
    print(f"Item: {data['item']['stromzaehlernummer']}")
    for value in data['values']:
        print(f"  {value.time}: {value.value} ({value.quality})")
```

### Als DataFrame

```python
# TimeSeriesResult laden und zu DataFrame konvertieren
result = client.list_timeseries_values(
    inventory_name="Stromzaehler",
    namespace_name="Energie",
    timeseries_property="messwerte_Energie",
    from_time=datetime(2025, 1, 1),
    to_time=datetime(2025, 12, 31)
)

# Als Dictionary verwenden
for item_id, data in result.items():
    print(f"Item {item_id}: {len(data['values'])} Werte")

# Optional: zu DataFrame konvertieren
df = result.to_df(include_metadata=True)

# DataFrame Struktur:
#                        value  quality  item_id  item_stromzaehlernummer
# time
# 2025-01-01 12:00:00   100.5    VALID   630...   SZ-12345

# Mit zusätzlichen Properties als Spalten
df = result.to_df(
    include_metadata=True,
    properties=["stromzaehlernummer", "standort"]
)
```

!!! tip "Flexibilität"
    Mit `.to_df()` können Sie zuerst mit Dictionary-Daten arbeiten und später entscheiden, ob Sie einen DataFrame benötigen.

## Zeitreihen-Werte speichern

### Einzelne Werte

```python
from questra_data import TimeSeriesValue, Quality

values = [
    TimeSeriesValue(
        time=datetime(2025, 1, 1, 12, 0),
        value=100.5,
        quality=Quality.VALID
    )
]

client.save_timeseries_values(
    inventory_name="Stromzaehler",
    namespace_name="Energie",
    item_id="630...",
    timeseries_property="messwerte_Energie",
    values=values
)
```

### Batch Write

```python
# Viele Werte auf einmal schreiben
values = [
    TimeSeriesValue(
        time=datetime(2025, 1, 1, i),
        value=float(i * 10),
        quality=Quality.VALID
    )
    for i in range(100)
]

client.save_timeseries_values(
    inventory_name="Stromzaehler",
    namespace_name="Energie",
    item_id="630...",
    timeseries_property="messwerte_Energie",
    values=values
)
```

## Quality Codes

```python
from questra_data import Quality

# Verfügbare Quality Codes
Quality.VALID       # Gültige Messung
Quality.INVALID     # Ungültige Messung
Quality.ESTIMATED   # Geschätzter Wert
Quality.MISSING     # Fehlender Wert
```

## Zeitreihen-Analysen mit pandas

### Resampling

```python
result = client.list_timeseries_values(...)
df = result.to_df()

# Tägliche Mittelwerte
daily_avg = df.resample('1D').mean()

# Monatliche Summen
monthly_sum = df.resample('1M').sum()

# Stündliche Maxima
hourly_max = df.resample('1H').max()
```

### Aggregationen

```python
# Statistiken pro Item
stats = df.groupby('item_id')['value'].agg(['mean', 'std', 'min', 'max'])

# Qualitäts-Verteilung
quality_dist = df['quality'].value_counts()
```

### Plotting

```python
import matplotlib.pyplot as plt

df['value'].plot(title='Zeitreihen-Verlauf')
plt.show()

# Mit mehreren Items
df.pivot(columns='item_id', values='value').plot()
```

## Low-Level REST API

Für direkten Zugriff auf die REST API:

```python
lowlevel = client.lowlevel

# TimeSeries Daten abrufen
data = lowlevel.timeseries.get_data(
    inventory_name="Stromzaehler",
    namespace_name="Energie",
    item_id="630...",
    property_name="messwerte_Energie",
    from_time=datetime(2025, 1, 1),
    to_time=datetime(2025, 12, 31)
)

# TimeSeries Daten setzen
lowlevel.timeseries.set_data(
    inventory_name="Stromzaehler",
    namespace_name="Energie",
    item_id="630...",
    property_name="messwerte_Energie",
    data=...
)
```

## Siehe auch

- [TimeSeriesValue](../api/models-timeseries.md)
- [REST Operationen](../api/rest-operations.md)
- [QuestraData](../api/highlevel-client.md)
