diff --git a/plots/pygal/line/area-basic/default.py b/plots/pygal/line/area-basic/default.py new file mode 100644 index 0000000000..ada256822c --- /dev/null +++ b/plots/pygal/line/area-basic/default.py @@ -0,0 +1,147 @@ +""" +area-basic: Basic Area Chart +Implementation for: pygal +Variant: default +Python: 3.10+ +""" + +from typing import TYPE_CHECKING, Optional + +import pandas as pd +import pygal +from pygal.style import Style + + +if TYPE_CHECKING: + from pygal import Line + + +def create_plot( + data: pd.DataFrame, + x: str, + y: str, + title: Optional[str] = None, + xlabel: Optional[str] = None, + ylabel: Optional[str] = None, + fill_alpha: float = 0.5, + color: Optional[str] = None, + show_line: bool = True, + width: int = 1600, + height: int = 900, + **kwargs, +) -> "Line": + """ + Create a basic area chart showing a filled area under a line using pygal. + + An area chart displays a single data series as a filled region beneath + a line, ideal for showing trends while emphasizing magnitude. + + Args: + data: Input DataFrame with required columns + x: Column name for x-axis values (categories/labels) + y: Column name for y-axis numeric values + title: Chart title (optional) + xlabel: Custom x-axis label (optional, defaults to column name) + ylabel: Custom y-axis label (optional, defaults to column name) + fill_alpha: Transparency of the filled area (default: 0.5) + color: Color for the line and fill (optional) + show_line: Whether to show the line on top of fill (default: True) + width: Figure width in pixels (default: 1600) + height: Figure height in pixels (default: 900) + **kwargs: Additional parameters for pygal configuration + + Returns: + pygal Line chart object configured as an area chart + + Raises: + ValueError: If data is empty + KeyError: If required columns not found + + Example: + >>> data = pd.DataFrame({ + ... 'Month': ['Jan', 'Feb', 'Mar', 'Apr', 'May'], + ... 'Sales': [100, 150, 130, 180, 200] + ... }) + >>> chart = create_plot(data, x='Month', y='Sales') + """ + # Input validation + if data.empty: + raise ValueError("Data cannot be empty") + + # Check required columns + for col in [x, y]: + if col not in data.columns: + available = ", ".join(data.columns) + raise KeyError(f"Column '{col}' not found. Available columns: {available}") + + # Define colors - use provided color or default + primary_color = color or "#3498db" + + # Create custom style with appropriate opacity for fill + custom_style = Style( + background="white", + plot_background="white", + foreground="#333", + foreground_strong="#333", + foreground_subtle="#555", + opacity=fill_alpha, + opacity_hover=min(fill_alpha + 0.2, 1.0), + colors=(primary_color,), + font_family="Arial, sans-serif", + major_guide_stroke_dasharray="3,3", + guide_stroke_dasharray="1,1", + ) + + # Create line chart with fill enabled (makes it an area chart) + chart = pygal.Line( + title=title or "Area Chart", + x_title=xlabel or x, + y_title=ylabel or y, + width=width, + height=height, + fill=True, # This enables the area fill + show_legend=True, + style=custom_style, + show_x_guides=True, + show_y_guides=True, + dots_size=3 if show_line else 0, + stroke_style={"width": 2} if show_line else {"width": 0}, + **kwargs, + ) + + # Set x-axis labels + x_values = data[x].tolist() + chart.x_labels = [str(val) for val in x_values] + + # Add the data series + y_values = data[y].tolist() + series_label = ylabel or y + chart.add(series_label, y_values) + + return chart + + +if __name__ == "__main__": + # Sample data for testing - monthly website traffic + data = pd.DataFrame( + { + "Month": ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"], + "Visitors": [12000, 15000, 18000, 22000, 25000, 28000, 30000, 32000, 29000, 26000, 23000, 20000], + } + ) + + # Create plot + chart = create_plot( + data, + x="Month", + y="Visitors", + title="Monthly Website Traffic", + xlabel="Month", + ylabel="Number of Visitors", + fill_alpha=0.5, + color="#2ecc71", + ) + + # Save as PNG + chart.render_to_png("plot.png") + print("Plot saved to plot.png") diff --git a/specs/area-basic.md b/specs/area-basic.md index 3e1ad73cd8..02566f39db 100644 --- a/specs/area-basic.md +++ b/specs/area-basic.md @@ -4,43 +4,45 @@ ## Description -A simple filled area chart showing a single data series over time or sequential x-values. The area between the data line and the baseline (typically zero) is filled with a semi-transparent color to emphasize the magnitude of values. +A basic area chart displays a single data series as a filled area under a line, connecting data points in sequence. This visualization is ideal for showing trends over time while emphasizing the magnitude of values through the filled region beneath the line. ## Data Requirements -- **x**: Sequential or time-series values for the x-axis (numeric or datetime) -- **y**: Numeric values to plot on the y-axis +- **x**: Sequential values for the x-axis (numeric or categorical representing order/time) +- **y**: Numeric values for the y-axis representing the magnitude at each point ## Optional Parameters -- `fill_alpha`: Transparency of the filled area (type: float, default: 0.5) -- `line_color`: Color of the line and fill (type: str, default: library default) - `title`: Chart title (type: str, default: None) -- `x_label`: Label for x-axis (type: str, default: column name) -- `y_label`: Label for y-axis (type: str, default: column name) +- `xlabel`: X-axis label (type: str, default: column name) +- `ylabel`: Y-axis label (type: str, default: column name) +- `fill_alpha`: Transparency of the filled area (type: float, default: 0.5) +- `color`: Color for the line and fill (type: str, default: library default) +- `show_line`: Whether to show the line on top of fill (type: bool, default: True) ## Quality Criteria -- [ ] X and Y axes are labeled with meaningful names -- [ ] Grid is visible but subtle (alpha <= 0.5) -- [ ] Area fill is semi-transparent (alpha between 0.3 and 0.7) -- [ ] Line on top of fill area is visible +- [ ] X and Y axes are labeled with meaningful descriptions +- [ ] The filled area is clearly visible with appropriate transparency (alpha ~0.5) +- [ ] The line connecting data points is visible on top of the fill +- [ ] Grid is present but subtle (alpha ≤ 0.5) - [ ] No overlapping axis labels or tick marks -- [ ] Data accurately represented without distortion -- [ ] Figure has appropriate size (16:9 aspect ratio) +- [ ] Fill extends from the line to the baseline (y=0 or bottom axis) +- [ ] Data points are accurately represented without distortion ## Expected Output -A clean area chart with a filled region between the data line and the x-axis baseline. The fill should be semi-transparent to allow grid lines to show through slightly. The line defining the top of the area should be clearly visible. Axes should be properly labeled, and a subtle grid should aid in reading values. +A single area chart showing one data series with a filled region beneath the line. The line should be clearly visible on top of the semi-transparent fill. The fill should extend from the data line down to the x-axis baseline. The chart should include proper axis labels, a subtle grid for readability, and optionally a title. The overall appearance should be clean and professional, suitable for showing trends or cumulative data over a sequence. ## Tags -area, trend, time-series, basic, 2d +area, trend, timeseries, basic, 2d, composition ## Use Cases -- Visualizing website traffic over time -- Showing cumulative sales or revenue trends -- Displaying stock price history with emphasis on magnitude -- Monitoring system resource usage over time -- Tracking temperature or weather data trends +- Visualizing website traffic over time with emphasis on volume +- Showing cumulative sales or revenue trends over months/quarters +- Displaying temperature variations throughout a day +- Tracking stock price movements with visual volume emphasis +- Monitoring system resource usage (CPU, memory) over time +- Illustrating population growth or decline over years