couplr 1.0.2

Documentation

• Added Overview section to algorithms vignette with audience and prerequisites
• Fixed workflow diagram dark mode text handling in matching-workflows vignette
• Improved SVG theme-awareness for multi-line text labels
• Removed grid lines from matching-workflows plots for cleaner appearance
• Added threshold labels to balance comparison plot

couplr 1.0.0

Major New Features (2025-11-19 Update)

Automatic Preprocessing and Scaling

The package now includes intelligent preprocessing to improve matching quality:

• New auto_scale parameter in match_couples() and greedy_couples() enables automatic preprocessing
• Variable health checks detect and handle problematic variables:
  • Constant columns (SD = 0) are automatically excluded with warnings
  • High missingness (>50%) triggers warnings
  • Extreme skewness (|skewness| > 2) is flagged
• Smart scaling method selection analyzes data and recommends:
  • “robust” scaling using median and MAD (resistant to outliers)
  • “standardize” for traditional mean-centering and SD scaling
  • “range” for min-max normalization
• New preprocess_matching_vars() function for manual preprocessing control
• Categorical variable encoding for binary and ordered factors

Balance Diagnostics

Comprehensive tools to assess matching quality:

• New balance_diagnostics() function computes multiple balance metrics:
  • Standardized differences: (mean_left - mean_right) / pooled_sd
  • Variance ratios: SD_left / SD_right
  • Kolmogorov-Smirnov tests for distribution comparison
  • Overall balance metrics (mean, max, % large imbalance)
• Quality thresholds with interpretation:
  • |Std Diff| < 0.10: Excellent balance
  • |Std Diff| 0.10-0.25: Good balance
  • |Std Diff| 0.25-0.50: Acceptable balance
  • |Std Diff| > 0.50: Poor balance
• Per-block statistics with quality ratings when blocking is used
• balance_table() creates publication-ready formatted tables
• Informative print methods with interpretation guides

Joined Matched Dataset Output

Create analysis-ready datasets directly from matching results:

• New join_matched() function automates data preparation:
  • Joins matched pairs with original left and right datasets
  • Eliminates manual data wrangling after matching
  • Select specific variables via left_vars and right_vars parameters
  • Customizable suffixes (default: _left, _right) for overlapping columns
  • Optional metadata: pair_id, distance, block_id
  • Works with both optimal and greedy matching
• Broom-style augment() method for tidymodels integration:
  • S3 method following broom package conventions
  • Sensible defaults for quick exploration
  • Supports all join_matched() parameters
• Flexible output control:
  • include_distance - Include/exclude matching distance
  • include_pair_id - Include/exclude sequential pair IDs
  • include_block_id - Include/exclude block identifiers
  • Custom ID column support via left_id and right_id
  • Clean column ordering: pair_id → IDs → distance → block → variables

Precomputed and Reusable Distances

Performance optimization for exploring multiple matching strategies:

• New compute_distances() function precomputes and caches distance matrices:
  • Compute distances once, reuse across multiple matching operations
  • Store complete metadata: variables, distance metric, scaling method, timestamps
  • Preserve original datasets for seamless integration with join_matched()
  • Enable rapid exploration of different matching parameters
  • Performance improvement: ~60% faster when trying multiple matching strategies
• Distance objects (S3 class distance_object):
  • Self-contained: cost matrix, IDs, metadata, original data
  • Works with both match_couples() and greedy_couples()
  • Pass as first argument instead of datasets: match_couples(dist_obj, max_distance = 5)
  • Informative print and summary methods with distance statistics
• Constraint modification via update_constraints():
  • Apply new max_distance or calipers without recomputing distances
  • Creates new distance object following copy-on-modify semantics
  • Experiment with different constraints efficiently
• Backward compatible integration:
  • Modified function signatures: match_couples(left, right = NULL, vars = NULL, ...)
  • Automatically detects distance objects vs. datasets
  • All existing code continues to work unchanged

Parallel Processing

Speed up blocked matching with multi-core processing:

• New parallel parameter in match_couples() and greedy_couples():
  • Enable with parallel = TRUE for automatic configuration
  • Specify plan with parallel = "multisession" or other future plan
  • Works with any number of blocks - automatically determines if beneficial
  • Gracefully falls back if future packages not installed
• Powered by the future package:
  • Cross-platform support (Windows, Unix/Mac, clusters)
  • Respects user-configured parallel backends
  • Automatic worker management
  • Clean restoration of original plan after execution
• Performance:
  • Best for 10+ blocks with 50+ units per block
  • Speedup scales with number of cores and complexity
  • Minimal overhead for small problems
• Integration:
  • Works with all blocking methods (exact, fuzzy, clustering)
  • Compatible with distance caching from Step 4
  • Supports all matching parameters (constraints, calipers, scaling)

