View Objects

View objects are immutable dataclasses that represent plot-ready data.

Layer 1: Data and representations.

class plotsmith.objects.BandView(x, y_lower, y_upper, label=None, alpha=None)[source]

Bases: object

Immutable view of a confidence band or shaded region.

x: X-axis values (must align with y_lower and y_upper).

y_lower: Lower bound of the band.

y_upper: Upper bound of the band.

label: Optional label for the band (for legend).

alpha: Optional transparency (0.0 to 1.0).

Parameters:

x (ndarray)
y_lower (ndarray)
y_upper (ndarray)
label (str | None)
alpha (float | None)

__init__(x, y_lower, y_upper, label=None, alpha=None)

Parameters:

x (ndarray)
y_lower (ndarray)
y_upper (ndarray)
label (str | None)
alpha (float | None)

alpha: float | None = None

label: str | None = None

x: ndarray

y_lower: ndarray

y_upper: ndarray

class plotsmith.objects.BarView(x, height, label=None, color=None, edgecolor=None, alpha=None, horizontal=False)[source]

Bases: object

Immutable view of bar chart data.

x: X-axis positions (categories or positions).

height: Bar heights.

label: Optional label for the bars (for legend).

color: Optional fill color.

edgecolor: Optional edge color.

alpha: Optional transparency (0.0 to 1.0).

horizontal: If True, create horizontal bars.

Parameters:

x (ndarray | list[str])
height (ndarray)
label (str | None)
color (str | None)
edgecolor (str | None)
alpha (float | None)
horizontal (bool)

__init__(x, height, label=None, color=None, edgecolor=None, alpha=None, horizontal=False)

Parameters:

x (ndarray | list[str])
height (ndarray)
label (str | None)
color (str | None)
edgecolor (str | None)
alpha (float | None)
horizontal (bool)

alpha: float | None = None

color: str | None = None

edgecolor: str | None = None

height: ndarray

horizontal: bool = False

label: str | None = None

x: ndarray | list[str]

class plotsmith.objects.BoxView(data, labels=None, positions=None, colors=None, color=None, show_outliers=True, show_means=False)[source]

Bases: object

Immutable view of box plot data.

data: List of arrays, one per box (category).

labels: Optional labels for each box.

positions: Optional positions for boxes on x-axis.

colors: Optional list of colors for each box.

color: Optional single color for all boxes.

show_outliers: If True, show outliers (default True).

show_means: If True, show means (default False).

Parameters:

data (list[ndarray])
labels (list[str] | ndarray | None)
positions (ndarray | None)
colors (list[str] | ndarray | None)
color (str | None)
show_outliers (bool)
show_means (bool)

__init__(data, labels=None, positions=None, colors=None, color=None, show_outliers=True, show_means=False)

Parameters:

data (list[ndarray])
labels (list[str] | ndarray | None)
positions (ndarray | None)
colors (list[str] | ndarray | None)
color (str | None)
show_outliers (bool)
show_means (bool)

color: str | None = None

colors: list[str] | ndarray | None = None

data: list[ndarray]

labels: list[str] | ndarray | None = None

positions: ndarray | None = None

show_means: bool = False

show_outliers: bool = True

class plotsmith.objects.DumbbellView(categories, values1, values2, label1=None, label2=None, colors=None, color=None, orientation='h')[source]

Bases: object

Immutable view of dumbbell chart data.

categories: Category labels.

values1: First set of values (left/start points).

values2: Second set of values (right/end points).

label1: Optional label for first set.

label2: Optional label for second set.

colors: Optional list of colors for each category.

color: Optional single color for all dumbbells.

orientation: ‘h’ for horizontal (default) or ‘v’ for vertical.

Parameters:

categories (list[str] | ndarray)
values1 (ndarray)
values2 (ndarray)
label1 (str | None)
label2 (str | None)
colors (list[str] | ndarray | None)
color (str | None)
orientation (str)

__init__(categories, values1, values2, label1=None, label2=None, colors=None, color=None, orientation='h')

Parameters:

