# Copilot Instruct- **Crop Analysis & Messaging:**
  - Main script: `r_app/06_crop_messaging.R`
  - Usage: `Rscript 06_crop_messaging.R [current_week] [previous_week] [estate_name]`
  - Two-dimensional alerting: Time (week-over-week changes) + Space (field uniformity/patches)
  - Handles missing weeks due to clouds (CI band = 0)
  - Output: WhatsApp-ready text (.txt) and Word reports (.docx) with farm-wide summary, missing data notes, areas in hectares and acres, and interpretation guides for columns
  - Filenames include estate name (e.g., `crop_messaging_simba.txt`, `crop_messaging_simba.docx`)or SmartCane Codebase

## Big Picture Architecture
- **Three main components:**
  - `r_app/`: R scripts for crop analysis, package management, and reporting
  - `r_app/experiments/sar_dashboard/`: Production SAR dashboard system (Python + R)
  - `python_app/` & `python_scripts/`: Python notebooks and scripts for satellite data download and preprocessing
  - `laravel_app/`: Laravel PHP web application for user-facing features
- **Data Flow:**
  - Satellite data is downloaded/preprocessed in Python, stored in `python_scripts/data/` or `r_app/experiments/sar_dashboard/data/`
  - R scripts in `r_app/` analyze, visualize, and report on this data
  - SAR dashboard combines Python download + R analysis + Word report generation
  - Reports and outputs are saved in `output/` or `r_app/experiments/sar_dashboard/`
  - Laravel app may consume outputs for web display (integration is project-specific)

## Critical Developer Workflows
- **R Package Management:**
  - Always run `r_app/package_manager.R` after pulling changes or before analysis
  - Commit `renv.lock` but NOT the `renv/` folder
  - Use `source("r_app/package_manager.R")` in RStudio or `Rscript r_app/package_manager.R` in terminal
- **Crop Analysis & Messaging:**
  - Main script: `r_app/06_crop_messaging.R`
  - Usage: `Rscript 06_crop_messaging.R [current_week] [previous_week] [estate_name]`
  - Two-dimensional alerting: Time (change trends) + Space (field uniformity/patches)
  - Handles missing weeks due to clouds (CI band = 0)
  - Output: WhatsApp-ready text, CSV data, .docx reports, and Markdown tables
- **SAR Analysis & Reporting:**
  - **SAR Dashboard:** Production-ready Word reports for SAR data analysis
  - **Main folder:** `r_app/experiments/sar_dashboard/`
  - **Download script:** `r_app/experiments/sar_dashboard/download_s1_simba.py` (for Simba) or `download_s1_[client].py`
  - **Report generation:** `Rscript r_app/experiments/sar_dashboard/generate_sar_report.R [client_name]`
  - **Test script:** `Rscript r_app/experiments/sar_dashboard/test_sar_dashboard.R`
  - **Data source:** `r_app/experiments/sar_dashboard/data/[client]/weekly_SAR_mosaic/`
  - **Features:** RGB visualization (each band = different week), SAR indices (RVI, cross-pol ratio), harvest detection, field uniformity analysis, time series plots
  - **Output:** Word document (.docx) with comprehensive SAR analysis and visualizations
  - **Field boundaries:** Uses `r_app/experiments/pivot.geojson` for field polygons
- **Python Data Download:**
  - Notebooks/scripts in `python_app/` and `python_scripts/` handle satellite data acquisition
  - Check `requirements_*.txt` for dependencies
- **Laravel App:**
  - Standard Laravel conventions (see `laravel_app/README.md`)
  - Use `artisan` for migrations, tests, etc.

## Project-Specific Conventions
- **Field Uniformity & Alerting:**
  - **Two-dimensional analysis**: Time (week-over-week changes) + Space (field homogeneity)
  - **Message categories**: 🚨 URGENT, ⚠️ ALERT, ✅ POSITIVE, 💡 OPPORTUNITY
  - **Uniformity thresholds**: CV < 0.15 (good), CV < 0.08 (excellent), CV > 0.25 (poor)
  - **Change detection**: Increase > 0.5, Decrease < -0.5 (configurable thresholds)
  - **Spatial patterns**: Moran's I analysis for clustering detection
  - **Missing data handling**: Clouds (CI=0) trigger spatial-only analysis
