Timeline¶

CodeBlock¶

class psynet.timeline.CodeBlock(function)[source]¶

A timeline component that executes some back-end logic without showing anything to the participant.

Parameters:: function – A function with up to two arguments named participant and experiment, that is executed once the participant reaches the corresponding part of the timeline.

Conditional statements¶

psynet.timeline.conditional(label, condition, logic_if_true, logic_if_false=None, fix_time_credit=False, bound_progress=True, log_chosen_branch=True, time_estimate=None)[source]¶

Executes a series of elts if and only if a certain condition is satisfied.

Parameters:

label (str) – Internal label to assign to the construct.
condition (Callable) – A function with up to two arguments named participant and experiment, that is executed once the participant reaches the corresponding part of the timeline, returning a Boolean.
logic_if_true – An elt (or list of elts) to display if condition returns True.
logic_if_false – An optional elt (or list of elts) to display if condition returns False.
fix_time_credit (bool) – Whether participants should receive the same time credit irrespective of the branch taken. Defaults to False; if set to True, all participants receive the same credit, corresponding to the branch with the maximum time credit.
bound_progress (bool) – Whether the progress estimate should be ‘bound’ such that, whatever happens, when the participant exits the conditional construct, the progress estimate will be the same as if the participant had taken the branch with the maximum time credit. Defaults to True.
log_chosen_branch (bool) – Whether to keep a log of which participants took each branch; defaults to True.
time_estimate (float) – An optional time estimate to use for the conditional construct. If not provided, the time estimate will be estimated by computing time estimates for the two branches and taking the maximum.

Returns:

list – A list of elts that can be embedded in a timeline using psynet.timeline.join().

Page¶

class psynet.timeline.Page(*, time_estimate=None, template_path=None, template_str=None, template_arg=None, label='untitled', js_vars=None, js_links=None, media=None, scripts=None, css=None, css_links=None, contents=None, session_id=None, save_answer=True, events=None, progress_display=None, start_trial_automatically=True, show_termination_button=None, aggressive_termination_on_no_focus=False, bot_response=<class 'psynet.utils.NoArgumentProvided'>, validate=None)[source]¶

The base class for pages, customised by passing values to the __init__ function and by overriding the following methods:

format_answer()
validate()
metadata()

Parameters:

time_estimate (Optional[float]) – Time estimated for the page.
template_path (Optional[str]) – Path to the jinja2 template to use for the page.
template_str (Optional[str]) – Alternative way of specifying the jinja2 template as a string.
template_arg (Optional[Dict]) – Dictionary of arguments to pass to the jinja2 template.
label (str) – Internal label to give the page, used for example in results saving.
js_vars (Optional[Dict]) – Dictionary of arguments to instantiate as global Javascript variables.
js_links (Optional[List]) – Optional list of paths to JavaScript scripts to include in the page.
media (psynet.timeline.MediaSpec) – Optional specification of media assets to preload (see the documentation for psynet.timeline.MediaSpec).
scripts (Optional[List]) – Optional list of scripts to include in the page. Each script should be represented as a string, which will be passed verbatim to the page’s HTML.

css (Optional[List]) –

Optional list of CSS specification to include in the page. Each specification should be represented as a string, which will be passed verbatim to the page’s HTML. A valid CSS specification might look like this:

.modal-content {
    background-color: #4989C8;
    margin: auto;
    padding: 20px;
    border: 1px solid #888;
    width: 80%;
}

.close {
    color: #aaaaaa;
    float: right;
    font-size: 28px;
    font-weight: bold;
}

