Skip to content

Experiment actions

backend.experiment.actions.base_action#

BaseAction #

Bases: object

Base class for all experiment actions in the MUSCLE framework.

This class serves as the foundation for various action types that configure frontend components. All action classes (e.g., Score, Playback, Form, etc.) inherit from this base class to ensure consistent behavior and structure.

Key Features: - Provides a standardized way to serialize actiolinkn data for frontend components - Handles frontend styling configuration - Ensures each action has a unique identifier through the ID class variable - Implements a common interface for action serialization via the action() method

Example 
class CustomAction(BaseAction):
    view = "CUSTOM"

    def __init__(self, custom_data, style=None):
        super().__init__(style=style)
        self.custom_data = custom_data
Note

When creating a new action type:

  1. Inherit from BaseAction

  2. Define a unique view class variable

  3. Initialize with required parameters

  4. Override action() method if custom serialization is needed

Source code in backend/experiment/actions/base_action.py 
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
class BaseAction(object):
    """Base class for all experiment actions in the MUSCLE framework.

    This class serves as the foundation for various action types that configure
    frontend components. All action classes (e.g., Score, Playback, Form, etc.)
    inherit from this base class to ensure consistent behavior and structure.

    Key Features:
    - Provides a standardized way to serialize actiolinkn data for frontend components
    - Handles frontend styling configuration
    - Ensures each action has a unique identifier through the ID class variable
    - Implements a common interface for action serialization via the action() method

    Example:
        ```python
        class CustomAction(BaseAction):
            view = "CUSTOM"

            def __init__(self, custom_data, style=None):
                super().__init__(style=style)
                self.custom_data = custom_data
        ```

    Note:
        When creating a new action type: \n
        1. Inherit from `BaseAction` \n
        2. Define a unique `view` class variable \n
        3. Initialize with required parameters \n
        4. Override `action()` method if custom serialization is needed
    """

    view = "BASE"

    def action(self) -> dict:
        """Serialize the action configuration for frontend consumption.

        This method creates a standardized dictionary format that frontend
        components expect. All instance variables are included, and the
        action's ID is added to identify the correct frontend component.

        Returns:
            dict: A dictionary containing:
                - All instance variables from __dict__
                - 'view': The action's ID for frontend component mapping
        """
        action_dict = self.camelize(self.__dict__)
        action_dict['view'] = self.view
        return action_dict

    def camelize(self, input_dict: dict) -> dict:
        output_dict = {}
        for key in input_dict.keys():
            output_dict[camelize(key)] = input_dict[key]
        return output_dict

action() #

Serialize the action configuration for frontend consumption.

This method creates a standardized dictionary format that frontend components expect. All instance variables are included, and the action’s ID is added to identify the correct frontend component.

Returns:

Name Type Description
dict dict

A dictionary containing: - All instance variables from dict - ‘view’: The action’s ID for frontend component mapping
Source code in backend/experiment/actions/base_action.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def action(self) -> dict:
    """Serialize the action configuration for frontend consumption.

    This method creates a standardized dictionary format that frontend
    components expect. All instance variables are included, and the
    action's ID is added to identify the correct frontend component.

    Returns:
        dict: A dictionary containing:
            - All instance variables from __dict__
            - 'view': The action's ID for frontend component mapping
    """
    action_dict = self.camelize(self.__dict__)
    action_dict['view'] = self.view
    return action_dict

backend.experiment.actions.consent#

Consent #

Bases: BaseAction

Handles experiment consent form generation and rendering and provides the consent form data to the frontend.

This class manages the display and processing of informed consent forms for experiments. It can handle consent text from multiple sources (file upload, URL template, or default text) and supports both HTML and Markdown formats.

Parameters:

Name Type Description Default
text File

A Django File object containing the consent form content. If provided, this takes precedence over the URL parameter.

 required
title Optional[str]

The heading displayed above the consent form. Defaults to “Informed consent”.

 'Informed consent'
confirm Optional[str]

Text for the confirmation button. Defaults to “I agree”.

 required
deny Optional[str]

Text for the rejection button. Defaults to “Stop”.

 required
url Optional[str]

Template path to load consent content if no text file is provided. Supports both HTML (default) and Markdown files.

 ''
Example 
consent = Consent(
    text=File(open("path/to/consent.md")),
    title="Informed consent",
    confirm_button=Button("I agree", "colorPositive"),
    deny_button=Button("Stop", "colorNegative")
)
Note
  • The text file is normally uploaded via the admin interface for the experiment, so most of the time (and by default) you will use an experiment’s texts.consent file.
  • This component is used in conjunction with the frontend Consent.tsx component
  • HTML templates can use Django template language
  • Markdown files are automatically converted to HTML
  • Priority order for content: 1) uploaded file, 2) template URL, 3) default text
Source code in backend/experiment/actions/consent.py 
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
class Consent(BaseAction):  # pylint: disable=too-few-public-methods
    """Handles experiment consent form generation and rendering and provides the consent form data to the frontend.

    This class manages the display and processing of informed consent forms for experiments.
    It can handle consent text from multiple sources (file upload, URL template, or default text)
    and supports both HTML and Markdown formats.

    Args:
        text (File): A Django File object containing the consent form content. If provided,
            this takes precedence over the URL parameter.
        title (Optional[str]): The heading displayed above the consent form.
            Defaults to "Informed consent".
        confirm (Optional[str]): Text for the confirmation button. Defaults to "I agree".
        deny (Optional[str]): Text for the rejection button. Defaults to "Stop".
        url (Optional[str]): Template path to load consent content if no text file is provided.
            Supports both HTML (default) and Markdown files.

    Example:
        ```python
        consent = Consent(
            text=File(open("path/to/consent.md")),
            title="Informed consent",
            confirm_button=Button("I agree", "colorPositive"),
            deny_button=Button("Stop", "colorNegative")
        )
        ```

    Note:
        - The text file is normally uploaded via the admin interface for the experiment, so most of the time (and by default) you will use an experiment's `texts.consent` file.
        - This component is used in conjunction with the frontend Consent.tsx component
        - HTML templates can use Django template language
        - Markdown files are automatically converted to HTML
        - Priority order for content: 1) uploaded file, 2) template URL, 3) default text
    """

    # default consent text, that can be used for multiple blocks
    view = "CONSENT"

    default_text = "Lorem ipsum dolor sit amet, nec te atqui scribentur. Diam \
                molestie posidonium te sit, ea sea expetenda suscipiantur \
                contentiones, vix ex maiorum denique! Lorem ipsum dolor sit \
                amet, nec te atqui scribentur. Diam molestie posidonium te sit, \
                ea sea expetenda suscipiantur contentiones, vix ex maiorum \
                denique! Lorem ipsum dolor sit amet, nec te atqui scribentur. \
                Diam molestie posidonium te sit, ea sea expetenda suscipiantur \
                contentiones, vix ex maiorum denique! Lorem ipsum dolor sit \
                amet, nec te atqui scribentur. Diam molestie posidonium te sit, \
                ea sea expetenda suscipiantur contentiones."

    def __init__(
        self,
        text: File,
        title: str = "Informed consent",
        confirm_button: Button = Button(_("I agree"), 'colorPositive'),
        deny_button: Button = Button(_("Stop"), 'colorNegative'),
        url: str = "",
    ) -> None:
        # Determine which text to use
        if text != "":
            # Uploaded consent via file field: experiment.consent (High priority)
            with text.open("r") as f:
                dry_text = f.read()
            render_format = get_render_format(text.url)
        elif url != "":
            # Template file via url (Low priority)
            dry_text = render_to_string(url)
            render_format = get_render_format(url)
        else:
            # use default text
            dry_text = self.default_text
            render_format = "HTML"
        # render text fot the consent component
        self.text = render_html_or_markdown(dry_text, render_format)
        self.title = title
        self.confirmButton = confirm_button.action()
        self.denyButton = deny_button.action()

get_render_format(url) #

Detect markdown file based on file extension

Parameters:

Name Type Description Default
url str

Url of the consent file

 required

Returns:

Type Description
Literal['HTML', 'MARKDOWN']

File format of the consent file (HTML or MARKDOWN)
Source code in backend/experiment/actions/consent.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
def get_render_format(url: str) -> Literal["HTML", "MARKDOWN"]:
    """
    Detect markdown file based on file extension

    Args:
        url: Url of the consent file

    Returns:
        File format of the consent file (HTML or MARKDOWN)

    """
    if splitext(url)[1] == ".md":
        return "MARKDOWN"
    return "HTML"

render_html_or_markdown(dry_text, render_format) #

render html or markdown

Parameters:

Name Type Description Default
dry_text str

contents of a markdown or html file

 required
render_format Literal['HTML', 'MARKDOWN']

type of contents, either ‘HTML’ or ‘MARKDOWN’

 required

Returns:

Type Description
str

Content rendered to html.
Source code in backend/experiment/actions/consent.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
def render_html_or_markdown(dry_text: str, render_format: Literal["HTML", "MARKDOWN"]) -> str:
    """render html or markdown

    Args:
        dry_text (str): contents of a markdown or html file
        render_format (Literal["HTML", "MARKDOWN"]): type of contents, either 'HTML' or 'MARKDOWN'

    Returns:
        Content rendered to html.
    """

    if render_format == "HTML":
        template = Template(dry_text)
        context = Context()
        return template.render(context)
    if render_format == "MARKDOWN":
        return formatter(dry_text, filter_name="markdown")

    raise ValueError("Invalid render format. Must be either 'HTML' or 'MARKDOWN'.")

