Contributing to gwArsenicR

Thank you for your interest in contributing to gwArsenicR! This document provides guidelines for contributing to the project.

Code of Conduct
Getting Started
Development Setup
How to Contribute
Reporting Issues
Submitting Pull Requests
Development Guidelines
Testing
Documentation
Release Process

Code of Conduct

We are committed to providing a welcoming and inclusive environment for all contributors. Please be respectful and professional in all interactions.

Expected Behavior

Use welcoming and inclusive language
Be respectful of differing viewpoints and experiences
Gracefully accept constructive criticism
Focus on what is best for the community
Show empathy towards other community members

Unacceptable Behavior

Harassment, discrimination, or offensive comments
Personal attacks or trolling
Publishing others’ private information without permission
Any conduct that would be inappropriate in a professional setting

Getting Started

Prerequisites

R (≥ 4.4.0)
VS Code (recommended)
Git
Pandoc for building vignettes

Required R Packages

# Development tools
install.packages(c("devtools", "roxygen2", "testthat", "covr"))

# Package dependencies (see DESCRIPTION file)
install.packages(c("data.table", "dplyr", "lme4", "mice", "broom.mixed"))

Development Setup

Fork the repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/gwArsenicR.git
cd gwArsenicR

Set up the development environment:

# In R/RStudio
devtools::load_all()
devtools::test()
devtools::check()

Create a new branch for your contribution:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-number

How to Contribute

We welcome several types of contributions:

🐛 Bug Reports

Search existing issues first
Use the bug report template
Include reproducible examples
Specify R version and package version

💡 Feature Requests

Check if the feature already exists
Clearly describe the use case
Explain why it would be valuable
Consider backward compatibility

📖 Documentation Improvements

Fix typos or unclear explanations
Add examples or clarify existing ones
Improve function documentation
Update vignettes

🧪 Code Contributions

Bug fixes
New features
Performance improvements
Test coverage improvements

📊 Examples and Use Cases

Real-world application examples
Educational materials
Tutorial improvements

Reporting Issues

When reporting issues, please include:

For Bug Reports

Describe the bug: Clear description of what happened
Reproduction steps: Minimal code to reproduce the issue
Expected behavior: What you expected to happen

System information:

sessionInfo()
packageVersion("gwArsenicR")

Data: If possible, provide sample data that reproduces the issue

For Feature Requests

Feature description: What functionality you’d like to see
Use case: Why this feature would be useful
Proposed implementation: If you have ideas about how to implement it

Submitting Pull Requests

Before Submitting

Ensure your code passes all checks:

devtools::load_all()
devtools::test()
devtools::check()

Update documentation if needed:
```
devtools::document()
```
Add tests for new functionality
Update NEWS.md with your changes

Pull Request Process

Commit your changes with clear, descriptive messages:

git add .
git commit -m "Add: brief description of changes"

Push to your fork:

git push origin feature/your-feature-name

Create a pull request on GitHub with:
- Clear title describing the change
- Detailed description of what was changed and why
- Reference to any related issues
- Confirmation that tests pass
Respond to review feedback promptly and professionally

Pull Request Guidelines

Keep changes focused and atomic
Write clear commit messages
Include tests for new functionality
Update documentation as needed
Ensure backward compatibility when possible

Development Guidelines

Code Style

Follow the tidyverse style guide:

# Good
calculate_arsenic_exposure <- function(data, method = "weighted") {
  if (is.null(data)) {
    stop("Data cannot be NULL")
  }
  
  result <- data %>%
    filter(!is.na(arsenic_level)) %>%
    summarize(mean_exposure = mean(arsenic_level))
  
  return(result)
}

# Function names: snake_case
# Variable names: snake_case
# Constants: UPPER_SNAKE_CASE
# Use explicit returns
# Add input validation

Package Structure

