### Install and Use Termgraph

Source: https://github.com/mkaz/termgraph/blob/main/docs/index.md

Shows how to install the termgraph library using pip and provides a concise example of creating and drawing a simple bar chart directly from the command line.

```bash
# Install termgraph
pip install termgraph
```

```python
python -c "from termgraph import Data, BarChart; chart = BarChart(Data([1,2,3], ['A','B','C'])); chart.draw()"
```

--------------------------------

### Install Dependencies with 'just'

Source: https://github.com/mkaz/termgraph/blob/main/CONTRIBUTING.md

Install development dependencies using the 'just' command runner.

```bash
just install           # Install development dependencies
```

--------------------------------

### Run Example with Sample Data

Source: https://github.com/mkaz/termgraph/blob/main/CONTRIBUTING.md

Execute the project's example script with sample data using the 'just' command runner.

```bash
just run-example       # Run with sample data
```

--------------------------------

### Quick Start: Create and Draw a Bar Chart

Source: https://github.com/mkaz/termgraph/blob/main/docs/README.md

A basic example demonstrating how to create data and draw a simple bar chart using Termgraph.

```python
from termgraph import Data, BarChart, Args

# Create data
data = Data([23, 45, 56, 78, 32], ["A", "B", "C", "D", "E"])

# Create and display chart
chart = BarChart(data)
chart.draw()
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/mkaz/termgraph/blob/main/CONTRIBUTING.md

Install necessary development dependencies using the 'just' command runner. Alternatively, use 'uv sync --dev'.

```bash
just install
# or manually: uv sync --dev
```

--------------------------------

### Termgraph Python API Basic Setup

Source: https://github.com/mkaz/termgraph/blob/main/README.md

Demonstrates the basic setup for using the termgraph Python API, including importing necessary classes and configuring chart arguments.

```python
from termgraph import (
    Data, Args,
    BarChart, StackedChart, VerticalChart, HistogramChart
)

# Basic setup
data = Data([[10], [20]], ["A", "B"])
args = Args(title="My Chart")

# Choose your chart type
chart = BarChart(data, args)        # Horizontal bars
# chart = StackedChart(data, args)  # Stacked bars
# chart = VerticalChart(data, args) # Vertical bars

```

--------------------------------

### CLI Usage Examples

Source: https://context7.com/mkaz/termgraph/llms.txt

Examples demonstrating how to use the termgraph command-line interface for various chart types and data sources.

```APIDOC
## Basic bar chart from a data file

### Description
Generates a horizontal bar chart from a two-column data file (label + value).

### Command
```bash
termgraph data/sales.dat --title "Annual Revenue" --width 40 --suffix "K"
```

### Example Data (data/sales.dat)
```
# 2020 183.32
# 2021 231.23
# 2022 16.43
# 2023 508.97
```

## Reading from stdin

### Description
Termgraph can read data directly from standard input, making it useful for shell pipelines.

### Command
```bash
echo -e "Apples 40\nBananas 70\nCherry 25" | termgraph --title "Fruit Count"
```

## Multi-variable color chart with space between rows

### Description
Creates a grouped bar chart when the data file includes category names using the `@` prefix.

### Command
```bash
termgraph data/products.dat --color cyan yellow --space-between --title "Quarterly Sales"
```

### Example Data (data/products.dat)
```
# @ Product A, Product B
# Q1 120, 80
# Q2 150, 95
# Q3 180, 110
```

## Stacked bar chart

### Description
Renders a stacked bar chart to visualize the composition of data over categories.

### Command
```bash
termgraph data/market.dat --color green magenta --stacked --title "Market Share"
```

## Histogram

### Description
Generates a histogram to show the distribution of data values across specified bins.

### Command
```bash
termgraph data/measurements.dat --histogram --bins 5 --title "Value Distribution"
```

## Vertical (column) chart

### Description
Creates a vertical column chart for visualizing data.

### Command
```bash
termgraph data/scores.dat --vertical --width 30 --title "Test Scores"
```

## Calendar heatmap

### Description
Displays a calendar heatmap, expecting dates in `YYYY-MM-DD` format as labels.

### Command
```bash
termgraph data/activity.dat --calendar --start-dt 2023-01-01 --color blue
```

## Custom tick marks (emoji)

### Description
Allows customization of the bar tick character, including using emoji.

### Command
```bash
termgraph data/sales.dat --custom-tick "🏃" --width 20 --title "Running Data"
```

## Percentage display

### Description
Formats the displayed values as percentages with custom formatting options.

### Command
```bash
echo -e "ProjectA 0.65\nProjectB 0.80\nProjectC 0.45" | \
  termgraph --percentage --format "{:<4.0f}" --suffix "%" --title "Completion"
```
```

--------------------------------

### Install Termgraph

Source: https://github.com/mkaz/termgraph/blob/main/docs/README.md

Use pip to install the Termgraph library.

```bash
pip install termgraph
```

--------------------------------

### Basic Flat Data Example

Source: https://github.com/mkaz/termgraph/blob/main/docs/data-class.md

Demonstrates initializing a Data object with flat sales data and retrieving minimum and maximum sales values.

```python
from termgraph import Data

# Simple sales data
sales_data = Data(
    data=[150, 230, 180, 290, 210],
    labels=["Jan", "Feb", "Mar", "Apr", "May"]
)

