Invitation to hack the Distant Reader

We invite you to write a cool hack enabling students & scholars to "read" an arbitrarily large corpus of textual materials.


A website called The Distant Reader takes an arbitrary number of files or links to files as input. [1] The Reader then amasses the files locally, transforms them into plain text files, and performs quite a bit of natural language processing against them. [2] The result -- the the form of a file system -- is a set of operating system independent indexes which point to individual files from the input. [3] Put another way, each input file is indexed in a number of ways, and therefore accessible by any one or combination of the following attributes:

All of things listed above are saved as plain text files, but they have also been reduced to an SQLite database (./etc/reader.db), which is also distributed with the file system.

The Challenge

Your mission, if you choose to accept it, is to write a cool hack against the Distant Reader's output. By doing so, you will be enabling people to increase their comprehension of the given files. Here is a list of possible hacks:

Sample data

In order for you to do your good work, you will need some Distant Reader output, and you can find a number of publicly available "study carrels" at

Helpful hints

With the exception of only a few files (./etc/reader.db, ./etc/reader.vec, and ./cache/*), all of the files in the Distant Reader's output are plain text files. More specifically, they are either unstructured data files or delimited files. Despite any file's extension, the vast majority of the files can be read with your favorite text editor, spreadsheet, or database application. To read the database file (./etc/reader.db), you will need an SQLite application. The files in the adr, bib, ent, pos, urls, or wrd directories are all tab delimited files. A program called OpenRefine is a WONDERFUL tool for reading and analyzing tab delimited files. [9] In fact, a whole lot can be learned through the skillful use of OpenRefine against the tab delimited files.


[1] The home page of the Distant Reader is

[2] All of the code doing this processing is available on GitHub. See

[3] This file system is affectionately known as a "study carrel".

[4] A easy-to-use library for creating such vectors is a part of the Scikit Learn suite of software. See

[5] The algorithm is described at, and a SciKit Learn module is available at

[6] The name of the library is called sql.js and it is available at

[7] The Levenshtein distance is described here --, and various libraries doing the good work are outlined at

[8] Yet another SciKit Learn module may be of use here --

[9] OpenRefine eats delimited files for lunch. See

Eric Lease Morgan <>
July 26, 2019