PlotScatterplot — Analysis Tool Box

Introduction

Whether population density predicts transmission rate, whether age correlates with symptom severity, whether two variables trade off in a way that suggests a 2×2 prioritization framework — these are all questions a scatterplot answers directly. PlotScatterplot renders two continuous variables against each other with optional color grouping, point sizing by a third variable, a fitted straight or LOWESS trend line, and — distinctively — labeled, colored quadrants for frameworks like impact-vs-effort or risk-vs-likelihood matrices.

Teaching Note

Scatterplots are essential for:

Epidemiology: Examining the relationship between population density and transmission rates.
Healthcare: Correlating patient age with physiological metrics like blood pressure or heart rate.
Intelligence Analysis: Analyzing the relationship between insurgent activity and local economic stability.
Data Science: Identifying patterns, clusters, and multi-collinearity during feature engineering.
Public Health: Correlating socioeconomic status indices with local life expectancy.
Finance: Visualizing the risk (standard deviation) vs. return of various asset classes.
Marketing: Examining the correlation between advertising spend and customer conversion volume.
Quality Control: Monitoring the relationship between manufacturing temperature and defect counts.

Parameters

Parameter	Type	Default	Description
`dataframe`required	`pd.DataFrame`	—	The pandas DataFrame containing the numeric and categorical data to plot.
`y_axis_column_name`required	`str`	—	The name of the column to be plotted on the vertical y-axis.
`x_axis_column_name`required	`str`	—	The name of the column to be plotted on the horizontal x-axis.
`grouping_column_name`	`str`	`None`	The name of a categorical column used for color-encoding (hue). Defaults to None.
`group_color_palette`	`str`	`'Set1'`	The name of the seaborn color palette to use for groupings. Defaults to 'Set1'.
`dot_fill_color`	`str`	`'#999999'`	The hex color code for points when no grouping is applied. Defaults to '#999999'.
`size_by_column_name`	`str`	`None`	The name of a numeric column used to scale the size of the scatter points. Defaults to None.
`size_normalization`	`tuple`	`None`	A (min, max) tuple defining the range of point sizes. Defaults to None.
`fitted_line_type`	`{None, 'straight', 'lowess'}`	`None`	The type of regression line to overlay on the plot. 'straight' fits a linear regression, while 'lowess' fits a smooth non-linear curve. Defaults to None.
`line_color`	`str`	`None`	The hex color code for the fitted regression line. If None, it matches the dot_fill_color. Defaults to None.
`title_for_plot`	`str`	`None`	The primary title text at the top of the chart. Defaults to None.
`subtitle_for_plot`	`str`	`None`	Descriptive subtitle text below the main title. Defaults to None.
`caption_for_plot`	`str`	`None`	Explanatory text or notes 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.128`	Horizontal offset for the titles and captions relative to the axes. Defaults to -0.128.
`title_y_indent`	`float`	`1.125`	Vertical offset for the title position relative to the grid. Defaults to 1.125.
`subtitle_y_indent`	`float`	`1.05`	Vertical offset for the subtitle position relative to the grid. Defaults to 1.05.
`caption_y_indent`	`float`	`-0.3`	Vertical offset for the caption position relative to the grid. Defaults to -0.3.
`upper_left_quadrant_label`	`str`	`None`	Text label to display in the upper-left quadrant area. Defaults to None.
`upper_left_quadrant_fill_color`	`str`	`None`	Hex color code for the upper-left quadrant background. Defaults to None.
`upper_right_quadrant_label`	`str`	`None`	Text label to display in the upper-right quadrant area. Defaults to None.
`upper_right_quadrant_fill_color`	`str`	`None`	Hex color code for the upper-right quadrant background. Defaults to None.
`lower_left_quadrant_label`	`str`	`None`	Text label to display in the lower-left quadrant area. Defaults to None.
`lower_left_quadrant_fill_color`	`str`	`None`	Hex color code for the lower-left quadrant background. Defaults to None.
`lower_right_quadrant_label`	`str`	`None`	Text label to display in the lower-right quadrant area. Defaults to None.
`lower_right_quadrant_fill_color`	`str`	`None`	Hex color code for the lower-right quadrant background. Defaults to None.
`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 scatterplot using matplotlib and optionally saves it to disk.

Example

python

from analysistoolbox.visualizations import PlotScatterplot

# Portfolio prioritization: impact vs. effort
PlotScatterplot(
    dataframe=initiatives_df,
    y_axis_column_name='expected_impact',
    x_axis_column_name='implementation_effort',
    upper_left_quadrant_label='Quick Wins',
    upper_right_quadrant_label='Major Projects',
    lower_left_quadrant_label='Fill-Ins',
    lower_right_quadrant_label='Thankless Tasks',
    title_for_plot='Initiative Prioritization Matrix',
)