gwArsenicR/
├── R/
│   ├── gwArsenic.R           # Main exported function
│   ├── data-loading.R        # Data loading functions
│   ├── imputation.R          # Imputation functions
│   ├── regression.R          # Analysis functions
│   └── utils.R               # Utility functions
├── tests/testthat/           # Test files
├── man/                      # Generated documentation
├── vignettes/               # Package vignettes
└── inst/                    # Additional package files

Function Guidelines

Single responsibility: Each function should do one thing well
Clear naming: Function names should describe what they do
Input validation: Check arguments and provide helpful error messages
Documentation: Use roxygen2 for all exported functions
Error handling: Use informative error messages

Internal Functions

Use @keywords internal for functions not intended for end users
Prefix with . if the function is truly internal (e.g., .validate_input)
Keep internal functions focused and well-documented

Testing

Writing Tests

Use testthat framework
Test both success and failure cases
Use descriptive test names
Test edge cases and error conditions

test_that("load_usgs_data handles missing columns gracefully", {
  # Create test data missing required column
  test_data <- data.frame(wrong_col = 1:10)
  
  expect_error(
    load_usgs_data(test_data, required_cols = "correct_col"),
    "missing columns"
  )
})

test_that("arsenic imputation produces valid probabilities", {
  results <- impute_arsenic_exposure(test_data, ndraws = 2)
  
  expect_true(all(results$probabilities >= 0))
  expect_true(all(results$probabilities <= 1))
  expect_equal(length(results$datasets), 2)
})

Running Tests

# Run all tests
Rscript -e "devtools::test()"

# Run specific test file
Rscript -e "testthat::test_file('tests/testthat/test-imputation.R')"

# Check test coverage
Rscript -e "covr::package_coverage()"

Test Data

Use synthetic data for tests
Keep test datasets small for speed
Store test data in tests/testthat/ directory
Use helper-*.R files for test data generation functions

Documentation

Function Documentation

Use roxygen2 for all exported functions:

#' Perform Arsenic Exposure Analysis
#'
#' This function performs a comprehensive analysis of arsenic exposure
#' using multiple imputation and mixed-effects modeling.
#'
#' @param data A data frame containing the input data
#' @param ndraws An integer specifying the number of imputed datasets (default: 10)
#' @param output_dir A character string specifying the output directory
#' @return A list containing analysis results and summary statistics
#' @examples
#' \dontrun{
#' results <- perform_sensitivity_analysis(
#'   data = my_data,
#'   ndraws = 5,
#'   output_dir = "results/"
#' )
#' }
#' @export

Vignettes

Update vignettes when adding new features
Include realistic examples
Explain the statistical methodology
Show interpretation of results

Package Documentation

Update README.md for user-facing changes
Update NEWS.md for all changes
Keep DESCRIPTION file current

Release Process

Versioning

We use Semantic Versioning: - MAJOR.MINOR.PATCH (e.g., 1.2.3) - MAJOR: Incompatible API changes - MINOR: New functionality (backward compatible) - PATCH: Bug fixes (backward compatible)

Release Checklist

Update version in DESCRIPTION
Update NEWS.md with changes
Run comprehensive tests: devtools::check()
Update documentation: devtools::document()
Build and test package
Create GitHub release with release notes

Getting Help

Questions and Discussions

GitHub Discussions: For questions about usage or development
GitHub Issues: For bug reports and feature requests
Email: Contact maintainers for sensitive issues

Resources

R Packages book by Hadley Wickham
Advanced R for advanced R programming
testthat documentation for testing
roxygen2 documentation for documentation

Recognition

Contributors will be acknowledged in: - DESCRIPTION file (for significant contributions) - README.md contributors section - Release notes for their contributions

Thank you for contributing to gwArsenicR! Your efforts help advance arsenic exposure research and public health.

Questions? Feel free to open an issue or contact the maintainers: - Dr. Sayantan Majumdar - Dr. Matthew O. Gribble

Table of Contents