Metadata-Version: 2.1
Name: chart_builder
Version: 0.3.1
Summary: A library for building customizable charts in Python
Home-page: https://github.com/BrandynHamilton/Chart-Builder
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.6
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: plotly
Requires-Dist: kaleido
Requires-Dist: svgwrite
Requires-Dist: python-dotenv
Requires-Dist: colorcet
Requires-Dist: matplotlib
Requires-Dist: nbformat

# A Library for High-Quality, Reproducable Charts

- This library builds off Plotly and automates portions of data cleaning and charting for users.
- A user only inputs specified parameters such as chart type and columns to chart, enabling quick charting of complex data structures.

# Visualization Pipeline Parameters

This document explains the parameters of the `visualization_pipeline` class, grouped by category.

---

## 1. Core Settings

- **chart_type**: Type of chart (`line`, `bar`, `pie`, `line_and_bar`, `ranked bar`, etc.).
- **title**: Chart title.
- **subtitle**: Chart subtitle.
- **auto_title**: If `True`, automatically generates a title using column names.
- **dimensions**: Dict with chart size, e.g. `dict(height=400, width=730)`.
- **bgcolor**: Background color (`rgba` string).
- **autosize**: If `True`, chart auto-scales to container.

---

## 2. Data Input & Processing

- **df**: Pandas DataFrame containing the data.
- **file**: File path to load data from (optional).
- **is_file_path**: If `True`, treats `file` as a path to read from.
- **delimiter**: File delimiter (e.g., `,`).
- **cols_to_plot**: Columns to include (`'All'` by default).
- **groupby**: Column used for grouping data.
- **num_col**: Numeric column used for y-axis values.
- **bar_col / line_col**: Set the columns used for charting in a `line_and_bar` chart type.
- **index_col**: Column to use as DataFrame index.
- **time_col**: Column to treat as datetime.
- **set_time_col**: Sets the estimated datetime column as index, but does NOT turn to datetime data type.
- **turn_to_time**: If `True`, converts `time_col` to datetime.
- **resample_freq**: Resampling frequency (`'D'`, `'W'`, `'M'`).
- **agg_func**: Aggregation function (`'sum'`, `'mean'`, etc.).
- **start_date / end_date**: Filters data within a date range.
- **drop_duplicates**: Drop duplicate rows if `True`.
- **fillna / ffill**: Fill missing values.
- **keepna / dropna / dropna_col**: NA handling options.
- **clean_dates**: If `True`, will drop latest data points in timeseries if it falls within the middle of the estimated time frequency (week, month, year).

---

## 3. Axes & Ticks

- **axes_data**: Dict specifying axes data, e.g. `dict(y1=[], y2=[])`.
- **axes_titles**: Dict with axis titles, e.g. `dict(y1="Y Axis", y2="Secondary Y Axis")`.
- **axes_font_colors**: Dict of axis font colors (`y1`, `y2`). Also take in `auto` to automatically use the color palette.
- **tick0**: Starting tick value (`'min'` for auto).
- **dtick**: Step size between ticks.
- **tickformat**: Dict for axis formatting, e.g. `dict(x='%b %d <br>%y')`.
- **tickprefix**: Dict of prefixes for axis ticks (`y1`, `y2`).
- **ticksuffix**: Dict of suffixes for axis ticks (`y1`, `y2`).
- **tickangle**: Angle of tick labels.
- **ytickvals**: Custom y-axis tick values.
- **yticktext**: Custom y-axis tick labels.
- **ytick_num**: Number of y-axis ticks.
- **custom_ticks**: Apply custom tick formatting.
- **min_tick_spacing**: Minimum spacing between ticks.
- **remove_zero**: If `True`, removes zero from axis.
- **y_log**: Logarithmic y-axis if `True`.

---

## 4. Sorting & Data Presentation

- **sort_list**: If `True`, sort categories automatically.
- **user_sort_list**: Custom list defining sort order.
- **descending**: Sort order (descending if `True`).
- **cumulative_sort**: If `True`, will sort data series using total sum.
- **to_reverse**: Reverse sort order if `True`.
- **topn**: Limit to top N values.
- **normalize**: Normalize values to percentage if `True`.
- **to_percent**: Multiply values by 100 to turn from decimal to percent.

---

## 5. Visual Styling

- **colors**: Color palette.
- **user_color_map**: Map specific values â†’ colors.
- **use_single_color**: Force single-color scheme if `True`.
- **line_color**: Line color used in the `line_and_bar` chart type.
- **marker_col / y2_col**: Columns for color or dual-axis mapping.
- **marker_size**: Size of scatter markers.
- **line_width**: Width of line traces.
- **line_factor**: Line scaling factor for a vertical dashed line.
- **area**: Fill under line if `True`.
- **fill**: Plotly fill type (`tozeroy`, `tonexty`, etc.).
- **barmode**: Bar mode (`stack`, `group`, etc.).
- **orientation**: Chart orientation (`'v'` vertical, `'h'` horizontal).
- **mode**: Trace mode (`lines`, `markers`, etc.).
- **traceorder**: Legend item order (`'normal'`, `'reversed'`).
- **discrete**: If `True`, treats values as discrete.

---

## 6. Text & Labels

- **text**: Show text labels if `True`.
- **text_freq**: Frequency of text labels.
- **textposition**: Label position (`inside`, `outside`, etc.).
- **text_font_size**: Font size for labels.
- **texttemplate**: Custom text template for labels.
- **textinfo**: For pie charts (`'percent+label'`, etc.).
- **annotation_prefix / annotation_suffix**: Prefix/suffix for annotation values.
- **annotations**: If `True`, show annotations for first and last data point.
- **max_annotation**: If `True`, show annotation for the highest value in the data.
- **custom_annotation**: Custom annotation text.
- **annotation_font_size**: Font size of annotations.

---

## 7. Legend & Layout

- **show_legend**: Show legend if `True`.
- **legend_orientation**: Orientation (`'v'` vertical, `'h'` horizontal).
- **legend_placement**: Dict for placement (`dict(x=0.2, y=0.9)`).
- **legend_font_size**: Font size of legend text.
- **legend_background**: Dict for legend box (bgcolor, border, etc.).
- **itemsizing**: Legend item sizing (`'constant'`, `'trace'`).
- **margin**: Chart margins (l, r, t, b).

---

## 8. Fonts & Theming

- **font_size**: Global font size.
- **font_family**: Font family (default: `'Cardo'`).
- **font_color**: Font color.
- **logo**: Path to logo overlay.

---

## 9. Export & Saving

- **directory / save_directory**: Output directory for saved images.
- **file_type**: Export type (`'svg'`, `'png'`, etc.).
- **buffer**: When the index is datetime type, this will add a buffer to the x axis with either integer or float used to represent number of days.
- **hole_size**: Pie/donut hole size (0â€“1).
- **days_first**: Parses datetime column assuming days occur first in the string.

---
