Modular Pages

Modular pages are the recommended way to implement custom pages in PsyNet. They work by splitting page design into two main components: the Prompts, constituting the information or stimulus that is presented to the listener, and the Controls, constituting the participant’s way of responding to the information or stimulus.

Prompts

The following subclasses of Prompt exist:

• AudioPrompt

• ImagePrompt

• ColorPrompt

• VideoPrompt

• GraphicPrompt

Controls

A wide range of controls all of which inherit from Control are available:

Audio/Video controls

• AudioMeterControl

• AudioRecordControl

• TappingAudioMeterControl

• AudioSliderControl

• VideoRecordControl

• VideoSliderControl

• GraphicControl

Option controls

These classes inherit from OptionControl.

• CheckboxControl

• DropdownControl

• PushButtonControl

• TimedPushButtonControl

• RadioButtonControl

Other controls

• NullControl

• NumberControl

• SliderControl

• TextControl

• SurveyJSControl

API

class psynet.modular_page.AudioMeterControl(calibrate=False, show_next_button=True, min_time=0.0, bot_response=<class 'psynet.utils.NoArgumentProvided'>, **kwargs)

Bases: Control

get_bot_response(experiment, bot, page, prompt)

This function is used when a bot simulates a participant responding to a given page. In the simplest form, the function just returns the value of the answer that the bot returns. For more sophisticated treatment, the function can return a BotResponse object which contains other parameters such as blobs and metadata.

class psynet.modular_page.AudioPrompt(audio, text, loop=False, text_align='left', play_window=None, controls=False, fade_in=0.0, fade_out=0.0, **kwargs)

Bases: Prompt

Plays an audio file to the participant.

Parameters:

• audio – Audio file to play. Can be an Asset object, or alternatively a URL written as a string.

• text (Union[str, Markup, dom_tag]) – Text to display to the participant. This can either be a string for plain text, or an HTML specification from markupsafe.Markup.

• loop (bool) – Whether the audio should loop back to the beginning after finishing.

• text_align – CSS alignment of the text.

• play_window (Optional[List]) – An optional two-element list identifying the time window in the audio file that should be played. If the first element is None, then the audio file is played from the beginning; otherwise, the audio file starts playback from this timepoint (in seconds) (note that negative numbers will not be accepted here). If the second element is None, then the audio file is played until the end; otherwise, the audio file finishes playback at this timepoint (in seconds). The behaviour is undefined when the time window extends past the end of the audio file.

• controls (bool) – Whether to give the user playback controls (default = False).

• fade_in (float) – Fade-in duration for the audio (defaults to 0.0).

• fade_out (float) – Fade-out duration for the audio (defaults to 0.0).

• kwargs – Passed to Prompt.

class psynet.modular_page.AudioRecordControl(*, controls=False, loop_playback=False, num_channels=1, personal=True, bot_response_media=None, **kwargs)

Bases: RecordControl

Records audio from a participant.

Parameters:

• controls (bool) – Whether to give the user controls for the recorder (default = False).

• loop_playback (bool) – Whether in-browser playback of the recording should have looping enabled by default (default = False). Ignored if controls is False.

• num_channels (int) – The number of channels used to record the audio. Default is mono (num_channels=1).

• personal – Whether the recording should be marked as ‘personal’ and hence excluded from ‘scrubbed’ data exports. Default: True.

• **kwargs – Further arguments passed to RecordControl

format_answer(raw_answer, **kwargs)

Formats the raw answer object returned from the participant’s browser.

Parameters:

• raw_answer – The raw answer object returned from the participant’s browser.

• **kwargs –

  Keyword arguments, including:

  1. blobs: A dictionary of any blobs that were returned from the participant’s browser.

  2. metadata: The metadata returned from the participant’s browser.

  3. experiment: An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.

  4. participant: An instantiation of psynet.participant.Participant, corresponding to the current participant.

  5. trial: An instantiation of psynet.trial.main.Trial, corresponding to the participant’s current trial, or None if the participant is not currently taking a trial.

Returns:

• Object – The formatted answer, suitable for serialisation to JSON and storage in the database.

get_bot_response(experiment, bot, page, prompt)

This function is used when a bot simulates a participant responding to a given page. In the simplest form, the function just returns the value of the answer that the bot returns. For more sophisticated treatment, the function can return a BotResponse object which contains other parameters such as blobs and metadata.

class psynet.modular_page.AudioSliderControl(start_value, min_value, max_value, audio, sound_locations, autoplay=False, disable_while_playing=False, disable_slider_on_change='', n_steps=10000, slider_id='sliderpage_slider', input_type='HTML5_range_slider', random_wrap=False, reverse_scale=False, directional=True, snap_values='sound_locations', minimal_interactions=0, minimal_time=0)

Bases: MediaSliderControl

Audio slider control for backwards compatibility with AudioSliderControl.

class psynet.modular_page.Blob(file)

Bases: object

Imitates the blob objects which are returned from the Flask front-end; used for testing.

class psynet.modular_page.Button(id_, text, style='', is_response_button=False, start_disabled=False, disable_on_click=False)

Bases: BaseButton

Buttons can be included into modular pages via the page’s buttons argument. These buttons can be used to trigger custom events.

Parameters:

• id – The button’s ID. This must be written in camelCase. When the button is pressed, an event is triggered with this exact ID.

• text (Union[str, dom_tag]) – Text to display on the button.

• style (str) – Optional CSS styling for the button.

• is_response_button – If set to True, then the button is treated as a ‘response’ button and is only enabled once the PsyNet responseEnable event is triggered.

• start_disabled – If set to True, then the button starts disabled.

• disable_on_click – If set to True, then the button is disabled when it is clicked, typically to avoid redundant clicks.

class psynet.modular_page.CheckboxControl(choices, labels=None, style='', name='checkboxes', arrange_vertically=True, force_selection=False, show_reset_button='never', locale='en')

Bases: OptionControl

This control interface solicits a multiple-choice response from the participant using checkboxes.

Parameters:

• name (str) – Name of the checkbox group.

• choices (List[str]) – The different options the participant has to choose from.

• labels (Optional[List[str]]) – An optional list of textual labels to apply to the checkboxes, which the participant will see instead of choices. Default: None.

• arrange_vertically (bool) – Whether to arrange the checkboxes vertically. Default: True.

• style (str) – CSS style attributes to apply to the checkboxes. Default: "".

• force_selection (bool) – Determines if at least checkbox has to be ticked. Default: False.

• show_reset_button (str) – Whether to display a ‘Reset’ button to allow for unsetting ticked checkboxes. Possible values are: never, always, and on_selection, the latter meaning that the button is displayed only when at least one checkbox is ticked. Default: never.

validate(response, **kwargs)

