chartengineer 0.1.0__tar.gz

chartengineer-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.1
+Name: chartengineer
+Version: 0.1.0
+Summary: Library for quick and modern chart building.
+Home-page:  
+Author: Brandyn Hamilton
+Author-email: brandynham1120@gmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: dotenv
+Requires-Dist: plotly
+Requires-Dist: matplotlib
+Requires-Dist: colorcet
+Requires-Dist: nbformat>=4.2.0
+Requires-Dist: kaleido==0.1.0.post1
+
+# `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
+
+```bash
+pip install chartengineer
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/your-org/chartengineer
+cd chartengineer
+pip install -e .
+```
+
+---
+
+## Quickstart
+
+```python
+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:
+
+```python
+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.  
+
+```python
+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

chartengineer-0.1.0/README.md

@@ -0,0 +1,153 @@
+# `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
+
+```bash
+pip install chartengineer
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/your-org/chartengineer
+cd chartengineer
+pip install -e .
+```
+
+---
+
+## Quickstart
+
+```python
+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:
+
+```python
+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.  
+
+```python
+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

chartengineer-0.1.0/chartengineer/__init__.py

@@ -0,0 +1 @@
+from .core import (ChartMaker)