Experiment actions
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 action 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
Note
When creating a new action type:
-
Inherit from
BaseAction
-
Define a unique
view
class variable -
Initialize with required parameters
-
Override
action()
method if custom serialization is needed
Source code in experiment/actions/base_action.py
__init__(style=None)
#
Initialize the base action with optional styling.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
style |
Optional[list[str]]
|
list of class arguments to set in the frontend |
None
|
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 - ‘style’: Serialized style configuration if present |
Source code in experiment/actions/base_action.py
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”. |
'I agree'
|
deny |
Optional[str]
|
Text for the rejection button. Defaults to “Stop”. |
'Stop'
|
url |
Optional[str]
|
Template path to load consent content if no text file is provided. Supports both HTML (default) and Markdown files. |
''
|
Example
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
translated_content.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 experiment/actions/consent.py
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 experiment/actions/consent.py
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 experiment/actions/consent.py
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_label |
Optional[str]
|
Label for the button that proceeds to the next view |
"Let's go!"
|
timer |
Optional[int]
|
Timer in ms |
None
|
step_numbers |
Optional[bool]
|
Show step numbers |
False
|
Source code in experiment/actions/explainer.py
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 experiment/actions/explainer.py
action(number=None)
#
Create an explainer step, with description and optional number
experiment.actions.final#
ButtonConfiguration
#
Bases: TypedDict
Button configuration for an optional call-to-action button.
Attributes:
Name | Type | Description |
---|---|---|
text |
str
|
The text displayed on the button. |
link |
str
|
The URL or path to navigate to when the button is clicked. |
Source code in experiment/actions/final.py
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 call-to-action button configuration. For example: {“text”: “Play again”, “link”: “/{experiment_slug}”}. |
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 experiment/actions/final.py
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 |
|
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 experiment/actions/final.py
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 experiment/actions/final.py
experiment.actions.form#
AutoCompleteQuestion
#
Bases: Question
A question with an autocomplete input.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
choices |
Dict[str, str]
|
Available options |
required |
**kwargs |
Additional Question arguments |
{}
|
Example
Source code in experiment/actions/form.py
BooleanQuestion
#
Bases: Question
A yes/no question component.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
choices |
Optional[Dict[str, str]]
|
Custom yes/no labels |
None
|
**kwargs |
Additional Question arguments |
{}
|
Example
Source code in experiment/actions/form.py
ButtonArrayQuestion
#
Bases: Question
A question with a button array.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
choices |
Dict[str, str]
|
Available options |
required |
**kwargs |
Additional Question arguments |
{}
|
Example
Source code in experiment/actions/form.py
ChoiceQuestion
#
Bases: Question
A question with (multiple) choice options.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
choices |
Dict[str, str]
|
Available options |
required |
min_values |
int
|
Minimum number of selections required |
1
|
**kwargs |
Additional Question arguments |
{}
|
Example
Note
- To have multiple choices (participant can select more than one answer), set
view
to ‘CHECKBOXES’
Source code in experiment/actions/form.py
DropdownQuestion
#
Bases: Question
A question with a dropdown menu.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
choices |
Dict[str, str]
|
Available options |
required |
**kwargs |
Additional Question arguments |
{}
|
Example
Source code in experiment/actions/form.py
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_label |
str
|
Text for submit button |
gettext_lazy('Continue')
|
skip_label |
str
|
Text for skip button |
gettext_lazy('Skip')
|
is_skippable |
bool
|
Whether form can be skipped |
False
|
Example
Source code in experiment/actions/form.py
LikertQuestion
#
Bases: Question
A question with a Likert scale.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
scale_steps |
int
|
Number of scale steps (default: 7) |
7
|
explainer |
str
|
Additional instructions for the question |
gettext_lazy('How much do you agree or disagree?')
|
likert_view |
LikertView
|
Likert scale view (default: ‘TEXT_RANGE’) |
'TEXT_RANGE'
|
choices |
Dict[int, str]
|
Custom Likert scale labels |
{}
|
**kwargs |
Additional Question arguments |
{}
|
Example
Source code in experiment/actions/form.py
LikertQuestionIcon
#
Bases: Question
A question with a Likert scale using icons.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
scale_steps |
int
|
Number of scale steps (default: 7) |
7
|
likert_view |
LikertView
|
Likert scale view (default: ‘ICON_RANGE’) |
'ICON_RANGE'
|
**kwargs |
Additional Question arguments |
{}
|
Example
Source code in experiment/actions/form.py
NumberQuestion
#
Bases: Question
A question that accepts numeric input.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
input_type |
str
|
Type of number input (default: ‘number’) |
'number'
|
min_value |
int
|
Minimum allowed value |
0
|
max_value |
int
|
Maximum allowed value |
120
|
**kwargs |
Additional Question arguments |
{}
|
Source code in experiment/actions/form.py
Question
#
Bases: BaseAction
The Question action is a component that represents a single question in a form.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
key |
str
|
Unique identifier for the question in results table |
required |
result_id |
Optional[int]
|
Optional result ID for testing purposes |
None
|
view |
QuestionView
|
Widget type to use in frontend (default: ‘STRING’) |
'STRING'
|
explainer |
str
|
Additional instructions for the question |
''
|
question |
str
|
The actual question text |
''
|
is_skippable |
bool
|
Whether question can be skipped |
False
|
submits |
bool
|
Whether answering submits the form |
False
|
style |
Optional[list[str]]
|
CSS class name(s) set in the frontend for styling |
[value]
|
Example
Note
-
You can use any of the child classes to create a specific question type (e.g. TextQuestion, BooleanQuestion).
-
The
key
should be unique within the form.
Source code in experiment/actions/form.py
RadiosQuestion
#
Bases: Question
A question with radio buttons.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
choices |
Dict[str, str]
|
Available options |
required |
**kwargs |
Additional Question arguments |
{}
|
Example
Source code in experiment/actions/form.py
RangeQuestion
#
Bases: Question
A question with a range slider.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
min_value |
int
|
Minimum value |
required |
max_value |
int
|
Maximum value |
required |
**kwargs |
Additional Question arguments |
{}
|
Example
Source code in experiment/actions/form.py
TextQuestion
#
Bases: Question
A question that accepts text input.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
input_type |
str
|
Type of text input (default: ‘text’) |
'text'
|
max_length |
int
|
Maximum character length |
64
|
**kwargs |
Additional Question arguments |
{}
|
Source code in experiment/actions/form.py
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:
Source code in experiment/actions/html.py
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_label |
str
|
label of button on bottom |
None
|
button_link |
str
|
(optional) button link. If no link is set, clicking the button will redirect the participant to the next action. |
None
|
Example
Note
Relates to the Info.tsx
component in the frontend.
Source code in experiment/actions/info.py
experiment.actions.playback#
Autoplay
#
Bases: Playback
Player that starts playing automatically.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sections |
List[Section]
|
List of audio sections to play. |
required |
**kwargs |
Any
|
Additional arguments passed to |
{}
|
Note
If show_animation is True, displays a countdown and moving histogram.
Source code in experiment/actions/playback.py
ImagePlayer
#
Bases: Multiplayer
Multiplayer that shows an image next to each play button.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sections |
List[Section]
|
List of audio sections to play. |
required |
images |
List[str]
|
List of image paths/urls to display. |
required |
image_labels |
List[str]
|
Optional labels for images. Defaults to empty list. |
[]
|
**kwargs |
Any
|
Additional arguments passed to Multiplayer. |
{}
|
Example
Raises:
Type | Description |
---|---|
UserWarning
|
If number of images or labels doesn’t match sections. |
Source code in experiment/actions/playback.py
MatchingPairs
#
Bases: Multiplayer
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 |
score_feedback_display |
ScoreFeedbackDisplay
|
How to display score feedback. Defaults to “large-top” (pick from “small-bottom-right”, “large-top”, “hidden”). |
'large-top'
|
tutorial |
Optional[Dict[str, Any]]
|
Tutorial configuration dictionary. Defaults to None. |
None
|
**kwargs |
Any
|
Additional arguments passed to Multiplayer. |
{}
|
Example
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",
tutorial={
"no_match": _(
"This was not a match, so you get 0 points. Please try again to see if you can find a matching pair."
),
"lucky_match": _(
"You got a matching pair, but you didn't hear both cards before. This is considered a lucky match. You get 10 points."
),
"memory_match": _("You got a matching pair. You get 20 points."),
"misremembered": _(
"You thought you found a matching pair, but you didn't. This is considered a misremembered pair. You lose 10 points."
),
}
)
Source code in experiment/actions/playback.py
Multiplayer
#
Bases: PlayButton
Player with multiple play buttons.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sections |
List[Section]
|
List of audio sections to play. |
required |
stop_audio_after |
float
|
Seconds after which to stop audio. Defaults to 5. |
5
|
labels |
List[str]
|
Custom labels for players. Defaults to empty list. |
[]
|
style |
FrontendStyle
|
Frontend styling options. |
None
|
**kwargs |
Any
|
Additional arguments passed to PlayButton. |
{}
|
Raises:
Type | Description |
---|---|
UserWarning
|
If |
Source code in experiment/actions/playback.py
PlayButton
#
Bases: Playback
Player that shows a button to trigger playback.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sections |
List[Section]
|
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. |
{}
|
Source code in experiment/actions/playback.py
Playback
#
Bases: BaseAction
Base class for different kinds of audio players.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
sections |
List[Section]
|
List of audio sections to play. |
required |
preload_message |
str
|
Text to display during preload. Defaults to “”. |
''
|
instruction |
str
|
Text to display during presentation. Defaults to “”. |
''
|
play_from |
float
|
Start position in seconds. Defaults to 0. |
0
|
show_animation |
bool
|
Whether to show playback animation. Defaults to False. |
False
|
mute |
bool
|
Whether to mute audio. Defaults to False. |
False
|
timeout_after_playback |
Optional[float]
|
Seconds to wait after playback before proceeding. Defaults to None. |
None
|
stop_audio_after |
Optional[float]
|
Seconds after which to stop playback. Defaults to None. |
None
|
resume_play |
bool
|
Whether to resume from previous position. Defaults to False. |
False
|
style |
Optional[list[str]]
|
CSS class name(s) set in the frontend for styling |
None
|
tutorial |
Optional[Dict[str, Any]]
|
Tutorial configuration dictionary. Defaults to None. |
None
|
Source code in experiment/actions/playback.py
determine_play_method(section)
#
Determine which play method to use based on section properties.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
section |
Section
|
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 experiment/actions/playback.py
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 experiment/actions/playback.py
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 |
Source code in experiment/actions/redirect.py
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: |
None
|
icon |
Optional[str]
|
the name of a themify-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 experiment/actions/score.py
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 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 |
|
action()
#
Serialize score data
Returns:
Type | Description |
---|---|
dict
|
dictionary with the relevant data for the Score.tsx view |
Source code in experiment/actions/score.py
default_score_message(score)
#
Fallback to generate a message for the given score
Source code in experiment/actions/score.py
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 experiment/actions/score.py
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 experiment/actions/score.py
experiment.actions.styles#
ColorScheme
#
Bases: StrEnum
Enumeration of valid color schemes that can be applied to arrays of (playback) buttons
Note
Color schemes are mutually exclusive. Possible values are:
-
BOOLEAN
-
BOOLEAN_NEGATIVE_FIRST
-
NEUTRAL
-
NEUTRAL_INVERTED
Source code in experiment/actions/styles.py
FrontendStyle
#
A class to manage and apply frontend styles to different elements.
The FrontendStyle class allows setting and managing styles for various UI elements, with validation against predefined style options. To be used in conjunction with Playback and Question actions.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
styles |
list[str] |
list[str]
|
Source code in experiment/actions/styles.py
experiment.actions.trial#
Config
#
Bases: TypedDict
Configuration for the Trial action.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
- |
response_time (int
|
how long to wait until stopping the player |
required |
- |
auto_advance (bool
|
proceed automatically after stopping |
required |
- |
listen_first (bool
|
block form submission until playback ends |
required |
- |
show_continue_button (bool
|
display a ‘Continue’ button |
required |
- |
continue_label (str
|
label for the continue button |
required |
Source code in experiment/actions/trial.py
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 |
''
|
config |
Optional[Config]
|
configuration for the trial with options for response time, auto advance, listen first, show continue button, and continue label |
None
|
Example
key = 'test_trial'
section = session.playlist.get_section()
question = BooleanQuestion(
question=_(
"Do you like this song?"),
key=key,
result_id=prepare_result(key, session, section=section),
submits=True
)
form = Form([question])
playback = Autoplay([section])
view = Trial(
playback=playback,
feedback_form=form,
title=_('Test block'),
config={
'response_time': section.duration,
'listen_first': True
}
)
Note
Relates to client component: Trial.tsx
Source code in experiment/actions/trial.py
action()
#
Serialize data for a block action
Source code in experiment/actions/trial.py
experiment.actions.utils#
final_action_with_optional_button(session, final_text='', title=_('End'), button_text=_('Continue'))
#
Description: Create a final action with an optional button to proceed to the next block, if available.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
session |
Session
|
The current session. |
required |
final_text |
str
|
The text to display in the final action. |
''
|
title |
str
|
The title for the final action screen. |
gettext_lazy('End')
|
button_text |
str
|
The text displayed on the continuation button. |
gettext_lazy('Continue')
|
Returns:
Type | Description |
---|---|
Final
|
The final action with an optional button. |
Source code in experiment/actions/utils.py
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. |
Source code in experiment/actions/utils.py
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. |
Source code in experiment/actions/utils.py
get_current_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. |
Note
Returns None if there is no experiment slug.
Source code in experiment/actions/utils.py
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. |
Source code in experiment/actions/utils.py
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. |
Source code in experiment/actions/utils.py
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. |
Source code in experiment/actions/utils.py
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. |
Note: Can be used as the final_text
parameter in the Final
action or the final_action_with_optional_button
function.
Source code in experiment/actions/utils.py
experiment.actions.wrappers#
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). |
Source code in experiment/actions/wrappers.py
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 |
|
two_alternative_forced(session, section, choices, expected_response=None, style=None, comment='', scoring_rule=None, title='', config=None)
#
Description: Provide data for a two-alternative forced choice (2AFC) view, with an optional comment and scoring.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
session |
Session
|
Current user session. |
required |
section |
Section
|
Section to use in the playback or question. |
required |
choices |
dict
|
Possible choices presented to the user. |
required |
expected_response |
str
|
The expected user response. |
None
|
style |
dict
|
Additional style configurations for buttons. |
None
|
comment |
str
|
Comment or additional info about the session. |
''
|
scoring_rule |
str
|
Rule for scoring the user’s response. |
None
|
title |
str
|
Title to be displayed in the trial. |
''
|
config |
dict
|
Additional configuration parameters. |
None
|
Returns:
Type | Description |
---|---|
Trial
|
Configured trial containing a playback, a question, and a feedback form. |