print(f"Min sales: {sales_data.find_min()}")  # Min sales: 150
print(f"Max sales: {sales_data.find_max()}")  # Max sales: 290
print(f"Data: {sales_data}")
```

--------------------------------

### Multi-Series Data with Categories Example

Source: https://github.com/mkaz/termgraph/blob/main/docs/data-class.md

Shows how to initialize a Data object for quarterly sales of multiple products, including labels and category names.

```python
from termgraph import Data

# Quarterly sales for two products
quarterly_data = Data(
    data=[
        [120, 80],   # Q1: Product A, Product B
        [150, 95],   # Q2: Product A, Product B
        [180, 110],  # Q3: Product A, Product B
        [200, 125]   # Q4: Product A, Product B
    ],
    labels=["Q1", "Q2", "Q3", "Q4"],
    categories=["Product A", "Product B"]
)

print(f"Dimensions: {quarterly_data.dims}")  # (4, 2)
print(f"Categories: {quarterly_data.categories}")
```

--------------------------------

### Configure Chart-Specific Options

Source: https://github.com/mkaz/termgraph/blob/main/docs/chart-classes.md

Provides examples of chart-specific configuration options for BarChart, HistogramChart, and VerticalChart using the Args object.

```python
# Bar chart specific
args = Args(
    different_scale=True,  # Use different scales for multi-series
    label_before=True      # Show labels before bars
)

# Histogram specific
args = Args(
    bins=10               # Number of histogram bins
)

# Vertical chart specific
args = Args(
    vertical=True         # Enable vertical mode
)
```

--------------------------------

### Run Test Suite

Source: https://github.com/mkaz/termgraph/blob/main/CONTRIBUTING.md

Execute the project's test suite to verify the development environment setup. This ensures all tests pass before proceeding.

```bash
just test
```

--------------------------------

### Add New Chart Option Example

Source: https://github.com/mkaz/termgraph/blob/main/CONTRIBUTING.md

Demonstrates how to add a new chart option by updating arguments, CLI parsing, and chart rendering logic.

```python
# 1. Add to Args.default in args.py
"new_option": False,
```

```python
# 2. Add CLI argument in termgraph.py  
parser.add_argument("--new-option", action="store_true", help="Enable new option")
```

```python
# 3. Use in chart rendering
if self.args.get_arg("new_option"):
    # implement feature
```

--------------------------------

### Configure Chart with Args Class

Source: https://context7.com/mkaz/termgraph/llms.txt

Illustrates the Args class for centralizing chart configuration. Shows default and full configuration examples, including title, dimensions, formatting, colors, and chart types. It also demonstrates reading and updating arguments, and handling invalid arguments.

```python
from termgraph import Args, Colors

# All defaults
args = Args()

# Full configuration example
args = Args(
    title="Q4 Performance",
    width=60,                     # chart width in characters (default 50)
    format="{:>8.2f}",            # Python format string for values
    suffix=" units",              # appended to every printed value
    no_labels=False,              # True = hide row labels
    no_values=False,              # True = hide numeric values
    space_between=True,           # blank line between bars
    colors=[Colors.Green, Colors.Blue],  # per-series ANSI colors
    label_before=False,           # True = print label before bar
    percentage=False,             # True = multiply value × 100 and add %
    no_readable=False,            # True = disable auto K/M/B abbreviation
    custom_tick="▓",              # override default ▇ tick character
    different_scale=False,        # True = normalize each series independently
    stacked=False,                # True = stacked bar mode
    histogram=False,              # True = histogram mode
    bins=5,                       # number of histogram bins
    vertical=False,               # True = vertical column chart
)

# Read and update
print(args.get_arg("width"))      # 60
args.update_args(width=80, title="Updated")
print(args.get_arg("title"))      # "Updated"

# Invalid arg raises immediately
try:
    Args(unknown_option=True)
except Exception as e:
    print(e)   # "Invalid Argument: unknown_option"

# Available color constants
# Colors.Black, Colors.Red, Colors.Green, Colors.Yellow
# Colors.Blue, Colors.Magenta, Colors.Cyan
# (correspond to ANSI SGR codes 90–96)
```

--------------------------------

### Working with Negative Values Example

Source: https://github.com/mkaz/termgraph/blob/main/docs/data-class.md

Illustrates how the normalize method handles profit/loss data that includes negative values, automatically offsetting and scaling.

```python
from termgraph import Data

# Profit/Loss data with negative values
pnl_data = Data(
    data=[-50, 30, -20, 80, 45],
    labels=["Jan", "Feb", "Mar", "Apr", "May"]
)

# Normalization handles negative values automatically
normalized = pnl_data.normalize(40)
print(f"Normalized data: {normalized}")
```

--------------------------------

### Draw Bar Chart

Source: https://github.com/mkaz/termgraph/blob/main/CONTRIBUTING.md

Create and draw a bar chart using Data and Args objects. This example demonstrates basic chart instantiation and rendering.

```python
from termgraph import Data, Args, BarChart

data = Data([[10], [20]], ["A", "B"])
args = Args(title="Test Chart")
chart = BarChart(data, args)
chart.draw()
```

--------------------------------

### Termgraph Custom Tick Example

Source: https://github.com/mkaz/termgraph/blob/main/README.md

Demonstrates using a custom emoji as a tick mark for the graph.

```bash
termgraph data/ex1.dat --custom-tick "🏃" --width 20 --title "Running Data"

# Running Data

2007: 🏃🏃🏃🏃🏃🏃🏃 183.32
2008: 🏃🏃🏃🏃🏃🏃🏃🏃🏃 231.23
2009:  16.43
2010: 🏃 50.21
2011: 🏃🏃🏃🏃🏃🏃🏃🏃🏃🏃🏃🏃🏃🏃🏃🏃🏃🏃🏃🏃 508.97
2012: 🏃🏃🏃🏃🏃🏃🏃🏃 212.05
2014:  1.00


