►Congame
►6 Module Reference
▼6.1 Conscript Reference
6.1.1 Core
6.1.2 Page Content
6.1.3 Form0
6.1.4 Survey Tools
6.1.5 Matchmaking
6.1.6 Admin
On this page:
make-matchmaker
get-current-group
get-ready-groups
get-pending-groups
current-group-members
reset-current-group
store-my-result-in-group!
get-my-result-in-group
current-group-member-results
current-group-results-count
    contents    up   

6.1.5 Matchmaking🔗

 (require conscript/matchmaking) package: conscript

The bindings in this module are also provided by conscript/base.

These functions are used for matching participants into groups. Tehy take care of the mechanics of pausing the study until groups are full, and of sharing results between group members.

A matchmaker function is used to collect participants into groups of a given size, displaying a “Please wait” step until the group is full. A pending group is one that has one or more members but still needs more to meet its quota; a ready group has met its quota of assigned participants and is ready to proceed.

procedure

(make-matchmaker group-size [group-ok?]) → (-> (-> xexpr?) any/c)

  group-size : exact-positive-integer?
  group-ok? : (-> buid/c boolean?) = values
Returns a matchmaker function that accepts one argument (that argument being a study step function) and which adds the current participant to the current pending group (creating a new group if all other groups are full already), and then either skips to the next step in the study (if the current group now has group-size members) or loads the step page provided by the argument.

You should avoid calling make-matchmaker more than once with different values of group-size in the same study.

A group-ok? procedure can be supplied in order to give the study author a way to prevent adding the participant to certain groups. The procedure will be called with the identifier of the candidate group, which can be used as a key to the hash returned by get-pending-groups. The procedure must return #t if the participant can be added to the candidate group or #f if not. (During the body of the group-ok? procedure, the hash table returned by get-pending-groups will not yet include the current-participant-id.)

procedure

(get-current-group) → (or/c buid/c #f)

Returns the BUID of the group the current participant is assigned to, or #f if not currently assigned to any group.

If the result is not #f, it can be used as a key for the hash returned by either get-ready-groups or get-pending-groups (depending on whether the current participant is in a ready group or a pending group) to get a list of participant IDs.

procedure

(get-ready-groups) → (hash/c buid/c (listof integer?))

Returns a hash table of all currently ready groups; that is, groups which, as of the last call to a matchmaker function, have been assigned the number of participants given as group-size in the call to make-matchmaker which produced the matchmaker.

Each key in the hash table is a group ID and references a list of participant IDs assigned to that group.

procedure

(get-pending-groups) → (hash/c buid/c (listof integer?))

Returns a hash table of all currently pending groups; that is, groups which, as of the last call to a matchmaker function, have been assigned one or more participants but still fewer than the number of participants given as group-size in the call to make-matchmaker which produced the matchmaker.

Each key in the hash table is a group ID and references a list of participant IDs assigned to that group.

procedure

(current-group-members #:include-self? include-self?)

 → (listof integer?)
  include-self? : #f
If the current participant is a member of a ready group, returns a list the members in that group. If the current participant is not in a group or is in a group that is only partially full, an empty list is returned.

By default, current participant’s own ID is not included in the returned list, but if include-self? is not #f then the returned list will include all members of the group.

procedure

(reset-current-group) → void?

Removes the participant from any group to which they have been assigned (whether it was filled or not).

If, at the time the participant’s current group is reset, they were in a group that was only partially filled, then a subsequent call to a matchmaker function may add them back to the same group (causing their ID to appear more than once in that group’s member list). If they were in a filled group, the participant’s ID will remain among the list of the original group members.

procedure

(store-my-result-in-group! lookup-key val) → void?

  lookup-key : any/c
  val : any/c
Records val in a table of information within the current group so that it can be referenced with lookup-key (see other-group-member-results).

If the current participant is not a member of a group, no data will be recorded.

procedure

(get-my-result-in-group lookup-key) → any/c

  lookup-key : any/c
Retrieves the value stored under lookup-key for the current participant within their currently assigned group. If the participant is not a member of a group, or if they have not previously stored a value under lookup-key within the current group, #f is returned.

procedure

(current-group-member-results lookup-key 
  #:include-ids? ids? 
  #:include-self? include-self?) 
 → 
(or/c (listof (cons/c id/c any/c))
      (listof any/c))
  lookup-key : any/c
  ids? : #f
  include-self? : #f
Returns a list containing the result stored under lookup-key for members of the current group. For any member that has not yet stored a value under lookup-key, #f will be returned.

If the current participant is not a member of a group, an empty list is returned.

If ids? is not #f, then each element the returned list will be a pair of the form (id . result) where id is the ID of the participant that recorded the result. If ids? is #f, the returned list will simply contain all the result values.

By default, current participant’s own result is not included in the returned list, but if include-self? is not #f then the returned list will include a response recorded by the current participant under lookup-key, if one exists, or #f if it does not exist.

As an example, assume the current participant has an ID of 100 and is paired with participant 199. If the current participant has recorded a response of "no" under lookup key 'has-eaten and the other group member has not yet recorded a response under that key:

(current-group-member-results 'has-eaten) ; → ’(#f)
 
(current-group-member-results 'has-eaten #:include-ids? #t) ; → ’((199 . #f))
(current-group-member-results 'has-eaten #:include-self? #t) ; → ’("no" #f)
(current-group-member-results 'has-eaten
                              #:include-self? #t
                              #:include-ids? #t) ; → ’((100 . "no") (199 . #f))

procedure

(current-group-results-count lookup-key 
  #:include-self? include-self) 
 → exact-nonnegative-integer?
  lookup-key : any/c
  include-self : #f
Returns the count of results recorded under lookup-key for members of the current group.

If the current participant is not a member of a group, the result will be 0.

By default, current participant’s own result is not counted, but if include-self? is not #f then the count will reflect any responses recorded by the current participant under lookup-key, if any.

    contents    up