Visualization Functions¶

Thin facade for the visualisation layer.

Implementation has been moved to the missingly.visualisation sub-package:

missingly.visualisation._base – shared helpers (_rtl_safe, _safe_labels, _nullity, _pct_labels)
missingly.visualisation.static – all matplotlib-based functions
missingly.visualisation.interactive – all Plotly backends and public wrappers (called when interactive=True)

This module re-exports every public name unchanged so that existing code continues to work without modification:

from missingly import visualise
visualise.heatmap(df)
# or
from missingly.visualise import heatmap
heatmap(df)

Visualization catalogue¶

Basic: matrix, bar, miss_case, miss_var_pct, vis_miss, miss_which
Pattern analysis: upset, miss_patterns, miss_cooccurrence
Correlation / clustering: heatmap, dendrogram, miss_cluster
Row / variable profiles: miss_row_profile, miss_impute_compare
Shadow / MAR detection: shadow_scatter
Factor / group breakdown: vis_miss_fct, vis_miss_by_group
Imputation diagnostics: vis_impute_dist
Miscellaneous: scatter_miss, vis_miss_cumsum_var, vis_miss_cumsum_case, vis_miss_span, vis_parallel_coords
Helper utilities (also accessible via this module): _rtl_safe, _safe_labels

missingly.visualise.matrix(df, *, figsize=None, color=(0.25, 0.25, 0.25), fontsize=12, labels=True, sparkline=True, freq=None, ax=None, backend='matplotlib', interactive=False, missing_values=None, **kwargs)[source]¶

Nullity matrix.

Return type:

matplotlib.axes.Axes or plotly Figure

Parameters:

df (DataFrame)
figsize (tuple[float, float] | None)
color (tuple[float, float, float])
fontsize (int)
labels (bool)
sparkline (bool)
freq (str | None)
ax (Any)
backend (str)
interactive (bool)
kwargs (Any)

missingly.visualise.bar(df, *, figsize=None, color='#4C72B0', log=False, labels=True, fontsize=12, sort=False, ax=None, backend='matplotlib', interactive=False, missing_values=None, **kwargs)[source]¶

Bar chart of per-column missing-value counts.

Return type:

matplotlib.axes.Axes or plotly Figure

Parameters:

df (DataFrame)
figsize (tuple[float, float] | None)
color (str)
log (bool)
labels (bool)
fontsize (int)
sort (bool)
ax (Any)
backend (str)
interactive (bool)
kwargs (Any)

missingly.visualise.miss_case(df, *, figsize=None, color='#4C72B0', fontsize=12, sort=True, ax=None, backend='matplotlib', interactive=False, missing_values=None, **kwargs)[source]¶

Bar chart of missing-value counts per row (case).

Return type:

matplotlib.axes.Axes or plotly Figure

Parameters:

df (DataFrame)
figsize (tuple[float, float] | None)
color (str)
fontsize (int)
sort (bool)
ax (Any)
backend (str)
interactive (bool)
kwargs (Any)

missingly.visualise.miss_var_pct(df, *, figsize=None, color='#4C72B0', fontsize=12, sort=True, ax=None, backend='matplotlib', interactive=False, missing_values=None, **kwargs)[source]¶

Horizontal bar chart of percentage missing per variable.

Return type:

matplotlib.axes.Axes or plotly Figure

Parameters:

df (DataFrame)
figsize (tuple[float, float] | None)
color (str)
fontsize (int)
sort (bool)
ax (Any)
backend (str)
interactive (bool)
kwargs (Any)

missingly.visualise.vis_miss(df, *, figsize=None, fontsize=12, sort=False, cluster=False, ax=None, backend='matplotlib', interactive=False, missing_values=None, **kwargs)[source]¶

Pixel-level heatmap of present / missing values (naniar-style).

Return type:

matplotlib.axes.Axes or plotly Figure

Parameters:

df (DataFrame)
figsize (tuple[float, float] | None)
fontsize (int)
sort (bool)
cluster (bool)
ax (Any)
backend (str)
interactive (bool)
kwargs (Any)

missingly.visualise.miss_which(df, *, figsize=None, fontsize=10, ax=None, missing_values=None, **kwargs)[source]¶

Heatmap showing which cells are missing (rows x columns).

Return type:

matplotlib.axes.Axes

Parameters:

df (DataFrame)
figsize (tuple[float, float] | None)
fontsize (int)
ax (Any)
kwargs (Any)

missingly.visualise.upset(df, *, figsize=None, min_subset_size=1, backend='matplotlib', interactive=False, missing_values=None, **kwargs)[source]¶

UpSet plot of missing-value co-occurrence patterns.

Parameters:

