# Correlation App

Die *Correlation App* analysiert Korrelationen zwischen Attributen von Assets unter Berücksichtigung anpassbarer Zeitverzögerungen (*Lag Intervals*) und generiert umfassende Berichte mit Visualisierungen.

***

## Hauptfunktionen

* **Zeitverzögerungsbasierte Korrelation**: Analysieren Sie Zusammenhänge zwischen Attributen für definierte Zeitverzögerungen.
* **Berichtsgenerierung**: Erstellen Sie HTML- und PDF-Berichte mit Heatmaps, Streudiagrammen und Verzögerungsdiagrammen.
* **E-Mail-Integration**: Senden Sie Berichte direkt an festgelegte Empfänger.
* **Anpassbarer Zeitraum**: Legen Sie den Start- und Endzeitpunkt der Analyse fest.

***

## Konfiguration

### Umgebungsvariablen

| Variable            | Beschreibung                                              | Beispiel                                |
| ------------------- | --------------------------------------------------------- | --------------------------------------- |
| `CONNECTION_STRING` | Verbindungsdetails zur Eliona-Datenbank.                  | `postgres://user:pass@host:port/dbname` |
| `API_ENDPOINT`      | API-Endpunkt für den Zugriff auf Eliona-Services.         | `http://api-v2:3000/v2`                 |
| `API_TOKEN`         | Authentifizierungs-Token für Eliona-Services.             | `your_api_token`                        |
| `API_SERVER_PORT`   | (Optional) Port für den API-Server. Standardwert: `3000`. | `3000`                                  |
| `SMTP_SERVER`       | Adresse des SMTP-Servers.                                 | `smtp.example.com`                      |
| `SMTP_PORT`         | Port des SMTP-Servers.                                    | `587`                                   |
| `SMTP_USER`         | Benutzername für den SMTP-Server.                         | `user@example.com`                      |
| `SMTP_PASSWORD`     | Passwort für den SMTP-Server.                             | `password`                              |

## API-Endpunkte

### **1. POST /v1/correlate**

**Beschreibung**: Berechnet die Korrelation zwischen den angegebenen Attributen mehrerer Assets.

* Wird nur eine Asset-ID angegeben (ohne Attributnamen), werden alle Attribute des Assets miteinander korreliert.

**Anfragetext**:

```json
{
    "assets": ,
    "lags": ,
    "start_time":,
    "end_time": ,
    "to_email": ,
}
```

**Antwort**:

* **200 OK**: Rückgabe folgender Daten:
  * Analysierte Assets und Zeitverzögerungen.
  * Zeitspanne der Analyse.
  * Ergebnisse der Korrelation inkl. `best_correlation`, `best_lag` und `lag_details`.
  * Ein HTML-Bericht (`report_html`) mit Heatmap-Visualisierungen.
  * Wenn `to_email` angegeben ist, wird der Bericht per E-Mail versendet.
* **400 Bad Request**: Ungültige Eingabeparameter.

***

### **2. POST /v1/correlate-children**

**Beschreibung**: Korreliert alle Attribute von Kind-Assets eines angegebenen Assets.

**Anfragetext**: Wie bei `/v1/correlate`, jedoch mit Angabe von `asset_id` anstelle einer Liste von Assets.

**Antwort**: Identisch zu `/v1/correlate`, einschließlich HTML-Bericht.

***

### **3. POST /v1/in-depth-correlation**

**Beschreibung**: Führt eine detaillierte Korrelationsanalyse für genau zwei Attribute durch.

**Antwort**:

* Detaillierte Korrelationsdaten inkl.:
  * Beste Korrelation und zugehörige Verzögerung.
  * Korrelationswerte für jede getestete Verzögerung.
* HTML-Bericht (`report_html`) mit Streu- und Verzögerungsdiagrammen.

***

## Anfrageparameter

Folgende Parameter können in der Anfrage enthalten sein:

* **assets**: Liste von Asset-Attribut-Paaren für die Analyse. Ohne Attributangabe werden alle Attribute des Assets analysiert.
* **lags**: Optionale Zeitverzögerungen, z. B. `{"hours": 10}`.
* **start\_time**, **end\_time**: Zeitspanne der Analyse.
* **to\_email**: (Optional) E-Mail-Adresse für den Versand des Berichts.

### Beispielanfrage

```json
{
    "assets": [
        {"asset_id": 123, "attribute_name": "temperature"},
        {"asset_id": 456, "attribute_name": "humidity"}
    ],
    "lags": [
        {"minutes": 15},
        {"hours": 2},
        {"days": 1}
    ],
    "start_time": "2025-01-01T00:00:00",
    "end_time": "2025-01-03T23:59:59",
    "to_email": "example@domain.com"
}
```

## Beispielantwort für die API-Anfrage `/v1/correlate`

```json
{
    "assets": [
        {"asset_id": 123, "attribute_name": "temperature"},
        {"asset_id": 456, "attribute_name": "humidity"}
    ],
    "lags": [
        {"minutes": 15},
        {"hours": 2},
        {"days": 1}
    ],
    "start_time": "2025-01-01T00:00:00",
    "end_time": "2025-01-03T23:59:59",
    "correlation": {
        "temperature and humidity": {
            "best_correlation": 0.85,
            "best_lag": 2,
            "lag_unit": "hours",
            "lag_details": [
                {"lag_step": -2, "lag_unit": "hours", "correlation": 0.75},
                {"lag_step": 0, "lag_unit": "hours", "correlation": 0.85},
                {"lag_step": 2, "lag_unit": "hours", "correlation": 0.80}
            ]
        }
    },
    "report_html": "<!DOCTYPE html><html><head>...</head><body>...</body></html>"
}
```

### Erklärung der Antwortfelder

1. **assets**:
   * Enthält die analysierten Assets und ihre Attribute, z. B. Temperatur und Feuchtigkeit.
2. **lags**:
   * Liste der getesteten Zeitverzögerungen: 15 Minuten, 2 Stunden und 1 Tag.
3. **start\_time**, **end\_time**:
   * Der Zeitraum der Analyse, hier 1. bis 3. Januar 2025.
4. **correlation**:
   * Detaillierte Korrelationsdaten:
     * **best\_correlation**: Höchster Korrelationswert (0,85).
     * **best\_lag**: Die Zeitverzögerung (2 Stunden), bei der die höchste Korrelation auftritt.
     * **lag\_details**: Korrelationswerte für verschiedene Verzögerungen (-2, 0, +2 Stunden).
5. **report\_html**:
   * Ein HTML-Bericht mit Visualisierungen wie Heatmaps und Streudiagrammen, bereit zum direkten Anzeigen oder Speichern.

***

## Berichtserstellung

Berichte enthalten folgende Visualisierungen:

#### HTML-Bericht

Generiert für die Endpunkte `/v1/correlate` und `/v1/correlate-children`:

* **Heatmaps**: Beste Korrelationen zwischen Attributen.
* **Korrelationszahlen**: Detailstatistiken zu jeder Korrelation.

Generiert für den Endpunkt `/v1/in-depth-correlation`:

* **Streudiagramme**: Beziehungen zwischen Attributen.
* **Verzögerungsdiagramme**: Zeitabhängige Trends.