# Korrelations-App

Der *Korrelations-App* analysiert Korrelationen zwischen Attributen von Anlagen und berücksichtigt dabei anpassbare Zeitverzögerungen (*Verzögerungsintervalle*) und erstellt umfassende Berichte mit Visualisierungen.

***

## Hauptfunktionen

* **Korrelation auf Basis von Zeitverzögerungen**: Analysiert Korrelationen zwischen Attributen für definierte Zeitverzögerungen.
* **Berichterstellung**: Erstellt HTML- und PDF-Berichte mit Heatmaps, Streudiagrammen und Verzögerungsdiagrammen.
* **E-Mail-Integration**: Sendet Berichte direkt an definierte Empfänger.
* **Anpassbarer Zeitraum**: Legt Start- und Endzeit der Analyse fest.

***

## Konfiguration

### Umgebungsvariablen

| Variable            | Beschreibung                                                 | Beispiel                                |
| ------------------- | ------------------------------------------------------------ | --------------------------------------- |
| `CONNECTION_STRING` | Verbindungsdetails zur BuildingPro-Suites-Datenbank.         | `postgres://user:pass@host:port/dbname` |
| `API_ENDPOINT`      | API-Endpunkt für den Zugriff auf BuildingPro-Suites-Dienste. | `http://api-v2:3000/v2`                 |
| `API_TOKEN`         | Authentifizierungstoken für BuildingPro-Suites-Dienste.      | `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 Anlagen.

* Wenn nur eine Anlagen-ID angegeben ist (ohne Attributnamen), werden alle Attribute der Anlage miteinander korreliert.

**Anfragetext**:

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

**Antwort**:

* **200 OK**: Gibt die folgenden Daten zurück: \* Analysierte Anlagen und Zeitverzögerungen. \* Zeitraum der Analyse. \* Korrelationsergebnisse einschließlich `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 gesendet.
* **400 Bad Request**: Ungültige Eingabeparameter.

***

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

**Beschreibung**: Korreliert alle Attribute der untergeordneten Anlagen einer angegebenen Anlage.

**Anfragetext**: Entspricht `/v1/correlate`, aber mit `asset_id` anstelle einer Liste von Anlagen.

**Antwort**: Identisch mit `/v1/correlate`, einschließlich des HTML-Berichts.

***

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

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

**Antwort**:

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

***

## Anforderungsparameter

Die folgenden Parameter können in die Anfrage aufgenommen werden:

* **assets**: Liste von Anlagen-Attribut-Paaren für die Analyse. Wenn kein Attribut angegeben ist, werden alle Attribute der Anlage analysiert.
* **lags**: Optionale Zeitverzögerungen, z. B. `{"hours": 10}`.
* **start\_time**, **end\_time**: Zeitraum der Analyse.
* **to\_email**: (Optional) E-Mail-Adresse zum Senden 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>"
}
```

### Erläuterung der Antwortfelder

1. **assets**:
   * Enthält die analysierten Anlagen und ihre Attribute, z. B. Temperatur und Luftfeuchtigkeit.
2. **lags**:
   * Liste der getesteten Zeitverzögerungen: 15 Minuten, 2 Stunden und 1 Tag.
3. **start\_time**, **end\_time**:
   * Der Zeitraum der Analyse, hier der 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, direkt zur Anzeige oder zum Speichern bereit.

***

## Berichtserstellung

Berichte enthalten die folgenden Visualisierungen:

#### HTML-Bericht

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

* **Heatmaps**: Beste Korrelationen zwischen Attributen.
* **Korrelationszahlen**: Detaillierte Statistiken für jede Korrelation.

Erstellt für die `/v1/in-depth-correlation` Endpunkt:

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