mturk 1.8.1

data/samples/best_image/best_image.properties

@@ -0,0 +1,39 @@
+######################################
+## Basic HIT Properties
+######################################
+
+Title:Select the best image for a given topic
+Description:The task is to select one image out of three that best represents the provided topic given a set of evaluation criteria.
+Keywords:sample, SDK, best, image
+Reward.Amount:0
+Reward.CurrencyCode:USD
+MaxAssignments:1
+RequesterAnnotation:sample#image
+
+######################################
+## HIT Timing Properties
+######################################
+
+# this Assignment Duration value is 60 * 60 = 1 hour
+AssignmentDurationInSeconds: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
+######################################
+
+# Qualifications can be defined in the properties file instead of in code.
+# You can add multiple qualifications for this HIT by simply increasing the # suffix.
+# i.e. qualification.2: XXXXX
+#      qualification.comparator.2:greaterthan
+
+# 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

data/samples/best_image/best_image.question

@@ -0,0 +1,82 @@
+<?xml version="1.0"?>
+<QuestionForm xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/QuestionForm.xsd">
+  <Overview>
+    <FormattedContent><![CDATA[
+      <h1 align="center">Select the best image</h1>
+      <h2>Instructions</h2>
+      Your task is to select <strong>one</strong> image out of <strong>three</strong> that best represents the provided topic given the evaluation criteria defined below.
+      <br/>It is possible that none of the images can satisfy all the evaluation criteria.  Your goal is to select the best image of the three.
+      <br/>
+      <h3>Evaluation Criteria</h3>
+        <ul>
+          <li>The image should be a representation of the provided topic (i.e. If the topic is Ferris Wheel, you should not select images that are not related to a Ferris Wheel.)</li>
+          <li>The image should be in focus.  (i.e. not blurry)</li>
+          <li>The image should have good color balance.  (i.e. not tinted)</li>
+          <li>The image should be properly exposed.  (i.e. not overexposed/underexposed)</li>
+          <li>The image should be composed well.  (i.e. not skewed)</li>
+          <li>Please refer to the following <a href="http://s3.amazonaws.com/mturk/samples/bestimage/best-image-instructions.html" target="_blank" >link</a> for visual examples of the above criteria.</li>
+        </ul>
+      <h2>Task</h2>
+    ]]></FormattedContent>
+  </Overview>
+  <Question>
+    <QuestionIdentifier>best_image</QuestionIdentifier>
+    <IsRequired>true</IsRequired>
+    <QuestionContent>
+      <FormattedContent><![CDATA[
+      <font size="4" color="darkblue" >Select the image below that best represents: Houses of Parliament, London, England</font>
+      ]]></FormattedContent>
+    </QuestionContent>
+    <AnswerSpecification>
+      <SelectionAnswer>
+        <StyleSuggestion>radiobutton</StyleSuggestion>
+        <Selections>
+          <Selection>
+            <SelectionIdentifier>sample-bestimage-image1.jpg</SelectionIdentifier>
+            <Binary>
+              <MimeType>
+                <Type>image</Type>
+                <SubType>jpg</SubType>
+              </MimeType>
+              <DataURL>http://s3.amazonaws.com/mturk/samples/bestimage/sample-bestimage-image1.jpg</DataURL>
+              <AltText>sample-bestimage-image1.jpg</AltText>
+            </Binary>
+          </Selection>
+          <Selection>
+            <SelectionIdentifier>sample-bestimage-image2.jpg</SelectionIdentifier>
+            <Binary>
+              <MimeType>
+                <Type>image</Type>
+                <SubType>jpg</SubType>
+              </MimeType>
+              <DataURL>http://s3.amazonaws.com/mturk/samples/bestimage/sample-bestimage-image2.jpg</DataURL>
+              <AltText>sample-bestimage-image2.jpg</AltText>
+            </Binary>
+          </Selection>
+          <Selection>
+            <SelectionIdentifier>sample-bestimage-image3.jpg</SelectionIdentifier>
+            <Binary>
+              <MimeType>
+                <Type>image</Type>
+                <SubType>jpg</SubType>
+              </MimeType>
+              <DataURL>http://s3.amazonaws.com/mturk/samples/bestimage/sample-bestimage-image3.jpg</DataURL>
+              <AltText>sample-bestimage-image3.jpg</AltText>
+            </Binary>
+          </Selection>
+        </Selections>
+      </SelectionAnswer>
+    </AnswerSpecification>
+  </Question>
+  <Question>
+    <QuestionIdentifier>comments</QuestionIdentifier>
+    <QuestionContent>
+      <Text>Please help us improve this HIT by including any Questions and/or Comments (optional):</Text>
+    </QuestionContent>
+    <AnswerSpecification>
+      <FreeTextAnswer>
+        <NumberOfLinesSuggestion>10</NumberOfLinesSuggestion>
+      </FreeTextAnswer>
+    </AnswerSpecification>
+  </Question>
+</QuestionForm>

