diff --git a/plots/matplotlib/fill_between/area-basic/default.py b/plots/matplotlib/fill_between/area-basic/default.py new file mode 100644 index 0000000000..b0a650a12c --- /dev/null +++ b/plots/matplotlib/fill_between/area-basic/default.py @@ -0,0 +1,126 @@ +""" +area-basic: Basic Area Chart +Implementation for: matplotlib +Variant: default +Python: 3.10+ +""" + +from typing import TYPE_CHECKING, Optional + +import matplotlib.pyplot as plt +import pandas as pd + + +if TYPE_CHECKING: + from matplotlib.figure import Figure + + +def create_plot( + data: pd.DataFrame, + x: str, + y: str, + color: str = "steelblue", + alpha: float = 0.4, + line_color: Optional[str] = None, + line_width: float = 2.0, + title: Optional[str] = None, + xlabel: Optional[str] = None, + ylabel: Optional[str] = None, + figsize: tuple[float, float] = (16, 9), + **kwargs, +) -> "Figure": + """ + Create a basic area chart showing a filled region between the x-axis and a line. + + Args: + data: Input DataFrame with required columns + x: Column name for x-axis values (continuous sequence) + y: Column name for y-axis values (numeric values) + color: Fill color for the area (default: "steelblue") + alpha: Transparency level for the filled area 0.0-1.0 (default: 0.4) + line_color: Color of the top edge line (default: same as fill color) + line_width: Width of the top edge line (default: 2.0) + title: Plot title (default: None) + xlabel: Custom x-axis label (default: column name) + ylabel: Custom y-axis label (default: column name) + figsize: Figure size as (width, height) (default: (16, 9)) + **kwargs: Additional parameters passed to ax.fill_between() + + Returns: + Matplotlib Figure object + + Raises: + ValueError: If data is empty + KeyError: If required columns not found + + Example: + >>> data = pd.DataFrame({'Time': [1, 2, 3, 4, 5], 'Value': [10, 25, 15, 30, 20]}) + >>> fig = create_plot(data, x='Time', y='Value') + """ + # 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: {available}") + + # Create figure + fig, ax = plt.subplots(figsize=figsize) + + # Get data values + x_values = data[x] + y_values = data[y] + + # Determine line color (default to fill color if not specified) + edge_color = line_color if line_color else color + + # Plot the filled area + ax.fill_between(x_values, y_values, alpha=alpha, color=color, **kwargs) + + # Plot the top edge line for clarity + ax.plot(x_values, y_values, color=edge_color, linewidth=line_width) + + # Apply styling + ax.set_xlabel(xlabel or x) + ax.set_ylabel(ylabel or y) + ax.grid(True, alpha=0.3, linestyle="--") + + # Title + if title: + ax.set_title(title, fontsize=14, fontweight="bold") + + # Tight layout to avoid label clipping + plt.tight_layout() + + return fig + + +if __name__ == "__main__": + # Sample data for testing - simulating 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, 32000, 30000, 27000, 24000, 20000, 18000], + } + ) + + # For a proper area chart, we need numeric x values + # Convert month names to numeric positions for continuous x-axis + data["Month_Num"] = range(1, 13) + + # Create plot + fig = create_plot( + data, x="Month_Num", y="Visitors", title="Monthly Website Traffic", xlabel="Month", ylabel="Number of Visitors" + ) + + # Customize x-ticks to show month names + ax = fig.axes[0] + ax.set_xticks(range(1, 13)) + ax.set_xticklabels(data["Month"]) + + # Save for inspection + plt.savefig("plot.png", dpi=300, bbox_inches="tight") + print("Plot saved to plot.png") diff --git a/specs/area-basic.md b/specs/area-basic.md new file mode 100644 index 0000000000..89e024be92 --- /dev/null +++ b/specs/area-basic.md @@ -0,0 +1,63 @@ +# area-basic: Basic Area Chart + + + +**Spec Version:** 1.0.0 + +## Description + +Create a simple area chart showing a filled region between the x-axis and a line. +Perfect for visualizing quantities over continuous intervals, trends over time, or cumulative values. +Works with any dataset containing a continuous x variable and numeric y values. + +## Data Requirements + +- **x**: Values for the x-axis (numeric or datetime: continuous sequence) +- **y**: Numeric values defining the top of the filled area (numeric: continuous values) + +## Optional Parameters + +- `color`: Fill color for the area (type: string, default: "steelblue") +- `alpha`: Transparency level for the filled area (type: float 0.0-1.0, default: 0.4) +- `line_color`: Color of the top edge line (type: string, default: same as fill color) +- `line_width`: Width of the top edge line (type: float, default: 2.0) +- `title`: Plot title (type: string, default: None) +- `xlabel`: Custom x-axis label (type: string, default: column name) +- `ylabel`: Custom y-axis label (type: string, default: column name) +- `figsize`: Figure size (type: tuple, default: (16, 9)) + +## Quality Criteria + +- [ ] X and Y axes are labeled with column names (or custom labels if provided) +- [ ] Grid is visible but subtle with alpha=0.3 +- [ ] Filled area is clearly visible with appropriate transparency +- [ ] Top edge line is visible and distinguishes the data boundary +- [ ] No overlapping axis labels or tick marks +- [ ] Colorblind-safe colors (use accessible defaults) +- [ ] Appropriate figure size (16x9 default) for readability +- [ ] Title is centered and clearly readable if provided (fontsize 14, bold) + +## Expected Output + +A clean area chart with a filled region extending from the x-axis up to the data values. +The filled area should have moderate transparency to show grid lines underneath while remaining clearly visible. +A solid line along the top edge should clearly define where the data values lie. +The plot should be immediately understandable without additional explanation. +All text elements (labels, title, and tick labels) should be legible at standard display sizes. + +## Tags + +trend, continuous, basic, area, time-series, statistical, exploratory + +## Use Cases + +- Stock price visualization showing value over time (e.g., daily closing prices) +- Website traffic metrics over time (e.g., daily page views) +- Temperature variations throughout a day or season +- Revenue or sales trends over months or years +- Resource utilization over time (e.g., CPU usage, memory consumption) +- Population growth over time periods