# LTM (Last Twelve Months) Methodology Rules

## ⭐ RECOMMENDED: Use analysis_utils.py

**Prefer utility functions:**
```python
from analysis_utils import get_ltm_period_config, get_annual_data, calculate_annual_metrics
from config import get_ltm_period, get_ltm_label

ltm_start, ltm_end = get_ltm_period_config()
year_data, year_label = get_annual_data(df, 2025, ltm_start, ltm_end)
```

## What is LTM?

**LTM (Last Twelve Months)** = Rolling 12-month period for the most recent partial year
- **Purpose:** Apples-to-apples comparison with full calendar years
- **Example:** If latest data is through September 2025, use Oct 2024 - Sep 2025 (12 months)

## When to Use LTM

- **Full calendar years (2021-2024):** Use complete year data
- **Most recent partial year (2025):** Use LTM if you only have partial year data
- **Complete years only:** Disable LTM in config if all years are complete

## Configuration

**Configure in config.py:**
```python
LTM_ENABLED = True  # Set to False if all years are complete
LTM_START_MONTH = 10  # Month number (1-12)
LTM_START_YEAR = 2024
LTM_END_MONTH = 9
LTM_END_YEAR = 2025
```

## Implementation Pattern

```python
from analysis_utils import get_ltm_period_config, get_annual_data

ltm_start, ltm_end = get_ltm_period_config()

for year in sorted(df['Year'].unique()):
    year_data, year_label = get_annual_data(df, year, ltm_start, ltm_end)
    # year_label will be "2025 (LTM 9/2025)" for LTM year, or "2025" for regular year
```

## Labeling Requirements

**ALWAYS label LTM year with notation in:**
- Chart titles
- Chart x-axis labels
- Table headers
- Print statements
- Report text

**Example:**
```python
from config import get_ltm_label

ltm_label = get_ltm_label()  # Returns "2025 (LTM 9/2025)" or None
if ltm_label:
    title = f'Annual Revenue Trend\n({ltm_label})'
```

## Common Mistakes

❌ **WRONG:**
```python
year_2025_data = df[df['Year'] == 2025]  # Uses partial year (not comparable)
```

✅ **CORRECT:**
```python
from analysis_utils import get_annual_data
ltm_start, ltm_end = get_ltm_period_config()
year_2025_data, year_label = get_annual_data(df, 2025, ltm_start, ltm_end)
```

## Disabling LTM

If all years in your analysis are complete calendar years:
```python
# In config.py:
LTM_ENABLED = False
```

Then all years will be treated as full calendar years.