CreateHIT: Create HIT

In pyMTurkR: A Client for the 'MTurk' Requester API

Create HIT

Description

Create a single HIT. This is the most important function in the package. It creates a HIT based upon the specified parameters: (1) characteristics inherited from a HITType or specification of those parameters and (2) some kind of Question data structure.

Usage

CreateHIT(
  hit.type = NULL,
  question = NULL,
  expiration,
  assignments = NULL,
  assignment.review.policy = NULL,
  hit.review.policy = NULL,
  annotation = NULL,
  unique.request.token = NULL,
  title = NULL,
  description = NULL,
  reward = NULL,
  duration = NULL,
  keywords = NULL,
  auto.approval.delay = NULL,
  qual.req = NULL,
  hitlayoutid = NULL,
  hitlayoutparameters = NULL,
  verbose = getOption("pyMTurkR.verbose", TRUE)
)

Arguments

hit.type	An optional character string specifying the HITTypeId that this HIT should be generated from. If used, the HIT will inherit title, description, keywords, reward, and other properties of the HIT.
question	A mandatory (unless layoutid is specified) character string containing a QuestionForm, HTMLQuestion, or ExternalQuestion data structure. In lieu of a question parameter, a hitlayoutid and, optionally, hitlayoutparameters can be specified.
expiration	The time (in seconds) that the HIT should be available to workers. Must be between 30 and 31536000 seconds.
assignments	A character string specifying the number of assignments
assignment.review.policy	An optional character string containing an Assignment-level ReviewPolicy data structure as returned by GenerateAssignmentReviewPolicy.
hit.review.policy	An optional character string containing a HIT-level ReviewPolicy data structure as returned by GenerateHITReviewPolicy.
annotation	An optional character string annotating the HIT. This is not visible to workers, but can be used as a label by which to identify the HIT from the API.
unique.request.token	An optional character string, included only for advanced users. It can be used to prevent creating a duplicate HIT. A HIT will not be creatd if a HIT was previously granted (within a short time window) using the same unique.request.token.
title	A character string containing the title for the HITType. All HITs of this HITType will be visibly grouped to workers according to this title. Maximum of 128 characters.
description	A character string containing a description of the HITType. This is visible to workers. Maximum of 2000 characters.
reward	A character string containing the per-assignment reward amount, in U.S. Dollars (e.g., “0.15”).
duration	A character string containing the amount of time workers have to complete an assignment for HITs of this HITType, in seconds (for example, as returned by seconds). Minimum of 30 seconds and maximum of 365 days.
keywords	An optional character string containing a comma-separated set of keywords by which workers can search for HITs of this HITType. Maximum of 1000 characters.
auto.approval.delay	An optional character string specifying the amount of time, in seconds (for example, as returned by seconds), before a submitted assignment is automatically granted. Maximum of 30 days.
qual.req	An optional list containing one or more QualificationRequirements, for example as returned by GenerateQualificationRequirement.
hitlayoutid	An optional character string including a HITLayoutId retrieved from a HIT “project” template generated in the Requester User Interface at ‘⁠https://requester.mturk.com/create/projects⁠’. If the HIT template includes variable placeholders, must also specify hitlayoutparameters.
hitlayoutparameters	Required if using a hitlayoutid with placeholder values. This must be a list of lists containing Name and String values.
verbose	Optionally print the results of the API request to the standard output. Default is taken from getOption('pyMTurkR.verbose', TRUE).

Details

This function creates a new HIT and makes it available to workers. Characteristics of the HIT can either be specified by including a valid HITTypeId for “hit.type” or creating a new HITType by atomically specifying the characteristics of a new HITType.

When creating a HIT, some kind of Question data structure must be specified. Either, a QuestionForm, HTMLQuestion, or ExternalQuestion data structure can be specified for the question parameter or, if a HIT template created in the Requester User Interface (RUI) is being used, the appropriate hitlayoutid can be specified. If the HIT template contains variable placeholders, then the hitlayoutparameters should also be specified.

When creating a ExternalQuestion HITs, the GenerateHITsFromTemplate function can emulate the HIT template functionality by converting a template .html file into a set of individual HIT .html files (that would also have to be uploaded to a web server) and executing CreateHIT for each of these external files with an appropriate ExternalQuestion data structure specified for the question parameter.

Note that HIT and Assignment Review Policies are not currently supported.

createhit(), create(), CreateHITWithHITType(), and createhitwithhittype() are aliases.

Value

A data frame containing the HITId and other details of the newly created HIT.

Author(s)

Tyler Burleigh, Thomas J. Leeper

References

API Reference

Examples

## Not run: 

CreateHIT(title = "Survey",
         description = "5 question survey",
         reward = "0.10",
         assignments = 1,
         expiration = seconds(days = 4),
         duration = seconds(hours = 1),
         keywords = "survey, questionnaire",
         question = GenerateExternalQuestion("https://www.example.com/","400"))

## End(Not run)

pyMTurkR documentation built on May 29, 2024, 6:13 a.m.