WaitingPage#

class alfred3_interact.page.WaitingPage(*args, wait_msg: Optional[str] = None, wait_timeout: Optional[int] = None, wait_sleep_time: Optional[int] = None, wait_timeout_page: Optional[Page] = None, wait_exception_page: Optional[Page] = None, **kwargs)[source]#

Bases: NoNavigationPage

A page that provides a waiting screen for synchronization in interactive experiments.

This page is must be derived. You define the condition by defining the wait_for() method. The page has a default design, set in on_exp_access() - you can safely redefine this method to use your own design.

Once the wait_for() method returns a True-like value (i.e., a value for which bool(value) == True holds), the WaitingPage will proceed to the next page automatically.

Important

The wait_for() method must return a value, otherwise you will always run into the timeout.

Parameters

wait_msg (str) – Text to be displayed in the default layout. Defaults to None, in which case the text is “Waiting for other group members.” Can be defined as a class attribute.
wait_timeout (int) – Maximum waiting time in seconds. If wait_for does not return a True-like value within waiting time, the experiment session is aborted. Defaults to None, in which case the timeout is 60 * 20, i.e. 20 minutes. Can be defined as a class attribute.
wait_sleep_time (int) – Number of seconds in between two internal calls to wait_for(). Defaults to None, in which case a call will be made every two seconds. Can be defined as a class attribute.
wait_timeout_page (alfred3.Page) – A custom page to be displayed in case of a waiting timeout. Defaults to an instance of DefaultWaitingTimeoutPage. Can be defined as a class attribute.
wait_exception_page (alfred3.Page) – A custom page to be displayed in case of an exception during waiting. Defaults to an instance of DefaultWaitingExceptionPage. Can be defined as a class attribute.

**kwargs –

Inherited keyword arguments

background_color (str)	A color to be used for the background of this page. Can be any color value understood by CSS, including hex and RGB. Can be defined as a class attribute.
fixed_width (str)	Custom value for defining a fixed width of the page. Only takes effect, if the experiment is set to generally operate with a fixed page width in config.conf (option responsive in section layout must be false). Must be a string including a unit, e.g. 900px. Can be defined as a class attribute.
footer_text (str)	Page-specific footer text. Replaces the `footer_text` defined in `config.conf`. Can be defined as a class attribute.
header_color (str)	A color to be used for the header of this page. Can be any color value understood by CSS, including hex and RGB. Can be defined as a class attribute.
minimum_display_time (str)	The minimal amount of time that the page must be displayed, before participants can move to the next page. Must be specified as a string with a unit of s (for seconds), or m (for minutes), for instance 30s. Defaults to None. Can be defined as a class attribute.
minimum_display_time_msg (str)	A page-specific message to be displayed, if participants try to move forward before the minimum display time has expired. Defaults to None, which means that the default message defined in config.conf will be used. Can be defined as a class attribute.
name (str)	Name of the member. Must be unique throughout the experiment. Can be defined as a class attribute. When you write a page or section in class style, the name can be inferred from the class name and does not need to be defined explicitly again. If a name is defined explicitly as a class attribute, that name is used.
prefix_element_names (bool)	If True, the names of all input elements on this page will be prefixed with the page name. Defaults to None. Can be defined as a class attribute.
progress (int, float)	Can be used to manually determine the level of experiment progress displayed in the experiments progress bar. Can be an int or float between 0 and 100. Defaults to None, which means that the experiment-wide setting is used (see `ExperimentSession.progress_bar`). Can be defined as a class attribute.
responsive_width (str)	Custom values for definig the width of the page in percent of the screen width. Only takes effect, if the option responsive in section layout is true (which is the default). Must be a single string with 1 to 4 relative widths separated by commas, e.g. 60%, 50%. The first value refers to small (sm) screens, the following values to the next bigger ones. Extra small screens like mobile phones will always get 100% width. If the string contains less than four values, the last value will be used for all screens from that size on upward. The sizes are taken from Bootstrap and correspond to the five width attributes of a `RowLayout`. By default, responsive widths are - 100% on extra small screens (below 576px, not modifiable) - 85% on small screens (576-767px, think of tablets) - 75% on medium screens (768-991px, think of small laptops) - 65% on large screens (992-1199px) - 55% on extra large screens (1200px and larger) Can be defined as a class attribute.
subtitle (str)	Subtitle of the member. Can be defined as a class attribute.
title (str)	Title of the member. Can be defined as a class attribute.
vargs (dict)	A dictionary that can be used to pass additional arguments to the page. The arguments are then available as an instance attribute. As a special feature, the instance attribute allows you to access the values of the dictionary not only via the usual square-bracket notation, but also via dot-notation. This argument fulfills a similar function as `**kwargs` do sometimes, but it makes sure that user-defined additional arguments will not collide with inherited keywords arguments. Can be defined as a class attribute.

Examples

How to use the WaitingPage for matching:

import alfred3 as al
import alfred3_interact as ali

exp = al.Experiment()

@exp.setup
def setup(exp):
    spec = ali.ParallelSpec("a", "b", nslots=10, name="spec1")
    exp.plugins.mm = ali.MatchMaker(spec, exp=exp)

@exp.member
class Match(ali.WaitingPage):

    def wait_for(self):
        group = self.exp.plugins.mm.match()
        self.exp.plugins.group = group
        return True

@exp.member
class Success(al.Page):

    def on_first_show(self):
        group = self.exp.plugins.group
        role = group.me.role

        self += al.Text(f"Successfully matched to role: {role}")

