alfred3 package¶

alfred3.element module¶

Provides element classes for adding content to pages.

All elements are derived from the base Element. There are currently four kinds of elements:

Display elements are used to present something
Input elements are used to allow subject input
Action elements trigger some kind of action, when they are interacted with.
Utility elements are used for different kinds of handy things

The following tables give an overview over all of these elements.

Element bases¶
Element Name	Description
`Element`	Basis for all elements
`LabelledElement`	Basis for elements with labels
`InputElement`	Basis for elements with user input
`RowLayout`	Basis for horizontal layouting

Display Elements¶
Element Name	Description
`Html`	Displays html code
`Text`	Displays text. Can render Markdown, html, and emoji shortcodes
`CodeBlock`	Displays code with syntax highlighting
`Image`	Displays an image
`Audio`	Plays sound
`Video`	Displays a video
`MatPlot`	Displays a `matplotlib.figure.Figure`
`Hline`	Displays a horizontal line on the page
`ButtonLabels`	Additional labels for `SingleChoiceButtons` or `MultipleChoiceButtons`
`BarLabels`	Additional labels for `SingleChoiceBar` or `MultipleChoiceBar`

Input Elements¶
Element Name	Description
`TextEntry`	A simple text entry field
`TextArea`	A text area field for multiline input
`RegEntry`	TextEntry with input validation via regular expressions
`NumberEntry`	TextEntry that specializes on numbers
`SingleChoice`	Radiobuttons, allowing selection of one out of several options
`SingleChoiceList`	Dropdown list, allowing selection of one out of several options
`SingleChoiceButtons`	Buttons, allowing selection of one out of several options
`SingleChoiceBar`	Toolbar of SingleChoiceButtons
`MultipleChoice`	Checkboxes, allowing selection of multiple options
`MultipleChoiceButtons`	Buttons, allowing selection of multiple options
`MultipleChoiceBar`	Toolbar of MultipleChoiceButtons
`MultipleChoiceList`	Scrollable list, allowing selection of multiple options

Action Elements¶
Element Name	Description
`SubmittingButtons`	Buttons which trigger the experiment to move forward on click
`JumpButtons`	Buttons which trigger the experiment to jump to a specific page on click
`DynamicJumpButtons`	JumpButtons, which get their target page dynamically from another element on the same page
`JumpList`	Dropbown of pages for jumping

Utility Elements¶
Element Name	Description
`Row`	Aligns multiple elements horizontally in a row
`Stack`	Stacks multiple elements in a row on top of each other. Think “multi-row-cell”
`VerticalSpace`	Adds vertical space
`Style`	Adds CSS code to a page
`JavaScript`	Adds JavaScript code to a page
`HideNavigation`	Removes to navigation buttons from a page
`WebExitEnabler`	Turns the “Do you really want to leave?” dialogue upon closing of a page off
`Value`	Saves a value to the experiment data without displaying anything
`Data`	Alias for `Value`

alfred3.element.jinja_env = <jinja2.environment.Environment object>¶: jinja2.Environment, giving access to included jinja-templates.

class alfred3.element.RowLayout(ncols: int, valign_cols: List[str] = None, responsive: bool = True)¶

Bases: object

Provides layouting functionality for responsive horizontal positioning of elements.

Default behavior is to have equal-width columns with an automatic breakpoint on extra small screens (i.e. all columns get the bootstrap class ‘col-sm’ by default).

The layout’s width attributes can be accessed an changed to customize appearance. In this example, we change the width of the columns on screens of “small” and bigger width, so that we have narrow columns to the right and left (each taking up 2/12 of the available space), and one wide column (taking up 8/12 of the space) in the middle. On “extra small” screens, the columns will be stacked vertically and each take up the full width.

You can define widths for five breakpoints individually, allowing for fine-grained control (see attributes).

Parameters

ncols – Number of columns to arrange in a row.
valign_cols – List of vertical column alignments. Valid values are ‘auto’ (default), ‘top’, ‘center’, and ‘bottom’.
responsive – Boolean, indicating whether breakpoints should be responsive, or not.

Examples

layout = RowLayout(ncols=3) # 3 columns of equal width
layout.width_sm = [2, 8, 2]

ncols¶: Number of columns

responsive¶: Indicates whether breakpoints should be responsive, or not.

width_xs¶: List of column widths on screens of size ‘xs’ or bigger (<576px). Content must be integers between 1 and 12.

width_sm¶: List of column widths on screens of size ‘s’ or bigger (>=576px). Content must be integers between 1 and 12.

width_md¶: List of column widths on screens of size ‘md’ or bigger (>=768px). Content must be integers between 1 and 12.

width_lg¶: List of column widths on screens of size ‘lg’ or bigger (>=992px). Content must be integers between 1 and 12.

width_xl¶: List of column widths on screens of size ‘xl’ or bigger (>=1200px). Content must be integers between 1 and 12.

col_breaks(col: int) → str ¶

Returns the column breakpoints for a specific column as strings for use as bootstrap classes.

Parameters: col – Column index (starts at 0)

format_breaks(breaks: List[int], bp: str) → List[str]¶

Takes a list of column sizes (in integers from 1 to 12) and returns a corresponding list of formatted Bootstrap column classes.

Parameters

breaks – List of integers, indicating the breakpoints.
bp – Specifies the relevant bootstrap breakpoint. (xs, sm, md, lg, or xl).

property valign_cols¶

Vertical column alignments.

Valid values are ‘auto’ (default), ‘top’, ‘center’, and ‘bottom’. Can be specified upon initalization or modified as instance attribute.

Each element of the list refers to one column. If it contains fewer elements than the number of columns, the last entry of the list will be used as value for the unreferenced columns.

Examples

All columns of the following layout will be aligned to the bottom of the row (specified upon initialization):

