How to configure an experiment#
Alfred comes with a lot of sensible defaults, but can be flexibly configured by users.
Configuration relies on two files:
config.conf |
General configuration file (can be shared with others). |
secrets.conf |
Secret configuration like database credentials |
You simply place either of these files in your experiment directory. Alfred will find and read them automatically.
You need to fill only the fields that you need in your experiment, everything else will be covered by alfred automatically. For example, a config.conf might often look like this, with only the metadata defined:
[metdata]
exp_title = My title
author = my@email.adress
version = 1
exp_id = my_exp_id
Below, you find exhaustive commented versions of the default config.conf and secrets.conf files. They show and explain all available options.
- See Also:
More advanced configuration documentation can be found here: Advanced configuration. This includes
Defining your own config options
Defining default configuration across multiple experiments
config.conf#
########################################################################
# ALFRED DEFAULT CONFIGURATION #########################################
########################################################################
# SECTION: metadata ----------------------------------------------------
# Information about the experiment and its author.
# The information placed here is used in data saving, especially
# if you use your own mongo saving agent. The version is relevant
# for codebook data.
# ----------------------------------------------------------------------
[metadata]
title = default_title # Experiment title
author = default_author # Experiment author
version = 0.1 # Experiment version
exp_id = default_id # Experiment id. MUST be unique when using a mongo saving agent
# SECTION: general -----------------------------------------------------
# General settings that affect the whole experiment.
# ----------------------------------------------------------------------
[general]
open_browser = true # If true, alfred3 will try to open a browser window automcatically upon running an experiment
fullscreen = false # If true (and Chrome is available), the exp starts in fullscreen kiosk mode
# NOTE that this will only work if Chrome is not already running when you start the experiment
debug = false # If true, the exp starts in debug mode
admin = false # If true, the exp starts in admin mode
force_input = false # If true, input elements are force input by default
# SECTION: data --------------------------------------------------------
# General configuration for data collection and export.
# ----------------------------------------------------------------------
[data]
save_data = true # If true, the experiment will save data. If false, no data will be saved.
save_client_info = true # If true, information about participants' technichal setup will be saved
record_move_history = true # If true, information about partcipants' moves through the exp will be saved
export_exp_data = true # If true, the main exp data will be exported to csv after each *local* session
export_unlinked_data = true # If true, unlinked data will be exported to csv after each *local* session
export_codebook = true # If true, codebook data will be exported to csv after each *local* session
export_move_history = true # If true, movement data will be exported to csv after each *local* session
csv_directory = data # The directory (relative to exp directory) in which csv data files will be created
csv_delimiter = ; # The delimiter to use in exported csv files
save_directory = save # Directory for saving additional data, e.g. for counting sessions or randomization
# SECTION: navigation --------------------------------------------------
# Defines the texts on alfreds navigation buttons.
# ----------------------------------------------------------------------
[navigation]
forward = Weiter # Text on the "forward" button
backward = Zurück # Text on the "backward" button
finish = Beenden # Text on the "finish" button
# SECTION: layout ------------------------------------------------------
# General configuration of the appearance of your alfred experiment.
# ----------------------------------------------------------------------
[layout]
website_title = alfred3 Experiment # The title of the exp website (displayed for example as tab heading)
style = base # The basic color style to use
static_folder = _static # Name of directory (relative to exp directory) in which alfred looks for additional .css files for styling
responsive = true # Whether the alfred layout should adapt to participants' screen size automatically
responsive_width = 85, 75, 65, 55 # Comma-separated list of relative page widths on sm, md, lg, xl screen sizes
fixed_width = 920px # Page width if "responsive = false"
show_progress = true # If true, alfred will show a progress bar
fix_progress_top = true # If true, the progress bar will float at the top of the page when scrolling down
logo_text = # Text to display at the right border of the header
logo = _static/logo.png # Image to use as a logo
footer_text = # Text to use in the footer
header_color = # Color of the header bar (RGB, Hex, CSS color keywords)
background_color = # Background color (RGB, Hex, CSS color keywords)
# Settings for previews on social media services
preview_title = Online-Studie # Title MAX 35 characters
preview_description = Jetzt mitmachen und Teil der aktuellen Forschung werden. # Description MAX 155 characters
preview_image = # Full URL to custom preview image (2063 + 1080 px) (For Facebook and similar)
preview_image_small = # Full URL to custom preview image for small versions (300 x 200 px) (for WhatsApp an similar)
# SECTION: layout_base -------------------------------------------------
# Specific configuration for the layout style "base"
# ----------------------------------------------------------------------
[layout_base]
logo =
logo_text = alfred<br>A library for rapid experiment development
# SECTION: layout_goe --------------------------------------------------
# Specific configuration for the layout style "goe"
# ----------------------------------------------------------------------
[layout_goe]
logo =
logo_text = Georg-Elias-Müller Institut für Psychologie
# SECTION: webserver ---------------------------------------------------
# Webserver configuration
# QUESTIONING - the option might be removed in future releases
# ----------------------------------------------------------------------
[webserver]
basepath =
# SECTION: log ---------------------------------------------------------
# Configration of alfred's logging behavior.
# ----------------------------------------------------------------------
[log]
path = log # Directory in which to place the log file
level = info # Log level. Can be debug, info, warning, error, critical
# SECTION: debug -------------------------------------------------------
# Configuration of alfred's behavior in debug mode
# ----------------------------------------------------------------------
[debug]
set_default_values = true # If true, default values will be set automatically in debug mode
disable_minimum_display_time = true # If true, page's minimum display time behavior will be disabled
reduce_countdown = true # If true, the timeout of pages inheriting from TimeoutPage will be reduced
reduced_countdown_time = 1 # The time (in seconds) to which the countdown will be reduced if "reduce_countdown = true"
log_level_override = true # If true, the log_level defined in section [debug] will override the one from [log] in debug mode
log_level = debug # Log level in debug mode, if "log_level_override = true". Can be debug, info, warning, error, critical
disable_saving = false # If true, alfred will not save data in debug mode
code_in_templates = false # If true, CSS and JS will be inserted directly into the exp html document, making the .html file standalone
# Default values used in debug mode
Input_default = input
TextEntry_default = testText
TextArea_default = TextArea
RegEntry_default = testReg
NumberEntry_default = 10
SingleChoice_default = 1
SingleChoiceList_default = 1
SingleChoiceButtons_default = 1
SingleChoiceBar_default = 1
# debug default values for MultipleChoice type elements are determined by the elements
# SECTION: hints -------------------------------------------------------
# Default texts used by alfred to inform participants about
# events in an experiment
# ----------------------------------------------------------------------
[hints]
# hints for specific elements if they are force input and have not received input
no_inputTextEntry = Bitte geben Sie etwas ein.
no_inputTextArea = Bitte geben Sie etwas ein.
no_inputRegEntry = Bitte geben Sie etwas ein.
no_inputNumberEntry = Bitte geben Sie eine Zahl ein.
no_inputPasswordEntry = Bitte geben Sie etwas ein.
no_inputSingleChoice = Bitte wählen Sie eine Antwortmöglichkeit aus.
no_inputMultipleChoice = Bitte wählen Sie mindestens eine Option aus.
# Displayed if the exp realizes at the end of a section that a force input element was not filled out
# (only relevant if you customize a section's validation methods)
no_input_section_validation = Auf den {n} Seiten dieses Abschnitts fehlt mindestens eine Eingabe.
# Displayed if the input of a RegEntry element does not match the required expression
match_MatchEntry = Bitte überprüfen Sie Ihre Eingabe.
match_RegEntry = Bitte überprüfen Sie Ihre Eingabe.
match_EmailEntry = Bitte geben Sie eine valide Email-Adresse ein.
match_PasswordEntry = Falsches Passwort. Bitte versuchen Sie es erneut.
match_MultiplePasswordEntry = Falsches Passwort. Bitte versuchen Sie es erneut.
# A combination of the hints below is displayed if the input of a NumberEntry element does not fulfill the required conditions
match_NumberEntry = Bitte überprüfen Sie Ihre Eingabe. Sie können nur Zahlen eingeben.
min_NumberEntry = Das Minimum ist {min}.
max_NumberEntry = Das Maximum ist {max}.
ndecimals_NumberEntry = Sie können {ndecimals} Nachkommastellen verwenden.
decimal_signs_NumberEntry = Erlaubte Dezimaltrennzeichen sind: {decimal_signs}
# Displayed, if the number of selected options does not meet the requirements of a MultipleChoice type element
select_MultipleChoiceElement = Bitte wählen sie mindestens {min} und maximal {max} Felder aus.
# Page hints ---
# Displayed, if a jump is tried and the current page's section does not allow it
jumpfrom_forbidden = Von der aktuellen Seite kann nicht gesprungen werden.
# Displayed, if a jump is tried and the target page's section does not allow it
jumpto_forbidden = Die Zielseite kann nicht durch Sprung erreicht werden.
# Displayed, if a jump is tried and the target page cannot be found
jump_page_not_found = Die Zielseite wurde nicht gefunden.
# Displayed if a participants jumps over a page that must be shown
page_must_be_shown = Eine verpflichtende Seite wurde übersprungen.
# Displayed, if a participant tries to move forward before a page's minimum display time has expired
minimum_display_time = Sie können diese Seite frühestens nach {mdt} verlassen
# Final page
final_page_title = Experiment beendet
final_page_text = Das Experiment ist nun beendet.<br>Vielen Dank für die Teilnahme.
# SECTION: local_saving_agent ------------------------------------------
# Configuration of alfred's local saving agent
# ----------------------------------------------------------------------
[local_saving_agent]
use = true # If true, alfred will use this saving agent
assure_initialization = true # If true, alfred will abort in case initialization of this saving agent fails
path = save/exp # Directory path (relative to exp directory) in which to save the raw .json files
name = data # Name of the saving agent
level = 1 # Activation level, works like a threshold. Only tasks with higher level than the level given here will be saved. Usually, there's no need to change this setting. Don't touch it, if you don't fully understand it.
# SECTION: fallback_local_saving_agent ---------------------------------
# Configuration of a fallback local saving agent that takes effect, if
# the main local saving agent fails for any reason.
# ----------------------------------------------------------------------
[fallback_local_saving_agent]
use = false # same as for [local_saving_agent]
assure_initialization = false # same as for [local_saving_agent]
path = save/fallback_save1 # same as for [local_saving_agent]
name = data_fallback # same as for [local_saving_agent]
level = 1 # same as for [local_saving_agent]
# SECTION: level2_fallback_local_saving_agent --------------------------
# Configuration of a second fallback local saving agent that takes
# effect if both the main and the fallback agent fail.
# ----------------------------------------------------------------------
[level2_fallback_local_saving_agent]
use = false # same as for [local_saving_agent]
assure_initialization = false # same as for [local_saving_agent]
path = save/fallback_save2 # same as for [local_saving_agent]
name = data_level2_fallback # same as for [local_saving_agent]
level = 1 # same as for [local_saving_agent]
# SECTION: local_saving_agent_unlinked ---------------------------------
# Configuration of a saving agent for unlinked data
# ----------------------------------------------------------------------
[local_saving_agent_unlinked]
use = true # same as for [local_saving_agent]
path = save/unlinked # same as for [local_saving_agent]
name = local_unlinked # same as for [local_saving_agent]
level = 1
# If true, values (not variable names) saved by this agent will be encrypted.
# For save encryption, you must define a secret encryption
# key in secrets.conf or an environment variable. If you don't define
# an encryption key, alfred will raise an error when encryption is tried
encrypt = false
decrypt_csv_export = true # If true, encrypted .json files will be decrypted upon export to csv
# SECTION: failure_local_saving_agent ----------------------------------
# Configuration of a last-resort failsage local saving agent. This one
# takes effect, if all other options are exhausted
# ----------------------------------------------------------------------
[failure_local_saving_agent]
use = true # same as for [local_saving_agent]
path = save/failure_save # same as for [local_saving_agent]
name = failure_save # same as for [local_saving_agent]
assure_initialization = true # same as for [local_saving_agent]
level = 1 # same as for [local_saving_agent]
# SECTION: mortimer_specific -------------------------------------------
# Configuration settings that are overwritten by mortimer, if the
# experiment runs on mortimer. No need to alter these manually.
# ----------------------------------------------------------------------
[mortimer_specific]
session_id =
runs_on_mortimer = false
secrets.conf#
########################################################################
# ALFRED DEFAULT SECRETS ###############################################
########################################################################
# The secrets.conf is intended as your
# SECTION: flask -------------------------------------------------------
# General settings for the flask server used to run alfred experiments
# ----------------------------------------------------------------------
[flask]
secret_key = # Secret key for flask's session. If none is provided here, a random secret key will be generated automatically.
[general]
adminpass_lvl1 = # password for admin mode level 1
adminpass_lvl2 = # password for admin mode level 2
adminpass_lvl3 = # password for admin mode level 3
# SECTION: encryption --------------------------------------------------
# Encryption settings
# ----------------------------------------------------------------------
[encryption]
key = # Key used for symmetric encryption in alfred. Must be a valid fernet key. See documentation of alfred3.experiment.ExperimentSession.encrypt for more information on how to generate a key.
# SECTION: mongo_saving_agent ------------------------------------------
# Configuration of a saving agent that saves data to a MongoDB
# Authentication is conducted through the pymongo API.
# See https://pymongo.readthedocs.io/en/stable/
# for more information on pymongo.
# ----------------------------------------------------------------------
[mongo_saving_agent]
mock = false
use = false # If true, alfred will use this saving agent
name = mongo # Name of the saving agent
assure_initialization = true # If true, alfred will abort in case initialization of this saving agent fails
level = 1 # Activation level, works like a threshold. Only tasks with higher level than the level given here will be saved. Usually, there's no need to change this setting. Don't touch it, if you don't fully understand it.
user = # username for authentication on database
password = # password for authentication
host = # host adress of database
port = # port on which to communicate with database
database = alfred # name of the actual database
collection = # name of the document collection to use in the database
misc_collection = # name of the document collection to use for miscellaneous data alongside this saving agent.
# Miscellaneous data is mainly administrative, for example, data neede for
# efficient list randomization.
auth_source = alfred # name of the authentication database
use_ssl = false # If true, alfred will communicate with the database via ssl/tls. In this case, a CA file is needed
ca_file_path = # A file containing a single or a bundle of “certification authority” certificates, which are used to validate certificates passed from the other end of the connection.
# SECTION: fallback_mongo_saving_agent ---------------------------------
# Configuration of a fallback mongo saving agent that takes effect, if
# the main mongo saving agent fails for any reason.
# ----------------------------------------------------------------------
[fallback_mongo_saving_agent]
mock = false
use = false # same as for [mongo_saving_agent]
name = mongo_fallback # same as for [mongo_saving_agent]
assure_initialization = true # same as for [mongo_saving_agent]
level = 99 # same as for [mongo_saving_agent]
user = # same as for [mongo_saving_agent]
password = # same as for [mongo_saving_agent]
host = # same as for [mongo_saving_agent]
database = # same as for [mongo_saving_agent]
collection = # same as for [mongo_saving_agent]
use_ssl = false # same as for [mongo_saving_agent]
ca_file_path = # same as for [mongo_saving_agent]
# SECTION: mongo_saving_agent_unlinked ---------------------------------
# Configuration of a saving agent for saving unlinked data.
# This saving agent will be used by pages derived from UnlinkedDataPage.
#
# NOTE: You only need to enter information that differs from the
# main mongo saving agent, so it might be enough to set 'use = true' and
# 'collection = unlinked', if you use a different collection on the
# same database.
#
# You can define all options that are offered by mongo_saving_agent,
# but should not define options here without assigning a value. That
# would break the inheritance mechanism.
# ----------------------------------------------------------------------
[mongo_saving_agent_unlinked]
mock = false
encrypt = false # If true, values will be encrypted before they are written to the database. A valid encryption key must be defined for this option to work.
use = false # same as for [mongo_saving_agent]
name = mongo_unlinked # same as for [mongo_saving_agent]