chartengineer 0.1.0

Library for quick and modern chart building.

chartengineer Documentation

chartengineer is a lightweight Python package for building publication-ready, highly customizable Plotly charts from pandas DataFrames.

It supports a flexible API for pie charts, grouped bar charts, heatmaps, time series, and area/line plots, with robust formatting, annotations, and layout tools.

---

Installation

pip install chartengineer

Or install from source:

git clone https://github.com/your-org/chartengineer
cd chartengineer
pip install -e .

---

Quickstart

from chartengineer import ChartMaker

cm = ChartMaker(shuffle_colors=True)
cm.build(
    df=my_df,
    groupby_col="CHAIN",
    num_col="TOTAL_VOLUME",
    title="Bridge Volume by Chain",
    chart_type="pie",
    options={
        "tickprefix": {"y1": "$"},
        "annotations": True,
        "texttemplate": "%{label}<br>%{percent}"
    }
)
cm.add_title(subtitle="As of 2025-04-01")
cm.show_fig()

---

Supported Chart Types

• "line" (default)
• "bar"
• "area"
• "pie"
• "heatmap"

You can use a string or dictionary:

chart_type = "bar"  # applies to both y1/y2
chart_type = {"y1": "line", "y2": "bar"}  # axis-specific

---

Main Methods

ChartMaker.build(...)

Build a chart.

Arguments

• df: pandas DataFrame
• title: Chart title
• chart_type: string or dict
• groupby_col, num_col: for grouped series or pie/bar
• axes_data: e.g. {"x": "DATE", "y1": ["TVL"]}
• options: plot style and behavior options

---

ChartMaker.show_fig()

Render the current chart inline (Jupyter) or open in browser.

ChartMaker.save_fig(path, filetype='png')

Save the chart as .png, .svg, or .html.

ChartMaker.add_annotations(max_annotation=True, custom_annotations=None, annotation_placement=dict(x=0.5,y=0.5))

If called and the chart is plotting timeseries data, this automatically adds annotations for the first and last data points. If max_annotation is True, it dynamically calculates the max value in the dataset and annotates it. Note that this is meant for plotting single-series timeseries data.

If the chart is a Pie chart, the annotation_placement parameter enables moving the location of where the annotation is placed.

ChartMaker.add_dashed_line(date, annotation_text=None)

Adds a dashed line and annotation at the specified date; meant for timeseries data. If annotation_text is None, it uses the column name that contains the max value for the specified date.

ChartMaker.return_df()

Returns the dataframe used in a chart.

ChartMaker.return_fig()

Returns the Plotly figure that was created from calling the build method.

---

Customization Options

All style options can be passed via the options parameter. These are the same options that can be passed to a base Plotly figure. Refer to the Plotly library documentation for a full list of accepted parameters.

options = {
    "tickprefix": {"y1": "$"},
    "ticksuffix": {"y1": "%"},
    "dimensions": {"width": 800, "height": 400},
    "font_family": "Cardo",
    "font_size": {"axes": 16, "legend": 12, "textfont": 12},
    "legend_placement": {"x": 1.05, "y": 1},
    "show_text": True,
    "annotations": True,
}

---

Chart Features

• Grouped bar plots with custom sort and color mapping
• Automatic annotations for first/last/max points
• Time series support with datetime formatting
• Pie chart labels, percentages, donut hole support
• Heatmaps with flexible x/y/z column mapping

---

Project Structure

chartengineer/
├── __init__.py
├── core.py         # ChartMaker class
├── utils.py        # Plotting utils, formatting

---

License

MIT License © Brandyn Hamilton