# Example Analysis Scripts

This directory contains working example analysis scripts that demonstrate how to use the sales analysis template framework.

## Available Examples

### 1. Annual Revenue Trend (`examples/annual_revenue_trend.py`)

**Purpose:** Simple annual revenue analysis with LTM support

**What it demonstrates:**
- Loading data using `data_loader`
- Calculating annual metrics with LTM
- Creating a revenue trend chart
- Following template best practices

**Usage:**
```bash
python examples/annual_revenue_trend.py
```

**Output:**
- Chart: `charts/annual_revenue_trend.png`
- Console output with annual revenue summary

---

### 2. Customer Segmentation (`examples/customer_segmentation.py`)

**Purpose:** Customer segmentation using RFM (Recency, Frequency, Monetary) methodology

**What it demonstrates:**
- Customer-level aggregation
- RFM scoring and segmentation
- Segment analysis and visualization
- Multiple chart generation

**Usage:**
```bash
python examples/customer_segmentation.py
```

**Output:**
- Chart: `charts/customer_segmentation.png`
- Console output with segment summary

**Segments:**
- **Champions:** High recency, frequency, and monetary value
- **Loyal Customers:** Regular customers with good value
- **At Risk:** Recent but declining frequency
- **Hibernating:** Low recency, may need reactivation
- **Potential Loyalists:** Good recency and frequency, lower value
- **Need Attention:** Mixed signals, need engagement

---

### 3. Product Performance (`examples/product_performance.py`)

**Purpose:** Product mix and performance analysis

**What it demonstrates:**
- Product-level aggregation
- Product performance metrics
- Top products identification
- Product mix visualization

**Usage:**
```bash
python examples/product_performance.py
```

**Output:**
- Chart: `charts/product_performance.png`
- Console output with top products summary

---

## How to Use Examples

### Step 1: Configure Template

Before running examples, ensure your template is configured:

```bash
python setup_wizard.py
```

Or manually update `config.py` with your data file and column mappings.

### Step 2: Prepare Data

Place your sales data CSV file in the template directory, or update `DATA_DIR` in `config.py`.

Alternatively, generate sample data for testing:

```bash
python generate_sample_data.py
```

### Step 3: Run Example

```bash
python examples/annual_revenue_trend.py
```

### Step 4: Customize

Copy an example script and modify it for your needs:

```bash
cp examples/annual_revenue_trend.py my_analysis.py
# Edit my_analysis.py
python my_analysis.py
```

---

## Example Patterns

### Pattern 1: Simple Annual Analysis

```python
from data_loader import load_sales_data
from analysis_utils import calculate_annual_metrics, get_ltm_period_config
from config import REVENUE_COLUMN

df = load_sales_data(get_data_path())
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)
```

### Pattern 2: Customer-Level Analysis

```python
from config import CUSTOMER_COLUMN, REVENUE_COLUMN

customer_metrics = df.groupby(CUSTOMER_COLUMN).agg({
    REVENUE_COLUMN: 'sum',
    DATE_COLUMN: 'count'
}).reset_index()
```

### Pattern 3: Product-Level Analysis

```python
from config import ITEM_COLUMN, REVENUE_COLUMN

product_metrics = df.groupby(ITEM_COLUMN)[REVENUE_COLUMN].sum().sort_values(ascending=False)
top_10 = product_metrics.head(10)
```

---

## Learning Path

1. **Start with:** `annual_revenue_trend.py` - Simplest example
2. **Then try:** `product_performance.py` - More complex aggregation
3. **Advanced:** `customer_segmentation.py` - Multi-step analysis with custom logic

---

## Troubleshooting

**"Module not found" errors:**
- Ensure you're running from the template root directory
- Check that all template files are present

**"Data file not found" errors:**
- Run `setup_wizard.py` to configure data file path
- Or update `DATA_FILE` in `config.py`

**"Column not found" errors:**
- Update column mappings in `config.py`
- Run `python config_validator.py` to check configuration

---

## Advanced Examples

For more sophisticated analyses, see:
- `.cursor/rules/advanced_analysis_patterns.md` - Advanced analysis patterns
- `.cursor/rules/ai_assistant_guide.md` - How to use Cursor AI effectively

## Next Steps

After running examples:

1. Review the generated charts
2. Examine the code to understand patterns
3. Copy an example and customize for your analysis
4. Check `.cursor/rules/analysis_patterns.md` for more patterns
5. Read `.cursor/rules/advanced_analysis_patterns.md` for advanced techniques
6. Use Cursor AI with prompts from `ai_assistant_guide.md`
7. Read `README.md` for comprehensive documentation

---

**Last Updated:** January 2026  
**Template Version:** 1.0