Why Small PMM Coding Errors Matter
Predictive mean matching (PMM) is often described as a flexible imputation method because it takes an imputed value from an observed case rather than generating a new value from a fitted outcome distribution. That property does not make an implementation automatically sound. The donor must be selected using the intended predictive scores, uncertainty in the model must be represented as specified, and the variables supplied to the model must have an appropriate statistical meaning.
This tutorial focuses on four practical errors: matching on observed outcomes instead of prediction scores, omitting parameter draws, treating arbitrary category codes as quantitative, and confusing the number of candidate donors with the number of imputed data sets. Each can produce plausible-looking completed data while changing the conditional distributions that the imputation is meant to represent.
The usual rationale assumes that the conditional model is suitable for predicting \(Y\) from \(X\), that the predictors contain the relevant information for the imputation, and that observed cases provide usable donors for cases with missing outcomes. In a MICE analysis, the missingness assumptions and the choice of variables also matter; PMM does not remove those requirements. In particular, matching cannot manufacture information in regions where observed cases provide no comparable donors.
Implementation Error 1: Matching on Outcomes Instead of Scores
The distance used for donor selection is a distance between predictive scores, not between an observed donor outcome and a missing case’s predicted outcome. For a fitted coefficient vector \(\beta\), a common score is \(X_i^\mathsf{T}\beta\). If \(i\) is missing the outcome and \(j\) has an observed outcome, the matching distance is
The donor’s actual \(Y_j\) is transferred only after donor selection. It is not substituted for \(X_j^\mathsf{T}\beta\) in the distance calculation. A common faulty implementation compares \(X_i^\mathsf{T}\beta\) with \(Y_j\), mixing a model-based score with a realized outcome that includes residual variation. That can rank donors differently from the intended algorithm.
Worked Example: Finding an Outcome-Scale Matching Bug
Suppose a fitted model gives predictive scores 5.00, 5.10, and 8.00 for observed cases A, B, and C. Their observed outcomes are 20, 0, and 6 units, respectively. A case with a missing outcome has a predictive score of 5.05. For simplicity, suppose the donor count is one.
Correct calculation. Compare the missing case’s score with each observed case’s score:
A and B are tied for the closest score. A valid tie-handling rule must be applied; for example, choose randomly between the tied closest donors. The donor outcome will then be either 20 or 0 units.
Faulty calculation. If the code compares the missing case’s score with observed outcomes instead, it obtains \(|5.05-20|=14.95\), \(|5.05-0|=5.05\), and \(|5.05-6|=0.95\). It selects C, whose score was far from the missing case’s score. The mistake changes the donor pool and thus the imputed outcome distribution. It is not fixed by the fact that the selected outcome, 6 units, appears numerically close to 5.05.
A reliable code review checks the quantities on both sides of the distance explicitly. They should be scores calculated on the same scale using the same parameter draw. Mixing a score with a raw outcome is a scale error even when both happen to be recorded in the same units.
Implementation Error 2: Omitting Parameter Draws
In PMM implementations that use parameter draws, uncertainty in the fitted model is represented by drawing model parameters, then calculating predictive scores under that draw. Replacing the draw with a single fixed estimate, such as the maximum-likelihood estimate in every iteration, removes a source of variation. Using a random donor does not, by itself, restore the missing parameter uncertainty: donor randomness and model-parameter uncertainty are distinct.
One way to see the consequence is the law of total variance. Let \(\theta\) denote uncertain model parameters and \(Q\) a quantity computed from completed data. The total variance has two components:
The first component reflects variation conditional on a parameter value; the second reflects variation across plausible parameter values. A fixed-parameter implementation can omit or greatly reduce the second component. As a result, repeated imputations may vary less than they should, and uncertainty in estimates combining the imputations may be understated.
Worked Example: Checking Scores Under Two Parameter Draws
Consider a one-predictor model with predictor \(x\). Two observed donors have \(x_A=0\) and \(x_B=1\), and a case with a missing outcome has \(x_i=0.6\). Suppose two parameter draws are \((\beta_0,\beta_1)=(1,3)\) and \((4,1)\). These values are hypothetical and are used only to illustrate how to check calculations.
Under the first draw, scores are \(1+3x\). Thus A’s score is \(1+3(0)=1\), B’s is \(1+3(1)=4\), and the missing case’s is \(1+3(0.6)=2.8\). The distances are \(|2.8-1|=1.8\) for A and \(|2.8-4|=1.2\) for B, so B is the closer donor.
Under the second draw, scores are \(4+x\). A’s score is 4, B’s is 5, and the missing case’s is \(4+0.6=4.6\). The distances are \(|4.6-4|=0.6\) for A and \(|4.6-5|=0.4\) for B, so B is again closer. The donor happens to be the same under both draws; this does not make the draws redundant. The scores and distances differ, and in a more complex predictor configuration a parameter draw can change donor rankings as well as scores.
If an implementation instead uses one fixed coefficient vector for every imputation, it cannot represent variation across such parameter draws. A useful check is to log or inspect the coefficient draws and resulting scores for a small run, not merely to confirm that the donor-sampling step is random.
The precise parameter-drawing procedure depends on the model and software implementation. The key check is whether the implementation follows the specified PMM algorithm, including its uncertainty treatment, rather than silently reusing one fitted coefficient vector. A draw that is generated but not used to calculate the scores is also an implementation error.
Implementation Error 3: Arbitrary Numeric Codes for Categories
A model treats a numeric predictor according to the structure specified for it. Entering categories as 1, 2, and 3 in a linear predictor generally treats them as quantitative: it imposes an order and equal spacing. That structure is not justified merely because a software data table stores the categories as numbers. If the categories are nominal, use a categorical-variable representation, such as indicator variables with a stated reference category, or an appropriate model parameterization.
Worked Example: When Numeric Codes Invent a Trend
Suppose a hypothetical clinic records service type as A, B, or C. These labels are nominal: there is no meaningful claim that B lies halfway between A and C. A programmer encodes them as 1, 2, and 3 and includes the code as a single linear predictor. The fitted model then assigns predicted-score contributions \(\beta\), \(2\beta\), and \(3\beta\) to A, B, and C.
If \(\beta=2\) score units per code, the imposed contributions are 2, 4, and 6. The model therefore forces a one-unit code increase to have the same two-score-unit effect from A to B as from B to C. Relabeling the same services as 1, 3, and 2 would change the model’s numerical relationships, even though no service or person changed. That dependence on arbitrary labels demonstrates why a numeric code is not an adequate quantitative predictor here.
With indicator coding and A as the reference, the linear predictor can instead include separate terms for B and C. Their fitted contributions need not be ordered or equally spaced. PMM scores are then calculated from that appropriate model representation. If categories are genuinely ordinal, a numeric trend may be defensible only when the chosen coding and trend assumptions are substantively justified.
Incorrect coding can distort predicted scores, group cases in inappropriate ways, and exclude sensible donors while favoring others. Before fitting, check variable types, factor levels, reference categories, and the model matrix produced by the software. A code that runs without an error message is not necessarily representing the intended predictor structure.
Implementation Error 4: Confusing Donor Count With Imputation Count
Two separate choices are often denoted by different quantities. Let \(k\) be the number of nearest observed cases considered as candidate donors for a missing value. Let \(m\) be the number of completed data sets generated for the analysis. These numbers serve different purposes: \(k\) controls the size of a local donor pool, while \(m\) controls how many completed data sets are available for representing imputation variability and carrying out the subsequent analysis.
Worked Example: Interpreting Donor Count and Imputation Count
Suppose a PMM run uses \(k=4\) candidate donors and generates \(m=6\) completed data sets. For one missing cell, the algorithm identifies the four closest observed cases according to the score distances. In each completed data set, it draws one donor from the candidate set according to the implementation’s sampling rule and inserts that donor’s outcome.
Thus the cell receives one imputed value in each of six completed data sets, not four values in each data set. The four is the candidate-pool size; the six is the number of completed versions. Donor draws may happen to repeat across the six sets, and a donor may also be used for other missing cases. Increasing \(k\) does not create more completed data sets, and increasing \(m\) does not enlarge the candidate pool.
A common bug is to use one setting where the other was intended—for instance, generating four completed data sets because the code’s donor setting is four. The result may still be a valid-looking collection of data tables, but it does not implement the requested choices. Check software arguments by their documented meaning and verify the dimensions and number of returned completed data sets.
Practical Checks, Alternatives, and Limits
A compact audit can catch many of these errors before a full analysis. For a few missing cases, calculate the scores and distances by hand and compare them with the software output. Confirm that the observed outcomes are copied only after donor selection, that the intended parameter draws affect the scores, and that categorical predictors have the intended model representation. Then verify that the reported candidate-pool size and number of completed data sets match the requested settings.
Confirm the outcome, predictors, missingness pattern, factor coding, and model form. Check that the observed cases used to fit the model are the intended cases.
For a small test case, calculate a score for each observed case and missing case under the same parameter draw. Ensure distances compare score to score.
Check that parameter draws are used when required, donor sampling follows the specified rule, \(k\) is the candidate-pool size, and \(m\) is the number of completed data sets.
PMM is not the only option. Parametric regression imputation generates an outcome from a specified conditional distribution rather than transferring an observed donor outcome. This can provide model-based values beyond the observed outcome values, but depends more directly on the distributional specification. PMM preserves observed outcome values, but that feature does not guarantee suitable donors or correct conditional relationships. The choice between approaches depends on the outcome, model adequacy, donor support, and inferential goal; neither approach repairs an inappropriate predictor set or unjustified missingness assumptions.
A key limitation is that PMM’s empirical support is inherited from observed donor outcomes. If a missing case is in a predictor region with no comparable observed cases, its nearest available donors may still be poor matches. Increasing the donor count can broaden the pool but does not create information where overlap is absent. Conversely, an extremely small candidate pool can concentrate imputations on a narrow set of outcomes. These are design and data limitations, not coding errors that can always be corrected by changing a setting.
Common Mistakes to Avoid
- Comparing an observed \(Y_j\) with a missing case’s prediction. This mixes a realized outcome with a model score. Compare predictive scores with predictive scores, then transfer the selected donor’s outcome.
- Assuming donor randomness replaces parameter uncertainty. Randomly selecting a donor from a fixed ranking does not represent uncertainty in the fitted model. Follow the parameter-drawing procedure required by the implementation.
- Assuming numeric storage means a quantitative variable. Codes for nominal categories are labels unless a meaningful numerical structure is justified.
- Calling the candidate-pool size the number of imputations. The donor count \(k\) and completed-data count \(m\) are separate settings with separate roles.
- Assuming plausible-looking imputations prove correct implementation. Donor values can look reasonable even when they came from the wrong pool or the model omitted intended uncertainty.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions below.
- A missing case has score 3.2. Two observed cases have scores 3.1 and 7.0, with outcomes 15 and 3 units. Which is the closer donor by score, and why is comparing the outcomes to 3.2 incorrect?
- An implementation randomly samples donors but uses the same fitted coefficients in every imputation. What uncertainty may be missing?
- A nominal three-category predictor is coded 1, 2, and 3 as one linear predictor. What structure does this impose, and what is a more suitable approach?
- A procedure uses \(k=5\) and \(m=8\). State what each number means for a single missing cell.
Solutions. (1) The score distances are \(|3.2-3.1|=0.1\) and \(|3.2-7.0|=3.8\), so the first case is closer. Comparing outcomes 15 and 3 with 3.2 uses raw outcomes rather than the predictive scores used to define the donor neighborhood. (2) It may omit variation across plausible parameter values, reducing between-imputation variability and potentially understating uncertainty. Random donor selection is not a substitute for parameter draws. (3) It imposes an order and equal spacing of category effects per code unit. Use categorical indicators or another justified categorical parameterization; use a numeric trend only if its structure is defensible. (4) Five is the candidate-donor pool size; eight is the number of completed data sets. The cell gets one donor outcome in each completed data set, with donor selection repeated according to the procedure.