sales-data-analysis/QUICK_START.md

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

pip install -r requirements.txt

Step 2: Run Setup Wizard

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

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)

# Try an example first to see how it works
python examples/annual_revenue_trend.py

Step 5: Create Your First Analysis

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

from data_loader import load_sales_data
from config import get_data_path

df = load_sales_data(get_data_path())

Calculate Annual Metrics

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

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

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

python config_validator.py

Export Results

from export_utils import export_to_excel
export_to_excel(df, 'results.xlsx')

Generate Sample Data

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.