mturk 1.8.1

data/samples/review_policy/review_policy.question

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<QuestionForm xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/QuestionForm.xsd">
+  <Question>
+    <QuestionIdentifier>q1</QuestionIdentifier>
+    <QuestionContent>
+      <Text>What is 1 + 1?</Text>
+    </QuestionContent>
+    <AnswerSpecification>
+      <FreeTextAnswer/>
+    </AnswerSpecification>
+  </Question>
+  <Question>
+    <QuestionIdentifier>q2</QuestionIdentifier>
+    <QuestionContent>
+      <Text>What is 2 + 2?</Text>
+    </QuestionContent>
+    <AnswerSpecification>
+      <FreeTextAnswer/>
+    </AnswerSpecification>
+  </Question>
+  <Question>
+    <QuestionIdentifier>q3</QuestionIdentifier>
+    <QuestionContent>
+      <Text>What color is the sky?</Text>
+    </QuestionContent>
+    <AnswerSpecification>
+      <FreeTextAnswer/>
+    </AnswerSpecification>
+  </Question>
+</QuestionForm>

data/samples/reviewer/Reviewer.rb

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+
+# Copyright:: Copyright (c) 2007 Amazon Technologies, Inc.
+# License::   Apache License, Version 2.0
+
+begin ; require 'rubygems' ; rescue LoadError ; end
+
+# The Reviewer sample application will retrieve the completed assignments for a given HIT,
+# output the results and approve the assignment.
+#
+# mturk.yml is used to configure default settings ( must be in the same directory as Reviewer.rb )
+# You will need to have the HIT ID of an existing HIT that has been accepted, completed and
+# submitted by a worker.
+# Or you can use the .success file generated from bulk loading several HITs (i.e. Site Category sample application).
+#
+# The following concepts are covered:
+# - Retrieve results for a HIT
+# - Output results for several HITs to a file
+# - Approve assignments
+
+require 'mturk'
+@mturk = Amazon::WebServices::MechanicalTurkRequester.new :Config => File.join( File.dirname(__FILE__), 'mturk.yml' )
+
+# Prints the submitted results of HITs when provided with a .success file.
+# successFile:: The .success file containing the HIT ID and HIT Type ID
+# outputFile:: The output file to write the submitted results to
+def printResults( successFile,  outputFile)
+
+  # Loads the .success file containing the HIT IDs and HIT Type IDs of HITs to be retrieved.
+  success = Amazon::Util::DataReader.load( successFile, :Tabular )
+
+  # Retrieves the submitted results of the specified HITs from Mechanical Turk
+  results = @mturk.getHITResults(success)
+
+  # parse answers to they're easier to digest
+  results.each { |assignment| assignment[:Answers] = @mturk.simplifyAnswer( assignment[:Answer] ) }
+
+  # Writes the submitted results to the defined output file.
+  # The output file is a tab delimited file containing all relevant details
+  # of the HIT and assignments.  The submitted results are included as the last set of fields
+  # and are represented as tab separated question/answer pairs
+  Amazon::Util::DataReader.save( outputFile, results, :Tabular )
+  puts "Results have been written to: #{outputFile}"
+
+end
+
+# Prints the submitted results of a HIT when provided with a HIT ID.
+# hitId:: The HIT ID of the HIT to be retrieved.
+def reviewAnswers( hitId )
+  assignments = @mturk.getAssignmentsForHITAll( :HITId => hitId, :AssignmentStatus => 'Submitted')
+
+  puts "--[Reviewing HITs]----------"
+  puts "  HIT Id: #{hitId}"
+
+  assignments.each do |assignment|
+
+    # By default, answers are specified in XML
+    answerXML = assignment[:Answer]
+
+    # Calling a convenience method that will parse the answer XML and extract out the question/answer pairs.
+    answers = @mturk.simplifyAnswer( answerXML )
+
+    answers.each do |id,answer|
+      assignmentId = assignment[:AssignmentId]
+      puts "Got an answer \"#{answer}\" for \"#{id}\" from worker #{assignment[:WorkerId]}"
+    end
+
+    # Approving the assignment
+    @mturk.approveAssignment(:AssignmentId => assignment[:AssignmentId], :RequesterFeedback => "Well Done!")
+    puts "Approved."
+
+  end
+  puts "--[End Reviewing HITs]----------"
+end
+
+require 'optparse'
+hitsToReview = []
+opts = OptionParser.new
+opts.on( '--review HITId', 'Review Answers for a single HIT ( can be specified multiple times)') {|hit| hitsToReview << hit ; @review = true }
+opts.on( '--results', 'Print Results using input and output files') { @getResults = true }
+opts.on( '--input FILE', 'Input File to get results') {|file| @inputFile = file }
+opts.on( '--output FILE', 'Output File to save results') {|file| @outputFile = file }
+
+begin
+  opts.parse ARGV
+  raise "Please, either --review or --results, not both" if @review && @getResults
+  raise "Pick something to do ( either --review or --results )" unless @review || @getResults
+  if @getResults
+    raise "missing input file" unless @inputFile
+    raise "missing output file" unless @outputFile
+    raise "input file does not exist: #{@inputFile}" unless File.exist? @inputFile
+  end
+rescue => e
+  puts e.message
+  puts opts.to_s
+  exit
+end
+
+if @getResults
+  printResults( @inputFile, @outputFile )
+elsif @review
+  hitsToReview.each {|h| reviewAnswers(h) }
+end

