psiTurk Documentation

Website:https://psiturk.org Source code:https://github.com/NYUCCL/psiturk Issue tracker:https://github.com/NYUCCL/psiturk/issues Usage questions:  https://groups.google.com/forum/#!forum/psiturk Twitter:https://twitter.com/psiturk

Note

This is documentation for psiturk v3. Documentation for psiturk v2 can be found here.

Welcome to psiTurk’s documentation. To learn more about the project, please visit https://psiturk.org.

To actually use psiTurk, you’ll first need to install it on your local computer or server. Instructions can be found on the Installation page. Afterwards, head over to our Quickstart.

For a more detailed tutorial demonstrating how to setup a simple experiment with psiTurk, visit Example project walkthrough. Also, check out the Experiment Exchange for examples to learn from, including demonstrations of integration with jspsych.

Migrating from psiturk 2 to psiturk 3? See the Migrating from psiTurk 2 to 3 guide.

User’s Guide

• Forward
  • Understanding the psiTurk design philosophy: An analogy
  • What is Mechanical Turk?
  • Why psiTurk?
  • Basic Requirement: A publicly-accessible server
  • Do I have to learn how to code?
• Quickstart
  • Step 1: Install psiTurk
  • Step 2: Create a default project structure
  • Step 3: Enter credentials
  • Step 4: Launch psiTurk in the new project directory
  • Step 5: Start the server
  • Step 6: Debug/view your experiment
  • Step 7: Create a sandboxed HIT/Ad
  • Step 8: Check your data
  • Step 9: Monitor progress
  • Step 10: Approve workers
  • Step 11: Switch to “live” mode
• Migrating from psiTurk 2 to 3
  • Announcing psiTurk 3.0
  • Migration technical considerations
• Installation
  • From Source
  • Running inside a Virtual Environment
  • System-specific notes
• Setting Up an Amazon Mechanical Turk Account
  • Accounts Creation and Linking
  • AWS Credentials
• Configuration Overview
  • Which go where? Consider security and privacy, as well as science replicability
  • Local configuration file
  • The .psiturkconfig global config file
• Settings
  • HIT Configuration
  • Database Parameters
  • Server Parameters
  • Task Parameters
  • Shell Parameters
• Command-line Interface Overview
  • Options
  • Command invocation
  • Launch an interactive shell
  • Create an Example Project
• psiTurk commands
  • amt_balance
  • config
  • debug
  • download_datafiles
  • help
  • hit
  • worker
  • quit
  • server
  • status
  • mode
• Databases Overview
  • Using SQLite
  • Using a postgresql database on Heroku
  • Using a SQL database server
• Tutorials
  • Example project walkthrough
  • Running psiTurk on Heroku
  • Hosting your own HTTPS Experiment
  • Using external survey tools with psiTurk
• Anatomy of a basic psiTurk project
  • config.txt
  • custom.py
  • participants.db
  • server.log
  • The static/ directory
  • The templates/ directory
• Recording Data
  • Types of Data
  • Saving the data
• Retrieving Data
  • Methods
  • How the datastring is structured
• Customizing psiTurk
  • Example: Automatically computing performance bonus
  • The basic logic of using custom.py
  • Tips about debugging your custom route
• Dashboard Overview
  • Dynamic Filtered Table
  • Batch Actions
  • Campaigns
  • Tasks
  • Configuration
• Experiment Exchange
  • Contributing to the exchange
  • Browse experiments for study or replication
• Frequently Asked Questions
  • How do I host a psiTurk experiment for MTurkers?
  • I’m trying to run psiTurk at home using a cable modem or other connection. Will it work?
  • My university will not give me a static IP address. Can I still use psiTurk?
  • I insist on running my experiment from my home, despite the insanity of doing the same.
  • Can I use psiTurk for non-MTurk studies?
  • There was an error in my experiment and I need to pay participants, but I can’t because they weren’t able to complete my HIT. How can I pay them?
  • Why doesn’t psiTurk work on Windows?
  • I need an experiment to do X, will psiTurk be able to do this?
  • I’m having trouble with my AWS/AMT credentials
  • Can you program my experiment for me?
  • I’m having Javascript errors when designing my experiment. Can you help?
  • Where is the /static/js/psiturk.js file? It doesn’t appear in any of the experiments I have downloaded!
  • How do I interpret the hit list counts of “Pending,” “Complete,” and “Remain”?
  • Immediately after I post my HIT on the “live” mode of AMT, I cannot find it via an mturk dashboard search?
  • Why does my server keep crashing when I try to start it via psiturk server on?
• Getting help
• Disclaimer

Contributing to psiTurk

• Contributing to psiTurk
  • Contribution guidelines
  • Decision process
• Project Roadmap
  • General priorities
  • Version 3.0

API Reference

• psiturk.js API
  • Creating the psiTurk object
  • psiturk.taskdata
  • psiturk.preloadPages(pagelist)
  • psiturk.getPage(pagename)
  • psiturk.showPage(pagename)
  • psiturk.preloadImages(imagelist)
  • psiturk.recordTrialData(datalist)
  • psiturk.recordUnstructuredData(field, value)
  • psiturk.saveData([callbacks])
  • psiturk.completeHIT()
  • psiturk.doInstructions(pages, callback)
  • psiturk.finishInstructions()

Citing

See the github repo README for how to cite usage of psiTurk.

License

See the LICENSEFILE on github.