# Angata KPI Script Updates - 09_calculate_kpis_Angata.R

## Overview
The script has been restructured to focus on **4 required KPIs** for Angata, with legacy KPIs disabled by default but retained for future use.

## Changes Made

### 1. **Script Configuration**
- **File**: `09_calculate_kpis_Angata.R`
- **Toggle Variable**: `ENABLE_LEGACY_KPIS` (default: `FALSE`)
  - Set to `TRUE` to run the 6 original KPIs
  - Set to `FALSE` for Angata's 4 KPIs only

### 2. **Angata KPIs (4 Required)**

#### KPI 1: **Area Change Summary** ✅ REAL DATA
- **File**: Embedded in script as `calculate_area_change_kpi()`
- **Method**: Compares current week CI to previous week CI
- **Classification**:
  - **Improving areas**: Mean change > +0.5 CI units
  - **Stable areas**: Mean change between -0.5 and +0.5 CI units
  - **Declining areas**: Mean change < -0.5 CI units
- **Output**: Hectares, Acres, and % of farm for each category
- **Data Type**: REAL DATA (processed from satellite imagery)

#### KPI 2: **Germination Acreage** ✅ REAL DATA
- **Function**: `calculate_germination_acreage_kpi()`
- **Germination Phase Detection**:
  - **Start germination**: When 10% of field's CI > 2
  - **End germination**: When 70% of field's CI ≥ 2
- **Output**:
  - Count of fields in germination phase
  - Count of fields in post-germination phase
  - Total acres and % of farm for each phase
- **Data Type**: REAL DATA (CI-based, calculated from satellite imagery)

#### KPI 3: **Harvested Acreage** ⚠️ DUMMY DATA
- **Function**: `calculate_harvested_acreage_kpi()`
- **Current Status**: Returns zero values with clear "DUMMY DATA - Detection TBD" label
- **TODO**: Implement harvesting detection logic
  - Likely indicators: CI drops below 1.5, sudden backscatter change, etc.
- **Output Format**: 
  - Number of harvested fields
  - Total acres
  - % of farm
  - Clearly marked as DUMMY DATA in output table

#### KPI 4: **Mature Acreage** ⚠️ DUMMY DATA
- **Function**: `calculate_mature_acreage_kpi()`
- **Current Status**: Returns zero values with clear "DUMMY DATA - Definition TBD" label
- **Concept**: Mature fields have high and stable CI for several weeks
- **TODO**: Implement stability-based maturity detection
  - Calculate CI trend over last 3-4 weeks per field
  - Stability metric: low CV over period, high CI relative to field max
  - Threshold: e.g., field reaches 80%+ of max CI and stable for 3+ weeks
- **Output Format**:
  - Number of mature fields
  - Total acres
  - % of farm
  - Clearly marked as DUMMY DATA in output table

### 3. **Legacy KPIs (Disabled by Default)**

These original 6 KPIs are **disabled** but code is preserved for future use:
1. Field Uniformity Summary
2. TCH Forecasted
3. Growth Decline Index
4. Weed Presence Score
5. Gap Filling Score

To enable: Set `ENABLE_LEGACY_KPIS <- TRUE` in the script

### 4. **Output & Logging**

#### Console Output (STDOUT)
```
=== ANGATA KPI CALCULATION SUMMARY ===
Report Date: [date]
Current Week: [week]
Previous Week: [week]
Total Fields Analyzed: [count]
Project: [project_name]
Calculation Time: [timestamp]
Legacy KPIs Enabled: FALSE

--- REQUIRED ANGATA KPIs ---

1. Area Change Summary (REAL DATA):
   [table]

2. Germination Acreage (CI-based, REAL DATA):
   [table]

3. Harvested Acreage (DUMMY DATA - Detection TBD):
   [table with "DUMMY" marker]

4. Mature Acreage (DUMMY DATA - Definition TBD):
   [table with "DUMMY" marker]

=== ANGATA KPI CALCULATION COMPLETED ===
```

#### File Output (RDS)
- **Location**: `laravel_app/storage/app/[project]/reports/kpis/`
- **Filename**: `[project]_kpi_summary_tables_week[XX].rds`
- **Contents**:
  - `area_change_summary`: Summary table
  - `germination_summary`: Summary table
  - `harvested_summary`: Summary table (DUMMY)
  - `mature_summary`: Summary table (DUMMY)
  - Field-level results for each KPI
  - Metadata (report_date, weeks, total_fields, etc.)

### 5. **Data Clarity Markers**

All tables in output clearly indicate:
- **REAL DATA**: Derived from satellite CI measurements
- **DUMMY DATA - [TBD Item]**: Placeholder values; actual method to be implemented

This prevents misinterpretation of preliminary results.

## Usage

```powershell
# Run Angata KPIs only (default, legacy disabled)
Rscript r_app/09_calculate_kpis_Angata.R 2025-11-27 7 angata

# With specific date
Rscript r_app/09_calculate_kpis_Angata.R 2025-11-20 7 angata
```

## Future Work

1. **Harvesting Detection**: Implement CI threshold + temporal pattern analysis
2. **Maturity Definition**: Define stability metrics and thresholds based on field CI ranges
3. **Legacy KPIs**: Adapt or retire based on Angata's needs
4. **Integration**: Connect outputs to reporting system (R Markdown, Word reports, etc.)

## File Structure

```
r_app/
├── 09_calculate_kpis_Angata.R           (main script - UPDATED)
├── kpi_utils.R                          (optional - legacy functions)
├── crop_messaging_utils.R               (dependencies)
├── parameters_project.R                 (project config)
└── growth_model_utils.R                 (optional)

Output:
└── laravel_app/storage/app/angata/reports/kpis/
    └── angata_kpi_summary_tables_week[XX].rds
```

---
**Updated**: November 27, 2025