Charts¶

The utkit.visualize.charts module provides chart creation utilities powered by Matplotlib. It supports bar charts and line charts with customizable styling, saved as high-resolution PNG images.

Installation¶

matplotlib is part of the optional vishualize extras. Install utkit with the vishualize extra:

pip install "utkit[vishualize]"

Or with uv:

uv add "utkit[vishualize]"

Bar chart¶

Create a bar chart with create_bar_chart.

from utkit.visualize.charts import create_bar_chart

months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
sales = [120, 145, 138, 172, 185, 210]

create_bar_chart(
    x=months,
    y=sales,
    output_path="monthly_sales.png",
    title="Monthly Sales",
    xlabel="Month",
    ylabel="Sales",
    color="steelblue",
    edgecolor="black",
    width=0.6,
    dpi=300,
    grid=True,
)

Parameters¶

Parameter	Type	Default	Description
`x`	`list[str \\| int \\| float]`	—	X-axis labels.
`y`	`list[int \\| float]`	—	Bar values.
`output_path`	`str \\| Path`	—	PNG output path.
`title`	`str`	`"Bar Chart"`	Chart title.
`xlabel`	`str`	`""`	X-axis label.
`ylabel`	`str`	`""`	Y-axis label.
`figsize`	`tuple[int, int]`	`(10, 5)`	Figure size in inches.
`dpi`	`int`	`300`	Image resolution.
`color`	`str`	`"steelblue"`	Bar fill color.
`edgecolor`	`str`	`"black"`	Bar border color.
`width`	`float`	`0.6`	Bar width.
`grid`	`bool`	`True`	Show horizontal grid lines.
`show`	`bool`	`False`	Display the chart interactively.

Returns¶

Path — The resolved path to the saved PNG file.

Raises¶

ValueError — If x and y have different lengths or are empty.

Pie chart¶

Create a pie chart with create_pie_chart.

from utkit.visualize.charts import create_pie_chart

create_pie_chart(
    labels=["Python", "Java", "C++", "JavaScript"],
    values=[45, 25, 15, 15],
    output_path="charts/pie_chart.png",
    title="Programming Language Usage",
    explode=[0, 0, 0, 0],
    colors=["#4C72B0", "#55A868", "#C44E52", "#8172B3"],
)

Parameters¶

Parameter	Type	Default	Description
`labels`	`list`	—	Labels for each slice.
`values`	`list`	—	Values for each slice.
`output_path`	`str \\| Path`	—	PNG output path.
`title`	`str`	`"Pie Chart"`	Chart title.
`figsize`	`tuple[int, int]`	`(8, 8)`	Figure size in inches.
`dpi`	`int`	`300`	Image resolution.
`colors`	`list[str] \\| None`	`None`	Slice colors.
`explode`	`list[float] \\| None`	`None`	Offset each slice from the center.
`autopct`	`str`	`"%1.1f%%"`	Percentage label format.
`startangle`	`int`	`90`	Starting angle of the pie.
`shadow`	`bool`	`False`	Whether to draw a shadow.
`counterclock`	`bool`	`True`	Draw slices counterclockwise.
`wedgeprops`	`dict \\| None`	`None`	Properties for wedge styling.
`textprops`	`dict \\| None`	`None`	Properties for text styling.
`show`	`bool`	`False`	Display the chart interactively.

Returns¶

Path — The resolved path to the saved PNG file.

Raises¶

ValueError — If labels and values have different lengths or are empty.
ValueError — If any value is negative.
ValueError — If the sum of values is zero.
ValueError — If explode length doesn't match values length.

Line chart¶

Create a line chart with create_line_chart.

from utkit.visualize.charts import create_line_chart

months = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul"]
sales = [120, 145, 138, 172, 185, 210, 345]

create_line_chart(
    x=months,
    y=sales,
    output_path="monthly_trend.png",
    title="Monthly Sales Trend",
    xlabel="Month",
    ylabel="Sales",
    marker="o",
    linewidth=2.0,
    dpi=300,
    grid=True,
)

Parameters¶

Parameter	Type	Default	Description
`x`	`list[int \\| float]`	—	X-axis values.
`y`	`list[int \\| float]`	—	Y-axis values.
`output_path`	`str \\| Path`	—	Path to save the PNG.
`title`	`str`	`"Line Chart"`	Chart title.
`xlabel`	`str`	`""`	X-axis label.
`ylabel`	`str`	`""`	Y-axis label.
`figsize`	`tuple[int, int]`	`(10, 5)`	Figure size in inches.
`dpi`	`int`	`300`	Image resolution.
`marker`	`str`	`"o"`	Marker style.
`linewidth`	`float`	`2.0`	Line width.
`grid`	`bool`	`True`	Show grid.
`show`	`bool`	`False`	Display the chart interactively.

Returns¶

Path — The resolved path to the saved PNG file.

Raises¶

ValueError — If x and y have different lengths or are empty.