layout1 = RowLayout(ncols=3, valign_cols=["bottom"])

The first column of the following layout will be aligned top, the 2nd and 3rd columns will be aligned bottom (specified after initialization):

layout2 = RowLayout(ncols=3)
layout2.valign_cols = ["top", "bottom"]

Type: List[str]

class alfred3.element.Element(name: str = None, font_size: Union[str, int] = None, align: str = 'left', width: str = 'full', height: str = None, position: str = 'center', showif: dict = None, instance_level_logging: bool = False)¶

Bases: object

Element baseclass, providing basic functionality for all elements.

Parameters

name – Name of the element. This should be a unique identifier. It will be used to identify the corresponding data in the final data set.
font_size – Font size for text in the element. Can be ‘normal’ (default), ‘big’, ‘huge’, or an integer giving the desired size in pt.
align – Horizontal alignment of text in the element. Does not usually apply to labels. Think of it as an alignment that applies to the innermost layer of an element (while labels are generally located at outer layers). See LabelledElement for more on labelled elements. Can be ‘left’ (default), ‘center’, ‘right’, or ‘justify’.
position – Horizontal position of the full element on the page. Values can be ‘left’, ‘center’ (default), ‘end’, or any valid value for the justify-content flexbox utility. Takes effect only, when the element is not full-width.
width – Defines the horizontal width of the element from small screens upwards. It’s always full-width on extra small screens. Possible values are ‘narrow’, ‘medium’, ‘wide’, and ‘full’. For more detailed control, you can define the element_width attribute.
height – Vertical height of the element’s display area. Supply a string with a unit, e.g. “80px”. Usually, the default is fine. For adding vertical space to a page, you should prefer the VerticalSpace element, as it is sematically more clear.
showif – A dictionary, defining conditions that must be met for the element to be shown. The conditions take the form of key-value pairs, where each key is an element name and the value is the required input. See showif for details.
instance_level_logging – If True, the element will use an instance-specific logger, thereby allowing detailed fine- tuning of its logging behavior.

See also

How to create a custom element

Notes

The Element does not have its own display. It is used only to inherit functionality.

base_template: jinja2.environment.Template = <Template 'Element.html.j2'>¶: Base template for the element, which will be used to hold the rendered element template. Gets rendered by web_widget

element_template: jinja2.environment.Template = None¶: The element’s specific, inner template. Gets rendered by inner_html

page¶: The element’s parent Page (i.e. the page on which it is displayed).

exp¶: The Experiment to which this element belongs

experiment¶: Alias for exp

align¶: Alignment of inner element (does not apply to labels)

height¶: Vertical height of the element

instance_level_logging¶: Boolean flag, indicating whether the element should spawn its own logger, or use the class-specific logger. Can be set to True to allow for very fine-grained logging. In most cases, it is fine to leave it at the default (False)

log¶: A QueuedLoggingInterface, offering logging through the methods debug, info, warning, error, exception, and log.

property showif¶

Conditions that have to be met for the element to be shown.

The showif dictionary can contain multiple conditions as key- value-pairs. The element will only be shown, if all conditions are met. You can use all names that show up in the main dataset. That includes:

The names of all input elements that were shown before the current page
The names of all input elements on the current page
The experiment metadata, including exp_condition, exp_start_time, and more. See Experiment.metadata

Note

If you wish to implement more sophisticated conditions (e.g. linking conditions with ‘or’ instead of ‘and’), you can do so by using if-statements in an on_show or on_each_show page-hook.

Those conditions will not work for elements on the same page though. If you want to create complex showif conditions depending on elements on the same page, you have to implement them in JavaScript yourself. See add_js() and JavaScript for information on how to add JavaScript.

Examples

This is a simple showif based on experiment condition. The text element in this example will only be shown to subjects in the condition “one”:

import alfred3 as al
exp = al.Experiment()

@exp.setup
def setup(exp):
    exp.condition = al.random_condition("one", "two")

@exp.member
class MyPage(al.Page):
    name = "my_page"

    def on_exp_access(self):
        self += al.Text("This is text", showif={"exp_condition": "one"})

This is a more complex condition using the hook method. The text element on page2 will only be show to subjects, if they spent more than 20 seconds on page1:

import alfred3 as al
exp = al.Experiment()
exp += al.Page(name="page1")

@exp.member
class SecondPage(al.Page):
    name = "page2"

    def on_first_show(self):
        if sum(self.exp.page1.durations) > 20:
            self += al.Text("This is text")

See also

Page hooks

Type: dict

property converted_width¶

List of bootstrap column widths at different screen sizes.

Converted from width.

Type: list

property width¶

Element width

Type: str

property position¶

Position of the whole element on the page.

Determines the element position, when an element is not full-width.

Type: str

property font_size¶

Font size

Type: int

property element_width¶

Returns a string of column width definitions.

Manually setting the width

The element width list can contain up to 5 width definitions, specified as integers from 1 to 12. The integers refer to the five breakbpoints in Bootstrap 4’s 12-column-grid system, i.e. [xs, sm, md, lg, xl]:

>>> element = Element()
>>> element.element_width = [12, 8, 8, 7, 6]
element.element_width
"col-12 col-sm-8 col-md-8 col-lg-7 col-xl-6"

Width resultion order

If there is no width defined for a certain screen size, the next smaller entry is used. For example, the following definition will lead to full width on extra small screens and 8/12 widths on all larger widths:

element = Element()
element.element_width = [12, 8]

To make an element full-width on extra small and small screens and half-width on medium, large and extra large screens, follow this example:

element = Element()
element.element_width = [12, 12, 6]

Type: str

property name¶

Unique identifier for the element.

The element name will be used to identify the corresponding input in the final dataset.

Type: str

property should_be_shown¶

Boolean, indicating whether the element is meant to be shown.