```

--------------------------------

### Histogram for Data Distribution

Source: https://github.com/mkaz/termgraph/blob/main/docs/README.md

Example of creating a histogram to visualize the distribution of continuous data. Requires specifying the number of bins for data grouping.

```python
from termgraph import Data, HistogramChart, Args, Colors

# Temperature readings that will be binned
data = Data(
    data=[[15.2, 18.7, 22.1, 19.5, 25.3, 28.9, 24.4, 21.8, 26.2, 23.7, 20.1, 17.6]],
    labels=["Temperature Data"]
)

args = Args(
    title="Temperature Distribution",
    bins=6,
    colors=[Colors.Red],
    width=50
)

chart = HistogramChart(data, args)
chart.draw()
```

--------------------------------

### Add New Data Operation Example

Source: https://github.com/mkaz/termgraph/blob/main/CONTRIBUTING.md

Illustrates adding a new data operation by implementing a method in the Data class, a backward compatibility function, and corresponding tests.

```python
# 1. Add method to Data class in data.py
def new_operation(self) -> float:
    return some_calculation(self.data)
```

```python
# 2. Add backward compatibility function
def new_operation(data: list) -> float:
    data_obj = Data(data, [str(i) for i in range(len(data))])
    return data_obj.new_operation()
```

```python
# 3. Add tests in test_data_utils.py
def test_new_operation():
    # test implementation
```

--------------------------------

### Get Tabular String Representation of Data

Source: https://github.com/mkaz/termgraph/blob/main/docs/data-class.md

Shows how to create a Data object and print its tabular string representation, which includes labels and categories.

```python
data = Data(
    data=[[100, 150], [200, 250], [300, 350]],
    labels=["Product 1", "Product 2", "Product 3"],
    categories=["Sales", "Revenue"]
)

print(data)
```

--------------------------------

### Integrate Multiple Chart Types

Source: https://github.com/mkaz/termgraph/blob/main/docs/chart-classes.md

An example demonstrating the integration of multiple chart types (BarChart, StackedChart, VerticalChart) using the same dataset and common arguments.

```python
from termgraph import Data, BarChart, StackedChart, VerticalChart, Args, Colors

# Sample data
data = Data(
    data=[[30, 45], [25, 50], [40, 35], [35, 40]],
    labels=["Q1", "Q2", "Q3", "Q4"],
    categories=["Revenue", "Expenses"]
)

args = Args(
    width=40,
    title="Financial Data",
    colors=[Colors.Green, Colors.Red]
)

# Example usage with different chart types would follow here, e.g.:
# bar_chart = BarChart(data, args)
# bar_chart.draw()
# stacked_chart = StackedChart(data, args)
# stacked_chart.draw()
# vertical_chart = VerticalChart(data, args)
# vertical_chart.draw()
```

--------------------------------

### Stacked Bar Chart for Part-to-Whole Visualization

Source: https://github.com/mkaz/termgraph/blob/main/docs/README.md

Example of creating a stacked bar chart to visualize how different components contribute to a whole over categories. Uses multiple colors for different data segments.

```python
from termgraph import Data, StackedChart, Args, Colors

# Budget breakdown
data = Data(
    data=[
        [30, 20, 10],  # Q1: Marketing, Development, Operations
        [35, 25, 15],  # Q2: Marketing, Development, Operations
        [40, 30, 20],  # Q3: Marketing, Development, Operations
        [45, 35, 25]   # Q4: Marketing, Development, Operations
    ],
    labels=["Q1", "Q2", "Q3", "Q4"],
    categories=["Marketing", "Development", "Operations"]
)

args = Args(
    title="Budget Allocation by Quarter",
    colors=[Colors.Green, Colors.Blue, Colors.Yellow],
    suffix="K"
)

chart = StackedChart(data, args)
chart.draw()
```

--------------------------------

### Render Horizontal Bar Chart with BarChart

Source: https://context7.com/mkaz/termgraph/llms.txt

Demonstrates rendering a horizontal bar chart using the BarChart class. It shows examples for single-series and multi-series data, and highlights the use of the `different_scale` argument for improved legibility with disparate data ranges.

```python
from termgraph import Data, Args, BarChart, Colors

# Single series
data = Data([23, 45, 56, 78, 32], ["Mon", "Tue", "Wed", "Thu", "Fri"])
args = Args(title="Daily Tickets", colors=[Colors.Cyan], suffix=" tix", width=40)
BarChart(data, args).draw()
# Daily Tickets
#
# Mon: ▇▇▇▇▇▇▇▇▇▇▇▇ 23.00 tix

```

--------------------------------

### Simple Args Configuration

Source: https://github.com/mkaz/termgraph/blob/main/docs/args-class.md

Basic configuration for chart appearance with width, title, colors, and suffix.

```python
from termgraph import Args

args = Args(
    width=50,
    title="Sales Data",
    colors=[Colors.Blue],
    suffix=" units"
)
```

--------------------------------

### Termgraph Python Module Usage

Source: https://github.com/mkaz/termgraph/blob/main/README.md

Example of using the termgraph Python module to create and display a bar chart with custom options.

```python
from termgraph import Data, Args, BarChart

# Create data
data = Data([[10], [25], [50], [40]], ["Q1", "Q2", "Q3", "Q4"])

# Configure chart options
args = Args(
    title="Quarterly Sales",
    width=50,
    format="{:.0f}",
    suffix="K"
)

