Counterbalancing & Assignment

Within-subjects structure — factors, crossing, sampling, shuffling — decides what one participant sees and in what order (see Experiment Design). Counterbalancing is the orthogonal question: across many participants, who gets which condition, kept balanced and auditable. In PsyCloud it's declared, not left to chance. Stateful hosted modes record assignments in the server ledger; cb_hash is the separate stateless mode for teams that prefer per-run reproducibility over active balancing.

Two layers that work together

Counterbalancing in PsyCloud has two cooperating pieces:

1. A per-trial assignment step — assign_between. Inside a phase's pipeline, it filters the trial table down to the rows matching this participant's assigned cell. Methods:
   • hash — deterministic from the participant id; no server state required.
   • quota — balanced toward target counts (server-tracked).
   • random — seeded random pick.
2. A bundle-level allocation policy — cb_hash / cb_random / cb_rotation. This declares the factor's levels and the algorithm the server uses to allocate each new participant to a cell. cb_hash is stateless; cb_random and cb_rotation use the allocation ledger to balance as people arrive.

The policy decides which cell a participant is in; assign_between applies that cell to the trial table at run time. Most studies use both (as below); a quick pilot can use assign_between(method = "hash") alone.

Declare it

# Per-trial: filter the practice/main rows to this participant's mapping cell.
exp |>
  phase("practice", label = "Practice") |>
  trials(both_mappings(practice_rows)) |>
  assign_between(factor = "mapping", method = "hash")
 
# ... later, at the bundle level: declare the stateless hash policy.
exp |>
  bundle(
    with_auto_ids = TRUE,
    counterbalance = cb_hash(mapping = c("A", "B"))
  )

Hash, random, rotation, minimization

The policy's algorithm decides how participants are spread across cells:

• cb_hash derives the cell from the run id, assignment key, policy hash, namespace, and strata. It requires no state read and no allocation lock, so it scales well and is reproducible per run. It is balanced only in expectation and cannot enforce quotas, streak-avoidance, balance targets, or online item rotation.
• cb_random records each participant in the hosted allocation ledger and samples toward the target proportions as people arrive. Assignment is unpredictable; at small N a run can be uneven — it's balanced in expectation, not exactly.
• cb_rotation assigns by cycling through the cells (the order reshuffled each full cycle), so the cells are evened out after each complete cycle — the tightest balance, best at small/medium N. If the next scheduled cell is unavailable (e.g. a hard quota is full) it falls back to the balancing (minimization) algorithm.
• Minimization is the lower-level adaptive allocator for finite-sample balancing against explicit objectives, quotas, and recent-assignment penalties.

Rule of thumb: reach for cb_hash when reproducible, stateless assignment is more important than active balance; cb_rotation when you want maximally even cells throughout; and cb_random when you want unpredictable assignment and N is large enough that balance-in-expectation is fine.

# Hash: reproducible per run, no server state needed for the decision
bundle(counterbalance = cb_hash(mapping = c("A", "B")))
 
# Random: ledger-backed, ~50/50 in expectation
bundle(counterbalance = cb_random(mapping = c("A", "B")))
 
# Rotation: as-even-as-possible at every point (tighter at small N)
bundle(counterbalance = cb_rotation(mapping = c("A", "B")))
 
# Multi-factor (2x2): the two axes are crossed into 4 cells
bundle(counterbalance = cb_rotation(
  mapping = c("A", "B"),
  framing = c("gain", "loss")
))

For weighted splits, quotas, balance targets, or streak-avoidance, drop to the lower-level cb_policy() builder. Those stateful constraints are not allowed with cb_hash. Cells are counted by assigned participants by default (accounting_unit can count started / completed / passed_qc instead).

The both_mappings(...) / practice_rows helpers above are illustrative — see the full runnable study in the repo's examples/high-level/task-switching-gate.

How balance actually happens (hosted vs. preview)

This distinction matters and is easy to get wrong:

• Hosted runs (real participants). At session start the server allocates the participant using the policy's algorithm. With cb_hash, it derives the cell from the run id, assignment key, policy hash, namespace, and strata, then records the result. With cb_rotation, cb_random, or minimization, it reads the allocation ledger, chooses from the current counts/history, and records the decision. The chosen cell is fixed for the session and passed to the runtime, where assign_between applies it.
• Preview / simulate (no server). There's no ledger, so PsyCloud makes a stable, seeded per-participant pick across the declared levels — enough to exercise the design and reproduce a given participant, but not cross-participant balanced.
• Compiled bundles. A compiled bundle has no participant, so compilation pins one representative cell (the first level of each between-subject axis) consistently across all scopes. Inspect a compiled artifact and you'll see that single cell — not the live per-participant allocation.

Reproducibility

There are two different guarantees, depending on where assignment happens:

• Preview / simulate is seeded — assignment and trial order derive from a deterministic chain (study + participant + namespace), so they reproduce offline from the seed alone.
• Hosted stateful assignment is ledger-backed — for cb_random, cb_rotation, and minimization, reconstruct from the stored assignment plus the policy, not a seed alone. The decision depends on arrival order and counts.
• Hosted cb_hash is stateless per run — the first assignment is derived from run id, assignment key, policy hash, namespace, and strata. The recorded assignment still wins for a returning participant, so a mid-study policy or namespace edit does not silently reassign someone already recorded. Re-launches produce fresh assignments because the run id is part of the hash input.

The within-subject trial order for a given participant is seed-reproducible in both cases. Pair the stored assignment with a preregistered analysis script for fully reproducible results. Changing randomNamespace in the design's determinism settings deliberately invalidates all previously generated streams.

Order counterbalancing (Latin square)

For within-session order effects (e.g. block order), PsyCloud's allocators include Latin-square schemes — cyclic rotation and balanced Williams designs (which control first-order carryover). These are selected through the allocation policy rather than assign_between.

In Studio

When a phase contains an assign_between step, Studio surfaces a between-subjects factor banner in Trial Design with a per-factor method selector — Balanced quota (recommended), Deterministic hash, or Random. Advanced balancing (targets, Latin-square / balanced blocks, sequential effects) is configured through the counterbalance wizard reached from the assignment inspector.

Validation & checking allocation

• psycloud validate <bundle-or-study> and psycloud inspect <bundle-or-study> --section counterbalance check the policy structure (schema 0.1.1 / 0.1.2): factor ids, non-empty levels, proportions, quotas. Hash policies reject stateful fields such as quotas, streak-avoidance, balance targets, and online item rotation.
• On a live run, Monitor shows allocation status. Data exports carry an assignment_hash per session, and the participant's cell shows up as the filtered factor values in the trial rows (after assign_between) — there's no separate assigned-cell column, so confirm balance from those.

Known limits (alpha)

Next