Add comprehensive refactoring plan for R package modernization

[Copilot]

Addresses the need for a detailed, prioritized refactoring strategy to modernize the artMS proteomics analysis package while maintaining backward compatibility.

Documentation Suite (6 files, 81KB)

Navigation & Quick Reference

• DOCUMENTATION_INDEX.md - Role-based reading guide and topic navigation
• REFACTORING_OVERVIEW.md - Visual timeline, metrics dashboard, success criteria

Planning & Strategy

• REFACTORING_PLAN.md - 3-phase implementation (P0-P3 priorities, 6-month timeline)
• DEPENDENCIES.md - Audit of 50 dependencies with migration paths

Implementation Support

• IMPLEMENTATION_GUIDE.md - Task-by-task steps with code templates
• MIGRATION_GUIDE.md - User transition guide across versions

Key Plan Elements

Phase 1 (4-6 weeks): Critical Updates → v1.12.0

• Replace deprecated dependencies: plyr → dplyr, gProfileR → gprofiler2
• Add input validation with checkmate
• Expand test coverage from 30% to 60%

Phase 2 (6-8 weeks): Organization → v1.14.0

• Reorganize 22 R files by functional module
• Decompose functions >200 lines
• Add progress indicators, enhance documentation

Phase 3 (4-6 weeks): Advanced → v1.16.0

• Performance optimization (10-20% target improvement)
• Optional parallel processing
• S3 classes for result objects

Backward Compatibility

• Deprecation timeline: Warnings (v1.12) → Defunct (v1.16) → Removal (v2.0)
• All refactoring maintains existing API
• Zero breaking changes until major version

Package Analysis

Current state: 22 R files, ~14K LOC, 33 exports, 4 functional modules (QC, MSstats, analysis, export)

Priority fixes identified:

• P0: plyr (superseded), gProfileR (deprecated/removed from CRAN)
• P1: Input validation gaps, test coverage at 30%
• P2: Monolithic functions (max 800+ lines), code duplication ~15%

Example Migration Pattern

# Before (plyr, deprecated)
result <- plyr::ddply(data, .(group), summarise, mean = mean(value))

# After (dplyr)
result <- data %>%
  dplyr::group_by(group) %>%
  dplyr::summarise(mean = mean(value), .groups = 'drop')

Updated README.md with links to refactoring documentation.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Comprehensive Refactoring Plan for R Package Modernization</issue_title>
<issue_description>This R package provides proteomics data analysis workflows with four core functional modules:

• Quality control (QC) functions for proteomics data
• Relative quantification using MSstats integration
• Downstream statistical analysis (enrichment, clustering, PCA, visualization)
• Export utilities for external tools (SAINTq, SAINTexpress, Photon, Phosfate)

Refactoring Objectives:

Provide a detailed, prioritized refactoring plan addressing:

Code Modernization:

• Update to modern R practices (tidyverse compatibility, pipe operators, tidy evaluation)
• Replace deprecated functions and dependencies
• Implement consistent coding style (tidyverse style guide)
• Add type checking and input validation

Package Structure:

• Reorganize functions into logical modules matching the four core areas
• Identify and eliminate code duplication
• Separate plotting/visualization into dedicated functions
• Modularize export functions for each external tool

Dependencies:

• Audit current dependencies for relevance and maintenance status
• Update MSstats integration to latest API
• Minimize dependency footprint where possible
• Document version requirements

Testing & Documentation:

• Add unit tests (testthat) for each functional module
• Create example datasets for testing
• Write comprehensive vignettes for each workflow
• Improve function documentation (roxygen2)
• Add lifecycle badges for function maturity

Performance:

• Identify computational bottlenecks
• Implement parallel processing where appropriate
• Optimize memory usage for large datasets

User Experience:

• Standardize function naming conventions
• Improve error messages and warnings
• Add progress indicators for long-running operations
• Create consistent return object structures

Backwards Compatibility:

• Strategy for deprecated function migration
• Version migration guide for existing users

Deliverable Format:

• Pased implementation plan (Phase 1: critical updates, Phase 2: enhancements, Phase 3: new features)
• Specific file structure recommendations
• Priority ranking for each task
• Estimated effort/complexity for major refactoring tasks
• Breaking changes documentation strategy
  </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Comprehensive Refactoring Plan for artMS R Package Modernization #199

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.