Evaluates all showif conditions. Can be set manually. Returns False, if the element’s parent page should not be shown.

Type: bool

property section¶: The direct parent section of this element’s page.

property tree¶

String, giving the exact position in the experiment.

The tree is composed of the names of all sections and the element’s page dots. Example for an element that belongs to a page “hello_world” that was added directly to the experiment:

_root._content.hello_world

_root and _content are basic sections that alfred always includes in an experiment.

Type: str

property short_tree¶

String, giving the exact position in the experiment.

This version of the tree omits the _root._content part that is the same for all elements.

Type: str

property css_code¶

A list of tuples, which contain a priority and CSS code.

Type: List[tuple]

property css_urls¶

A list of tuples, which contain a priority and an url pointing to CSS code.

Type: List[tuple]

property js_code¶

A list of tuples, which contain a priority and Javascript.

Type: List[tuple]

property js_urls¶

A list of tuples, which contain a priority and an url pointing to JavaScript.

Type: List[tuple]

property template_data¶

Dictionary of data to be passed on to jinja templates.

When deriving a new element class, you will often want to redefine this property to add template data. When doing so, remember to retrieve the basic template data with super():

import alfred3 as al

class NewElement(al.Element):

    @property
    def template_data(self):
        d = super().template_data
        d["my_value"] = "this is my value"

        return d    # don't forget to return the dictionary!

The call super().template_data applies the parent classes code to the current object. That way, you only need to define values that differ from the parent class.

Note

Be aware that, by default, the same template data will be passed to the respective templates when rendering inner_html / element_template and web_widget / base_template.

Type: dict

added_to_experiment(experiment)¶

Tells the element that it was added to an experiment.

The experiment is made available to the element, and the element’s logging interface initializes its experiment-specific logging.

This is also the place where the element’s name is checked for experiment-wide uniqueness.

Parameters: experiment – The alfred experiment to which the element was added.

added_to_page(page)¶

Tells the element that it was added to a page.

The page and the experiment are made available to the element.

Parameters: page – The page to which the element was added.

prepare_web_widget()¶

Hook for computations for preparing an element’s web widget.

This method is supposed to be overridden by derived elements if necessary.

property inner_html¶

Renders the element template element_template.

Hands over the data returned by template_data, renders the template and returns the resulting html code.

If no element_template is defined, None is returned. Usually, the inner html gets placed into the higher-level :attr: .base_template, when Element.web_widget gets called.

Returns: Inner html code for this element.
Return type: str

property web_widget¶

The element’s rendered html code for display on a page.

This is done by rendering the base_template with the template_data and injecting the inner_html into it.

Returns: The full html code for this element.
Return type: str

property css_class_element¶

Returns the name of the element’s CSS class.

On the webpage generated by alfred3, all elements reside in some sort of container which has a CSS class of the element’s css_class_element. The name is composed as the element’s class name, followed by -element.

Examples

This is a simplified illustration of the html structure of a text element. Let’s say, the element was instantiated with the name “example_text”. The element’s css_class_element will be Text-element:

>>> import alfred3 as al
>>> ex = Text("This is an example", name="example_text")
>>> ex.css_class_element
Text-element

The html code generated by this element is structured as follows

<div class="Text-element-container" id="example_text-container">
  ...
  <div class="Text-element" id="example_text">
    <p>This is an example</p>
  </div>
  ...
</div>

Note that the element receives two CSS classes and two IDs, one each for the outer container and one for the innermost layer. The outer container includes the element’s base template (e.g. Element.html, or LabelledElement.html), while the inner layer includes the specific element- template (e.g. TextElement.html).

property css_class_container¶

Returns the name the element container’s CSS class.

The class can be used for CSS styling.

See also

See css_class_element for details.

Type: str

add_css(code: str, priority: int = 10)¶

Adds CSS to the element.

This is most useful when writing new elements. To simply add element-related CSS code to a page, usually the CSS element is a better choice.

Parameters

code – Css code
priority – Can be used to influence the order in which code is added to the page. Sorting is ascending, i.e. the lowest numbers appear closest to the top of the page.

See also

The CSS element can be used to add generic CSS code to a page.

add_js(code: str, priority: int = 10)¶

Adds Javascript to the element.

This is most useful when writing new elements. To simply add element-related JavaScript code to a page, usually the JavaScript element is a better choice.

Parameters

code – Css code
priority – Can be used to influence the order in which code is added to the page. Sorting is ascending, i.e. the lowest numbers appear closest to the top of the page.

See also

The JavaScript element can be used to add generic JavsScript code to a page.

class alfred3.element.Row(*elements: alfred3.element.Element, valign_cols: List[str] = None, height: str = 'auto', name: str = None, showif: dict = None, elements_full_width: bool = True)¶

Bases: alfred3.element.Element

Allows you to arrange up to 12 elements in a row.

The row will arrange your elements using Bootstrap 4’s grid system and breakpoints, making the arrangement responsive to different screen sizes. You can customize the behavior of the row for five different screen sizes (Bootstrap 4’s default break points) with the width attributes of its layout attribute.

If you don’t specify breakpoints manually via the layout attribute, the columns will default to equal width and wrap on breakpoints automatically.

Parameters

elements – The elements that you want to arrange in a row.
valign_cols – List of vertical column alignments. Valid values are ‘auto’ (default), ‘top’, ‘center’, and ‘bottom’. The elements of the list correspond to the row’s columns. See RowLayout.valign_cols
height – Custom row height (with unit, e.g. ‘100px’).
elements_full_width – A switch, telling the row whether you wish it to resize all elements in it to full-width (default: True). This switch exists, because some elements might default to a smaller width, but when using them in a Row, you usually want them to span the full width of their column.

Notes

CSS-class: row-element

