Small Fixes in Pursuit of a Persistently Stable Release

SIGNIFICANT USER-VISIBLE CHANGES

• GetAssignments() now attempts to convert non-character variables to an appropriate R vector type via type.convert(, as.is = TRUE).
• Some statistics have been deprecated for the GetStatistic() and RequesterReport(), including "NumberAssignmentsAvailable", "NumberAssignmentsAccepted", "NumberAssignmentsReturned", "TotalFeePayout", and "TotalRewardAndFeePayout". This is reflected in the return value of ListStatistics().

DOCUMENTATION

• Added two papers (one from The Political Methodologist and one from The R Journal) as supplemental PDF documentation, accessible via ? MTurkR. (#93)
• Documentation now indicates that GrantBonus() allows the reason argument to contain newlines and tabs. (#109)

BUG FIXES

• Question identifiers used in a Qualification AnswerKey are only checked if CreateQualificationType() is called with validate.answerkey = TRUE. (#117, h/t Darrell Penta)
• Fixed a bug in BulkCreateFromHITLayout() that caused the function to fail. (#114, h/t Tyler Scott)
• Fixed a bug in trying to parse already parsed response for GetBonuses(). (#113, h/t Andrew Brown)
• The simple wizard now correctly respects AWS credentials specified as environment variables instead of the deprecated credentials() function. (h/t Kim Gross)
• Functions should now all return data frames with character class columns (unless otherwise noted) with sequentially numbered rownames. This corrects potentially some confusing behavior introduced during XML parsing. (#112)

Better everything.

SIGNIFICANT USER-VISIBLE CHANGES

• GenerateExternalQuestion now sets a default value of frame.height = 400.
• The AWS Access Key ID used for requests is now redacted from the error message printing when an API request fails to reduce the risk of accidentally disclosing the credential. (#105)
• AWS removed the Categorization and Photo Moderation QualificationTypes on December 18th, 2015. Use of these QualificationTypeIds will trigger warnings in some cases and the "generic" Masters QualificationTypeId will be substituted automatically. Users should not need to update any code, though they may be receive warnings. These have also been removed from ListQualificationTypes(). (#104)
• The use of credentials(), and options("MTurkR.keypair") are completely deprecated. A warning will now be issued if trying to supply credentials in this way. AWS credentials should be specified in environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. Messages are triggered on package load if environment variables are not set. (#102)
• HITStatus() will now display any non-empty RequesterAnnotation field for a HIT. (#101)
• The deprecated argument print, which was removed in v0.5, has been fully removed. Use verbose instead. (#97)
• The deprecated functions mturkrhelp and APIReference have been removed. (#96)
• MTurkR.Wizard has been removed from MTurkR and has been recreated as a separate package called MTurkRGUI. (#95)
• HITStatus now reports condensed column names better suited for narrow displays.
• Correctly handle multiple response.group arguments passed to HIT-related functions. (#89)
• authenticate, which was deprecated in v0.5, is removed.
• Use of RCurl has been replaced by curl. This necessitated a new dependency, base64enc. (#86)
• In lieu of credentials, AWS credentials should be specified via environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. credentials will be deprecated.
• SufficientFunds() reflects the new commission structure effective July 21, 2015. (#87)
• BulkCreateFromTemplate and BulkCreateFromURLs now have a frame.height argument with a default of 450.

DOCUMENTATION

• A small test suite has been added to help ensure correct package functionality. It is only executed in the sandbox in the presence of valid AWS credentials. (#100)
• The package now includes pages describing common use cases for MTurk (surveys, categorization, sentiment analysis, and webscraping). (#98)
• Descriptions of global package options have been added to MTurkR-package.Rd. (#103)
• The package now includes additional HTMLQuestion templates including examples for image categorization and sentiment rating. (#94)
• Documentation for GenerateHITReviewPolicy and GenerateAssignmentReviewPolicy was expanded and tested, and a related HTMLQuestion HIT template is now installed.

BUG FIXES

• Fixed a bug in checking for a valid AWS keypair in request(). (h/t Sean Murphy, #106)
• When ttk widgets were added to the graphical wizard in v0.6, scrollbar calls retained tk-only options. Those have been removed. (h/t Justin Koch)
• State-level locales are now correctly supported in QualificationRequirements, including in complex combinations with country locales with no subdivision (so mixing U.S. states with other countries is possible). This feature was added in v0.6.5 but had a critical bug. (h/t Ricky Bilakhia)
• Closing the graphical wizard crashed RStudio due to bringToTop(-1). This is fixed. (h/t Carolina Kuepper-Tetzel)

Bulk HIT Creation and Graphical Interface Updates

MTurkR 0.6.5 has been sent to CRAN. In addition to various bug fixes, this release includes two major sets of updates:

1. Four new functions have been added to bulk create HITs (i.e., to create multiple HITs in a single function call). These functions are: BulkCreate, BulkCreateFromTemplate, BulkCreateFromURLs, and BulkCreateFromHITLayout. These functions should greatly simplify managing large, multi-HIT projects (e.g., for coding, content analysis, categorization, transcription, etc.). See package documentation and a tutorial on the MTurkR wiki for full details.
2. The graphical wizard has received some updates important including:
   • HIT- and Assignment-level ReviewPolicies can now be attached to HITs at the time of HIT creation.
   • When creating a Qualification test, the wizard can now generate a template AnswerKey for the test automatically.

See NEWS for details of all changes.

Graphical Wizard Overhaul and Bug Fixes

This release primarily updates the graphical wizard (MTurkR.Wizard) for interacting with the MTurk API using a point-and-click interface. The interface has been significantly overhauled to improve its visual appearance by both updating layouts manually and converting to "themed tk" widgets (supported by tcl/tk v8.5). The overhaul also includes support for additional MTurkR features, documentation on the MTurkR wiki, and better handling of HITTypeId, HITId, and QualificationTypeId values.

The release also includes a few other changes:

• A fix for a major bug in ContactWorkers (when batch = TRUE) that contacted workers multiple times.
• Some updated examples for CreateHIT and CreateQualificationType and the inclusion of template files for better understanding the HTMLQuestion, QuestionForm, and AnswerKey data structures used by MTurk.
• Addition of examples of HITType Notifications, added support for SQS Notifications, and an expanded tutorial in the MTurkR wiki.

Support for Batches and ReviewPolicies

MTurkR v0.5.5

This release includes several smaller bug fixes and a few larger enhancements, described below.

• MTurkR finally supports MTurk ReviewPolicies, which allows the MTurk system to automatically approve, reject, and extend assignments for HITs based on either "known answers" in workers' responses or "plurality" agreement across multiple workers' responses. To achieve this, GenerateReviewPolicy is removed in lieu of two new functions: GenerateHITReviewPolicy and GenerateAssignmentReviewPolicy, both of which have a simplified function API and include extensive examples in the documentation. The use of CreateHIT remains unchanged.
• Additional support for working with "batches" created via the online Requester User Interface (RUI) has been added. Specifically, HITStatus, ApproveAllAssignments, ChangeHITType, DisposeHIT, DisableHIT, ExpireHIT, ExtendHIT, GetAssignment, GetBonuses, SetHITAsReviewing now include an optional annotation argument that can be used to apply the function to all HITs of a given batch. For example, to add two assignments to every HIT in a batch, simply find the batch number from the RUI and pass it as follows: ExtendHIT(annotation = "BatchId:78382;", add.assignments = 2).
• A substantial effort has been made to improve and expand documentation for the package. As part of this, examples in package documentation for all functions have been substantially expanded and checked for accuracy. And, the MTurkR wiki now includes numerous updated code examples, including full documentation for both the text-based wizard.simple and graphical mturkr.wizard interactive interfaces for MTurkR.
• All functions should now return type-consistent responses. This replaces the previous behavior of returning NULL on certain failures where dataframes have always been returned on successes.

See NEWS and GitHub commit logs for full details.

Simplified Function Arguments and Numerous Fixes

MTurkR v0.5

This release includes a large number of bug fixes, documentation corrections, and a large number of user-visible changes to function arguments meant to substantially simplify package use. Some highlights:

• GenerateQualificationRequirement now supports new comparators (given MTurk API update on 2014-07-17): "DoesNotExist", "In", and "NotIn". The "DoesNotExist" comparator allows requesters to effectively block workers who do not have, e.g., a requester-defined qualification. The "In" and "NotIn" comparators allow a boolean OR logical in QualificationRequirements (e.g., allowing a worker to be from the US or the UK) rather than having to create two separate HITs with different Locale restrictions. See documentation for details.
• Some features of of the basic API request functionality have changed: The signature argument to request now defaults to NULL and is generated automatically (authenticate is therefore deprecated). ParseErrorCodes is removed (now used internally in request). Arguments can be passed to request via a new ... argument in all functions.
• options('MTurkR.print') is deleted and replaced by options('MTurkR.verbose'). All functions will, temporarily, accept print arguments. All code should be updated to reflect the new terminology moving forward.
• Functions of the form *ToDataFrame have been replaced with as.data.frame S3 methods, which are handled by a global as.data.frame.MTurkResponse function.