css_links (Optional[List]) – Optional list of links to CSS stylesheets to include in the page.
contents (Optional[Dict]) – Optional dictionary to store some experiment specific data. For example, in an experiment about melodies, the contents property might look something like this: {”melody”: [1, 5, 2]}.
save_answer (bool) – If True (default), then the answer generated by the page is saved to participant.answer, and a link to the corresponding Response object is saved in participant.last_response_id. If False, these slots are left unchanged. If a string, then the answer is not only saved to participant.answer and participant.last_response_id, but it is additionally saved as a participant variable named by that string.
events (Optional[Dict]) – An optional dictionary of event specifications for the page. This determines the timing of various Javascript events that happen on the page. Each key of this dictionary corresponds to a particular event. Each value should then correspond to an object of class Event. The Event object specifies how the event is triggered by other events. For example, if I want to define an event that occurs 3 seconds after the trial starts, I would write events={"myEvent": Event(is_triggered_by="trialStart", delay=3.0)}. Useful standard events to know are trialStart (start of the trial), promptStart (start of the prompt), promptEnd (end of the prompt), recordStart (beginning of a recording), recordEnd (end of a recording), responseEnable (enables the response options), and submitEnable (enables the user to submit their response). These events and their triggers are set to sensible defaults, but the user is welcome to modify them for greater customization. See also the update_events methods of Prompt and Control, which provide alternative ways to customize event sequences for modular pages.
progress_display (Optional[ProgressDisplay]) – Optional ProgressDisplay object.
show_termination_button (bool) – If True, a button is displayed allowing the participant to terminate the experiment, Defaults to recruiter.show_termination_button which can be False for all recruiters except for the Lucid recruiter where it should be True.
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).
bot_response – Optional function to call when this page is consumed by a bot. This will override any bot_response function specified in the class’s bot_response method.
validate (Optional[callable]) –
Optional validation function to use for the participant’s response. Alternatively, the validation function can be set by overriding this class’s validate method. If no validation function is found, no validation is performed. See validate() for information about how to write this function.

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.

contents¶

A dictionary containing experiment specific data.

Type:: dict

session_id¶

If session_id is not None, then it must be a string. If two consecutive pages occur with the same session_id, then when it’s time to move to the second page, the browser will not navigate to a new page, but will instead update the Javascript variable psynet.page with metadata for the new page, and will trigger an event called pageUpdated. This event can be listened for with Javascript code like window.addEventListener(”pageUpdated”, …).

Type:: str

dynamically_update_progress_bar_and_reward¶

If True, then the page will regularly poll for updates to the progress bar and the reward. If False (default), the progress bar and reward are updated only on page refresh or on transition to the next page.

Type:: bool

attributes(participant)[source]¶: Returns a dictionary containing the session_id, the page type, and the page_uuid .

format_answer(raw_answer, **kwargs)[source]¶

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.

Returns:

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

get_bot_response(experiment, bot)[source]¶: 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)[source]¶

Compiles metadata about the page or its response from the participant. This metadata will be merged with the default metadata object returned from the browser, with any duplicate terms overwritten.

Parameters:

**kwargs –

Keyword arguments, including:

raw_answer: The raw answer returned from the participant’s browser.
answer: The formatted answer.
metadata: The original metadata returned from the participant’s browser.

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

Returns:

dict – A dictionary of metadata.

pre_render()[source]¶: 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)[source]¶

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.page.DebugResponsePage[source]¶

Bases: PageMaker

Implements a debugging page for responses. Displays a page to the user with information about the last response received from the participant.

class psynet.page.ExecuteFrontEndJS(js, message='')[source]¶: Bases: InfoPage

class psynet.page.InfoPage(content, time_estimate=None, **kwargs)[source]¶

Bases: ModularPage

This page displays some content to the user alongside a button with which to advance to the next page.

Parameters:

content (Union[str, Markup, dom_tag]) – The content to display to the user. Use markupsafe.Markup to display raw HTML.
time_estimate (Optional[float]) – Time estimated for the page.
**kwargs – Further arguments to pass to psynet.modular_page.ModularPage.

get_bot_response(experiment, bot)[source]¶: 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.page.JsPsychPage(label, timeline, time_estimate, js_links, css_links, js_vars=None, **kwargs)[source]¶

