# Correlation App

The *Correlation App* analyzes correlations between asset attributes, taking into account customizable time delays (*Lag Intervals*), and generates comprehensive reports with visualizations.

***

## Main Functions

* **Time-delay-based correlation**: Analyze correlations between attributes for defined time delays.
* **Report generation**: Create HTML and PDF reports with heatmaps, scatter plots, and delay charts.
* **Email integration**: Send reports directly to defined recipients.
* **Customizable time period**: Set the start and end time of the analysis.

***

## Configuration

### Environment Variables

| Variable            | Description                                                | Example                                 |
| ------------------- | ---------------------------------------------------------- | --------------------------------------- |
| `CONNECTION_STRING` | Connection details to the BuildingPro Suites database.     | `postgres://user:pass@host:port/dbname` |
| `API_ENDPOINT`      | API endpoint for accessing BuildingPro Suites services.    | `http://api-v2:3000/v2`                 |
| `API_TOKEN`         | Authentication token for BuildingPro Suites services.      | `your_api_token`                        |
| `API_SERVER_PORT`   | (Optional) Port for the API server. Default value: `3000`. | `3000`                                  |
| `SMTP_SERVER`       | Address of the SMTP server.                                | `smtp.example.com`                      |
| `SMTP_PORT`         | Port of the SMTP server.                                   | `587`                                   |
| `SMTP_USER`         | Username for the SMTP server.                              | `user@example.com`                      |
| `SMTP_PASSWORD`     | Password for the SMTP server.                              | `password`                              |

## API Endpoints

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

**Description**: Calculates the correlation between the specified attributes of multiple assets.

* If only one asset ID is specified (without an attribute name), all attributes of the asset are correlated with each other.

**Request body**:

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

**Response**:

* **200 OK**: Returns the following data: \* Analyzed assets and time delays. \* Time period of the analysis. \* Correlation results including `best_correlation`, `best_lag`, and `lag_details`. \* An HTML report (`report_html`) with heatmap visualizations. \* If `to_email` is specified, the report is sent via email.
* **400 Bad Request**: Invalid input parameters.

***

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

**Description**: Correlates all attributes of child assets of a specified asset.

**Request body**: Same as with `/v1/correlate`, but with `asset_id` instead of a list of assets.

**Response**: Identical to `/v1/correlate`, including the HTML report.

***

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

**Description**: Performs a detailed correlation analysis for exactly two attributes.

**Response**:

* Detailed correlation data including:
  * Best correlation and associated delay.
  * Correlation values for each tested delay.
* HTML report (`report_html`) with scatter and delay charts.

***

## Request Parameters

The following parameters can be included in the request:

* **assets**: List of asset-attribute pairs for the analysis. Without an attribute specified, all attributes of the asset are analyzed.
* **lags**: Optional time delays, e.g., `{"hours": 10}`.
* **start\_time**, **end\_time**: Time period of the analysis.
* **to\_email**: (Optional) Email address for sending the report.

### Example Request

```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"
}
```

## Example Response for the API request `/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>"
}
```

### Explanation of the Response Fields

1. **assets**:
   * Contains the analyzed assets and their attributes, e.g., temperature and humidity.
2. **lags**:
   * List of tested time delays: 15 minutes, 2 hours, and 1 day.
3. **start\_time**, **end\_time**:
   * The time period of the analysis, here January 1 to January 3, 2025.
4. **correlation**:
   * Detailed correlation data:
     * **best\_correlation**: Highest correlation value (0.85).
     * **best\_lag**: The time delay (2 hours) at which the highest correlation occurs.
     * **lag\_details**: Correlation values for different delays (-2, 0, +2 hours).
5. **report\_html**:
   * An HTML report with visualizations such as heatmaps and scatter plots, ready to be displayed or saved directly.

***

## Report Generation

Reports contain the following visualizations:

#### HTML Report

Generated for the `/v1/correlate` and `/v1/correlate-children` endpoints:

* **Heatmaps**: Best correlations between attributes.
* **Correlation numbers**: Detailed statistics for each correlation.

Generated for the `/v1/in-depth-correlation` endpoint:

* **Scatter plots**: Relationships between attributes.
* **Delay charts**: Time-dependent trends.