# Prolific prescreening requirement 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. class ## 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](https://docs.prolific.co/docs/api-docs/public/). See the section **'Setting up prescreeners for Prolific'** as well as the [prolific.api package vignette](../doc/prolificapi-package.html). - **`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](../doc/prolificapi-package.html). ## 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" ) ``` - **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](https://docs.prolific.co/docs/api-docs/public/). 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 ```r library("prolific.api") prolific_api_access <- api_access(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 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) ```

prolific_prescreener function