data/samples/reviewer/mturk.yml

@@ -0,0 +1,8 @@
+# Your AWSAccessKeyId ( leave commented to use global default )
+# AWSAccessKeyId: <need access key id>
+
+# Your AWSAccessKey ( leave commented to use global default )
+# AWSAccessKey: <need access key>
+
+# Host to talk to ( Prod or Sandbox )
+Host: Sandbox

data/samples/simple_survey/SimpleSurvey.rb

@@ -0,0 +1,98 @@
+#!/usr/bin/env ruby
+
+# Copyright:: Copyright (c) 2007-2014 Amazon Technologies, Inc.
+# License::   Apache License, Version 2.0
+
+begin ; require 'rubygems' ; rescue LoadError ; end
+
+# The Simple Survey sample application will create a HIT asking a worker to indicate their
+# political party preferences.
+#
+# mturk.properties must be found in the current file path.
+#
+# The following concepts are covered:
+# - File based QuestionForm HIT loading
+# - Using a locale qualification
+
+require 'mturk'
+@mturk = Amazon::WebServices::MechanicalTurkRequester.new
+
+
+# Check to see if your account has sufficient funds
+def hasEnoughFunds?
+  available = @mturk.availableFunds
+  puts "Got account balance: %.2f" % available
+  return available > 0.055
+end
+
+def getHITUrl( hitTypeId )
+  if @mturk.host =~ /sandbox/
+    "http://workersandbox.mturk.com/mturk/preview?groupId=#{hitTypeId}" # Sandbox Url
+  else
+    "http://mturk.com/mturk/preview?groupId=#{hitTypeId}" # Production Url
+  end
+end
+
+# Creates the simple survey.
+def createSimpleSurvey
+  title = "What is your political preference?"
+  description = "This is a simple survey HIT created by the Amazon Mechanical Turk SDK for Ruby."
+  numAssignments = 1
+  reward = { :Amount => 0.05, :CurrencyCode => 'USD' }
+  keywords = "sample, SDK, survey"
+  assignmentDurationInSeconds = 60 * 60 # 1 hour
+  autoApprovalDelayInSeconds = 60 * 60 # 1 hour
+  lifetimeInSeconds = 60 * 60 # 1 hour
+  requesterAnnotation = "sample#survey"
+
+  # Defining the location of the externalized question (QuestionForm) file.
+  rootDir = File.dirname $0
+  questionFile = rootDir + "/simple_survey.question"
+		
+
+  # This is an example of using qualification requirements.
+  # This is a built-in qualification -- user must be based in the Washington (US state), Maryland (US state), Canada, or Great Britain
+  locationQualReq = { :QualificationTypeId => Amazon::WebServices::MechanicalTurkRequester::LOCALE_QUALIFICATION_TYPE_ID,
+                      :Comparator => 'In',
+                      :LocaleValue => [{:Country => 'US', :Subdivision => 'WA'},
+                                       {:Country => 'US', :Subdivision => 'MD'},
+                                       {:Country => 'CA'},
+                                       {:Country => 'GB'}] }
+
+  # This is a built-in qualification -- user must have had greater than 1000 HTIs approved
+  numHITsApprovedQualReq = { :QualificationTypeId => Amazon::WebServices::MechanicalTurkRequester::NUMBER_OF_HITS_APPROVED_QUALIFICATION_TYPE_ID,
+                             :Comparator => 'GreaterThan',
+                             :IntegerValue => 1000 }
+
+  # The create HIT method takes in an array of QualificationRequirements since a HIT can have multiple qualifications.
+  qualReqs = [locationQualReq, numHITsApprovedQualReq]
+
+  # Loading the question (QuestionForm) file
+  question = File.read( questionFile )
+
+  # Creating the HIT and loading it into Mechanical Turk
+  hit = @mturk.createHIT( :Title => title,
+                          :Description => description,
+                          :Keywords => keywords,
+                          :Question => question,
+                          :Reward => reward,
+                          :AssignmentDurationInSeconds => assignmentDurationInSeconds,
+                          :AutoApprovalDelayInSeconds => autoApprovalDelayInSeconds,
+                          :LifetimeInSeconds => lifetimeInSeconds,
+                          :MaxAssignments => numAssignments,
+                          :RequesterAnnotation => requesterAnnotation,
+                          :QualificationRequirement => qualReqs )
+
+  puts "Created HIT: #{hit[:HITId]}"
+  puts "Url: #{getHITUrl( hit[:HITTypeId] )}"
+
+  # Demonstrates how a HIT can be retrieved if you know its HIT ID
+  hit2 = @mturk.getHIT(:HITId => hit[:HITId])
+
+  puts "Retrieved HIT: #{hit2[:HITId]}"
+
+  puts "Oops!  The HIT Ids shoud match: #{hit[:HITId]}, #{hit2[:HITId]}" unless hit[:HITId] == hit2[:HITId]
+
+end
+
+createSimpleSurvey if hasEnoughFunds?

