# Chart Formatting Rules

## ⭐ RECOMMENDED: Use analysis_utils.py

**Prefer utility functions:**
```python
from analysis_utils import setup_revenue_chart, save_chart, get_millions_formatter
from config import CHART_SIZES, OUTPUT_DIR

fig, ax = plt.subplots(figsize=CHART_SIZES['medium'])
ax.plot(data / 1e6, ...)
setup_revenue_chart(ax)  # Applies formatter automatically
save_chart(fig, 'chart.png')  # Saves to charts/ directory
```

## Revenue Charts: Millions Formatter

**ALWAYS use this pattern for revenue charts:**

```python
from analysis_utils import setup_revenue_chart

# Divide data by 1e6 BEFORE plotting
ax.plot(data / 1e6, ...)
# OR
ax.bar(x, values / 1e6, ...)

# Apply formatter automatically
setup_revenue_chart(ax)
```

**Manual approach (if not using utilities):**
```python
from matplotlib.ticker import FuncFormatter

def millions_formatter(x, pos):
    return f'${x:.1f}m'

ax.plot(data / 1e6, ...)
ax.yaxis.set_major_formatter(FuncFormatter(millions_formatter))
ax.set_ylabel('Revenue (Millions USD)')
```

## Thousands Formatter (for smaller values)

```python
from analysis_utils import get_thousands_formatter

ax.xaxis.set_major_formatter(get_thousands_formatter())
ax.barh(x, values / 1e3, ...)
ax.set_xlabel('Value (Thousands USD)')
```

## Chart Labeling with LTM

**If LTM is enabled, ALWAYS include LTM notation:**

```python
from config import get_ltm_label, COMPANY_NAME

title = f'Annual Revenue Trend - {COMPANY_NAME}'
ltm_label = get_ltm_label()
if ltm_label:
    title += f'\n({ltm_label})'
ax.set_title(title)
```

## Chart Sizes

**Use predefined sizes from config:**
```python
from config import CHART_SIZES

fig, ax = plt.subplots(figsize=CHART_SIZES['medium'])  # (10, 6)
# Options: 'small' (6, 4), 'medium' (10, 6), 'large' (12, 8), 'wide' (14, 6)
```

## Common Mistakes

❌ **WRONG:**
```python
ax.plot(revenue, ...)  # Shows scientific notation (1e8)
```

✅ **CORRECT:**
```python
ax.plot(revenue / 1e6, ...)  # Divide first
setup_revenue_chart(ax)  # Then format
```

## Saving Charts

**ALWAYS use save_chart() utility:**
```python
from analysis_utils import save_chart

save_chart(fig, 'chart_name.png')  # Saves to charts/ with proper settings
plt.close()  # Don't forget to close!
```

## Chart Styling

**Configure style in config.py:**
```python
# In config.py:
CHART_STYLE = 'seaborn-v0_8'  # Options: 'default', 'ggplot', 'seaborn-v0_8'

# In your script:
import matplotlib.pyplot as plt
plt.style.use(CHART_STYLE)  # Apply before creating figures
```