Skip to content
This repository has been archived by the owner on May 24, 2019. It is now read-only.

Wizard Text Based

Jump to bottom
leeper edited this page Dec 7, 2014 · 10 revisions

Introduction to the Simple Wizard (Text Based)

This is an introduction to the MTurkR simple, text-based wizard, which supplies some basic interactive features for using MTurk. Users interested in functionality not supplied here may also be interested in [the graphical wizard](Wizard Graphical) or in using the MTurkR functions directly via the command line.

Getting Started with MTurkR

There are a few steps you'll need to complete before you start working with MTurkR, after getting your AWS security credentials you'll be able to start working with MTurkR.

  1. First you need to acquire your security credentials from Amazon. They can be found on the Amazon Web Services site http://aws.amazon.com. Once you create an account and login, click on "Access Keys". In the bottom left hand side there will be a button that says "Create New Access Key". Click this.
  2. Once you get your credentials keep them in a safe spot, as you can only download them once. New credentials can be reissued as needed. Your keypair will be an access key and secret key will each be a series of letters, numbers, and possibly other symbols.
  3. Now you are ready to start working with the Wizard.

Introduction to the Simple Wizard

Once you have your keypair, you need to install R. Then:

  1. Open R and install MTurkR. You can either install a stable package version using install.packages("MTurkR"), or install the most recent version with the newest features by doing the following:

    install.packages("devtools")
devtools::install_github("leeper/MTurkR")

  2. Once you have MTurkR installed, load the package using library("MTurkR") and then start the text-based wizard by typing mturkr.wizard("simple").

  3. You will be prompted to enter your AWS Access Key ID and the Secret Access Key.

  4. You will be prompted whether you want to use the "Sandbox". The sandbox is a trial server where you can test out operations before making them available on the real MTurk site.

> library("MTurkR")
> wizard.simple()
MTurkR Wizard loading...

Retrieve your AWS access keys from https://aws-portal.amazon.com/gp/aws/securityCredentials
AWS/MTurk Access Key ID: TypeYourAccessKeyHere
AWS/MTurk Secret Access Key: TypeYourSecretKeyHere
Use Sandbox? (Y/N): Y

Navigating the text-based wizard is via numbered menus. To select any option on a menu, simply enter the number listed next to the item. The number 0 is used on each menu to exit. Thus, if you enter a dialog but wish to return to the main menu, simply press 0 and hit <Enter>/<Return>.

MTurkR Operations 

 1: Check Account Balance          2: Check Sufficient Funds      
 3: Create HIT                     4: Check HIT Status            
 5: Get Assignment(s)              6: Extend HIT                  
 7: Expire HIT                     8: Approve Assignment(s)       
 9: Reject Assignment(s)          10: Grant Bonus(es)             
11: Contact Worker(s)             12: Block Worker(s)             
13: Unblock Worker(s)             14: Manage Qualifications       
15: Requester Statistics          16: Worker Statistics           
17: Open MTurk RUI Pages          18: Load MTurkR Log File/Entries
19: Exit                          

Selection:

Note: If you start the wizard with mturkr.wizard("simpleGUI"), you can instead use a point-and-click set of menus. The contents of the wizard are otherwise identical to the text-based version.

The following sections describe the commands available in the wizard.

###Option 1: Check Account Balance

This command will allow you to see how much money is left in your MTurk requester account, this will only show how much you have in your requester account and will not count any money you've earned doing HITs. Note: In the sandbox, this number will always be $10,000.00.

MTurkR Operations 

 1: Check Account Balance          2: Check Sufficient Funds      
 3: Create HIT                     4: Check HIT Status            
 5: Get Assignment(s)              6: Extend HIT                  
 7: Expire HIT                     8: Approve Assignment(s)       
 9: Reject Assignment(s)          10: Grant Bonus(es)             
11: Contact Worker(s)             12: Block Worker(s)             
13: Unblock Worker(s)             14: Manage Qualifications       
15: Requester Statistics          16: Worker Statistics           
17: Open MTurk RUI Pages          18: Load MTurkR Log File/Entries
19: Exit                          

Selection: 1
Balance: $10,000.00

###Option 2: Check Sufficient Funds

This option allows you to estimate whether you have sufficient funds in your MTurk account to finance a particular HIT. It is simply a calculator that wraps around AccountBalance.