In Bootstrap’s grid, the horizontal space is divided into 12 equally wide units. You can define the horizontal width of a column by assigning it a number of those units. A column of width 12 will take up all available horizontal space, other columns will be placed below such a full-width column.

You can define the column width for each of five breakpoints separately. The definition will be valid for screens of the respective size up to the next breakpoint.

See https://getbootstrap.com/docs/4.5/layout/grid/#grid-options for detailed documentation of how Bootstrap’s breakpoints work.

Examples

A minimal experiment with a row:

import alfred3 as al
exp = al.Experiment()

@exp.member
class HelloWorld(al.Page):
    name = "hello_world"

    def on_exp_access(self):
        el1 = al.Text("text")
        el2 = al.TextEntry(toplab="lab", name="example")

        self += al.Row(el1, el2)

The arrangement will look like this:

|=========|========|
|   el1   |  el2   |
|=========|========|

elements¶: List of the elements in this row

layout¶: An instance of RowLayout, used for layouting. You can use this attribute to finetune column widths via the width attributes (e.g. RowLayout.width_xs)

height¶: Custom row height (with unit, e.g. ‘100px’).

elements_full_width¶: If True, all elements will take up the full horizontal space of their column, regardless of the element’s Element.element_width and Element.width attributes.

added_to_page(page)¶

Tells the element that it was added to a page.

The page and the experiment are made available to the element.

Parameters: page – The page to which the element was added.

property template_data¶

Dictionary of data to be passed on to jinja templates.

When deriving a new element class, you will often want to redefine this property to add template data. When doing so, remember to retrieve the basic template data with super():

import alfred3 as al

class NewElement(al.Element):

    @property
    def template_data(self):
        d = super().template_data
        d["my_value"] = "this is my value"

        return d    # don't forget to return the dictionary!

The call super().template_data applies the parent classes code to the current object. That way, you only need to define values that differ from the parent class.

Note

Be aware that, by default, the same template data will be passed to the respective templates when rendering inner_html / element_template and web_widget / base_template.

Type: dict

class alfred3.element.Stack(*elements: alfred3.element.Element, **kwargs)¶

Bases: alfred3.element.Row

Stacks multiple elements on top of each other.

Stacks are intended for use in Rows. They allow you to flexibly arrange elements in a grid.

Parameters

*elements – The elements to stack.
**kwargs – Keyword arguments that are passend on to the parent class Row.

Notes

CSS-class: stack-element
Html element id: elid-<name> (<name> is the Element.name attribute, defined at initialization.)

Examples

A minimal experiment with a stack in a row:

import alfred3 as al
exp = al.Experiment()

@exp.member
class HelloWorld(al.Page):
    name = "hello_world"

    def on_exp_access(self):
        el1 = al.Text("text")
        el2 = al.TextEntry(toplab="lab", name="example")
        el3 = al.Text("long text")

        self += al.Row(al.Stack(el1, el2), el3)

The arrangement will look like this:

|=========|========|
|   el1   |        |
|=========|  el3   |
|   el2   |        |
|=========|========|

class alfred3.element.VerticalSpace(space: str = '1em')¶

Bases: alfred3.element.Element

The easiest way to add vertical space to a page.

Parameters: space – Desired space in any unit that is understood by a CSS margin (e.g. em, px, cm). Include the unit (e.g. ‘1em’).

Notes

CSS-class: vertical-space-element

Examples

Example of vertical space added between two text elements:

import alfred3 as al
exp = al.Experiment()

@exp.member
class HelloWorld(al.Page):
    name = "hello_world"

    def on_exp_access(self):
        self += al.Text("Element 1")
        self += al.VerticalSpace("100px")
        self += al.Text("Element 2")

class alfred3.element.Style(code: str = None, url: str = None, path: str = None, priority: int = 10)¶

Bases: alfred3.element.Element

Adds CSS code to a page.

CSS styling can be used to change the appearance of page or individual elements.

Notes

A style is added to a specific page, and thus only affects the layout of that page. To change the appearance of the whole experiment, you can define your styles in a .css file in your experiment directory and reference it in the config.conf in the option style of the section layout.

See also

How to reference a CSS file in the config.conf
CSS classes and element IDs of alfred3 elements

class alfred3.element.HideNavigation¶

Bases: alfred3.element.Style

Removes the forward/backward/finish navigation buttons from a page.

See also

Using JumpButtons and JumpList, you can add custom navigation elements to a page.
By defining the Page.custom_move() method on a page, you can implement highly customized movement behavior.

class alfred3.element.JavaScript(code: str = None, url: str = None, path: str = None, priority: int = 10)¶

Bases: alfred3.element.Element

Adds JavaScript to a page.

Javascript can be used to implement dynamic behavior on the client side.

See also

CSS classes and IDs of alfred3 elements.

class alfred3.element.WebExitEnabler¶

Bases: alfred3.element.JavaScript

Removes the “Do you really want to leave?” popup upon closing a page.

By default, subjects are asked to confirm their desire to leave a running experiment. You can turn off this behavior by adding this element to a page.

class alfred3.element.Html(html: str = None, path: Union[pathlib.Path, str] = None, **element_args)¶

Bases: alfred3.element.Element

Displays html code on a page.

Parameters

html – Html to be displayed.
path – Filepath to a file with html code (relative to the experiment directory).
**kwargs – Keyword arguments passed to the parent class Element.

Notes

CSS-class: html-element

This works very similar to Text. The most notable difference is that the Text element expects markdown, and therefore generally renders input text in a <p> tag. This is not always desirable for custom html, because it adds a margin at the bottom of the text.

The Html element renders neither markdown, nor emoji shortcodes.

Examples

Adding a simple div to the experiment:

import alfred3 as al
exp = al.Experiment()

