Package: couplr 1.4.1

couplr: Optimal Pairing and Matching via Linear Assignment

Solves optimal pairing and matching problems using linear assignment algorithms. Provides implementations of the Hungarian method (Kuhn 1955) <doi:10.1002/nav.3800020109>, Jonker-Volgenant shortest path algorithm (Jonker and Volgenant 1987) <doi:10.1007/BF02278710>, Auction algorithm (Bertsekas 1988) <doi:10.1007/BF02186476>, cost-scaling (Goldberg and Kennedy 1995) <doi:10.1007/BF01585996>, scaling algorithms (Gabow and Tarjan 1989) <doi:10.1137/0218069>, push-relabel (Goldberg and Tarjan 1988) <doi:10.1145/48014.61051>, and Sinkhorn entropy-regularized transport (Cuturi 2013) <doi:10.48550/arxiv.1306.0895>. Designed for matching plots, sites, samples, or any pairwise optimization problem. Supports rectangular matrices, forbidden assignments, data frame inputs, batch solving, k-best solutions, and pixel-level image morphing for visualization. Includes automatic preprocessing with variable health checks, multiple scaling methods (standardized, range, robust), greedy matching algorithms, and comprehensive balance diagnostics for assessing match quality using standardized differences and distribution comparisons.

Authors:Gilles Colling [aut, cre, cph]

couplr_1.4.1.tar.gz
couplr_1.4.1.zip(r-4.7)couplr_1.4.1.zip(r-4.6)couplr_1.4.1.zip(r-4.5)
couplr_1.4.1.tgz(r-4.6-x86_64)couplr_1.4.1.tgz(r-4.6-arm64)couplr_1.4.1.tgz(r-4.5-x86_64)couplr_1.4.1.tgz(r-4.5-arm64)
couplr_1.4.1.tar.gz(r-4.7-arm64)couplr_1.4.1.tar.gz(r-4.7-x86_64)couplr_1.4.1.tar.gz(r-4.6-arm64)couplr_1.4.1.tar.gz(r-4.6-x86_64)
couplr_1.4.1.tgz(r-4.6-emscripten)
manual.pdf |manual.html
DESCRIPTION |NEWS
card.svg |card.png
couplr/json (API)

# Install 'couplr' in R:
install.packages('couplr', repos = c('https://gcol33.r-universe.dev', 'https://cloud.r-project.org'))

Bug tracker:https://github.com/gcol33/couplr/issues

Pkgdown/docs site:https://gillescolling.com

Uses libs:
  • c++– GNU Standard C++ Library v3
Datasets:

On CRAN:

Conda:

bipartite-matchinglinear-assignmentoptimizationcpp

6.35 score 1 stars 39 scripts 527 downloads 46 exports 54 dependencies

Last updated from:6c2f0c7edc. Checks:13 OK. Indexed: yes.

TargetResultTimeFilesSyslog
linux-devel-arm64OK290
linux-devel-x86_64OK290
source / vignettesOK384
linux-release-arm64OK287
linux-release-x86_64OK293
macos-release-arm64OK259
macos-release-x86_64OK599
macos-oldrel-arm64OK361
macos-oldrel-x86_64OK577
windows-develOK372
windows-releaseOK364
windows-oldrelOK318
wasm-releaseOK249

Exports:animated_methodsas_assignment_matrixas_matchitassignmentassignment_dualsaugmentbal.tab.cem_resultbal.tab.full_matching_resultbal.tab.matching_resultbal.tab.subclass_resultbalance_diagnosticsbalance_tablebottleneck_assignmentcardinality_matchcem_matchcompute_distancesdiagnose_distance_matrixexample_costsexample_dffull_matchget_method_usedget_total_costgreedy_couplesgroup_byis_distance_objectis_lap_solve_batch_resultis_lap_solve_kbest_resultis_lap_solve_resultjoin_matchedlap_animatelap_solvelap_solve_batchlap_solve_kbestlap_solve_line_metricmatch_couplesmatch_datamatchmakerpixel_morphpixel_morph_animatepreprocess_matching_varsps_matchsensitivity_analysissinkhornsinkhorn_to_assignmentsubclass_matchupdate_constraints

Dependencies:base64encbriobslibcachemcallrclicrayondescdiffobjdigestdplyrevaluatefastmapfontawesomefsgenericsgluehighrhtmltoolshtmlwidgetsjquerylibjsonliteknitrlifecyclemagrittrmemoisemimeotelpillarpkgbuildpkgconfigpkgloadpraiseprocessxpspurrrR6rappdirsRcppRcppEigenrlangrmarkdownrprojrootsasstestthattibbletidyselecttinytexutf8vctrswaldowithrxfunyaml