Takes the psynet.timeline.Response object created by the page and runs a validation check to determine whether the participant may continue to the next page.

Parameters:

• response – An instance of psynet.timeline.Response. Typically the answer attribute of this object is most useful for validation.

• **kwargs –

  Keyword arguments, including:

  1. experiment: An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.

  2. participant: An instantiation of psynet.participant.Participant, corresponding to the current participant.

  3. answer: The formatted answer returned by the participant.

  4. raw_answer: The unformatted answer returned by the participant.

  5. page: The page to which the participant is responding.

Returns:

• None or an object of class psynet.timeline.FailedValidation – On the case of failed validation, an instantiation of psynet.timeline.FailedValidation containing a message to pass to the participant.

class psynet.modular_page.ColorPrompt(color, text, width='200px', height='200px', text_align='left')

Bases: Prompt

Displays a color to the participant.

Parameters:

• color (List[float]) – Color to show, specified as a list of HSL values.

• text (Union[str, Markup]) – Text to display to the participant. This can either be a string for plain text, or an HTML specification from markupsafe.Markup.

• width (str) – CSS width specification for the color box (default '200px').

• height (str) – CSS height specification for the color box (default '200px').

• text_align (str) – CSS alignment of the text.

class psynet.modular_page.ColorSliderControl(start_value, min_value, max_value, slider_id='sliderpage_slider', hidden_inputs={})

Bases: SliderControl

class psynet.modular_page.Control(bot_response=<class 'psynet.utils.NoArgumentProvided'>, locale='en', buttons=None, show_next_button=True)

Bases: object

The Control class provides some kind of controls for the participant, with which they will provide their response.

Parameters:

• bot_response –

  Defines how bots respond to this page. Can be a single value, in which case this is interpreted as the participant’s (formatted) answer. Alternatively, it can be an instance of class BotResponse, which can accept more detailed information, for example:

  raw_answer :

  The raw_answer returned from the page.

  answer :

  The (formatted) answer, as would ordinarily be computed by format_answer.

  metadata :

  A dictionary of metadata.

  blobs :

  A dictionary of blobs returned from the front-end.

  client_ip_address :

  The client’s IP address.

• buttons (Optional[List]) – An optional list of additional buttons to include on the page. Normally these will be created by calls to psynet.modular_page.Button.

show_next_button :

Determines whether a ‘next’ button is shown on the page. This button is used to submit the response to the present page. If this is not set to True, then the response must be submitted another way, for example by triggering the event manualSubmit.

macro

The name of the Jinja2 macro as defined within the respective template file.

Type:

str

metadata

Metadata to save about the prompt; can take arbitrary form, but must be serialisable to JSON.

Type:

Object

media

Optional object of class MediaSpec that provisions media resources for the controls.

Type:

MediaSpec

external_template

Optionally specifies a custom Jinja2 template from which the control macro should be sourced. If not provided, the control macro will be assumed to be located in PsyNet’s built-in control.html file.

Type:

Optional[str]

format_answer(raw_answer, **kwargs)

Formats the raw answer object returned from the participant’s browser.

Parameters:

• raw_answer – The raw answer object returned from the participant’s browser.

• **kwargs –

  Keyword arguments, including:

  1. blobs: A dictionary of any blobs that were returned from the participant’s browser.

  2. metadata: The metadata returned from the participant’s browser.

  3. experiment: An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.

  4. participant: An instantiation of psynet.participant.Participant, corresponding to the current participant.

  5. trial: An instantiation of psynet.trial.main.Trial, corresponding to the participant’s current trial, or None if the participant is not currently taking a trial.

Returns:

• Object – The formatted answer, suitable for serialisation to JSON and storage in the database.

get_bot_response(experiment, bot, page, prompt)

This function is used when a bot simulates a participant responding to a given page. In the simplest form, the function just returns the value of the answer that the bot returns. For more sophisticated treatment, the function can return a BotResponse object which contains other parameters such as blobs and metadata.

validate(response, **kwargs)

Takes the psynet.timeline.Response object created by the page and runs a validation check to determine whether the participant may continue to the next page.

Parameters:

• response – An instance of psynet.timeline.Response. Typically the answer attribute of this object is most useful for validation.

• **kwargs –

  Keyword arguments, including:

  1. experiment: An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.

  2. participant: An instantiation of psynet.participant.Participant, corresponding to the current participant.

  3. answer: The formatted answer returned by the participant.

  4. raw_answer: The unformatted answer returned by the participant.

  5. page: The page to which the participant is responding.

Returns:

• None or an object of class psynet.timeline.FailedValidation – On the case of failed validation, an instantiation of psynet.timeline.FailedValidation containing a message to pass to the participant.

class psynet.modular_page.DropdownControl(choices, labels=None, style='', name='dropdown', force_selection=True, default_text='Select an option', locale='en')

Bases: OptionControl

This control interface solicits a multiple-choice response from the participant using a dropdown selectbox.

Parameters:

• choices (List[str]) – The different options the participant has to choose from.

• labels (Optional[List[str]]) – An optional list of textual labels to apply to the dropdown options, which the participant will see instead of choices.

• style (str) – CSS style attributes to apply to the dropdown. Default: "".

• name (str) – Name of the dropdown selectbox.

• force_selection (bool) – Determines if an answer has to be selected. Default: True.

validate(response, **kwargs)

Takes the psynet.timeline.Response object created by the page and runs a validation check to determine whether the participant may continue to the next page.

Parameters:

• response – An instance of psynet.timeline.Response. Typically the answer attribute of this object is most useful for validation.

• **kwargs –

  Keyword arguments, including:

  1. experiment: An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.

  2. participant: An instantiation of psynet.participant.Participant, corresponding to the current participant.

  3. answer: The formatted answer returned by the participant.

  4. raw_answer: The unformatted answer returned by the participant.

  5. page: The page to which the participant is responding.

Returns:

• None or an object of class psynet.timeline.FailedValidation – On the case of failed validation, an instantiation of psynet.timeline.FailedValidation containing a message to pass to the participant.

class psynet.modular_page.FrameSliderControl(*, url, file_type, width, height, starting_value=0.5, minimal_time=2.0, reverse_scale=False, directional=True, hide_slider=False, bot_response=<class 'psynet.utils.NoArgumentProvided'>)

Bases: Control

get_bot_response(experiment, bot, page, prompt)

This function is used when a bot simulates a participant responding to a given page. In the simplest form, the function just returns the value of the answer that the bot returns. For more sophisticated treatment, the function can return a BotResponse object which contains other parameters such as blobs and metadata.

