prolific.api (version 0.5.2)

prolific_study: Prolific study

Description

Class that represents Prolific studies, such that they can be transferred to or from the Prolific API. This allows to create, review and update studies.
The fields and methods are available as in RefClass or S4 objects (see examples and the prolific.api package vignette).

API access to interact with the Prolific platform is done by using objects from the api_access class, i.e. prolific_studies are intended to be transferred as bodies in calls to the Prolific API (see examples).

Fields

id

(character):
The study's ID on Prolific.
Note: This ID is set by Prolific and can not be changed by the user
(see the 'Further (read-only) fields' section below).

name

(character):
Public name or title of the study (will be publicly visible when publishing the study).

internal_name

(character):
Internal name of the study (not shown to participants).

description

(character):
Description of the study (will be publicly visible when publishing the study).

external_study_url

(character):
URL of the survey or experiment the participants will be redirected to (will be publicly visible when publishing the study).
Note:

• The URL must be valid at the time the study is created on the Prolific platform.

• For the use of URL parameters, see field url_parameters.

url_parameters

(list):
A named list of URL parameters that is appended to external_study_url. The default

list(
     prolific_id = "{%PROLIFIC_PID%}",
     study_id = "{%STUDY_ID%}",
     session_id = "{%SESSION_ID%}"
)

is used for passing the participant's, study's and session's ID from Prolific to the data collection website.

prolific_id_option

(character):
This determines the method of passing the respondent's Prolific ID.
Valid options are:

• "url_parameters" for passing the ID as URL parameter {%PROLIFIC_PID%}

• "question" for letting the respondents enter their ID (e.g. via copy & paste), or

• "not_required" if the Prolific ID is not to be passed.

completion_code

(character):
The completion code that is provided to participants after completing the study. This code is used to prove that a participant completed the study. It is therefore visible for participants after completing the study.

completion_option

(character):
This determines the method for passing the completion_code.
Valid options are:

• "url"for passing the code as URL parameter when redirecting participants back to Prolific after completing the study, or

• "code"for providing a code for copy and paste.

total_available_places

(integer):
The number of participant you would like to recruit in the study (will be publicly visible when publishing the study).

estimated_completion_time

(integer):
The estimated time it takes to complete the study, in minutes (will be publicly visible when publishing the study).

maximum_allowed_time

(integer):
The maximum allowed time for participants to complete the study, in minutes.

reward

(integer):
The amount of money (in pence) you pay for completing the study (will be publicly visible when publishing the study).
Note: Compensation...

eligibility_requirements

(list):
A list containing prolific_prescreener objects that characterize the participants to be recruited. Note:

• NULL means that every participant can see and complete the study.

• Only persons fulfiling these requirements will be able to participate in the study.

device_compatibility

(character):
Note: NULL means that all options are available.

peripheral_requirements

(character):
A vector of technical requirements that participants have to fulfill to complete the study. One or multiple values from

   c("audio", "camera", "download", "microphone")

Note: NULL means that none of the requirements is needed.

naivety_distribution_rate

(numeric):
A value between 1 and 0 that controls the balance between speed of your study and the naivety of the participants.
Prolific's description of this field is rather vague, but it seems to imply that

• 1 means that less trained or 'professional' participants will have access to the study.

• 0 means that all eligible participants will have access to the study at the same time.

• values between 0 and 1 represent a tradeoff between both options.

further_fields

(list):
Prolific studies can have various further fields, which (if used) are stored in further_fields. These fields are read-only, and determined by Prolific. See the 'Further (read-only) fields' section below for a list of these read-only fields.

...

(further arguments):
Will be added to the further_fields field of the prolific_study (see above).

Types of fields

Required fields

are required for creating a study on Prolific.
The values for all of these except completion_option and prolific_id_option should be specified before publishing a study. Default values are only placeholders.

Optional fields

are writable, but optional for Prolific.
The user can but does not have to set these fields when creating a study.
The required and optional fields are:

	Required fields	Optional fields
	completion_code	device_compatibility
	completion_option	internal_name
	description	maximum_allowed_time
	eligibility_requirements	naivety_distribution_rate
	estimated_completion_time	peripheral_requirements
	external_study_url	url_parameters
	name