categories (list[str] | ndarray)
values1 (ndarray)
values2 (ndarray)
label1 (str | None)
label2 (str | None)
colors (list[str] | ndarray | None)
color (str | None)
orientation (str)

categories: list[str] | ndarray

color: str | None = None

colors: list[str] | ndarray | None = None

label1: str | None = None

label2: str | None = None

orientation: str = 'h'

values1: ndarray

values2: ndarray

class plotsmith.objects.FigureSpec(title=None, xlabel=None, ylabel=None, xlim=None, ylim=None)[source]

Bases: object

Immutable specification for figure and axes styling.

title: Optional figure/axes title.

xlabel: Optional X-axis label.

ylabel: Optional Y-axis label.

xlim: Optional tuple of (xmin, xmax).

ylim: Optional tuple of (ymin, ymax).

Parameters:

title (str | None)
xlabel (str | None)
ylabel (str | None)
xlim (tuple[float, float] | None)
ylim (tuple[float, float] | None)

__init__(title=None, xlabel=None, ylabel=None, xlim=None, ylim=None)

Parameters:

title (str | None)
xlabel (str | None)
ylabel (str | None)
xlim (tuple[float, float] | None)
ylim (tuple[float, float] | None)

title: str | None = None

xlabel: str | None = None

xlim: tuple[float, float] | None = None

ylabel: str | None = None

ylim: tuple[float, float] | None = None

class plotsmith.objects.HeatmapView(data, x_labels=None, y_labels=None, cmap=None, vmin=None, vmax=None, annotate=False, fmt=None)[source]

Bases: object

Immutable view of heatmap data.

data: 2D array of values to display as heatmap.

x_labels: Optional labels for x-axis (columns).

y_labels: Optional labels for y-axis (rows).

cmap: Optional colormap name.

vmin: Optional minimum value for color scale.

vmax: Optional maximum value for color scale.

annotate: If True, annotate cells with values.

fmt: Optional format string for annotations.

Parameters:

data (ndarray)
x_labels (list[str] | ndarray | None)
y_labels (list[str] | ndarray | None)
cmap (str | None)
vmin (float | None)
vmax (float | None)
annotate (bool)
fmt (str | None)

__init__(data, x_labels=None, y_labels=None, cmap=None, vmin=None, vmax=None, annotate=False, fmt=None)

Parameters:

data (ndarray)
x_labels (list[str] | ndarray | None)
y_labels (list[str] | ndarray | None)
cmap (str | None)
vmin (float | None)
vmax (float | None)
annotate (bool)
fmt (str | None)

annotate: bool = False

cmap: str | None = None

data: ndarray

fmt: str | None = None

vmax: float | None = None

vmin: float | None = None

x_labels: list[str] | ndarray | None = None

y_labels: list[str] | ndarray | None = None

class plotsmith.objects.HistogramView(values, bins=None, label=None, color=None, edgecolor=None, alpha=None)[source]

Bases: object

Immutable view of histogram data.

values: Array of values to histogram.

bins: Optional number of bins or bin edges.

label: Optional label for the histogram (for legend).

color: Optional fill color.

edgecolor: Optional edge color.

alpha: Optional transparency (0.0 to 1.0).

Parameters:

values (ndarray)
bins (int | ndarray | None)
label (str | None)
color (str | None)
edgecolor (str | None)
alpha (float | None)

__init__(values, bins=None, label=None, color=None, edgecolor=None, alpha=None)

Parameters:

values (ndarray)
bins (int | ndarray | None)
label (str | None)
color (str | None)
edgecolor (str | None)
alpha (float | None)

alpha: float | None = None

bins: int | ndarray | None = None

color: str | None = None

edgecolor: str | None = None

label: str | None = None

values: ndarray

class plotsmith.objects.LollipopView(categories, values, color=None, marker=None, linewidth=None, horizontal=False)[source]

Bases: object

Immutable view of lollipop chart data.

categories: Category labels.

values: Values for each category.

color: Optional color for the lollipops.

marker: Optional marker style for the lollipop heads.

linewidth: Optional line width.

horizontal: If True, create horizontal lollipops.

Parameters:

