Charts Module
Module containing the charts.
The charts module contains the methods to create the plots and figures,
grouped by the question they answer.
| FUNCTION | DESCRIPTION |
|---|---|
LineChart |
Creates the line chart. |
StackedAreaChart |
Creates the stacked area chart. |
BarChart |
Creates the bar chart. |
PyramidChart |
Creates the pyramid chart. |
RadialChart |
Creates the radial chart. |
Histogram |
Creates the histogram. |
BoxPlot |
Creates the box plot. |
ViolinPlot |
Creates the violin plot. |
SwarmPlot |
Creates the swarm plot. |
RaincloudPlot |
Creates the raincloud plot. |
ScatterChart |
Creates the scatter chart. |
Heatmap |
Creates the heatmap. |
ContourChart |
Creates the contour chart. |
HexbinChart |
Creates the hexbin chart. |
ParallelCoords |
Creates the parallel coordinates chart. |
SankeyChart |
Creates the Sankey chart. |
Trends and Comparisons
LineChart(
data: Union[
List[LineDataPointAttrs],
List[List[LineDataPointAttrs]],
],
*,
title: Optional[str] = None,
xlabel: Optional[str] = None,
ylabel: Optional[str] = None,
subtitle: Optional[
Union[str, List[Optional[str]]]
] = None,
emphasis: Optional[
Union[EMPHASIS, str, List[Optional[str]]]
] = None,
figsize: Optional[
Union[FIG_SIZE, Tuple[float, float]]
] = None,
xmin: Optional[Union[int, float]] = None,
xmax: Optional[Union[int, float]] = None,
ymin: Optional[Union[int, float]] = None,
ymax: Optional[Union[int, float]] = None,
show_legend: Optional[bool] = None,
show_grid: Optional[Union[SHOW_GRID, str]] = None,
show_yerr: Optional[bool] = None,
show_area: Optional[bool] = None,
aspect_ratio: Optional[Union[ASPECT_RATIO, str]] = None,
scalex: Optional[Union[SCALE, str]] = None,
scaley: Optional[Union[SCALE, str]] = None,
subplots: Optional[bool] = None,
max_cols: Optional[int] = None,
sharex: Optional[bool] = None,
sharey: Optional[bool] = None,
style: Optional[
Union[
LineStyleAttrs, List[Optional[LineStyleAttrs]]
]
] = None,
xticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
xticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
xtickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
yticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
yticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
ytickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
vlines: Optional[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
List[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
None,
]
],
]
] = None,
hlines: Optional[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
List[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
None,
]
],
]
] = None,
texts: Optional[
Union[
TextAttrs,
List[TextAttrs],
List[Union[TextAttrs, List[TextAttrs], None]],
]
] = None,
x: Optional[Union[str, List[Optional[str]]]] = None,
y: Optional[Union[str, List[Optional[str]]]] = None,
yerr: Optional[Union[str, List[Optional[str]]]] = None
) -> plt.Figure
Creates the line chart.
Lines connect ordered (x, y) points to show how a value changes along a continuous
axis, typically time. Use it for trends, growth, and comparing the trajectories of
several series on the same scale. For unordered categories use
BarChart; for unconnected samples use
ScatterChart.
Examples:
>>> from datachart.charts import LineChart
>>> figure = LineChart(
... data=[
... {"x": 1, "y": 5},
... {"x": 2, "y": 10},
... {"x": 3, "y": 15},
... {"x": 4, "y": 20},
... {"x": 5, "y": 25}
... ],
... title="Basic Line Chart",
... xlabel="X",
... ylabel="Y"
... )
| PARAMETER | DESCRIPTION |
|---|---|
data
|
The data points for the line chart(s). Can be a single list of data points for one chart, or a list of lists for multiple charts/subplots.
TYPE:
|
title
|
The title of the chart.
TYPE:
|
xlabel
|
The x-axis label.
TYPE:
|
ylabel
|
The y-axis label.
TYPE:
|
subtitle
|
The subtitle(s) for individual charts. Used as legend labels.
TYPE:
|
emphasis
|
The emphasis role(s) for individual charts, aligned like
TYPE:
|
figsize
|
The size of the figure.
TYPE:
|
xmin
|
The minimum x-axis value.
TYPE:
|
xmax
|
The maximum x-axis value.
TYPE:
|
ymin
|
The minimum y-axis value.
TYPE:
|
ymax
|
The maximum y-axis value.
TYPE:
|
show_legend
|
Whether to show the legend.
TYPE:
|
show_grid
|
Which grid lines to show (e.g., "both", "x", "y").
TYPE:
|
show_yerr
|
Whether to show y-axis error bars.
TYPE:
|
show_area
|
Whether to show the area under the line.
TYPE:
|
aspect_ratio
|
The aspect ratio of the axes ("auto" or "equal"). See
TYPE:
|
scalex
|
The x-axis scale (e.g., "log", "linear").
TYPE:
|
scaley
|
The y-axis scale (e.g., "log", "linear").
TYPE:
|
subplots
|
Whether to create separate subplots for each chart.
TYPE:
|
max_cols
|
Maximum number of columns in subplots (when subplots=True).
TYPE:
|
sharex
|
Whether to share the x-axis in subplots.
TYPE:
|
sharey
|
Whether to share the y-axis in subplots.
TYPE:
|
style
|
Style configuration(s) for the line(s).
TYPE:
|
xticks
|
Custom x-axis tick positions.
TYPE:
|
xticklabels
|
Custom x-axis tick labels.
TYPE:
|
xtickrotate
|
Rotation angle for x-axis tick labels.
TYPE:
|
yticks
|
Custom y-axis tick positions.
TYPE:
|
yticklabels
|
Custom y-axis tick labels.
TYPE:
|
ytickrotate
|
Rotation angle for y-axis tick labels.
TYPE:
|
vlines
|
Vertical line(s) to plot.
TYPE:
|
hlines
|
Horizontal line(s) to plot.
TYPE:
|
texts
|
Text annotation(s) to draw.
TYPE:
|
x
|
The key name in data for x-axis values (default: "x").
TYPE:
|
y
|
The key name in data for y-axis values (default: "y").
TYPE:
|
yerr
|
The key name in data for y-axis error values (default: "yerr").
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
plt.Figure
|
The figure containing the line chart. |
StackedAreaChart(
data: Union[
List[LineDataPointAttrs],
List[List[LineDataPointAttrs]],
],
*,
baseline: Optional[Union[BASELINE, str]] = None,
title: Optional[str] = None,
xlabel: Optional[str] = None,
ylabel: Optional[str] = None,
subtitle: Optional[
Union[str, List[Optional[str]]]
] = None,
emphasis: Optional[
Union[EMPHASIS, str, List[Optional[str]]]
] = None,
figsize: Optional[
Union[FIG_SIZE, Tuple[float, float]]
] = None,
xmin: Optional[Union[int, float]] = None,
xmax: Optional[Union[int, float]] = None,
ymin: Optional[Union[int, float]] = None,
ymax: Optional[Union[int, float]] = None,
show_legend: Optional[bool] = None,
show_grid: Optional[Union[SHOW_GRID, str]] = None,
aspect_ratio: Optional[Union[ASPECT_RATIO, str]] = None,
scalex: Optional[Union[SCALE, str]] = None,
scaley: Optional[Union[SCALE, str]] = None,
subplots: Optional[bool] = None,
max_cols: Optional[int] = None,
sharex: Optional[bool] = None,
sharey: Optional[bool] = None,
style: Optional[
Union[
StackedAreaStyleAttrs,
List[Optional[StackedAreaStyleAttrs]],
]
] = None,
xticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
xticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
xtickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
yticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
yticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
ytickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
vlines: Optional[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
List[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
None,
]
],
]
] = None,
hlines: Optional[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
List[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
None,
]
],
]
] = None,
texts: Optional[
Union[
TextAttrs,
List[TextAttrs],
List[Union[TextAttrs, List[TextAttrs], None]],
]
] = None,
x: Optional[Union[str, List[Optional[str]]]] = None,
y: Optional[Union[str, List[Optional[str]]]] = None
) -> plt.Figure
Creates the stacked area chart.
Stacked areas fill each series on top of the previous one along an ordered
axis, so the top edge traces the total and the bands show how it splits into
parts — class proportions over time, traffic by channel per year. Every
series must share the same x values. Use it for composition that changes
along an axis; for the trajectories themselves use
LineChart, and for composition at a few
discrete categories use BarChart with
bar_mode="stack".
Added in 0.9.0
Examples:
>>> from datachart.charts import StackedAreaChart
>>> figure = StackedAreaChart(
... data=[
... [{"x": 1, "y": 3}, {"x": 2, "y": 4}, {"x": 3, "y": 5}],
... [{"x": 1, "y": 2}, {"x": 2, "y": 3}, {"x": 3, "y": 1}],
... ],
... subtitle=["Mobile", "Desktop"],
... title="Traffic by Device",
... xlabel="Year",
... ylabel="Visits",
... )
| PARAMETER | DESCRIPTION |
|---|---|
data
|
The data points for the stacked series. A single list of points
draws one band; a list of lists draws one band per series, the
first at the bottom. Every series must hold the same
TYPE:
|
baseline
|
Where the first series starts: "zero" (default), "percent"
(each
TYPE:
|
title
|
The title of the chart.
TYPE:
|
xlabel
|
The x-axis label.
TYPE:
|
ylabel
|
The y-axis label.
TYPE:
|
subtitle
|
The subtitle(s) for individual series. Used as legend labels.
TYPE:
|
emphasis
|
The emphasis role(s) for individual series, aligned like
TYPE:
|
figsize
|
The size of the figure.
TYPE:
|
xmin
|
The minimum x-axis value.
TYPE:
|
xmax
|
The maximum x-axis value.
TYPE:
|
ymin
|
The minimum y-axis value.
TYPE:
|
ymax
|
The maximum y-axis value.
TYPE:
|
show_legend
|
Whether to show the legend.
TYPE:
|
show_grid
|
Which grid lines to show (e.g., "both", "x", "y").
TYPE:
|
aspect_ratio
|
The aspect ratio of the axes ("auto" or "equal"). See
TYPE:
|
scalex
|
The x-axis scale (e.g., "log", "linear").
TYPE:
|
scaley
|
The y-axis scale (e.g., "log", "linear").
TYPE:
|
subplots
|
Whether to draw each series unstacked in its own subplot.
TYPE:
|
max_cols
|
Maximum number of columns in subplots (when subplots=True).
TYPE:
|
sharex
|
Whether to share the x-axis in subplots.
TYPE:
|
sharey
|
Whether to share the y-axis in subplots.
TYPE:
|
style
|
Style configuration(s) for the band(s).
TYPE:
|
xticks
|
Custom x-axis tick positions.
TYPE:
|
xticklabels
|
Custom x-axis tick labels.
TYPE:
|
xtickrotate
|
Rotation angle for x-axis tick labels.
TYPE:
|
yticks
|
Custom y-axis tick positions.
TYPE:
|
yticklabels
|
Custom y-axis tick labels.
TYPE:
|
ytickrotate
|
Rotation angle for y-axis tick labels.
TYPE:
|
vlines
|
Vertical line(s) to plot.
TYPE:
|
hlines
|
Horizontal line(s) to plot.
TYPE:
|
texts
|
Text annotation(s) to draw.
TYPE:
|
x
|
The key name in data for x-axis values (default: "x").
TYPE:
|
y
|
The key name in data for y-axis values (default: "y").
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
plt.Figure
|
The figure containing the stacked area chart. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If the series do not share the same |
BarChart(
data: Union[
List[BarDataPointAttrs],
List[List[BarDataPointAttrs]],
],
*,
title: Optional[str] = None,
xlabel: Optional[str] = None,
ylabel: Optional[str] = None,
subtitle: Optional[
Union[str, List[Optional[str]]]
] = None,
emphasis: Optional[
Union[EMPHASIS, str, List[Optional[str]]]
] = None,
figsize: Optional[
Union[FIG_SIZE, Tuple[float, float]]
] = None,
xmin: Optional[Union[int, float]] = None,
xmax: Optional[Union[int, float]] = None,
ymin: Optional[Union[int, float]] = None,
ymax: Optional[Union[int, float]] = None,
show_legend: Optional[bool] = None,
show_grid: Optional[Union[SHOW_GRID, str]] = None,
show_yerr: Optional[bool] = None,
show_values: Optional[bool] = None,
value_format: Optional[Union[VALUE_FORMAT, str]] = None,
aspect_ratio: Optional[Union[ASPECT_RATIO, str]] = None,
orientation: Optional[
Union[ORIENTATION, str]
] = ORIENTATION.VERTICAL,
bar_mode: Optional[Union[BAR_MODE, str]] = None,
scalex: Optional[Union[SCALE, str]] = None,
scaley: Optional[Union[SCALE, str]] = None,
subplots: Optional[bool] = None,
max_cols: Optional[int] = None,
sharex: Optional[bool] = None,
sharey: Optional[bool] = None,
style: Optional[
Union[BarStyleAttrs, List[Optional[BarStyleAttrs]]]
] = None,
xticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
xticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
xtickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
yticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
yticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
ytickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
vlines: Optional[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
List[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
None,
]
],
]
] = None,
hlines: Optional[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
List[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
None,
]
],
]
] = None,
texts: Optional[
Union[
TextAttrs,
List[TextAttrs],
List[Union[TextAttrs, List[TextAttrs], None]],
]
] = None,
label: Optional[Union[str, List[Optional[str]]]] = None,
y: Optional[Union[str, List[Optional[str]]]] = None,
yerr: Optional[Union[str, List[Optional[str]]]] = None
) -> plt.Figure
Creates the bar chart.
Bars compare a numeric value across discrete categories: each label gets a bar whose
length encodes its value. Use it when the categories are few and unordered (or
ordinal) and the question is "which is bigger, and by how much"; several series can
be grouped, stacked, or overlaid via bar_mode. For a continuous x-axis reach for
LineChart, for distributions for
Histogram.
Examples:
>>> from datachart.charts import BarChart
>>> figure = BarChart(
... data=[
... {"label": "cat1", "y": 5},
... {"label": "cat2", "y": 10},
... {"label": "cat3", "y": 15},
... {"label": "cat4", "y": 20},
... {"label": "cat5", "y": 25}
... ],
... title="Basic Bar Chart",
... xlabel="LABEL",
... ylabel="Y"
... )
| PARAMETER | DESCRIPTION |
|---|---|
data
|
The data points for the bar chart(s). Can be a single list of data points for one chart, or a list of lists for multiple charts/subplots.
TYPE:
|
title
|
The title of the chart.
TYPE:
|
xlabel
|
The x-axis label.
TYPE:
|
ylabel
|
The y-axis label.
TYPE:
|
subtitle
|
The subtitle(s) for individual charts. Used as legend labels.
TYPE:
|
emphasis
|
The emphasis role(s) for individual charts, aligned like
TYPE:
|
figsize
|
The size of the figure as (width, height) in inches. See
TYPE:
|
xmin
|
The minimum x-axis value.
TYPE:
|
xmax
|
The maximum x-axis value.
TYPE:
|
ymin
|
The minimum y-axis value.
TYPE:
|
ymax
|
The maximum y-axis value.
TYPE:
|
show_legend
|
Whether to show the legend.
TYPE:
|
show_grid
|
Which grid lines to show ("both", "x", "y"). See
TYPE:
|
show_yerr
|
Whether to show y-axis error bars.
TYPE:
|
show_values
|
Whether to show bar value labels at the edge of each bar.
TYPE:
|
value_format
|
Format string for bar value labels: a
TYPE:
|
aspect_ratio
|
The aspect ratio of the axes ("auto" or "equal"). See
TYPE:
|
bar_mode
|
How multiple bar series share the axis: "group" (side-by-side),
"stack" (stacked), or "overlay" (overlapping). See
TYPE:
|
orientation
|
The orientation of the bars ("vertical" or "horizontal").
See
TYPE:
|
scalex
|
The x-axis scale ("linear", "log", "symlog", "asinh"). Useful
for horizontal bars. See
TYPE:
|
scaley
|
The y-axis scale ("linear", "log", "symlog", "asinh"). Useful
for vertical bars. See
TYPE:
|
subplots
|
Whether to create separate subplots for each chart.
TYPE:
|
max_cols
|
Maximum number of columns in subplots (when subplots=True).
TYPE:
|
sharex
|
Whether to share the x-axis in subplots.
TYPE:
|
sharey
|
Whether to share the y-axis in subplots.
TYPE:
|
style
|
Style configuration(s) for the bar(s).
TYPE:
|
xticks
|
Custom x-axis tick positions.
TYPE:
|
xticklabels
|
Custom x-axis tick labels.
TYPE:
|
xtickrotate
|
Rotation angle for x-axis tick labels.
TYPE:
|
yticks
|
Custom y-axis tick positions.
TYPE:
|
yticklabels
|
Custom y-axis tick labels.
TYPE:
|
ytickrotate
|
Rotation angle for y-axis tick labels.
TYPE:
|
vlines
|
Vertical line(s) to plot.
TYPE:
|
hlines
|
Horizontal line(s) to plot.
TYPE:
|
texts
|
Text annotation(s) to draw.
TYPE:
|
label
|
The key name in data for label values (default: "label").
TYPE:
|
y
|
The key name in data for y-axis values (default: "y").
TYPE:
|
yerr
|
The key name in data for y-axis error values (default: "yerr").
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
plt.Figure
|
The figure containing the bar chart. |
PyramidChart(
data: List[List[BarDataPointAttrs]],
*,
title: Optional[str] = None,
xlabel: Optional[str] = None,
ylabel: Optional[str] = None,
subtitle: Optional[
Union[str, List[Optional[str]]]
] = None,
figsize: Optional[
Union[FIG_SIZE, Tuple[float, float]]
] = None,
xmin: Optional[Union[int, float]] = None,
xmax: Optional[Union[int, float]] = None,
show_legend: Optional[bool] = None,
show_grid: Optional[Union[SHOW_GRID, str]] = None,
show_yerr: Optional[bool] = None,
show_values: Optional[bool] = None,
value_format: Optional[Union[VALUE_FORMAT, str]] = None,
style: Optional[
Union[BarStyleAttrs, List[Optional[BarStyleAttrs]]]
] = None,
xticks: Optional[List[Union[int, float]]] = None,
xticklabels: Optional[List[str]] = None,
xtickrotate: Optional[int] = None,
yticks: Optional[List[Union[int, float]]] = None,
yticklabels: Optional[List[str]] = None,
ytickrotate: Optional[int] = None,
vlines: Optional[
Union[VLinePlotAttrs, List[VLinePlotAttrs]]
] = None,
hlines: Optional[
Union[HLinePlotAttrs, List[HLinePlotAttrs]]
] = None,
texts: Optional[
Union[TextAttrs, List[TextAttrs]]
] = None,
label: Optional[Union[str, List[Optional[str]]]] = None,
y: Optional[Union[str, List[Optional[str]]]] = None,
yerr: Optional[Union[str, List[Optional[str]]]] = None
) -> plt.Figure
Creates the pyramid chart.
A pyramid chart draws exactly two series as horizontal bars mirrored around a shared category axis, the first series to the left and the second to the right: the classic age-sex population pyramid. Use it to compare the distribution of two groups over the same ordered categories, such as age bands, where the symmetry (or lack of it) is the message.
Both series are supplied as positive values; value ticks and labels show
absolute values. Unlike the other chart fronts, the axis parameters are
spatial: xlabel, xticks, and xmax address the horizontal value axis,
and ylabel the vertical category axis.
Added in v0.8.0
Examples:
>>> from datachart.charts import PyramidChart
>>> figure = PyramidChart(
... data=[
... [
... {"label": "0-14", "y": 12},
... {"label": "15-29", "y": 18},
... {"label": "30-44", "y": 22},
... ],
... [
... {"label": "0-14", "y": 11},
... {"label": "15-29", "y": 19},
... {"label": "30-44", "y": 24},
... ],
... ],
... subtitle=["Group A", "Group B"],
... title="Basic Pyramid Chart",
... show_legend=True,
... )
| PARAMETER | DESCRIPTION |
|---|---|
data
|
Exactly two lists of data points — the first is the left side, the second the right. Values are positive for both sides; the chart mirrors the left side itself.
TYPE:
|
title
|
The title of the chart.
TYPE:
|
xlabel
|
The label of the horizontal value axis.
TYPE:
|
ylabel
|
The label of the vertical category axis.
TYPE:
|
subtitle
|
The names of the two sides. Used as legend labels.
TYPE:
|
figsize
|
The size of the figure as (width, height) in inches. See
TYPE:
|
xmin
|
Not supported; the value axis is always symmetric around zero. Raises when passed.
TYPE:
|
xmax
|
The maximum per-side value; the value axis spans (-xmax, xmax).
TYPE:
|
show_legend
|
Whether to show the legend.
TYPE:
|
show_grid
|
Which grid lines to show ("both", "x", "y"). See
TYPE:
|
show_yerr
|
Whether to show error bars on the bars.
TYPE:
|
show_values
|
Whether to show bar value labels at the edge of each bar.
TYPE:
|
value_format
|
Format string for bar value labels: a
TYPE:
|
style
|
Style configuration(s) for the bars, per side.
TYPE:
|
xticks
|
Custom value-axis tick positions, as positive values; each is mirrored to both halves.
TYPE:
|
xticklabels
|
Custom value-axis tick labels (same length as
TYPE:
|
xtickrotate
|
Rotation angle for value-axis tick labels.
TYPE:
|
yticks
|
Custom category-axis tick positions.
TYPE:
|
yticklabels
|
Custom category-axis tick labels.
TYPE:
|
ytickrotate
|
Rotation angle for category-axis tick labels.
TYPE:
|
vlines
|
Vertical line(s) to plot.
TYPE:
|
hlines
|
Horizontal line(s) to plot.
TYPE:
|
texts
|
Text annotation(s) to draw.
TYPE:
|
label
|
The key name in data for label values (default: "label").
TYPE:
|
y
|
The key name in data for the bar values (default: "y").
TYPE:
|
yerr
|
The key name in data for the bar error values (default: "yerr").
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
plt.Figure
|
The figure containing the pyramid chart. |
RadialChart(
data: Union[
List[RadialDataPointAttrs],
List[List[RadialDataPointAttrs]],
],
*,
type: Optional[Union[RADIAL_TYPE, str]] = None,
title: Optional[str] = None,
xlabel: Optional[str] = None,
ylabel: Optional[str] = None,
subtitle: Optional[
Union[str, List[Optional[str]]]
] = None,
emphasis: Optional[
Union[EMPHASIS, str, List[Optional[str]]]
] = None,
figsize: Optional[
Union[FIG_SIZE, Tuple[float, float]]
] = None,
ymin: Optional[Union[int, float]] = None,
ymax: Optional[Union[int, float]] = None,
show_legend: Optional[bool] = None,
show_grid: Optional[Union[SHOW_GRID, str]] = None,
show_yerr: Optional[bool] = None,
show_area: Optional[bool] = None,
show_values: Optional[bool] = None,
show_tip_labels: Optional[bool] = None,
show_border: Optional[bool] = None,
value_format: Optional[str] = None,
bar_mode: Optional[Union[BAR_MODE, str]] = None,
num_bins: Optional[int] = None,
startangle: Optional[Union[str, int, float]] = None,
direction: Optional[Union[DIRECTION, str]] = None,
innerradius: Optional[float] = None,
scalex: Optional[Union[SCALE, str]] = None,
scaley: Optional[Union[SCALE, str]] = None,
subplots: Optional[bool] = None,
max_cols: Optional[int] = None,
sharex: Optional[bool] = None,
sharey: Optional[bool] = None,
style: Optional[
Union[
_RadialStyleAttrs,
List[Optional[_RadialStyleAttrs]],
]
] = None,
texts: Optional[
Union[
TextAttrs,
List[TextAttrs],
List[Union[TextAttrs, List[TextAttrs], None]],
]
] = None,
vlines: Optional[dict] = None,
hlines: Optional[dict] = None,
label: Optional[Union[str, List[Optional[str]]]] = None,
x: Optional[Union[str, List[Optional[str]]]] = None,
y: Optional[Union[str, List[Optional[str]]]] = None,
yerr: Optional[Union[str, List[Optional[str]]]] = None
) -> plt.Figure
Creates the radial chart.
A radial chart plots series on polar axes: as a line (radar) profile, an
area, bars, or a histogram, chosen with type. Use the radar form to
compare a few entities across several metrics on a shared scale, and the
bar and histogram forms for cyclic categories such as hours, weekdays, or
compass directions.
Added in v0.8.0
Examples:
>>> from datachart.charts import RadialChart
>>> figure = RadialChart(
... data=[
... {"label": "N", "y": 5},
... {"label": "E", "y": 10},
... {"label": "S", "y": 15},
... {"label": "W", "y": 20}
... ],
... title="Basic Radial Chart"
... )
| PARAMETER | DESCRIPTION |
|---|---|
data
|
The data points for the radial chart(s). Can be a single list of data
points for one chart, or a list of lists for multiple charts/subplots.
The line, bar, and scatter visuals take
TYPE:
|
type
|
The visual the whole figure draws: "line" (default), "bar",
"scatter", or "histogram". See
TYPE:
|
title
|
The title of the chart.
TYPE:
|
xlabel
|
The angular-axis label.
TYPE:
|
ylabel
|
The radial-axis label.
TYPE:
|
subtitle
|
The subtitle(s) for individual charts. Used as legend labels.
TYPE:
|
emphasis
|
The emphasis role(s) for individual charts, aligned like
TYPE:
|
figsize
|
The size of the figure.
TYPE:
|
ymin
|
The minimum radial-axis value.
TYPE:
|
ymax
|
The maximum radial-axis value.
TYPE:
|
show_legend
|
Whether to show the legend.
TYPE:
|
show_grid
|
Which grid lines to show (e.g., "both", "x", "y").
TYPE:
|
show_yerr
|
Whether to show the radial error band (line visual).
TYPE:
|
show_area
|
Whether to fill the area inside the line (line visual).
TYPE:
|
show_values
|
Whether to write each mark's value at its tip, rotated along the spoke.
TYPE:
|
show_tip_labels
|
Whether to write the category labels at the mark tips, rotated along their spokes, instead of around the circle.
TYPE:
|
show_border
|
Whether to draw the outer border circle. Defaults to the
theme's spine visibility;
TYPE:
|
value_format
|
Format for the values written by
TYPE:
|
bar_mode
|
How multiple bar series share the circle: "group",
"stack", or "overlay" (bar visual). See
TYPE:
|
num_bins
|
The number of angular bins over [0, 360) (histogram visual).
TYPE:
|
startangle
|
Where the first point sits: a compass location ("N", "NE", "E", "SE", "S", "SW", "W", "NW") or a numeric compass bearing in degrees clockwise from north. Defaults to "N".
TYPE:
|
direction
|
Which way the angles increase: "clockwise" (default) or
"counterclockwise". See
TYPE:
|
innerradius
|
The donut hole, as a fraction (0 <= f < 1) of the radial extent. Defaults to 0.
TYPE:
|
scalex
|
Not supported; the angular axis has no scale. Raises when passed.
TYPE:
|
scaley
|
The radial-axis scale (e.g., "log", "linear").
TYPE:
|
subplots
|
Whether to create separate polar subplots for each chart.
TYPE:
|
max_cols
|
Maximum number of columns in subplots (when subplots=True).
TYPE:
|
sharex
|
Whether to share the angular axis in subplots.
TYPE:
|
sharey
|
Whether to share the radial axis in subplots.
TYPE:
|
style
|
Style configuration(s) for the chart(s); radial visuals obey the
matching cartesian style family (
TYPE:
|
texts
|
Text annotation(s) to draw. On the polar axes, data
coordinates are (angle in radians, radius); axes-fraction
coordinates (
TYPE:
|
vlines
|
Not supported on a polar axes. Raises when passed.
TYPE:
|
hlines
|
Not supported on a polar axes. Raises when passed.
TYPE:
|
label
|
The key name in data for the category labels (default: "label").
TYPE:
|
x
|
The key name in data for the histogram observations (default: "x").
TYPE:
|
y
|
The key name in data for radial values (default: "y").
TYPE:
|
yerr
|
The key name in data for radial error values (default: "yerr").
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
plt.Figure
|
The figure containing the radial chart. |
Distributions
Histogram(
data: Union[
List[HistDataPointAttrs],
List[List[HistDataPointAttrs]],
],
*,
title: Optional[str] = None,
xlabel: Optional[str] = None,
ylabel: Optional[str] = None,
subtitle: Optional[
Union[str, List[Optional[str]]]
] = None,
emphasis: Optional[
Union[EMPHASIS, str, List[Optional[str]]]
] = None,
figsize: Optional[
Union[FIG_SIZE, Tuple[float, float]]
] = None,
xmin: Optional[Union[int, float]] = None,
xmax: Optional[Union[int, float]] = None,
ymin: Optional[Union[int, float]] = None,
ymax: Optional[Union[int, float]] = None,
show_legend: Optional[bool] = None,
show_grid: Optional[Union[SHOW_GRID, str]] = None,
show_density: Optional[bool] = None,
show_cumulative: Optional[bool] = None,
aspect_ratio: Optional[Union[ASPECT_RATIO, str]] = None,
orientation: Optional[
Union[ORIENTATION, str]
] = ORIENTATION.VERTICAL,
bar_mode: Optional[Union[BAR_MODE, str]] = None,
num_bins: Optional[int] = None,
scalex: Optional[Union[SCALE, str]] = None,
scaley: Optional[Union[SCALE, str]] = None,
subplots: Optional[bool] = None,
max_cols: Optional[int] = None,
sharex: Optional[bool] = None,
sharey: Optional[bool] = None,
style: Optional[
Union[
HistStyleAttrs, List[Optional[HistStyleAttrs]]
]
] = None,
xticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
xticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
xtickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
yticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
yticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
ytickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
vlines: Optional[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
List[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
None,
]
],
]
] = None,
hlines: Optional[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
List[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
None,
]
],
]
] = None,
texts: Optional[
Union[
TextAttrs,
List[TextAttrs],
List[Union[TextAttrs, List[TextAttrs], None]],
]
] = None,
x: Optional[Union[str, List[Optional[str]]]] = None
) -> plt.Figure
Creates the histogram.
A histogram bins a single numeric variable and draws the count (or density) per bin,
revealing the shape of its distribution: center, spread, skew, modes, and outliers.
Use it to inspect one variable or compare a few overlaid distributions. For
side-by-side group summaries use BoxPlot or
ViolinPlot.
Examples:
>>> from datachart.charts import Histogram
>>> figure = Histogram(
... data=[
... {"x": 1},
... {"x": 2},
... {"x": 3},
... {"x": 4},
... {"x": 5}
... ],
... title="Basic Histogram",
... xlabel="X",
... ylabel="Y"
... )
| PARAMETER | DESCRIPTION |
|---|---|
data
|
The data points for the histogram(s). Can be a single list of data points for one chart, or a list of lists for multiple charts/subplots.
TYPE:
|
title
|
The title of the chart.
TYPE:
|
xlabel
|
The x-axis label.
TYPE:
|
ylabel
|
The y-axis label.
TYPE:
|
subtitle
|
The subtitle(s) for individual charts. Used as legend labels.
TYPE:
|
emphasis
|
The emphasis role(s) for individual charts, aligned like
TYPE:
|
figsize
|
The size of the figure.
TYPE:
|
xmin
|
The minimum x-axis value.
TYPE:
|
xmax
|
The maximum x-axis value.
TYPE:
|
ymin
|
The minimum y-axis value.
TYPE:
|
ymax
|
The maximum y-axis value.
TYPE:
|
show_legend
|
Whether to show the legend.
TYPE:
|
show_grid
|
Which grid lines to show (e.g., "both", "x", "y").
TYPE:
|
show_density
|
Whether to plot the density histogram.
TYPE:
|
show_cumulative
|
Whether to plot the cumulative histogram.
TYPE:
|
aspect_ratio
|
The aspect ratio of the axes ("auto" or "equal"). See
TYPE:
|
orientation
|
The orientation of the histogram (vertical or horizontal).
TYPE:
|
bar_mode
|
How multiple histogram series share the axis: "stack"
(stacked on shared bins, the default) or "overlay" (each series
drawn individually over the others). "group" has no histogram
meaning and behaves like "overlay". See
TYPE:
|
num_bins
|
The number of bins to split the data into.
TYPE:
|
scalex
|
The x-axis scale (e.g., "log", "linear"). Useful for log-distributed data.
TYPE:
|
scaley
|
The y-axis scale (e.g., "log", "linear").
TYPE:
|
subplots
|
Whether to create separate subplots for each chart.
TYPE:
|
max_cols
|
Maximum number of columns in subplots (when subplots=True).
TYPE:
|
sharex
|
Whether to share the x-axis in subplots.
TYPE:
|
sharey
|
Whether to share the y-axis in subplots.
TYPE:
|
style
|
Style configuration(s) for the histogram(s).
TYPE:
|
xticks
|
Custom x-axis tick positions.
TYPE:
|
xticklabels
|
Custom x-axis tick labels.
TYPE:
|
xtickrotate
|
Rotation angle for x-axis tick labels.
TYPE:
|
yticks
|
Custom y-axis tick positions.
TYPE:
|
yticklabels
|
Custom y-axis tick labels.
TYPE:
|
ytickrotate
|
Rotation angle for y-axis tick labels.
TYPE:
|
vlines
|
Vertical line(s) to plot.
TYPE:
|
hlines
|
Horizontal line(s) to plot.
TYPE:
|
texts
|
Text annotation(s) to draw.
TYPE:
|
x
|
The key name in data for x-axis values (default: "x").
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
plt.Figure
|
The figure containing the histogram. |
BoxPlot(
data: Union[
List[BoxDataPointAttrs],
List[List[BoxDataPointAttrs]],
],
*,
title: Optional[str] = None,
xlabel: Optional[str] = None,
ylabel: Optional[str] = None,
subtitle: Optional[
Union[str, List[Optional[str]]]
] = None,
emphasis: Optional[
Union[EMPHASIS, str, List[Optional[str]]]
] = None,
figsize: Optional[
Union[FIG_SIZE, Tuple[float, float]]
] = None,
xmin: Optional[Union[int, float]] = None,
xmax: Optional[Union[int, float]] = None,
ymin: Optional[Union[int, float]] = None,
ymax: Optional[Union[int, float]] = None,
show_legend: Optional[bool] = None,
show_grid: Optional[Union[SHOW_GRID, str]] = None,
show_outliers: Optional[bool] = None,
show_notch: Optional[bool] = None,
aspect_ratio: Optional[Union[ASPECT_RATIO, str]] = None,
orientation: Optional[
Union[ORIENTATION, str]
] = ORIENTATION.VERTICAL,
scaley: Optional[Union[SCALE, str]] = None,
subplots: Optional[bool] = None,
max_cols: Optional[int] = None,
sharex: Optional[bool] = None,
sharey: Optional[bool] = None,
style: Optional[
Union[BoxStyleAttrs, List[Optional[BoxStyleAttrs]]]
] = None,
xticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
xticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
xtickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
yticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
yticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
ytickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
vlines: Optional[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
List[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
None,
]
],
]
] = None,
hlines: Optional[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
List[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
None,
]
],
]
] = None,
texts: Optional[
Union[
TextAttrs,
List[TextAttrs],
List[Union[TextAttrs, List[TextAttrs], None]],
]
] = None,
label: Optional[Union[str, List[Optional[str]]]] = None,
value: Optional[Union[str, List[Optional[str]]]] = None
) -> plt.Figure
Creates the box plot.
A box plot summarizes a numeric distribution per group by its median, quartiles,
whiskers, and outliers. Use it to compare the level and spread of many groups
compactly, or to spot skew and outliers, when the full distribution shape is not
needed. For shape use ViolinPlot; for the raw
points use SwarmPlot.
Added in v0.7.0
Examples:
>>> from datachart.charts import BoxPlot
>>> figure = BoxPlot(
... data=[
... {"label": "Group A", "value": 10},
... {"label": "Group A", "value": 15},
... {"label": "Group A", "value": 12},
... {"label": "Group B", "value": 20},
... {"label": "Group B", "value": 25},
... {"label": "Group B", "value": 22},
... ],
... title="Basic Box Plot",
... xlabel="Group",
... ylabel="Value"
... )
| PARAMETER | DESCRIPTION |
|---|---|
data
|
The data points for the box plot(s). Can be a single list of data points
for one chart, or a list of lists for multiple charts/subplots.
Each data point should have a
TYPE:
|
title
|
The title of the chart.
TYPE:
|
xlabel
|
The x-axis label.
TYPE:
|
ylabel
|
The y-axis label.
TYPE:
|
subtitle
|
The subtitle(s) for individual charts. Used as legend labels.
TYPE:
|
emphasis
|
The emphasis role(s), aligned with the box labels of one call (a single value applies to every box): "background" mutes a box and its whiskers, caps, median, and outliers, "highlight" bolds the box edges and median, None leaves it unchanged.
TYPE:
|
figsize
|
The size of the figure.
TYPE:
|
xmin
|
The minimum x-axis value.
TYPE:
|
xmax
|
The maximum x-axis value.
TYPE:
|
ymin
|
The minimum y-axis value.
TYPE:
|
ymax
|
The maximum y-axis value.
TYPE:
|
show_legend
|
Whether to show the legend.
TYPE:
|
show_grid
|
Which grid lines to show (e.g., "both", "x", "y").
TYPE:
|
show_outliers
|
Whether to show outliers. Defaults to True.
TYPE:
|
show_notch
|
Whether to show notched boxes for median confidence interval.
TYPE:
|
aspect_ratio
|
The aspect ratio of the axes ("auto" or "equal"). See
TYPE:
|
orientation
|
The orientation of the boxes (vertical or horizontal).
TYPE:
|
scaley
|
The y-axis scale (e.g., "log", "linear").
TYPE:
|
subplots
|
Whether to create separate subplots for each chart.
TYPE:
|
max_cols
|
Maximum number of columns in subplots (when subplots=True).
TYPE:
|
sharex
|
Whether to share the x-axis in subplots.
TYPE:
|
sharey
|
Whether to share the y-axis in subplots.
TYPE:
|
style
|
Style configuration(s) for the box(es).
TYPE:
|
xticks
|
Custom x-axis tick positions.
TYPE:
|
xticklabels
|
Custom x-axis tick labels.
TYPE:
|
xtickrotate
|
Rotation angle for x-axis tick labels.
TYPE:
|
yticks
|
Custom y-axis tick positions.
TYPE:
|
yticklabels
|
Custom y-axis tick labels.
TYPE:
|
ytickrotate
|
Rotation angle for y-axis tick labels.
TYPE:
|
vlines
|
Vertical line(s) to plot.
TYPE:
|
hlines
|
Horizontal line(s) to plot.
TYPE:
|
texts
|
Text annotation(s) to draw.
TYPE:
|
label
|
The key name in data for label/category values (default: "label").
TYPE:
|
value
|
The key name in data for numeric values (default: "value").
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
plt.Figure
|
The figure containing the box plot. |
ViolinPlot(
data: Union[
List[ViolinDataPointAttrs],
List[List[ViolinDataPointAttrs]],
],
*,
title: Optional[str] = None,
xlabel: Optional[str] = None,
ylabel: Optional[str] = None,
subtitle: Optional[
Union[str, List[Optional[str]]]
] = None,
emphasis: Optional[
Union[EMPHASIS, str, List[Optional[str]]]
] = None,
figsize: Optional[
Union[FIG_SIZE, Tuple[float, float]]
] = None,
xmin: Optional[Union[int, float]] = None,
xmax: Optional[Union[int, float]] = None,
ymin: Optional[Union[int, float]] = None,
ymax: Optional[Union[int, float]] = None,
show_legend: Optional[bool] = None,
show_grid: Optional[Union[SHOW_GRID, str]] = None,
aspect_ratio: Optional[Union[ASPECT_RATIO, str]] = None,
orientation: Optional[
Union[ORIENTATION, str]
] = ORIENTATION.VERTICAL,
scaley: Optional[Union[SCALE, str]] = None,
subplots: Optional[bool] = None,
max_cols: Optional[int] = None,
sharex: Optional[bool] = None,
sharey: Optional[bool] = None,
style: Optional[
Union[
ViolinStyleAttrs,
List[Optional[ViolinStyleAttrs]],
]
] = None,
xticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
xticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
xtickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
yticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
yticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
ytickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
vlines: Optional[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
List[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
None,
]
],
]
] = None,
hlines: Optional[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
List[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
None,
]
],
]
] = None,
texts: Optional[
Union[
TextAttrs,
List[TextAttrs],
List[Union[TextAttrs, List[TextAttrs], None]],
]
] = None,
label: Optional[Union[str, List[Optional[str]]]] = None,
value: Optional[Union[str, List[Optional[str]]]] = None,
inner: Optional[
Union[VIOLIN_INNER, str]
] = VIOLIN_INNER.BOX,
bandwidth: Optional[
Union[BANDWIDTH, str, float]
] = None,
split: Optional[str] = None
) -> plt.Figure
Creates the violin plot.
A violin plot draws the kernel density estimate of each group's numeric distribution as a mirrored profile, showing shape (multimodality, skew, tails) that a box plot hides. Use it to compare distributions across groups when shape matters and each group has enough samples for a density estimate.
Added in 0.9.0
Examples:
>>> from datachart.charts import ViolinPlot
>>> figure = ViolinPlot(
... data=[
... {"label": "Group A", "value": 10},
... {"label": "Group A", "value": 15},
... {"label": "Group A", "value": 12},
... {"label": "Group B", "value": 20},
... {"label": "Group B", "value": 25},
... {"label": "Group B", "value": 22},
... ],
... title="Basic Violin Plot",
... xlabel="Group",
... ylabel="Value"
... )
| PARAMETER | DESCRIPTION |
|---|---|
data
|
The data points for the violin plot(s). Can be a single list of data points
for one chart, or a list of lists for multiple charts/subplots.
Each data point should have a
TYPE:
|
title
|
The title of the chart.
TYPE:
|
xlabel
|
The x-axis label.
TYPE:
|
ylabel
|
The y-axis label.
TYPE:
|
subtitle
|
The subtitle(s) for individual charts (subplots).
TYPE:
|
emphasis
|
The emphasis role(s), aligned with the violin labels of one call (a single value applies to every violin): "background" mutes a violin body and its inner marks, "highlight" bolds the body edge, None leaves it unchanged.
TYPE:
|
figsize
|
The size of the figure.
TYPE:
|
xmin
|
The minimum x-axis value.
TYPE:
|
xmax
|
The maximum x-axis value.
TYPE:
|
ymin
|
The minimum y-axis value.
TYPE:
|
ymax
|
The maximum y-axis value.
TYPE:
|
show_legend
|
Whether to show the legend.
TYPE:
|
show_grid
|
Which grid lines to show (e.g., "both", "x", "y").
TYPE:
|
aspect_ratio
|
The aspect ratio of the axes ("auto" or "equal"). See
TYPE:
|
orientation
|
The orientation of the violins (vertical or horizontal).
TYPE:
|
scaley
|
The y-axis scale (e.g., "log", "linear").
TYPE:
|
subplots
|
Whether to create separate subplots for each chart.
TYPE:
|
max_cols
|
Maximum number of columns in subplots (when subplots=True).
TYPE:
|
sharex
|
Whether to share the x-axis in subplots.
TYPE:
|
sharey
|
Whether to share the y-axis in subplots.
TYPE:
|
style
|
Style configuration(s) for the violin(s).
TYPE:
|
xticks
|
Custom x-axis tick positions.
TYPE:
|
xticklabels
|
Custom x-axis tick labels.
TYPE:
|
xtickrotate
|
Rotation angle for x-axis tick labels.
TYPE:
|
yticks
|
Custom y-axis tick positions.
TYPE:
|
yticklabels
|
Custom y-axis tick labels.
TYPE:
|
ytickrotate
|
Rotation angle for y-axis tick labels.
TYPE:
|
vlines
|
Vertical line(s) to plot.
TYPE:
|
hlines
|
Horizontal line(s) to plot.
TYPE:
|
texts
|
Text annotation(s) to draw.
TYPE:
|
label
|
The key name in data for label/category values (default: "label").
TYPE:
|
value
|
The key name in data for numeric values (default: "value").
TYPE:
|
inner
|
The marks drawn inside each body: "box" (quartile bar, 1.5·IQR
whisker, median dot), "quartiles" (dashed median, dotted Q1/Q3),
"median" (one line), or None (body only). See
TYPE:
|
bandwidth
|
The KDE bandwidth: None or "scott" (Scott's rule),
"silverman", or a scalar factor. See
TYPE:
|
split
|
The key name in data whose exactly two distinct values become the left and right halves of each violin, colored from the multiple palette and listed in the legend.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
plt.Figure
|
The figure containing the violin plot. |
SwarmPlot(
data: Union[
List[SwarmDataPointAttrs],
List[List[SwarmDataPointAttrs]],
],
*,
title: Optional[str] = None,
xlabel: Optional[str] = None,
ylabel: Optional[str] = None,
subtitle: Optional[
Union[str, List[Optional[str]]]
] = None,
emphasis: Optional[
Union[EMPHASIS, str, List[Optional[str]]]
] = None,
figsize: Optional[
Union[FIG_SIZE, Tuple[float, float]]
] = None,
xmin: Optional[Union[int, float]] = None,
xmax: Optional[Union[int, float]] = None,
ymin: Optional[Union[int, float]] = None,
ymax: Optional[Union[int, float]] = None,
show_legend: Optional[bool] = None,
show_grid: Optional[Union[SHOW_GRID, str]] = None,
mode: Union[SWARM_MODE, str] = SWARM_MODE.SWARM,
jitter: float = 0.4,
aspect_ratio: Optional[Union[ASPECT_RATIO, str]] = None,
orientation: Optional[
Union[ORIENTATION, str]
] = ORIENTATION.VERTICAL,
scaley: Optional[Union[SCALE, str]] = None,
subplots: Optional[bool] = None,
max_cols: Optional[int] = None,
sharex: Optional[bool] = None,
sharey: Optional[bool] = None,
style: Optional[
Union[
SwarmStyleAttrs, List[Optional[SwarmStyleAttrs]]
]
] = None,
xticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
xticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
xtickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
yticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
yticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
ytickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
vlines: Optional[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
List[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
None,
]
],
]
] = None,
hlines: Optional[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
List[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
None,
]
],
]
] = None,
texts: Optional[
Union[
TextAttrs,
List[TextAttrs],
List[Union[TextAttrs, List[TextAttrs], None]],
]
] = None,
label: Optional[Union[str, List[Optional[str]]]] = None,
value: Optional[Union[str, List[Optional[str]]]] = None
) -> plt.Figure
Creates the swarm plot.
A swarm plot draws every observation as a point at its group's category
position, spread across the category width so the points do not hide each
other, making counts and gaps visible. Use it for small-to-medium samples
where each observation matters, or overlay it on a
BoxPlot with Panel (the two share
positions). For large samples prefer
ViolinPlot.
Added in 0.9.0
Examples:
>>> from datachart.charts import SwarmPlot
>>> figure = SwarmPlot(
... data=[
... {"label": "Group A", "value": 10},
... {"label": "Group A", "value": 15},
... {"label": "Group A", "value": 12},
... {"label": "Group B", "value": 20},
... {"label": "Group B", "value": 25},
... {"label": "Group B", "value": 22},
... ],
... title="Basic Swarm Plot",
... xlabel="Group",
... ylabel="Value"
... )
| PARAMETER | DESCRIPTION |
|---|---|
data
|
The data points for the swarm plot(s). Can be a single list of data
points for one chart, or a list of lists for multiple charts.
Each data point should have a
TYPE:
|
title
|
The title of the chart.
TYPE:
|
xlabel
|
The x-axis label.
TYPE:
|
ylabel
|
The y-axis label.
TYPE:
|
subtitle
|
The subtitle(s) for individual charts. Used as legend labels.
TYPE:
|
emphasis
|
The emphasis role(s), aligned with the group labels of one call (a single value applies to every group): "background" mutes a group's points, "highlight" bolds their edges, None leaves them unchanged.
TYPE:
|
figsize
|
The size of the figure.
TYPE:
|
xmin
|
The minimum x-axis value.
TYPE:
|
xmax
|
The maximum x-axis value.
TYPE:
|
ymin
|
The minimum y-axis value.
TYPE:
|
ymax
|
The maximum y-axis value.
TYPE:
|
show_legend
|
Whether to show the legend.
TYPE:
|
show_grid
|
Which grid lines to show (e.g., "both", "x", "y").
TYPE:
|
mode
|
How the points spread across the category width. See
TYPE:
|
jitter
|
The strip jitter width, as a fraction of the category width.
Only used with
TYPE:
|
aspect_ratio
|
The aspect ratio of the axes ("auto" or "equal"). See
TYPE:
|
orientation
|
The orientation of the swarms (vertical or horizontal).
TYPE:
|
scaley
|
The y-axis scale (e.g., "log", "linear").
TYPE:
|
subplots
|
Whether to create separate subplots for each chart.
TYPE:
|
max_cols
|
Maximum number of columns in subplots (when subplots=True).
TYPE:
|
sharex
|
Whether to share the x-axis in subplots.
TYPE:
|
sharey
|
Whether to share the y-axis in subplots.
TYPE:
|
style
|
Style configuration(s) for the points.
TYPE:
|
xticks
|
Custom x-axis tick positions.
TYPE:
|
xticklabels
|
Custom x-axis tick labels.
TYPE:
|
xtickrotate
|
Rotation angle for x-axis tick labels.
TYPE:
|
yticks
|
Custom y-axis tick positions.
TYPE:
|
yticklabels
|
Custom y-axis tick labels.
TYPE:
|
ytickrotate
|
Rotation angle for y-axis tick labels.
TYPE:
|
vlines
|
Vertical line(s) to plot.
TYPE:
|
hlines
|
Horizontal line(s) to plot.
TYPE:
|
texts
|
Text annotation(s) to draw.
TYPE:
|
label
|
The key name in data for label/category values (default: "label").
TYPE:
|
value
|
The key name in data for numeric values (default: "value").
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
plt.Figure
|
The figure containing the swarm plot. |
RaincloudPlot(
data: Union[
List[RaincloudDataPointAttrs],
List[List[RaincloudDataPointAttrs]],
],
*,
title: Optional[str] = None,
xlabel: Optional[str] = None,
ylabel: Optional[str] = None,
subtitle: Optional[
Union[str, List[Optional[str]]]
] = None,
emphasis: Optional[
Union[EMPHASIS, str, List[Optional[str]]]
] = None,
figsize: Optional[
Union[FIG_SIZE, Tuple[float, float]]
] = None,
xmin: Optional[Union[int, float]] = None,
xmax: Optional[Union[int, float]] = None,
ymin: Optional[Union[int, float]] = None,
ymax: Optional[Union[int, float]] = None,
show_legend: Optional[bool] = None,
show_grid: Optional[Union[SHOW_GRID, str]] = None,
show_outliers: Optional[bool] = True,
mode: Union[SWARM_MODE, str] = SWARM_MODE.SWARM,
jitter: float = 0.4,
bandwidth: Optional[
Union[BANDWIDTH, str, float]
] = None,
aspect_ratio: Optional[Union[ASPECT_RATIO, str]] = None,
orientation: Optional[
Union[ORIENTATION, str]
] = ORIENTATION.VERTICAL,
scaley: Optional[Union[SCALE, str]] = None,
subplots: Optional[bool] = None,
max_cols: Optional[int] = None,
sharex: Optional[bool] = None,
sharey: Optional[bool] = None,
style: Optional[
Union[
RaincloudStyleAttrs,
List[Optional[RaincloudStyleAttrs]],
]
] = None,
xticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
xticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
xtickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
yticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
yticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
ytickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
vlines: Optional[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
List[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
None,
]
],
]
] = None,
hlines: Optional[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
List[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
None,
]
],
]
] = None,
texts: Optional[
Union[
TextAttrs,
List[TextAttrs],
List[Union[TextAttrs, List[TextAttrs], None]],
]
] = None,
label: Optional[Union[str, List[Optional[str]]]] = None,
value: Optional[Union[str, List[Optional[str]]]] = None
) -> plt.Figure
Creates the raincloud plot.
A raincloud plot draws each group as a cloud (a half violin of its density), its rain (the raw observations), and a box (the quartile summary) side by side at one category position, all in the group's palette color. Use it when you want the shape, the summary statistics, and the individual observations in a single view, for example when reporting experimental results per condition. Vertical rainclouds keep the cloud on the left; horizontal ones keep it above.
Added in 0.9.0
Examples:
>>> from datachart.charts import RaincloudPlot
>>> figure = RaincloudPlot(
... data=[
... {"label": "Group A", "value": 10},
... {"label": "Group A", "value": 15},
... {"label": "Group A", "value": 12},
... {"label": "Group B", "value": 20},
... {"label": "Group B", "value": 25},
... {"label": "Group B", "value": 22},
... ],
... title="Basic Raincloud Plot",
... xlabel="Group",
... ylabel="Value"
... )
| PARAMETER | DESCRIPTION |
|---|---|
data
|
The data points for the raincloud plot(s). Can be a single list of
data points for one chart, or a list of lists for multiple charts
(drawn as subplots). Each data point should have a
TYPE:
|
title
|
The title of the chart.
TYPE:
|
xlabel
|
The x-axis label.
TYPE:
|
ylabel
|
The y-axis label.
TYPE:
|
subtitle
|
The subtitle(s) for individual charts.
TYPE:
|
emphasis
|
The emphasis role(s), aligned with the group labels of one call (a single value applies to every group): "background" mutes a group's cloud, rain, and box, "highlight" bolds their edges, None leaves them unchanged.
TYPE:
|
figsize
|
The size of the figure.
TYPE:
|
xmin
|
The minimum x-axis value.
TYPE:
|
xmax
|
The maximum x-axis value.
TYPE:
|
ymin
|
The minimum y-axis value.
TYPE:
|
ymax
|
The maximum y-axis value.
TYPE:
|
show_legend
|
Whether to show the legend; one entry per group.
TYPE:
|
show_grid
|
Which grid lines to show (e.g., "both", "x", "y").
TYPE:
|
show_outliers
|
Whether the box shows outliers.
TYPE:
|
mode
|
How the rain spreads across its width. See
TYPE:
|
jitter
|
The strip jitter width, as a fraction of the category width
like
TYPE:
|
bandwidth
|
The cloud's KDE bandwidth: None or "scott" (Scott's rule),
"silverman" (Silverman's rule), or a scalar factor. See
TYPE:
|
aspect_ratio
|
The aspect ratio of the axes ("auto" or "equal"). See
TYPE:
|
orientation
|
The orientation of the rainclouds (vertical or horizontal).
TYPE:
|
scaley
|
The y-axis scale (e.g., "log", "linear").
TYPE:
|
subplots
|
Whether to create separate subplots for each chart.
TYPE:
|
max_cols
|
Maximum number of columns in subplots (when subplots=True).
TYPE:
|
sharex
|
Whether to share the x-axis in subplots.
TYPE:
|
sharey
|
Whether to share the y-axis in subplots.
TYPE:
|
style
|
Style configuration(s); the violin keys style the cloud, the swarm keys the rain, and the box keys the box.
TYPE:
|
xticks
|
Custom x-axis tick positions.
TYPE:
|
xticklabels
|
Custom x-axis tick labels.
TYPE:
|
xtickrotate
|
Rotation angle for x-axis tick labels.
TYPE:
|
yticks
|
Custom y-axis tick positions.
TYPE:
|
yticklabels
|
Custom y-axis tick labels.
TYPE:
|
ytickrotate
|
Rotation angle for y-axis tick labels.
TYPE:
|
vlines
|
Vertical line(s) to plot.
TYPE:
|
hlines
|
Horizontal line(s) to plot.
TYPE:
|
texts
|
Text annotation(s) to draw.
TYPE:
|
label
|
The key name in data for label/category values (default: "label").
TYPE:
|
value
|
The key name in data for numeric values (default: "value").
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
plt.Figure
|
The figure containing the raincloud plot. |
Relationships
ScatterChart(
data: Union[
List[ScatterDataPointAttrs],
List[List[ScatterDataPointAttrs]],
],
*,
title: Optional[str] = None,
xlabel: Optional[str] = None,
ylabel: Optional[str] = None,
subtitle: Optional[
Union[str, List[Optional[str]]]
] = None,
emphasis: Optional[
Union[EMPHASIS, str, List[Optional[str]]]
] = None,
figsize: Optional[
Union[FIG_SIZE, Tuple[float, float]]
] = None,
xmin: Optional[Union[int, float]] = None,
xmax: Optional[Union[int, float]] = None,
ymin: Optional[Union[int, float]] = None,
ymax: Optional[Union[int, float]] = None,
show_legend: Optional[bool] = None,
show_grid: Optional[Union[SHOW_GRID, str]] = None,
show_regression: Optional[bool] = None,
show_ci: Optional[bool] = None,
ci_level: Optional[float] = None,
show_correlation: Optional[bool] = None,
aspect_ratio: Optional[Union[ASPECT_RATIO, str]] = None,
scalex: Optional[Union[SCALE, str]] = None,
scaley: Optional[Union[SCALE, str]] = None,
subplots: Optional[bool] = None,
max_cols: Optional[int] = None,
sharex: Optional[bool] = None,
sharey: Optional[bool] = None,
style: Optional[
Union[
ScatterStyleAttrs,
List[Optional[ScatterStyleAttrs]],
]
] = None,
xticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
xticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
xtickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
yticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
yticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
ytickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
vlines: Optional[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
List[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
None,
]
],
]
] = None,
hlines: Optional[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
List[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
None,
]
],
]
] = None,
texts: Optional[
Union[
TextAttrs,
List[TextAttrs],
List[Union[TextAttrs, List[TextAttrs], None]],
]
] = None,
x: Optional[Union[str, List[Optional[str]]]] = None,
y: Optional[Union[str, List[Optional[str]]]] = None,
size: Optional[Union[str, List[Optional[str]]]] = None,
hue: Optional[Union[str, List[Optional[str]]]] = None,
size_range: Optional[Tuple[float, float]] = None
) -> plt.Figure
Creates a scatter chart.
Each point is one observation placed by two numeric variables, optionally
with a third encoded as marker size. Use it to check whether two variables
are related, spot clusters and outliers, and quantify the link with the
optional regression line and correlation coefficient. For ordered series
use LineChart.
Added in v0.7.0
Examples:
>>> from datachart.charts import ScatterChart
>>> # Basic scatter plot
>>> figure = ScatterChart(
... data=[
... {"x": 1, "y": 5},
... {"x": 2, "y": 10},
... {"x": 3, "y": 15},
... {"x": 4, "y": 20},
... {"x": 5, "y": 25}
... ],
... title="Basic Scatter Chart",
... xlabel="X",
... ylabel="Y"
... )
>>>
>>> # Scatter with hue grouping
>>> figure = ScatterChart(
... data=[
... {"x": 1, "y": 5, "category": "A"},
... {"x": 2, "y": 10, "category": "B"},
... ],
... hue="category",
... show_legend=True
... )
>>>
>>> # Bubble chart with size variable
>>> figure = ScatterChart(
... data=[
... {"x": 1, "y": 5, "pop": 100},
... {"x": 2, "y": 10, "pop": 200}
... ],
... size="pop",
... size_range=(20, 200)
... )
>>>
>>> # Scatter with regression line
>>> figure = ScatterChart(
... data=[...],
... show_regression=True,
... show_ci=True,
... ci_level=0.95
... )
>>>
>>> # Scatter with correlation annotation
>>> figure = ScatterChart(
... data=[...],
... show_correlation=True
... )
| PARAMETER | DESCRIPTION |
|---|---|
data
|
The data points for the scatter chart(s). Can be a single list of data points for one chart, or a list of lists for multiple charts/subplots.
TYPE:
|
title
|
The title of the chart.
TYPE:
|
xlabel
|
The x-axis label.
TYPE:
|
ylabel
|
The y-axis label.
TYPE:
|
subtitle
|
The subtitle(s) for individual charts. Used as legend labels.
TYPE:
|
emphasis
|
The emphasis role(s) for individual charts, aligned like
TYPE:
|
figsize
|
The size of the figure.
TYPE:
|
xmin
|
The minimum x-axis value.
TYPE:
|
xmax
|
The maximum x-axis value.
TYPE:
|
ymin
|
The minimum y-axis value.
TYPE:
|
ymax
|
The maximum y-axis value.
TYPE:
|
show_legend
|
Whether to show the legend.
TYPE:
|
show_grid
|
Which grid lines to show (e.g., "both", "x", "y").
TYPE:
|
show_regression
|
Whether to show the regression line.
TYPE:
|
show_ci
|
Whether to show the confidence interval around the regression line.
TYPE:
|
ci_level
|
The confidence interval level (default 0.95).
TYPE:
|
show_correlation
|
Whether to show the Pearson correlation coefficient (r-value) as an annotation.
TYPE:
|
aspect_ratio
|
The aspect ratio of the axes ("auto" or "equal"). See
TYPE:
|
scalex
|
The x-axis scale (e.g., "log", "linear").
TYPE:
|
scaley
|
The y-axis scale (e.g., "log", "linear").
TYPE:
|
subplots
|
Whether to create separate subplots for each chart.
TYPE:
|
max_cols
|
Maximum number of columns in subplots (when subplots=True).
TYPE:
|
sharex
|
Whether to share the x-axis in subplots.
TYPE:
|
sharey
|
Whether to share the y-axis in subplots.
TYPE:
|
style
|
Style configuration(s) for the scatter markers.
TYPE:
|
xticks
|
Custom x-axis tick positions.
TYPE:
|
xticklabels
|
Custom x-axis tick labels.
TYPE:
|
xtickrotate
|
Rotation angle for x-axis tick labels.
TYPE:
|
yticks
|
Custom y-axis tick positions.
TYPE:
|
yticklabels
|
Custom y-axis tick labels.
TYPE:
|
ytickrotate
|
Rotation angle for y-axis tick labels.
TYPE:
|
vlines
|
Vertical line(s) to plot.
TYPE:
|
hlines
|
Horizontal line(s) to plot.
TYPE:
|
texts
|
Text annotation(s) to draw.
TYPE:
|
x
|
The key name in data for x-axis values (default: "x").
TYPE:
|
y
|
The key name in data for y-axis values (default: "y").
TYPE:
|
size
|
The key name in data for marker size values (for bubble charts).
TYPE:
|
hue
|
The key name in data for color grouping (categorical variable).
TYPE:
|
size_range
|
Tuple of (min_size, max_size) for bubble charts (default: (20, 200)).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
plt.Figure
|
The figure containing the scatter chart. |
Heatmap(
data: Union[HeatmapDataAttrs, List[HeatmapDataAttrs]],
*,
title: Optional[str] = None,
xlabel: Optional[str] = None,
ylabel: Optional[str] = None,
subtitle: Optional[
Union[str, List[Optional[str]]]
] = None,
emphasis: None = None,
figsize: Optional[
Union[FIG_SIZE, Tuple[float, float]]
] = None,
xmin: Optional[Union[int, float]] = None,
xmax: Optional[Union[int, float]] = None,
ymin: Optional[Union[int, float]] = None,
ymax: Optional[Union[int, float]] = None,
show_legend: Optional[bool] = None,
show_grid: Optional[Union[SHOW_GRID, str]] = None,
show_colorbars: Optional[bool] = None,
show_heatmap_values: Optional[bool] = None,
aspect_ratio: Optional[Union[ASPECT_RATIO, str]] = None,
subplots: Optional[bool] = None,
max_cols: Optional[int] = None,
sharex: Optional[bool] = None,
sharey: Optional[bool] = None,
style: Optional[
Union[
HeatmapStyleAttrs,
List[Optional[HeatmapStyleAttrs]],
]
] = None,
norm: Optional[Union[str, List[Optional[str]]]] = None,
vmin: Optional[
Union[float, List[Optional[float]]]
] = None,
vmax: Optional[
Union[float, List[Optional[float]]]
] = None,
valfmt: Optional[
Union[VALUE_FORMAT, str, List[Optional[str]]]
] = None,
xticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
xticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
xtickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
yticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
yticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
ytickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
colorbar: Optional[
Union[
HeatmapColorbarAttrs,
List[Optional[HeatmapColorbarAttrs]],
]
] = None,
texts: Optional[
Union[
TextAttrs,
List[TextAttrs],
List[Union[TextAttrs, List[TextAttrs], None]],
]
] = None
) -> plt.Figure
Creates the heatmap.
A heatmap maps every cell of a 2-D matrix to a color, so structure in a grid of numbers (correlations, confusion matrices, feature-by-time tables) reads at a glance. Use it when both axes are categorical or gridded and the value is what matters; the color scale, colorbar, and cell value labels are all configurable.
Added in v0.4.0
Examples:
>>> from datachart.charts import Heatmap
>>> figure = Heatmap(
... data={
... "x": ["a", "b", "c"],
... "y": ["p", "q", "r"],
... "z": [
... [1, 2, 3],
... [4, 5, 6],
... [7, 8, 9],
... ],
... },
... title="Basic Heatmap",
... xlabel="X",
... ylabel="Y"
... )
| PARAMETER | DESCRIPTION |
|---|---|
data
|
The labelled grid(s) for the heatmap(s): one
TYPE:
|
title
|
The title of the chart.
TYPE:
|
xlabel
|
The x-axis label.
TYPE:
|
ylabel
|
The y-axis label.
TYPE:
|
subtitle
|
The subtitle(s) for individual charts.
TYPE:
|
emphasis
|
Not supported: a heatmap is a single raster layer with no
series to mute or highlight. Passing a value raises
TYPE:
|
figsize
|
The size of the figure.
TYPE:
|
xmin
|
The minimum x-axis value.
TYPE:
|
xmax
|
The maximum x-axis value.
TYPE:
|
ymin
|
The minimum y-axis value.
TYPE:
|
ymax
|
The maximum y-axis value.
TYPE:
|
show_legend
|
Whether to show the legend (not typical for heatmaps).
TYPE:
|
show_grid
|
Which grid lines to show (e.g., "both", "x", "y").
TYPE:
|
show_colorbars
|
Whether to show the colorbar(s).
TYPE:
|
show_heatmap_values
|
Whether to show values on the heatmap cells.
TYPE:
|
aspect_ratio
|
The aspect ratio of the axes ("auto" or "equal"). See
TYPE:
|
subplots
|
Whether to create separate subplots for each heatmap.
TYPE:
|
max_cols
|
Maximum number of columns in subplots (when subplots=True).
TYPE:
|
sharex
|
Whether to share the x-axis in subplots.
TYPE:
|
sharey
|
Whether to share the y-axis in subplots.
TYPE:
|
style
|
Style configuration(s) for the heatmap(s).
TYPE:
|
norm
|
Value normalization method(s).
TYPE:
|
vmin
|
Minimum value(s) for normalization.
TYPE:
|
vmax
|
Maximum value(s) for normalization.
TYPE:
|
valfmt
|
Format string(s) for cell values, with the value named
TYPE:
|
xticks
|
Custom x-axis tick positions.
TYPE:
|
xticklabels
|
Custom x-axis tick labels.
TYPE:
|
xtickrotate
|
Rotation angle for x-axis tick labels.
TYPE:
|
yticks
|
Custom y-axis tick positions.
TYPE:
|
yticklabels
|
Custom y-axis tick labels.
TYPE:
|
ytickrotate
|
Rotation angle for y-axis tick labels.
TYPE:
|
colorbar
|
Colorbar configuration(s).
TYPE:
|
texts
|
Text annotation(s) to draw.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
plt.Figure
|
The figure containing the heatmap. |
ContourChart(
data: Union[ContourDataAttrs, List[ContourDataAttrs]],
*,
title: Optional[str] = None,
xlabel: Optional[str] = None,
ylabel: Optional[str] = None,
subtitle: Optional[
Union[str, List[Optional[str]]]
] = None,
emphasis: Optional[
Union[EMPHASIS, str, List[Optional[str]]]
] = None,
figsize: Optional[
Union[FIG_SIZE, Tuple[float, float]]
] = None,
xmin: Optional[Union[int, float]] = None,
xmax: Optional[Union[int, float]] = None,
ymin: Optional[Union[int, float]] = None,
ymax: Optional[Union[int, float]] = None,
show_legend: Optional[bool] = None,
show_grid: Optional[Union[SHOW_GRID, str]] = None,
filled: Optional[bool] = None,
levels: Optional[
Union[CONTOUR_LEVELS, str, int, List[float]]
] = None,
show_labels: Optional[bool] = None,
show_colorbars: Optional[bool] = None,
aspect_ratio: Optional[Union[ASPECT_RATIO, str]] = None,
scalex: Optional[Union[SCALE, str]] = None,
scaley: Optional[Union[SCALE, str]] = None,
subplots: Optional[bool] = None,
max_cols: Optional[int] = None,
sharex: Optional[bool] = None,
sharey: Optional[bool] = None,
style: Optional[
Union[
ContourStyleAttrs,
List[Optional[ContourStyleAttrs]],
]
] = None,
norm: Optional[Union[str, List[Optional[str]]]] = None,
vmin: Optional[
Union[float, List[Optional[float]]]
] = None,
vmax: Optional[
Union[float, List[Optional[float]]]
] = None,
valfmt: Optional[
Union[VALUE_FORMAT, str, List[Optional[str]]]
] = None,
xticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
xticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
xtickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
yticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
yticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
ytickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
vlines: Optional[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
List[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
None,
]
],
]
] = None,
hlines: Optional[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
List[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
None,
]
],
]
] = None,
colorbar: Optional[
Union[
HeatmapColorbarAttrs,
List[Optional[HeatmapColorbarAttrs]],
]
] = None,
texts: Optional[
Union[
TextAttrs,
List[TextAttrs],
List[Union[TextAttrs, List[TextAttrs], None]],
]
] = None
) -> plt.Figure
Creates the contour chart.
A contour chart draws a surface sampled on a grid — a loss landscape, a
2-D density, a terrain — as iso-lines of equal value, or as filled bands
between them. Use it to read the shape of a function of two variables:
where its minima and ridges sit and how steeply it changes. Lines overlay
on other charts and on each other; fills stand alone, with an optional
colorbar. For a per-cell view of a matrix use
Heatmap; for the raw points behind a density
use ScatterChart.
Added in 0.9.0
Examples:
>>> from datachart.charts import ContourChart
>>> figure = ContourChart(
... data={
... "x": [0, 1, 2],
... "y": [0, 1, 2],
... "z": [
... [0, 1, 4],
... [1, 2, 5],
... [4, 5, 8],
... ],
... },
... title="Basic Contour Chart",
... xlabel="X",
... ylabel="Y"
... )
| PARAMETER | DESCRIPTION |
|---|---|
data
|
The gridded surface(s): a dictionary with the 2-D
TYPE:
|
title
|
The title of the chart.
TYPE:
|
xlabel
|
The x-axis label.
TYPE:
|
ylabel
|
The y-axis label.
TYPE:
|
subtitle
|
The subtitle(s) for individual charts. Used as legend labels.
TYPE:
|
emphasis
|
The emphasis role(s) for individual line contours, aligned
like
TYPE:
|
figsize
|
The size of the figure.
TYPE:
|
xmin
|
The minimum x-axis value.
TYPE:
|
xmax
|
The maximum x-axis value.
TYPE:
|
ymin
|
The minimum y-axis value.
TYPE:
|
ymax
|
The maximum y-axis value.
TYPE:
|
show_legend
|
Whether to show the legend.
TYPE:
|
show_grid
|
Which grid lines to show (e.g., "both", "x", "y"). Off by default for filled contours.
TYPE:
|
filled
|
Whether to fill the bands between the levels (colored by the colormap) instead of drawing iso-lines (in the chart's color).
TYPE:
|
levels
|
Which levels cut the surface: a rule of
TYPE:
|
show_labels
|
Whether to write the level values along the iso-lines.
TYPE:
|
show_colorbars
|
Whether to show the colorbar(s) of filled contours.
TYPE:
|
aspect_ratio
|
The aspect ratio of the axes ("auto" or "equal"). See
TYPE:
|
scalex
|
The x-axis scale (e.g., "log", "linear").
TYPE:
|
scaley
|
The y-axis scale (e.g., "log", "linear").
TYPE:
|
subplots
|
Whether to create separate subplots for each chart.
TYPE:
|
max_cols
|
Maximum number of columns in subplots (when subplots=True).
TYPE:
|
sharex
|
Whether to share the x-axis in subplots.
TYPE:
|
sharey
|
Whether to share the y-axis in subplots.
TYPE:
|
style
|
Style configuration(s) for the contour chart(s).
TYPE:
|
norm
|
Value normalization method(s) of the colormap.
TYPE:
|
vmin
|
Minimum value(s) for normalization.
TYPE:
|
vmax
|
Maximum value(s) for normalization.
TYPE:
|
valfmt
|
Format string(s) for the inline level labels, with the value
named
TYPE:
|
xticks
|
Custom x-axis tick positions.
TYPE:
|
xticklabels
|
Custom x-axis tick labels.
TYPE:
|
xtickrotate
|
Rotation angle for x-axis tick labels.
TYPE:
|
yticks
|
Custom y-axis tick positions.
TYPE:
|
yticklabels
|
Custom y-axis tick labels.
TYPE:
|
ytickrotate
|
Rotation angle for y-axis tick labels.
TYPE:
|
vlines
|
Vertical line(s) to plot.
TYPE:
|
hlines
|
Horizontal line(s) to plot.
TYPE:
|
colorbar
|
Colorbar configuration(s).
TYPE:
|
texts
|
Text annotation(s) to draw.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
plt.Figure
|
The figure containing the contour chart. |
HexbinChart(
data: Union[HexbinDataAttrs, List[HexbinDataAttrs]],
*,
title: Optional[str] = None,
xlabel: Optional[str] = None,
ylabel: Optional[str] = None,
subtitle: Optional[
Union[str, List[Optional[str]]]
] = None,
emphasis: None = None,
figsize: Optional[
Union[FIG_SIZE, Tuple[float, float]]
] = None,
xmin: Optional[Union[int, float]] = None,
xmax: Optional[Union[int, float]] = None,
ymin: Optional[Union[int, float]] = None,
ymax: Optional[Union[int, float]] = None,
show_grid: Optional[Union[SHOW_GRID, str]] = None,
show_colorbars: bool = True,
aspect_ratio: Optional[Union[ASPECT_RATIO, str]] = None,
scalex: Optional[Union[SCALE, str]] = None,
scaley: Optional[Union[SCALE, str]] = None,
subplots: Optional[bool] = None,
max_cols: Optional[int] = None,
sharex: Optional[bool] = None,
sharey: Optional[bool] = None,
style: Optional[
Union[
HexbinStyleAttrs,
List[Optional[HexbinStyleAttrs]],
]
] = None,
gridsize: Optional[
Union[int, List[Optional[int]]]
] = None,
reduce: Optional[
Union[HEXBIN_REDUCE, str, List[Optional[str]]]
] = None,
mincnt: Optional[
Union[int, List[Optional[int]]]
] = None,
norm: Optional[Union[str, List[Optional[str]]]] = None,
vmin: Optional[
Union[float, List[Optional[float]]]
] = None,
vmax: Optional[
Union[float, List[Optional[float]]]
] = None,
valfmt: Optional[
Union[VALUE_FORMAT, str, List[Optional[str]]]
] = None,
xticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
xticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
xtickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
yticks: Optional[
Union[
List[Union[int, float]],
List[List[Union[int, float]]],
]
] = None,
yticklabels: Optional[
Union[List[str], List[List[str]]]
] = None,
ytickrotate: Optional[
Union[int, List[Optional[int]]]
] = None,
vlines: Optional[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
List[
Union[
VLinePlotAttrs,
List[VLinePlotAttrs],
None,
]
],
]
] = None,
hlines: Optional[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
List[
Union[
HLinePlotAttrs,
List[HLinePlotAttrs],
None,
]
],
]
] = None,
colorbar: Optional[
Union[
HeatmapColorbarAttrs,
List[Optional[HeatmapColorbarAttrs]],
]
] = None,
texts: Optional[
Union[
TextAttrs,
List[TextAttrs],
List[Union[TextAttrs, List[TextAttrs], None]],
]
] = None
) -> plt.Figure
Creates the hexbin chart.
A hexbin chart tiles the plane with hexagons and colors each by the number
of points falling in it — or, with a per-point c, by an aggregate of
those values. Use it where a scatter chart turns into an opaque blob:
thousands of points, overlapping clusters, or a value that varies across
the plane. For the points themselves use
ScatterChart; for a smooth density
estimate use ContourChart on
stats.kde2d.
Added in 0.9.0
Examples:
>>> from datachart.charts import HexbinChart
>>> figure = HexbinChart(
... data={
... "x": [0.1, 0.4, 0.5, 1.2, 1.3, 2.0],
... "y": [0.2, 0.3, 0.6, 1.1, 1.4, 2.1],
... },
... title="Basic Hexbin Chart",
... xlabel="X",
... ylabel="Y"
... )
| PARAMETER | DESCRIPTION |
|---|---|
data
|
The points to bin: a dictionary with the
TYPE:
|
title
|
The title of the chart.
TYPE:
|
xlabel
|
The x-axis label.
TYPE:
|
ylabel
|
The y-axis label.
TYPE:
|
subtitle
|
The subtitle(s) for individual charts.
TYPE:
|
emphasis
|
Not supported: a hexbin chart is a single colormapped layer
with no series to mute or highlight. Passing a value raises
TYPE:
|
figsize
|
The size of the figure.
TYPE:
|
xmin
|
The minimum x-axis value.
TYPE:
|
xmax
|
The maximum x-axis value.
TYPE:
|
ymin
|
The minimum y-axis value.
TYPE:
|
ymax
|
The maximum y-axis value.
TYPE:
|
show_grid
|
Which grid lines to show (e.g., "both", "x", "y"). Off by default: the hexagons cover it.
TYPE:
|
show_colorbars
|
Whether to show the colorbar(s).
TYPE:
|
aspect_ratio
|
The aspect ratio of the axes ("auto" or "equal"). See
TYPE:
|
scalex
|
The x-axis scale (e.g., "log", "linear").
TYPE:
|
scaley
|
The y-axis scale (e.g., "log", "linear").
TYPE:
|
subplots
|
Whether to create separate subplots for each chart.
TYPE:
|
max_cols
|
Maximum number of columns in subplots (when subplots=True).
TYPE:
|
sharex
|
Whether to share the x-axis in subplots.
TYPE:
|
sharey
|
Whether to share the y-axis in subplots.
TYPE:
|
style
|
Style configuration(s) for the hexbin chart(s).
TYPE:
|
gridsize
|
The number of hexagons across the x-axis; the
TYPE:
|
reduce
|
How the
TYPE:
|
mincnt
|
The point count below which a hexagon stays blank; every hexagon is drawn by default.
TYPE:
|
norm
|
Value normalization method(s) of the colormap;
TYPE:
|
vmin
|
Minimum value(s) for normalization.
TYPE:
|
vmax
|
Maximum value(s) for normalization.
TYPE:
|
valfmt
|
Format string(s) for the colorbar tick labels, with the value
named
TYPE:
|
xticks
|
Custom x-axis tick positions.
TYPE:
|
xticklabels
|
Custom x-axis tick labels.
TYPE:
|
xtickrotate
|
Rotation angle for x-axis tick labels.
TYPE:
|
yticks
|
Custom y-axis tick positions.
TYPE:
|
yticklabels
|
Custom y-axis tick labels.
TYPE:
|
ytickrotate
|
Rotation angle for y-axis tick labels.
TYPE:
|
vlines
|
Vertical line(s) to plot.
TYPE:
|
hlines
|
Horizontal line(s) to plot.
TYPE:
|
colorbar
|
Colorbar configuration(s).
TYPE:
|
texts
|
Text annotation(s) to draw.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
plt.Figure
|
The figure containing the hexbin chart. |
ParallelCoords(
data: Union[
List[ParallelCoordsDataPointAttrs],
List[List[ParallelCoordsDataPointAttrs]],
],
*,
title: Optional[str] = None,
xlabel: Optional[str] = None,
ylabel: Optional[str] = None,
subtitle: Optional[
Union[str, List[Optional[str]]]
] = None,
emphasis: Optional[
Union[EMPHASIS, str, List[Optional[str]]]
] = None,
figsize: Optional[
Union[FIG_SIZE, Tuple[float, float]]
] = None,
show_legend: Optional[bool] = None,
show_grid: Optional[Union[SHOW_GRID, str]] = None,
aspect_ratio: Optional[Union[ASPECT_RATIO, str]] = None,
style: Optional[
Union[
ParallelCoordsStyleAttrs,
List[Optional[ParallelCoordsStyleAttrs]],
]
] = None,
dimensions: Optional[List[str]] = None,
hue: Optional[Union[str, List[Optional[str]]]] = None,
category_orders: Optional[Dict[str, List[str]]] = None,
texts: Optional[
Union[
TextAttrs,
List[TextAttrs],
List[Union[TextAttrs, List[TextAttrs], None]],
]
] = None
) -> plt.Figure
Creates the parallel coordinates chart.
Parallel coordinates draw each record as a polyline across one vertical
axis per dimension. Use it to explore multivariate data: clusters show as
bundles of similar lines, and correlations between neighboring dimensions
show as parallel or crossing segments. Works best with a handful of
dimensions; color the records by group with hue to compare groups.
Added in v0.7.0
Examples:
>>> from datachart.charts import ParallelCoords
>>> figure = ParallelCoords(
... data=[
... {"sepal_length": 5.1, "sepal_width": 3.5, "petal_length": 1.4, "petal_width": 0.2, "species": "setosa"},
... {"sepal_length": 4.9, "sepal_width": 3.0, "petal_length": 1.4, "petal_width": 0.2, "species": "setosa"},
... {"sepal_length": 7.0, "sepal_width": 3.2, "petal_length": 4.7, "petal_width": 1.4, "species": "versicolor"},
... ],
... title="Iris Dataset",
... hue="species",
... dimensions=["sepal_length", "sepal_width", "petal_length", "petal_width"],
... show_legend=True
... )
| PARAMETER | DESCRIPTION |
|---|---|
data
|
The data points for the chart. Each data point is a dictionary where keys are dimension names and values are numeric or string values. Can optionally include a hue key for categorical coloring.
TYPE:
|
title
|
The title of the chart.
TYPE:
|
xlabel
|
The x-axis label.
TYPE:
|
ylabel
|
The y-axis label.
TYPE:
|
subtitle
|
The subtitle(s) for individual charts.
TYPE:
|
emphasis
|
The emphasis role(s), aligned with the data rows (a single value applies to every row): "background" mutes a row (theme muted color, lowered alpha, thinner line, behind the others, no hue legend entry), "highlight" bolds it and brings it to the front among the data rows, None leaves it unchanged.
TYPE:
|
figsize
|
The size of the figure.
TYPE:
|
show_legend
|
Whether to show the legend (for hue categories).
TYPE:
|
show_grid
|
Which grid lines to show (e.g., "both", "x", "y").
TYPE:
|
aspect_ratio
|
The aspect ratio of the axes ("auto" or "equal"). See
TYPE:
|
style
|
Style configuration(s) for the lines.
TYPE:
|
dimensions
|
List of dimension names to include and their order. If None, all columns (except hue) are auto-detected.
TYPE:
|
hue
|
The key name in data for line coloring. String values color
categorically: data points with the same hue value get the same
color from
TYPE:
|
category_orders
|
Dictionary mapping dimension names to lists of category values in the desired order. Example: {"rating": ["Low", "Medium", "High"]}. Categories not in the list will be appended at the end (sorted).
TYPE:
|
texts
|
Text annotation(s) to draw.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
plt.Figure
|
The figure containing the parallel coordinates chart. |
Flows
SankeyChart(
data: Union[
SankeySingleChartAttrs, List[SankeySingleChartAttrs]
],
*,
nodes: Optional[List[List[str]]] = None,
column_labels: Optional[List[str]] = None,
show_values: Optional[bool] = None,
value_format: Optional[Union[VALUE_FORMAT, str]] = None,
title: Optional[str] = None,
subtitle: Optional[
Union[str, List[Optional[str]]]
] = None,
emphasis: None = None,
figsize: Optional[
Union[FIG_SIZE, Tuple[float, float]]
] = None,
subplots: Optional[bool] = None,
max_cols: Optional[int] = None,
style: Optional[
Union[
SankeyStyleAttrs,
List[Optional[SankeyStyleAttrs]],
]
] = None,
texts: Optional[
Union[
TextAttrs,
List[TextAttrs],
List[Union[TextAttrs, List[TextAttrs], None]],
]
] = None
) -> plt.Figure
Creates the Sankey chart.
A Sankey diagram draws weighted flows between categories: nodes are bars
laid out in columns and each flow is a ribbon whose height carries its
value — label transitions between annotators, attrition through a signup
funnel, energy from source to use. Use it when the question is where a
quantity goes; for the totals per category alone use
BarChart.
Added in 0.9.0
Examples:
>>> from datachart.charts import SankeyChart
>>> figure = SankeyChart(
... data={
... "links": [
... {"source": "Visited", "target": "Signed up", "value": 300},
... {"source": "Visited", "target": "Bounced", "value": 700},
... {"source": "Signed up", "target": "Paid", "value": 90},
... {"source": "Signed up", "target": "Churned", "value": 210},
... ]
... },
... title="Signup funnel",
... )
| PARAMETER | DESCRIPTION |
|---|---|
data
|
The chart data: a
TYPE:
|
nodes
|
The node columns, left to right, each a list of node names top to bottom. Must name every node in the links exactly once. When omitted, a node's column is its longest path from any source and nodes keep their first-seen order within a column.
TYPE:
|
column_labels
|
One heading per column, drawn above it; must match the number of columns.
TYPE:
|
show_values
|
Whether to write each flow's value on its ribbon.
TYPE:
|
value_format
|
The format of the ribbon values: a
TYPE:
|
title
|
The title of the chart.
TYPE:
|
subtitle
|
The subtitle(s) for individual charts.
TYPE:
|
emphasis
|
Not supported: a Sankey has no series to mute or
highlight. Passing a value raises
TYPE:
|
figsize
|
The size of the figure.
TYPE:
|
subplots
|
Whether to show each chart in its own subplot; several charts always split into subplots.
TYPE:
|
max_cols
|
Maximum number of columns in subplots.
TYPE:
|
style
|
Style configuration(s) for the chart(s).
TYPE:
|
texts
|
Text annotation(s) to draw. The columns span 0–1 horizontally and the tallest column 0–1 vertically.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
plt.Figure
|
The figure containing the Sankey chart. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If |