Skip to content

Matcher Objects

Creation

perfect_strangers.create_matcher 

create_matcher(groups_per_round: int, group_size: int, participant_labels: Sequence | None = None) -> BaseMatcher

Create a perfect stranger matcher for the given experiment parameters.

Parameters:

  • groups_per_round (int) –

    The number of groups per round of the experiment.

  • group_size (int) –

    The number of participants in each group.

  • participant_labels (Sequence | None, default: None ) –

    Unique labels for the experiment participants. This should be a sequence of participant labels with groups_per_round * group_spec unique elements.

Returns:

perfect_strangers.create_typed_matcher 

create_typed_matcher(groups_per_round: int, group_spec: GroupSpec, participant_labels: Sequence | None = None) -> TypedMatcher

Create a typed perfect stranger matcher for the given experiment parameters.

Parameters:

  • groups_per_round (int) –

    The number of groups per round of the experiment.

  • group_spec (GroupSpec) –

    A sequence of integers specifying the composition of each group. The length of the provided sequence defines the number of different types of participant. The values in the sequence give the number of participants of each type in each group. The total number of participants per groups is given by the sum of the values in the sequence.

  • participant_labels (Sequence | None, default: None ) –

    Unique labels for the experiment participants. Either a sequence of labels, or a sequence of sequences of labels.

    • If a sequence of labels is provided it should contain as many unique labels as there are total participants in the experiment (i.e. groups_per_round * sum(group_spec)). These labels will be assigned to different participant types automatically.
    • To specify participant typings yourself, provide a sequence of sequences. There should be as many sequences as there are participant types (i.e. elements of group_spec). The nth sequence should have groups_per_round * group_spec[n] unique elements.

Returns:

Base Classes

All matching methods inherit the interface of the BaseMatcher class.

perfect_strangers.BaseMatcher

Base class for all group matching methods.

max_rounds property 

max_rounds: int

The maximum number of rounds this matcher will produce under perfect stranger matching conditions.

rounds property 

rounds: RoundSequence

A list of participant groupings for all rounds constructed by this matcher.

__iter__ 

__iter__()

Allow for iterating over rounds in a for loop. For example:

matcher = create_matcher(groups_per_round, group_size)

for round in matcher:
    print(round)

available_sub_matchers 

available_sub_matchers() -> set[int]

Get the sizes of sub-matchers available for this matcher.

Returns:

  • set[int] –

    A set of valid groups_per_round arguments for sub_matcher().

groups_for_next_round 

groups_for_next_round() -> GroupingMatrix | None

Get the groups for the next round.

Returns:

  • GroupingMatrix | None –

    A list of participants groupings for the next round, or None if there are no more rounds possible.

groups_for_round 

groups_for_round(round_index: int) -> GroupingMatrix

Get the groups for the round with a given index.

Parameters:

  • round_index (int) –

    The index of the round to get groups for, an integer between 0 and self.max_rounds - 1.

Returns:

  • GroupingMatrix –

    A list of participants groupings for the requested round.

restart 

restart()

Reset the matcher to the first round.

shuffle_sequence 

shuffle_sequence()

Shuffle the list of rounds produced by this matcher and restart the sequence.

sub_matcher 

sub_matcher(groups_per_round: int) -> BaseMatcher | None

Get a sub-matcher with a given number of groups_per_round and the same group_size as this matcher.

Parameters:

  • groups_per_round (int) –

    The requested number of groups per round.

Returns:

  • BaseMatcher | None –

    If a sub-matcher which the requested groups_per_round exists, a matcher which gives participant groupings for this sub-matcher.

perfect_strangers.TypedMatcher

Bases: BaseMatcher

Base class for matchers which perform typed perfect stranger matching.

participant_types property 

participant_types: list[list]

A list of lists detailing which participants are of which type. The nth list contains the participants identifiers for the nth participant type.

Types

perfect_strangers.types.GroupingMatrix module-attribute 

GroupingMatrix = list[list]

perfect_strangers.types.RoundSequence module-attribute 

RoundSequence = list[GroupingMatrix]

perfect_strangers.types.GroupSpec module-attribute 

GroupSpec = Sequence[int]