class psynet.modular_page.HtmlSliderControl(start_value, min_value, max_value, slider_media, media_locations, autoplay=False, disable_slider_on_change='', media_width='', media_height='', n_steps=10000, slider_id='sliderpage_slider', input_type='HTML5_range_slider', random_wrap=False, reverse_scale=False, directional=True, snap_values='media_locations', minimal_time=0, minimal_interactions=0, continuous_updates=False)

Bases: MediaSliderControl

This control solicits a slider response from the user that results in showing an HTML element. The slider can either be horizontal or circular.

Parameters:

• start_value (float) – Initial position of slider.

• min_value (float) – Minimum value of the slider.

• max_value (float) – Maximum value of the slider.

• slider_media (dict) –

  A dictionary of media assets (image). Each item can either be a string, corresponding to the URL for a single file (e.g. “/static/image/test.svg”), or a dictionary, corresponding to metadata for a batch of media assets. A batch dictionary must contain the field “url”, providing the URL to the batch file, and the field “ids”, providing the list of IDs for the batch’s constituent assets. A valid image argument might look like the following:

  {
      'example': '/static/example.svg',
      'my_batch': {
          'url': '/static/file_concatenated.batch',
          'ids': ['funk_game_loop', 'honey_bee', 'there_it_is'],
          'type': 'batch'
      }
  }
  

• media_locations (dict) – Dictionary with IDs as keys and locations on the slider as values.

• autoplay (Optional[bool]) – The media closest to the current slider position is shown once the page is loaded. Default: False.

• disable_slider_on_change (Union[float, str, None]) –

  • <float>: Duration for which the media slider should be disabled after its value changed, in seconds.

  • "while_playing": The slider will be disabled after a value change, as long as the related media is playing.

  • "never": The slider will not be disabled after a value change.

  Default: never.

• media_width (Optional[str]) – CSS width specification for the media container.

• media_height (Optional[str]) – CSS height specification for the media container.

• n_steps (Optional[int]) –

  • <int>: Number of equidistant steps between min_value and max_value that the slider can be dragged through. This is before any snapping occurs.

  • "n_media": Sets the number of steps to the number of media. This only makes sense if the media locations are distributed equidistant between the min_value and max_value of the slider.

  Default: 10000.

• slider_id (Optional[str]) – The HTML id attribute value of the slider. Default: “sliderpage_slider”.

• input_type (Optional[str]) – Defaults to “HTML5_range_slider”, which gives a standard horizontal slider. The other option currently is “circular_slider”, which gives a circular slider.

• random_wrap (Optional[bool]) – Defaults to False. If True then original value of the slider is wrapped twice, creating a new virtual range between min and min+2(max-min). To avoid boundary issues, the phase of the slider is randomised for each slider using the new range. During the user interaction with the slider, we use the virtual wrapped value (output_value) in the new range and with the random phase, but at the end we use the unwrapped value in the original range and without random phase (raw_value). Both values are stored in the metadata.

• reverse_scale (Optional[bool]) – Flip the scale. Default: False.

• directional (default: True) – Make the slider appear in either grey/blue color (directional) or all grey color (non-directional).

• snap_values (Union[int, list, None]) –

  • "media_locations": slider snaps to nearest image location.

  • <int>: indicates number of possible equidistant steps between min_value and max_value

  • <list>: enumerates all possible values, need to be within min_value and max_value.

  • None: don’t snap slider.

  Default: “media_locations”.

• minimal_interactions (Optional[int]) – Minimal interactions with the slider before the user can go to the next trial. Default: 0.

• minimal_time (Optional[int]) – Minimum amount of time in seconds that the user must spend on the page before they can continue. Default: 0.

• continuous_updates (Optional[bool]) – If True, then the slider continuously calls slider-update events when it is dragged, rather than just when it is released. In this case the log is disabled. Default: False.

class psynet.modular_page.ImagePrompt(url, text, width, height, show_after=0.0, hide_after=None, margin_top='0px', margin_bottom='0px', text_align='left')

Bases: Prompt

Displays an image to the participant.

Parameters:

• url (str) – URL of the image to show.

• text (Union[str, Markup]) – Text to display to the participant. This can either be a string for plain text, or an HTML specification from markupsafe.Markup.

• width (str) – CSS width specification for the image (e.g. '50%').

• height (str) – CSS height specification for the image (e.g. '50%'). 'auto' will choose the height automatically to match the width; the disadvantage of this is that other page content may move once the image loads.

• show_after (float) – Specifies the time in seconds when the image will be displayed, calculated relative to the start of the trial. Defaults to 0.0.

• hide_after (Optional[float]) – If not None, specifies a time in seconds after which the image should be hidden.

• margin_top (str) – CSS specification of the image’s top margin.

• margin_bottom (str) – CSS specification of the image’s bottom margin.

• text_align (str) – CSS alignment of the text.

class psynet.modular_page.ImageSliderControl(start_value, min_value, max_value, slider_media, media_locations, autoplay=False, disable_slider_on_change='', media_width='', media_height='', n_steps=10000, slider_id='sliderpage_slider', input_type='HTML5_range_slider', random_wrap=False, reverse_scale=False, directional=True, snap_values='media_locations', minimal_time=0, minimal_interactions=0, continuous_updates=False)

Bases: MediaSliderControl

This control solicits a slider response from the user that results in showing an image. The slider can either be horizontal or circular.

Parameters:

• start_value (float) – Initial position of slider.

• min_value (float) – Minimum value of the slider.

• max_value (float) – Maximum value of the slider.

• slider_media (dict) –

  A dictionary of media assets (image). Each item can either be a string, corresponding to the URL for a single file (e.g. “/static/image/test.png”), or a dictionary, corresponding to metadata for a batch of media assets. A batch dictionary must contain the field “url”, providing the URL to the batch file, and the field “ids”, providing the list of IDs for the batch’s constituent assets. A valid image argument might look like the following:

  {
      'example': '/static/example.png',
      'my_batch': {
          'url': '/static/file_concatenated.batch',
          'ids': ['funk_game_loop', 'honey_bee', 'there_it_is'],
          'type': 'batch'
      }
  }
  

• media_locations (dict) – Dictionary with IDs as keys and locations on the slider as values.

• autoplay (Optional[bool]) – The media closest to the current slider position is shown once the page is loaded. Default: False.

• disable_slider_on_change (Union[float, str, None]) –

  • <float>: Duration for which the media slider should be disabled after its value changed, in seconds.

  • "while_playing": The slider will be disabled after a value change, as long as the related media is playing.

  • "never": The slider will not be disabled after a value change.

  Default: never.

• media_width (Optional[str]) – CSS width specification for the media container. The image will scale to the width of this container.

• media_height (Optional[str]) – CSS height specification for the media container.

