176 lines
4.5 KiB
Markdown
176 lines
4.5 KiB
Markdown
# 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.
|