# Create and display chart
chart = BarChart(data, args)
chart.draw()

```

```text
# Quarterly Sales

Q1: ▇▇▇▇▇▇▇▇▇▇ 10K
Q2: ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 25K
Q3: ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 50K
Q4: ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 40K

```

--------------------------------

### Get Data Dimensions (Flat)

Source: https://github.com/mkaz/termgraph/blob/main/docs/data-class.md

Returns a tuple representing the dimensions of the data structure. For flat data, this will be a tuple with a single element.

```python
# Flat data
data = Data([10, 20, 30], ["A", "B", "C"])
print(data.dims)  # (3,)
```

--------------------------------

### Create a Bar Chart with Percentage Formatting

Source: https://github.com/mkaz/termgraph/blob/main/docs/chart-classes.md

Shows how to display project completion status as percentages using the `percentage=True` option and custom formatting with a '%' suffix.

```python
from termgraph import Data, BarChart, Args, Colors

# Percentage completion data
data = Data(
    data=[0.65, 0.80, 0.45, 0.92, 0.73],
    labels=["Project A", "Project B", "Project C", "Project D", "Project E"]
)

args = Args(
    width=40,
    title="Project Completion Status",
    colors=[Colors.Green],
    percentage=True,      # Format as percentages
    format="{:<4.0f}",
    suffix="%"
)

chart = BarChart(data, args)
chart.draw()
```

--------------------------------

### Args Constructor

Source: https://github.com/mkaz/termgraph/blob/main/docs/args-class.md

Initializes the Args class with default or custom configuration options. All parameters are optional and provided as keyword arguments.

```APIDOC
## Constructor

```python
from termgraph import Args

# Default args
args = Args()

# Custom args
args = Args(
    width=60,
    title="My Chart",
    colors=["red", "blue"],
    suffix=" units"
)
```

### Parameters

All parameters are optional and provided as keyword arguments. If not specified, default values are used.
```

--------------------------------

### Initialize Args with Default and Custom Values

Source: https://github.com/mkaz/termgraph/blob/main/docs/args-class.md

Instantiate the Args class. Default arguments are used if none are provided. Custom arguments can be passed as keyword arguments.

```python
from termgraph import Args

# Default args
args = Args()

# Custom args
args = Args(
    width=60,
    title="My Chart",
    colors=["red", "blue"],
    suffix=" units"
)
```

--------------------------------

### Initialize Args Class Instance

Source: https://github.com/mkaz/termgraph/blob/main/CONTRIBUTING.md

Instantiate the Args class to manage chart configuration. It allows setting options like width, title, and percentage display. Access arguments using get_arg.

```python
from termgraph import Args

args = Args(width=100, title="My Chart", percentage=True)
print(args.get_arg("width"))  # 100
```

--------------------------------

### Get Data Dimensions (Nested)

Source: https://github.com/mkaz/termgraph/blob/main/docs/data-class.md

Returns a tuple representing the dimensions of the data structure. For nested data, this will reflect the number of rows and columns.

```python
# Nested data
data = Data([[10, 15], [20, 25]], ["X", "Y"])
print(data.dims)  # (2, 2)
```

--------------------------------

### List Available 'just' Commands

Source: https://github.com/mkaz/termgraph/blob/main/CONTRIBUTING.md

Display all available commands that can be executed using the 'just' command runner. This is useful for understanding the development workflow.

```bash
just                    # Show available commands
```

--------------------------------

### Create Project Status Bar Chart

Source: https://github.com/mkaz/termgraph/blob/main/docs/README.md

Displays project completion percentages using a bar chart. Configured with percentage formatting and a single color. Requires Data, BarChart, Args, and Colors.

```python
from termgraph import Data, BarChart, Args, Colors

projects_data = Data(
    data=[0.85, 0.62, 0.93, 0.78, 0.45, 0.91],
    labels=["Website Redesign", "Mobile App", "Database Migration", "API v2", "Documentation", "Testing Suite"]
)

args = Args(
    title="Project Completion Status",
    colors=[Colors.Green],
    percentage=True,
    width=50,
    format="{:<3.0f}",
    suffix="%"
)

chart = BarChart(projects_data, args)
chart.draw()
```

--------------------------------

### Run Tests with 'just'

Source: https://github.com/mkaz/termgraph/blob/main/CONTRIBUTING.md

Run the entire test suite using the 'just' command runner.

```bash
just test              # Run the test suite
```

--------------------------------

### Create and Draw a Histogram Chart

Source: https://github.com/mkaz/termgraph/blob/main/README.md

Instantiate a HistogramChart with data and arguments, then draw it to the console. Ensure data is properly formatted before passing it.

```python
chart = HistogramChart(data, args) # Histogram

chart.draw()
```

--------------------------------

### Customize Chart Bar Character

Source: https://github.com/mkaz/termgraph/blob/main/docs/args-class.md

Replace the default block character for chart bars with a custom character using 'custom_tick'. Examples include asterisks or equals signs.

```python
args = Args(custom_tick="*")   # Use asterisks
```

```python
args = Args(custom_tick="=")   # Use equals signs
```

```python
args = Args(custom_tick="█")   # Use solid blocks
```

--------------------------------

### Integration with Chart Constructors

Source: https://github.com/mkaz/termgraph/blob/main/docs/args-class.md

Shows how to create an Args object and pass it to a chart constructor like BarChart.

```python
from termgraph import Data, BarChart, Args, Colors

# Create data and args
data = Data([10, 20, 30], ["A", "B", "C"])
args = Args(
    width=40,
    title="Sample Chart",
    colors=[Colors.Green]
)