Bases: Page

A page that embeds a jsPsych experiment. See demos/jspsych for example usage.

label :: Label for the page.
timeline :: A path to an HTML file that defines the jsPsych experiment’s timeline. The timeline should be saved as an object called timeline. See demos/jspsych for an example.
js_links :: A list of links to JavaScript files to include in the page. Typically this would include a link to the required jsPsych version as well as links to the required plug-ins. It is recommended to include these files in the static directory and refer to them using relative paths; alternatively it is possible to link to these files via a CDN.
css_links :: A list of links to CSS stylesheets to include. Typically this would include the standard jsPsych stylesheet.
js_vars :: An optional dictionary of variables to pass to the front-end. These can then be accessed in the timeline template, writing for example psynet.var["my_variable"].

format_answer(raw_answer, **kwargs)[source]¶

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.

Returns:

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

class psynet.page.RejectedConsentPage(failure_tags=None, **kwargs)[source]¶: Bases: PageMaker

class psynet.page.SuccessfulEndPage[source]¶: Bases: PageMaker

class psynet.page.UnityPage(title, resources, contents, session_id, game_container_width='960px', game_container_height='600px', time_estimate=None, debug=False, **kwargs)[source]¶

Bases: Page

This is the main page when conducting Unity experiments. Its attributes contents and attributes can be accessed through the JavaScript variable psynet.page inside the page template.

Ín order to conclude this page call the psynet.nextPage function which has following parameters:

rawAnswer: The main answer that the page returns.
metadata: Additional information that might be useful for debugging or other exploration, e.g. time taken on the page.
blobs: Use this for large binaries, e.g. audio recordings.

Once the psynet.nextPage function is called, PsyNet will navigate to a new page if the new page has a different session_id compared to the current page, otherwise it will update the page while preserving the ongoing Unity session, specifically updating psynet.page and triggering the JavaScript event pageUpdated in the window object.

Parameters:

title (str) – The title of the experiment to be rendered in the HTML title-tag of the page.
game_container_width (str) – The width of the game container, e.g. ‘960px’.
game_container_height (str) – The height of the game container, e.g. ‘600px’.
resources (str) –
The path to the directory containing the Unity files residing inside the “static” directory. The path should start with “/static” and should comply with following basic structure:

static/ ├── css/ └── scripts/

css: Contains stylesheets scripts: Contains JavaScript files
contents (dict) – A dictionary containing experiment specific data.
time_estimate (Optional[float]) – Time estimated for the page (seconds).
session_id (str) – If session_id is not None, then it must be a string. If two consecutive pages occur with the same session_id, then when it’s time to move to the second page, the browser will not navigate to a new page, but will instead update the JavaScript variable psynet.page with metadata for the new page, and will trigger an event called pageUpdated. This event can be listened for with JavaScript code like window.addEventListener(”pageUpdated”, …).
debug (bool) – Specifies if we are in debug mode and use unity-debug-page.html as template instead of the standard unity-page.html.
**kwargs – Further arguments to pass to psynet.timeline.Page.

metadata(**kwargs)[source]¶

Compiles metadata about the page or its response from the participant. This metadata will be merged with the default metadata object returned from the browser, with any duplicate terms overwritten.

Parameters:

**kwargs –

Keyword arguments, including:

raw_answer: The raw answer returned from the participant’s browser.
answer: The formatted answer.
metadata: The original metadata returned from the participant’s browser.

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

Returns:

dict – A dictionary of metadata.

class psynet.page.UnsuccessfulEndPage(failure_tags=None, **kwargs)[source]¶: Bases: PageMaker

class psynet.page.WaitPage(wait_time, content=None, **kwargs)[source]¶

Bases: Page

This page makes the user wait for a specified amount of time before automatically continuing to the next page.

Parameters:

wait_time (float) – Time that the user should wait.
content – Message to display to the participant while they wait. Default: “Please wait, the experiment should continue shortly…”
**kwargs – Further arguments to pass to psynet.timeline.Page.

