Introduction
A correlation coefficient tells you the strength of a linear relationship, but it silently misses U-shapes, thresholds, and other nonlinear patterns that a scatter plot would reveal instantly. PlotCorrelationMatrix gives you both views: a printed numeric correlation matrix for a quick scan, or a full pairplot with scatter plots and optional LOWESS trend lines for every variable pair, optionally narrowed to just the relationships with a specific outcome column so a large predictor set stays readable.
Teaching Note
Correlation matrices and pairplots are essential for:
- Epidemiology: Examining the relationships between multiple environmental factors and disease incidence.
- Healthcare: Analyzing correlations between different patient vital signs and recovery outcomes.
- Data Science: Identifying multi-collinearity during feature selection and exploratory data analysis.
- Public Health: Correlating various socioeconomic indicators with regional life expectancy.
- Finance: Analyzing the price movements of multiple assets to assess portfolio diversification.
- Quality Control: Examining the relationship between different manufacturing sensor readings and defect counts.
- Social Science: Exploring the connections between multiple demographic variables and survey scores.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
dataframerequired | pd.DataFrame | — | The pandas DataFrame containing the numeric data to analyze. |
list_of_value_column_namesrequired | list of str | — | The names of the columns to be used on the x-axis of the pairplot (or the entire variable set if list_of_outcome_column_names is None). |
list_of_outcome_column_names | list of str | None | The names of the outcome columns to be used on the y-axis of the pairplot. If None, a symmetric grid is created using all value columns. Defaults to None. |
show_as_pairplot | bool | True | Whether to generate the visual pairplot. If False, the function prints the numeric correlation matrix to the console instead. Defaults to True. |
pairplot_size | tuple | (20, 20) | The dimensions of the entire figure grid in inches. Defaults to (20, 20). |
scatter_fill_color | str | '#3269a8' | The hex color code for the scatter plot points and diagonal distributions. Defaults to '#3269a8'. |
fit_lowess_line | bool | True | Whether to fit a Locally Weighted Scatterplot Smoothing (LOWESS) line to the scatter plots to show non-linear trends. Defaults to True. |
line_color | str | '#cc4b5a' | The hex color code for the regression or LOWESS line. Defaults to '#cc4b5a'. |
title_for_plot | str | 'Pairplot of Numeric Variables' | The primary title text displayed at the top of the figure. Defaults to 'Pairplot of Numeric Variables'. |
subtitle_for_plot | str | 'Shows the linear relationship between numeric variables' | Descriptive subtitle text displayed below the title. |
caption_for_plot | str | None | Explanatory text or notes displayed at the bottom of the plot. Defaults to None. |
data_source_for_plot | str | None | Text identifying the source of the data, appended to the caption. Defaults to None. |
x_indent | float | -0.7 | Horizontal offset for titles and captions relative to the axes. Defaults to -0.7. |
title_y_indent | float | 1.12 | Vertical offset for the title position relative to the grid. Defaults to 1.12. |
title_font_size | int | 14 | Font size for the primary title. Defaults to 14. |
subtitle_y_indent | float | 1.03 | Vertical offset for the subtitle position relative to the grid. Defaults to 1.03. |
subtitle_font_size | int | 11 | Font size for the subtitle. Defaults to 11. |
caption_y_indent | float | -0.35 | Vertical offset for the caption position relative to the grid. Defaults to -0.35. |
caption_font_size | int | 8 | Font size for the caption text. Defaults to 8. |
filepath_to_save_plot | str | None | The local path (ending in .png or .jpg) where the plot should be exported. If None, the file is not saved. Defaults to None. |
Returns
None — the function displays the plot using matplotlib (or prints a correlation matrix) and optionally saves the visual output to disk.
Example
python
from analysistoolbox.visualizations import PlotCorrelationMatrix
PlotCorrelationMatrix(
dataframe=df,
list_of_value_column_names=['age', 'income', 'credit_score', 'loan_amount'],
list_of_outcome_column_names=['default_risk'],
fit_lowess_line=True,
title_for_plot='Credit Risk Feature Relationships',
)