Timon/SmartCane
1
1
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
SmartCane/.github/copilot-instructions.md

7.9 KiB
Raw Blame History

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: 
    Rscript r_app/package_manager.R ; Rscript r_app/06_crop_messaging.R 32 31 simba
  • To run crop messaging with cloud handling: 
    Rscript r_app/06_crop_messaging.R 30 29 chemba  # Only spatial analysis if week 29 has clouds
  • To generate SAR dashboard report: 
    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: 
    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 or any other .mD files 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.