204 lines
4.8 KiB
Markdown
204 lines
4.8 KiB
Markdown
# 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
|