dbgrandi-ruby-aws 1.2.0

data/samples/mturk/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/mturk/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/mturk/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 'ruby-aws'
+@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/mturk/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 'ruby-aws'
+@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/mturk/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 Libraries for Amazon Web Services.
+
+require 'ruby-aws'
+@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/mturk/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/mturk/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 'ruby-aws'
+@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.exists? @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/mturk/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/mturk/simple_survey/SimpleSurvey.rb

@@ -0,0 +1,90 @@
+#!/usr/bin/env ruby
+
+# Copyright:: Copyright (c) 2007 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 'ruby-aws'
+@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 creating a qualification.
+  # This is a built-in qualification -- user must be based in the US
+  qualReq = { :QualificationTypeId => Amazon::WebServices::MechanicalTurkRequester::LOCALE_QUALIFICATION_TYPE_ID,
+              :Comparator => 'EqualTo',
+              :LocaleValue => {:Country => 'US'}, }
+
+  # The create HIT method takes in an array of QualificationRequirements since a HIT can have multiple qualifications.
+  qualReqs = [qualReq]
+
+  # 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?