• n_steps (Optional[int]) –

  • <int>: Number of equidistant steps between min_value and max_value that the slider can be dragged through. This is before any snapping occurs.

  • "n_media": Sets the number of steps to the number of media. This only makes sense if the media locations are distributed equidistant between the min_value and max_value of the slider.

  Default: 10000.

• slider_id (Optional[str]) – The HTML id attribute value of the slider. Default: “sliderpage_slider”.

• input_type (Optional[str]) – Defaults to “HTML5_range_slider”, which gives a standard horizontal slider. The other option currently is “circular_slider”, which gives a circular slider.

• random_wrap (Optional[bool]) – Defaults to False. If True then original value of the slider is wrapped twice, creating a new virtual range between min and min+2(max-min). To avoid boundary issues, the phase of the slider is randomised for each slider using the new range. During the user interaction with the slider, we use the virtual wrapped value (output_value) in the new range and with the random phase, but at the end we use the unwrapped value in the original range and without random phase (raw_value). Both values are stored in the metadata.

• reverse_scale (Optional[bool]) – Flip the scale. Default: False.

• directional (default: True) – Make the slider appear in either grey/blue color (directional) or all grey color (non-directional).

• snap_values (Union[int, list, None]) –

  • "media_locations": slider snaps to nearest image location.

  • <int>: indicates number of possible equidistant steps between min_value and max_value

  • <list>: enumerates all possible values, need to be within min_value and max_value.

  • None: don’t snap slider.

  Default: “media_locations”.

• minimal_interactions (Optional[int]) – Minimal interactions with the slider before the user can go to the next trial. Default: 0.

• minimal_time (Optional[int]) – Minimum amount of time in seconds that the user must spend on the page before they can continue. Default: 0.

• continuous_updates (Optional[bool]) – If True, then the slider continuously calls slider-update events when it is dragged, rather than just when it is released. In this case the log is disabled. Default: False.

class psynet.modular_page.MediaSliderControl(start_value, min_value, max_value, slider_media, modality, media_locations, autoplay=False, disable_while_playing=False, disable_slider_on_change='', n_steps=10000, slider_id='sliderpage_slider', input_type='HTML5_range_slider', random_wrap=False, reverse_scale=False, directional=True, snap_values='media_locations', minimal_time=0, minimal_interactions=0)

Bases: SliderControl

This control solicits a slider response from the user that results in playing some media. The slider can either be horizontal or circular.

Parameters:

• start_value (float) – Initial position of slider.

• min_value (float) – Minimum value of the slider.

• max_value (float) – Maximum value of the slider.

• slider_media (dict) –

  A dictionary of media assets (image, video, or sound). Each item can either be a string, corresponding to the URL for a single file (e.g. “/static/audio/test.wav”), or a dictionary, corresponding to metadata for a batch of media assets. A batch dictionary must contain the field “url”, providing the URL to the batch file, and the field “ids”, providing the list of IDs for the batch’s constituent assets. A valid audio argument might look like the following:

  {
      'example': '/static/example.wav',
      'my_batch': {
          'url': '/static/file_concatenated.mp3',
          'ids': ['funk_game_loop', 'honey_bee', 'there_it_is'],
          'type': 'batch'
      }
  }
  

• modality (str) – Either "audio", "image" or "video".

• media_locations (dict) – Dictionary with IDs as keys and locations on the slider as values.

• autoplay (Optional[bool]) – The media closest to the current slider position is shown once the page is loaded. Default: False.

• disable_while_playing (bool) –

  If True, the slider is disabled while the media is playing. Default: False.

  Deprecated since version 11.0.0: Use disable_slider_on_change instead.

• disable_slider_on_change (Union[float, str, None]) –

  • <float>: Duration for which the media slider should be disabled after its value changed, in seconds.

  • "while_playing": The slider will be disabled after a value change, as long as the related media is playing.

  • "never": The slider will not be disabled after a value change.

  Default: never.

• n_steps (Optional[int]) –

  • <int>: Number of equidistant steps between min_value and max_value that the slider can be dragged through. This is before any snapping occurs.

  • "n_media": Sets the number of steps to the number of media. This only makes sense if the media locations are distributed equidistant between the min_value and max_value of the slider.

  Default: 10000.

• slider_id (Optional[str]) – The HTML id attribute value of the slider. Default: “sliderpage_slider”.

• input_type (Optional[str]) – Defaults to “HTML5_range_slider”, which gives a standard horizontal slider. The other option currently is “circular_slider”, which gives a circular slider.

• random_wrap (Optional[bool]) – Defaults to False. If True then original value of the slider is wrapped twice, creating a new virtual range between min and min+2(max-min). To avoid boundary issues, the phase of the slider is randomised for each slider using the new range. During the user interaction with the slider, we use the virtual wrapped value (output_value) in the new range and with the random phase, but at the end we use the unwrapped value in the original range and without random phase (raw_value). Both values are stored in the metadata.

• reverse_scale (Optional[bool]) – Flip the scale. Default: False.

• directional (default: True) – Make the slider appear in either grey/blue color (directional) or all grey color (non-directional).

• snap_values (Union[int, list, None]) –

  • "media_locations": slider snaps to nearest media location.

  • <int>: indicates number of possible equidistant steps between min_value and max_value

  • <list>: enumerates all possible values, need to be within min_value and max_value.

  • None: don’t snap slider.

  Default: “media_locations”.

• minimal_interactions (Optional[int]) – Minimal interactions with the slider before the user can go to the next trial. Default: 0.

• minimal_time (Optional[int]) – Minimum amount of time in seconds that the user must spend on the page before they can continue. Default: 0.

• continuous_updates – If True, then the slider continuously calls slider-update events when it is dragged, rather than just when it is released. In this case the log is disabled. Default: False.

class psynet.modular_page.ModularPage(label, prompt, control=None, time_estimate=None, media=None, events=None, js_vars=None, start_trial_automatically=True, buttons=None, show_start_button=False, show_next_button=None, validate=None, layout=<class 'psynet.utils.NoArgumentProvided'>, **kwargs)

Bases: Page

The ModularPage class provides a way of defining pages in terms of two primary components: the Prompt and the Control. The former determines what is presented to the participant; the latter determines how they may respond.

Parameters:

• label (str) – Internal label to give the page, used for example in results saving.

• prompt (Union[str, dom_tag, Prompt]) – A Prompt object that determines the prompt to be displayed to the participant. Alternatively, you can also provide text or a markupsafe.Markup object, which will then be automatically wrapped in a Prompt object.

• control (Optional[Control]) – A Control object that determines the participant’s response controls.

• time_estimate (Optional[float]) – Time estimated for the page.

• media (Optional[MediaSpec]) – Optional specification of media assets to preload (see the documentation for psynet.timeline.MediaSpec). Typically this field can be left blank, as media will be passed through the Prompt or Control objects instead.

