manureshed 🌾💧

CRAN status Total Downloads License: MIT pkgdown

Spatiotemporal Nutrient Balance Analysis Across Agricultural and Municipal Systems

An R package for analyzing integrated agricultural-municipal nutrient flows and watershed management. The manureshed framework enables comprehensive analysis of nitrogen and phosphorus balances across multiple spatial scales (county, HUC8, HUC2) with seamless integration of wastewater treatment plant (WWTP) discharge data.

📋 Table of Contents

✨ Key Features

🗺️ Multi-Scale Spatial Analysis

🌾 Comprehensive Nutrient Analysis

💧 WWTP Integration

📊 Rich Visualizations

🔄 End-to-End Workflows

⚡ Performance & Data Management

📦 Installation

# Install the stable version from CRAN
install.packages("manureshed")

Development Version from GitHub

# Install development version with latest features
# install.packages("devtools")
devtools::install_github("cwru-sdle/manureshed")
# Enhanced visualization and spatial analysis
install.packages(c("ggplot2", "sf", "dplyr", "tidyr", "viridis"))

# Optional packages for advanced features
install.packages(c("tigris", "nhdplusTools", "igraph", "cowplot"))

🚀 Quick Start

Load Package and Check Data

library(manureshed)

# Check what data is available
check_builtin_data()

# Download all datasets (optional, ~40MB total)
download_all_data()

# Test connection to data repository
test_osf_connection()

# Check package health
health_check()

Basic Analysis Examples

# 1. Quick analysis with automatic visualizations
results <- quick_analysis(
  scale = "county",
  year = 2016,
  nutrients = "nitrogen",
  include_wwtp = TRUE
)

# 2. Comprehensive analysis for both nutrients
results_both <- run_builtin_analysis(
  scale = "huc8",
  year = 2016,
  nutrients = c("nitrogen", "phosphorus"),
  include_wwtp = TRUE,
  output_dir = "analysis_results"
)

# 3. Historical analysis (2007-2016 WWTP available!)
historical <- run_builtin_analysis(
  scale = "county",
  year = 2010,
  nutrients = "nitrogen",
  include_wwtp = TRUE
)

# 4. Multi-year analysis
batch_results <- batch_analysis_years(
  scale = "huc8",
  years = c(2010, 2012, 2014, 2016),
  nutrients = "phosphorus",
  include_wwtp = TRUE
)

# 5. State-specific analysis
ohio <- run_state_analysis(
  state = "OH",
  scale = "county",
  year = 2016,
  nutrients = c("nitrogen", "phosphorus"),
  include_wwtp = TRUE
)

📖 Documentation

Vignettes and Tutorials

Function Reference

# View all available functions
help(package = "manureshed")

# Key workflow functions
?run_builtin_analysis
?quick_analysis
?batch_analysis_years
?run_state_analysis

# Data loading functions
?load_builtin_nugis
?load_builtin_wwtp
?load_builtin_boundaries

# Custom data integration
?load_user_wwtp
?wwtp_clean_data

# Visualization functions
?map_agricultural_classification
?map_wwtp_points
?map_wwtp_influence

# Utility functions
?check_builtin_data
?citation_info
?health_check

🎯 Real-World Examples

Regional Nutrient Analysis

# Analyze nitrogen flows in the Great Lakes region
great_lakes <- run_builtin_analysis(
  scale = "huc8",
  year = 2016,
  nutrients = "nitrogen",
  include_wwtp = TRUE,
  output_dir = "great_lakes_analysis"
)

# Extract key statistics
summary_stats <- create_classification_summary(
  great_lakes$nitrogen$agri_classified,
  great_lakes$nitrogen$integrated_result
)

# Visualize impact
plot_before_after_comparison(summary_stats)

Watershed Management Planning

# Load watershed boundaries
huc8_boundaries <- load_builtin_boundaries("huc8")

# Analyze nutrient balance
watershed_balance <- run_builtin_analysis(
  scale = "huc8",
  year = 2016,
  nutrients = c("nitrogen", "phosphorus"),
  include_wwtp = TRUE
)

# Calculate transition probabilities
transitions_n <- calculate_transition_probabilities(
  watershed_balance$nitrogen$agri_classified,
  watershed_balance$nitrogen$integrated_result
)

# Visualize network flows
create_network_plot(
  transitions_n,
  nutrient = "nitrogen",
  title = "HUC8 Nitrogen Classification Transitions"
)

Custom WWTP Data Integration

# Load your own WWTP data for any year
custom_wwtp <- load_user_wwtp(
  file_path = "my_wwtp_2018.csv",
  nutrient = "nitrogen",
  column_mapping = list(
    facility = "Facility_Name",
    latitude = "Lat",
    longitude = "Long",
    load = "Total_N_kg"
  ),
  load_units = "kg"
)

# Integrate with agricultural data
custom_results <- run_builtin_analysis(
  scale = "county",
  year = 2016,  # Use 2016 agricultural data
  nutrients = "nitrogen",
  include_wwtp = TRUE,
  custom_wwtp_nitrogen = custom_wwtp
)

Multi-Year Trend Analysis

# Analyze trends across multiple years
trend_results <- batch_analysis_years(
  scale = "county",
  years = seq(2010, 2016, by = 2),
  nutrients = c("nitrogen", "phosphorus"),
  include_wwtp = TRUE,
  output_dir = "trend_analysis"
)