# Create and draw chart
chart = BarChart(data, args)
chart.draw()

```

--------------------------------

### Termgraph Color Charts

Source: https://github.com/mkaz/termgraph/blob/main/README.md

Examples of using color options for bar charts, including multi-variable and stacked charts. Note that color charts use ANSI escape codes.

```bash
termgraph data/ex4.dat --color {cyan/yellow} --space-between

```

```bash
termgraph data/ex7.dat --color {green,magenta} --stacked

```

--------------------------------

### Handle Data Initialization Exceptions

Source: https://github.com/mkaz/termgraph/blob/main/docs/data-class.md

Demonstrates how to catch exceptions that occur due to invalid data structures or mismatched dimensions when initializing the Data class.

```python
try:
    # Missing labels
    Data([10, 20, 30])
except Exception as e:
    print(f"Error: {e}")
```

```python
try:
    # Mismatched dimensions
    Data([10, 20], ["A", "B", "C"])
except Exception as e:
    print(f"Error: {e}")
```

```python
try:
    # Inconsistent nested structure
    Data([[10, 20], [30]], ["A", "B"])
except Exception as e:
    print(f"Error: {e}")
```

--------------------------------

### Create a Histogram Chart

Source: https://github.com/mkaz/termgraph/blob/main/docs/chart-classes.md

Shows how to generate a histogram chart by binning continuous data. Ensure the data is provided as a list of lists for binning.

```python
from termgraph import Data, HistogramChart, Args, Colors

# Histogram chart
# Note: For histograms, data should be the raw values you want to bin
data = Data(
    data=[[12.5, 15.3, 18.7, 22.1, 25.6, 28.9, 32.4, 35.8, 38.2, 41.7]],
    labels=["Temperature Readings"]
)

args = Args(
    width=40,
    bins=5,  # Number of bins
    title="Temperature Distribution",
    colors=[Colors.Red]
)

chart = HistogramChart(data, args)
chart.draw()
```

--------------------------------

### Calendar heatmap

Source: https://context7.com/mkaz/termgraph/llms.txt

Displays a calendar heatmap. The chart expects dates in YYYY-MM-DD format as labels. Use --start-dt to set the starting date and --color for color schemes.

```bash
$ termgraph data/activity.dat --calendar --start-dt 2023-01-01 --color blue
```

--------------------------------

### Load Data from File using Data.from_file()

Source: https://context7.com/mkaz/termgraph/llms.txt

Shows how to use the Data.from_file() class method to parse data from a file or standard input. It demonstrates specifying arguments like delimiter and verbosity, and accessing the parsed labels, categories, and data.

```python
from termgraph.data import Data

# Read from a file
# File format (data/sales.dat):
#   # Annual sales figures
#   @ Region A, Region B
#   2021 120, 80
#   2022 150, 95
#   2023 180, 110

data_obj = Data.from_file("data/sales.dat", args={"delim": ",", "verbose": True})
# >> Reading data from data/sales.dat

print(data_obj.labels)      # ['2021', '2022', '2023']
print(data_obj.categories)  # ['Region A', 'Region B']
print(data_obj.data)        # [[120.0, 80.0], [150.0, 95.0], [180.0, 110.0]]

# Read from stdin (filename="-")
import sys
data_stdin = Data.from_file("-", args={"delim": ""})
```

--------------------------------

### Horizontal Bar Chart for Single Series

Source: https://github.com/mkaz/termgraph/blob/main/docs/README.md

Example of creating a horizontal bar chart for a single data series, useful for comparing values across different categories. Uses Colors enum for styling.

```python
from termgraph import Data, BarChart, Args, Colors

# Single series
data = Data([45, 32, 78, 56, 23], ["Product A", "Product B", "Product C", "Product D", "Product E"])
chart = BarChart(data, Args(colors=[Colors.Blue]))
chart.draw()
```

--------------------------------

### Configure Common Chart Options

Source: https://github.com/mkaz/termgraph/blob/main/docs/chart-classes.md

Illustrates the use of common configuration options available for all chart classes via the Args object, such as width, title, colors, and formatting.

```python
from termgraph import Args, Colors

args = Args(
    width=50,              # Chart width in characters
    title="My Chart",      # Chart title
    colors=[Colors.Blue],  # Colors for series
    suffix=" units",       # Value suffix
    format="{:<6.1f}",    # Value formatting
    no_labels=False,       # Hide labels
    no_values=False,       # Hide values
    space_between=True     # Add space between bars
)
```

--------------------------------

### Run Module API Integration Tests

Source: https://github.com/mkaz/termgraph/blob/main/tests/README.md

Execute all module API integration tests.

```bash
just test-module
```

--------------------------------

### Initialize Data Class Instance

Source: https://github.com/mkaz/termgraph/blob/main/CONTRIBUTING.md

Instantiate the Data class with data and labels. Use this to prepare data for charting. It finds the maximum value in the dataset.

```python
from termgraph import Data

data = Data([[1, 2], [3, 4]], ["Label1", "Label2"])
print(data.find_max())  # 4
```

--------------------------------

### Termgraph Command Line Arguments Help

Source: https://github.com/mkaz/termgraph/blob/main/README.md

Displays the usage information and available options for the termgraph command-line interface.

```text
usage: termgraph [-h] [options] [filename]

draw basic graphs on terminal

positional arguments:
  filename              data file name (comma or space separated). Defaults to stdin.