Selection: 2
How much do you want to pay per assignment (in US Dollars): 0.75
How many HITs do you plan to offer (usually 1): 1
How many assignments per HIT: 250

Total Payments:   $187.50 
Payment Fee:      $18.75 
Masters Fee:      $0.00 
Bonuses:          $0.00 
Bonus Fee:        $0.00 
-------------------------
  Old Balance:    $10000.00 
  Total Cost:     $206.25 
  New Balance:    $9793.75  < SUFFICIENT FUNDS

###Option 3: Create HIT

This option walks you through how to create a HIT. The wizard only supports creating HITs in two ways:

  1. Using an ExternalHIT structure, which requires you to supply an HTTPS URL for a webpage that contains the entire HIT contents and that will, on form submission, submit to the appropriate MTurk submit URL (see HITs).
  2. Using a HITLayoutId, as retrieved from the Requester User Interface.

The wizard will walk through all of the information required to create the HIT, then execute the request and print the HITId for the new HIT to the console.

###Option 4: Check HIT Status

This operation will check the status of a HIT by simply prompting for a HITId (for example, as returned by the Create HIT dialog). Details will be printed to the console.

###Option 5: Get Assignments

This operation will retrieve assignment details for either a specific assignment or an entire HIT. This requires either the AssignmentId or HITId, respectively.

###Option 6: Extend HIT

This operation will add time and/or assignments to a specified HIT. After being prompted for the HITId, a dialog will allow you to add time (in seconds), assignments, or both.

###Option 7: Expire HIT

This operation will expire a HIT (thus making it unavailable to workers). All that is required is the HITId. To reopen the HIT to workers, use the Extend HIT dialog.

###Option 8: Approve Assignment(s)

This operation will allow you to approve one or more assignments. You have the choice to approve:

  1. One assignment
  2. Multiple assignments
  3. All assignments for a HIT

For one assignment, you will be prompted to enter the AssignmentId. For multiple assignments, you first be prompted for the number of assignments you will approve followed by prompts for each of the AssignmentIds, specified one per line. Finally, if you choose to approve all assignments for a HIT, you will be prompted for the HITId.

Details in each case will be printed to the console.

###Option 9: Reject Assignment(s)

Similar to approving assignments, this dialog will allow you to reject one or more assignments. It is not possible to reject all assignments for a HIT. For one assignment, you will be prompted to enter the AssignmentId. For multiple assignments, you first be prompted for the number of assignments you will reject followed by prompts for each of the AssignmentIds, specified one per line.

In either case you will also be prompted to supply a reason for the rejection, which will be visible to the worker. In the case of multiple assignments, the same reason is used for all assignments.

Details in each case will be printed to the console.

###Option 10: Grant Bonus(es)

This dialog allows you to supply bonuses to one or more workers.

If you choose to grant a bonus to a single worker, you will be prompted for their WorkerId, the AssignmentId for which the bonus is being paid, the amount of the bonus in US dollars, and a reason for the bonus that will be visible to workers.

Selection: 10
Contact one worker or multiple workers? 

1: Single Worker
2: Multiple Workers

Selection: 1
WorkerId to Bonus: WorkerId
AssignmentId to Bonus: AssignmentId
Amount of Bonus in US Dollars: 0.01
Reason for Bonus: Thanks for the good work!

If you choose to grant a bonus to multiple workers, you will be prompted for the amount of the bonus in US dollars, the reason for the bonus that is visible to each worker (note: the same reason is used for all bonuses), and then the number of Workers you will be granting the bonus to. After this, you will be prompted to enter each WorkerId one-per-line. Then, you will be asked to enter the corresponding AssignmentId for each worker, again one per line.

Selection: 10
Contact one worker or multiple workers? 

1: Single Worker
2: Multiple Workers

Selection: 2
Amount of Bonus in US Dollars: 0.01
Reason for Bonus: Thanks for the good work!
How many bonuses to pay: 2
Enter each WorkerId on own line:
1: WorkerId1
2: WorkerId2
Read 2 items
Enter corresponding AssignmentId for each Worker on own line:
1: AssignmentId1
2: AssignmentId2
Read 2 items

Some details will be printed to the console.