# Available years for WWTP: 2007-2016
list_available_years()

State-Level Analysis

# Quick state analysis with maps
iowa_results <- quick_state_analysis(
  state = "IA",
  scale = "county",
  year = 2016,
  nutrients = "nitrogen"
)

# Multiple states
midwest_states <- c("IA", "IL", "IN", "OH", "MI")
midwest_results <- lapply(midwest_states, function(state) {
  run_state_analysis(
    state = state,
    scale = "county",
    year = 2016,
    nutrients = "nitrogen",
    include_wwtp = TRUE
  )
})
names(midwest_results) <- midwest_states

🌟 What Makes manureshed Special

1. Integrated Framework

The manureshed concept represents a paradigm shift from treating agricultural and municipal nutrient systems separately to analyzing them as integrated socio-environmental systems. This enables: - Circular economy insights: Identify opportunities for nutrient recycling - Regional planning: Optimize nutrient flows at watershed scales - Policy analysis: Evaluate impact of nutrient management strategies

2. Comprehensive Spatial Coverage

3. Temporal Depth

4. Research-Ready

Designed specifically for reproducible research: - Permanent data archive: DOI-based OSF repository - Version control: Fixed data versions for reproducibility - Complete workflow: From raw data to publication figures - Metadata tracking: Analysis parameters saved automatically

5. Flexible Data Integration

6. Rich Analytical Tools

📊 Data Sources

NuGIS Agricultural Data (1987-2016)

Source: The Fertilizer Institute (TFI) and Plant Nutrition Canada (PNC)

Website: https://nugis.tfi.org/tabular_data

Components: - County-level crop and livestock data (USDA Census of Agriculture) - Fertilizer use data (AAPFCO) - Manure production estimates - Nutrient removal by crops - Biological nitrogen fixation

Spatial Scales: County, HUC8, HUC2

Citation: Use citation_info() for complete attribution

EPA WWTP Discharge Data (2007-2016)

Source: U.S. Environmental Protection Agency

System: Discharge Monitoring Report (DMR) Loading Tool via ECHO

Website: https://echo.epa.gov/trends/loading-tool/water-pollution-search

Parameters: - Total nitrogen loads - Total phosphorus loads - Facility locations and identifiers - Permit information

Pre-processing: Cleaned and quality-controlled in manureshed package

License: Public domain (U.S. Government work)

Spatial Boundaries

Sources: - US Census TIGER (counties) - USGS Watershed Boundary Dataset (HUC8, HUC2)

Projection: Albers Equal Area Conic (EPSG:5070)

Coverage: Continental United States (CONUS)

⚡ Performance

The package is optimized for:

Performance Tips

# Check package health
health_check()

# Pre-download all data for offline work
download_all_data()

# Clear cache if needed
clear_data_cache()

# Use quick_check to validate results
quick_check(results)

# For large batch analyses, process in chunks
years_chunk1 <- seq(2007, 2011)
years_chunk2 <- seq(2012, 2016)

🛠 System Requirements

Required Dependencies

# Core dependencies (automatically installed)
sf (>= 1.0-0)
dplyr (>= 1.0.0)
ggplot2 (>= 3.3.0)
tidyr (>= 1.0.0)
jsonlite
rlang
# Install these for full functionality
install.packages(c(
  "viridis",      # Color schemes
  "tigris",       # US boundaries
  "nhdplusTools", # Watershed tools
  "igraph",       # Network analysis
  "cowplot"       # Multi-panel plots
))

Minimum R Version

📄 Citation

If you use manureshed in your research, please cite:

Package Citation

citation("manureshed")

Akanbi, O. D.; Mandayam, V.; Gupta, A.; Flynn, K. C.; Yarus, J. M.; Barcelos, E. I.; & French, R. H. (2025). manureshed: An Open-Source R Package for Scalable Temporal and Multi-Regional Analysis of Integrated Agricultural-Municipal Nutrient Flows. R package version 0.1.0. OSF Repository: https://osf.io/g39xa/

Methodology Paper

Akanbi, O. D.; Gupta, A.; Mandayam, V.; Flynn, K. C.; Yarus, J. M.; Barcelos, E. I.; French, R. H. Towards Circular Nutrient Economies: An Integrated Manureshed Framework for Agricultural and Municipal Resource Management. Resources, Conservation and Recycling, 2025. https://doi.org/10.1016/j.resconrec.2025.108697

Data Sources

Use citation_info() to display complete citations for: - NuGIS agricultural data - EPA WWTP discharge data - Spatial boundary datasets

📧 Contact

🤝 Contributing

We welcome contributions! To contribute:

  1. Report bugs: Use GitHub Issues with reproducible examples
  2. Suggest features: Open a discussion issue
  3. Submit pull requests: Follow our coding standards
  4. Improve documentation: Help make the package more accessible

Getting Help

📝 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Funding

This material is based upon financial support by the National Science Foundation, EEC Division of Engineering Education and Centers, NSF Engineering Research Center for Advancing Sustainable and Distributed Fertilizer Production (CASFER), NSF 20-553 Gen-4 Engineering Research Centers award 2133576.

Contributing Institutions

Special Thanks

Development Team

Ready to get started? Install from CRAN with install.packages("manureshed") and check out the Getting Started vignette!

Questions? Run health_check() to verify your installation, or use citation_info() for publication citations.