196 lines
6.6 KiB
Markdown
196 lines
6.6 KiB
Markdown
# 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()
|
|
```
|