MTurkR (version 0.8.0)

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 GenerateExternalQuestion) or HTMLQuestion (created by GenerateHTMLQuestion). Each entry in this vector or list represents one HIT to be created.

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). Operation will fail if variable names do not correspond.

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 GenerateHTMLQuestion before use.

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 placeholders, must also specify hitlayoutparameters.

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 for details.

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 could become unwieldy.

…

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

API Reference: CreateHIT

Requester User Interface: HIT Template

API Reference: ExternalQuestion

See Also

CreateHIT

GenerateHITsFromTemplate

GenerateHITLayoutParameter

Examples

# NOT RUN {
## 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()))
# }
# NOT RUN {
# }
# NOT RUN {
## 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()))
# }
# NOT RUN {
# }
# NOT RUN {
## 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()))
# }
# NOT RUN {
# }
# NOT RUN {
## 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()))
# }