prolific_prescreener {prolific.api}

Prolific prescreening requirement

Description

Class that represents prescreening requirements to characterize the participants to be selected for a certain study on Prolific, i.e. the persons to be recruited via Prolific. prolific_prescreener objects are therefore mainly used in the eligibility_requirements field of prolific_studys.
The fields and methods are available as in RefClass or S4 objects (see examples).

The section 'Setting up prescreeners for Prolific' below provides an overview and examples of how to specify prescreening requirements.

Fields

title

(character):
A valid title for a single prescreener that is available on the Prolific platform. To be valid, this title must appear in the list of prescreeners obtainable from the Prolific API.
See the section 'Setting up prescreeners for Prolific' as well as the prolific.api package vignette.

constraints

(list):
The valid constraints for this particular prescreener.
When creating a prolific_prescreener object, an arbitrary number of constraints can be specified using named or unnamed custom arguments. In the named case,

       name_1 = value_1,...,name_i = value_i,

name = value pairs are used to set the constraints and values. Using the unnamed case

       name_1,...,name_i

allows to ommit the values for prescreeners where value_1 = ... = value_i = TRUE. In that way, users can simply provide the names of the groups to be recruited. See the section 'Setting up prescreeners for Prolific' as well as the examples and prolific.api package vignette.

Setting up prescreeners for Prolific

Prescreeners are used to select participants for a prolific_study that meet certain characteristics. In most cases, this selection is done with regard to the answers the participants gave in a survey conducted by Prolific across all its members.

Choosing a prescreening variable

At the moment, there are 265 variables which can be used to recruit specific subgroups from Prolific. To obtain a list of all available prescreening variables, use

          table_of_prescreeners <-
                    prescreeners(prolific_api_access)

where prolific_api_access is an api_access object with a valid api_token.

A prescreening variable is determined by the title field of the prolific_prescreener object. To be valid, this title must appear in the title column of the resulting table_of_prescreeners.

Setting constraints for a particular prescreening variable

The constraints are specified in the form

         name_1 = value_1,
         ...,
         name_n = value_n

or

         name_1,
         ...,
         name_n

For most prescreeners, the values value_1 ... value_n are logical values to select participants that gave a certain answer in some pre-screening question. In this case, specifying

         name_i = TRUE

for the prescreener means that participants who gave answer name_i are eligible for the study. However, keep in mind there are some prescreeners that work in the opposite way, e.g. to specify a list of participants to be exluded (see the sections 'Ex- or include a list of specific participants' and 'Ex- or include all participants from previous studies' below).

For all cases where the values value_1 ... value_n are logical,

         name_1,
         ...,
         name_n

is an equivalent shortcut for

         name_1 = TRUE,
         ...,
         name_n = TRUE

.

Yet, the constraint values are not always of type logical. In particular, there are prescreeners that allow to select participants lying within a certain range of a numerical variable. For example, this is the case when selecting participants who are in a certain age bracket, where lower and upper boundary for a person's age are specified in the constraints. In this case, value_1, ..., value_n in the above specification need to be numeric as well, and must be named e.g. as in

         min_age = 50,
         max_age = 60

for selecting participants between age 50 and 60 for the study.

The names name_1, ..., name_n are always taken literally. This means that they are not automatically evaluated. Enclosing a name in an eval() command forces it to be evaluated rather than taken literally. This is important for example in cases where the categories are stored in a list (see the section 'Examples for prolific_prescreeners' for an example).

To obtain the list of possible constraints for a particular prescreener with a valid title "the_title" as described above, use

     table_of_constraints <-
               prescreeners(prolific_api_access,
                            filter=expression(title==c("the_title")),
                            show_full=TRUE)

The names name_1, ..., name_n of the constraints list should come from a single (typically the name) column of the resulting table_of_constraints, the respective list elements represent the values that participants have to meet.

To make this a bit clearer, the following section provides examples for setting up prescreening requirements.

Examples for prolific_prescreeners

Nationality requirements