data/samples/simple_survey/simple_survey.question

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<QuestionForm xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/QuestionForm.xsd">
+  <Question>
+    <QuestionIdentifier>1</QuestionIdentifier>
+    <QuestionContent>
+      <Text>What is your political party affiliation?</Text>
+    </QuestionContent>
+    <AnswerSpecification>
+      <SelectionAnswer>
+        <MinSelectionCount>1</MinSelectionCount>
+        <MaxSelectionCount>1</MaxSelectionCount>
+        <StyleSuggestion>radiobutton</StyleSuggestion>
+        <Selections>
+          <Selection>
+            <SelectionIdentifier>republican</SelectionIdentifier>
+            <Text>Republican</Text>
+          </Selection>
+          <Selection>
+            <SelectionIdentifier>democrat</SelectionIdentifier>
+            <Text>Democrat</Text>
+          </Selection>
+		  <Selection>
+            <SelectionIdentifier>noneoftheabove</SelectionIdentifier>
+            <Text>None of the Above</Text>
+          </Selection>
+        </Selections>
+      </SelectionAnswer>
+    </AnswerSpecification>
+  </Question>
+</QuestionForm>

data/samples/site_category/SiteCategory.rb

@@ -0,0 +1,87 @@
+#!/usr/bin/env ruby
+
+# Copyright:: Copyright (c) 2007 Amazon Technologies, Inc.
+# License::   Apache License, Version 2.0
+
+begin ; require 'rubygems' ; rescue LoadError ; end
+
+# The Site Category sample application will create 5 HITs asking workers to categorize websites into predefined categories.
+#
+# The following concepts are covered:
+# - Bulk load HITs using an input file
+# - File based HIT loading
+
+require 'mturk'
+@mturk = Amazon::WebServices::MechanicalTurkRequester.new
+
+# Check to see if your account has sufficient funds
+def hasEnoughFunds?
+  available = @mturk.availableFunds
+  puts "Got account balance: %.2f" % available
+  return available > (0.055 * 5)
+end
+
+def getHITUrl( hitTypeId )
+  if @mturk.host =~ /sandbox/
+    "http://workersandbox.mturk.com/mturk/preview?groupId=#{hitTypeId}" # Sandbox Url
+  else
+    "http://mturk.com/mturk/preview?groupId=#{hitTypeId}" # Production Url
+  end
+end
+
+# Create the website category HITs.
+def createSiteCategoryHITs
+
+  # Defining the locations of the input files
+  rootDir = File.dirname $0
+  inputFile = rootDir + "/site_category.input"
+  propertiesFile = rootDir + "/site_category.properties"
+  questionFile = rootDir + "/site_category.question"
+
+  # Loading the input file.  The input file is a tab delimited file where the first row
+  # defines the fields/variables and the remaining rows contain the values for each HIT.
+  # Each row represents a unique HIT.  ERB is used to merge the values into the Question template.
+  input = Amazon::Util::DataReader.load( inputFile, :Tabular )
+
+  # Loading the question (QuestionForm) file
+  question = File.read( questionFile )
+
+  # Loading the HIT properties file.  The properties file defines two system qualifications that will
+  # be used for the HIT.  The properties file can also be an ERB template.  This allows the developer
+  # to "tie in" the input value to the results.
+  props = Amazon::Util::DataReader.load( propertiesFile, :Properties )
+
+  hits = [];
+
+  # Create multiple HITs using the input, properties, and question files
+
+  puts "--[Loading HITs]----------"
+  startTime = Time.now
+  puts "  Start time: #{startTime}"
+
+  # The simpliest way to bulk load a large number of HITs where all details are defined in files.
+  # This method returns a hash with two arrays:
+  # - :Created is an array of successfully created HITs
+  # - :Failed is an array of lines we failed to create HITs with
+  hits = @mturk.createHITs(props, question, input);
+
+  puts "--[End Loading HITs]----------"
+  endTime = Time.now
+  puts "  End time: #{endTime}"
+  puts "--[Done Loading HITs]----------"
+  puts "  Total load time: #{ endTime - startTime } seconds."
+
+  hit_ids = hits[:Created].collect {|h| h[:HITId] }
+  hit_type_id = hits[:Created].first[:HITTypeId]
+
+  puts "  Created HITs: #{hit_ids.join(' ')}"
+  puts "  Url: #{getHITUrl( hit_type_id )}"
+
+  # We'll save the results to hits.success and hits.failure
+  Amazon::Util::DataReader.save( rootDir + "/hits.success", hits[:Created], :Tabular )
+  Amazon::Util::DataReader.save( rootDir + "/hits.failure", hits[:Failed], :Tabular )
+  # The .success file can be used in subsequent operations to retrieve the results that workers submitted.
+
+end
+
+createSiteCategoryHITs if hasEnoughFunds?

