# Enrolment and randomisation

This chapter explains how the portal decides which arm a participant goes into, and how
it knows when to pause or stop recruiting. You set the inputs in
{doc}`setup/3-treatment-phases`; this is what the portal does with them.

## The two things you set

Per arm, participants to complete
: For each active or sham arm, the number of participants you expect to **complete** it.

Per trial, estimated completion rate
: The fraction of enrolled participants you expect to finish (default 0.5).

Everything else is worked out from these.

## What the portal derives

Total completion target
: The sum of the per-arm targets. This is the number of completed participants the
  trial is aiming for.

Randomisation shares
: Each arm's target divided by the total. With targets 50 / 25 / 25 the shares are
  50% / 25% / 25%.

Total enrolment limit
: The total completion target divided by the completion rate, rounded up. It is the
  most participants that may be enrolled at once.

:::{admonition} Worked example
:class: note
Targets **50 / 25 / 25**, rate **0.5**:
- randomisation shares **0.5 / 0.25 / 0.25**
- total completion target **100** participants
- total enrolment limit **200** (100 ÷ 0.5)
:::

## How participants are assigned

Assignment is **weighted random**: a new participant is placed into an arm with
probability equal to that arm's share. An arm with twice the target gets twice the
chance.

Two properties matter:

- **Targets are soft.** An arm is never closed for being "full"; it can overshoot. So
  targets 50 / 25 / 25 might finish as, say, 67 / 23 / 38, that is expected and fine.
- **The shares are fixed.** They do not rebalance as arms fill. The portal will not
  steer participants toward an under-filled arm to hit the targets exactly, so final
  counts scatter around the targets rather than landing on them.

If you genuinely want equal assignment across arms, give every arm the same target;
equal targets produce equal shares.

## When recruitment pauses or stops

Recruitment is governed by two trial-wide gates, never by a single arm.

Enrolment limit, a reversible **pause**
: When the number of participants currently enrolled (everyone who has not withdrawn)
  reaches the total enrolment limit, recruitment pauses. It resumes on its own as that
  number falls, for example when participants withdraw and free a place. A withdrawal
  refunds a place; a completion does not.

Completion target, an irreversible **stop**
: When the number of participants who have **completed** the trial reaches the total
  completion target, recruitment ends for good and does not reopen.

In a balanced trial you usually reach the completion target (the hard stop) before the
enrolment limit (the soft pause). The pause mainly bites when completions are lagging , 
lots of people enrolled and in progress, but few finishing yet, which is exactly when
you would want to stop pulling more people in.

## Adjusting the plan while it runs

You can change the per-arm targets and the completion rate after launch, from the trial
overview (see {doc}`running-a-trial`). The derived total, limit, and shares recompute,
and the gates use the new values from then on. This lets you retarget an under- or
over-recruiting trial without rebuilding it.

## Parallel vs crossover

The randomisation shares are defined per arm. In a **parallel** trial each participant
is in one arm, so the shares apply directly. In a **crossover** trial every participant
passes through all arms in a randomised order, so what is actually randomised is the
*order*; the per-arm targets weight those orderings. If you run a crossover design,
confirm the intended weighting with the trial statistician.