Assign item sets to counterbalancing lists so the lists match on the item dimensions

The factorial recipe's default deal is by set rank, which balances nothing. This searches instead for an assignment whose lists have near-equal totals on each declared dimension, by steepest-descent pairwise swaps between lists. List sizes are preserved, because a swap exchanges one set for another.

Usage

balance_lists(stimuli, design, schema)

Arguments

stimuli

A stimuli data frame with a set column and the balance dimensions.

design

A parsed design configuration. Reads counterbalance.lists, counterbalance.balance_on (defaulting to match_on, then to the continuous predictor and controls), counterbalance.max_passes and counterbalance.scale (mean or mad, defaulting to mean).

schema

The parsed global schema (provides the seed).

Value

A list with list_of_set (a named integer vector mapping each set to a list) and report (the dimensions, the integer cost before and after, the number of swaps taken, whether the pass bound was reached, the unit the cost is counted in and, under the mad scale, the scale).

Details

The search is deterministic and identical in the R and Python engines: the objective is all-integer (see the notes in this file), the descent takes the single best swap each pass, and ties are broken by the seeded keyed hash rather than by position, so no list is favoured by being numbered first. Because the cost is a non-negative integer that strictly decreases, the search terminates; max_passes bounds it anyway and the report says whether the bound was reached.

counterbalance.scale sets each dimension's unit. mean, the default, divides by the dimension's mean, which suits ratio scales only. mad balances deviations from the mean in units of the mean absolute deviation, so adding a constant to a dimension, such as writing Zipf frequency as Zipf - 3, leaves the lists unchanged. The report then gives scale too, and cost_unit names the unit under either scale.

Five situations are refused rather than answered with an assignment that would mislead. A Latin-square design is refused because every item already appears in every list there, so there is nothing left to equate, and fewer than two lists leaves no pair of lists to exchange sets between. A design with no resolvable balance dimension is refused, as is one naming a dimension the stimuli do not carry, and the message names the columns. The last refusal is arithmetic: the search stops if the integer objective would leave the range a double represents exactly, since past that point the two engines could disagree.