###Option 11: Contacting Workers

This dialog allows you to contact workers via email using their WorkerId. You can email one or multiple workers.

If you contact one worker, you will be prompted for their WorkerId, an email subject line, and the body of an email. You can use \t (tab) and \n (newline) characters to create appropriate spacing in the email. This is what the dialog looks like:

Selection: 11
Contact one worker or multiple workers? 

1: Single Worker
2: Multiple Workers

Selection: 1
WorkerId to Notify: MyWorkerId
Email Subject Line: Test Email
Email body text: This is a test email.\n Please disregard.

If you are sending messages to multiple workers, you will be prompted for an email subject line, the body of the email, and then asked how many workers you will contact. Then, you can enter each WorkerId one-per-line. You can, for example, copy and paste a column of WorkerIds from a text editor or spreadsheet program directly into R. Note: All workers will receive an identical email. This is what the dialog looks like:

Selection: 11
Contact one worker or multiple workers? 

1: Single Worker
2: Multiple Workers

Selection: 2
Email Subject Line: Test Email
Email body text: This is a test email.\n Please disregard.
How many workers to notify: 3
Enter each WorkerId on own line:
1: WorkerId1
2: WorkerId2
3: WorkerId3
Read 3 items

The result is a text-based based email:

Message from Thomas J. Leeper
---------------------------------
This is a test email.\n Please disregard.
---------------------------------

Greetings from Amazon Mechanical Turk,

The message above was sent by an Amazon Mechanical Turk user.
Please review the message and respond to it as you see fit.

Sincerely,
Amazon Mechanical Turk
https://workersandbox.mturk.com
410 Terry Avenue North
SEATTLE, WA 98109-5210 USA

###Option 12: Block Worker

This dialog will allow you to block a worker. A block prevents a worker from completing your HITs (but note that the HITs will still be visible to them in the worker interface). You can only block workers one at a time. You will simply be prompted for their WorkerId and a reason for the block.

###Option 13: Unblock Worker

This dialog will allow you to unblock a worker that you previously blocked. You can only unblock workers one at a time. You will simply be prompted for their WorkerId.

###Option 14: Manage Qualifications

This option opens up a large menu of subsequent options that all relate to Qualifications. That menu looks like:

What would you like to do? 

1: Get Worker(s) By Qualification
2: Assign a Qualification
3: Get a Qualification Score
4: Update Worker(s) Qualification Score
5: Create a QualificationType
6: Update a QualificationType
7: View a QualificationType
8: Search QualificationTypes
9: List Built-In QualificationTypes

These options are intended for more advanced users who are interested in creating QualificationTypes, granting those Qualifications to workers, and managing qualifications.

###Option 15: Requester Statistics

  • Requester Statistics will show you some basic information about your requester account.
  • You can filter your requester statistics based on time
    1. One Day
    2. Last Seven Days
    3. Last Thirty Days
    4. Lifetime of the account
  • This command will return 23 statistics for your account, here is a short list of the sort of data you'll find with this option.
  • Number of Assignments you have running on MTurk (Line 1).
  • Number of HITs you've rejected (Line 5).
  • Number of HITs that have been returned by workers (Line 6).
  • How much money you've paid to workers in US dollars (Line 14).
  • How much money you've paid to workers and Amazon (Line 18).
  • How much money Amazon is holding for uncompleted HITs (Line 23).

###Option 16: Worker Statistics

This dialog will return some statistics about a particular worker that describe their previous work for you (and you only). You will be prompted to enter their WorkerId and then select a time period for the statistics, one of:

  1. OneDay
  2. SevenDays
  3. ThirtyDays
  4. LifeToDate

Some details will then be printed to the console.

###Option 17: Open MTurk RUI Pages

This dialog is simply meant to provide easy access to some of the Requester User Interface pages on the MTurk website. For example, you can open the page to manage a given worker or HIT.

###Option 18: Load MTurkR Log File/Entries

This dialog allows you to view the raw API response for previous MTurk requests. This can be helpful for figuring out what went wrong in a request. You can choose between:

1. View most recent MTurk response
2. View another MTurk response

If you choose 1, the most recent API response will print to the console. If you choose 2, you will be further offered a choice among the last 10 API requests (with the type of response listed in the menu).

.

Clone this wiki locally