categories (list[str] | ndarray)
values (ndarray)
color (str | None)
marker (str | None)
linewidth (float | None)
horizontal (bool)

__init__(categories, values, color=None, marker=None, linewidth=None, horizontal=False)

Parameters:

categories (list[str] | ndarray)
values (ndarray)
color (str | None)
marker (str | None)
linewidth (float | None)
horizontal (bool)

categories: list[str] | ndarray

color: str | None = None

horizontal: bool = False

linewidth: float | None = None

marker: str | None = None

values: ndarray

class plotsmith.objects.MetricView(title, value, delta=None, prefix=None, suffix=None, value_color=None, delta_color=None)[source]

Bases: object

Immutable view of metric display data.

title: Title text.

value: Main value to display.

delta: Optional change value (positive or negative).

prefix: Optional prefix for value (e.g., ‘$’).

suffix: Optional suffix for value (e.g., ‘%’).

value_color: Optional color for the value.

delta_color: Optional color for the delta (defaults based on sign).

Parameters:

title (str)
value (float)
delta (float | None)
prefix (str | None)
suffix (str | None)
value_color (str | None)
delta_color (str | None)

__init__(title, value, delta=None, prefix=None, suffix=None, value_color=None, delta_color=None)

Parameters:

title (str)
value (float)
delta (float | None)
prefix (str | None)
suffix (str | None)
value_color (str | None)
delta_color (str | None)

delta: float | None = None

delta_color: str | None = None

prefix: str | None = None

suffix: str | None = None

title: str

value: float

value_color: str | None = None

class plotsmith.objects.RangeView(categories, values1, values2, label1=None, label2=None, color=None, orientation='h')[source]

Bases: object

Immutable view of range chart data (similar to dumbbell but different styling).

categories: Category labels.

values1: First set of values (left/start points).

values2: Second set of values (right/end points).

label1: Optional label for first set.

label2: Optional label for second set.

color: Optional color for the range.

orientation: ‘h’ for horizontal (default) or ‘v’ for vertical.

Parameters:

categories (list[str] | ndarray)
values1 (ndarray)
values2 (ndarray)
label1 (str | None)
label2 (str | None)
color (str | None)
orientation (str)

__init__(categories, values1, values2, label1=None, label2=None, color=None, orientation='h')

Parameters:

categories (list[str] | ndarray)
values1 (ndarray)
values2 (ndarray)
label1 (str | None)
label2 (str | None)
color (str | None)
orientation (str)

categories: list[str] | ndarray

color: str | None = None

label1: str | None = None

label2: str | None = None

orientation: str = 'h'

values1: ndarray

values2: ndarray

class plotsmith.objects.ScatterView(x, y, label=None, marker=None, alpha=None, s=None, c=None)[source]

Bases: object

Immutable view of scatter plot data.

x: X-axis values.

y: Y-axis values.

label: Optional label for the scatter (for legend).

marker: Optional marker style (e.g., ‘o’, ‘s’).

alpha: Optional transparency (0.0 to 1.0).

s: Optional marker size (single value or array).

c: Optional marker color (single value, array, or column name for mapping).

Parameters:

x (ndarray)
y (ndarray)
label (str | None)
marker (str | None)
alpha (float | None)
s (float | ndarray | None)
c (str | ndarray | None)

__init__(x, y, label=None, marker=None, alpha=None, s=None, c=None)

Parameters:

x (ndarray)
y (ndarray)
label (str | None)
marker (str | None)
alpha (float | None)
s (float | ndarray | None)
c (str | ndarray | None)

alpha: float | None = None

c: str | ndarray | None = None

label: str | None = None

marker: str | None = None

s: float | ndarray | None = None

x: ndarray

y: ndarray

class plotsmith.objects.SeriesView(x, y, label=None, marker=None, linewidth=None, alpha=None)[source]

Bases: object

Immutable view of a time series for plotting.

x: X-axis values (e.g., time indices or timestamps).

y: Y-axis values (the series data).

label: Optional label for the series (for legend).

marker: Optional marker style (e.g., ‘o’, ‘s’, ‘-‘).

linewidth: Optional line width.