df (pandas.DataFrame) – Input data whose joint missingness patterns are plotted.
figsize (tuple of float, optional) – Matplotlib figure size. A readable default is selected when omitted.
min_subset_size (int, default 1) – Minimum number of rows required for an intersection to be displayed.
backend ({"matplotlib", "plotly"}, default "matplotlib") – Rendering backend. interactive=True also selects Plotly.
interactive (bool, default False) – Whether to return an interactive Plotly figure.
missing_values (optional) – Additional sentinel value or values treated as missing.
**kwargs (Any) – Backend-specific options. The native Matplotlib backend accepts show_pct; Plotly options are forwarded to its implementation.

Returns:

Matplotlib axes under intersections, matrix, and totals; or an interactive Plotly figure.

Return type:

dict or plotly.graph_objects.Figure

Raises:

ImportError – If Plotly is requested but not installed.
TypeError – If an unsupported Matplotlib keyword argument is supplied.

Examples

>>> import numpy as np
>>> import pandas as pd
>>> from missingly.visualisation.static import upset
>>> frame = pd.DataFrame({"a": [1.0, np.nan], "b": [np.nan, np.nan]})
>>> axes = upset(frame)
>>> sorted(axes)
['intersections', 'matrix', 'totals']

missingly.visualise.miss_patterns(df, *, top_n=10, figsize=None, color='#4C72B0', fontsize=11, ax=None, backend='matplotlib', interactive=False, missing_values=None, **kwargs)[source]¶

Bar chart of the most common missingness patterns.

Return type:

matplotlib.axes.Axes or plotly Figure

Parameters:

df (DataFrame)
top_n (int)
figsize (tuple[float, float] | None)
color (str)
fontsize (int)
ax (Any)
backend (str)
interactive (bool)
kwargs (Any)

missingly.visualise.miss_cooccurrence(df, *, normalize=True, figsize=None, cmap='Blues', fontsize=11, annot=True, fmt='.2f', ax=None, backend='matplotlib', interactive=False, missing_values=None, **kwargs)[source]¶

Co-occurrence heatmap of column missingness.

Return type:

matplotlib.axes.Axes or plotly Figure

Parameters:

df (DataFrame)
normalize (bool)
figsize (tuple[float, float] | None)
cmap (str)
fontsize (int)
annot (bool)
fmt (str)
ax (Any)
backend (str)
interactive (bool)
kwargs (Any)

missingly.visualise.heatmap(df, *, figsize=None, cmap='RdYlGn', fontsize=12, annot=True, fmt='.2f', vmin=-1.0, vmax=1.0, center=0.0, linewidths=0.5, ax=None, backend='matplotlib', interactive=False, mask_insignificant=True, significance=0.05, method='pearson', missing_values=None, **kwargs)[source]¶

Nullity correlation heatmap.

Return type:

matplotlib.axes.Axes or plotly Figure

Parameters:

df (DataFrame)
figsize (tuple[float, float] | None)
cmap (str)
fontsize (int)
annot (bool)
fmt (str)
vmin (float)
vmax (float)
center (float)
linewidths (float)
ax (Any)
backend (str)
interactive (bool)
mask_insignificant (bool)
significance (float)
method (str)
kwargs (Any)

missingly.visualise.dendrogram(df, *, figsize=(10, 4), fontsize=12, orientation='bottom', ax=None, missing_values=None, **kwargs)[source]¶

Hierarchical-clustering dendrogram of column nullity correlation.

Return type:

matplotlib.axes.Axes

Parameters:

df (DataFrame)
figsize (tuple[float, float])
fontsize (int)
orientation (str)
ax (Any)
kwargs (Any)

missingly.visualise.miss_cluster(df, *, figsize=None, cmap='gray_r', fontsize=10, ax=None, missing_values=None, **kwargs)[source]¶

Clustered heatmap of missing indicator matrix.

Return type:

matplotlib.axes.Axes

Parameters:

df (DataFrame)
figsize (tuple[float, float] | None)
cmap (str)
fontsize (int)
ax (Any)
kwargs (Any)

missingly.visualise.miss_row_profile(df, *, figsize=(8, 4), color='#4C72B0', fontsize=11, ax=None, missing_values=None, **kwargs)[source]¶

Histogram of per-row completeness fractions.

Return type:

matplotlib.axes.Axes

Parameters:

df (DataFrame)
figsize (tuple[float, float])
color (str)
fontsize (int)
ax (Any)
kwargs (Any)

missingly.visualise.shadow_scatter(df, x, y, *, shadow_col=None, hue=None, figsize=(7, 5), color_present='#4C72B0', color_missing='#dd8452', alpha=0.7, ax=None, missing_values=None, **kwargs)[source]¶

Scatter with margin rug for rows missing x or y.

Parameters:

shadow_col (str, optional) – Column to use for colouring shadow points (alias for hue).
df (DataFrame)
x (str)
y (str)
hue (str | None)
figsize (tuple[float, float])
color_present (str)
color_missing (str)
alpha (float)
ax (Any)
kwargs (Any)

Return type:

matplotlib.axes.Axes

missingly.visualise.vis_miss_fct(df, fct, *, figsize=None, fontsize=10, missing_values=None, **kwargs)[source]¶

Faceted vis_miss split by a categorical column.

Return type:

matplotlib.axes.Axes (last facet axes)

Parameters:

df (DataFrame)
fct (str)
figsize (tuple[float, float] | None)
fontsize (int)
kwargs (Any)

missingly.visualise.vis_miss_by_group(df, group_col, *, figsize=None, cmap='YlOrRd', fontsize=11, annot=True, fmt='.0f', ax=None, missing_values=None, **kwargs)[source]¶

Heatmap of % missing per column per group.

Parameters:

group_col (str) – Column to group by.
df (DataFrame)
figsize (tuple[float, float] | None)
cmap (str)
fontsize (int)
annot (bool)
fmt (str)
ax (Any)
kwargs (Any)

Return type:

matplotlib.axes.Axes

missingly.visualise.vis_impute_dist(df_before, df_after, column, *, figsize=(8, 4), bins=30, color_before='#4C72B0', color_after='#dd8452', fontsize=11, ax=None, missing_values=None, **kwargs)[source]¶

Overlay histograms comparing a column before and after imputation.

Parameters:

column (str) – Column to compare.
df_before (DataFrame)
df_after (DataFrame)
figsize (tuple[float, float])
bins (int)
color_before (str)
color_after (str)
fontsize (int)
ax (Any)
kwargs (Any)

Return type:

matplotlib.axes.Axes

missingly.visualise.miss_impute_compare(original, imputed, column=None, *, columns=None, figsize=None, bins=30, fontsize=11, missing_values=None, **kwargs)[source]¶

Grid of histograms comparing columns across multiple imputation results.

Parameters:

original (pd.DataFrame) – Data before imputation.
imputed (pd.DataFrame or dict[str, pd.DataFrame]) – Either a single imputed DataFrame or a mapping of label -> DataFrame.
column (str, optional) – Single column to compare. If None and imputed is a DataFrame, all numeric columns with missing values in original are compared.
columns (list of str, optional) – Explicit ordered subset of numeric columns to compare. This cannot be combined with column.
figsize (tuple[float, float] | None)
bins (int)
fontsize (int)
kwargs (Any)

Return type:

matplotlib.figure.Figure

missingly.visualise.scatter_miss(df, x, y, **kwargs)[source]¶

Alias for shadow_scatter().

Parameters:

df (DataFrame)
x (str)
y (str)
kwargs (Any)

Return type:

Any

missingly.visualise.vis_miss_cumsum_var(df, *, figsize=(8, 4), color='#4C72B0', fontsize=11, ax=None, missing_values=None, **kwargs)[source]¶

Line plot of cumulative % missing as variables are added.

Return type:

matplotlib.axes.Axes

Parameters:

df (DataFrame)
figsize (tuple[float, float])
color (str)
fontsize (int)
ax (Any)
kwargs (Any)

missingly.visualise.vis_miss_cumsum_case(df, *, figsize=(8, 4), color='#dd8452', fontsize=11, ax=None, missing_values=None, **kwargs)[source]¶

Line plot of cumulative % missing as rows are added.

Return type:

matplotlib.axes.Axes

Parameters:

df (DataFrame)
figsize (tuple[float, float])
color (str)
fontsize (int)
ax (Any)
kwargs (Any)

missingly.visualise.vis_miss_span(df, column, span_every=20, *, span=None, figsize=(10, 4), color='#4C72B0', fontsize=11, ax=None, missing_values=None, **kwargs)[source]¶

Rolling-window missing rate for a single column over the row index.

Parameters:

column (str) – Column name to analyse.
span_every (int) – Rolling window size (preferred parameter name).
span (int, optional) – Alias for span_every (kept for backwards compatibility).
df (DataFrame)
figsize (tuple[float, float])
color (str)
fontsize (int)
ax (Any)
kwargs (Any)

Return type:

matplotlib.axes.Axes

missingly.visualise.vis_parallel_coords(df, *, color_complete='#4C72B0', color_missing='#dd8452', alpha=0.3, figsize=None, fontsize=11, ax=None, missing_values=None, **kwargs)[source]¶

Parallel coordinates plot coloured by whether any value is missing.

Return type:

matplotlib.axes.Axes

Parameters:

df (DataFrame)
color_complete (str)
color_missing (str)
alpha (float)
figsize (tuple[float, float] | None)
fontsize (int)
ax (Any)
kwargs (Any)