data/samples/site_category/externalpage.htm

@@ -0,0 +1,71 @@
+<!-- This file needs to be hosted on an external server.  -->
+<html>
+<script language="Javascript">
+//
+// This method Gets URL Parameters (GUP)
+//
+function gup( name )
+{
+  var regexS = "[\\?&]"+name+"=([^&#]*)";
+  var regex = new RegExp( regexS );
+  var tmpURL = window.location.href;
+  var results = regex.exec( tmpURL );
+  if( results == null )
+    return "";
+  else
+    return results[1];
+}
+
+//
+// This method decodes the query parameters that were URL-encoded
+//
+function decode(strToDecode)
+{
+  var encoded = strToDecode;
+  return unescape(encoded.replace(/\+/g,  " "));
+}
+
+</script>
+<body>
+<form id="mturk_form" method="POST" action="http://www.mturk.com/mturk/externalSubmit">
+<input type="hidden" id="assignmentId" name="assignmentId" value="">
+<table border="0" height="100%" width="100%">
+<tr><td>
+<h1>What type of webpage is shown below?</h1>
+<p>
+<input type="radio" name="category" value="news">&nbsp;News Site<br>
+<input type="radio" name="category" value="search">&nbsp;Search Engine<br>
+<input type="radio" name="category" value="retail">&nbsp;Online Retailer<br>
+<input type="radio" name="category" value="other" selected>&nbsp;Other<br>
+<p>
+<input id="submitButton" type="submit" name="Submit" value="Submit">
+<p>
+</td></tr>
+<tr><td height="100%">
+<iframe id="pageFrame" width="100%" height="100%"></iframe>
+</td></tr>
+</table>
+</form>
+<script language="Javascript">
+    document.getElementById('pageFrame').src = decode(gup('url'));
+    document.getElementById('assignmentId').value = gup('assignmentId');
+
+
+    //
+    // Check if the worker is PREVIEWING the HIT or if they've ACCEPTED the HIT
+    //
+    if (gup('assignmentId') == "ASSIGNMENT_ID_NOT_AVAILABLE")
+    {
+  // If we're previewing, disable the button and give it a helpful message
+  document.getElementById('submitButton').disabled = true;
+  document.getElementById('submitButton').value = "You must ACCEPT the HIT before you can submit the results.";
+    } else {
+        var form = document.getElementById('mturk_form');
+        if (document.referrer && ( document.referrer.indexOf('workersandbox') != -1) ) {
+            form.action = "http://workersandbox.mturk.com/mturk/externalSubmit";
+        }
+    }
+
+</script>
+</body>
+</html>