@exp.member
class HelloWorld(al.Page):
    name = "hello_world"

    def on_exp_access(self):
        self += al.Html("<div id='mydiv'>Text in div</div>")

property html_code¶

The element’s html code

Type: str

class alfred3.element.Text(text: str = None, path: Union[pathlib.Path, str] = None, width: str = None, emojize: bool = True, **kwargs)¶

Bases: alfred3.element.Element

Displays text.

You can use GitHub-flavored Markdown syntax and common emoji shortcodes . Additionally, you can use raw html for advanced formatting.

Parameters

text – Text to be displayed.
path – Filepath to a textfile (relative to the experiment directory).
width – Element width. Usage is the same as in Element, but the Text element uses its own specific default, which ensures good readability in most cases on different screen sizes.
emojize – If True (default), emoji shortcodes in the text will be converted to unicode (i.e. emojis will be displayed).
**kwargs – Keyword arguments passed to the parent class Element.

Notes

CSS-class: text-element

Examples

A simple text element, including a 😊 (:blush:) emoji added to a page:

import alfred3 as al
exp = al.Experiment()

@exp.member
class HelloWorld(al.Page):
    name = "hello_world"

    def on_exp_access(self):
        self += al.Text("This is text :blush:")

path¶

Path to a textfile, if specified in the init

Type: pathlib.Path

emojize¶

Boolean flag, indicating whether emoji shortcodes should be interpreted

Type: bool

render_text() → str ¶

Renders the markdown and emoji shortcodes in text

Returns: Text rendered to html code
Return type: str

property text¶

The text to be displayed

Type: str

class alfred3.element.Hline(name: str = None, font_size: Union[str, int] = None, align: str = 'left', width: str = 'full', height: str = None, position: str = 'center', showif: dict = None, instance_level_logging: bool = False)¶

Bases: alfred3.element.Element

A simple horizontal line.

class alfred3.element.CodeBlock(text: str = None, path: Union[pathlib.Path, str] = None, lang: str = 'auto', width: str = 'full', **element_args)¶

Bases: alfred3.element.Text

A convenience element for displaying highlighted code.

Parameters

text – The code to be displayed.
path – path: Filepath to a textfile (relative to the experiment directory) from which to read code.
lang – The programming language to highlight 1 . Defaults to ‘auto’, which tries to auto-detect the right language.
**kwargs – Keyword arguments are passed on to the parent elements Text and Element

Notes

CSS-class: code-element

1: See https://prismjs.com/index.html#supported-languages for an overview of possible language codes. Note though that we may not support all possible languages.

class alfred3.element.Label(text, width='full', **kwargs)¶

Bases: alfred3.element.Text

A child of the Text element, serving as label for other elements.

Notes

CSS-class: label-element

layout¶

Layouting facility for controlling the column breaks and vertical alignment of the label. Gets set by LabelledElement automatically.

Type: RowLayout

layout_col¶: Tells the label which column of the layout it is

property col_breaks¶: The label’s breakpoints for diferent screen sizes.

property vertical_alignment¶: The label’s vertical alignment

class alfred3.element.LabelledElement(toplab: str = None, leftlab: str = None, rightlab: str = None, bottomlab: str = None, layout: List[int] = None, **kwargs)¶

Bases: alfred3.element.Element

An intermediate Element class which provides support for labels.

This class is used as a base class for all elements that come equipped with labels.

Parameters

toplab – String or instance of Label, which will be used to label the element.
leftlab – String or instance of Label, which will be used to label the element.
rightlab – String or instance of Label, which will be used to label the element.
bottomlab – String or instance of Label, which will be used to label the element.
layout – A list of integers, specifying the allocation of horizontal space between leftlab, main element widget and rightlab. Uses Bootstraps 12-column-grid, i.e. you can choose integers between 1 and 12.

property toplab¶

Label above of the main element widget.

Type: Label

property bottomlab¶

Label below of the main element widget.

Type: Label

property leftlab¶

Label to the left of the main element widget.

Type: Label

property rightlab¶

Label to the right of the main element widget.

Type: Label

property labels¶

Returns the labels in a single, nicely formatted string.

Type: str

class alfred3.element.ProgressBar(progress: Union[str, float, int] = 'auto', bar_height: str = '6px', show_text: bool = False, striped: bool = True, style: str = 'primary', animated: bool = False, round_corners: bool = False, **kwargs)¶

Bases: alfred3.element.LabelledElement

Displays a progress bar.

Parameters

progress – Can be either “auto”, or a number between 0 and 100. If “auto”, the progress is calculated from the current progress of the experiment. If a number is supplied, that number will be used as the progress to be displayed.
bar_height – Height of the progress bar. Supply a string with unit, e.g. “6px”.
text (show) – Indicates, whether the progress bar should include text with the current progress.
striped – Indicates, whether the progress bar shoulb be striped.
style – Determines the color of the progress bar. Possible values are “primary”, “secondary”, “info”, “success”, “warning”, “danger”, “light”, “dark”.
animated – Determines, whether a striped progress bar should be equipped with an animation.
round – Determines, whether the corners of the progress bar should be round.

See also

See ExperimentSession.progress_bar for more information on the experiment-wide progress bar.

Notes

If the argument show_text is True, the text’s appearance can be altered via CSS. It receives a class of “css_class_element-text” and an id of “name-text”. You can use the method add_css() to append fitting CSS to the bar (see examples).

Examples

Overriding the default experiment-wide progress bar:

import alfred3 as al
exp = al.Experiment()

@exp.setup
def setup(exp_session):
    exp_session.progress_bar = al.ProgressBar(show_text=True, bar_height="15px")

exp += al.Page(name="example_page")

Adding a progress bar as an element to a page:

import alfred3 as al
exp = al.Experiment()

@exp.member
class Example(al.Page):
    name = "example_page"

    def on_exp_access(self):
        self += al.ProgressBar()

