Workflows
Workflows are the main entry point for users. They provide high-level functions for creating plots.
Layer 4: Workflows providing public API entry points.
- plotsmith.workflows.figure(*, nrows=1, ncols=1, figsize=None, sharex=False, sharey=False, constrained_layout=True)[source]
Create a PlotSmith-styled figure.
This is a light wrapper around matplotlib.pyplot.subplots that chooses sensible defaults for analytical figures and returns the figure plus axes.
- Parameters:
nrows (
int) – Number of rows of subplots.ncols (
int) – Number of columns of subplots.figsize (
tuple[float,float] |None) – Figure size tuple (width, height).sharex (
bool) – If True, share x-axis across subplots.sharey (
bool) – If True, share y-axis across subplots.constrained_layout (
bool) – If True, use constrained layout.
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes or list of Axes).
- plotsmith.workflows.plot_backtest(results, y_true_col='y_true', y_pred_col='y_pred', fold_id_col='fold_id', title=None, xlabel=None, ylabel=None, save_path=None, figsize=(8, 8))[source]
Plot backtest results as scatter plot of predictions vs actuals.
- Parameters:
results (
DataFrame) – DataFrame with y_true, y_pred, and optionally fold_id columns.y_true_col (
str) – Name of the true values column.y_pred_col (
str) – Name of the predicted values column.fold_id_col (
str|None) – Optional name of the fold ID column for grouping.save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_bar(x, height, title=None, xlabel=None, ylabel=None, label=None, color=None, edgecolor=None, alpha=None, horizontal=False, force_zero=True, save_path=None, figsize=(10, 6))[source]
Plot a bar chart.
- Parameters:
x (
ndarray|list[str] |Series|Index) – X-axis positions (categories or positions).height (
ndarray|Series) – Bar heights.horizontal (
bool) – If True, create horizontal bars.force_zero (
bool) – If True, force y-axis to start at zero (honest scale).save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_box(data, x, y, title=None, xlabel=None, ylabel=None, colors=None, color=None, show_outliers=True, show_means=False, save_path=None, figsize=(10, 6))[source]
Plot a box plot.
- Parameters:
data (
DataFrame) – DataFrame with x (category) and y (value) columns.x (
str) – Name of the category column.y (
str) – Name of the value column.colors (
list[str] |None) – Optional list of colors for each box.show_outliers (
bool) – If True, show outliers (default True).show_means (
bool) – If True, show means (default False).save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_correlation(data, method='pearson', title=None, xlabel=None, ylabel=None, cmap=None, annotate=True, fmt=None, save_path=None, figsize=(10, 8))[source]
Plot a correlation heatmap.
- Parameters:
data (
DataFrame) – DataFrame to compute correlation matrix from.method (
str) – Correlation method (‘pearson’, ‘kendall’, ‘spearman’).cmap (
str|None) – Optional colormap name (defaults to ‘RdYlGn’).annotate (
bool) – If True, annotate cells with correlation values.save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_dumbbell(df, categories_col, values1_col, values2_col, label1=None, label2=None, colors=None, color=None, orientation='h', title=None, xlabel=None, ylabel=None, save_path=None, figsize=(10, 6))[source]
Plot a dumbbell chart.
- Parameters:
df (
DataFrame) – DataFrame with categories and two value columns.categories_col (
str) – Name of the categories column.values1_col (
str) – Name of the first values column.values2_col (
str) – Name of the second values column.colors (
list[str] |None) – Optional list of colors for each category.color (
str|None) – Optional single color for all dumbbells.orientation (
str) – ‘h’ for horizontal (default) or ‘v’ for vertical.save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_forecast_comparison(actual, forecasts, intervals=None, title=None, xlabel=None, ylabel=None, save_path=None, figsize=(12, 6))[source]
Plot forecast comparison with actual data and multiple forecasts.
- Parameters:
actual (
Series|ndarray) – Actual time series data.forecasts (
dict[str,Series|ndarray]) – Dictionary mapping forecast names to forecast arrays/Series.intervals (
dict[str,tuple[Series|ndarray,Series|ndarray]] |None) – Optional dictionary mapping forecast names to (lower, upper) interval tuples.save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_heatmap(data, title=None, xlabel=None, ylabel=None, cmap=None, vmin=None, vmax=None, annotate=False, fmt=None, save_path=None, figsize=(10, 8))[source]
Plot a heatmap (correlation matrix or 2D data).
- Parameters:
data (
ndarray|DataFrame) – 2D array or DataFrame to display as heatmap.vmin (
float|None) – Optional minimum value for color scale.vmax (
float|None) – Optional maximum value for color scale.annotate (
bool) – If True, annotate cells with values.save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_histogram(data, bins=None, labels=None, colors=None, title=None, xlabel=None, ylabel=None, label=None, color=None, edgecolor=None, alpha=None, save_path=None, figsize=(10, 6))[source]
Plot a histogram (supports single or multiple overlaid histograms).
- Parameters:
data (
ndarray|Series|list[ndarray|Series]) – Data to histogram (array-like, pandas Series, or list of arrays for overlaid).bins (
int|ndarray|None) – Optional number of bins or bin edges.labels (
list[str] |None) – Optional list of labels for multiple histograms.colors (
list[str] |None) – Optional list of colors for multiple histograms.label (
str|None) – Optional label for single histogram (deprecated if using labels).color (
str|None) – Optional fill color for single histogram (deprecated if using colors).save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_lollipop(df, categories_col, values_col, color=None, marker=None, linewidth=None, horizontal=False, title=None, xlabel=None, ylabel=None, save_path=None, figsize=(10, 6))[source]
Plot a lollipop chart.
- Parameters:
df (
DataFrame) – DataFrame with categories and values columns.categories_col (
str) – Name of the categories column.values_col (
str) – Name of the values column.marker (
str|None) – Optional marker style for the lollipop heads.horizontal (
bool) – If True, create horizontal lollipops.save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_metric(title, value, delta=None, prefix=None, suffix=None, value_color=None, delta_color=None, save_path=None, figsize=(6, 4))[source]
Plot a metric display.
- Parameters:
title (
str) – Title text.value (
float) – Main value to display.delta (
float|None) – Optional change value (positive or negative).prefix (
str|None) – Optional prefix for value (e.g., ‘$’).suffix (
str|None) – Optional suffix for value (e.g., ‘%’).delta_color (
str|None) – Optional color for the delta (defaults based on sign).save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_model_comparison(data, models, test_start_idx=None, title=None, xlabel=None, ylabel=None, save_path=None, figsize=(12, 6))[source]
Plot multiple model predictions compared to actual data.
- Parameters:
data (
Series|DataFrame) – Actual time series data as pandas Series or DataFrame.models (
dict[str,ndarray|Series]) – Dictionary mapping model names to their predictions (arrays/Series).test_start_idx (
int|None) – Optional index where test period starts (for visual separation).save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_range(df, categories_col, values1_col, values2_col, label1=None, label2=None, color=None, orientation='h', title=None, xlabel=None, ylabel=None, save_path=None, figsize=(10, 6))[source]
Plot a range chart (similar to dumbbell but different styling).
- Parameters:
df (
DataFrame) – DataFrame with categories and two value columns.categories_col (
str) – Name of the categories column.values1_col (
str) – Name of the first values column.values2_col (
str) – Name of the second values column.orientation (
str) – ‘h’ for horizontal (default) or ‘v’ for vertical.save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_residuals(actual, predicted, x=None, title=None, xlabel=None, ylabel=None, plot_type='scatter', add_perfect_line=True, save_path=None, figsize=(10, 6))[source]
Plot residuals (actual vs predicted or residuals over time).
- Parameters:
actual (
ndarray|Series) – Actual/true values.predicted (
ndarray|Series) – Predicted values.x (
ndarray|Series|None) – Optional x-axis values (for series plot). If None, uses index.plot_type (
str) – Type of plot - “scatter” for scatter plot, “series” for time series.add_perfect_line (
bool) – If True and plot_type is “scatter”, add diagonal perfect prediction line.save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_scatter(data, x, y, color=None, size=None, label=None, title=None, xlabel=None, ylabel=None, alpha=None, marker=None, save_path=None, figsize=(10, 6))[source]
Plot a scatter plot with optional color and size mappings.
- Parameters:
data (
DataFrame) – DataFrame with x and y columns, and optionally color/size columns.x (
str) – Name of the x column.y (
str) – Name of the y column.color (
str|None) – Optional name of column to use for color mapping.size (
str|None) – Optional name of column to use for size mapping.label (
str|None) – Optional label for the scatter (for legend).save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_slope(data_frame=None, x=None, y=None, group=None, df=None, categories_col=None, values_cols=None, title=None, xlabel=None, ylabel=None, colors=None, save_path=None, figsize=(10, 6))[source]
Plot a slope chart.
Can be called in two ways: 1. With long format: data_frame with x, y, and group columns 2. With wide format: df with categories_col and values_cols (list of column names)
- Parameters:
data_frame (
DataFrame|None) – DataFrame with x, y, and group columns (long format).x (
str|None) – Name of the x column (typically time periods) - for long format.y (
str|None) – Name of the y column (values) - for long format.group (
str|None) – Name of the group column (categories to track) - for long format.df (
DataFrame|None) – DataFrame with categories column and value columns (wide format).categories_col (
str|None) – Name of the categories column (for wide format).values_cols (
list[str] |None) – List of column names for values (for wide format).colors (
dict[str,str] |None) – Optional dictionary mapping group names to colors.save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_timeseries(data, bands=None, title=None, xlabel=None, ylabel=None, save_path=None, figsize=(10, 6))[source]
Plot a time series with optional confidence bands.
- Parameters:
data (
Series|DataFrame) – Time series data as pandas Series or DataFrame.bands (
dict[str,tuple[Series,Series]] |None) – Optional dict mapping band names to (lower, upper) Series tuples.save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_violin(data, x, y, title=None, xlabel=None, ylabel=None, colors=None, color=None, show_means=False, show_medians=True, save_path=None, figsize=(10, 6))[source]
Plot a violin plot.
- Parameters:
data (
DataFrame) – DataFrame with x (category) and y (value) columns.x (
str) – Name of the category column.y (
str) – Name of the value column.colors (
list[str] |None) – Optional list of colors for each violin.show_means (
bool) – If True, show means (default False).show_medians (
bool) – If True, show medians (default True).save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_waffle(df, category_col, value_col, colors=None, rows=None, columns=None, title=None, save_path=None, figsize=(10, 8))[source]
Plot a waffle chart.
- Parameters:
df (
DataFrame) – DataFrame with category and value columns.category_col (
str) – Name of the category column.value_col (
str) – Name of the value column.colors (
list[str] |None) – Optional list of colors for each category.columns (
int|None) – Optional number of columns in the grid.save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).
- plotsmith.workflows.plot_waterfall(df, categories_col, values_col, measure_col=None, colors=None, color=None, title=None, xlabel=None, ylabel=None, save_path=None, figsize=(10, 6))[source]
Plot a waterfall chart.
- Parameters:
df (
DataFrame) – DataFrame with categories and values columns.categories_col (
str) – Name of the categories column.values_col (
str) – Name of the values column.measure_col (
str|None) – Optional name of the measure type column (‘absolute’, ‘relative’, ‘total’).colors (
list[str] |None) – Optional list of colors for each bar.save_path (
str|Path|None) – Optional path to save the figure.figsize (
tuple[float,float]) – Figure size tuple (width, height).
- Return type:
- Returns:
Tuple of (matplotlib Figure, Axes).