Basic Usage¶

Here, we learn the basic functionality of the prolific recruitment manager. A tool to automatically set up, run and pause a study on prolific. In an autora cycle this is typically used in conjunction with an experimentation manager, that manages the sending of conditions, retrieving of observations and setup of a study on a hosting service. The combination of a recruitment manager and an experimentation manager is called experiment-runner in autora terms.

Example¶

A prolific recruitment manager runs and over-watches the recruitment of participant on prolific and sends them to a website. The website is managed by a experimentation manager that sends condition to a database, that then get read by the website. The experimentation-manager also reads observation from the database and tells the recruitment manager when to stop or interupts if something unexpected happens.

In This Tutorial¶

Here we show how to set up a study, pause and unpause it.

In [ ]:

!pip install autora-experiment-runner-recruitment-manager-prolific

!pip install autora-experiment-runner-recruitment-manager-prolific

Import the relevant functions (we want to set up an experiment and have a way to pause/unpause it)

In [ ]:

from autora.experiment_runner.recruitment_manager.prolific import setup_study, start_study, pause_study

from autora.experiment_runner.recruitment_manager.prolific import setup_study, start_study, pause_study

Let's see, what arguments setup_study expects:

In [ ]:

help(setup_study)

help(setup_study)

Most arguments have a default option and in this example we'll leave them as they are, but we have to set 5 arguments: (1) name: This is the name the users on prolific will see (2) description: This is the description the users on prolific will see. (3) external_study_url: This is the link to the website were you host the experiment (for a detailed explanation on how to use Firebase to setup an online experiment visit: https://autoresearch.github.io/autora/ You can add url-variables here. There are special ones that will be set by prolific if specified: www.example-experiment.de?PROLIFIC_PID={{%PROLIFIC_PID%}}&STUDY_ID={{%STUDY_ID%}}&SESSION_ID={{%SESSION_ID%}} will set the Prolific_pid, study_id and session_id, and you can retrieve these variables in your website (4) estimated_completion_time: The time a participant will take on average to finish the experiment in minutes (this also sets a maximum allowed time and the reward if not specified differently) (5) prolific_token: The api token to your prolific account (you can get here: https://app.prolific.co/ (after you logged in, under settings)

In [ ]:

# Set up the parameters
name = 'Awesome AutoRA Study'
description = 'Descriptive description for the example study'
external_study_url = 'https://autoresearch.github.io/autora/'
estimated_completion_time = 5
prolific_token = "your-token-goes-in-here"

# Set up the parameters name = 'Awesome AutoRA Study' description = 'Descriptive description for the example study' external_study_url = 'https://autoresearch.github.io/autora/' estimated_completion_time = 5 prolific_token = "your-token-goes-in-here"

In [ ]:

study = setup_study(name = name,
                    description = description,
                    external_study_url= external_study_url,
                    estimated_completion_time =  estimated_completion_time,
                    prolific_token = prolific_token)

study = setup_study(name = name, description = description, external_study_url= external_study_url, estimated_completion_time = estimated_completion_time, prolific_token = prolific_token)

Checkout your prolific account. A new (paused) study with the provided name, description, url and completion time should have appeared.

The setup_study function returns a dictionary with the keys id and maximum allowed time. The id can be used as a handle to pause and unpause the study or to perform other actions. The maximum allowed time can be useful to set up timeouts to recruit new participants.

We can now start the study |Warning This will start the prolific recruitment!|

In [ ]:

start_study(study['id'], prolific_token)

start_study(study['id'], prolific_token)

And immediately pause the study again

In [ ]:

pause_study(study['id'], prolific_token)

pause_study(study['id'], prolific_token)