data/samples/blank_slate/BlankSlate.rb

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+
+# Copyright:: Copyright (c) 2007 Amazon Technologies, Inc.
+# License::   Apache License, Version 2.0
+
+begin ; require 'rubygems' ; rescue LoadError ; end
+
+# The BlankSlate sample application disposes all of your HITs on sandbox
+
+require 'mturk'
+@mturk = Amazon::WebServices::MechanicalTurkRequester.new :Host => :Sandbox
+
+def forceExpire(id)
+  print "Ensuring HIT #{id} is expired: "
+  begin
+    @mturk.forceExpireHIT( :HITId => id )
+  rescue => e
+    raise e unless e.message == 'AWS.MechanicalTurk.InvalidHITState'
+  end
+  puts "OK"
+end
+
+def approveRemainingAssignments(id)
+  print "Approving remaining assignments for HIT #{id}: "
+  count = 0
+  @mturk.getAssignmentsForHITAll( :HITId => id ).each do |assignment|
+    @mturk.approveAssignment :AssignmentId => assignment[:AssignmentId] if assignment[:AssignmentStatus] == 'Submitted'
+    count += 1
+  end
+  puts "OK (Approved #{count})"
+end
+
+def dispose(id)
+  print "Disposing HIT #{id}: "
+  @mturk.disposeHIT( :HITId => id )
+  puts "OK"
+end
+
+def purge
+  hit_ids = @mturk.searchHITsAll.collect {|hit| hit[:HITId] }
+  puts "Found #{hit_ids.size} HITs"
+
+  return false if hit_ids.size == 0
+
+  hit_ids.each do |id|
+    begin
+      forceExpire id
+      approveRemainingAssignments id
+      dispose id
+    rescue Exception => e
+      raise e if e.is_a? Interrupt
+      puts e.inspect
+    end
+  end
+  
+  return true
+end
+
+while purge
+  puts 'Ensuring there are no more hits...'
+end
+
+puts 'You now have a blank slate'

