Initial commit: sales analysis template

Co-authored-by: Cursor <cursoragent@cursor.com>

EXAMPLES.md

@@ -0,0 +1,203 @@
+# 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