prolific_id_option		reward
	total_available_places

Further (read-only) fields

contain information that is determined internally by Prolific and read-only.
The id-field is of particular relevance. Once a study is created via API access, it is obtained from the API and stored in the prolific_study object, since it can be used to update, manage or delete a study.
To fully represent the information that is obtainable from the Prolific API, the further_fields list can contain some or all of the entries listed below. The corresponding overview provided in the Prolific API documentation currently seems to be work in progress.

	_links	average_reward_per_hour
	average_reward_per_hour_without_adjustment	average_time_taken
	currency_code	date_created
	device_compatibility	discount_from_coupons
	eligible_participant_count	estimated_reward_per_hour
	fees_per_submission	fees_percentage
	has_had_adjustment	internal_name
	is_pilot	is_underpaying
	last_email_update_sent_datetime	maximum_allowed_time
	minimum_reward_per_hour	naivety_distribution_rate
	number_of_submissions	peripheral_requirements
	pilot_test_steps_state	places_taken
	project	publish_at
	published_at	publisher
	quota_requirements	receipt
	representative_sample	representative_sample_fee
	researcher	reward_level
	share_id	stars_remaining
	status	study_type
	total_cost	total_participant_pool
	vat_percentage	workspace

Methods

validity_check

Check whether the study is valid in terms of the Prolific API.
Note: For checking the validity of the eligibility_requirements, an api_access object that passes check_authorization() needs to be available. It suffices if any such api_access object is specified, since the reference to it is determined automatically.

Return Value

• If the study is valid: A logical value indicating that the study is valid

• If the study is not valid: A character vector that lists the studie's issues.

Usage

     prolific_study$validity_check()

Examples

library(prolific.api)

prolific_api_access <- api_access(api_token = "")

# Create a new study
fancy_new_study <- prolific_study(
    name = "A fancy study on Prolific",
    external_study_url = "https://www.my_fancy_study_url.com",
    completion_code = "123ab456cd78",
    eligibility_requirements = list(),
    estimated_completion_time = 1,
    reward = 1,
    total_available_places = 0
)

# Check the study's validity
print(fancy_new_study$validity_check())

# Whoops, better add a description and change the total_available_places,
# using RefClass and S4 methods for illustration
# both are equivalent, so only one of the two commands is required in practice
# RefClass variant
fancy_new_study$total_available_places <- 1L
# S4 variant
total_available_places(fancy_new_study) <- 1L

# RefClass variant
fancy_new_study$description <- "A fancy description"
# S4 variant
description(fancy_new_study) <- "A fancy description"

# Re-Check the study's validity
print(fancy_new_study$validity_check())

# Note: For the following code to work,
# you have to replace  in the code above by the actual API token

if (FALSE) {
# Post the 'fancy_new_study' to Prolific - i.e. create it as a draft study on the platform
output_of_post <- prolific_api_access$access(
    endpoint = "studies",
    method = "post",
    data = fancy_new_study
)

# Success: fancy_new_study got an ID - it is now a draft study on Prolific!
fancy_new_study$id

# Note: The output of the access() command with a prolific_study object as `data` argument
# is a pointer to this prolific_study object.
# The prolific_study object is updated by reference
print(tracemem(output_of_post) == tracemem(fancy_new_study))

# Change the study's name
name(fancy_new_study) <- "A NEW name for 'fancy_new_study'"

# Update (patch) the study on Prolific,
# using S4 methods for illustration
output_of_patch <- access(
    prolific_api_access,
    endpoint = c("studies", id(fancy_new_study)),
    method = "patch",
    data = fancy_new_study
)

# Note: As above, the output of the access() command is a pointer to the prolific_study object.
print(tracemem(output_of_post) == tracemem(fancy_new_study))

# Delete fancy_new_study
prolific_api_access$access(
    endpoint = c("studies", id(fancy_new_study)),
    method = "delete",
    as_list = FALSE
)
}