A library for creating quadrant charts with base64 output
Project description
Quadrant Generator
A Python library for creating quadrant charts with customizable labels and data points, optimized for web applications and API integrations.
Features
- Create quadrant charts from CSV strings or data points
- Customizable axis labels and titles
- Automatic text positioning to prevent overlap
- Generate base64-encoded images for easy web integration
- Clean, minimalist design
Installation
From Source
# Clone the repository
git clone https://github.com/ceccode/quadrant-gen.git
cd quadrant-gen
# Install the package
pip install -e .
Using pip
pip install quadrant-gen
Usage
The library is designed to be used programmatically in your Python applications, particularly for web applications and APIs.
CSV Format
Your CSV file should have the following columns:
name: Name of the data pointdescription: Description of the data pointx: X-coordinate (0.0 to 1.0)y: Y-coordinate (0.0 to 1.0)
Example:
name,description,x,y
Product A,High quality,0.2,0.8
Product B,Low cost,0.7,0.3
Python API
Using CSV String Input
from quadrant_gen.chart import csv_to_quadrant_chart
# CSV string with your data
csv_string = """
name,description,x,y
Product A,High quality,0.2,0.8
Product B,Low cost,0.7,0.3
"""
# Generate chart directly to base64-encoded image
base64_image = csv_to_quadrant_chart(
csv_string=csv_string,
title="My Quadrant Chart",
x_left="Low X",
x_right="High X",
y_bottom="Low Y",
y_top="High Y",
format="png" # or "pdf"
)
# Use the base64 image in HTML
html = f'<img src="{base64_image}" alt="Quadrant Chart">'
Using Data Points
from quadrant_gen.chart import generate_quadrant_chart, sample_points
# Use sample data
points = sample_points()
# Or create your own data
points = [
{"label": "Item 1\n(Description)", "x": 0.2, "y": 0.8},
{"label": "Item 2\n(Description)", "x": 0.7, "y": 0.3},
]
# Generate chart directly to base64-encoded image
base64_image = generate_quadrant_chart(
points=points,
title="My Quadrant Chart",
x_left="Low X",
x_right="High X",
y_bottom="Low Y",
y_top="High Y",
format="png" # or "pdf"
)
Examples
The following examples are included in the repository:
- Simple Integration Example:
examples/integration_example.py- Shows how to use the library in a Python script - Flask API Example:
examples/flask_api_example.py- RESTful API for generating charts - Flask CSV App:
examples/flask_csv_app/- Web application with CSV input form
Integration with Web Applications
The Quadrant Generator is optimized for web applications and API integrations:
Flask Integration Example
# Important: Set matplotlib backend to 'Agg' before importing any matplotlib modules
# This is required for web applications to avoid GUI-related errors
import matplotlib
matplotlib.use('Agg')
from flask import Flask, render_template_string
from quadrant_gen.chart import csv_to_quadrant_chart
app = Flask(__name__)
@app.route('/')
def index():
# Sample CSV data
csv_data = """
name,description,x,y
Product A,High quality,0.2,0.8
Product B,Low cost,0.7,0.3
""".strip()
# Generate chart as base64 image
base64_image = csv_to_quadrant_chart(
csv_string=csv_data,
title="Product Analysis",
x_left="Low Cost", x_right="High Cost",
y_bottom="Low Value", y_top="High Value"
)
# Return HTML with embedded image
return render_template_string("""
<!DOCTYPE html>
<html>
<head>
<title>Quadrant Chart Example</title>
</head>
<body>
<h1>Product Analysis</h1>
<img src="{{ chart }}" alt="Quadrant Chart">
</body>
</html>
""", chart=base64_image)
if __name__ == '__main__':
app.run(debug=True)
Note: When using Matplotlib in web applications, you must set the backend to a non-interactive one like 'Agg' before importing any Matplotlib modules. This prevents GUI-related errors, especially on macOS where GUI operations must be on the main thread.
See the complete Flask integration example in examples/flask_api_example.py.
Flask CSV Web Application
The repository includes a complete web application for generating quadrant charts from CSV data:
# Run the Flask CSV app
cd examples/flask_csv_app
python app.py
# Then open http://127.0.0.1:5001/ in your browser
This application provides:
- A form for entering CSV data
- Options to customize chart title and axis labels
- Preview of the generated chart
- Download options for PNG or PDF formats
See examples/flask_csv_app/ for the complete application.
API Integration
The library is perfect for API services that need to generate charts on-the-fly:
# In a FastAPI application
from fastapi import FastAPI, Response
from pydantic import BaseModel
from quadrant_gen.chart import csv_to_quadrant_chart
app = FastAPI()
class ChartRequest(BaseModel):
csv_data: str
title: str = "Quadrant Chart"
x_left: str = "Low X"
x_right: str = "High X"
y_bottom: str = "Low Y"
y_top: str = "High Y"
@app.post("/generate-chart/")
async def generate_chart(request: ChartRequest):
# Generate base64 image
base64_image = csv_to_quadrant_chart(
csv_string=request.csv_data,
title=request.title,
x_left=request.x_left,
x_right=request.x_right,
y_bottom=request.y_bottom,
y_top=request.y_top
)
# Return JSON with the base64 image
return {"chart_data": base64_image}
Output Formats
The library generates base64-encoded images in two formats:
- PNG: Web-friendly format for digital display
- PDF: Vector format for high-quality printing and scaling
Contributing
For Developers
If you're a developer looking to contribute or maintain this package:
- See PUBLISHING.md for instructions on how to build and publish new versions to PyPI
License
MIT
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file quadrant_gen-0.2.0.tar.gz.
File metadata
- Download URL: quadrant_gen-0.2.0.tar.gz
- Upload date:
- Size: 6.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3af95ff3e400c26c07168ac9f4863b40305971a1ec3a2cc21cc5796448217e5e
|
|
| MD5 |
6f14320c86f657c1c58336d38a33f1d9
|
|
| BLAKE2b-256 |
5ccf7fd84d55db1085b499a91526e849727ffaa0a64b5c2521c1d19370f1177d
|
File details
Details for the file quadrant_gen-0.2.0-py3-none-any.whl.
File metadata
- Download URL: quadrant_gen-0.2.0-py3-none-any.whl
- Upload date:
- Size: 6.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.0
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
9f00035acbe21addea62885afa983656b17951d0a06c085e32637960e2402243
|
|
| MD5 |
2175c25390cc60bb5e638dfdba64471d
|
|
| BLAKE2b-256 |
150838ede2369056ceb0ed1bb6a39df165221f07ffa0a5c0054be04eb8d8a512
|
