# Quick Start Guide

**For Cursor Users:** This template is optimized for Cursor AI. Just ask: *"Create a revenue analysis using the template"* and the AI will handle everything.

## 🚀 Get Started in 5 Minutes

### Step 1: Install Dependencies
```bash
pip install -r requirements.txt
```

### Step 2: Run Setup Wizard
```bash
python setup_wizard.py
```

The wizard will ask you:
- Company name
- Data file location
- Column names in your CSV
- Date range
- LTM configuration (if needed)

### Step 3: Test Data Loading
```bash
python -c "from data_loader import load_sales_data; from config import get_data_path; df = load_sales_data(get_data_path()); print(f'✓ Loaded {len(df):,} rows')"
```

### Step 4: Run Example Analysis (Recommended)
```bash
# Try an example first to see how it works
python examples/annual_revenue_trend.py
```

### Step 5: Create Your First Analysis
```bash
cp analysis_template.py my_analysis.py
# Or copy an example
cp examples/annual_revenue_trend.py my_analysis.py
# Edit my_analysis.py
python my_analysis.py
```

---

## 📋 Essential Configuration Checklist

Before running analyses, verify in `config.py`:

- [ ] `COMPANY_NAME` - Your company name
- [ ] `DATA_FILE` - Your CSV filename
- [ ] `REVENUE_COLUMN` - Your revenue column name
- [ ] `DATE_COLUMN` - Your date column name
- [ ] `CUSTOMER_COLUMN` - Your customer column name
- [ ] `ANALYSIS_YEARS` - Years to include
- [ ] `MIN_YEAR` and `MAX_DATE` - Date range
- [ ] `LTM_ENABLED` - Set to False if all years complete

---

## 💡 Common Patterns

### Load Data
```python
from data_loader import load_sales_data
from config import get_data_path

df = load_sales_data(get_data_path())
```

### Calculate Annual Metrics
```python
from analysis_utils import calculate_annual_metrics, get_ltm_period_config
from config import REVENUE_COLUMN

ltm_start, ltm_end = get_ltm_period_config()

def calculate_metrics(year_data):
    return {'Revenue': year_data[REVENUE_COLUMN].sum()}

annual_df = calculate_annual_metrics(df, calculate_metrics, ltm_start, ltm_end)
```

### Create Chart
```python
from analysis_utils import setup_revenue_chart, save_chart
from config import CHART_SIZES
import matplotlib.pyplot as plt

fig, ax = plt.subplots(figsize=CHART_SIZES['medium'])
ax.plot(data / 1e6, ...)  # Divide by 1e6!
setup_revenue_chart(ax)
save_chart(fig, 'chart.png')
plt.close()
```

---

## ⚠️ Critical Rules

1. **ALWAYS use `data_loader.py`** - Never `pd.read_csv()` directly
2. **ALWAYS divide by 1e6** before plotting revenue
3. **ALWAYS use `setup_revenue_chart()`** for revenue charts
4. **ALWAYS use config values** - Never hardcode column names
5. **ALWAYS validate data** after loading

## 💡 New Utilities

### Data Quality Check
```bash
python -c "from data_quality import generate_data_quality_report, print_data_quality_report; from data_loader import load_sales_data; from config import get_data_path; df = load_sales_data(get_data_path()); report = generate_data_quality_report(df); print_data_quality_report(report)"
```

### Configuration Validation
```bash
python config_validator.py
```

### Export Results
```python
from export_utils import export_to_excel
export_to_excel(df, 'results.xlsx')
```

### Generate Sample Data
```bash
python generate_sample_data.py
```

---

## 🐛 Quick Troubleshooting

**"Data file not found"**
→ Check `DATA_FILE` in config.py

**"Column not found"**
→ Update column mappings in config.py

**Charts show 1e8 (scientific notation)**
→ Divide by 1e6 before plotting: `ax.plot(data / 1e6, ...)`

**"DataFrame is empty"**
→ Check `MIN_YEAR`, `MAX_DATE`, and `ANALYSIS_YEARS` in config.py

---

## 🎯 Using Cursor AI (Recommended)

This template is optimized for Cursor. Instead of manual setup, just ask:

```
"Create a revenue trend analysis using template patterns"
```

The AI will:
- ✅ Use all template utilities automatically
- ✅ Follow best practices
- ✅ Include proper validation
- ✅ Generate production-ready code

**See:** `.cursor/rules/ai_assistant_guide.md` for complete prompt library

## 📚 Next Steps

- **Run examples:** Try `examples/annual_revenue_trend.py` to see it in action
- **Check data quality:** Run `python data_quality.py` to analyze your data
- **Validate config:** Run `python config_validator.py` to check configuration
- **Read documentation:** See `README.md` for comprehensive guide
- **Review patterns:** Check `.cursor/rules/` for detailed patterns
- **See examples:** Check `EXAMPLES.md` for example script guide

---

**Need help?** Check `.cursor/rules/common_errors.md` for detailed troubleshooting.