This package provides access to the Amazon Mechanical Turk (MTurk) Requester API. The package provides users of the MTurk Requester User Interface with access to a variety of functions currently unavailable to them (the creation and maintenance of worker Qualifications, email notifications to workers through ContactWorker, automated reviewing of assignments using Review Policies, and streamlined bonus payments through GrantBonus). It also provides users with all functions available in the RUI directly in R as well as a large number of other functions, and a simple, interactive command-line tool for performing many operations. A relatively fully featured, cross-platform graphical user interface is available in a separate add-on package called MTurkRGUI.
Most users will find themselves using three principal functions: CreateHIT, GetAssignments, and ApproveAssignments, to create one or more HITs on the MTurk server, to retrieve completed assignments, and to approve assignments (and thus pay workers), respectively. As task complexity increases, additional functions are provided to handle worker qualifications, bonuses, emails to workers, automated review policies, bulk creation of HITs, and so forth.
Critically important, nothing in MTurkR will work during a given session without either first setting AWS credentials. The easiest way to do this is to specify AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables using Sys.setenv() or by placing these values in an .Renviron file. Credentials can also be specified atomically within each MTurkR function as the keypair argument, which accepts the credentials as a two-element character vector.
There are five common parameters that can be specified in most MTurkR functions: keypair, verbose, log.requests, and sandbox. The first of these is the AWS credentials parameter just described and the latter four are logicals. verbose causes certain information to be displayed on the standard output when functions are executed. log.requests records details of API calls in the working directory (see readlogfile). This is slightly time-consuming, so it can be omitted if you do not need access to log information (e.g., for troubleshooting). Setting the parameter sandbox=TRUE executes requests in the developer sandbox rather than the live server, which is a useful test environment.
All of these options can be set globally using options(). The specific forms are:
options('MTurkR.sandbox'): A logical (default FALSE), to control use of the MTurk sandbox.
options('MTurkR.browser'): A logical (default FALSE), to send requests to a web browser rather than through R.
options('MTurkR.verbose'): A logical (default TRUE), to control printing to the console. If TRUE, updates will be printed to the console during function execution. This can be useful when, for example, executing a large number of assignment approvals, etc.
options('MTurkR.log'): A logical (default TRUE), to control whether requests are logged to a directory.
options('MTurkR.logdir'): A character string specifying a directory path in which to store the “MTurkRlog.tsv” log file. This is set, by default, as the working directory when MTurkR is loaded; if the option is not set (or unset), the current working directory is used.
options('MTurkR.test'): A logical, which if TRUE (not the default), can allow request to be used for debugging purposes. It returns details of the request.
The MTurkR Wiki, which contains numerous code examples and tutorials.
The MTurkRGUI Package, which provides a graphical user interface for MTurkR.
To get started using MTurkR, see the documentation for CreateHIT (for creating single tasks) and/or BulkCreate (for creating batches of tasks). For some tutorials on how to use MTurkR for specific use cases, see the following:
survey, for collecting survey(-experimental) data
categorization, for doing large-scale categorization (e.g., photo moderation or developing a training set)
sentiment, for doing sentiment coding
webscraping, for manual scraping of web data