# SmartCane Project - Package Management & Crop Analysis

## Quick Start

### For New Team Members
1. Open R/RStudio
2. Set working directory to the project root: `setwd("path/to/smartcane")`
3. Run: `source("r_app/package_manager.R")`
4. Type `y` when prompted
5. Wait for completion ✅

### For Existing Team Members (After Git Pull)
Same steps as above - the script will check for updates automatically.

## Crop Analysis Messaging System

### Overview
The `crop_analysis_messaging.R` script provides automated field monitoring with intelligent alerting based on crop index (CI) analysis. It compares weekly satellite data to detect uniformity issues and performance changes.

### Message Determination Logic

#### **Uniformity Thresholds (CV = Coefficient of Variation)**
| Threshold | CV Range | Category | Action |
|-----------|----------|----------|---------|
| Excellent | ≤ 0.08 | ✅ Excellent | Monitor only |
| Good | 0.08 - 0.15 | ✅ Good | Monitor only |
| Moderate | 0.15 - 0.25 | ⚠️ Alert | Review management |
| Poor | > 0.25 | 🚨 Urgent | Immediate action |

#### **Additional Alert Triggers**
- **Low Acceptable Area**: < 40% of field within ±25% of mean CI
- **Very Strong Clustering**: Moran's I > 0.95 (indicates management issues)
- **Declining Trends**: Combined with poor uniformity = escalated urgency

#### **Message Categories & Examples**

**🚨 URGENT Messages:**
- `🚨 URGENT: Poor field uniformity detected - immediate management review required`
- `🚨 CRITICAL: Poor uniformity with declining trend - emergency intervention needed`

**⚠️ ALERT Messages:**
- `⚠️ Alert: Moderate field variation detected - low acceptable area - review management uniformity`
- `⚠️ Alert: Good uniformity but very strong clustering detected - check management practices`

**✅ POSITIVE Messages:**
- `✅ Excellent: Optimal field uniformity and stability`
- `✅ Great: Good uniformity with improvement trend`

**💡 OPPORTUNITY Messages:**
- `💡 Opportunity: X% of field performing well - replicate conditions in remaining areas`

#### **Spatial Pattern Analysis**
- **Moran's I Interpretation**: Measures spatial autocorrelation
  - 0.7-0.85: Normal field continuity
  - 0.85-0.95: Strong spatial pattern (monitor)
  - >0.95: Very strong clustering (management concern)

#### **Farm-Wide Summary Statistics**
- **Field Distribution**: Percentage in each uniformity category
- **Area Analysis**: Hectares improving/declining/stable
- **Consistency Checks**: Flags inconsistent CV vs Entropy readings
- **Alert Rate**: Typically 15-20% of fields for healthy monitoring

## Package Management

### What This Script Does

1. **Initializes renv** - Creates isolated package environment
2. **Checks package versions** - Compares installed vs required
3. **Installs/Updates packages** - Only if needed
4. **Creates lockfile** - `renv.lock` for exact reproducibility
5. **Generates reports** - Console output + `package_manager.log`

### Key Features

- ✅ **Minimum version requirements** (allows patch updates)
- ✅ **Critical package locking** (tmap v4 for new syntax)
- ✅ **Automatic installation** of missing packages
- ✅ **Console + Log output** for debugging
- ✅ **Cross-platform compatibility**

### Required Packages & Versions

| Package | Min Version | Purpose |
|---------|-------------|---------|
| tmap | 4.0.0 | **CRITICAL** - New syntax used |
| tidyverse | 2.0.0 | Data manipulation |
| sf | 1.0.0 | Spatial data |
| terra | 1.7.0 | Raster processing |
| rmarkdown | 2.21.0 | Report generation |
| spdep | 1.2.0 | **NEW** - Spatial statistics for Moran's I |

### Crop Analysis Usage

```r
# Basic usage (defaults to weeks 30 vs 29, simba farm)
Rscript crop_analysis_messaging.R

# Custom analysis
Rscript crop_analysis_messaging.R 32 31 other_farm

# Or from R console
source("r_app/crop_analysis_messaging.R")
```

#### **Output Interpretation**
- **Field-by-field analysis**: Individual field metrics and alerts
- **Summary section**: Total alerts and problem fields
- **Farm-wide statistics**: Overall uniformity distribution
- **Consistency checks**: Spatial pattern validation

## Workflow

### Development Workflow
```
1. 👨‍💻 Developer: Make changes → run package_manager.R → test → commit + push
2. 👥 Teammate: Pull → run package_manager.R → test
3. 🚀 Production: Pull → run package_manager.R → deploy
```

### Crop Analysis Workflow
```
1. 📊 Weekly Data: New satellite mosaics arrive
2. 🔄 Analysis: Run crop_analysis_messaging.R
3. 📋 Review: Check alerts and prioritize fields
4. 🚜 Action: Implement management recommendations
5. 📈 Monitor: Track improvements in next week's analysis
```

### Files Created
- `renv.lock` - Exact package versions (commit this!)
- `package_manager.log` - Installation log (don't commit)
- `renv/` folder - Package cache (don't commit)

## Troubleshooting

### "Package failed to install"
- Check internet connection
- Update R to latest version
- Install system dependencies (varies by OS)

### "Version conflicts"  
- Delete `renv/` folder
- Run script again for clean install

### "renv not working"
- Install manually: `install.packages("renv")`
- Restart R session
- Run script again

## Team Guidelines

1. **Always run** `package_manager.R` after pulling changes
2. **Commit** `renv.lock` to git (not `renv/` folder)
3. **Don't modify** package versions in scripts - use this manager
4. **Report issues** in the log file to team
5. **Review crop alerts** weekly and prioritize urgent fields first
6. **Document management actions** taken in response to alerts

## Crop Analysis Best Practices

### **Alert Prioritization**
1. 🚨 **URGENT** alerts: Address within 24-48 hours
2. ⚠️ **ALERT** messages: Schedule for next management cycle
3. 💡 **OPPORTUNITIES**: Implement when resources available

### **Field Investigation Guidelines**
- **High CV + Low Acceptable Area**: Check irrigation uniformity
- **Very Strong Clustering**: Look for management zone boundaries
- **Declining Trends**: Investigate nutrition or disease issues
- **Spatial Patterns**: Consider soil variability or equipment patterns

### **Validation Steps**
1. Cross-reference alerts with field observations
2. Check weather data for recent stress events
3. Validate spatial patterns with drone imagery if available
4. Document management responses and track improvements

## Advanced Usage

### Restore from lockfile only:
```r
renv::restore()
```

### Add new package requirement:
1. Edit `REQUIRED_PACKAGES` in `package_manager.R`
2. Run the script
3. Commit updated `renv.lock`

### Check status without changes:
```r
source("r_app/package_manager.R")
# Then just read the log or run generate_package_report()
```