Altering the progress bar text’s apperance, applied to the experiment-wide progress bar. Note that the experiment-wide progress bar always receives the name “progress_bar_”:

import alfred3 as al
exp = al.Experiment()

@exp.setup
def setup(exp):
    exp.progress_bar = al.ProgressBar(show_text=True, bar_height="15px")
    exp.progress_bar.add_css("#progress_bar_ {font-size: 12pt;}")

exp += al.Page(name="example_page")

class alfred3.element.InputElement(toplab: str = None, force_input: bool = False, default: Union[str, int, float] = None, description: str = None, disabled: bool = False, no_input_corrective_hint: str = None, **kwargs)¶

Bases: alfred3.element.LabelledElement

Base class for elements that allow data input.

Parameters

toplab – String or instance of Label, which will be used to label the element. The other labels (leftlab, rightlab, bottomlab) are supported aswell. Specify them as keyword arguments, not positional arguments.
force_input – If True, users can only progress to the next page if they enter data into this field. Note that a NoValidationSection or similar sections might overrule this setting.
default – Default value. Type depends on the element type.
description – An additional description of the element. This will show up in the alfred-generated codebook. It has no effect on the display of the experiment, as it only serves as a descriptor for humans.
no_input_corrective_hint – Hint to be displayed if force_input set to True and no user input registered. Defaults to the experiment-wide value specified in config.conf.
**kwargs – Further keyword arguments are passed on to the parent classes LabelledElement and Element.

Notes

The InputElement does not have its own display. It is used only to inherit functionality.

can_display_corrective_hints_in_line: bool = True¶: Boolean flag, indicating whether the element’s html template has a dedicated container for corrective hints. If False, corrective hints regarding this element will be placed in the general page-wide conainer for such hints.

description¶: Detailed description of this element to be added to the automatically generated codebook

show_corrective_hints¶: Flag, indicating whether corrective hints regarding this element should be shown.

hint_manager¶: A MessageManager, handling the corrective hints for this element.

disabled¶: A boolean flag, indicating whether the element is disabled A disabled input element is shown and displays its input value, but subjects cannot enter any data.

property corrective_hints¶

Shortcut for accessing the element’s corrective hints.

Yields: str – Corrective hint.

property debug_value¶

Value to be used as a default in debug mode.

This value is read from config.conf. Only used, if there is no dedicated default for this element.

Notes

The property searches for an option of the form <element_class>_debug in the section debug of config.conf. If no option is found, the return value is None

Type: Union[str, None]

property debug_enabled¶

Boolean flag, indicating whether debug mode is enabled and default values should be set.

Type: bool

property default¶

Default value of this element.

The data type can vary, depending on the element.

Type: Union[str, int, float]

property force_input¶

If True, subjects must fill this element to proceed.

Type: bool

validate_data() → bool ¶

Method for validation of input to the element.

Returns

True, if the input is correct and subjects may: proceed to the next page, False, if the input is not in the correct form.

Return type

bool

property no_input_hint¶

Hint for subjects, if they left a force_input field empty.

Type: str

property default_no_input_hint¶

Default hint if subject input is missing in force_entry elements.

This value is read from config.conf. Only used, if there is no dedicated no_input_hint for this element.

Notes

The property searches for an option of the form <element_class>_debug in the section debug of config.conf. If no option is found, the return value is “You need to enter something”.

Type: str

property input¶

Subject input to this element.

Type: str

property data¶

Dictionary of element data.

Includes the subject input and the element’s codebook_data.

Type: dict

set_data(d: dict)¶

Sets the input data.

Parameters: d – A dictionary with data.

Notes

The d dictionary will usually be a dictionary of all data collected on a page.

property codebook_data¶

Information about the element in dictionary form.

Type: dict

class alfred3.element.Data(value: Union[str, int, float], description: str = None, **kwargs)¶

Bases: alfred3.element.InputElement

Data can be used to save data without any display.

Example:

Data(value="test", name="mydata")

Parameters: value – The value that you want to save.

class alfred3.element.Value(value: Union[str, int, float], description: str = None, **kwargs)¶: Bases: alfred3.element.Data

class alfred3.element.TextEntry(toplab: str = None, prefix: str = None, suffix: str = None, placeholder: str = None, **kwargs)¶

Bases: alfred3.element.InputElement

Provides a text entry field.

Parameters

prefix – Prefix for the input field.
suffix – Suffix for the input field.
placeholder – Placeholder text, displayed inside the input field.
default – Default value.
**kwargs – Further keyword arguments that are passed on to the parent class InputElement.

validate_data()¶

Method for validation of input to the element.

Returns

True, if the input is correct and subjects may: proceed to the next page, False, if the input is not in the correct form.

Return type

bool

property codebook_data¶

Information about the element in dictionary form.

Type: dict

class alfred3.element.TextArea(toplab: str = None, nrows: int = 5, **kwargs)¶: Bases: alfred3.element.TextEntry

class alfred3.element.Choice(label: str = None, label_id: str = None, id: str = None, name: str = None, value: str = None, type: str = 'radio', checked: bool = False, css_class: str = None, disabled: bool = False)¶

Bases: object

Dataclass for managing choices.

class alfred3.element.ChoiceElement(*choice_labels, vertical: bool = False, shuffle: bool = False, align: str = 'center', **kwargs)¶

Bases: alfred3.element.InputElement, abc.ABC

prepare_web_widget()¶

Hook for computations for preparing an element’s web widget.

This method is supposed to be overridden by derived elements if necessary.

class alfred3.element.SingleChoice(*choice_labels, vertical: bool = False, shuffle: bool = False, align: str = 'center', **kwargs)¶

Bases: alfred3.element.ChoiceElement

property codebook_data¶

Information about the element in dictionary form.

