sales-data-analysis/EXAMPLES.md

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:

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:

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:

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:

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:

python generate_sample_data.py

Step 3: Run Example

python examples/annual_revenue_trend.py

Step 4: Customize

Copy an example script and modify it for your needs:

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

---

Example Patterns

Pattern 1: Simple Annual Analysis

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

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

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