# rainerosr

Calculate I30 (maximum 30-minute rainfall intensity) and EI30 (erosivity index) from rainfall breakpoint data for use in soil erosion modeling.

## Installation

```r
# Install from GitHub (once uploaded)
# devtools::install_github("yourusername/rainerosr")

# Or install locally
devtools::install_local("path/to/rainerosr")
```

## Features

- **I30 Calculation**: Maximum 30-minute rainfall intensity from breakpoint data
- **EI30 (Erosivity Index)**: Calculate rainfall erosivity using multiple kinetic energy equations
- **Multi-Event Processing**: Automatically separate and analyze multiple storm events
- **Data Validation**: Comprehensive checks for data quality and consistency
- **Visualization**: Plot rainfall patterns and intensity profiles
- **Flexible Input**: Works with various time interval formats

## Quick Start

### Basic I30 Calculation

```r
library(rainerosr)

# Create sample data
data <- data.frame(
  datetime = as.POSIXct(c(
    "2024-01-15 14:00:00",
    "2024-01-15 14:15:00",
    "2024-01-15 14:30:00",
    "2024-01-15 14:45:00",
    "2024-01-15 15:00:00"
  )),
  rainfall_mm = c(5.2, 8.3, 6.1, 3.4, 2.0)
)

# Calculate I30
result <- calculate_i30(data, "datetime", "rainfall_mm")

print(paste("Maximum 30-minute intensity:", result$i30, "mm/hr"))
print(paste("Total rainfall:", result$total_rainfall, "mm"))
```

### Calculate EI30 (Erosivity Index)

```r
# Calculate erosivity index
ei30_result <- calculate_ei30(data, "datetime", "rainfall_mm")

print(paste("EI30:", ei30_result$ei30, "MJ mm ha^-1 hr^-1"))
print(paste("Total energy:", ei30_result$total_energy, "MJ ha^-1"))
print(paste("I30:", ei30_result$i30, "mm/hr"))

# Use different kinetic energy equation
ei30_wisch <- calculate_ei30(data, "datetime", "rainfall_mm", 
                             ke_equation = "wischmeier")
```

### Process Multiple Storm Events

```r
# Data with multiple storms
multi_data <- data.frame(
  datetime = as.POSIXct(c(
    # Storm 1
    "2024-03-10 09:00:00", "2024-03-10 09:15:00", "2024-03-10 09:30:00",
    # Storm 2 (8 hours later)
    "2024-03-10 18:00:00", "2024-03-10 18:20:00", "2024-03-10 18:40:00"
  )),
  rainfall_mm = c(6.5, 8.9, 5.2, 9.2, 7.8, 6.3)
)

# Process all events
events <- process_storm_events(
  multi_data, 
  "datetime", 
  "rainfall_mm",
  min_gap_hours = 6,        # Separate events by 6-hour gaps
  min_rainfall_mm = 12.7    # Minimum 12.7mm to be considered an event
)

print(events)
```

### Data Validation

```r
# Validate your data before analysis
validation <- validate_rainfall_data(data, "datetime", "rainfall_mm")

if (validation$valid) {
  print("Data is valid!")
} else {
  print("Issues found:")
  print(validation$issues)
}

if (length(validation$warnings) > 0) {
  print("Warnings:")
  print(validation$warnings)
}
```

### Visualization

```r
library(ggplot2)

# Plot rainfall pattern
plot_rainfall_pattern(data, "datetime", "rainfall_mm", plot_type = "both")

# Plot intensity profile with I30 highlighted
plot_intensity_profile(data, "datetime", "rainfall_mm", highlight_i30 = TRUE)
```

## Input Data Format

The package accepts rainfall breakpoint data in the following formats:

### Option 1: Time and Rainfall Depth (most common)

```r
data <- data.frame(
  time = as.POSIXct(...),  # POSIXct datetime objects
  depth_mm = c(...)         # Rainfall depth in mm
)
```

The function will automatically calculate time intervals between consecutive points.

### Option 2: With Explicit Intervals

```r
data <- data.frame(
  time = as.POSIXct(...),
  depth_mm = c(...),
  interval_min = c(...)     # Time interval in minutes
)
```

## Kinetic Energy Equations

Three equations are available for calculating kinetic energy:

1. **Brown & Foster (1987)** - Default, widely used
   - `e = 0.29[1 - 0.72exp(-0.05i)]`

2. **Wischmeier & Smith (1978)** - Classic USLE equation
   - `e = 0.119 + 0.0873log10(i)`

3. **McGregor & Mutchler (1976)** - For southern US conditions
   - `e = 0.273 + 0.2168i - 0.0083i²` (for i < 76 mm/hr)

Where `e` is unit energy (MJ ha⁻¹ mm⁻¹) and `i` is intensity (mm hr⁻¹).

## Functions

| Function | Description |
|----------|-------------|
| `calculate_i30()` | Calculate maximum 30-minute rainfall intensity |
| `calculate_ei30()` | Calculate rainfall erosivity index (EI30) |
| `validate_rainfall_data()` | Check data quality and consistency |
| `process_storm_events()` | Analyze multiple storm events |
| `plot_rainfall_pattern()` | Visualize rainfall over time |
| `plot_intensity_profile()` | Plot intensity with I30 highlighted |

## Output Units

- **I30**: mm/hr (millimeters per hour)
- **Rainfall depth**: mm (millimeters)
- **EI30**: MJ mm ha⁻¹ hr⁻¹ (megajoules millimeters per hectare per hour)
- **Energy**: MJ ha⁻¹ (megajoules per hectare)
- **Duration**: minutes

## Use Cases

- **USLE/RUSLE modeling**: Calculate R-factor components
- **Hydrological analysis**: Assess rainfall intensity patterns
- **Erosion risk assessment**: Quantify erosive potential of storms
- **Climate studies**: Analyze temporal rainfall patterns
- **Engineering design**: Design storm characterization

## References

- Brown, L.C., & Foster, G.R. (1987). Storm erosivity using idealized intensity distributions. *Transactions of the ASAE*, 30(2), 379-386.

- Wischmeier, W.H., & Smith, D.D. (1978). Predicting rainfall erosion losses: A guide to conservation planning. *USDA Agriculture Handbook No. 537*.

- Renard, K.G., Foster, G.R., Weesies, G.A., McCool, D.K., & Yoder, D.C. (1997). Predicting soil erosion by water: A guide to conservation planning with the Revised Universal Soil Loss Equation (RUSLE). *USDA Agriculture Handbook No. 703*.

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## License

MIT License

## Author

Your Name

## Citation

If you use this package in your research, please cite:

```
Your Name (2026). rainerosr: Calculate Rainfall Intensity and Erosivity Indices.
R package version 0.1.0.
```