options:
  -h, --help            show this help message and exit
  --title TITLE         Title of graph
  --width WIDTH         width of graph in characters default:50
  --format FORMAT       format specifier to use.
  --suffix SUFFIX       string to add as a suffix to all data points.
  --no-labels           Do not print the label column
  --no-values           Do not print the values at end
  --space-between       Print a new line after every field
  --color [COLOR ...]   Graph bar color( s )
  --vertical            Vertical graph
  --stacked             Stacked bar graph
  --histogram           Histogram
  --bins BINS           Bins of Histogram
  --different-scale     Categories have different scales.
  --calendar            Calendar Heatmap chart
  --start-dt START_DT   Start date for Calendar chart
  --custom-tick CUSTOM_TICK
                        Custom tick mark, emoji approved
  --delim DELIM         Custom delimiter, default , or space
  --verbose             Verbose output, helpful for debugging
  --label-before        Display the values before the bars
  --no-readable         Disable the readable numbers
  --percentage          Display the number in percentage
  --version             Display version and exit

```

--------------------------------

### Percentage Chart Configuration

Source: https://github.com/mkaz/termgraph/blob/main/docs/args-class.md

Configure a chart to display data as percentages with specific formatting.

```python
from termgraph import Args, Colors

# Percentage display
args = Args(
    width=50,
    title="Completion Status",
    percentage=True,
    colors=[Colors.Green],
    format="{:<3.0f}",
    suffix="%"
)
```

--------------------------------

### Create Performance Metrics Bar Chart

Source: https://github.com/mkaz/termgraph/blob/main/docs/README.md

Visualizes system performance metrics like uptime and response time using a bar chart with different scales for each metric. Imports Data, BarChart, Args, and Colors.

```python
from termgraph import Data, BarChart, Args, Colors

performance_data = Data(
    data=[
        [95.5, 1250],    # Uptime %, Response Time (ms)
        [98.2, 980],
        [97.1, 1100],
        [99.1, 850],
        [96.8, 1300]
    ],
    labels=["Week 1", "Week 2", "Week 3", "Week 4", "Week 5"],
    categories=["Uptime (%)", "Response Time (ms)"]
)

args = Args(
    title="System Performance Metrics",
    colors=[Colors.Green, Colors.Red],
    different_scale=True,  # Use different scales for each metric
    width=50,
    space_between=True
)

chart = BarChart(performance_data, args)
chart.draw()
```

--------------------------------

### Initialize Data Class with Flat Data

Source: https://github.com/mkaz/termgraph/blob/main/docs/data-class.md

Use this to create a Data object with a simple list of numbers and corresponding labels.

```python
from termgraph import Data

# Basic usage
data = Data(data=[10, 20, 30, 40], labels=["Q1", "Q2", "Q3", "Q4"])
```

--------------------------------

### Basic Bar Chart Creation

Source: https://github.com/mkaz/termgraph/blob/main/docs/README.md

Demonstrates creating a simple bar chart with custom labels and data. The output shows the visual representation of the data in the terminal.

```python
from termgraph import Data, BarChart

# Sales data
data = Data(
    data=[150, 230, 180, 290, 210],
    labels=["Jan", "Feb", "Mar", "Apr", "May"]
)

chart = BarChart(data)
chart.draw()
```

--------------------------------

### Core Termgraph Workflow

Source: https://github.com/mkaz/termgraph/blob/main/docs/index.md

Demonstrates the fundamental steps for creating a chart using the Termgraph library: data preparation, argument configuration, chart instantiation, and drawing.

```python
from termgraph import Data, BarChart, StackedChart, VerticalChart, HistogramChart, Args, Colors

# Core workflow
data = Data([10, 20, 30], ["A", "B", "C"])        # Data preparation
args = Args(width=50, colors=[Colors.Blue])        # Configuration
chart = BarChart(data, args)                       # Chart creation
chart.draw()                                       # Visualization
```

--------------------------------

### Run All Quality Checks

Source: https://github.com/mkaz/termgraph/blob/main/CONTRIBUTING.md

Execute all code quality checks, including linting and type checking, using the 'just' command runner.

```bash
just check             # Run all quality checks (lint + typecheck)
```

--------------------------------

### Percentage display chart

Source: https://context7.com/mkaz/termgraph/llms.txt

Configures the chart to display values as percentages. Use --percentage, --format for custom number formatting, --suffix for units, and --title for labeling.

```bash
echo -e "ProjectA 0.65\nProjectB 0.80\nProjectC 0.45" | \
  termgraph --percentage --format "{:<4.0f}" --suffix "%" --title "Completion"
```

--------------------------------

### Create Data with Flat Data (Single Series)

Source: https://github.com/mkaz/termgraph/blob/main/docs/README.md

Initializes a Data object with a simple list of numbers and corresponding labels for a single series chart.

```python
# Simple list of numbers
data = Data([10, 20, 30, 40], ["A", "B", "C", "D"])
```

--------------------------------

### Run Individual Module Test

Source: https://github.com/mkaz/termgraph/blob/main/tests/README.md

Execute a specific module integration test script.

```bash
uv run python tests/module-test1.py
uv run python tests/module-test2.py
uv run python tests/module-test3.py
```

--------------------------------

### Integrate Data with BarChart

Source: https://github.com/mkaz/termgraph/blob/main/docs/data-class.md

Illustrates how to create a Data object and use it with a BarChart, including custom arguments for chart appearance.

```python
from termgraph import Data, BarChart, Args

# Create data
data = Data([45, 32, 78, 56, 23], ["A", "B", "C", "D", "E"])