• js_vars (Optional[dict]) – Optional dictionary of arguments to instantiate as global Javascript variables.

• start_trial_automatically (bool) – If True (default), the trial starts automatically, e.g. by the playing of a queued audio file. Otherwise the trial will wait for the trialPrepare event to be triggered (e.g. by clicking a ‘Play’ button, or by calling psynet.trial.registerEvent(“trialPrepare”) in JS).

• buttons (Optional[List]) – An optional list of additional buttons to include on the page. Normally these will be created by calls to psynet.modular_page.Button.

• show_start_button (Optional[bool]) – Determines whether a ‘start’ button is shown on the page. The default is False, but one might consider setting this to True if start_trial_automatically is set to False.

• show_next_button (Optional[bool]) – Determines whether a ‘next’ button is shown on the page. The default is None, which means that the decision is deferred to the selected Control. If set to True or False, the default from the Control is overridden.

• validate (Optional[callable]) –

  Optional validation function to use for the participant’s response. If left blank, then the validation function will instead be read from the provided Control. Alternatively, the validation function can be set by overriding this class’s validate method. If no validation function is found, no validation is performed.

  Validation functions provided via the present route may contain various optional arguments. Most typically the function will be of the form lambda answer: ...` or ``lambda answer, participant: ..., but it is also possible to include the arguments raw_answer, response, page, and experiment. Note that raw_answer is the answer before applying format_answer, and answer is the answer after applying format_answer.

  Validation functions should return None if the validation passes, or if it fails a string corresponding to a message to pass to the participant.

  For example, a validation function testing that the answer contains exactly 3 characters might look like this: lambda answer: "Answer must contain exactly 3 characters!" if len(answer) != 3 else None.

• layout – Determines the layout of elements in the page. Should take the form of a list that enumerates the page elements in order of appearance. If left blank, defaults to .default_layout.

• **kwargs – Further arguments to be passed to psynet.timeline.Page.

format_answer(raw_answer, **kwargs)

By default, the format_answer method is extracted from the page’s Control member.

get_bot_response(experiment, bot)

This function is used when a bot simulates a participant responding to a given page. In the simplest form, the function just returns the value of the answer that the bot returns. For more sophisticated treatment, the function can return a BotResponse object which contains other parameters such as blobs and metadata.

metadata(**kwargs)

By default, the metadata attribute combines the metadata of the Prompt member. and the Control members.

pre_render()

This method is called immediately prior to rendering the page for the participant. It will be called again each time the participant refreshes the page.

validate(response, **kwargs)

Takes the psynet.timeline.Response object created by the page and runs a validation check to determine whether the participant may continue to the next page.

Parameters:

• response – An instance of psynet.timeline.Response. Typically the answer attribute of this object is most useful for validation.

• **kwargs –

  Keyword arguments, including:

  1. experiment: An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.

  2. participant: An instantiation of psynet.participant.Participant, corresponding to the current participant.

  3. answer: The formatted answer returned by the participant.

  4. raw_answer: The unformatted answer returned by the participant.

  5. page: The page to which the participant is responding.

Returns:

• None or an object of class psynet.timeline.FailedValidation – On the case of failed validation, an instantiation of psynet.timeline.FailedValidation containing a message to pass to the participant.

class psynet.modular_page.MultiSliderControl(sliders, next_button=True, bot_response=<class 'psynet.utils.NoArgumentProvided'>)

Bases: Control

class psynet.modular_page.MusicNotationPrompt(content, text=None, text_align='left')

Bases: Prompt

Displays music notation using the abcjs library by Paul Rosen and Gregory Dyke. See https://www.abcjs.net/ for information about abcjs. See https://abcnotation.com/ for information about ABC notation.

Parameters:

• content (str) – Content to display, in ABC notation. This will be rendered to an image. See https://www.abcjs.net/abcjs-editor.html for an interactive editor. See https://abcnotation.com/wiki/abc:standard:v2.1 for a detailed definition of ABC notation.

• text (Union[None, str, Markup, dom_tag]) – Text to display above the score.

• text_align (str) – Alignment instructions for this text.

class psynet.modular_page.NullControl(bot_response=<class 'psynet.utils.NoArgumentProvided'>, locale='en', buttons=None, show_next_button=True)

Bases: Control

Here the participant just has a single button that takes them to the next page.

get_bot_response(experiment, bot, page, prompt)

This function is used when a bot simulates a participant responding to a given page. In the simplest form, the function just returns the value of the answer that the bot returns. For more sophisticated treatment, the function can return a BotResponse object which contains other parameters such as blobs and metadata.

class psynet.modular_page.NumberControl(width='120px', text_align='right', bot_response=<class 'psynet.utils.NoArgumentProvided'>, locale='en')

Bases: Control

This control interface solicits number input from the participant.

Parameters:

• width (Optional[str]) – CSS width property for the text box. Default: “120px”.

• text_align (Optional[str]) – CSS width property for the alignment of the text inside the number input field. Default: “right”.

get_bot_response(experiment, bot, page, prompt)

This function is used when a bot simulates a participant responding to a given page. In the simplest form, the function just returns the value of the answer that the bot returns. For more sophisticated treatment, the function can return a BotResponse object which contains other parameters such as blobs and metadata.

validate(response, **kwargs)

Takes the psynet.timeline.Response object created by the page and runs a validation check to determine whether the participant may continue to the next page.

Parameters:

• response – An instance of psynet.timeline.Response. Typically the answer attribute of this object is most useful for validation.

• **kwargs –

  Keyword arguments, including:

  1. experiment: An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.

  2. participant: An instantiation of psynet.participant.Participant, corresponding to the current participant.

  3. answer: The formatted answer returned by the participant.

  4. raw_answer: The unformatted answer returned by the participant.

  5. page: The page to which the participant is responding.

Returns:

• None or an object of class psynet.timeline.FailedValidation – On the case of failed validation, an instantiation of psynet.timeline.FailedValidation containing a message to pass to the participant.

class psynet.modular_page.OptionControl(choices, labels=None, style='', bot_response=<class 'psynet.utils.NoArgumentProvided'>, **kwargs)

Bases: Control

The OptionControl class provides four kinds of controls for the participant in its subclasses CheckboxControl, DropdownControl, PushButtonControl, and RadioButtonControl.

get_bot_response(experiment, bot, page, prompt)

This function is used when a bot simulates a participant responding to a given page. In the simplest form, the function just returns the value of the answer that the bot returns. For more sophisticated treatment, the function can return a BotResponse object which contains other parameters such as blobs and metadata.

class psynet.modular_page.Prompt(text=None, text_align='left', buttons=None)

Bases: object

The Prompt class displays some kind of media to the participant, to which they will have to respond.

Currently the prompt must be written as a Jinja2 macro in templates/macros.html. In the future, we will update the API to allow macros to be defined in external files.

Parameters:

• text (Union[None, str, Markup]) – Optional text to display to the participant. This can either be a string, which will be HTML-escaped and displayed as regular text, or an HTML string as produced by markupsafe.Markup.

• text_align (str) – CSS alignment of the text.

• buttons (Optional[List]) – An optional list of additional buttons to include on the page. Normally these will be created by calls to psynet.modular_page.Button.

macro

The name of the Jinja2 macro as defined within the respective template file.

Type:

str

metadata

Metadata to save about the prompt; can take arbitrary form, but must be serialisable to JSON.

Type:

Object

media

Optional object of class MediaSpec that provisions media resources for the prompt.

Type:

MediaSpec

external_template

Optionally specifies a custom Jinja2 template from which the prompt macro should be sourced. If not provided, the prompt macro will be assumed to be located in PsyNet’s built-in prompt.html file.

Type:

Optional[str]

class psynet.modular_page.PushButtonControl(choices, labels=None, style='min-width: 100px; margin: 10px', arrange_vertically=True, show_next_button=False, **kwargs)

Bases: OptionControl

This control interface solicits a multiple-choice response from the participant.

Parameters:

• choices (List[Union[str, float, int]]) – The different options the participant has to choose from.

• labels (Optional[List[str]]) – An optional list of textual labels to apply to the buttons, which the participant will see instead of choices. Default: None.

• style (str) – CSS styles to apply to the buttons. Default: "min-width: 100px; margin: 10px".

• arrange_vertically (bool) – Whether to arrange the buttons vertically. Default: True.

class psynet.modular_page.RadioButtonControl(choices, labels=None, style='cursor: pointer;', name='radiobuttons', arrange_vertically=True, force_selection=True, show_reset_button='never', show_free_text_option=False, placeholder_text_free_text=None, locale='en')

Bases: OptionControl

This control interface solicits a multiple-choice response from the participant using radiobuttons.

Parameters:

• choices (List[str]) – The different options the participant has to choose from.

• labels (Optional[List[str]]) – An optional list of textual labels to apply to the radiobuttons, which the participant will see instead of choices.

• style (str) – CSS style attributes to apply to the radiobuttons. Default: "cursor: pointer".

• name (str) – Name of the radiobutton group.

• arrange_vertically (bool) – Whether to arrange the radiobuttons vertically.

• force_selection (bool) – Determines if an answer has to be selected. Default: True.

• show_reset_button (str) – Whether to display a ‘Reset’ button to allow for unsetting a ticked radiobutton. Possible values are: never, always, and on_selection, the latter meaning that the button is displayed only when a radiobutton is ticked. Default: never.

• show_free_text_option (bool) – Appends a free text option to the radiobuttons. Default: False.

validate(response, **kwargs)

Takes the psynet.timeline.Response object created by the page and runs a validation check to determine whether the participant may continue to the next page.

Parameters:

• response – An instance of psynet.timeline.Response. Typically the answer attribute of this object is most useful for validation.

• **kwargs –

  Keyword arguments, including:

  1. experiment: An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.

  2. participant: An instantiation of psynet.participant.Participant, corresponding to the current participant.

  3. answer: The formatted answer returned by the participant.

  4. raw_answer: The unformatted answer returned by the participant.

  5. page: The page to which the participant is responding.

Returns:

• None or an object of class psynet.timeline.FailedValidation – On the case of failed validation, an instantiation of psynet.timeline.FailedValidation containing a message to pass to the participant.

class psynet.modular_page.RecordControl(duration, auto_advance=False, show_meter=False, bot_response=<class 'psynet.utils.NoArgumentProvided'>, **kwargs)

Bases: Control

Generic class for recording controls. Cannot be instantiated directly. See AudioRecordControl and VideoRecordControl.

duration

Duration of the desired recording, in seconds. Note: the output recording may not be exactly this length, owing to inaccuracies in the Javascript recording process.

auto_advance

Whether the page should automatically advance to the next page once the audio recording has been uploaded.

show_meter

Whether an audio meter should be displayed, so as to help the participant to calibrate their volume.

class psynet.modular_page.SliderControl(start_value, min_value, max_value, n_steps=10000, reverse_scale=False, directional=True, slider_id='sliderpage_slider', input_type='HTML5_range_slider', random_wrap=False, snap_values=None, minimal_interactions=0, minimal_time=0, continuous_updates=False, template_filename=None, template_args=None, bot_response=<class 'psynet.utils.NoArgumentProvided'>)

Bases: Control

This control interface displays either a horizontal or circular slider to the participant.

The control logs all interactions from the participant including: - initial location of the slider - subsequent release points along with time stamps

Currently the slider does not display any numbers describing the slider’s current position. We anticipate adding this feature in a future release, if there is interest.

Parameters:

• label – Internal label for the control (used to store results).

• start_value (float) – Initial position of slider.

• min_value (float) – Minimum value of the slider.

• max_value (float) – Maximum value of the slider.

• n_steps (int) – Determines the number of steps that the slider can be dragged through. Default: 10000.

• snap_values (Union[int, list, None]) –

  Optional. Determines the values to which the slider will ‘snap’ to once it is released. Can take various forms:

  • <None>: no snapping is performed.

  • <int>: indicating number of equidistant steps between min_value and max_value.

  • <list>: list of numbers enumerating all possible values, need to be within min_value and max_value.

• reverse_scale (Optional[bool]) – Flip the scale. Default: False.

• directional (default: True) – Make the slider appear in either grey/blue color (directional) or all grey color (non-directional).

• slider_id (Optional[str]) – The HTML id attribute value of the slider. Default: “sliderpage_slider”.

• input_type (Optional[str]) – Defaults to “HTML5_range_slider”, which gives a standard horizontal slider. The other option currently is “circular_slider”, which gives a circular slider.

• random_wrap (Optional[bool]) – Defaults to False. If True then slider is wrapped twice so that there are no boundary jumps, and the phase to initialize the wrapping is randomized each time.

• minimal_interactions (Optional[int]) – Minimal interactions with the slider before the user can go to the next trial. Default: 0.

• minimal_time (Optional[int]) – Minimum amount of time in seconds that the user must spend on the page before they can continue. Default: 0.

• continuous_updates (Optional[bool]) – If True, then the slider continuously calls slider-update events when it is dragged, rather than just when it is released. In this case the log is disabled. Default: False.

• template_filename (Optional[str]) – Filename of an optional additional template. Default: None.

• template_args (Optional[Dict]) – Arguments for the optional additional template. Default: None.

get_bot_response(experiment, bot, page, prompt)

This function is used when a bot simulates a participant responding to a given page. In the simplest form, the function just returns the value of the answer that the bot returns. For more sophisticated treatment, the function can return a BotResponse object which contains other parameters such as blobs and metadata.

validate(response, **kwargs)

Takes the psynet.timeline.Response object created by the page and runs a validation check to determine whether the participant may continue to the next page.

Parameters:

• response – An instance of psynet.timeline.Response. Typically the answer attribute of this object is most useful for validation.

• **kwargs –

  Keyword arguments, including:

  1. experiment: An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.

  2. participant: An instantiation of psynet.participant.Participant, corresponding to the current participant.

  3. answer: The formatted answer returned by the participant.

  4. raw_answer: The unformatted answer returned by the participant.

  5. page: The page to which the participant is responding.

Returns:

• None or an object of class psynet.timeline.FailedValidation – On the case of failed validation, an instantiation of psynet.timeline.FailedValidation containing a message to pass to the participant.

class psynet.modular_page.StartButton

Bases: Button

class psynet.modular_page.SurveyJSControl(design, bot_response=<class 'psynet.utils.NoArgumentProvided'>)

Bases: Control

This control exposes the open-source SurveyJS library. You can use this library to develop sophisticated questionnaires which many different question types.

When a SurveyJSControl is included in a PsyNet timeline it produces a single SurveyJS survey. This survey can have multiple questions and indeed multiple pages. Responses to these questions are compiled together as a dictionary and saved as the participant’s answer, similar to other controls.

The recommended way to design a SurveyJS survey is to use their free Survey Creator tool. This can be accessed from their website: https://surveyjs.io/create-free-survey. You design your survey using the interactive editor. Once you are done, click the “JSON Editor” tab. Copy and paste the provided JSON into the design argument of your SurveyJSControl. You may need to update a few details to match Python syntax, for example replacing true with True; your syntax highlighter should flag up points that need updating. That’s it!

See https://surveyjs.io/ for more details.

See the survey_js demo for example usage.

Parameters:

• design – A JSON-style specification for the survey.

• bot_response – Used for bot simulations; see demos for example usage.

format_answer(raw_answer, **kwargs)

Formats the raw answer object returned from the participant’s browser.

Parameters:

• raw_answer – The raw answer object returned from the participant’s browser.

• **kwargs –

  Keyword arguments, including:

  1. blobs: A dictionary of any blobs that were returned from the participant’s browser.

  2. metadata: The metadata returned from the participant’s browser.

  3. experiment: An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.

  4. participant: An instantiation of psynet.participant.Participant, corresponding to the current participant.

  5. trial: An instantiation of psynet.trial.main.Trial, corresponding to the participant’s current trial, or None if the participant is not currently taking a trial.

Returns:

• Object – The formatted answer, suitable for serialisation to JSON and storage in the database.

get_bot_response(experiment, bot, page, prompt)

This function is used when a bot simulates a participant responding to a given page. In the simplest form, the function just returns the value of the answer that the bot returns. For more sophisticated treatment, the function can return a BotResponse object which contains other parameters such as blobs and metadata.

class psynet.modular_page.TappingAudioMeterControl(calibrate=False, show_next_button=True, min_time=0.0, bot_response=<class 'psynet.utils.NoArgumentProvided'>, **kwargs)

Bases: AudioMeterControl

class psynet.modular_page.TextControl(one_line=True, width=None, height=None, text_align='left', block_copy_paste=False, bot_response=<class 'psynet.utils.NoArgumentProvided'>)

Bases: Control

This control interface solicits free text from the participant.

Parameters:

• one_line (bool) – Whether the text box should comprise solely one line.

• width (Optional[str]) – CSS width property for the text box.

• height (Optional[str]) – CSS height property for the text box.

• text_align (str) – CSS width property for the alignment of the text inside the text input field. Default: “left”.

• block_copy_paste (bool) – Whether to block the copy, cut and paste options in the text input box.

get_bot_response(experiment, bot, page, prompt)

This function is used when a bot simulates a participant responding to a given page. In the simplest form, the function just returns the value of the answer that the bot returns. For more sophisticated treatment, the function can return a BotResponse object which contains other parameters such as blobs and metadata.

class psynet.modular_page.TimedPushButtonControl(choices, labels=None, button_highlight_duration=0.75, **kwargs)

Bases: PushButtonControl

This presents a multiple-choice push-button interface to the participant. The participant can press as many buttons as they like, and the timing of each press will be recorded. They advance to the next page by pressing a ‘Next’ button.

Parameters:

• choices (List[str]) – The different options the participant has to choose from.

• labels (Optional[List[str]]) – An optional list of textual labels to apply to the buttons, which the participant will see instead of choices. Default: None.

• button_highlight_duration (float) – How long to highlight the button for once it has been clicked (seconds). Defaults to 0.75 s.

• style – CSS styles to apply to the buttons. Default: "min-width: 100px; margin: 10px".

• arrange_vertically – Whether to arrange the buttons vertically. Default: True.

• **kwargs – Other arguments to pass to PushButtonControl.

format_answer(raw_answer, **kwargs)

Formats the raw answer object returned from the participant’s browser.

Parameters:

• raw_answer – The raw answer object returned from the participant’s browser.

• **kwargs –

  Keyword arguments, including:

  1. blobs: A dictionary of any blobs that were returned from the participant’s browser.

  2. metadata: The metadata returned from the participant’s browser.

  3. experiment: An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.

  4. participant: An instantiation of psynet.participant.Participant, corresponding to the current participant.

  5. trial: An instantiation of psynet.trial.main.Trial, corresponding to the participant’s current trial, or None if the participant is not currently taking a trial.

Returns:

• Object – The formatted answer, suitable for serialisation to JSON and storage in the database.

class psynet.modular_page.VideoPrompt(video, text, text_align='left', width='560px', height='auto', play_window=None, controls=False, muted=False, hide_when_finished=True, mirrored=False, **kwargs)

Bases: Prompt

Plays a video file to the participant.

Parameters:

• video – Video file to play. Can be an Asset object, or alternatively a URL written as a string.

• text (Union[str, Markup]) – Text to display to the participant. This can either be a string for plain text, or an HTML specification from markupsafe.Markup.

• text_align (str) – CSS alignment of the text.

• width (str) – Width of the video frame to be displayed. Default: “560px”.

• height (str) – Height of the video frame to be displayed. Default is “auto” whereby the height is automatically adjusted to match the width.

• play_window (Optional[List]) – An optional two-element list identifying the time window in the video file that should be played. If a list is provided, the first element must be a number specifying the timepoint in seconds at which the video should begin. The second element may then either be None, in which case the video is played until the end, or a number specifying the timepoint in seconds at which the video should end.

• controls (bool) – Determines whether the user should be given controls for manipulating video playback.

• muted (bool) – If True, then the video will be muted (i.e. it will play without audio). The default is False.

• hide_when_finished (bool) – If True (default), the video will disappear once it has finished playing.

• mirrored (bool) – Whether to mirror the video on playback. Default: False.

• kwargs – Passed to Prompt.

class psynet.modular_page.VideoRecordControl(*, recording_source='camera', record_audio=True, audio_n_channels=1, width='300px', show_preview=False, controls=False, loop_playback=False, mirrored=True, personal=True, bot_response_media=None, **kwargs)

Bases: RecordControl

Records a video either by using the camera or by capturing from the screen. Output format for both screen and camera recording is .webm.

Parameters:

• recording_source (str) – Specifies whether to record by using the camera and/or by capturing from the screen. Possible values are ‘camera’, ‘screen’ and ‘both’. Default: ‘camera’.

• record_audio (bool) – Whether to record audio using the microphone. This setting only applies when ‘camera’ or ‘both’ is chosen as recording_source. Default: True.

• audio_n_channels (int) – The number of channels used to record the audio (if enabled by record_audio). Default is mono (audio_n_channels=1).

• width (str) – Width of the video frame to be displayed. Default: “560px”.

• show_preview (bool) – Whether to show a preview of the video on the page. Default: False.

• controls (bool) – Whether to provide controls for manipulating the recording.

• loop_playback (bool) – Whether to loop playback by default (only relevant if controls=True.

• mirrored (bool) – Whether the preview of the video is displayed as if looking into a mirror. Default: True.

• personal (bool) – Whether the recording should be marked as ‘personal’ and hence excluded from ‘scrubbed’ data exports. Default: True.

format_answer(raw_answer, **kwargs)

Formats the raw answer object returned from the participant’s browser.

Parameters:

• raw_answer – The raw answer object returned from the participant’s browser.

• **kwargs –

  Keyword arguments, including:

  1. blobs: A dictionary of any blobs that were returned from the participant’s browser.

  2. metadata: The metadata returned from the participant’s browser.

  3. experiment: An instantiation of psynet.experiment.Experiment, corresponding to the current experiment.

  4. participant: An instantiation of psynet.participant.Participant, corresponding to the current participant.

  5. trial: An instantiation of psynet.trial.main.Trial, corresponding to the participant’s current trial, or None if the participant is not currently taking a trial.

Returns:

• Object – The formatted answer, suitable for serialisation to JSON and storage in the database.

get_bot_response(experiment, bot, page, prompt)

This function is used when a bot simulates a participant responding to a given page. In the simplest form, the function just returns the value of the answer that the bot returns. For more sophisticated treatment, the function can return a BotResponse object which contains other parameters such as blobs and metadata.

class psynet.modular_page.VideoSliderControl(start_value, min_value, max_value, slider_media, media_locations, autoplay=False, disable_while_playing=False, disable_slider_on_change='never', media_width='', media_height='', n_steps=10000, slider_id='sliderpage_slider', input_type='HTML5_range_slider', random_wrap=False, reverse_scale=False, directional=True, snap_values='media_locations', minimal_time=0, minimal_interactions=0, **kwargs)

Bases: MediaSliderControl

This control solicits a slider response from the user that results in showing a video. The slider can either be horizontal or circular.

Parameters:

• start_value (float) – Initial position of slider.

• min_value (float) – Minimum value of the slider.

• max_value (float) – Maximum value of the slider.

• slider_media (dict) –

  A dictionary of media assets (video). Each item can either be a string, corresponding to the URL for a single file (e.g. “/static/image/test.mp4”), or a dictionary, corresponding to metadata for a batch of media assets. A batch dictionary must contain the field “url”, providing the URL to the batch file, and the field “ids”, providing the list of IDs for the batch’s constituent assets. A valid image argument might look like the following:

  {
      'example': '/static/example.mp4',
      'my_batch': {
          'url': '/static/file_concatenated.mp4',
          'ids': ['funk_game_loop', 'honey_bee', 'there_it_is'],
          'type': 'batch'
      }
  }
  

• media_locations (dict) – Dictionary with IDs as keys and locations on the slider as values.

• autoplay (Optional[bool]) – The media closest to the current slider position is shown once the page is loaded. Default: False.

• disable_while_playing (bool) –

  If True, the slider is disabled while the media is playing. Default: False.

  Deprecated since version 11.0.0: Use disable_slider_on_change instead.

• disable_slider_on_change (Union[float, str, None]) –

  • <float>: Duration for which the media slider should be disabled after its value changed, in seconds.

  • "while_playing": The slider will be disabled after a value change, as long as the related media is playing.

  • "never": The slider will not be disabled after a value change.

  Default: never.

• media_width (Optional[str]) – CSS width specification for the media container. The video will scale to the width of this container.

• media_height (Optional[str]) – CSS height specification for the media container.

• n_steps (Optional[int]) –

  • <int>: Number of equidistant steps between min_value and max_value that the slider can be dragged through. This is before any snapping occurs.

  • "n_media": Sets the number of steps to the number of media. This only makes sense if the media locations are distributed equidistant between the min_value and max_value of the slider.

  Default: 10000.

• slider_id (Optional[str]) – The HTML id attribute value of the slider. Default: “sliderpage_slider”.

• input_type (Optional[str]) – Defaults to “HTML5_range_slider”, which gives a standard horizontal slider. The other option currently is “circular_slider”, which gives a circular slider.

• random_wrap (Optional[bool]) – Defaults to False. If True then original value of the slider is wrapped twice, creating a new virtual range between min and min+2(max-min). To avoid boundary issues, the phase of the slider is randomised for each slider using the new range. During the user interaction with the slider, we use the virtual wrapped value (output_value) in the new range and with the random phase, but at the end we use the unwrapped value in the original range and without random phase (raw_value). Both values are stored in the metadata.

• reverse_scale (Optional[bool]) – Flip the scale. Default: False.

• directional (default: True) – Make the slider appear in either grey/blue color (directional) or all grey color (non-directional).

• snap_values (Union[int, list, None]) –

  • "media_locations": slider snaps to nearest video location.

  • <int>: indicates number of possible equidistant steps between min_value and max_value

  • <list>: enumerates all possible values, need to be within min_value and max_value.

  • None: don’t snap slider.

  Default: “media_locations”.

• minimal_interactions (Optional[int]) – Minimal interactions with the slider before the user can go to the next trial. Default: 0.

• minimal_time (Optional[int]) – Minimum amount of time in seconds that the user must spend on the page before they can continue. Default: 0.