Type: dict

class alfred3.element.SingleChoiceButtons(*choice_labels, button_width: Union[str, list] = 'equal', button_style: Union[str, list] = 'btn-outline-dark', button_corners: str = None, **kwargs)¶

Bases: alfred3.element.SingleChoice

“align” parameter has no effect in labels.

Keyword Arguments

button_width – Can be used to manually define the width of buttons. If you supply a single string, the same width will be applied to all buttons in the element. If you supply “auto”, button width will be determined automatically. You can also supply a list of specific widths for each individual button. You must specify a unit, e.g. ‘140px’. Defaults to “equal”.
button_style – Can be used for quick color-styling, using Bootstraps default color keywords: btn-primary, btn-secondary, btn-success, btn-info, btn-warning, btn-danger, btn-light, btn-dark. You can also use the “outline” variant to get outlined buttons (eg. “btn-outline-secondary”). If you specify a single string, this style is applied to all buttons in the element. If you supply a list, you can define individual styles for each button. If you supply a list that is shorter than the list of labels, the last style will be repeated for remaining buttons. Advanced user can supply their own CSS classes for button-styling.
button_toolbar – A boolean switch to toggle whether buttons should be layoutet as a connected toolbar (True), or as separate neighbouring buttons (False, default).
button_round_corners – A boolean switch to toggle whether buttons should be displayed with additionally rounded corners (True). Defaults to False.

prepare_web_widget()¶

Hook for computations for preparing an element’s web widget.

This method is supposed to be overridden by derived elements if necessary.

class alfred3.element.SingleChoiceBar(*choice_labels, button_width: Union[str, list] = 'equal', button_style: Union[str, list] = 'btn-outline-dark', button_corners: str = None, **kwargs)¶: Bases: alfred3.element.SingleChoiceButtons

class alfred3.element.MultipleChoice(*choice_labels, min: int = None, max: int = None, select_hint: str = None, default: Union[int, List[int]] = None, **kwargs)¶

Bases: alfred3.element.ChoiceElement

Checkboxes, allowing users to select multiple options.

Defining ‘min’, ‘max’ implies force_input.

validate_data()¶

Method for validation of input to the element.

Returns

True, if the input is correct and subjects may: proceed to the next page, False, if the input is not in the correct form.

Return type

bool

property data¶

Dictionary of element data.

Includes the subject input and the element’s codebook_data.

Type: dict

set_data(d)¶

Sets the input data.

Parameters: d – A dictionary with data.

Notes

The d dictionary will usually be a dictionary of all data collected on a page.

class alfred3.element.MultipleChoiceButtons(*choice_labels, min: int = None, max: int = None, select_hint: str = None, default: Union[int, List[int]] = None, **kwargs)¶

Bases: alfred3.element.MultipleChoice, alfred3.element.SingleChoiceButtons

Buttons, working as a MultipleChoice.

class alfred3.element.MultipleChoiceBar(*choice_labels, min: int = None, max: int = None, select_hint: str = None, default: Union[int, List[int]] = None, **kwargs)¶

Bases: alfred3.element.MultipleChoiceButtons

MultipleChoiceButtons, which are displayed as a toolbar instead of separate buttons.

class alfred3.element.ButtonLabels(*choice_labels, button_width: Union[str, list] = 'equal', button_style: Union[str, list] = 'btn-outline-dark', button_corners: str = None, **kwargs)¶

Bases: alfred3.element.SingleChoiceButtons

Disabled buttons. Example usecase might be additional labelling.

property data¶

Dictionary of element data.

Includes the subject input and the element’s codebook_data.

Type: dict

class alfred3.element.BarLabels(*choice_labels, button_width: Union[str, list] = 'equal', button_style: Union[str, list] = 'btn-outline-dark', button_corners: str = None, **kwargs)¶

Bases: alfred3.element.SingleChoiceBar

Disabled Button-Toolbar. Example usecase might be additional labelling.

property data¶

Dictionary of element data.

Includes the subject input and the element’s codebook_data.

Type: dict

class alfred3.element.SubmittingButtons(*choice_labels, button_style: Union[str, list] = 'btn-info', **kwargs)¶

Bases: alfred3.element.SingleChoiceButtons

SingleChoiceButtons that trigger submission of the current page on click.

class alfred3.element.JumpButtons(*choice_labels, button_style: Union[str, list] = 'btn-primary', **kwargs)¶

Bases: alfred3.element.SingleChoiceButtons

prepare_web_widget()¶

Hook for computations for preparing an element’s web widget.

This method is supposed to be overridden by derived elements if necessary.

validate_data()¶

Method for validation of input to the element.

Returns

True, if the input is correct and subjects may: proceed to the next page, False, if the input is not in the correct form.

Return type

bool

class alfred3.element.DynamicJumpButtons(*choice_labels, button_style: Union[str, list] = 'btn-primary', **kwargs)¶

Bases: alfred3.element.JumpButtons

validate_data()¶

Method for validation of input to the element.

Returns

True, if the input is correct and subjects may: proceed to the next page, False, if the input is not in the correct form.

Return type

bool

class alfred3.element.SingleChoiceList(*choice_labels, toplab: str = None, size: int = None, default: int = 1, **kwargs)¶: Bases: alfred3.element.SingleChoice

class alfred3.element.SelectPageList(toplab: str = None, scope: str = 'exp', check_jumpto: bool = True, check_jumpfrom: bool = True, show_all_in_scope: bool = True, **kwargs)¶

Bases: alfred3.element.SingleChoiceList

prepare_web_widget()¶

Hook for computations for preparing an element’s web widget.

This method is supposed to be overridden by derived elements if necessary.

set_data(d)¶

Sets the input data.

Parameters: d – A dictionary with data.

Notes