backend.experiment.actions.explainer#

Explainer #

Bases: BaseAction

Provide data for a explainer that explains the experiment steps

Relates to client component: Explainer.tsx

Explainer view automatically proceeds to the following view after timer (in ms) expires. If timer=None, explainer view will proceed to the next view only after a click of a button. Intro explainers should always have timer=None (i.e. interaction with a browser is required), otherwise the browser will not autoplay the first segment.

Parameters:

Name Type Description Default
instruction str

Instruction for the explainer

 required
steps List[Step]

List of steps to explain

 required
button Optional[Button]

Configure button that proceeds to the next view

 Button("Let's go!", 'colorPrimary')
timer Optional[int]

Timer in ms

 None
step_numbers Optional[bool]

Show step numbers

 False
Source code in backend/experiment/actions/explainer.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
class Explainer(BaseAction):
    """
    Provide data for a explainer that explains the experiment steps

    Relates to client component: Explainer.tsx

    Explainer view automatically proceeds to the following view after timer (in ms) expires. If timer=None, explainer view will proceed to the next view only after a click of a button. Intro explainers should always have timer=None (i.e. interaction with a browser is required), otherwise the browser will not autoplay the first segment.

    Args:
        instruction (str): Instruction for the explainer
        steps (List[Step]): List of steps to explain
        button (Optional[Button]): Configure button that proceeds to the next view
        timer (Optional[int]): Timer in ms
        step_numbers (Optional[bool]): Show step numbers
    """

    view = "EXPLAINER"

    def __init__(
        self,
        instruction: str,
        steps: List[Step],
        button: Button = Button("Let's go!", "colorPrimary"),
        timer: Optional[int] = None,
        step_numbers: Optional[bool] = False,
    ):
        self.instruction = instruction
        self.steps = steps
        self.button = button
        self.timer = timer
        self.step_numbers = step_numbers

    def action(self) -> ExplainerAction:
        if self.step_numbers:
            serialized_steps = [step.action(index + 1) for index, step in enumerate(self.steps)]
        else:
            serialized_steps = [step.action() for step in self.steps]
        return {
            "view": self.view,
            "instruction": self.instruction,
            "button": self.button.action(),
            "steps": serialized_steps,
            "timer": self.timer,
        }

Step #

Bases: object

A step in an explainer

Parameters:

Name Type Description Default
description str

Description of the step

 required
number Optional[int]

Optional number of the step

 None
Source code in backend/experiment/actions/explainer.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
class Step(object):
    """
    A step in an explainer

    Args:
        description (str): Description of the step
        number (Optional[int]): Optional number of the step
    """

    def __init__(self, description: str, number: Optional[int] = None):
        self.description = description
        self.number = number

    def action(self, number=None) -> StepAction:
        """Create an explainer step, with description and optional number"""
        return {
            "number": self.number if self.number else number,
            "description": formatter(self.description, "markdown"),
        }

action(number=None) #

Create an explainer step, with description and optional number

Source code in backend/experiment/actions/explainer.py 
35
36
37
38
39
40
def action(self, number=None) -> StepAction:
    """Create an explainer step, with description and optional number"""
    return {
        "number": self.number if self.number else number,
        "description": formatter(self.description, "markdown"),
    }

backend.experiment.actions.final#

Final #

Bases: BaseAction

Provide data for a “final” view, typically shown at the end of an experiment or session.

This view displays the participant’s final score and, optionally, their rank or performance category. It can also present navigation elements, such as a “Play again” button or links to other parts of the site. Branding elements like a logo or social sharing options can be included to enhance user engagement. A feedback section may also be provided if feedback_info is supplied.

The returned data aligns with FinalActionResponse, ensuring type consistency and making the structure clear for both developers and documentation readers. It can be consumed by a frontend component (e.g., Final.tsx) to render the final screen.

Parameters:

Name Type Description Default
session Session

The current session object associated with the participant.

 required
title str

The title displayed at the top of the final view. Defaults to a localized “Final score”.

 gettext_lazy('Final score')
final_text Optional[str]

An optional concluding message (e.g., “Thanks for participating!”).

 None
button Optional[ButtonConfiguration]

Optional button configuration. For example: {“text”: “Play again”, “link”: “/{experiment_identifier}”}. If not provided, a default button with label “Next” will be rendered, unless the experiment is not replayable. If the passed in button does not specify a link, get_experiment_url will be used to link back to the experiment, if it is replayable.

 None
points Optional[str]

The label for the score units (e.g., “points”). Defaults to a localized “points”.

 None
rank Optional[str]

The participant’s rank (e.g., “GOLD”). If not provided, no rank is displayed.

 None
show_profile_link bool

If True, display a link to the participant’s profile.

 False
show_participant_link bool

If True, display a participant-related link or information.

 False
show_participant_id_only bool

If True, only the participant ID is shown, without a link.

 False
feedback_info Optional[Dict[str, str]]

Optional dictionary containing feedback-related data. For example: {“header”: “Feedback”, “prompt”: “Tell us what you think”, “button_text”: “Submit”}.

 None
total_score Optional[float]

Explicit final score. If None, this is derived from the session.

 None
logo Optional[LogoConfiguration]

