API reference

Main module: smallerize

class smallerize.smallerize.Factor(name: str, levels: Iterable[str], weight: float = 1.0)

A prognostic factor with 2 or more levels, that needs to be balanced between treatment arms.

get_random_level() → str

Return one of the factor’s levels at random (all levels have equal probability).

Returns

Name of the chosen level

Return type

str

get_random_level_multiple(n) → List[str]

Return n random levels, sampled with replacement. Faster than calling get_random_level multiple times.

Parameters

n – Number of random levels to generate.

Returns

List of level names.

class smallerize.smallerize.Arm(name: str, allocation_ratio: int = 1)

A treatment arm that participants will be assigned to. Different arms in the trial may have different allocation ratios, e.g. 1:2:1 for arms A, B and C.

class smallerize.smallerize.Minimizer(factors: Iterable[smallerize.smallerize.Factor], arms: Iterable[smallerize.smallerize.Arm], d_imbalance_method: str = 'standard_deviation', total_imbalance_method: str = 'sum', probability_method: str = 'best_only', **method_args)

Given a set of prognostic factors and treatment arms, assigns participants to arms based on the minimization algorithm (or purely random assignment for comparison).

D_IMBALANCE_METHODS = {'is_largest': <function _get_imbalance_is_largest>, 'marginal_balance': <function _get_imbalance_marginal_balance>, 'over_max_range': <function _get_imbalance_over_max_range>, 'range': <function _get_imbalance_range>, 'standard_deviation': <function _get_imbalance_std_dev>, 'variance': <function _get_imbalance_variance>}

PROBABILITY_METHODS = ['best_only', 'rank_all', 'pure_random', 'biased_coin']

TOTAL_IMBALANCE_METHODS = ['sum', 'weighted_sum']

add_existing_participant(factor_levels: dict, arm: str) → None

Add a participant who has already been assigned to the trial to the count table. Modifies the count table in place.

Parameters

• factor_levels – A dictionary where the keys are the names of the factors in the trial, and the values are the factor levels for the participant.

• arm – Name of the arm they are assigned to.

arm_names

assign_participant(factor_levels: dict) → str

Assign a new participant to the trial, using the minimization algorithm. Modifies the count table in place, and returns the chosen arm.

Parameters

factor_levels (dict) – A dictionary that maps from factor names to participants.

Returns

Name of chosen arm

Return type

str

factor_names

factor_weights

get_all_new_counts(factor_levels: dict) → Dict[str, dict]

For each potential arm that a new participant could be assigned to, calculate the number of participants that would be in each arm if the potential arm was chosen, within each factor level that the new participant belongs to.

Parameters

factor_levels (dict) – A dictionary that maps from factor names to factor levels, giving the participant’s factor levels for each factor used in the trial.

Returns

A nested dictionary, that maps from (potential arm) -> (factor name) -> dict of arm counts within that factor

get_arm_probability(imbalances: dict) → dict

Calculate the probability assigned to each arm, based on the current imbalances and the chosen probability method.

get_assignment_info(factor_levels: dict, do_assignment: bool = False) → dict

Alternative to assign_participant(), takes factor levels for a new participant, chooses an arm, and returns the arm along with extra details about whether the most-favoured arm was chosen. By default, the participant is not actually assigned. To assign the participant at the same time, set do_assignment=True.

Returns

dict with keys: 'arm': chosen arm, 'prob': probability that was assigned to that arm before the selection, 'most_favoured': Whether the chosen arm was the arm with the highest probability (including if it was tied for highest probability).

get_current_x_counts(factor_levels: dict) → Dict[str, dict]

Return the current x_ijk (arm counts within each factor), when considering a participant with the given factor_levels.

Parameters

factor_levels (dict) – A dictionary that maps from factor names to factor levels, giving the participant’s factor levels for each factor used in the trial.

Returns

get_n() → int

Get the number of arms for the trial.

get_new_ds(factor_levels: dict) → Dict[str, dict]

Calculate the d_ik scores, the imbalance score within each factor, for each potential arm that a new participant could be assigned to.

Parameters

factor_levels – A dict that maps from (factor name) -> (new participant’s factor level)

Returns

A dict that maps from (potential arm) -> (dict of scores for each factor)

get_new_total_imbalances(factor_levels: dict) → Dict[str, Union[int, float]]

Get the total imbalance scores that would result from assigning a participant with the given factor levels to each arm.

Parameters

factor_levels (dict) – Maps from factor names to the participant’s level for each factor.

Returns

Total imbalance score for each potential arm.

Return type

dict

reset_counts_to_zero()

Reset the counts of assigned participants to zero, i.e. starting over as if no participants had been assigned.

simulate

class smallerize.simulate.SimulatedTrial(minimizers: Dict[str, smallerize.smallerize.Minimizer], factors: List[smallerize.smallerize.Factor])

assign_one(factor_levels: dict) → dict

create_random_participants(n: int)

simulate(n_trials: int)