The d dictionary will usually be a dictionary of all data collected on a page.

class alfred3.element.JumpList(scope: str = 'exp', label: str = 'Jump', check_jumpto: bool = True, check_jumpfrom: bool = True, debugmode: bool = False, show_all_in_scope: bool = True, button_style: Union[str, list] = 'btn-dark', button_corners: str = 'normal', **kwargs)¶

Bases: alfred3.element.Row

prepare_web_widget()¶

Hook for computations for preparing an element’s web widget.

This method is supposed to be overridden by derived elements if necessary.

class alfred3.element.MultipleChoiceList(*choice_labels, toplab: str = None, size: int = None, **kwargs)¶

Bases: alfred3.element.MultipleChoice

set_data(d)¶

Sets the input data.

Parameters: d – A dictionary with data.

Notes

The d dictionary will usually be a dictionary of all data collected on a page.

class alfred3.element.Image(path: Union[str, pathlib.Path] = None, url: str = None, **kwargs)¶

Bases: alfred3.element.Element

added_to_experiment(experiment)¶

Tells the element that it was added to an experiment.

The experiment is made available to the element, and the element’s logging interface initializes its experiment-specific logging.

This is also the place where the element’s name is checked for experiment-wide uniqueness.

Parameters: experiment – The alfred experiment to which the element was added.

property template_data¶

Dictionary of data to be passed on to jinja templates.

When deriving a new element class, you will often want to redefine this property to add template data. When doing so, remember to retrieve the basic template data with super():

import alfred3 as al

class NewElement(al.Element):

    @property
    def template_data(self):
        d = super().template_data
        d["my_value"] = "this is my value"

        return d    # don't forget to return the dictionary!

The call super().template_data applies the parent classes code to the current object. That way, you only need to define values that differ from the parent class.

Note

Be aware that, by default, the same template data will be passed to the respective templates when rendering inner_html / element_template and web_widget / base_template.

Type: dict

class alfred3.element.Audio(path: Union[str, pathlib.Path] = None, url: str = None, controls: bool = True, autoplay: bool = False, loop: bool = False, align: str = 'center', **kwargs)¶

Bases: alfred3.element.Image

property template_data¶

Dictionary of data to be passed on to jinja templates.

When deriving a new element class, you will often want to redefine this property to add template data. When doing so, remember to retrieve the basic template data with super():

import alfred3 as al

class NewElement(al.Element):

    @property
    def template_data(self):
        d = super().template_data
        d["my_value"] = "this is my value"

        return d    # don't forget to return the dictionary!

The call super().template_data applies the parent classes code to the current object. That way, you only need to define values that differ from the parent class.

Note

Be aware that, by default, the same template data will be passed to the respective templates when rendering inner_html / element_template and web_widget / base_template.

Type: dict

class alfred3.element.Video(path: Union[str, pathlib.Path] = None, url: str = None, allow_fullscreen: bool = True, video_height: str = 'auto', video_width: str = '100%', **kwargs)¶

Bases: alfred3.element.Audio

Displays a video on the page.

Note

You can specify a filepath or a url as the source, but not both at the same time.

Parameters

path – Path to the video (relative to the experiment)
url – Url to the video
allow_fullscreen – Boolean, indicating whether users can enable fullscreen mode.
video_height – Video height in absolute pixels (without unit). Defaults to “auto”.
video_width – Video width in absolute pixels (without unit). Defaults to “100%”. It is recommended to use leave this parameter at the default value and use the general element parameter width for setting the width.
**kwargs –
The following keyword arguments are inherited from Audio:
- controls
- autoplay
- loop

property template_data¶

Dictionary of data to be passed on to jinja templates.

When deriving a new element class, you will often want to redefine this property to add template data. When doing so, remember to retrieve the basic template data with super():

import alfred3 as al

class NewElement(al.Element):

    @property
    def template_data(self):
        d = super().template_data
        d["my_value"] = "this is my value"

        return d    # don't forget to return the dictionary!

The call super().template_data applies the parent classes code to the current object. That way, you only need to define values that differ from the parent class.

Note

Be aware that, by default, the same template data will be passed to the respective templates when rendering inner_html / element_template and web_widget / base_template.

Type: dict

class alfred3.element.MatPlot(fig, align: str = 'center', **kwargs)¶

Bases: alfred3.element.Element

Displays a matplotlib.figure.Figure object.

Note

When plotting in alfred, you need to use the Object-oriented matplotlib API (https://matplotlib.org/3.3.3/api/index.html#the-object-oriented-api).

Parameters

fig (matplotlib.figure.Figure) – The figure to display.
align – Alignment of the figure (‘left’, ‘right’, or ‘center’). Defaults to ‘center’.

Examples

Example usage is illustrated here. Note that the example_plot` will only be displayed if it is added to a page.

>>> import alfred3 as al
>>> from matplotlib.figure import Figure

>>> fig = Figure()
>>> ax = fig.add_subplot()
>>> ax.plot(range(10))
>>> example_plot = al.MatPlot(fig=fig, name="example))
>>> example_plot
MatPlot(name="example")

prepare_web_widget()¶

Hook for computations for preparing an element’s web widget.

This method is supposed to be overridden by derived elements if necessary.

property template_data¶

Dictionary of data to be passed on to jinja templates.

When deriving a new element class, you will often want to redefine this property to add template data. When doing so, remember to retrieve the basic template data with super():

import alfred3 as al

class NewElement(al.Element):

    @property
    def template_data(self):
        d = super().template_data
        d["my_value"] = "this is my value"

        return d    # don't forget to return the dictionary!

The call super().template_data applies the parent classes code to the current object. That way, you only need to define values that differ from the parent class.

Note

Be aware that, by default, the same template data will be passed to the respective templates when rendering inner_html / element_template and web_widget / base_template.

Type: dict