Optional logo configuration for branding. For example: {“image”: “/static/logo.png”, “link”: “https://example.com”}.

 None
Note

The action() method returns a FinalActionResponse that can be consumed by the frontend to render the final screen.

Source code in backend/experiment/actions/final.py 
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
class Final(BaseAction):  # pylint: disable=too-few-public-methods
    """
    Provide data for a "final" view, typically shown at the end of an experiment or session.

    This view displays the participant's final score and, optionally, their rank or performance category.
    It can also present navigation elements, such as a "Play again" button or links to other parts of the site.
    Branding elements like a logo or social sharing options can be included to enhance user engagement.
    A feedback section may also be provided if `feedback_info` is supplied.

    The returned data aligns with `FinalActionResponse`, ensuring type consistency and making the structure
    clear for both developers and documentation readers. It can be consumed by a frontend component
    (e.g.,
    [Final.tsx](https://amsterdam-music-lab.github.io/MUSCLE/storybook/?path=/story/final--default)) to render the final screen.

    Args:
        session (Session): The current session object associated with the participant.
        title (str): The title displayed at the top of the final view. Defaults to a localized "Final score".
        final_text (Optional[str]): An optional concluding message (e.g., "Thanks for participating!").
        button (Optional[ButtonConfiguration]): Optional button configuration. For example:
                                            {"text": "Play again", "link": "/{experiment_identifier}"}. If not provided, a default button with label "Next" will be rendered, unless the experiment is not replayable.
                                            If the passed in button does not specify a link, `get_experiment_url` will be used to link back to the experiment, if it is replayable.
        points (Optional[str]): The label for the score units (e.g., "points"). Defaults to a localized "points".
        rank (Optional[str]): The participant's rank (e.g., "GOLD"). If not provided, no rank is displayed.
        show_profile_link (bool): If True, display a link to the participant's profile.
        show_participant_link (bool): If True, display a participant-related link or information.
        show_participant_id_only (bool): If True, only the participant ID is shown, without a link.
        feedback_info (Optional[Dict[str, str]]): Optional dictionary containing feedback-related data. For example:
                                                  {"header": "Feedback", "prompt": "Tell us what you think", "button_text": "Submit"}.
        total_score (Optional[float]): Explicit final score. If None, this is derived from the session.
        logo (Optional[LogoConfiguration]): Optional logo configuration for branding. For example:
                                        {"image": "/static/logo.png", "link": "https://example.com"}.

    Note:
        The `action()` method returns a `FinalActionResponse` that can be consumed by the frontend
        to render the final screen.
    """

    view = "FINAL"

    RANKS = {
        "PLASTIC": {"text": _("plastic"), "class": "plastic"},
        "BRONZE": {"text": _("bronze"), "class": "bronze"},
        "SILVER": {"text": _("silver"), "class": "silver"},
        "GOLD": {"text": _("gold"), "class": "gold"},
        "PLATINUM": {"text": _("platinum"), "class": "platinum"},
        "DIAMOND": {"text": _("diamond"), "class": "diamond"},
    }

    def __init__(
        self,
        session: Session,
        title: str = _("Final score"),
        final_text: Optional[str] = None,
        button: Optional[Button] = None,
        points: Optional[str] = None,
        rank: Optional[str] = None,
        show_profile_link: bool = False,
        show_participant_link: bool = False,
        show_participant_id_only: bool = False,
        feedback_info: FeedbackInfo | None = None,
        total_score: Optional[float] = None,
        logo: Optional[LogoConfiguration] = None,
        percentile: Optional[float] = None,
        accumulative_percentile: Optional[float] = None,
    ):
        self.session = session
        self.title = title
        self.final_text = final_text
        self.button = self.get_button(button, session)
        self.rank = rank
        self.show_profile_link = show_profile_link
        self.show_participant_link = show_participant_link
        self.show_participant_id_only = show_participant_id_only
        self.feedback_info = feedback_info
        self.logo = logo
        self.percentile = percentile
        self.accumulative_percentile = accumulative_percentile

        if total_score is None:
            self.total_score = self.session.total_score()
        else:
            self.total_score = total_score

        if points is None:
            self.points = _("points")
        else:
            self.points = points

    def action(self) -> FinalActionResponse:
        response: FinalActionResponse = {
            "view": self.view,
            "score": self.total_score,
            "percentile": self.percentile,
            "accumulativePercentile": self.accumulative_percentile,
            "rank": self.rank,
            "finalText": self.wrap_plain_final_text(),
            "button": self.button.action() if self.button else None,
            "points": self.points,
            "actionTexts": {
                "playAgain": _("Play again"),
                "profile": _("My profile"),
                "allExperiments": _("All experiments"),
            },
            "title": self.title,
            "social": self.get_social_media_config(self.session),
            "showProfileLink": self.show_profile_link,
            "showParticipantLink": self.show_participant_link,
            "feedbackInfo": self.feedback_info,
            "participantIDOnly": self.show_participant_id_only,
            "logo": self.logo,
        }

        return response

    def get_button(self, button: Button, session: Session) -> Optional[Button]:
        """
        Render a button in the Final action if the link back to the experiment page is valid
        """
        if button and button.link is not None:
            return button
        button_link = get_experiment_url(session)
        if button_link:
            if button:
                button.link = button_link
                return button
            return Button(label=_("Next"), link=button_link)

    def get_social_media_config(self, session: Session) -> Optional[SocialMediaConfigConfiguration]:
        experiment = session.block.phase.experiment
        if hasattr(experiment, "social_media_config") and experiment.social_media_config:
            return serialize_social_media_config(experiment.social_media_config, session.total_score())
        return None

    def wrap_plain_final_text(self):
        """check if `final_text` starts with a html tag
        If not, wrap it in a `<center>` element for better alignment
        """
        tag_pattern = re.compile("<[a-z]*>")
        if self.final_text and not re.match(tag_pattern, str(self.final_text)):
            return f"<center>{self.final_text}</center>"
        return self.final_text

get_button(button, session) #

Render a button in the Final action if the link back to the experiment page is valid

Source code in backend/experiment/actions/final.py 
160
161
162
163
164
165
166
167
168
169
170
171
def get_button(self, button: Button, session: Session) -> Optional[Button]:
    """
    Render a button in the Final action if the link back to the experiment page is valid
    """
    if button and button.link is not None:
        return button
    button_link = get_experiment_url(session)
    if button_link:
        if button:
            button.link = button_link
            return button
        return Button(label=_("Next"), link=button_link)

wrap_plain_final_text() #

check if final_text starts with a html tag If not, wrap it in a <center> element for better alignment

Source code in backend/experiment/actions/final.py 
179
180
181
182
183
184
185
186
def wrap_plain_final_text(self):
    """check if `final_text` starts with a html tag
    If not, wrap it in a `<center>` element for better alignment
    """
    tag_pattern = re.compile("<[a-z]*>")
    if self.final_text and not re.match(tag_pattern, str(self.final_text)):
        return f"<center>{self.final_text}</center>"
    return self.final_text

LogoConfiguration #

Bases: TypedDict

Logo configuration for branding or visual identification on the final screen.

Attributes:

Name Type Description
image str

The URL of the logo image to display.
link str

The URL to navigate to when the logo is clicked.
Source code in backend/experiment/actions/final.py 
14
15
16
17
18
19
20
21
22
23
24
class LogoConfiguration(TypedDict):
    """
    Logo configuration for branding or visual identification on the final screen.

    Attributes:
        image (str): The URL of the logo image to display.
        link (str): The URL to navigate to when the logo is clicked.
    """

    image: str
    link: str

backend.experiment.actions.form#

Form #

Bases: BaseAction

The Form action is a view which brings together an array of questions with a submit and an optional skip button.

Parameters:

Name Type Description Default
form List[Question]

List of question components

 required
submit_button Button

Button object specifying label and color of submit button

 Button(gettext_lazy('Submit'), 'colorPrimary')
skip_button Button

Button object specifying label and color of skip button

 Button(gettext_lazy('Skip'), 'colorGrey')
Example 
form = Form([
    TextQuestion(
        identifier="name",
        text="What's your name?",
        explainer="Please enter your full name.",
    ),
    ButtonArrayQuestion(
        identifier="is_student",
        text="Are you a student?",
        choices=[{'value': 'YES', 'text': _('YES'), {'value': 'NO', 'label': _('NO')}],
    ),
])
Source code in backend/experiment/actions/form.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
class Form(BaseAction):
    """The Form action is a view which brings together an array of questions with a submit and an optional skip button.

    Args:
        form (List[Question]): List of question components
        submit_button (Button): Button object specifying label and color of submit button
        skip_button (Button): Button object specifying label and color of skip button

    Example:
        ```python
        form = Form([
            TextQuestion(
                identifier="name",
                text="What's your name?",
                explainer="Please enter your full name.",
            ),
            ButtonArrayQuestion(
                identifier="is_student",
                text="Are you a student?",
                choices=[{'value': 'YES', 'text': _('YES'), {'value': 'NO', 'label': _('NO')}],
            ),
        ])
        ```
    """

    def __init__(
        self,
        form: List[Any],
        submit_button: Optional[Button] = Button(_("Submit"), 'colorPrimary'),
        skip_button: Optional[Button] = Button(_("Skip"), 'colorGrey'),
    ) -> None:
        self.form = form
        self.submit_button = submit_button
        self.skip_button = skip_button

    def action(self) -> Dict[str, Any]:
        serialized_form = [question.action() for question in self.form]
        if not all([question.get('isSkippable') for question in serialized_form]):
            self.skip_button = None
        return {
            "form": serialized_form,
            "submitButton": self.submit_button.action() if self.submit_button else None,
            "skipButton": self.skip_button.action() if self.skip_button else None,
        }

backend.experiment.actions.html#

HTML #

Bases: BaseAction

An action that renders HTML content. See also the HTML.tsx component in the frontend project.

Parameters:

Name Type Description Default
body str

The HTML body content

 required

Examples:

To render a simple HTML snippet with a title and a paragraph:

>>> html_action = HTML('<h1>Hello, world!</h1><p>This is a simple HTML snippet.</p>')
Source code in backend/experiment/actions/html.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
class HTML(BaseAction):
    """An action that renders HTML content. See also the `HTML.tsx` component in the frontend project.

    Args:
        body (str): The HTML body content

    Examples:
        To render a simple HTML snippet with a title and a paragraph:

        >>> html_action = HTML('<h1>Hello, world!</h1><p>This is a simple HTML snippet.</p>')
    """

    view = "HTML"

    def __init__(self, body: str):
        self.body = body

backend.experiment.actions.info#

Info #

Bases: BaseAction

Provide data for a view that presents information using HTML to the participant, along with a customizable (link) button.

Parameters:

Name Type Description Default
body str

HTML body

 required
heading str

title/heading on top

 ''
button Button

properties of the button shown under the body

 None
Example 
Info(
    body="<p>Here is some information</p>",
    heading="This is the heading",
    button=Button("Next", "colorPrimary", "https://example.com"),
)
Note

Relates to the Info.tsx component in the frontend.

Source code in backend/experiment/actions/info.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
class Info(BaseAction):
    """
    Provide data for a view that presents information using HTML to the participant, along with a customizable (link) button.

    Args:
        body (str): HTML body
        heading (str): title/heading on top
        button (Button): properties of the button shown under the body

    Example:
        ```python
        Info(
            body="<p>Here is some information</p>",
            heading="This is the heading",
            button=Button("Next", "colorPrimary", "https://example.com"),
        )
        ```

    Note:
        Relates to the `Info.tsx` component in the frontend.
    """

    view = "INFO"

    def __init__(self, body, heading="", button: Optional[Button] = None):
        self.body = body
        self.heading = heading
        self.button = button

    def action(self):
        return {
            "view": self.view,
            "body": self.body,
            "heading": self.heading,
            "button": self.button.action(),
        }

backend.experiment.actions.playback#

Autoplay #

Bases: Playback

Player that starts playing automatically.

Parameters:

Name Type Description Default
sections List[AudioSection]

List of audio sections to play. Currently does not support more than one section.

 required
**kwargs

Additional arguments passed to Playback.

 {}
Example 
Autoplay(
    sections=[PlaybackSection(section1)],
    show_animation=True,
)
Note

If show_animation is True, displays a countdown and moving histogram.

Source code in backend/experiment/actions/playback.py 
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
class Autoplay(Playback):
    """Player that starts playing automatically.

    Args:
        sections List[AudioSection]: List of audio sections to play. Currently does not support more than one section.
        **kwargs: Additional arguments passed to `Playback`.

    Example:
        ```python
        Autoplay(
            sections=[PlaybackSection(section1)],
            show_animation=True,
        )
        ```

    Note:
        If show_animation is True, displays a countdown and moving histogram.
    """

    def __init__(self, **kwargs) -> None:
        super().__init__(**kwargs)
        self.view = TYPE_AUTOPLAY

ImagePlaybackSection #

Bases: PlaybackSection

A special type of PlaybackSection that shows an image along a play button

Source code in backend/experiment/actions/playback.py 
61
62
63
64
65
66
class ImagePlaybackSection(PlaybackSection):
    """A special type of PlaybackSection that shows an image along a play button"""

    def __init__(self, image: SectionImage, **kwargs):
        super().__init__(**kwargs)
        self.image = image

MatchingPairs #

Bases: Playback

Multiplayer where buttons are represented as cards and where the cards need to be matched based on audio.

Parameters:

Name Type Description Default
sections List[Section]

List of audio sections to play.

 required
show_animation bool

Whether to show an animated histogram during playback of a card.

 required
score_feedback_display ScoreFeedbackDisplay

How to display score feedback. Defaults to “large-top” (pick from “small-bottom-right”, “large-top”, “hidden”).

 'large-top'
**kwargs Any

Additional arguments passed to Multiplayer.

 {}
Example

python MatchingPairs( # You will need an even number of sections (ex. 16) [section1, section2, section3, section4, section5, section6, section7, section8, section9, section10, section11, section12, section13, section14, section15, section16], score_feedback_display="large-top",

Source code in backend/experiment/actions/playback.py 
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
class MatchingPairs(Playback):
    """Multiplayer where buttons are represented as cards and where the cards need to be matched based on audio.

    Args:
        sections (List[Section]): List of audio sections to play.
        show_animation (bool): Whether to show an animated histogram during playback of a card.
        score_feedback_display (ScoreFeedbackDisplay): How to display score feedback. Defaults to "large-top" (pick from "small-bottom-right", "large-top", "hidden").
        **kwargs: Additional arguments passed to Multiplayer.

    Example:
        ```python
        MatchingPairs(
            # You will need an even number of sections (ex. 16)
            [section1, section2, section3, section4, section5, section6, section7, section8, section9, section10, section11, section12, section13, section14, section15, section16],
            score_feedback_display="large-top",
         ```
    """

    def __init__(
        self,
        sections: List[PlaybackSection],
        score_feedback_display: ScoreFeedbackDisplay = "large-top",
        **kwargs: Any,
    ) -> None:
        super().__init__(sections, **kwargs)
        self.view = TYPE_MATCHINGPAIRS
        self.score_feedback_display = score_feedback_display

PlayButtons #

Bases: Playback

Player that shows buttons for each to trigger playback.

Parameters:

Name Type Description Default
sections

List of audio sections to play.

 required
play_once bool

Whether button should be disabled after one play. Defaults to False.

 False
**kwargs Any

Additional arguments passed to Playback.

 {}
Example 
PlayButtons(
    sections=[PlaybackSection(section1), PlaybackSection(section2)],
    play_once=False,
)
Source code in backend/experiment/actions/playback.py 
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
class PlayButtons(Playback):
    """Player that shows buttons for each to trigger playback.

    Args:
        sections: List of audio sections to play.
        play_once: Whether button should be disabled after one play. Defaults to False.
        **kwargs: Additional arguments passed to Playback.

    Example:
        ```python
        PlayButtons(
            sections=[PlaybackSection(section1), PlaybackSection(section2)],
            play_once=False,
        )
        ```
    """

    def __init__(self, play_once: bool = False, **kwargs: Any) -> None:
        super().__init__(**kwargs)
        self.view = TYPE_BUTTON
        self.play_once = play_once

Playback #

Bases: BaseAction

Base class for different kinds of audio players.

Parameters:

Name Type Description Default
sections List[PlaybackSection]

List of audio sections to play.

 required
preload_message str

Text to display during preload.

 ''
instruction str

Text to display during presentation.

 ''
show_animation bool

Whether to show playback animation.

 True
mute bool

Whether to mute audio.

 False
resume_play bool

Whether to resume from previous position.

 False
show_animation bool

Whether to show an animated histogram during playback (applies for AutoPlay & MatchingPairs)

 True
style Optional[list[str]]

CSS class name(s) set in the frontend for styling

 None
Source code in backend/experiment/actions/playback.py 
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
class Playback(BaseAction):
    """Base class for different kinds of audio players.

    Args:
        sections: List of audio sections to play.
        preload_message: Text to display during preload.
        instruction: Text to display during presentation.
        show_animation: Whether to show playback animation.
        mute: Whether to mute audio.
        resume_play: Whether to resume from previous position.
        show_animation: Whether to show an animated histogram during playback (applies for AutoPlay & MatchingPairs)
        style: CSS class name(s) set in the frontend for styling
    """

    def __init__(
        self,
        sections: List[PlaybackSection],
        preload_message: str = "",
        instruction: str = "",
        mute: bool = False,
        resume_play: bool = False,
        show_animation: bool = True,
        style: Optional[list[str]] = None,
    ) -> None:
        self.sections = sections
        self.preload_message = preload_message
        self.instruction = instruction
        self.mute = mute
        self.resume_play = resume_play
        self.show_animation = show_animation

    def action(self):
        serialized = super().action()
        serialized['sections'] = [section.action() for section in self.sections]
        return serialized

PlaybackSection #

Bases: Button

An object to represent a section to be played Args: link (str): Link to audio file label (Optional[str]): Label of play button (not shown in autoplay mode) color (Optional[str]): Color of play button (not shown in autoplay mode) play_from (float): Start position of the audio file in seconds

Infers a playback method for this section, i.e., whether the frontend will use webAudio and whether it will buffer. Currently there is no support for mixed playback methods.

Source code in backend/experiment/actions/playback.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
class PlaybackSection(Button):
    '''An object to represent a section to be played
    Args:
        link (str): Link to audio file
        label (Optional[str]): Label of play button (not shown in autoplay mode)
        color (Optional[str]): Color of play button (not shown in autoplay mode)
        play_from (float): Start position of the audio file in seconds

    Infers a playback method for this section, i.e., whether the frontend will use webAudio and whether it will buffer.
    Currently there is no support for mixed playback methods.
    '''

    def __init__(self, section: Section, label="", play_from=0, **kwargs):
        super().__init__(label, **kwargs)
        self.play_from = play_from
        self.link = section.absolute_url()
        self.play_method = get_play_method(section)

PlaybackSectionAction #

Bases: TypedDict

This type is similar to the ButtonAction type, but here link is the only required argument.

Source code in backend/experiment/actions/playback.py 
23
24
25
26
27
28
29
30
class PlaybackSectionAction(TypedDict):
    """This type is similar to the ButtonAction type, but here link is the only required argument."""

    link: str
    label: Optional[str]
    color: Optional[str]
    play_from: float
    play_method: PlayMethods

get_play_method(section) #

Determine which play method to use based on section properties.

Parameters:

Name Type Description Default
section PlaybackSection

Audio section object.

 required

Returns:

Name Type Description
str PlayMethods

Play method constant (PLAY_NOAUDIO, PLAY_EXTERNAL, PLAY_HTML, or PLAY_BUFFER).
Source code in backend/experiment/actions/playback.py 
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
def get_play_method(section: PlaybackSection) -> PlayMethods:
    """Determine which play method to use based on section properties.

    Args:
        section: Audio section object.

    Returns:
        str: Play method constant (PLAY_NOAUDIO, PLAY_EXTERNAL, PLAY_HTML, or PLAY_BUFFER).
    """
    filename = str(section.filename)
    if not is_audio_file(filename):
        return PLAY_NOAUDIO
    elif filename.startswith("http"):
        return PLAY_EXTERNAL
    elif section.duration > 45:
        return PLAY_HTML
    else:
        return PLAY_BUFFER

is_audio_file(filename) #

Check if filename has an audio extension.

Parameters:

Name Type Description Default
filename str

Name of the file to check.

 required

Returns:

Name Type Description
bool bool

True if file has an audio extension.
Source code in backend/experiment/actions/playback.py 
205
206
207
208
209
210
211
212
213
214
def is_audio_file(filename: str) -> bool:
    """Check if filename has an audio extension.

    Args:
        filename (str): Name of the file to check.

    Returns:
        bool: True if file has an audio extension.
    """
    return any(filename.lower().endswith(ext) for ext in audio_extensions)

backend.experiment.actions.question#

Types of questions to be presented to participants

AutoCompleteQuestion #

Bases: ChoiceQuestionAction

A question with an autocomplete input.

Parameters:

Name Type Description Default
choices dict

dictionary of answer options

 required
**kwargs Any

additional Question arguments

 {}
Example 
question = AutoCompleteQuestion(
    identifier="color",
    text="What's your favorite color?",
    choices=[
        {"value": "red", "label": "Red"},
        {"value": "green", "label": "Green"},
        {"value": "blue", "label": "Blue"},
    ],
)
Source code in backend/experiment/actions/question.py 
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
class AutoCompleteQuestion(ChoiceQuestionAction):
    """A question with an autocomplete input.

    Args:
        choices (dict): dictionary of answer options
        **kwargs: additional Question arguments

    Example:
        ```python
        question = AutoCompleteQuestion(
            identifier="color",
            text="What's your favorite color?",
            choices=[
                {"value": "red", "label": "Red"},
                {"value": "green", "label": "Green"},
                {"value": "blue", "label": "Blue"},
            ],
        )
        ```
    """

    def __init__(self, **kwargs: Any) -> None:
        super().__init__(view='AUTOCOMPLETE', **kwargs)

ButtonArrayQuestion #

Bases: ChoiceQuestionAction

A question showing buttons for each choice. If choices specify color values from the theme, buttons will be colored. Not practical to use for more than 5 choices.

Parameters:

Name Type Description Default
choices List[Choice]

list of dictionaries with value, label and optional color for choice

 required
**kwargs Any

Additional Question arguments

 {}
Example 
question = ButtonArrayQuestion(
    identifier="is_student",
    text="Are you a student?",
    choices=[
        {"value": "no", "label": _("Nope"), "color": "colorNegative"},
        {"value": "yes", "label": _("Yep"), "color": "colorPositive"}
    ],
)
Source code in backend/experiment/actions/question.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
class ButtonArrayQuestion(ChoiceQuestionAction):
    """A question showing buttons for each choice.
    If choices specify color values from the theme, buttons will be colored.
    Not practical to use for more than 5 choices.

    Args:
        choices (List[Choice]): list of dictionaries with value, label and optional color for choice
        **kwargs: Additional Question arguments

    Example:
        ```python
        question = ButtonArrayQuestion(
            identifier="is_student",
            text="Are you a student?",
            choices=[
                {"value": "no", "label": _("Nope"), "color": "colorNegative"},
                {"value": "yes", "label": _("Yep"), "color": "colorPositive"}
            ],
        )
        ```
    """

    def __init__(self, **kwargs: Any) -> None:
        super().__init__(view="BUTTON_ARRAY", **kwargs)

CheckBoxQuestion #

Bases: ChoiceQuestionAction

A question with (multiple) choice options represented as check boxes

Parameters:

Name Type Description Default
choices List[Choice]

Available options

 required
min_values int

Minimum number of selections required

 1
**kwargs Any

Additional Question arguments

 {}
Example 
question = MultipleChoiceQuestion(
    identifier="color",
    text="What's your favorite color?",
    choices=[
        {"value": "red", "label": "Red"},
        {"value": "green", "label": "Green"},
        {"value": "blue": "label": "Blue"}
    ],
    min_values=1,
)
Source code in backend/experiment/actions/question.py 
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
class CheckBoxQuestion(ChoiceQuestionAction):
    """A question with (multiple) choice options represented as check boxes

    Args:
        choices (List[Choice]): Available options
        min_values (int): Minimum number of selections required
        **kwargs: Additional Question arguments

    Example:
        ```python
        question = MultipleChoiceQuestion(
            identifier="color",
            text="What's your favorite color?",
            choices=[
                {"value": "red", "label": "Red"},
                {"value": "green", "label": "Green"},
                {"value": "blue": "label": "Blue"}
            ],
            min_values=1,
        )
        ```
    """

    def __init__(self, min_values: int = 1, **kwargs: Any) -> None:
        if min_values < 1:
            raise ValueError("min_values should be at least 1")
        super().__init__(view="CHECKBOXES", min_values=min_values, **kwargs)

    def action(self):
        return {**super().action(), 'min_values': self.min_values}

Choice #

Bases: TypedDict

The structure of the dictionary for a question choice Note that color (optional) is only shown in ButtonArrayQuestion and TextRangeQuestion

Source code in backend/experiment/actions/question.py 
33
34
35
36
37
38
39
40
class Choice(TypedDict):
    """The structure of the dictionary for a question choice
    Note that color (optional) is only shown in ButtonArrayQuestion and TextRangeQuestion
    """

    value: str
    label: str
    color: Optional[str]

ChoiceQuestionAction #

Bases: QuestionAction

An action class with choices

Parameters:

Name Type Description Default
choices dict

a dictionary of answer options

 required
min_values Optional[int]

the minimal number of options to be selected by user

 None
Source code in backend/experiment/actions/question.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
class ChoiceQuestionAction(QuestionAction):
    """An action class with choices

    Args:
        choices (dict): a dictionary of answer options
        min_values: the minimal number of options to be selected by user
    """

    def __init__(
        self,
        choices: List[Choice],
        min_values: Optional[int] = None,
        **kwargs: Any,
    ):
        super().__init__(**kwargs)
        self.choices = choices
        self.min_values = min_values

DropdownQuestion #

Bases: ChoiceQuestionAction

A question with a dropdown menu.

Parameters:

Name Type Description Default
choices List[Choice]

Available options

 required
**kwargs Any

Additional Question arguments

 {}
Example 
question = DropdownQuestion(
    identifier="color",
    text="What's your favorite color?",
    choices=[
        {"value": "red", "label": "Red"},
        {"value": "green", "label": "Green"},
        {"value": "blue", "label": "Blue"},
    ],
)
Source code in backend/experiment/actions/question.py 
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
class DropdownQuestion(ChoiceQuestionAction):
    """A question with a dropdown menu.

    Args:
        choices (List[Choice]): Available options
        **kwargs: Additional Question arguments

    Example:
        ```python
        question = DropdownQuestion(
            identifier="color",
            text="What's your favorite color?",
            choices=[
                {"value": "red", "label": "Red"},
                {"value": "green", "label": "Green"},
                {"value": "blue", "label": "Blue"},
            ],
        )
        ```
    """

    def __init__(self, **kwargs: Any) -> None:
        super().__init__(view="DROPDOWN", **kwargs)

NumberQuestion #

Bases: OpenQuestionAction

A question showing numeric input. NOTE: cannot set min value to avoid input rejecting keyboard input

Parameters:

Name Type Description Default
max_value int

Maximum allowed value

 120
**kwargs Any

Additional Question arguments

 {}
Source code in backend/experiment/actions/question.py 
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
class NumberQuestion(OpenQuestionAction):
    """A question showing numeric input.
    NOTE: cannot set min value to avoid input rejecting keyboard input

    Args:
        max_value: Maximum allowed value
        **kwargs: Additional Question arguments
    """

    def __init__(
        self,
        max_value: int = 120,
        **kwargs: Any,
    ) -> None:
        super().__init__(min_value=0, max_value=max_value, view="NUMBER", **kwargs)

OpenQuestionAction #

Bases: QuestionAction

A question class showing a text / number or range field

Parameters:

Name Type Description Default
min_value Optional[int]

minimum value (for number / range questions)

 None
max_value Optional[int]

maximum value (for number / range questions)

 None
max_length Optional[int]

maximum number of characters (for text questions)

 None
Source code in backend/experiment/actions/question.py 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
class OpenQuestionAction(QuestionAction):
    """A question class showing a text / number or range field

    Args:
        min_value: minimum value (for number / range questions)
        max_value: maximum value (for number / range questions)
        max_length: maximum number of characters (for text questions)
    """

    def __init__(
        self,
        min_value: Optional[int] = None,
        max_value: Optional[int] = None,
        max_length: Optional[int] = None,
        **kwargs: Any,
    ):
        super().__init__(**kwargs)
        self.min_value = min_value
        self.max_value = max_value
        self.max_length = max_length

QuestionAction #

Bases: BaseAction

A base object for question actions. Do not use direcly, use subtypes instead.

Parameters:

Name Type Description Default
identifier str

a unique identifier with which the question is logged to the database

 required
result_id int

the identifier of the Result object associated with this question

 None
text str

the text shown to the user

 ''
explainer str

optionally, an instruction for the user of how to use the shown widget

 ''
view str

the view (widget) shown to the user, set in the subclasses

 ''
Source code in backend/experiment/actions/question.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
class QuestionAction(BaseAction):
    """
    A base object for question actions. Do not use direcly, use subtypes instead.

    Args:
        identifier: a unique identifier with which the question is logged to the database
        result_id: the identifier of the `Result` object associated with this question
        text: the text shown to the user
        explainer: optionally, an instruction for the user of how to use the shown widget
        view: the view (widget) shown to the user, set in the subclasses
    """

    def __init__(
        self,
        identifier: str,
        result_id: int = None,
        text: str = '',
        explainer: str = '',
        view: str = '',
    ):
        self.identifier = identifier
        self.text = text
        self.result_id = result_id
        self.explainer = explainer
        self.view = view

RadiosQuestion #

Bases: ChoiceQuestionAction

A question with radio buttons.

Parameters:

Name Type Description Default
choices List[Choice]

Available options

 required
**kwargs Any

Additional Question arguments

 {}
Example 
question = RadiosQuestion(
    identifier="color",
    text="What's your favorite color?",
    choices=[
        {"value": "red", "label": "Red"},
        {"value": "green", "label": "Green"},
        {"value": "blue", "label": "Blue"},
    ],
)
Source code in backend/experiment/actions/question.py 
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
class RadiosQuestion(ChoiceQuestionAction):
    """A question with radio buttons.

    Args:
        choices (List[Choice]): Available options
        **kwargs: Additional Question arguments

    Example:
        ```python
        question = RadiosQuestion(
            identifier="color",
            text="What's your favorite color?",
            choices=[
                {"value": "red", "label": "Red"},
                {"value": "green", "label": "Green"},
                {"value": "blue", "label": "Blue"},
            ],
        )
        ```
    """

    def __init__(self, **kwargs: Any) -> None:
        super().__init__(view = "RADIOS", **kwargs)

RangeQuestion #

Bases: OpenQuestionAction

A question with a range slider.

Parameters:

Name Type Description Default
min_value int

Minimum value

 0
max_value int

Maximum value

 0
**kwargs Any

Additional Question arguments

 {}
Example 
question = RangeQuestion(
    identifier="age",
    text="How old are you?",
    min_value=18,
    max_value=120,
)
Source code in backend/experiment/actions/question.py 
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
class RangeQuestion(OpenQuestionAction):
    """A question with a range slider.

    Args:
        min_value: Minimum value
        max_value: Maximum value
        **kwargs: Additional Question arguments

    Example:
        ```python
        question = RangeQuestion(
            identifier="age",
            text="How old are you?",
            min_value=18,
            max_value=120,
        )
        ```
    """

    def __init__(self, min_value: int = 0, max_value: int = 0, **kwargs: Any) -> None:
        super().__init__(
            min_value=min_value, max_value=max_value, view='RANGE', **kwargs
        )

TextQuestion #

Bases: OpenQuestionAction

A question that accepts text input.

Parameters:

Name Type Description Default
max_length int

Maximum character length

 64
**kwargs Any

Additional Question arguments

 {}
Source code in backend/experiment/actions/question.py 
287
288
289
290
291
292
293
294
295
296
class TextQuestion(OpenQuestionAction):
    """A question that accepts text input.

    Args:
        max_length: Maximum character length
        **kwargs: Additional Question arguments
    """

    def __init__(self, max_length: int = 64, **kwargs: Any) -> None:
        super().__init__(max_length=max_length, view="STRING", **kwargs)

TextRangeQuestion #

Bases: ChoiceQuestionAction

A question with a slider, usually used for a Likert scale.

Parameters:

Name Type Description Default
choices List[Choice]

list of answer options

 required
**kwargs Any

Additional Question arguments

 {}
Example 
question = TextRangeQuestion(
    identifier="satisfaction",
    text="How satisfied are you with MUSCLE?",
    explainer="Please rate your satisfaction.",
    choices=[
        {"value": 1, "label": _("Very satisfied")},
        {"value": 2, "label": _("Satisfied")},
        {"value": 3, "label": _("Neutral")},
        {"value": 4, "label": _("Disappointed")},
        {"value": 5, "label": _("Very disappointed)}
    ]
)
Source code in backend/experiment/actions/question.py 
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
class TextRangeQuestion(ChoiceQuestionAction):
    """A question with a slider, usually used for a Likert scale.

    Args:
        choices (List[Choice]): list of answer options
        **kwargs: Additional Question arguments

    Example:
        ```python
        question = TextRangeQuestion(
            identifier="satisfaction",
            text="How satisfied are you with MUSCLE?",
            explainer="Please rate your satisfaction.",
            choices=[
                {"value": 1, "label": _("Very satisfied")},
                {"value": 2, "label": _("Satisfied")},
                {"value": 3, "label": _("Neutral")},
                {"value": 4, "label": _("Disappointed")},
                {"value": 5, "label": _("Very disappointed)}
            ]
        )
        ```
    """

    def __init__(self, **kwargs: Any):
        super().__init__(view='TEXT_RANGE', **kwargs)

backend.experiment.actions.redirect#

Redirect #

Bases: BaseAction

Redirect Action

This action is used to redirect the user to a specified URL.

Parameters:

Name Type Description Default
url str

The URL to redirect to.

 required
Example 
redirect_action = Redirect('https://example.com')
Source code in backend/experiment/actions/redirect.py 
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
class Redirect(BaseAction):
    """
    Redirect Action

    This action is used to redirect the user to a specified URL.

    Args:
        url (str): The URL to redirect to.

    Example:
        ```python
        redirect_action = Redirect('https://example.com')
        ```
    """

    view = "REDIRECT"

    def __init__(self, url):
        self.url = url

backend.experiment.actions.score#

Score #

Bases: BaseAction

Provide data for a score view, presenting feedback to a participant after a Trial.

Parameters:

Name Type Description Default
session Session

a Session object

 required
title str

the title of the score page

 ''
result Optional[Result]

the result for which section and/or score should be reported

 None
score Optional[float]

the score to report, will override result.score

 None
score_message str

a function which constructs feedback text based on the score

 ''
config Optional[ScoreConfig]

a dict with the following settings: - show_section (bool): whether to show the previous section - show_total_score (bool): whether to show the total score

 None
button Button

a button to continue to the next view

 Button(gettext('Next'), 'colorPrimary')
icon Optional[str]

the name of a fontawesome icon shown with the view or None

 None
timer Optional[int]

int or None. If int, wait for as many seconds until showing the next view

 None
feedback Optional[str]

An additional feedback text

 None
Note

Relates to the Score.tsx component in the frontend

Source code in backend/experiment/actions/score.py 
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
class Score(BaseAction):
    """
    Provide data for a score view, presenting feedback to a participant after a Trial.

    Args:
        session (Session): a Session object
        title (str): the title of the score page
        result (Optional[Result]): the result for which section and/or score should be reported
        score (Optional[float]): the score to report, will override result.score
        score_message: a function which constructs feedback text based on the score
        config (Optional[ScoreConfig]): a dict with the following settings:
            - show_section (bool): whether to show the previous section
            - show_total_score (bool): whether to show the total score
        button (Button): a button to continue to the next view
        icon (Optional[str]): the name of a fontawesome icon shown with the view or None
        timer (Optional[int]): int or None. If int, wait for as many seconds until showing the next view
        feedback (Optional[str]): An additional feedback text

    Note:
        Relates to the Score.tsx component in the frontend
    """

    view = "SCORE"

    def __init__(
        self,
        session: Session,
        title: str = "",
        button: Optional[Button] = Button(_("Next"), 'colorPrimary'),
        result: Optional[Result] = None,
        score: Optional[float] = None,
        score_message: str = "",
        config: Optional[ScoreConfig] = None,
        icon: Optional[str] = None,
        timer: Optional[int] = None,
        feedback: Optional[str] = None,
    ):
        self.title = title or _("Round {get_rounds_passed} / {total_rounds}").format(
            get_rounds_passed=session.get_rounds_passed(),
            total_rounds=session.block.rounds,
        )
        self.session = session
        self.score = self.get_score(score, result)
        self.score_message = score_message or self.default_score_message(self.score)
        self.feedback = feedback
        self.config = {"show_section": False, "show_total_score": False}
        if config:
            self.config.update(config)
        self.icon = icon
        self.button = button
        self.texts = {
            "score": _("Total Score"),
            "listen_explainer": _("You listened to:"),
        }
        self.last_song = result.section.song_label() if result else session.last_song()
        self.timer = timer

    def action(self) -> dict:
        """Serialize score data

        Returns:
            dictionary with the relevant data for the Score.tsx view
        """
        # Create action
        action = {
            "view": self.view,
            "title": self.title,
            "score": self.score,
            "score_message": self.score_message,
            "texts": self.texts,
            "button": self.button.action(),
            "feedback": self.feedback,
            "icon": self.icon,
            "timer": self.timer,
        }
        if self.config["show_section"]:
            action["last_song"] = self.last_song
        if self.config["show_total_score"]:
            action["total_score"] = self.session.total_score()
        return action

    def get_score(self, score: Optional[float] = None, result: Optional[Result] = None) -> float:
        """Retrieve the last relevant score, fall back to session.last_score() if neither score nor result are defined

        Args:
            score: the score passed from the rules file (optional)
            result: a Result object passed from the rules file (opional)
        """
        if score:
            return score
        elif result:
            return result.score
        else:
            return self.session.last_score()

    def default_score_message(self, score):
        """Fallback to generate a message for the given score"""
        # None
        if score is None:
            score = 0

        # Zero
        if score == 0:
            # "Too bad!", "Come on!", "Try another!", "Try again!"
            return random.choice([_("No points")])

        # Negative
        if score < 0:
            return random.choice([_("Incorrect")])  # "Too bad!", "Fail!", "Nooo!"

        # Positive
        # "Well done!", "Nice job!", "Great one!", "Score!", "You're good!", "Awesome!", "Nice one!"
        return random.choice([_("Correct")])

action() #

Serialize score data

Returns:

Type Description
dict

dictionary with the relevant data for the Score.tsx view
Source code in backend/experiment/actions/score.py 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
def action(self) -> dict:
    """Serialize score data

    Returns:
        dictionary with the relevant data for the Score.tsx view
    """
    # Create action
    action = {
        "view": self.view,
        "title": self.title,
        "score": self.score,
        "score_message": self.score_message,
        "texts": self.texts,
        "button": self.button.action(),
        "feedback": self.feedback,
        "icon": self.icon,
        "timer": self.timer,
    }
    if self.config["show_section"]:
        action["last_song"] = self.last_song
    if self.config["show_total_score"]:
        action["total_score"] = self.session.total_score()
    return action

default_score_message(score) #

Fallback to generate a message for the given score

Source code in backend/experiment/actions/score.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
def default_score_message(self, score):
    """Fallback to generate a message for the given score"""
    # None
    if score is None:
        score = 0

    # Zero
    if score == 0:
        # "Too bad!", "Come on!", "Try another!", "Try again!"
        return random.choice([_("No points")])

    # Negative
    if score < 0:
        return random.choice([_("Incorrect")])  # "Too bad!", "Fail!", "Nooo!"

    # Positive
    # "Well done!", "Nice job!", "Great one!", "Score!", "You're good!", "Awesome!", "Nice one!"
    return random.choice([_("Correct")])

get_score(score=None, result=None) #

Retrieve the last relevant score, fall back to session.last_score() if neither score nor result are defined

Parameters:

Name Type Description Default
score Optional[float]

the score passed from the rules file (optional)

 None
result Optional[Result]

a Result object passed from the rules file (opional)

 None
Source code in backend/experiment/actions/score.py 
106
107
108
109
110
111
112
113
114
115
116
117
118
def get_score(self, score: Optional[float] = None, result: Optional[Result] = None) -> float:
    """Retrieve the last relevant score, fall back to session.last_score() if neither score nor result are defined

    Args:
        score: the score passed from the rules file (optional)
        result: a Result object passed from the rules file (opional)
    """
    if score:
        return score
    elif result:
        return result.score
    else:
        return self.session.last_score()

ScoreConfig #

Bases: TypedDict

Configuration for the Score action

Parameters:

Name Type Description Default
show_section

whether metadata of the previous section should be shown, often the title of the last played song

 required
show_total_score

whether the total score should be shown in the view

 required
Source code in backend/experiment/actions/score.py 
12
13
14
15
16
17
18
19
20
21
22
class ScoreConfig(TypedDict):
    """
    Configuration for the Score action

    Args:
        show_section: whether metadata of the previous section should be shown, often the title of the last played song
        show_total_score: whether the total score should be shown in the view
    """

    show_section: bool
    show_total_score: bool

backend.experiment.actions.trial#

Trial #

Bases: BaseAction

A view that may include Playback and/or a Form to be displayed to the participant.

Parameters:

Name Type Description Default
playback Optional[Playback]

Player(s) to be displayed in this view (e.g. audio, video, image)

 None
html Optional[str]

HTML to be displayed in this view

 None
feedback_form Optional[Form]

array of form elements

 None
title Optional(str)

page title - defaults to empty

 ''
response_time int

time in seconds for the participant to react

 5.0
auto_advance bool

whether the view automatically forwards to the next after response_time

 False
listen_first bool

whether the controls are blocked while audio is playing

 False
continue_button Button

optionally configure label and color of button below the Trial. Not shown if form with submit_button is passed. Set to None to suppress such a button.

 Button(gettext_lazy('Continue'), 'colorPrimary')
break_round_on dict

conditions under which the current round should be abandoned, to query session/next_round for new actions

 None
Example 
identifier = 'test_trial'
section = session.playlist.get_section()
question = BooleanQuestion(
    text=_(
        "Do you like this song?"),
    identifier=identifier,
    result_id=prepare_result(identifier, session, section=section),
)
form = Form([question])
playback = Autoplay(sections=[PlaybackSection(section)])
view = Trial(
    playback=playback,
    feedback_form=form,
    title=_('Test block'),
)
Note

Relates to client component: Trial.tsx

Source code in backend/experiment/actions/trial.py 
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
class Trial(BaseAction):  # pylint: disable=too-few-public-methods
    """
    A view that may include Playback and/or a Form to be displayed to the participant.

    Args:
        playback (Optional[Playback]): Player(s) to be displayed in this view (e.g. audio, video, image)
        html (Optional[str]): HTML to be displayed in this view
        feedback_form (Optional[Form]): array of form elements
        title (Optional(str)): page title - defaults to empty
        response_time (int): time in seconds for the participant to react
        auto_advance (bool): whether the view automatically forwards to the next after response_time
        listen_first (bool): whether the controls are blocked while audio is playing
        continue_button (Button): optionally configure label and color of button below the Trial. Not shown if form with submit_button is passed. Set to `None` to suppress such a button.
        break_round_on (dict): conditions under which the current round should be abandoned, to query `session/next_round` for new actions


    Example:
        ```python
        identifier = 'test_trial'
        section = session.playlist.get_section()
        question = BooleanQuestion(
            text=_(
                "Do you like this song?"),
            identifier=identifier,
            result_id=prepare_result(identifier, session, section=section),
        )
        form = Form([question])
        playback = Autoplay(sections=[PlaybackSection(section)])
        view = Trial(
            playback=playback,
            feedback_form=form,
            title=_('Test block'),
        )
        ```

    Note:
        Relates to client component: Trial.tsx
    """

    view = "TRIAL_VIEW"

    def __init__(
        self,
        playback: Optional[Playback] = None,
        html: Optional[HTML] = None,
        feedback_form: Optional[Form] = None,
        title: str = "",
        response_time: float = 5.0,
        auto_advance: bool = False,
        listen_first: bool = False,
        continue_button: Optional[Button] = Button(_("Continue"), "colorPrimary"),
        break_round_on: Optional[BreakRoundOn] = None,
    ):
        self.playback = playback
        self.html = html
        self.feedback_form = feedback_form
        self.title = title
        self.response_time = response_time
        self.auto_advance = auto_advance
        self.listen_first = listen_first
        self.continue_button = continue_button
        self.break_round_on = break_round_on

    def action(self):
        """
        Serialize data for a block action

        """
        # Create action
        action = {
            "view": self.view,
            "title": self.title,
            "responseTime": self.response_time,
            "autoAdvance": self.auto_advance,
            "listenFirst": self.listen_first,
            "breakRoundOn": self.break_round_on,
        }
        if self.continue_button:
            action["continueButton"] = self.continue_button.action()
        if self.playback:
            action["playback"] = self.playback.action()
        if self.html:
            action["html"] = self.html.action()
        if self.feedback_form:
            action["feedbackForm"] = self.feedback_form.action()

        return action

action() #

Serialize data for a block action

Source code in backend/experiment/actions/trial.py 
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def action(self):
    """
    Serialize data for a block action

    """
    # Create action
    action = {
        "view": self.view,
        "title": self.title,
        "responseTime": self.response_time,
        "autoAdvance": self.auto_advance,
        "listenFirst": self.listen_first,
        "breakRoundOn": self.break_round_on,
    }
    if self.continue_button:
        action["continueButton"] = self.continue_button.action()
    if self.playback:
        action["playback"] = self.playback.action()
    if self.html:
        action["html"] = self.html.action()
    if self.feedback_form:
        action["feedbackForm"] = self.feedback_form.action()

    return action

backend.experiment.actions.utils#

camelize(input_str) #

convert a snake_case to camelCase string

Source code in backend/experiment/actions/utils.py 
12
13
14
15
def camelize(input_str: str) -> str:
    """convert a snake_case to camelCase string"""
    snake_case_pattern = compile(r'_([a-z])')
    return sub(snake_case_pattern, lambda match: match.group(1).upper(), input_str)

get_average_difference(session, num_turnpoints, initial_value) #

Description: Calculate and return the average difference in milliseconds participants could hear (from the last num_turnpoints records).

Parameters:

Name Type Description Default
session Session

The current session.

 required
num_turnpoints int

The number of last turnpoints to consider.

 required
initial_value float

A fallback initial value.

 required

Returns:

Type Description
float

The average difference in milliseconds.
Example 
avg_diff = get_average_difference(my_session, 3, 20.0)
Source code in backend/experiment/actions/utils.py 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def get_average_difference(session, num_turnpoints, initial_value) -> float:
    """
    Description: Calculate and return the average difference in milliseconds participants could hear (from the last `num_turnpoints` records).

    Args:
        session (Session): The current session.
        num_turnpoints (int): The number of last turnpoints to consider.
        initial_value (float): A fallback initial value.

    Returns:
        (float): The average difference in milliseconds.

    Example:
        ```python
        avg_diff = get_average_difference(my_session, 3, 20.0)
        ```
    """
    last_turnpoints = get_last_n_turnpoints(session, num_turnpoints)
    if last_turnpoints.count() == 0:
        last_result = get_fallback_result(session)
        if last_result:
            return float(last_result.section.song.name)
        else:
            # this cannot happen in DurationDiscrimination style blocks
            # for future compatibility, still catch the condition that there may be no results
            return initial_value
    return sum([int(result.section.song.name) for result in last_turnpoints]) / last_turnpoints.count()

get_average_difference_level_based(session, num_turnpoints, initial_value) #

Description: Calculate the difference level based on exponential decay.

Parameters:

Name Type Description Default
session Session

The current session.

 required
num_turnpoints int

The number of last turnpoints to consider.

 required
initial_value float

The starting reference value.

 required

Returns:

Type Description
float

The average difference in milliseconds.
Example 
level_diff = get_average_difference_level_based(my_session, 5, 20.0)
Source code in backend/experiment/actions/utils.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def get_average_difference_level_based(session, num_turnpoints, initial_value) -> float:
    """
    Description: Calculate the difference level based on exponential decay.

    Args:
        session (Session): The current session.
        num_turnpoints (int): The number of last turnpoints to consider.
        initial_value (float): The starting reference value.

    Returns:
        (float): The average difference in milliseconds.

    Example:
        ```python
        level_diff = get_average_difference_level_based(my_session, 5, 20.0)
        ```
    """
    last_turnpoints = get_last_n_turnpoints(session, num_turnpoints)
    if last_turnpoints.count() == 0:
        # outliers
        last_result = get_fallback_result(session)
        if last_result:
            return initial_value / (2 ** (int(last_result.section.song.name.split("_")[-1]) - 1))
        else:
            # participant didn't pay attention,
            # no results right after the practice rounds
            return initial_value
    # Difference by level starts at initial value (which is level 1, so 20/(2^0)) and then halves for every next level
    return (
        sum([initial_value / (2 ** (int(result.section.song.name.split("_")[-1]) - 1)) for result in last_turnpoints])
        / last_turnpoints.count()
    )

get_experiment_url(session) #

Description: Retrieve the URL for the current experiment.

Parameters:

Name Type Description Default
session Session

The current user experiment session.

 required

Returns:

Type Description
str | None

The URL for the current experiment.
Example 
url = get_experiment_url(session)
Note

Returns None if there is no experiment identifier.

Source code in backend/experiment/actions/utils.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
def get_experiment_url(session: Session) -> str | None:
    """
    Description: Retrieve the URL for the current experiment.

    Args:
        session (Session): The current user experiment session.

    Returns:
        (str | None): The URL for the current experiment.

    Example:
        ```python
        url = get_experiment_url(session)
        ```

    Note:
        Returns None if there is no experiment identifier.
    """
    experiment = session.block.phase.experiment

    if not experiment.replayable:
        blocks = experiment.associated_blocks()
        played_sessions = (
            Session.objects.filter(
                block__in=blocks,
                finished_at__isnull=False,
                participant=session.participant,
            )
            .values_list("block")
            .distinct()
            .count()
        )
        if played_sessions == blocks.count():
            return None

    if session.participant.participant_id_url:
        participant_id_url = session.participant.participant_id_url
        return f"/{experiment.identifier}?participant_id={participant_id_url}"
    else:
        return f"/{experiment.identifier}"

get_fallback_result(session) #

Description: Retrieve a fallback result if no turnpoints are found.

Parameters:

Name Type Description Default
session Session

The current session.

 required

Returns:

Type Description
Result | None

The fallback result.
Example 
fallback = get_fallback_result(my_session)
Source code in backend/experiment/actions/utils.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
def get_fallback_result(session) -> Result | None:
    """
    Description: Retrieve a fallback result if no turnpoints are found.

    Args:
        session (Session): The current session.

    Returns:
        (Result | None): The fallback result.

    Example:
        ```python
        fallback = get_fallback_result(my_session)
        ```
    """
    if session.result_set.count() == 0:
        # stopping right after practice rounds
        return None

    # TODO: Check if this is the correct way to get the last result as Python says .order_by returns a "Unknown" type
    result = session.result_set.order_by("-created_at")[0]
    return result

get_last_n_turnpoints(session, num_turnpoints) #

Description: Return the specified number of most recent turnpoint results from the session.

Parameters:

Name Type Description Default
session Session

The current session.

 required
num_turnpoints int

How many latest turnpoint results to retrieve.

 required

Returns:

Type Description
QuerySet[Result]

The latest turnpoint results.
Example 
turnpoints = get_last_n_turnpoints(my_session, 3)
Source code in backend/experiment/actions/utils.py 
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
def get_last_n_turnpoints(session, num_turnpoints) -> QuerySet[Result]:
    """
    Description: Return the specified number of most recent turnpoint results from the session.

    Args:
        session (Session): The current session.
        num_turnpoints (int): How many latest turnpoint results to retrieve.

    Returns:
        (QuerySet[Result]): The latest turnpoint results.

    Example:
        ```python
        turnpoints = get_last_n_turnpoints(my_session, 3)
        ```
    """
    all_results = session.result_set.filter(comment__iendswith="turnpoint").order_by("-created_at").all()
    cutoff = min(all_results.count(), num_turnpoints)
    return all_results[:cutoff]

randomize_playhead(min_jitter, max_jitter, continuation_correctness) #

Description: Randomly add to the playhead offset. If continuation_correctness=True, this function returns 0, and has no effect on the playhead.

Parameters:

Name Type Description Default
min_jitter float

Minimum offset.

 required
max_jitter float

Maximum offset.

 required
continuation_correctness bool

whether to add a random increment to the continued audio

 required

Returns:

Type Description
float

The random offset.
Example 
offset = randomize_playhead(0.5, 1.5, False)
Source code in backend/experiment/actions/utils.py 
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
def randomize_playhead(min_jitter, max_jitter, continuation_correctness) -> float:
    """
    Description: Randomly add to the playhead offset. If `continuation_correctness=True`, this function returns 0, and has no effect on the playhead.

    Args:
        min_jitter (float): Minimum offset.
        max_jitter (float): Maximum offset.
        continuation_correctness (bool): whether to add a random increment to the continued audio

    Returns:
        (float): The random offset.

    Example:
        ```python
        offset = randomize_playhead(0.5, 1.5, False)
        ```
    """
    return random.uniform(min_jitter, max_jitter) if not continuation_correctness else 0

render_feedback_trivia(feedback, trivia) #

Description: Render feedback and trivia into the final template.

Parameters:

Name Type Description Default
feedback str

The feedback text.

 required
trivia str

The trivia text.

 required

Returns:

Type Description
str

The rendered HTML.
Example 
rendered = render_feedback_trivia("Good job!", "Did you know ...?")

Note: Can be used as the final_text parameter in the Final action

Source code in backend/experiment/actions/utils.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
def render_feedback_trivia(feedback, trivia) -> str:
    """
    Description: Render feedback and trivia into the final template.

    Args:
        feedback (str): The feedback text.
        trivia (str): The trivia text.

    Returns:
        (str): The rendered HTML.

    Example:
        ```python
        rendered = render_feedback_trivia("Good job!", "Did you know ...?")
        ```

    Note: Can be used as the `final_text` parameter in the `Final` action
    """
    context = {"feedback": feedback, "trivia": trivia}
    return render_to_string(join("final", "feedback_trivia.html"), context)

backend.experiment.actions.wrappers#

TwoAlternativeForced #

Bases: Trial

Parameters:

Name Type Description Default
session Session

Session for which to generate TwoAlternativeForced Trial

 required
section Section

Section to be played in TwoAlternativeForced Trial

 required
choices dict

choices to be presented to participant

 required
expected_response str

expected response, if applicable

 None
comment str

comment to be logged with the result

 ''
scoring_rule Optional[str]

scoring rule to score the participant’s response

 None
**kwargs

additional arguments to initialize the Trial object (e.g., title or response_time)

 {}

Returns:

Type Description
Trial

Configured trial containing a playback, a question, and a feedback form.
Example 
trial = two_alternative_forced(session, section, {"yes": "Yes", "no": "No"}, expected_response="yes", title=_("Two Alternative Forced Choice"))
Source code in backend/experiment/actions/wrappers.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
class TwoAlternativeForced(Trial):
    """
    Args:
        session (Session): Session for which to generate TwoAlternativeForced Trial
        section (Section): Section to be played in TwoAlternativeForced Trial
        choices (dict): choices to be presented to participant
        expected_response (str): expected response, if applicable
        comment (str): comment to be logged with the result
        scoring_rule: scoring rule to score the participant's response
        **kwargs: additional arguments to initialize the Trial object (e.g., title or response_time)

    Returns:
        (Trial): Configured trial containing a playback, a question, and a feedback form.

    Example:
        ```python
        trial = two_alternative_forced(session, section, {"yes": "Yes", "no": "No"}, expected_response="yes", title=_("Two Alternative Forced Choice"))
        ```
    """

    def __init__(
        self,
        session: Session,
        section: Section,
        choices: list[Choice],
        expected_response: Optional[str] = None,
        comment: str = "",
        scoring_rule: Optional[str] = None,
        **kwargs
    ):
        playback = PlayButtons(
            sections=[PlaybackSection(section, color='colorNeutral2')], play_once=True
        )
        identifier = "choice"
        question = ButtonArrayQuestion(
            identifier=identifier,
            result_id=prepare_result(
                identifier,
                session=session,
                section=section,
                expected_response=expected_response,
                scoring_rule=scoring_rule,
                comment=comment,
            ),
            choices=choices,
        )
        feedback_form = Form([question], submit_button=None)
        super().__init__(playback=playback, feedback_form=feedback_form, **kwargs)

song_sync(session, section, title, recognition_time=15, sync_time=15, min_jitter=10, max_jitter=15) #

Description: Provide a series of Trials for song recognition and sync, including optional jitter.

Parameters:

Name Type Description Default
session Session

Current user session.

 required
section Section

Section to use for playback and silence intervals.

 required
title str

Title to be displayed for the trials.

 required
recognition_time int

Response time for recognition.

 15
sync_time int

Response time for syncing continuation.

 15
min_jitter int

Minimum playback offset for continuation correctness trial.

 10
max_jitter int

Maximum playback offset for continuity trial.

 15

Returns:

Type Description
list

A list of Trials (recognize, silence, correct_place).
Example 
trials = song_sync(session, section, _("Song Sync"), recognition_time=10)
Source code in backend/experiment/actions/wrappers.py 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
def song_sync(
    session: Session, section: Section, title: str, recognition_time=15, sync_time=15, min_jitter=10, max_jitter=15
):
    """
    Description: Provide a series of Trials for song recognition and sync, including optional jitter.

    Args:
        session (Session): Current user session.
        section (Section): Section to use for playback and silence intervals.
        title (str): Title to be displayed for the trials.
        recognition_time (int, optional): Response time for recognition.
        sync_time (int, optional): Response time for syncing continuation.
        min_jitter (int, optional): Minimum playback offset for continuation correctness trial.
        max_jitter (int, optional): Maximum playback offset for continuity trial.

    Returns:
        (list): A list of Trials (recognize, silence, correct_place).

    Example:
        ```python
        trials = song_sync(session, section, _("Song Sync"), recognition_time=10)
        ```
    """
    recognize = Trial(
        feedback_form=Form(
            [
                boolean_question(
                    identifier='recognize',
                    text='',
                    result_id=prepare_result(
                        "recognize",
                        session,
                        section=section,
                        json_data={'response_time': recognition_time},
                        scoring_rule="SONG_SYNC_RECOGNITION",
                    ),
                )
            ],
            submit_button=Button(""),
        ),
        playback=Autoplay(
            sections=[PlaybackSection(section)],
            show_animation=True,
            preload_message=_("Get ready!"),
            instruction=_("Do you recognize the song?"),
        ),
        response_time=recognition_time,
        auto_advance=True,
        break_round_on={"EQUALS": ["TIMEOUT", "no"]},
        title=title,
    )
    silence_time = 4
    silence = Trial(
        playback=Autoplay(
            sections=[PlaybackSection(section)],
            show_animation=True,
            instruction=_("Keep imagining the music"),
            mute=True,
        ),
        response_time=silence_time,
        auto_advance=True,
        continue_button=None,
        title=title,
    )
    continuation_correctness = random.choice([True, False])
    jitter = randomize_playhead(min_jitter, max_jitter, continuation_correctness)
    correct_place = Trial(
        feedback_form=Form(
            [
                boolean_question(
                    identifier="correct_place",
                    text="",
                    result_id=prepare_result(
                        "correct_place",
                        session,
                        section=section,
                        scoring_rule="SONG_SYNC_VERIFICATION",
                        json_data={"continuation_offset": jitter},
                        expected_response="yes" if continuation_correctness else "no",
                    ),
                )
            ]
        ),
        playback=Autoplay(
            sections=[PlaybackSection(section, play_from=silence_time + jitter)],
            instruction=_("Did the track come back in the right place?"),
            show_animation=True,
            resume_play=True,
        ),
        response_time=sync_time,
        title=title,
    )
    return [recognize, silence, correct_place]