MTurkR (version 0.8.0)

CreateHIT: 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. Use BulkCreate to create multiple HITs with shared properties.

Usage

CreateHIT(hit.type = NULL, question = NULL, validate.question = FALSE,
          expiration, assignments = "1", 
          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, 
          response.group = NULL, verbose = getOption('MTurkR.verbose', TRUE), ...)

Arguments

hit.type

An optional character string specifying the HITTypeId that this HIT should be visibly grouped with (and whose properties, e.g. reward amount, this HIT should inherit).

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.

validate.question

A logical specifying whether the question parameter should be validated against the relevant MTurk schema prior to creating the HIT (operation will fail if it does not validate, and will return validation information). Default is FALSE.

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 character string containing one or more QualificationRequirements data structures, 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

An optional character string containing URL query parameter-formatted HITLayout parameters, for example returned by GenerateHITLayoutParameter. Must be specified along with a hitlayoutid.

response.group

An optional character string (or vector of character strings) specifying what details of each HIT to return of: “Request”, “Minimal”, “HITDetail”, “HITQuestion”, “HITAssignmentSummary”. For more information, see Common Parameters and HIT Data Structure.

verbose

Optionally print the results of the API request to the standard output. Default is taken from getOption('MTurkR.verbose', TRUE).

...

Additional arguments passed to request.

Value

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

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.

createhit() and create() are aliases. BulkCreate can be used to create multiple HITs in a single call.

References

API Reference

See Also

BulkCreate

ExtendHIT

ExpireHIT

DisableHIT

DisposeHIT

RegisterHITType

GenerateHITReviewPolicy

GenerateQualificationRequirement

Examples

# NOT RUN {
## CreateHIT using HITLayout from MTurk Requester User Interface ##
a <- GenerateLayoutParameter("message","Text to display in HIT")
hit1 <- CreateHIT(hit.type = "2FFNCWYB49F9BBJWA4SJUNST5OFSOW",
                  hitlayoutid = "23ZGOOGQSCM61T1H5H9U0U00OQWFFU", 
                  expiration = seconds(days = 4),
                  hitlayoutparameters = a)

## CreateHIT using ExternalQuestion HIT URL ##
eq <- GenerateExternalQuestion("https://www.example.com/","400")

### Specifying a HITTypeId ###
hit2 <- CreateHIT(hit.type = "2FFNCWYB49F9BBJWA4SJUNST5OFSOW", 
                  expiration = seconds(days = 4),
                  question = eq$string)

### Creating a new HITTypeId atomically ###
hit3 <- CreateHIT(title = "Survey",
                  description = "5 question survey",
                  reward = ".10",
                  expiration = seconds(days = 4),
                  duration = seconds(hours = 1),
                  keywords = "survey, questionnaire",
                  question = eq$string)

## CreateHIT using HTMLQuestion HIT Contents ##
f1 <- system.file("templates/htmlquestion1.xml", package = "MTurkR")
hq <- GenerateHTMLQuestion(file = f1)
hit4 <- CreateHIT(hit.type = "2FFNCWYB49F9BBJWA4SJUNST5OFSOW", 
                  expiration = seconds(days = 4),
                  question = hq$string)

## CreateHIT using QuestionForm HIT Contents ##
f2 <- system.file("templates/tictactoe.xml", package = "MTurkR")
qf <- GenerateHTMLQuestion(file = f2)
hit5 <- CreateHIT(hit.type = "2FFNCWYB49F9BBJWA4SJUNST5OFSOW", 
                  expiration = seconds(days = 4),
                  question = qf$string)


## Cleanup examples ##
ExpireHIT(hit1$HITId)
ExpireHIT(hit2$HITId)
ExpireHIT(hit3$HITId)
ExpireHIT(hit4$HITId)
ExpireHIT(hit5$HITId)
DisposeHIT(hit1$HITId)
DisposeHIT(hit2$HITId)
DisposeHIT(hit3$HITId)
DisposeHIT(hit4$HITId)
DisposeHIT(hit5$HITId)
# }