data/samples/blank_slate/BlankSlate_multithreaded.rb

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+
+# Copyright:: Copyright (c) 2007 Amazon Technologies, Inc.
+# License::   Apache License, Version 2.0
+
+begin ; require 'rubygems' ; rescue LoadError ; end
+
+# The BlankSlate sample application disposes all of your HITs on sandbox
+
+require 'mturk'
+@mturk = Amazon::WebServices::MechanicalTurkRequester.new :Host => :Sandbox
+require 'amazon/util/threadpool'
+
+def forceExpire(id)
+  @mturk.forceExpireHIT( :HITId => id )
+rescue
+end
+
+def approveRemainingAssignments(id)
+  @mturk.getAssignmentsForHITAll( :HITId => id ).each do |assignment|
+    begin
+      @mturk.approveAssignment :AssignmentId => assignment[:AssignmentId] if assignment[:AssignmentStatus] == 'Submitted'
+    rescue
+    end
+  end
+end
+
+def dispose(id)
+  @mturk.disposeHIT( :HITId => id )
+end
+
+def purge
+  puts "*** starting purge ***"
+  hit_ids = @mturk.searchHITsAllProactive.collect {|hit| hit[:HITId] }
+  puts "Found #{hit_ids.size} HITs"
+
+  return false if hit_ids.size == 0
+
+  threadpool = Amazon::Util::ThreadPool.new(12)
+
+  puts "*** loading work ***"
+  hit_ids.each do |hid|
+    threadpool.addWork(hid) do |id|
+      begin
+        puts "starting #{id}"
+        forceExpire id
+        approveRemainingAssignments id
+        dispose id
+        puts "cleared #{id}"
+      rescue Exception => e
+        raise e if e.is_a? Interrupt
+        puts e.inspect
+      end
+    end
+  end
+  puts "*** finished adding to queue ***"
+
+  threadpool.finish
+  
+  return true
+end
+
+while purge
+  puts 'Ensuring there are no more hits...'
+end
+
+puts 'You now have a blank slate'

data/samples/helloworld/MTurkHelloWorld.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+
+# Copyright:: Copyright (c) 2007 Amazon Technologies, Inc.
+# License::   Apache License, Version 2.0
+
+begin ; require 'rubygems' ; rescue LoadError ; end
+
+# The MTurk Hello World sample application creates a simple HIT via the Mechanical Turk Ruby Libraries.
+
+require 'mturk'
+@mturk = Amazon::WebServices::MechanicalTurkRequester.new :Config => File.join( File.dirname(__FILE__), 'mturk.yml' )
+
+require 'amazon/webservices/mturk/question_generator'
+include Amazon::WebServices::MTurk
+
+def createHelloWorld
+  title = "Answer a question"
+  desc = "This is a HIT created by the Amazon Mechanical Turk SDK for Ruby.  Please answer the question."
+  keywords = "sample, SDK, hello"
+  numAssignments = 1
+  rewardAmount = 0.05 # 5 cents
+
+  question = QuestionGenerator.build(:Basic) do |q|
+    q.ask "What is the weather like right now in Seattle, WA?"
+  end
+
+  puts question
+
+  result = @mturk.createHIT( :Title => title,
+                    :Description => desc,
+                    :MaxAssignments => numAssignments,
+                    :Reward => { :Amount => rewardAmount, :CurrencyCode => 'USD' },
+                    :Question => question,
+                    :Keywords => keywords )
+
+  puts "Created HIT: #{result[:HITId]}"
+  puts "Url: #{getHITUrl( result[:HITTypeId] )}"
+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
+
+# 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
+
+
+createHelloWorld if hasEnoughFunds?

data/samples/helloworld/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/review_policy/ReviewPolicy.rb

