Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/danvk/localturk

Mechanical Turk on your own machine.
https://github.com/danvk/localturk

Last synced: about 16 hours ago
JSON representation

Mechanical Turk on your own machine.

Awesome Lists containing this project

README

        

[![CircleCI](https://circleci.com/gh/danvk/localturk.svg?style=svg)](https://circleci.com/gh/danvk/localturk)

# localturk

Local Turk implements Amazon's Mechanical Turk API on your own machine.

It's handy if you want to:

1. Develop a Mechanical Turk template
2. Do some repetitive tasks on your own, without involving Turkers.

You could use it, for instance, to generate test and training data for a Machine Learning algorithm.

## Quick Start

Install:

npm install -g localturk

Run:

cd localturk/sample
localturk transcribe.html tasks.csv outputs.csv

Then visit http://localhost:4321/ to start Turking.

## Templates and Tasks

Using Local Turk is just like using Amazon's Mechanical Turk. You create:

1. An HTML template file with a <form>
2. A CSV file of tasks

For example, say you wanted to record whether some images contained a red ball. You would make a CSV file containing the URLs for each image:

image_url
http://example.com/image_with_red_ball.png
http://example.com/image_without_red_ball.png

Then you'd make an HTML template for the task:

```html

Has a red ball

Does not have a red ball

```

Finally, you'd start up the Local Turk server:

$ localturk path/to/template.html path/to/tasks.csv path/to/output.csv

Now you can visit http://localhost:4321/ to complete each task. When you're done, the output.csv file will contain

image_url,has_button
http://example.com/image_with_red_ball.png,yes
http://example.com/image_without_red_ball.png,no

## Image Classification

The use case described above (classifying images) is an extremely common one.

To expedite this, localturk provides a separate script for doing image
classification. The example above could be written as:

classify-images --labels 'Has a red ball,Does not have a red ball' *.png

This will bring up a web server with a UI for assigning one of those two labels
to each image on your local file system. The results will go in `output.csv`.

Alternatively, you can also pass in a text file containing the paths to images.
In this case, the images can be URLs, rather than paths to local files.

For more details, run `classify-images --help`.

## Tips & Tricks

It can be hard to remember the exact format for template files. localturk can help! Run it with
the `--write-template` argument to generate a template file for your input that you can edit:

localturk --write-template tasks.csv > template.html

When you're going through many tasks, keyboard shortcuts can speed things up tremendously.
localturk supports these via the `data-key` attribute on form elements. For example, make yourer
submit button look like this:

Now, when you press `d`, it'll automatically click the "Good" button for you. _Note that this
feature is not available on mechanical turk itself!_

If you'd like to reference sensitive data that you'd prefer not to commit to your repo
(an API key, say), you can pass it via a command-line parameter:

localturk --var API_KEY=123456abcd

Then you can reference this as `${API_KEY}` in your template file.

## Development

To make changes to localturk, clone it and set it up using `yarn`:

yarn

You can run `localturk.ts` or `classify-images.ts` directly using `ts-node`:

ts-node localturk.ts path/to/template.html path/to/tasks.csv path/to/output.csv

To type check and run the tests:

yarn tsc
yarn test

To publish a new version on npm, run:

yarn tsc
yarn publish