The example demonstrates how to use the waiting page in an ongoing experiment to wait until a group member has proceeded to a certain point in the experiment (more precisely, until a group member has filled a certain input element in this case):

import alfred3 as al
import alfred3_interact as ali

exp = al.Experiment()

@exp.setup
def setup(exp):
    spec = ali.ParallelSpec("a", "b", nslots=10, name="spec1")
    exp.plugins.mm = ali.MatchMaker(spec, exp=exp)


@exp.member
class Match(ali.WaitingPage):

    def wait_for(self):
        group = self.exp.plugins.mm.match()
        self.exp.plugins.group = group
        return True


@exp.member
class InputPage(al.Page):

    def on_exp_access(self):
        self += al.TextEntry(leftlab="Enter text", name="el1", force_input=True)


@exp.member
class Sync1(ali.WaitingPage):

    def wait_for(self):
        you = self.exp.plugins.group.you
        return you.values.get("el1", False)


@exp.member
class SyncSuccess(al.Page):

    def on_first_show(self):
        self += al.Text("Successfully synced.")

Methods

`added_to_experiment`	Informs the member that it was added to an experiment session.
`added_to_section`	Informs the member that it was added to a section.
`append`	Appends a variable number of elements to the page.
`close`	Closes the page.
`custom_move`	Hook for defining a page's own movement behavior, executed every time a movement from the page takes place, before `on_first_hide()` and `on_each_hide()`.
`durations`	Iterates over the visit durations for this page.
`first_duration`	Returns the duration of the last visit to this page in the current session in seconds.
`last_duration`	Returns the duration of the last visit to this page in the current session in seconds.
`on_close`	Executed once, when the page is closed, before data saving.
`on_each_hide`	Executed every time the page is hidden, before closing it and before saving data, but after executing `on_first_hide()`.
`on_each_show`	Executed every time the page is shown, after executing `on_first_show()`.
`on_exp_access`	Executed once, when the `ExperimentSession` becomes available to the page.
`on_expire`
`on_first_hide`	Executed once, when the page is hidden for the first time, before executing `on_each_hide()`.
`on_first_show`	Executed once, when the page is shown for the first time, before executing `on_each_show()`.
`position_in_section`	Returns the position of this page or section inside its parent section, starting at 1.
`prepare_web_widget`	Hook for computations for preparing a page for display.
`save_data`	Saves current experiment data.
`showif`	Hook for controlling whether a page or section should be shown.
`uptree`	List of the parent section and the grandparent sections (recursive).
`validate`	Returns True, if the validation checks pass, False otherwise.
`visible`	Returns the subset of members in the given attribute that should be shown.
`wait_for`	Once this method returns True, the page automatically forwards participants to the next page.

Attributes

`all_elements`	Alias for `elements`.
`all_input_elements`	Alias for `input_elements`.
`background_color`	A color to be used for the background of this page.
`data`	Returns a dict of data for all input elements on the page.
`elements`	Dictionary of elements belonging to this page.
`exp`	The `ExperimentSession` to which this member belongs.
`experiment`	The `ExperimentSession` to which this member belongs.
`expiration_time`	Point in time at which the waiting page expires in seconds since epoch.
`expired`	True if the page has exceeded its maximum waiting time.
`filled_input_elements`	Dict of all input elements on this page with non-empty data attribute.
`fixed_width`	Custom value for defining a fixed width of the page.
`footer_text`	Page-specific footer text.
`has_been_shown`	Returns True, if the page has been displayed in the ongoing experiment session.
`header_color`	A color to be used for the header of this page.
`input_elements`	Dict of all input elements on this page.
`instance_log`	If True, the member will spawn a logger that can be configured individually for each instance
`is_closed`	Returns True, if the page is closed.
`minimum_display_time`	Minimal amount of time that a page must be displayed before participants can move forward.
`minimum_display_time_msg`	Message that is displayed if participants try to leave a page before the minimum display time is up.
`must_be_shown`	False, if the experiment tolerates skipping this page entirely.
`name`	Unique name of the member.
`parent`	Alias for `section`.
`parent_name`	Name of the parent section.
`passed_time`
`prefix_element_names`	If True, the names of all elements added to this page will receive a prefix of the page's name.
`progress`	Can be used to manually determine to level of experiment progress displayed in the experiment's progress bar.
`responsive_width`	Custom values for definig the width of the page in percent of the screen width.
`section`	The member's parent section.
`short_tree`	Short version of `tree`, without the `_root._content` part that is the same for all members.
`should_be_shown`	Boolean, indicating whether a page should be shown.
`subtitle`	Page subtitle (str).
`tag`	Alias for `name`, included under this name for backwards compatibility.
`title`	Page title
`tree`	A single string, indicating the member's position in the experiment.
`uid`	Alias for `name`, included under this name for backwards compatibility.
`unlinked_data`	Returns an empty dict for 'normal' pages and the input data for unlinked pages.
`updated_elements`	Returns a dict of all elements on the page that already have access to the experiment session.
`vargs`	A dictionary of additional arguments passed on the class upon initialization.
`wait_exception_page`	Abort page to be displayed on other exceptions during waiting
`wait_msg`	Text to be displayed in the default layout.
`wait_sleep_time`	Number of seconds in between two internal calls to `wait_for()`.
`wait_timeout`	Maximum waiting time in seconds.
`wait_timeout_page`	Abort page to be displayed on timeout
`waiting_start`	Time of waiting start in seconds since epoch We are not using the first show time here, because we want to try to synchronize the waiting timeout with the displayed Counter as best as possible.

WaitingPage

Contents

WaitingPage#