plotting_style_guide.md

# State of the Bay Plotting Style Guide

This guide ensures consistency across all data visualizations in the State of the Bay project.

## 1. Layout and Sizing

### Figure Dimensions
- Standard plots: `figsize=(12, 8)`
- Panel/faceted plots: `figsize=(15, 2.5 * n_panels)`
- Use `plt.tight_layout()` for proper spacing
- Arrange multi-panel plots vertically for better comparison

## 2. Colors and Visual Elements

### Color Palette
- Use predefined `COLOR_SCALE` for consistency
- Grey tones:
  ```python
  GREY30 = "#4d4d4d"  # Dark grey for titles
  GREY40 = "#666666"  # Medium grey for axes and labels
  ```
- Use alpha transparency (0.5-0.7) for overlays

### Line Styles
- Trend lines: dashed (`--`), red, `alpha=0.7`, `linewidth=1.5`
- Grid lines: light grey, `alpha=0.15`

## 3. Axes and Spines

### Spine Configuration
```python
# Remove unnecessary spines
ax.spines["top"].set_visible(False)
ax.spines["right"].set_visible(False)

# Style bottom spine
ax.spines["bottom"].set_color(GREY40)
ax.spines["bottom"].set_linewidth(0.5)

# Remove tick marks but keep labels
ax.tick_params(axis="both", which="both", length=0, colors=GREY40)
```

## 4. Grid Lines

### Configuration
```python
ax.grid(True, axis="y", alpha=0.15, linestyle="-", color="gray")
```

## 5. Text Elements

### Typography
- Main titles: centered, size 12
- Panel titles: size 10, `color=GREY30`, `pad=10`
- Axis labels: size 10, `color=GREY40`

### Statistics and Annotations
```python
ax.text(
    0.02, 0.98,
    stats_text,
    transform=ax.transAxes,
    verticalalignment="top",
    fontsize=8,
    bbox=dict(facecolor="white", alpha=0.8, edgecolor="none")
)
```

## 6. Data Visualization

### Line Charts
- Include confidence intervals (shaded regions)
- Solid lines for main trends
- Consistent line thickness

### Box Plots
```python
boxplot_props = {
    "patch_artist": True,
    "medianprops": dict(color="black"),
    "flierprops": dict(
        marker="o",
        markerfacecolor=color_scale[idx],
        alpha=0.5,
        markersize=4
    ),
    "boxprops": dict(facecolor=color_scale[idx], alpha=0.6),
    "widths": 0.6
}
```

## 7. Scales and Ranges

### Automatic Log Scaling
```python
use_log_scale = parameter in [
    "Turbidity",
    "Fecal Coliform (MPN)",
    "Total Nitrogen",
    "Total Phosphorus",
]
```

### Best Practices
- Add padding to axis limits
- Use consistent y-axis ranges across comparison panels
- Handle edge cases gracefully

## 8. Function Structure

### Return Values
```python
def plot_function(df: pd.DataFrame, parameter: str) -> tuple[Figure, pd.DataFrame, pd.DataFrame]:
    """
    Create a visualization.

    Parameters:
    -----------
    df : pd.DataFrame
        Input dataframe
    parameter : str
        Parameter to plot

    Returns:
    --------
    tuple[Figure, pd.DataFrame, pd.DataFrame]
        - Figure: Matplotlib figure
        - DataFrame: Raw data used in plot
        - DataFrame: Processed data points
    """
    # ... plotting code ...
    return fig, raw_data, plot_data
```

## 9. Error Handling

### Guidelines
- Handle missing data gracefully
- Include data validation
- Provide appropriate fallbacks for edge cases
- Log warnings for potential issues

## 10. Optional Features

### Configurable Elements
```python
def plot_function(
    df: pd.DataFrame,
    parameter: str,
    show_sem: bool = True,
    show_trend: bool = True,
    panel_chart: bool = False,
    color_scale: list[str] = COLOR_SCALE,
) -> tuple[Figure, pd.DataFrame, pd.DataFrame]:
    """..."""
```

### Common Options
- `show_sem`: Toggle standard error margins
- `show_trend`: Toggle trend lines and statistics
- `panel_chart`: Toggle between single and multi-panel layouts
- `color_scale`: Override default color palette