For example, a study can be set to exclusively target participants who currently live in the UK or the USA by using

          residential_prescreener <- prolific_prescreener(
              title = "Current Country of Residence",
              "United Kingdom", "United States"
           )

or equivalently

         list_of_countries <- list(
             country_1="United Kingdom",
             country_2="United States")

         residential_prescreener <- prolific_prescreener(
             title = "Current Country of Residence",
             eval(list_of_countries$country_1),
             eval(list_of_countries$country_2)
         )

Note that "Current Country of Residence" appears in the title column of table_of_prescreeners, and "United Kingdom" as well as "United States" appear in the name column of the resulting table_of_constraints described in the previous sections. Furthermore, note the use of eval() to force evaluation of list_of_countries$country_1 and list_of_countries$country_2.

Age requirements

Similarly, selecting participants who fall in the age range between 50 and 60 can be achieved through

          age_prescreener <- prolific_prescreener(
              title = "Age",
              "min_age" = 50,
              "max_age" = 60
          )

Ex- or include a list of specific participants

Specific participants can be in- or excluded from a study, for example if they participated in previous studies. This can be done in form of black- or whitelists.

Consider two fictional participants with Prolific id's 111 and 222. These can be specifically excluded by using the exclusion list defined by

          exclude_list_participants <- prolific_prescreener(
              title = "Custom Blacklist",
              "111","222"
          )

To exclusively recruit exactly these two participanty, use the include list defined by

          include_list_participants <- prolific_prescreener(
              title = "Custom Whitelist",
              "111","222"
          )

Note: The IDs for these constraints need to be valid Prolific IDs when creating a study. The above example for fictional IDs 111 and 222 will therefore always fail.

Ex- or include all participants from previous studies

You can not only blacklist single participants, but also the group(s) of participants who participated in of one or multiple of your previous studies.

To exclude all participants from two fictional studies with IDs ABC and DEF, specify the prescreener

          exclude_list_studies <- prolific_prescreener(
              title = "Exclude participants from previous studies",
              "ABC","DEF"
          )

To exclusively recruit participants from these studies, use

          include_list_studies <- prolific_prescreener(
              title = "Include participants from previous studies",
              "ABC","DEF"
          )

Note: The IDs for these constraints need to be valid Study IDs when creating a study. The above example for fictional IDs ABC and DEF will therefore always fail.

Methods

validity_check

Check whether the prescreener is valid in terms of the Prolific API.
Note: For checking a prescreener's validity, 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 prescreener is valid: A logical value indicating that the study is valid

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

Usage

     prescreener$validity_check()

Examples

library("prolific.api")

prolific_api_access <- api_access(api_token = "<api_token>")

# Create a new study with two of the prescreening constraints
#    from the help section 'Examples for prolific_prescreeners'
#    in this package's documentation.
fancy_new_study_with_prescreeners <- prolific_study(
    name = "A fancy study on Prolific",
    description = "Fancy description",
    external_study_url = "https://www.my_fancy_study_url.com",
    completion_code = "123ab456cd78",
    estimated_completion_time = 1,
    reward = 1,
    total_available_places = 1,
    eligibility_requirements = list(
        # Include only persons who live in the UK or the US
        prolific_prescreener(
            title = "Current Country of Residence",
            "United Kingdom", "United States"
        ),
        # Include participants only if they are between
        #    50 and 60 years old
        prolific_prescreener(
            title = "Age",
            "min_age" = 50,
            "max_age" = 60
        )
    )
)

# Note: For the following code to work,
# you have to replace <api_token> in the code above by the actual API token
## Not run: 
# Post the 'fancy_new_study_with_prescreeners' to Prolific,
#    i.e. create it as a draft study on the platform
prolific_api_access$access(
    endpoint = "studies",
    method = "post",
    data = fancy_new_study_with_prescreeners
)

# Success: fancy_new_study_with_prescreeners got an ID - it is now a draft study on Prolific!
# You can also inspect the study and requirements in the Prolific Web UI now.
fancy_new_study_with_prescreeners$id

## End(Not run)