@@ -0,0 +1,139 @@
+#!/usr/bin/env ruby
+
+# Copyright:: Copyright (c) 2007 Amazon Technologies, Inc.
+# License::   Apache License, Version 2.0
+
+begin ; require 'rubygems' ; rescue LoadError ; end
+
+# The Review Policy sample application will create a HIT which utilizes review policies
+
+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
+
+def questionXml
+  rootDir = File.dirname $0
+  questionFile = rootDir + "/review_policy.question"
+  question = File.read( questionFile )
+end
+
+# Helper function to convert policy parameters
+def kv_map(hash)
+  hash.collect do |k,v|
+    case v
+    when Hash
+      { :Key => k, :MapEntry => kv_map(v) }
+    else
+      { :Key => k, :Value => v }
+    end
+  end
+end
+
+def createMyHit
+  scoreKnownAnswersPolicy = {
+    :PolicyName => 'ScoreMyKnownAnswers/2011-09-01',
+    :Parameter => kv_map({
+      'ApproveIfKnownAnswerScoreIsAtLeast' => 100,
+      'ApproveReason' => 'You can count',
+      'RejectIfKnownAnswerScoreIsLessThan' => 50,
+      'RejectReason' => 'You flunked math',
+      'ExtendIfKnownAnswerScoreIsLessThan' => 50,
+      'AnswerKey' => { 'q1' => 2, 'q2' => 4 }
+    }),
+  }
+
+  pluralityHitReviewPolicy = {
+    :PolicyName => 'SimplePlurality/2011-09-01',
+    :Parameter => kv_map({
+      'QuestionIds' => ['q3'],
+      'QuestionAgreementThreshold' => 49,
+      'ExtendIfHITAgreementScoreIsLessThan' => 100,
+      'ExtendAssignments' => 1,
+      'ExtendMaximumAssignments' => 10,
+      'ApproveIfWorkerAgreementScoreIsAtLeast' => 100,
+      'RejectIfWorkerAgreementScoreIsLessThan' => 100,
+    }),
+  }
+
+  hit_properties = {
+    :Title       => 'Answer some questions',
+    :Description => 'This is a HIT created by the Mechanical Turk SDK.  Please answer the provided questions.',
+    :Keywords    => '',
+    :Reward => {
+      :CurrencyCode => 'USD',
+      :Amount       => 0.00
+    },
+    :RequesterAnnotation         => 'Test Hit',
+    :AssignmentDurationInSeconds => 60 * 60,
+    :AutoApprovalDelayInSeconds  => 60 * 60 * 10,
+    :MaxAssignments              => 3, # review policy requires multiple assignments per hit
+    :LifetimeInSeconds           => 60 * 60,
+    :Question                    => questionXml,
+    :AssignmentReviewPolicy      => scoreKnownAnswersPolicy,
+    :HITReviewPolicy             => pluralityHitReviewPolicy,
+  }
+  hit = @mturk.createHIT( hit_properties )
+
+  puts "Created HIT: #{hit[:HITId]}"
+  puts "Url: #{getHITUrl( hit[:HITTypeId] )}"
+end
+
+def displayPolicy(name,report)
+  puts "Results for policy #{name}:"
+  [report[:ReviewResult]].flatten.each do |result|
+    q = result[:Key]
+    q += " for #{result[:QuestionId]}" unless result[:QuestionId].to_s == ""
+    puts "- %s %s: %s is %s" % [result[:SubjectType],result[:SubjectId],q,result[:Value]]
+  end unless report[:ReviewResult].nil?
+  puts "Actions for policy #{name}:"
+  [report[:ReviewAction]].flatten.each do |action|
+    puts " - Action %s on %s %s: %s" % [action[:ActionName],action[:ObjectType],action[:ObjectId],action[:ActionStatus]]
+    puts "  Result: #{action[:Result]}"
+  end unless report[:ReviewAction].nil?
+end
+
+def getMyHitResults(hitId)
+  puts "Getting review policy results for HIT #{hitId}"
+  rez = @mturk.getReviewResultsForHIT( :HITId => hitId,
+                                       :PolicyLevel => ['Assignment','HIT'],
+                                       :RetrieveActions => true,
+                                       :RetrieveResults => true,
+                                       :PageNumber => 1,
+                                       :PageSize => 1000 )
+  displayPolicy(rez[:HITReviewPolicy][:PolicyName],rez[:HITReviewReport]) unless rez[:HITReviewPolicy].nil?
+  displayPolicy(rez[:AssignmentReviewPolicy][:PolicyName],rez[:AssignmentReviewReport]) unless rez[:AssignmentReviewPolicy].nil?
+end
+
+def usage
+  puts <<EOF
+Usage:
+  ReviewPolicy.rb
+    This will load a hit configured with sample review policies
+  ReviewPolicy.rb [HitId]
+    This will retrieve review policy information about the identified HIT
+EOF
+end
+
+
+case ARGV.size
+when 0
+  createMyHit if hasEnoughFunds?
+when 1
+  getMyHitResults(ARGV[0])
+else
+  usage
+end