Charts API¶

This is the complete API reference for all chart types in charted.

Base Chart Class¶

class charted.Chart(*args, **kwargs)[source]¶

Bases: ChartScaleMixin, ChartValueLabelMixin, ChartReferenceLayerMixin, ChartIntrospectionMixin, ChartPatternMixin, ChartConfigMixin, ChartTooltipMixin, ChartOutputMixin, SeriesLegend, Svg

Base class for all SVG chart types.

Provides common functionality for chart rendering including theme application, data validation, coordinate calculations, and SVG generation. All chart types inherit from this class.

This class has been refactored to focus on core responsibilities: - Data representation and state management - Coordinate system setup - Delegating utilities to focused modules

Parameters:

width (float)
height (float)
zero_index (bool)
x_data (Vector | Vector2D | None)
y_data (Vector | Vector2D | None)
series_styles (list[SeriesStyleConfig] | None)
x_labels (Labels | None)
y_labels (Labels | None)
series_names (list[str] | None)
x_stacked (bool)
title (str | None)
subtitle (str | None)
subtitle_leading (float)
theme (Theme)
chart_type (str | None)
x_label (str | None)
y_label (str | None)
data_labels (list[str] | list[list[str]] | None)
h_lines (list[float] | None)
v_lines (list[float] | None)
annotations (list[_Annotation] | None)
x_scale (object | None)
y_scale (object | None)
reference_lines (list[ReferenceLineDict] | None)
colors (list[str] | None)
x_range (tuple[float, float] | None)
y_range (tuple[float, float] | None)
domain_padding (float | None)
value_labels (bool | str | dict[str, object] | None)
legend (str)
category_label_max_width (float | None)
category_patterns (list[str] | bool | None)

x_stacked¶

If True, stack series along x-axis

Type:: bool

y_stacked¶

If True, stack series along y-axis

Type:: bool

render_axes¶

Whether to draw axes and grid lines

Type:: bool

theme¶

Applied theme configuration

Type:: charted.themes.core.Theme

colors¶: Auto-generated color palette for series

Example

>>> from charted.charts.chart import Chart
>>> # Use concrete subclasses instead:
>>> from charted import BarChart, LineChart, PieChart

The base Chart class provides a unified interface for creating any chart type dynamically.

y_stacked: bool = False¶

render_axes: bool = True¶

pad_x_labels: bool = True¶

style(**kwargs)[source]¶

Fluently apply theme overrides.

