🔬 analysis.correlation¶

Correlation analysis is a fundamental tool in data analysis, used to measure the strength and direction of relationships between variables. This module provides functionality to compute both the correlation matrix and lagged correlations for selected columns in a pandas DataFrame.

The CorrelationAnalyzer class offers a convenient interface for correlation analysis, supporting configurable lag values and precision, and is suitable for time series and general data exploration.

Overview¶

The module exposes:

A parameter dataclass for flexible configuration
An analyzer class that:
- Accepts a pandas DataFrame
- Computes the correlation matrix for selected features
- Computes lagged correlations for each feature up to a specified lag
- Supports configurable precision
- Returns structured output for downstream analysis or visualization

Class Reference¶

class owlmix.analysis.correlation.CorrelationParams(columns=None, n_lags=10, precision=4)¶

Dataclass for specifying correlation analysis parameters.

Parameters:

columns (Optional[List[str]]) – List of column names to include in the analysis. If None, all numeric columns are used.
n_lags (int) – Number of lag values to compute for lagged correlation.
precision (int) – Number of decimal places to round correlation values.

class owlmix.analysis.correlation.CorrelationAnalyzer(df, params)¶

Computes the correlation matrix and lagged correlations for specified features in a pandas DataFrame.

Parameters:

df (pandas.DataFrame) – Input DataFrame containing the data.
params (CorrelationParams) – Configuration parameters for correlation analysis.

compute()¶

Computes both the correlation matrix and lagged correlations.

Returns:: A dictionary with keys: - correlation_matrix: Nested dictionary representing the correlation matrix. - lagged_correlation_matrix: Dictionary mapping each column to its lagged correlations.
Return type:: dict[str, dict]

compute_correlation_matrix()¶

Computes the correlation matrix for the selected columns.

Returns:: Nested dictionary representing the correlation matrix.
Return type:: dict[str, dict[str, float]]

compute_lag_correlation()¶

Computes the correlation between a lagged version of a column and the original column for specified lags.

Returns:: Dictionary mapping each column to its lagged correlations.
Return type:: dict[str, dict[int, float]]

print_results_json(results=None, indent=2)¶

Prints the results in JSON format.

Parameters:

results (Optional[dict]) – The results to print. If None, uses the computed results.
indent (int) – Indentation level for pretty-printing the JSON.

print_results(results=None)¶

Prints the results in a human-readable tabular format.

Parameters:: results (Optional[dict]) – The results to print. If None, uses the computed results.

Usage Example¶

Below is a simple example of how to use the analyzer:

import pandas as pd
from owlmix.analysis.correlation import CorrelationAnalyzer, CorrelationParams

df = pd.DataFrame({
    "a": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
    "b": [2, 3, 2, 5, 7, 8, 6, 5, 4, 3],
    "c": [5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
})

params = CorrelationParams(
    columns=["a", "b", "c"],
    n_lags=2,
    precision=2
)
analyzer = CorrelationAnalyzer(df=df, params=params)
result = analyzer.compute()
analyzer.print_results_json(result)
analyzer.print_results(result)

Result Example

Result Output - analyzer.print_results_json(result)

{
    "correlation_matrix": {
        "a": {
            "a": 1.0,
            "b": 0.31,
            "c": 1.0
        },
        "b": {
            "a": 0.31,
            "b": 1.0,
            "c": 0.31
        },
        "c": {
            "a": 1.0,
            "b": 0.31,
            "c": 1.0
        }
    },
    "lagged_correlation_matrix": {
        "a": {
            "0": 1.0,
            "1": 1.0,
            "2": 1.0
        },
        "b": {
            "0": 1.0,
            "1": 0.66,
            "2": 0.13
        },
        "c": {
            "0": 1.0,
            "1": 1.0,
            "2": 1.0
        }
    }
}

Result Output - analyzer.print_results(result)

Correlation Matrix:
    a     b     c
--  ----  ----  ----
a   1.00  0.31  1.00
b   0.31  1.00  0.31
c   1.00  0.31  1.00

Lagged Correlation Matrix:
Column      Lag 0    Lag 1    Lag 2
--------  -------  -------  -------
a            1.00     1.00     1.00
b            1.00     0.66     0.13
c            1.00     1.00     1.00

Notes¶

Only numeric columns are processed; non-numeric columns are ignored.
Missing values are automatically handled by pandas correlation methods.
If fewer than two columns are provided, correlation is not defined and NaN is returned.
Lagged correlation is computed for each column up to the specified number of lags.

Dependencies¶

pandas
numpy
tabulate

🔬 analysis.correlation¶

Overview¶

Class Reference¶

Usage Example¶

Notes¶

Dependencies¶

References¶

See Also¶