alpha: Optional transparency (0.0 to 1.0).

Parameters:

x (ndarray)
y (ndarray)
label (str | None)
marker (str | None)
linewidth (float | None)
alpha (float | None)

__init__(x, y, label=None, marker=None, linewidth=None, alpha=None)

Parameters:

x (ndarray)
y (ndarray)
label (str | None)
marker (str | None)
linewidth (float | None)
alpha (float | None)

alpha: float | None = None

label: str | None = None

linewidth: float | None = None

marker: str | None = None

x: ndarray

y: ndarray

class plotsmith.objects.SlopeView(x, groups, colors=None)[source]

Bases: object

Immutable view of slope chart data.

x: X-axis values (typically two values for start and end).

groups: Dictionary mapping group names to y-values arrays.

colors: Optional dictionary mapping group names to colors.

Parameters:

x (ndarray)
groups (dict[str, ndarray])
colors (dict[str, str] | None)

__init__(x, groups, colors=None)

Parameters:

x (ndarray)
groups (dict[str, ndarray])
colors (dict[str, str] | None)

colors: dict[str, str] | None = None

groups: dict[str, ndarray]

x: ndarray

class plotsmith.objects.ViolinView(data, labels=None, positions=None, colors=None, color=None, show_means=False, show_medians=True)[source]

Bases: object

Immutable view of violin plot data.

data: List of arrays, one per violin (category).

labels: Optional labels for each violin.

positions: Optional positions for violins on x-axis.

colors: Optional list of colors for each violin.

color: Optional single color for all violins.

show_means: If True, show means (default False).

show_medians: If True, show medians (default True).

Parameters:

data (list[ndarray])
labels (list[str] | ndarray | None)
positions (ndarray | None)
colors (list[str] | ndarray | None)
color (str | None)
show_means (bool)
show_medians (bool)

__init__(data, labels=None, positions=None, colors=None, color=None, show_means=False, show_medians=True)

Parameters:

data (list[ndarray])
labels (list[str] | ndarray | None)
positions (ndarray | None)
colors (list[str] | ndarray | None)
color (str | None)
show_means (bool)
show_medians (bool)

color: str | None = None

colors: list[str] | ndarray | None = None

data: list[ndarray]

labels: list[str] | ndarray | None = None

positions: ndarray | None = None

show_means: bool = False

show_medians: bool = True

class plotsmith.objects.WaffleView(categories, values, colors=None, rows=None, columns=None)[source]

Bases: object

Immutable view of waffle chart data.

categories: Category labels.

values: Values for each category.

colors: Optional list of colors for each category.

rows: Optional number of rows in the grid.

columns: Optional number of columns in the grid.

Parameters:

categories (list[str] | ndarray)
values (ndarray)
colors (list[str] | ndarray | None)
rows (int | None)
columns (int | None)

__init__(categories, values, colors=None, rows=None, columns=None)

Parameters:

categories (list[str] | ndarray)
values (ndarray)
colors (list[str] | ndarray | None)
rows (int | None)
columns (int | None)

categories: list[str] | ndarray

colors: list[str] | ndarray | None = None

columns: int | None = None

rows: int | None = None

values: ndarray

class plotsmith.objects.WaterfallView(categories, values, measures=None, colors=None, color=None)[source]

Bases: object

Immutable view of waterfall chart data.

categories: Category labels for each bar.

values: Values for each category.

measures: Optional list of measure types (‘absolute’, ‘relative’, ‘total’).

colors: Optional list of colors for each bar.

color: Optional single color for all bars.

Parameters:

categories (list[str] | ndarray)
values (ndarray)
measures (list[str] | ndarray | None)
colors (list[str] | ndarray | None)
color (str | None)

__init__(categories, values, measures=None, colors=None, color=None)

Parameters:

categories (list[str] | ndarray)
values (ndarray)
measures (list[str] | ndarray | None)
colors (list[str] | ndarray | None)
color (str | None)

categories: list[str] | ndarray

color: str | None = None

colors: list[str] | ndarray | None = None

measures: list[str] | ndarray | None = None

values: ndarray