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:

{
    "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

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

{
    "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

assets:
- Contains the analyzed assets and their attributes, e.g., temperature and humidity.
lags:
- List of tested time delays: 15 minutes, 2 hours, and 1 day.
start_time, end_time:
- The time period of the analysis, here January 1 to January 3, 2025.
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).
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.

PreviousCoffeeCloud NextDevice simulator

Last updated 3 months ago