get_bot_response(experiment, bot)[source]¶: 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)[source]¶

Compiles metadata about the page or its response from the participant. This metadata will be merged with the default metadata object returned from the browser, with any duplicate terms overwritten.

Parameters:

**kwargs –

Keyword arguments, including:

raw_answer: The raw answer returned from the participant’s browser.
answer: The formatted answer.
metadata: The original metadata returned from the participant’s browser.

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

Returns:

dict – A dictionary of metadata.

psynet.page.wait_while(condition, expected_wait, check_interval=2.0, max_wait_time=20.0, wait_page=<class 'psynet.page.WaitPage'>, log_message=None, fail_on_timeout=True)[source]¶

Displays the participant a waiting page while a given condition remains satisfied.

Parameters:

condition – The condition to be checked; the participant will keep waiting while this condition returns True. This argument should be a function receiving the following arguments: participant (corresponding to the current participant) and experiment (corresponding to the current experiments). If one of this arguments is not needed, it can be omitted from the argument list.
expected_wait (float) – How long the participant is likely to wait, in seconds.
check_interval (float) – How often should the browser check the condition, in seconds.
max_wait_time (float) – The participant’s maximum waiting time in seconds. Default: 20.0.
wait_page – The wait page that should be displayed to the participant; defaults to WaitPage.
log_message (Optional[str]) – Optional message to display in the log.
fail_on_timeout – Whether the participants should be failed when the max_loop_time is reached. Setting this to False will not return the UnsuccessfulEndPage when maximum time has elapsed but allow them to proceed to the next page.

Returns:

list – A list of test elts suitable for inclusion in a PsyNet timeline.

PageMaker¶

class psynet.timeline.PageMaker(function, time_estimate=None, accumulate_answers=False, label='page_maker')[source]¶

A page maker is defined by a function that is executed when the participant requests the relevant page.

Parameters:

function (Callable[..., Union[Elt, List[Elt], EltCollection]]) – A function that may take up to two arguments, named experiment and participant. These arguments correspond to instantiations of the class objects psynet.experiment.Experiment and psynet.participant.Participant respectively. The function should return either a single test element (e.g. psynet.timeline.Page, psynet.timeline.PageMaker, psynet.timeline.CodeBlock) or a list of such elements. Note that psynet.timeline.PageMaker objects can be nested arbitrarily deeply. Note also that, if the page maker returns multiple pages, then the function will be recomputed each time the participant progresses to the next page. This functionality can be used to make the latter pages depend on the earlier pages in the page maker.
time_estimate (Optional[float]) – Time estimated to complete the segment. This time estimate is used for predicting the overall length of the experiment and hence generating the progress bar. The actual time credit given to the participant is determined by time_estimate parameters provided to the pages generated by function. However, there is an exception provided for back-compatibility: if function generates a list containing solely psynet.timeline.Page or psynet.timeline.PageMaker objects, and if those objects are all missing time_estimate values, then these time_estimate values will be imputed by dividing the parent psynet.timeline.PageMaker’s time_estimate by the number of produced elements.

PreDeployRoutine¶

class psynet.timeline.PreDeployRoutine(label, function, args=None)[source]¶

Bases: NullElt

A timeline component that allows for the definition of tasks to be performed before deployment. It is possible to make database changes as part of these routines and these will be propagated to the deployed experiment.

Parameters:

label – A label describing the pre-deployment task.
function – The name of a function to be executed.
args – The arguments for the function to be executed.

Response¶

class psynet.timeline.Response(*args, **kwargs)[source]¶

Bases: _Response

A database-backed object that stores the participant’s response to a Page. By default, one such object is created each time the participant tries to advance to a new page.

answer¶: The participant’s answer, after formatting.

page_type¶

The type of page administered.

Type:: str

successful_validation¶