# Create chart with custom arguments
args = Args(width=60, colors=["red"])
chart = BarChart(data, args)

# Draw the chart
chart.draw()
```

--------------------------------

### Basic bar chart from data file

Source: https://context7.com/mkaz/termgraph/llms.txt

Renders a horizontal bar chart from a two-column data file. Specify title, width, and suffix for customization.

```bash
# data/sales.dat:
# 2020 183.32
# 2021 231.23
# 2022 16.43
# 2023 508.97

$ termgraph data/sales.dat --title "Annual Revenue" --width 40 --suffix "K"
```

--------------------------------

### Create and Print Data Object

Source: https://context7.com/mkaz/termgraph/llms.txt

Demonstrates creating a Data object with negative values and printing its tabular string representation. The normalize method is shown to automatically handle offsets for negative values.

```python
pnl = Data([-50, 30, -20, 80, 45], ["Jan", "Feb", "Mar", "Apr", "May"])
print(pnl.normalize(40))          # values shifted so min >= 0, then scaled to width=40

multi = Data(
    data=[[100, 150], [200, 250]],
    labels=["Product 1", "Product 2"],
    categories=["Sales", "Revenue"]
)
print(multi)
```

--------------------------------

### Multi-Series Bar Chart for Comparison

Source: https://github.com/mkaz/termgraph/blob/main/docs/README.md

Demonstrates creating a multi-series bar chart to compare data across categories for different series. Requires specifying categories and multiple colors.

```python
from termgraph import Data, BarChart, Args, Colors

# Quarterly sales for two products
data = Data(
    data=[
        [120, 80],   # Q1: Product A, Product B
        [150, 95],   # Q2: Product A, Product B
        [180, 110],  # Q3: Product A, Product B
        [200, 125]   # Q4: Product A, Product B
    ],
    labels=["Q1", "Q2", "Q3", "Q4"],
    categories=["Product A", "Product B"]
)

args = Args(
    title="Quarterly Sales Comparison",
    colors=[Colors.Blue, Colors.Red],
    width=50
)

chart = BarChart(data, args)
chart.draw()
```

--------------------------------

### Stacked Chart Configuration

Source: https://github.com/mkaz/termgraph/blob/main/docs/args-class.md

Set up a stacked chart to visualize the composition of data over time or categories.

```python
from termgraph import Args, Colors

# Stacked chart setup
args = Args(
    width=50,
    title="Market Share Evolution",
    colors=[Colors.Blue, Colors.Green, Colors.Yellow],
    stacked=True,
    format="{:<4.0f}",
    suffix="%"
)
```

--------------------------------

### Create Stacked Bar Chart

Source: https://github.com/mkaz/termgraph/blob/main/docs/README.md

Generates a stacked bar chart to visualize revenue by region over quarters. Requires Data and Args objects.

```python
from termgraph import Data, StackedChart, Args, Colors

revenue_data = Data(
    data=[
        [450, 380, 290],  # Q1: Americas, EMEA, APAC
        [520, 420, 340],  # Q2: Americas, EMEA, APAC
        [480, 450, 380],  # Q3: Americas, EMEA, APAC
        [600, 480, 420]   # Q4: Americas, EMEA, APAC
    ],
    labels=["Q1 2023", "Q2 2023", "Q3 2023", "Q4 2023"],
    categories=["Americas", "EMEA", "APAC"]
)

print("=== Revenue by Region (Stacked) ===")
stacked_args = Args(
    title="Quarterly Revenue by Region",
    colors=[Colors.Blue, Colors.Green, Colors.Yellow],
    width=60,
    suffix="K USD",
    format="{:<5.0f}"
)
stacked_chart = StackedChart(revenue_data, stacked_args)
stacked_chart.draw()
```

--------------------------------

### Create a Vertical Bar Chart

Source: https://github.com/mkaz/termgraph/blob/main/docs/chart-classes.md

Demonstrates how to create and draw a simple vertical bar chart with custom data, labels, and styling.

```python
from termgraph import Data, VerticalChart, Args, Colors

data = Data(
    data=[23, 45, 56, 78, 32],
    labels=["A", "B", "C", "D", "E"]
)

args = Args(
    width=40,
    title="Vertical Chart Example",
    colors=[Colors.Cyan]
)

chart = VerticalChart(data, args)
chart.draw()
```

--------------------------------

### Histogram Configuration

Source: https://github.com/mkaz/termgraph/blob/main/docs/args-class.md

Configure histogram settings, including the number of bins and custom colors.

```python
from termgraph import Args, Colors

# Histogram settings
args = Args(
    width=60,
    title="Data Distribution",
    histogram=True,
    bins=10,
    colors=[Colors.Cyan],
    format="{:<3.0f}"
)
```

--------------------------------

### Run Specific Test File with 'just'

Source: https://github.com/mkaz/termgraph/blob/main/CONTRIBUTING.md

Execute a specific test file using the 'just' command runner. Replace <file> with the target test file name.

```bash
just test-file <file>   # Run specific test file
```

--------------------------------

### Create a Complex Multi-Series Bar Chart

Source: https://github.com/mkaz/termgraph/blob/main/docs/chart-classes.md

Demonstrates creating a complex bar chart with multiple data series representing regional sales performance across different quarters. Uses custom colors, suffixes, and formatting.

```python
from termgraph import Data, BarChart, Args, Colors

# Sales data across multiple regions and quarters
data = Data(
    data=[
        [150, 120, 90],   # Q1: North, South, West
        [180, 140, 110],  # Q2: North, South, West
        [200, 160, 130],  # Q3: North, South, West
        [220, 180, 150]   # Q4: North, South, West
    ],
    labels=["Q1 2023", "Q2 2023", "Q3 2023", "Q4 2023"],
    categories=["North Region", "South Region", "West Region"]
)