Fun Error Messages and Cost Checking

Like testthat, couplr makes errors light, memorable, and helpful with couple-themed messages:

• New check_costs parameter (default: TRUE) in match_couples() and greedy_couples():
  • Automatically checks distance distributions before matching
  • Provides friendly, actionable warnings for common problems
  • Set to FALSE to skip checks in production code
• Fun couple-themed error messages throughout the package:
  • 💔 “No matches made - can’t couple without candidates!”
  • 🔍 “Your constraints are too strict. Love can’t bloom in a vacuum!”
  • ✨ Helpful suggestions: “Try increasing max_distance or relaxing calipers”
  • 💖 Success messages: “Excellent balance! These couples are well-matched!”
• Automatic problem detection:
  • Too many zeros: Warns about duplicates or identical values (>10% zero distances)
  • Extreme costs: Detects skewed distributions (99th percentile > 10x the 95th)
  • Many forbidden pairs: Warns when constraints eliminate >50% of valid pairs
  • Constant distances: Alerts when all distances are identical
  • Constant variables: Detects and excludes variables with no variation
• New diagnostic function diagnose_distance_matrix():
  • Comprehensive analysis of cost distributions
  • Variable-specific problem detection
  • Actionable suggestions for fixes
  • Quality rating (good/fair/poor)
• Emoji control: Disable with options(couplr.emoji = FALSE) if preferred
• Philosophy: Errors should be less intimidating, more memorable, and provide clear guidance

New Functions

• preprocess_matching_vars() - Main preprocessing orchestrator
• balance_diagnostics() - Comprehensive balance assessment
• balance_table() - Formatted balance tables for reporting
• join_matched() - Create analysis-ready datasets from matching results
• augment.matching_result() - Broom-style interface for joined data
• compute_distances() - Precompute and cache distance matrices
• update_constraints() - Modify constraints on distance objects
• is_distance_object() - Type checking for distance objects
• diagnose_distance_matrix() - Comprehensive distance diagnostics
• check_cost_distribution() - Check for distribution problems
• Added robust scaling method using median and MAD

Documentation & Examples

• examples/auto_scale_demo.R - 5 preprocessing demonstrations
• examples/balance_diagnostics_demo.R - 6 balance diagnostic examples
• examples/join_matched_demo.R - 8 joined dataset demonstrations
• examples/distance_cache_demo.R - Distance caching and reuse examples
• examples/parallel_matching_demo.R - 7 parallel processing examples
• examples/error_messages_demo.R - 10 fun error message demonstrations
• Complete implementation documentation (claude/IMPLEMENTATION_STEP1.md through STEP6.md)
• All functions have full Roxygen documentation

Tests

• Added 34+ new tests (10 for preprocessing, 11 for balance diagnostics, 13 for joined datasets, tests for distance caching)
• All tests passing with full backward compatibility

Major Changes (Initial 1.0.0 Release)

Package Renamed: lapr → couplr

The package has been renamed from lapr to couplr to better reflect its purpose as a general pairing and matching toolkit.

couplr = Optimal pairing and matching via linear assignment

Clean 1.0.0 Release

First official stable release with clean, well-organized codebase.

New Organization

R Code

• Eliminated 3 redundant files
• Consistent morph_* naming prefix
• Two-layer API: assignment() (low-level) + lap_solve() (tidy)
• 10 well-organized files (down from 13)

C++ Code

• Modular subdirectory structure:
  • src/core/ - Utilities and headers
  • src/interface/ - Rcpp exports
  • src/solvers/ - 14 LAP algorithms
  • src/gabow_tarjan/ - Gabow-Tarjan solver
  • src/morph/ - Image morphing

Features

Solvers

Hungarian, Jonker-Volgenant, Auction (3 variants), SAP/SSP, SSAP-Bucket, Cost-scaling, Cycle-cancel, Gabow-Tarjan, Hopcroft-Karp, Line-metric, Brute-force, Auto-select

High-Level

✅ Tidy tibble interface ✅ Matrix & data frame inputs
✅ Grouped data frames ✅ Batch solving + parallelization ✅ K-best solutions (Murty, Lawler) ✅ Rectangular matrices ✅ Forbidden assignments (NA/Inf) ✅ Maximize/minimize ✅ Pixel morphing visualization

API

• lap_solve() - Main tidy interface
• lap_solve_batch() - Batch solving
• lap_solve_kbest() - K-best solutions
• assignment() - Low-level solver
• Utilities: get_total_cost(), as_assignment_matrix(), etc.
• Visualization: pixel_morph(), pixel_morph_animate()

Development history under “lapr” available in git log before v1.0.0.