# Prolific study Class that represents Prolific studies, such that they can be transferred to or from the [Prolific API](https://docs.prolific.co/docs/api-docs/public/). 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](../doc/prolificapi-package.html)).** 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](https://docs.prolific.co/docs/api-docs/public/) (see examples). class ## 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 participatein 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](https://docs.prolific.co/docs/api-docs/public/) 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](https://docs.prolific.co/docs/api-docs/public/), the `further_fields` list can contain some or all of the entries listed below. The corresponding overview provided in the [Prolific API documentation](https://docs.prolific.co/docs/api-docs/public/#tag/Studies/paths/~1api~1v1~1studies~1%7Bid%7D~1/get) 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](https://docs.prolific.co/docs/api-docs/public/). 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 ```r 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 ## Not run: # 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 ) ## End(Not run) ```

prolific_study function