args = Args(
    width=60,
    title="Regional Sales Performance",
    colors=[Colors.Blue, Colors.Green, Colors.Yellow],
    space_between=True,
    suffix="K",
    format="{:<5.0f}"
)

chart = BarChart(data, args)
chart.draw()
```

--------------------------------

### Initialize Data Class with Multi-Series Data

Source: https://github.com/mkaz/termgraph/blob/main/docs/data-class.md

Use this to create a Data object for charts with multiple data series, providing labels for each data point and names for each category.

```python
from termgraph import Data

# With categories for multi-series data
data = Data(
    data=[[10, 15], [20, 25], [30, 35], [40, 45]],
    labels=["Q1", "Q2", "Q3", "Q4"],
    categories=["Product A", "Product B"]
)
```

--------------------------------

### Format Values as Percentages

Source: https://github.com/mkaz/termgraph/blob/main/docs/args-class.md

Enable percentage formatting for chart values by setting 'percentage' to True. Values will be multiplied by 100 and displayed with a '%' sign.

```python
# Convert 0.75 to 75%
args = Args(percentage=True)
```

--------------------------------

### Normalize Data with Data.normalize()

Source: https://context7.com/mkaz/termgraph/llms.txt

Demonstrates the Data.normalize() method for scaling data values to fit a target character width. It covers flat and nested data normalization, and how negative values are handled by shifting before scaling.

```python
from termgraph import Data

# Flat normalization
d = Data([10, 20, 30, 40], ["Q1", "Q2", "Q3", "Q4"])
print(d.normalize(50))    # [12.5, 25.0, 37.5, 50.0]

# Nested normalization
d2 = Data([[10, 15], [20, 25], [30, 35]], ["X", "Y", "Z"])
print(d2.normalize(40))
# [[11.43, 17.14], [22.86, 28.57], [34.29, 40.0]]  (approx)

# Negative values: shifted before scaling
d3 = Data([-10, 0, 10, 20], ["A", "B", "C", "D"])
print(d3.normalize(30))   # [0.0, 10.0, 20.0, 30.0]
```

--------------------------------

### Vertical Chart Configuration

Source: https://github.com/mkaz/termgraph/blob/main/docs/args-class.md

Set up a vertical bar chart (column chart) with specified dimensions and colors.

```python
from termgraph import Args, Colors

# Column chart setup
args = Args(
    width=30,
    title="Vertical Sales Chart",
    vertical=True,
    colors=[Colors.Blue],
    no_labels=False
)
```

--------------------------------

### Args class

Source: https://context7.com/mkaz/termgraph/llms.txt

Args centralises all chart configuration. All parameters are optional keyword arguments; unknown keys raise an exception immediately. Use get_arg() to read values and update_args() to modify after construction.

```APIDOC
## Args class

`Args` centralises all chart configuration. All parameters are optional keyword arguments; unknown keys raise an exception immediately. Use `get_arg()` to read values and `update_args()` to modify after construction.

### Usage
```python
from termgraph import Args, Colors

# All defaults
args = Args()

# Full configuration example
args = Args(
    title="Q4 Performance",
    width=60,                     # chart width in characters (default 50)
    format="{:>8.2f}",            # Python format string for values
    suffix=" units",              # appended to every printed value
    no_labels=False,              # True = hide row labels
    no_values=False,              # True = hide numeric values
    space_between=True,           # blank line between bars
    colors=[Colors.Green, Colors.Blue],  # per-series ANSI colors
    label_before=False,           # True = print label before bar
    percentage=False,             # True = multiply value × 100 and add %
    no_readable=False,            # True = disable auto K/M/B abbreviation
    custom_tick="▓",              # override default ▇ tick character
    different_scale=False,        # True = normalize each series independently
    stacked=False,                # True = stacked bar mode
    histogram=False,              # True = histogram mode
    bins=5,                       # number of histogram bins
    vertical=False,               # True = vertical column chart
)

# Read and update
print(args.get_arg("width"))      # 60
args.update_args(width=80, title="Updated")
print(args.get_arg("title"))      # "Updated"

# Invalid arg raises immediately
try:
    Args(unknown_option=True)
except Exception as e:
    print(e)   # "Invalid Argument: unknown_option"

# Available color constants
# Colors.Black, Colors.Red, Colors.Green, Colors.Yellow
# Colors.Blue, Colors.Magenta, Colors.Cyan
# (correspond to ANSI SGR codes 90–96)
```
```

--------------------------------

### Create and Draw Different Chart Types

Source: https://github.com/mkaz/termgraph/blob/main/docs/chart-classes.md

Instantiate and draw various chart types (Bar, Stacked, Vertical) using the same data and arguments. Ensure data and args are prepared beforehand.

```python
print("=== Bar Chart ===")
bar_chart = BarChart(data, args)
bar_chart.draw()
```

```python
print("\n=== Stacked Chart ===")
stacked_chart = StackedChart(data, args)
stacked_chart.draw()
```

```python
print("\n=== Vertical Chart ===")
vertical_chart = VerticalChart(data, args)
vertical_chart.draw()
```

--------------------------------

### Format Currency Values

Source: https://github.com/mkaz/termgraph/blob/main/docs/README.md

Configure a custom format string and suffix to display values as currency.

```python
args = Args(format="{:<6.2f}", suffix=" USD")
```