156 lines
5.1 KiB
Markdown
156 lines
5.1 KiB
Markdown
# 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
|