BulkCreate: Generate Multiple HITs

Description

Generate multiple HITs, possibly from an HTML template file, HITLayout parameters, or a vector of External Question URLs.

Usage

BulkCreate(questions, annotation, verbose = FALSE, ...)

BulkCreateFromTemplate(template, input, annotation, type = "HTMLQuestion", 
                       frame.height = 450, verbose = FALSE, ...)

BulkCreateFromURLs(url, frame.height = 450, annotation, verbose = FALSE, ...)

BulkCreateFromHITLayout(hitlayoutid, input, annotation, verbose = FALSE, ...)

Arguments

questions

A character vector where each entry is a valid argument for the question argument to CreateHIT, or a list of objects of class ExternalQuestion (created by

template

A character string or filename for a HIT template (probably a character string containing an HTML document or a path to a .html file).

input

A data.frame containing one row for each HIT to be created and columns named identically to the placeholders in the HIT template file (for BulkCreateFromTemplate) or the HITLayout parameters (for BulkCreateFromHITLayout). Operati

type

A character string specifying how to wrap the resulting HIT question contents for use in CreateHIT. If set to HTMLQuestion, template is passed to

url

A character vector of URLs (served over HTTPS) of HIT files stored anywhere other than the MTurk server. See GenerateExternalQuestion.

frame.height

A character string containing the integer value (in pixels) of the frame height for the ExternalQuestion iframe. See GenerateExternalQuestion.

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 placeh

annotation

Either a one-element character vector containing a description for this group of HITs, or a character vector equal to the number of HITs to be created. This value is only visible to the requester. See CreateHIT<

verbose

Optionally print the results of the API request (and other details) to the standard output. Default is FALSE. Note that this overrides the default set by getOption('MTurkR.verbose') because in the case of many HITs, this output c

...

Additional arguments passed to CreateHIT. See examples.

Value

A list of data.frames, with each data.frame containing details of the HITs created. If all CreateHIT operations succeed, this response value can easily be collapsed into a single data.frame using do.call("rbind", value).

Details

These functions provide a wrapper for CreateHIT to be able to produce a group of HITs with identical properties. BulkCreateFromTemplate and BulkCreateFromHITLayout provide further wrappers that make it easy to create a group of HITs in a manner similar to using the Requester User Interface (RUI). BulkCreateFromURLs allows you to create multiple ExternalQuestion HITs. The annotation field is required in order to group the HITs together and facilitate monitoring the group using other MTurkR functions. Note that these functions do not create a batch as used by the RUI; a batch can only be created through that interface.

References

http://docs.amazonwebservices.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_CreateHITOperation.html{API Reference: CreateHIT} http://docs.amazonwebservices.com/AWSMechTurk/latest/RequesterUI/CreatingaHITTemplate.html{Requester User Interface: HIT Template} http://docs.amazonwebservices.com/AWSMechTurk/latest/AWSMturkAPI/ApiReference_ExternalQuestionArticle.html{API Reference: ExternalQuestion}

Examples

Run this code

## BulkCreate ##

# load a vector of HTML files from the working directory
qvec <- sapply(list.files(pattern = ".html"), function(x) {
          paste0(readLines(x, warn = FALSE), collapse = "\n")
        })
# create a HIT from each question file
hits1 <- BulkCreate(questions = qvec,
                    annotation = paste("Bulk Create", Sys.Date()),
                    title = "Categorize an image",
                    description = "Categorize this image",
                    reward = ".05",
                    expiration = seconds(days = 4),
                    duration = seconds(minutes = 5),
                    keywords = "categorization, image, moderation, category")

# cleanup
ExpireHIT(annotation = paste("Bulk Create", Sys.Date()))
DisposeHIT(annotation = paste("Bulk Create", Sys.Date()))

## BulkCreateFromURLs ##

# create three HITs from the template
hits2 <- 
BulkCreateFromURLs(url = paste0("https://www.example.com/",1:3,".html"),
                   frame.height = 400,
                   annotation = paste("Bulk From URLs", Sys.Date()),
                   title = "Categorize an image",
                   description = "Categorize this image",
                   reward = ".05",
                   expiration = seconds(days = 4),
                   duration = seconds(minutes = 5),
                   keywords = "categorization, image, moderation, category")

# cleanup
ExpireHIT(annotation = paste("Bulk From URLs", Sys.Date()))
DisposeHIT(annotation = paste("Bulk From URLs", Sys.Date()))

## BulkCreateFromTemplate ##

# load template HTML file
# should have placeholders of the form `${varName}` for variable values
temp <- system.file("templates/htmlquestion2.xml", package = "MTurkR")

# create/load data.frame of template variable values
a <- data.frame(hittitle = c("HIT title 1", "HIT title 2", "HIT title 3"),
                hitvariable = c("HIT text 1", "HIT text 2", "HIT text 3"), 
                stringsAsFactors = FALSE)

# create three HITs from the template
hits3 <- 
BulkCreateFromTemplate(template = temp,
                       input = a,
                       annotation = paste("Bulk From Template", Sys.Date()),
                       title = "Categorize an image",
                       description = "Categorize this image",
                       reward = ".05",
                       expiration = seconds(days = 4),
                       duration = seconds(minutes = 5),
                       keywords = "categorization, image, moderation, category")

# cleanup
ExpireHIT(annotation = paste("Bulk From Template", Sys.Date()))
DisposeHIT(annotation = paste("Bulk From Template", Sys.Date()))

## BulkCreateFromHITLayout ##

# retrieve HITLayoutID from Requester User Interface
layoutid <- "23ZGOOGQSCM61T1H5H9U0U00OQWFFU"

# create/load data.frame of HITLayout variable values
b <- data.frame(hittitle = c("HIT title 1", "HIT title 2", "HIT title 3"),
                hitvariable = c("HIT text 1", "HIT text 2", "HIT text 3"), 
                stringsAsFactors = FALSE)

# create three HITs from the template
hits4 <- 
BulkCreateFromHITLayout(hitlayoutid = layoutid,
                        input = b,
                        annotation = paste("Bulk From Layout", Sys.Date()),
                        title = "Categorize an image",
                        description = "Categorize this image",
                        reward = ".05",
                        expiration = seconds(days = 4),
                        duration = seconds(minutes = 5),
                        keywords = "categorization, image, moderation, category")

# cleanup
ExpireHIT(annotation = paste("Bulk From Layout", Sys.Date()))
DisposeHIT(annotation = paste("Bulk From Layout", Sys.Date()))

Run the code above in your browser using DataLab