Parameters:: **kwargs (object) – Theme attribute overrides (e.g. background_color=’#fff’, font_family=’sans-serif’, legend_font_size=12).
Returns:: self for chaining.
Return type:: Chart

Example

>>> chart = BarChart(...).style(background_color='#fff', font_size=13)

x_stacked: bool = False¶

theme: Theme¶

property x_scale: str¶: Name of the x-axis scale (‘linear’, ‘log’, or ‘time’).

property y_scale: str¶: Name of the y-axis scale (‘linear’, ‘log’, or ‘time’).

property x_data: list[list[float]]¶: Get x-axis data from DataModel (read-only).

property y_data: list[list[float]]¶: Get y-axis data from DataModel (read-only).

property width: float¶: Chart width (read-only).

property height: float¶: Chart height (read-only).

property h_padding: float¶: Horizontal padding fraction (read-only).

property v_padding: float¶: Vertical padding fraction (read-only).

property plot_width: float¶: Get plot area width from LayoutEngine.

property plot_height: float¶: Get plot area height from LayoutEngine.

get_base_transform()[source]¶

Get base transformation from LayoutEngine.

Return type:: list[str]

property x_offset: float¶

Calculate x-offset for charts with x_labels.

Ordinal charts (no explicit x_data): shift by one tick width so data points sit at the centre of their column. XY charts (explicit x_data provided): positions are already correct from reproject; offset is 0.

property left_padding: float¶: Get left padding from LayoutEngine.

property right_padding: float¶: Get right padding from LayoutEngine.

property top_padding: float¶: Get top padding from LayoutEngine.

property bottom_padding: float¶: Get bottom padding from LayoutEngine.

property x_label_rotation: tuple[float, float] | None¶: Get x-label rotation from LayoutEngine.

property colors: list[str]¶: Get color palette with automatic cycling (read-only).

property title: Text | None¶

property subtitle_element: Text | None¶: Render subtitle as smaller text below the title.

property v_pad: float¶

property h_pad: float¶

property container: Path¶: Create chart background rectangle using theme background color.

property x_labels: list[MeasuredText] | None¶: Get x-axis labels from DataModel (read-only).

property y_labels: list[MeasuredText] | None¶: Get y-axis labels from DataModel (read-only).

property x_count: int¶: Get x-axis count from DataModel (read-only).

property y_count: int¶: Get y-axis count from DataModel (read-only).

property y_offsets: list[list[float]]¶: Get y-offsets (read-only).

property x_offsets: list[list[float]] | None¶: Get x-offsets (read-only).

property x_width: float¶: Get width per x-label.

property y_values: list[list[float]]¶: Get y-values (read-only).

property x_values: list[list[float]]¶: Get x-values (read-only).

property zero_line: Path | None¶: Create zero line for charts with negative values.

property representation: G¶: Subclass must implement this.

property svg: str¶

Get SVG string representation of the chart.

Returns:: SVG string with all chart elements rendered.

Column Chart¶

class charted.ColumnChart(*args, **kwargs)[source]¶

Bases: Chart

Vertical column chart for comparing categorical data.

Displays data as vertical columns where the height of each column represents the value. Supports single and multi-series data, with optional stacking and side-by-side layouts.

Parameters:

data (Vector | Vector2D) – Single series (list of values) or multi-series (list of lists)
labels (Labels | None) – Category labels for the x-axis
column_gap (float | None) – Gap between columns as ratio of column width (default 0.2)
width (float) – Chart dimensions in pixels
height (float) – Chart dimensions in pixels
zero_index (bool) – Whether to include zero on the y-axis
title (str | None) – Optional chart title
theme (Theme | None) – Optional theme configuration
series_names (list[str] | None) – Names for each series (shown in legend)
y_stacked (bool) – If True, stack columns vertically instead of side-by-side
series_styles (list[SeriesStyleConfig] | None) – Per-series style overrides
subtitle (str | None)
subtitle_leading (float)
data_labels (list[str] | list[list[str]] | None)
x_label (str | None)
y_label (str | None)
h_lines (list[float] | None)
v_lines (list[float] | None)
annotations (list[_Annotation] | None)
x_scale (object | None)
y_scale (object | None)
reference_lines (list[ReferenceLineDict] | None)
colors (list[str] | None)
value_labels (bool | str | dict[str, object] | None)
legend (str)
category_patterns (list[str] | bool | None)
domain_padding (float | None)

Example

>>> from charted import ColumnChart
>>> chart = ColumnChart(data=[120, 180, 210], labels=['Q1', 'Q2', 'Q3'])
>>> chart.save('sales.svg')

Vertical bar chart with support for multi-series, stacked layouts, and side-by-side grouping.

Key Parameters:

data: List of lists for multi-series, or single list for one series
labels: X-axis labels
series_names: Names for each data series (used in legend)
y_stacked: If True, stack bars vertically (default for multi-series)
theme: Theme dictionary or theme name string

Example:

from charted import ColumnChart

chart = ColumnChart(
    data=[[120, 180, 210], [80, 95, 110]],
    labels=["Q1", "Q2", "Q3"],
    series_names=["Revenue", "Expenses"],
    title="Quarterly Performance"
)
chart.save("column.svg")

y_stacked: bool = True¶

property x_width: float¶: Get width per x-label.

property representation: G¶: Subclass must implement this.

Bar Chart¶

class charted.BarChart(*args, **kwargs)[source]¶

Bases: Chart

Horizontal bar chart for comparing categorical data.

Displays data as horizontal bars where the length of each bar represents the value. Supports single and multi-series data, with optional stacking and side-by-side layouts.

Parameters:

data (Vector | Vector2D) – Single series (list of values) or multi-series (list of lists)
labels (Labels | None) – Category labels for the y-axis
bar_gap (float | None) – Gap between bars as ratio of bar height (default from config)
width (float) – Chart dimensions in pixels
height (float) – Chart dimensions in pixels
zero_index (bool) – Whether to include zero on the x-axis
title (str | None) – Optional chart title
theme (Theme | None) – Optional theme configuration
series_names (list[str] | None) – Names for each series (shown in legend)
series_styles (list[SeriesStyleConfig] | None) – Per-series style overrides
x_stacked (bool) – If True, stack bars horizontally instead of side-by-side
category_label_max_width (float | None) – Max pixel width for a category label before it wraps onto multiple lines. None (default) keeps the full label on a single line and grows the left gutter to fit it. Set this to wrap long names (no truncation) and keep the plot area wide.
subtitle (str | None)
subtitle_leading (float)
data_labels (list[str] | list[list[str]] | None)
x_label (str | None)
y_label (str | None)
h_lines (list[float] | None)
v_lines (list[float] | None)
annotations (list[_Annotation] | None)
reference_lines (list[ReferenceLineDict] | None)
colors (list[str] | None)
value_labels (bool | str | dict[str, object] | None)
legend (str)
category_patterns (list[str] | bool | None)
domain_padding (float | None)

Example

>>> from charted import BarChart
>>> chart = BarChart(data=[120, 180, 210], labels=['Q1', 'Q2', 'Q3'])
>>> chart.save('sales.svg')

Horizontal bar chart with support for single/multi-series and various layouts.

Key Parameters:

data: Single list or list of lists for multi-series
labels: Y-axis labels
x_stacked: If True, stack bars horizontally
theme: Theme dictionary or theme name string

Example:

from charted import BarChart

chart = BarChart(
    data=[120, 180, 210],
    labels=["Q1", "Q2", "Q3"],
    title="Sales by Quarter"
)
chart.save("bar.svg")

property y_height: float¶

get_base_transform()[source]¶

Get base transformation from LayoutEngine.

Return type:: list[str]

property representation: G¶: Subclass must implement this.

Line Chart¶

class charted.LineChart(*args, **kwargs)[source]¶

Bases: Chart

Line chart for displaying trends over continuous data.

Connects data points with straight lines to show changes across categories or time. Supports multi-series data with optional area fills, markers, and custom styling.

Parameters:

data (Vector | Vector2D) – Single series (list of values) or multi-series (list of lists)
x_data (Vector | Vector2D | None) – Optional x-axis values (defaults to indices 0, 1, 2, …)
labels (Labels | None) – Optional x-axis labels
width (float) – Chart dimensions in pixels
height (float) – Chart dimensions in pixels
zero_index (bool) – Whether to include zero in the data range
title (str | None) – Optional chart title
theme (Theme | None) – Optional theme configuration
series_names (list[str] | None) – Names for each series (shown in legend)
series_styles (list[SeriesStyleConfig] | None) – Per-series style overrides (stroke, marker_shape, etc.)
subtitle (str | None)
subtitle_leading (float)
markers (bool)
data_labels (list[str] | list[list[str]] | None)
x_label (str | None)
y_label (str | None)
h_lines (list[float] | None)
v_lines (list[float] | None)
annotations (list[_Annotation] | None)
curve (str)
x_scale (object | None)
y_scale (object | None)
reference_lines (list[ReferenceLineDict] | None)
colors (list[str] | None)
legend (str)
dash_cycle (list[str] | bool | None)

Example

>>> from charted import LineChart
>>> # Basic line chart
>>> chart = LineChart(
...     data=[10, 25, 18, 32],
...     labels=['Jan', 'Feb', 'Mar', 'Apr']
... )
>>> chart.save('trends.svg')
>>>
>>> # Multi-series with area fill
>>> chart = LineChart(
...     data=[[10, 25, 18], [15, 20, 28]],
...     labels=['2023', '2024'],
...     series_styles=[{'area_fill': True, 'area_fill_opacity': 0.2}]
... )

Line chart with support for multi-series and XY mode.

Key Parameters:

data: List of lists for multi-series
labels: X-axis labels (or x_data for XY mode)
x_data: Custom X-axis values for XY mode
theme: Theme dictionary or theme name string

Example:

from charted import LineChart

chart = LineChart(
    data=[[120, 180, 210], [80, 95, 110]],
    labels=["Q1", "Q2", "Q3"],
    series_names=["Revenue", "Expenses"],
    title="Trend Line"
)
chart.save("line.svg")

pad_x_labels: bool = False¶

DEFAULT_DASH_CYCLE = ['none', '6,4', '2,3', '8,3,2,3', '1,3']¶

markers: bool = False¶

curve: str = 'linear'¶

property x_offset: float¶: Line charts use direct x positions, no label-padding offset.

property representation: G¶: Generate line chart SVG elements using LineRenderer.

Scatter Chart¶

class charted.ScatterChart(*args, **kwargs)[source]¶

Bases: Chart

Scatter plot for displaying relationships between two variables.

Plots individual data points at (x, y) coordinates to show correlations, clusters, or distributions. Supports multi-series data with custom marker shapes and sizes.

Parameters:

data – Single series (list of y-values with x=indices) or multi-series (list of lists) or list of (x, y) tuples
x_data (Vector | Vector2D) – Optional x-coordinates for each point
labels – Optional series names
width (float) – Chart dimensions in pixels
height (float) – Chart dimensions in pixels
zero_index – Whether to include zero in both axes
title (str | None) – Optional chart title
theme (Theme | None) – Optional theme configuration
series_names (list[str] | None) – Names for each series (shown in legend)
series_styles (list[SeriesStyleConfig] | None) – Per-series style overrides (marker_shape, marker_size)
point_styles (list[list[PointStyleConfig | None]] | None) – Per-POINT marker overrides, a list of per-series rows mirroring the data shape. Each entry is a PointStyleConfig (marker_shape, marker_size, fill, opacity) or None. Any present field wins over the series-level/shape-cycle resolution; omitted fields fall through. Defaults to None, leaving every point styled by its series (existing behaviour). Data-label colour now comes from the theme’s data_label_color token (override via Theme(data_label_color=...)); the default token reproduces the previous axis-title colour.
x_range (tuple[float, float] | None) – Optional (min, max) to fix the x-axis domain instead of deriving it from the data, removing the need for invisible anchor points to control the visible range.
y_range (tuple[float, float] | None) – Optional (min, max) to fix the y-axis domain.
domain_padding (float | None) – Optional fraction (e.g. 0.1) padding the data-derived domain by that amount on each side. Ignored on an axis with an explicit range. Defaults to None (no padding).
quadrant_label_inset (float) – Extra padding (px) used to inset the four quadrant labels from the plot corners so they clear the axis tick numbers instead of sitting flush. Defaults to 12.0; pass 0 to restore the original flush-corner placement.
quadrant_label_backplate (bool) – When True, draws a semi-opaque rounded background plate behind each quadrant label for contrast. Defaults to False.
shape_cycle (list[str] | bool | None) – Redundant shape encoding for multi-series scatters so series differ by marker SHAPE as well as colour. Defaults to None (every series uses circles, preserving existing behaviour). Pass True to enable the built-in cycle (circle, square, triangle, diamond, star), or a custom list of shape names to cycle through. A per-series marker_shape in series_styles always wins over the cycle.
legend (str) – Placement for a series legend that maps each series_names entry to its marker shape and colour swatch. One of 'none' (default, no legend), 'right', 'bottom', or 'top'. When shown, layout space is reserved on that side so the legend never overlaps the plot. Requires series_names; with no names there is nothing to label and the layout is left unchanged.
avoid_label_collisions (bool) – When True, run a collision-avoidance pass over the data labels so they overlap each other (and their markers) as little as possible, drawing a thin leader line back to a point whenever its label is pushed noticeably away. Defaults to False, which keeps the original fixed-offset label placement so existing renders are unchanged. See _render_data_labels for the algorithm and its limitations.
y_data (Vector | Vector2D)
subtitle (str | None)
subtitle_leading (float)
data_labels (list[str] | list[list[str]] | None)
x_label (str | None)
y_label (str | None)
h_lines (list[float] | None)
v_lines (list[float] | None)
annotations (list[_Annotation] | None)
quadrant_labels (list[str] | None)
x_scale (object | None)
y_scale (object | None)
reference_lines (list[ReferenceLineDict] | None)
colors (list[str] | None)
value_labels (bool | str | dict[str, object] | None)

Example

>>> from charted import ScatterChart
>>> # Basic scatter plot
>>> chart = ScatterChart(data=[5, 8, 12, 15], x_data=[1, 2, 3, 4])
>>> chart.save('correlation.svg')
>>>
>>> # Multi-series with custom markers
>>> chart = ScatterChart(
...     data=[[5, 8, 12], [7, 10, 14]],
...     x_data=[1, 2, 3],
...     series_styles=[{'marker_shape': 'circle'}, {'marker_shape': 'square'}]
... )

Scatter plot with marker customization.

Key Parameters:

data: List of [x, y] pairs or list of lists for multi-series
labels: Series names
marker_shape: “circle”, “square”, or “diamond”
theme: Theme dictionary or theme name string

Example:

from charted import ScatterChart

chart = ScatterChart(
    data=[[1, 2], [2, 3], [3, 5], [4, 4]],
    labels=["Series 1"],
    marker_shape="square",
    title="Scatter Plot"
)
chart.save("scatter.svg")

DEFAULT_SHAPE_CYCLE = ['circle', 'square', 'triangle', 'diamond', 'star']¶

property representation: G¶: Subclass must implement this.

Pie Chart¶

class charted.PieChart(*args, **kwargs)[source]¶

Bases: Chart

Pie chart for displaying categorical data as proportional slices.

Renders data as a circular chart divided into slices where each slice’s arc length (and area) is proportional to its value. Supports doughnut mode, slice explosion, and custom labeling.

Parameters:

data (Vector) – Values for each slice (must be non-negative, sum > 0)
labels (Labels | None) – Optional labels for each slice
width (float) – Chart dimensions in pixels (default 700x500 for better legend layout)
height (float) – Chart dimensions in pixels (default 700x500 for better legend layout)
title (str | None) – Optional chart title
theme (Theme | None) – Optional theme configuration
inner_radius (float) – Ratio (0.0-1.0) for doughnut hole; 0 = regular pie
explode (float | Vector) – Single value or list to offset slices from center (pixels)
start_angle (float) – Starting angle in degrees (0 = top, clockwise)
series_styles (list[SeriesStyleConfig] | None) – Optional per-slice styling overrides
show_percentages (bool) – If True, show percentage values on each slice
value_labels (bool | str | dict[str, object] | None)
legend (str)
category_patterns (list[str] | bool | None)

Example

>>> from charted import PieChart
>>> # Basic pie chart
>>> chart = PieChart(
...     data=[25, 35, 40],
...     labels=['Product A', 'Product B', 'Product C']
... )
>>> chart.save('market_share.svg')

Pie chart with doughnut mode and per-slice styling.

Key Parameters:

data: Single list of values
labels: Slice labels
series_names: Legend name

inner_radius: Inner radius for doughnut mode (0.3-0.7, 0 = regular pie)

slice_styles: Per-slice customization (colors, explosion, labels)

Example:

from charted import PieChart

chart = PieChart(
    data=[300, 150, 100, 50],
    labels=["Product A", "Product B", "Product C", "Product D"],
    series_names=["Sales"],
    title="Market Share"
)
chart.save("pie.svg")

Doughnut Mode:

chart = PieChart(
    data=[300, 150, 100],
    labels=["A", "B", "C"],
    inner_radius=0.5
)

Per-Slice Styling:

chart = PieChart(
    data=[300, 150, 100],
    labels=["A", "B", "C"],
    slice_styles={
        0: {"color": "#FF6B6B", "explode": 0.1},
        1: {"color": "#4ECDC4"},
        2: {"color": "#45B7D1", "label_position": "outside"}
    }
)

render_axes = False¶

__init__(data, labels=None, width=700, height=500, title=None, theme=None, inner_radius=0, explode=0, start_angle=0, series_styles=None, show_percentages=False, value_labels=None, legend='none', category_patterns=None)[source]¶

Initialize pie chart.

Parameters:

data (list[float]) – Values for each slice (must be non-negative, sum > 0)
labels (list[str] | None) – Optional labels for each slice
width (float) – Chart dimensions in pixels (default 700x500)
height (float) – Chart dimensions in pixels (default 700x500)
title (str | None) – Optional chart title
theme (Theme | None) – Optional theme configuration
inner_radius (float) – Ratio (0.0-1.0) for doughnut hole; 0 = regular pie
explode (float | list[float]) – Single value or list to offset slices from center (pixels)
start_angle (float) – Starting angle in degrees (0 = top, clockwise)
series_styles (list[SeriesStyleConfig] | None) – Optional per-slice styling overrides
show_percentages (bool) – If True, show percentage values on each slice
value_labels (bool | str | dict[str, object] | None)
legend (str)
category_patterns (list[str] | bool | None)

property colors: list[str]¶

Get generated color palette (read-only).

Colors are generated from data length in __init__ and cannot be modified. Use series_styles for per-slice color overrides.

property representation: G¶: Render the pie chart.

Radar Chart¶

class charted.RadarChart(*args, **kwargs)[source]¶

Bases: Chart

Radar chart (spider chart) for displaying multivariate data.

Renders data on a two-dimensional chart in the form of a polygon with vertices on axes radiating from a central point. Each axis represents a variable, with concentric grid lines showing scale. Supports multi-series data with customizable axis count and labels.

Parameters:

data (Vector | Vector2D) – Single series (list of values) or multi-series (list of lists)
labels (Labels) – Labels for each axis (one per data point in series)
width (float) – Chart dimensions in pixels
height (float) – Chart dimensions in pixels
title (str | None) – Optional chart title
theme (Theme | None) – Optional theme configuration
series_names (list[str] | None) – Names for each series (shown in legend)
series_styles (list[SeriesStyleConfig] | None) – Per-series style overrides (stroke, fill, etc.)
radius (float) – Chart radius as ratio of min(width, height) (default 0.75)
axis_count (int | None) – Number of axes (defaults to len(labels))
grid_levels (int) – Number of concentric grid circles (default 5)
show_axis_labels (bool) – Whether to display axis labels (default True)
label_offset (float) – Distance from grid edge for labels (default 20)
show_radial_labels (bool) – Whether to label radial rings with their numeric scale value (default True)

Example

>>> from charted import RadarChart
>>> # Basic radar chart
>>> chart = RadarChart(
...     data=[20, 35, 30, 45, 25],
...     labels=['Speed', 'Power', 'Endurance', 'Defense', 'Skill']
... )
>>> chart.save('character_stats.svg')
>>>
>>> # Multi-series comparison
>>> chart = RadarChart(
...     data=[[20, 35, 30, 45, 25], [30, 25, 40, 35, 30]],
...     labels=['Speed', 'Power', 'Endurance', 'Defense', 'Skill'],
...     series_names=['Player A', 'Player B']
... )

Radar (spider) chart for multi-axis comparison with support for multi-series data.

Key Parameters:

data: List of lists for multi-series, each inner list has one value per axis
labels: Axis labels (one per data point)
series_names: Names for each data series (used in legend)
theme: Theme dictionary or theme name string

Example:

from charted import RadarChart

chart = RadarChart(
    data=[
        [85, 90, 75, 88, 92],  # Player A
        [70, 85, 90, 75, 80],  # Player B
    ],
    labels=["Speed", "Strength", "Defense", "Technique", "Stamina"],
    series_names=["Player A", "Player B"],
    title="Player Skill Comparison"
)
chart.save("radar.svg")

render_axes = False¶

__init__(data, labels, width=500, height=500, title=None, theme=None, series_names=None, series_styles=None, radius=0.75, axis_count=None, grid_levels=5, show_axis_labels=True, label_offset=20, show_radial_labels=True)[source]¶

Initialize radar chart.

Parameters:

data (list[float] | list[list[float]]) – Single series (list of values) or multi-series (list of lists)
labels (list[str]) – Labels for each axis (one per data point in series)
width (float) – Chart dimensions in pixels
height (float) – Chart dimensions in pixels
title (str | None) – Optional chart title
theme (Theme | None) – Optional theme configuration
series_names (list[str] | None) – Names for each series (shown in legend)
series_styles (list[SeriesStyleConfig] | None) – Per-series style overrides (stroke, fill, etc.)
radius (float) – Chart radius as ratio of min(width, height) (default 0.75)
axis_count (int | None) – Number of axes (defaults to len(labels))
grid_levels (int) – Number of concentric grid circles (default 5)
show_axis_labels (bool) – Whether to display axis labels (default True)
label_offset (float) – Distance from grid edge for labels (default 20)
show_radial_labels (bool)

property colors: list[str]¶: Get color palette with automatic cycling (read-only).

get_base_transform()[source]¶

Radar charts use polar coordinates: no base transform needed.

Return type:: list[str]

property representation: G¶: Generate radar chart SVG elements using RadarRenderer.

Common Methods¶

All chart types share these methods:

to_svg()¶: Generate the SVG string representation of the chart.

save(filepath)¶: Save the chart to a file. Supports .svg extension.

to_markdown(path=None)¶: Generate markdown embedding. If path is provided, uses image reference. Otherwise returns inline data URL.

_repr_html_()¶: IPython/Jupyter integration: returns HTML with inline SVG.

Data Loading API¶

charted.load_csv(path, x_col, y_col, delimiter=None)[source]¶

Load data from a CSV file.

Convenience wrapper around load_data for CSV files.

Parameters:

path (str | Path) – Path to the CSV file.
x_col (str) – Column name for x-axis.
y_col (str) – Column name for y-axis.
delimiter (str | None) – Field delimiter (comma by default, tab for .tsv).

Returns:

Tuple of (x_data, y_data, labels).

Return type:

tuple[list[str], list[float], list[str]]

Example

>>> x, y, labels = load_csv("sales.csv", x_col="Quarter", y_col="Revenue")

Load data from a CSV file.

Parameters:

filepath: Path to CSV file
x_col: Column name for X-axis/labels
y_cols: Column name(s) for Y-axis data
delimiter: CSV delimiter (default: “,”)

Returns: Tuple of (x_values, y_values, column_names)

charted.load_json(path)[source]¶

Load data from a JSON file.

Convenience wrapper around load_data for JSON files.

Parameters:: path (str | Path) – Path to the JSON file.
Returns:: Tuple of (x_data, y_data, labels).
Return type:: tuple[list[str], list[float], list[str]]

Example

>>> x, y, labels = load_json("sales.json")

Load data from a JSON file. Auto-detects format based on JSON structure.

Parameters:

filepath: Path to JSON file

Returns: Tuple of (x_values, y_values, column_names)

Supported JSON Formats:

// Simple array
[120, 180, 210]

// Array of objects
[{"label": "Q1", "value": 120}, {"label": "Q2", "value": 180}]

// Object with data and labels
{"data": [120, 180, 210], "labels": ["Q1", "Q2", "Q3"], "title": "Sales"}

CLI API¶

charted includes a command-line interface for generating charts without writing Python code.

# Create a single chart
python -m charted create <chart_type> <output.svg> --data <input.csv|json>

# Batch process
python -m charted batch <input_dir> <output_dir>

Theme API¶

charted.get_theme(name)[source]¶

Get a theme by name.

Parameters:: name (str) – Theme name (preset or registered).
Returns:: Theme instance.
Raises:: ValueError – If theme is not found.
Return type:: Theme

Get a built-in theme by name or return a custom theme dictionary.

Parameters:

theme_name: Theme name string or theme dictionary

Returns: Theme dictionary with chart styling

Built-in themes: "dark", "light", "high-contrast", "blue", "green", "purple", "orange", "red", "pastel", "vibrant".