The Algorithm Collection
Overview | Who This Vignette Is For | The Race | Watch It Run | Hungarian on a 30x30 | Auction on a 30x30 | Gabow-Tarjan bit-scaling on a 30x30 | Jonker-Volgenant pre-stages on a 30x30 | The Problem | The LP Formulation | Duality: The Key to Efficiency | The Classics | Hungarian Algorithm (1955) | Jonker-Volgenant Algorithm (1987) | The Scaling Revolution | Auction Algorithm (1988) | Cost-Scaling Algorithm / CSA (1995) | Gabow-Tarjan Algorithm (1989) | Orlin-Ahuja Algorithm (1992) | The Network View | Network Simplex | Push-Relabel Algorithm | The Specialists | HK01: Binary Costs | SAP and LAPMOD: Sparse Problems | Ramshaw-Tarjan: Rectangular Problems (2012) | Beyond Standard Assignment | K-Best Solutions (Murty's Algorithm) | Bottleneck Assignment | Sinkhorn: Soft Assignment | Dual Variables | The Benchmark | Quick Reference | References

Last update: 2026-05-19
Started: 2025-11-15

Matching Workflows
Overview | Who This Vignette Is For | Documentation Roadmap | The Running Example: Job Training Evaluation | Key Features | Problem Definition | The Matching Problem | Why Matching Matters | Distance Metrics | Basic Usage | Creating a Matched Sample | Understanding the Output | Automatic Preprocessing | Why Preprocessing Matters | Smart Scaling with auto_scale = TRUE | Scaling Methods | Health Checks and Warnings | Optimal vs Greedy Matching | When to Use Each Approach | Greedy Strategies | Caliper Constraints | Why Use Calipers | Choosing Caliper Width | Blocking and Stratification | Why Use Blocking | Exact Blocking with matchmaker() | Cluster-Based Blocking | Balance Diagnostics | Key Balance Metrics | How to Interpret Balance Results | Visualizing Balance | Real-World Example: Treatment Effect Estimation | Scenario | Step 1: Data Preparation | Step 2: Perform Matching | Step 3: Assess Balance | Step 4: Estimate Treatment Effect | Step 5: Publication-Ready Output | Performance Considerations | Scalability | Memory Usage | Optimization Tips | What Can Go Wrong | Problem: Poor Balance Despite Matching | Problem: Very Few Matches | Problem: Matching Takes Too Long | Problem: Memory Error | Summary | Advanced Matching Techniques | Full Matching (Variable-Ratio Groups) | Ratio Matching (k:1) | With-Replacement Matching | Propensity Score Matching | Cardinality Matching | Coarsened Exact Matching (CEM) | Subclassification | Ecosystem Integration | Sensitivity Analysis | Visualizing Results with autoplot | See Also

Last update: 2026-03-09
Started: 2025-11-20

Comparison with Alternatives
Overview | Evaluation Dataset | Comparison 1: MatchIt | MatchIt Approach | couplr Approach | Balance Comparison | Key Differences | When to Use Each | Comparison 2: optmatch | optmatch Approach | Performance Comparison | Comparison 3: designmatch | designmatch Approach | Comparison 4: Matching Package | Matching Package Approach | Runtime Scaling | Memory Usage | Feature Comparison Summary | Decision Guide | Choose couplr when: | Choose MatchIt when: | Choose optmatch when: | Choose designmatch when: | Workflow Integration | Sequential Pipeline | Complementary Use | Real-World Case Study: Job Training Evaluation | Background | Simulating Lalonde-Style Data | Challenge: Large Control Pool | Balance Assessment | Interpretation | Key Takeaways | References | See Also

Last update: 2026-03-04
Started: 2026-01-07

Quick Start
What couplr Does | Documentation Roadmap | Your First Match | Understanding the Output | Why Scaling Matters | Checking Match Quality | Visualizing Match Quality | Large Datasets: Use Greedy Matching | Setting a Maximum Distance (Caliper) | Matching Within Groups (Blocking) | Full Matching: Keep Every Unit | Other Matching Methods | Complete Example | Next Steps | Additional: Direct Assignment Problem Solving | lap_solve(): Matrix-Based Assignment | Forbidden Assignments | Maximization | Grouped Data | K-Best Solutions | See Also

Last update: 2026-03-04
Started: 2025-11-07

Troubleshooting Guide
Overview | Infeasible Problems | Symptom | Cause | Diagnosis | Solutions | Poor Balance Despite Matching | Causes | Performance Issues | Memory Errors | Different Results with Different Methods | Missing Values in Data | Installation Issues | C++ Compilation Errors | Common Error Messages | "method_used attribute is NULL" | "Cost matrix contains non-finite values" | "All rows assigned to Inf columns" | "subscript out of bounds" | Getting Help | See Also

Last update: 2026-03-03
Started: 2026-01-07

Advanced Topics
Overview | Who This Vignette Is For | Documentation Roadmap | Why Pixels? | Scientific Applications at a Glance | The General Matching Problem | Problem Formulation | Computational Challenge | Visual Illustration: Pixel Morphing | Exact Pixel Matching | Feature Quantization Morph (Strategy 1) | Hierarchical Morph (Strategy 2) | Three Approximation Strategies | Strategy 1: Feature Quantization | Mathematical Formulation | Complexity Reduction | Quality Trade-offs | Strategy 2: Hierarchical Decomposition | Complexity (Sketch) | High-Level Algorithm | Strategy 3: Resolution Reduction | Complexity | Strategy Comparison | Implementation Details of Exact Pixel Matching | Application to Scientific Domains | Ecology: Vegetation Plot Matching | Physics: Particle Tracking | Chemistry: Molecular Conformation Alignment | Implementation Notes | Customizing Morph Duration | Using the Example Code | Regenerating Examples | Mathematical Foundation: Optimal Transport | Monge Problem | Kantorovich Relaxation | Discrete Linear Assignment | Wasserstein Distance | Further Reading | Optimal Transport Theory | Scientific Applications | Assignment Algorithms | Connection to couplr Workflows | When Do These Strategies Apply? | Practical Recommendations | Limitations of Approximation Strategies | Summary | See Also

Last update: 2026-01-21
Started: 2025-11-15

Readme and manuals

Help Manual

Help pageTopics
List methods that currently support animationanimated_methods
Convert assignment result to a binary matrixas_assignment_matrix
Convert couplr Result to matchit Objectas_matchit
Linear assignment solverassignment
Solve assignment problem and return dual variablesassignment_duals
Generic Augment Functionaugment
Augment Matching Results with Original Data (broom-style)augment.matching_result
ggplot2 autoplot for balance diagnosticsautoplot.balance_diagnostics
ggplot2 autoplot for matching resultsautoplot.matching_result
ggplot2 autoplot for sensitivity analysisautoplot.sensitivity_analysis
Balance Table for Matching Results (cobalt integration)bal.tab.cem_result bal.tab.full_matching_result bal.tab.matching_result bal.tab.subclass_result
Balance Diagnostics for Matched Pairsbalance_diagnostics balance_diagnostics.cem_result balance_diagnostics.full_matching_result balance_diagnostics.matching_result balance_diagnostics.subclass_result
Create Balance Tablebalance_table
Solve the Bottleneck Assignment Problembottleneck_assignment
Cardinality Matchingcardinality_match
Coarsened Exact Matchingcem_match
Compute and Cache Distance Matrix for Reusecompute_distances
Diagnose distance matrix and suggest fixesdiagnose_distance_matrix
Example cost matrices for assignment problemsexample_costs
Example assignment problem data frameexample_df
Full Matchingfull_match
Extract method used from assignment resultget_method_used
Extract total cost from assignment resultget_total_cost
Fast approximate matching using greedy algorithmgreedy_couples
Hospital staff scheduling example datasethospital_staff
Check if Object is a Distance Objectis_distance_object
Check if object is a batch assignment resultis_lap_solve_batch_result
Check if object is a k-best assignment resultis_lap_solve_kbest_result
Check if object is an assignment resultis_lap_solve_result
Join Matched Pairs with Original Datajoin_matched join_matched.cem_result join_matched.full_matching_result join_matched.matching_result join_matched.subclass_result
Animate an assignment algorithm step-by-steplap_animate
Solve linear assignment problemslap_solve
Solve multiple assignment problems efficientlylap_solve_batch
Find k-best optimal assignmentslap_solve_kbest
Solve 1-D Line Assignment Problemlap_solve_line_metric
Optimal matching using linear assignmentmatch_couples
Extract Analysis-Ready Data from Matching Resultsmatch_data match_data.cem_result match_data.full_matching_result match_data.matching_result match_data.subclass_result
Create blocks for stratified matchingmatchmaker
Pixel-level image morphing (final frame only)pixel_morph
Pixel-level image morphing (animation)pixel_morph_animate
Plot method for balance diagnosticsplot.balance_diagnostics
Plot method for matching resultsplot.matching_result
Plot method for sensitivity analysis (base graphics)plot.sensitivity_analysis
Preprocess matching variables with automatic checks and scalingpreprocess_matching_vars
Print Method for Balance Diagnosticsprint.balance_diagnostics
Print Method for CEM Resultsprint.cem_result
Print Method for Distance Objectsprint.distance_object
Print Method for Full Matching Resultsprint.full_matching_result
Print method for batch assignment resultsprint.lap_solve_batch_result
Print method for k-best assignment resultsprint.lap_solve_kbest_result
Print method for assignment resultsprint.lap_solve_result
Print method for matching resultsprint.matching_result
Print method for matchmaker resultsprint.matchmaker_result
Print method for preprocessing resultprint.preprocessing_result
Print method for sensitivity analysisprint.sensitivity_analysis
Print Method for Subclassification Resultsprint.subclass_result
Print method for variable healthprint.variable_health
Propensity Score Matchingps_match
Rosenbaum Sensitivity Analysissensitivity_analysis
'Sinkhorn-Knopp' optimal transport solversinkhorn
Round 'Sinkhorn' transport plan to hard assignmentsinkhorn_to_assignment
Subclassification on Propensity Scoresubclass_match
Summary method for balance diagnosticssummary.balance_diagnostics
Summary Method for Distance Objectssummary.distance_object
Get summary of k-best resultssummary.lap_solve_kbest_result
Summary method for matching resultssummary.matching_result
Summary method for sensitivity analysissummary.sensitivity_analysis
Update Constraints on Distance Objectupdate_constraints