Whether the response validation was successful, allowing the participant to advance to the next page.

Type:: bool

client_ip_address¶

The participant’s IP address as reported by Flask.

Type:: str

creation_time¶: the time at which the Network was created.

details¶: a generic column for storing structured JSON data

failed¶: boolean indicating whether the Network has failed which prompts Dallinger to ignore it unless specified otherwise. Objects are usually failed to indicate something has gone wrong.

failed_reason¶: an optional reason the object was failed. If the object is failed as part of a cascading failure triggered from another object, the chain of objects will be captured in this field.

id¶: a unique number for every entry. 1, 2, 3 and so on…

property metadata¶: A dictionary of metadata associated with the Response object. Stored in the details field in the database.

property1¶: a generic column that can be used to store experiment-specific details in String form.

property2¶: a generic column that can be used to store experiment-specific details in String form.

property3¶: a generic column that can be used to store experiment-specific details in String form.

property4¶: a generic column that can be used to store experiment-specific details in String form.

property5¶: a generic column that can be used to store experiment-specific details in String form.

time_of_death¶: the time at which failing occurred

type¶

vars¶

Switch statements¶

psynet.timeline.switch(label, function, branches, fix_time_credit=False, bound_progress=True, log_chosen_branch=True, time_estimate=None)[source]¶

Selects a series of elts to display to the participant according to a certain condition.

Parameters:

label (str) – Internal label to assign to the construct.
function (Callable) – A function with up to two arguments named participant and experiment, that is executed once the participant reaches the corresponding part of the timeline, returning a key value with which to index branches.
branches (dict) – A dictionary indexed by the outputs of function; each value should correspond to an elt (or list of elts) that can be selected by function.
fix_time_credit (bool) – Whether participants should receive the same time credit irrespective of the branch taken. Defaults to False; if set to True, all participants receive the same credit, corresponding to the branch with the maximum time credit.
bound_progress (bool) – Whether the progress estimate should be ‘bound’ such that, whatever happens, when the participant exits the conditional construct, the progress estimate will be the same as if the participant had taken the branch with the maximum time credit. Defaults to True.
log_chosen_branch (bool) – Whether to keep a log of which participants took each branch; defaults to True.
time_estimate (float) – An optional time estimate to use for the switch construct. If not provided, the time estimate will be estimated by computing time estimates for all branches and taking the maximum.

Returns:

list – A list of elts that can be embedded in a timeline using psynet.timeline.join().

While loops¶

psynet.timeline.while_loop(label, condition, logic, expected_repetitions, max_loop_time=None, fix_time_credit=True, fail_on_timeout=True)[source]¶

Loops a series of elts while a given criterion is satisfied. The criterion function is evaluated once at the beginning of each loop.

Parameters:

label (str) – Internal label to assign to the construct.
condition (Callable) – A function with up to two arguments named participant and experiment, that is executed once the participant reaches the corresponding part of the timeline, returning a Boolean.
logic – An elt (or list of elts) to display while condition returns True.
expected_repetitions (int) – The number of times the loop is expected to be seen by a given participant. This doesn’t have to be completely accurate, but it is used for estimating the length of the total experiment.
max_loop_time (float) – The maximum time in seconds for staying in the loop. Once exceeded, the participant is is presented the UnsuccessfulEndPage. Default: None.
fix_time_credit – Whether participants should receive the same time credit irrespective of whether condition returns True or not; defaults to True, so that all participants receive the same credit.
fail_on_timeout – Whether the participants should be failed when the max_loop_time is reached. Setting this to False will not return the UnsuccessfulEndPage when maximum time has elapsed but allow them to proceed to the next page.

Returns:

list – A list of elts that can be embedded in a timeline using psynet.timeline.join().

Timeline¶

CodeBlock¶

Conditional statements¶

Page¶

Consent pages¶

PageMaker¶

PreDeployRoutine¶

Response¶

Switch statements¶

While loops¶