- **Output Formatting:**
  - Word reports (.docx) include split tables for wide data, with column widths set for readability
  - Interpretation guides provided under each table explaining columns like 'acceptable %' and 'change' thresholds
  - Areas reported in both hectares and acres
- **Package Management:**
  - Minimum versions enforced for critical R packages (see `PACKAGE_MANAGEMENT.md`)
  - All package changes go through `package_manager.R`
- **SAR-Specific Analysis:**
  - **Data characteristics:** SAR (radar) penetrates clouds, all-weather capability, measures backscatter intensity
  - **Bands:** VV (vertical-vertical), VH (vertical-horizontal), dB scaled for analysis
  - **Indices:** RVI (Radar Vegetation Index), cross-polarization ratio, crop structure index
  - **Harvest detection:** Identifies completely bare fields by backscatter threshold and temporal change
  - **RGB visualization:** Each band represents different week for change detection
  - **Data availability:** Sentinel-1 provides ~6-day revisit, weekly composites recommended
  - **Field boundaries:** Critical for SAR analysis - ensure `pivot.geojson` is current and accurate

## Integration Points & Dependencies
- **R ↔ Python:**
  - R scripts expect preprocessed data from Python scripts
  - Data location conventions: `python_scripts/data/`, `pivot.geojson`
- **R ↔ Laravel:**
  - Laravel may read outputs from R analysis (integration is custom)
- **External:**
  - Sentinel-1 SAR data (via SentinelHub API), Planet optical data, field boundaries (GeoJSON), R/Python packages

## Examples
- To run a full crop analysis workflow:
  ```powershell
  Rscript r_app/package_manager.R ; Rscript r_app/06_crop_messaging.R 32 31 simba
  ```
- To run crop messaging with cloud handling:
  ```powershell
  Rscript r_app/06_crop_messaging.R 30 29 chemba  # Only spatial analysis if week 29 has clouds
  ```
- To generate SAR dashboard report:
  ```powershell
  cd r_app/experiments/sar_dashboard
  python download_s1_simba.py  # Download SAR data for Simba (last 8 weeks)
  Rscript generate_sar_report.R simba  # Generate Word report
  ```
- To test SAR dashboard setup:
  ```powershell
  cd r_app/experiments/sar_dashboard
  Rscript test_sar_dashboard.R
  ```

## Key Files & Directories
- `r_app/package_manager.R`, `PACKAGE_MANAGEMENT.md`: Package logic & workflow
- `r_app/06_crop_messaging.R`, `r_app/crop_messaging_utils.R`: Crop analysis & messaging logic
- `r_app/experiments/crop_messaging/crop_analysis_messaging.R`: Experimental messaging script
- `r_app/experiments/sar_dashboard/`: Complete SAR dashboard system
  - `download_s1_simba.py`: SAR data download for Simba fields
  - `generate_sar_report.R`: Generate Word document SAR reports
  - `test_sar_dashboard.R`: Test SAR dashboard components
  - `SAR_Dashboard_Report.Rmd`: RMarkdown template for Word reports
  - `sar_dashboard_utils.R`: SAR analysis utility functions
  - `data/[client]/weekly_SAR_mosaic/`: Downloaded SAR data organized by week
- `python_scripts/`, `python_app/`: Data download/preprocessing
- `output/`: All generated reports
- `laravel_app/`: Web application

## Environment Notes
- On Windows, R can be found at: `C:\Program Files\R\R-4.4.3\bin\x64\R.exe`

## Documentation & File Creation Policy
**IMPORTANT: Minimize markdown file creation to reduce repo clutter**

- **Do NOT create** README.md, START_HERE.md, QUICK_START.md, INDEX.md automatically
- **Only create .md files when:**
  - User explicitly requests it
  - A single index/guide for an entire folder (ONE per folder max)
  - Critical architecture/setup documentation that doesn't exist
- **Instead:**
  - Add comments directly in scripts explaining purpose & usage
  - Use inline documentation (docstrings, comments)
  - Reference existing docs rather than creating duplicates
- **Experiments folders:** Keep clean - code + minimal comments, no separate guides per experiment
- **When in doubt:** Ask the user if they want documentation before creating files

---
_If any section is unclear or missing, please provide feedback for further refinement._