data/samples/site_category/site_category.input

@@ -0,0 +1,6 @@
+urls
+https://www.reuters.com/
+https://www.google.com/
+https://www.amazon.com/
+https://www.apple.com/
+https://www.yahoo.com/

data/samples/site_category/site_category.properties

@@ -0,0 +1,56 @@
+######################################
+## External HIT Properties
+######################################
+
+Title:What website is this?
+Description:Please look at this website and tell us, in simple words, what website this is.
+Keywords:category, website, SDK, sample
+Reward.Amount:0.05
+Reward.CurrencyCode:USD
+MaxAssignments:1
+
+#Notice the use of ERB template directives here.  
+#This allows the input file to define the value of the HIT level annotation field. 
+RequesterAnnotation:<%= @urls %>
+
+######################################
+## HIT Timing Properties
+######################################
+
+# this Assignment Duration value is 60 * 60 = 1 hour
+AssignmentDuration:3600
+
+# this HIT Lifetime value is 60 * 60 = 1 hour
+LifetimeInSeconds:3600
+
+# this Auto Approval period is 60 * 60 = 1 hour 
+AutoApprovalDelayInSeconds:3600
+
+######################################
+## Qualification Properties
+######################################
+
+# In this example, two system qualifications and one location qualification are specified for the HIT.
+
+# this is a built-in qualification -- user must have an approval rate of 25% or greater
+QualificationRequirement.1.QualificationTypeId:000000000000000000L0
+QualificationRequirement.1.Comparator:GreaterThan
+QualificationRequirement.1.IntegerValue:25
+QualificationRequirement.1.RequiredToPreview:false
+
+# this is a built-in qualification -- user must have an abandonment rate of 50% or less
+QualificationRequirement.2.QualificationTypeId:00000000000000000070
+QualificationRequirement.2.Comparator:LessThan
+QualificationRequirement.2.IntegerValue:51
+QualificationRequirement.2.RequiredToPreview:true
+
+# this is a built-in qualification -- user must be based in Washington (US state), Maryland (US state), Canada, or Great Britain
+QualificationRequirement.3.QualificationTypeId:00000000000000000071
+QualificationRequirement.3.Comparator:In
+QualificationRequirement.3.LocaleValue.1.Country:US
+QualificationRequirement.3.LocaleValue.1.Subdivision:WA
+QualificationRequirement.3.LocaleValue.2.Country:US
+QualificationRequirement.3.LocaleValue.2.Subdivision:MD
+QualificationRequirement.3.LocaleValue.3.Country:CA
+QualificationRequirement.3.LocaleValue.4.Country:GB
+QualificationRequirement.3.RequiredToPreview:true