HIST2F90: Money & Power in the Atlantic World

Advanced Voyant Tools Workshop

Big question:

How can we use Voyant Tools to highlight and analyze significant subjects in written sources?
TIP: To answer the big question for this Workshop and for the Voyant Assignment, go beyond the obvious. In past years, for example, a few students found it significant that the most common words in the transcribed texts were "slave" and "slavery", and then proceeded to explain that. We think you'll agree that you do not need the help of a computer program to reach this obvious conclusion!  

Learning outcomes

At the end of this workshop you should be able to:
  • Create a shareable URL of a Voyant Tools output, describe it, and weigh its usefulness and limitations for analyzing a text.
  • Evaluate another person's Voyant Tool output and their analysis (their post).
In your posts, you should be trying to explain the difference between concepts and other kinds of words, and you should demonstrate an understanding of how Voyant Tools can help analyze concepts.

Overview of tasks

Our big question this workshop asks how can we use Voyant tools to highlight significant subjects in texts. In the previous Voyant Workshop, we’ve only used the Cirrus tool. Now we'll explore the program further. In this Workshop you’ll see the program offers several tools for our work of distant reading.
In our Transcription Assignment [NOTE: This assignment is not part of the course in 2021-22], we transcribed two texts that we can now use in Voyant (ready soon). For now we’re also making available the texts that students in previous last year’s transcribed. The goal of the Workshop and of the Voyant assignment and final project is to analyze these texts (the number of texts you use is open – more on this below).
Thinking in terms of a workflow, for this Workshop you will do the following.
  1. From ... [NOTE: dates and these details in points 1-3 are NOT relevant for the 2021-22 course], learn about several tools in Voyant, and practice applying them to the transcribed texts (see Primary Sources below) and create a URL that outputs your best analysis of at least one of the primary sources. You will submit and comment on your URL in the Forum;
    • NOTE: For your Forum post, it's enough for you to export and write about one tool and apply it to one of the texts, but we recommend that you try doing more.
    • For the Voyant Assignment, you will have to write about how you used at least two tools to analyze at least two texts. The Workshop is a good opportunity for you to start experimenting with this more ambitious task.
  2. From ..., comment on at least one of your classmate's URLs in the Forum (provide constructive questions, tips, or other kinds of useful feedback);
  3. Due Date for the Voyant Tools Assignment: .... You will submit the assignment in Sakai.

Questions to consider

In addition to the big question for the Workshop, here is a more specific set of questions to think about:


For this Workshop you'll need to schedule several hours (maybe more) to become familiar with some of Voyant's tools, create a URL to add to the Forum, and explain your URL to your Forum.

You are expected to complete at least two posts to the Forum before the end of the Workshop. See the overview of tasks (above) for details.

This is not a stand-alone activity. In fact, this Workshop is integral to the entire course as the assignments and workshops build on one another. Your data for this workshop will be the files you created in the Transcription Assignment (plus the files that last year's classes created), and your analysis in the Forum for this Workshop will form a starting point for the final major assignment in the course.

[From a previous version of the course...] We'll offer more details about the other assignments after reading week, but for now you should know that the major assignment will ask you to combine "distant reading" via Voyant [i.e. what you're practicing in this Workshop] with "close reading" [i.e. using your eyes and brain to read the conventional pages of texts!]. Our hope is that you'll discover some ways that distant reading enhances close reading, and vice versa.​

A Note about Original Research You Are All Doing in the Course

In this workshop you will use our transcribed and digitized documents to do original historical research. Original historical research is what historians do, and your work is original because very, very few historians have looked closely and carefully at the primary sources that 2F90 students have transcribed. This means that if you do your work well you can make an actual and significant contribution to scholarship! If your work is really good, it might even even be publishable!


Here's a word about a term you should think about in this workshop: concepts. Concepts are ideas, usually abstract ideas, although sometimes they're more like a notion or an assumption. They often appear as simple nouns, but because they're abstract, and because they often derive from other concepts, they are often quite complex. "Democracy" and "nation" are two examples. Their meanings are variable, contested and change over time. Because of this, a standard dictionary definition will almost certainly not help us understand the historically specific meanings of a word that is a concept.

As you'll recall from our first Voyant workshop, when you get your initial output from Voyant, you'll see a Cirrus (word cloud) and several of the terms will stand out as the most frequently used terms. We'd like you to think about what kind of terms these are (i.e., concepts, or not).  Looking at any one term, ask yourself, is this word a person, or a thing (usually a noun)?  Or is this word an action (usually a verb)? Most significantly, we'd like you ask, is this word a concept?

Voyant Tools is really good at showing the reader (you!!!) the frequency of some terms -- terms that might be concepts. Note that not all keywords or concepts in a text will be as useful for you to investigate using Voyant. For example, in a text on slavery, we can expect "slave" and "slavery" to be among the most common terms. We probably don't need Voyant to tell us that.

Voyant is really useful to help you dig deeper. For example, try focusing on words that the cirrus tool shows us are not the first or second, or third, or eighth (or whatever!) most frequent terms. Which of the words in the word cloud might might be the most revealing about the unique point of view in the text? You should begin to hit words that may be clearly conceptual - words that might help us to think about what the author thought about "slavery". In terms of how far you go down that list - first most common word, eighth (etc.) - there's not fixed rule here, except to make sure the word is still commonly used.

"Reading" using Voyant Tools allows us to identify potentially significant concepts in a text very quickly. Of course, we still have to do a good deal of interpretive work, since we have to make judgments about which of the most frequent words are important and meaningful, and then we have to follow up on our initial judgements with further investigations using other tools in Voyant and with close reading of carefully selected passages. The last point is important, because distant reading done quickly and carelessly will very likely lead to poor results. However, distant reading is useful for helping us find significant concepts and passages that deserve closer reading, especially when we have a large text, or a collection of texts. We have both.

Learning activities

The learning activity for this workshop consists of several main parts.

PART 1: Review our first Voyant workshop

You can make progress in this Workshop only if you are well acquainted with the basic skills outlined in our first Workshop. Before you proceed, make sure that you can make a cirrus of a digitized text using Voyant Tools, and that you can export the URL for that analysis.

PART 2: Read some more about how other students have applied Voyant Tools to particular research projects

Recently a professor in the US (Brian Croxall) has written a blog post summarizing the discoveries of his students. These students used Voyant Tools to analyze the HUGE number and amount of short stories of the famous 20th-century writer Ernest Hemingway. The results of these students' experiences might give you some ideas about how you might use Trends and Bubblelines in Voyant Tools to highlight possible subjects of significance in our corpus of texts. See the Secondary Sources for details and a link to the reading. It's not too long.

PART 3: Learn how to use new tools in Voyant Tools

The following instructions are similar to the instructions in the first Voyant Workshop, but we've updated them.

  1. Go to the list of primary sources for the Workshop (at the bottom of this page). Download each of the primary sources to your computer. For the Workshop (and the Voyant Assignment) you can choose which texts you will work with. Make sure you have good reasons for your selections.
    • TIP: Rather than making a random choice, we recommend that you skim through each transcribed text quickly (i.e., read it without using Voyant). Source each document (i.e., pay attention to year of publication, author, and as many clues as you can find about each author's unique perspective and purpose for writing about slavery). You can do this quickly (in just a few minutes) by reading the titles and chapter headings, and maybe just a little bit more in some sections. Try to figure out as much as you can about each text in a few minutes using this method of selective, strategic reading.
  2. Open up the Voyant Tools page at http://voyant-tools.org/.
  3. In the bottom left-hand corner of the input frame, click the Upload tab. Find the place on your computer desktop where you have put the transcribed files. Select the one or more files that you will try reading with Voyant. Once you open them in Voyant, the program should switch to an analysis screen that you'll be familiar with from the first Voyant Workshop.
  4. We have included a Voyant window below that has 7 of the transcribed texts preloaded. You can use this window to start experimenting with more tools and to see what you can discover about the texts. TIP: Before you are ready to export a URL to your Forum, make sure you can customize your selection of tools and texts.
  5. Take a few minutes to look closely at the the initial Voyant output. So far we have focused on the Cirrus. Most initial analysis windows will consist of the Cirrus, the Reader and Trends on a top row, plus Summary and Contexts windows on a bottom row.
    • Notice that each of these windows (plus the main window that has "Voyant Tools" and the Voyant owl) have hidden menus that pop up when you move your cursor over the top right-hand corner of each window frame.
    • These pop-up menus are important. The option with the box and arrow is for exporting your analysis to the Forum. (NOTE: You can also use the export button to open up one of the smaller tool windows in a separate, larger window of your browser.) The option with a four-part box allows you to switch tools for the window frame that you are in.
  6. To learn more the tools that you can use, go to the Voyant Tools documentation page. It's URL is http://docs.voyant-tools.org/tools/. [NOTE: In Dec 2021 these pages need updating; they have recently gone offline; check back here soon for more details]
    • There are more tools here than you can probably master in this Workshop. You are welcome to try as many as you want. Some are more technical than others. We recommend that you focus on the following tools:
    • You can access the input window for each of these tools by clicking on the links immediately above.
    • NOTE: One of the complications in using Voyant this year is that there is a new version of Voyant, but the instructions on the Voyant documentation page apply to the old version. That is why we have included the former names of tools. Try your best to use the old documentation and then experiment with the new version.
      • You can find video tutorials for the older version of Voyant on YouTube. Click the link to go there.
  7. Start experimenting as soon as you can. Let us know about any challenges you might have as you play with the tools and texts. We'll probably provide you with little video tutorials of our own as the Workshop progresses.
  8. Once you have generated some analysis of one, several, or all of the transcribed texts, you should share it with your Forum. Part of your post will explain the steps you took to choose texts, which tools you are exporting and why, and what you think your have discovered in your analysis. If you have encountered a particular problem, or have discovered a trick that you think is useful, share with the group.
  9. To share your Voyant output, go to the top right corner of the window you want to share. Find the export icon. Click it.
  10. In the "Export" window that appears, choose the option "Export View (Tools and Data)".
  11. Then choose the option "an HTML snippet for embedding this view in another web page" ... and then click "Export". A window will pop up.
  12. Copy the text that appears in the window.
  13. Go to the Forum in Sakai and "Start a New Conversation".
  14. Add a title for your post, and then click on the "Source" option in the text frame (it should be on the top left). Once you've selected "Source," paste the details (i.e., the HTML snippet from points 8 and 9) from Voyant there. Then click "post". This will embed your Voyant output in Sakai; if you do not see an active Voyant output window, then you have missed something. For the deadline, see the details at the beginning of the Workshop page.
  15. Finally, write a response to at least one of your peers' posts by the deadline listed above.


INSTRUCTIONS FROM THE ASSIGNMENT FROM SAKAI: For the assignment that is due on the Feb. 14, write 700 to 800 words about how you used at least two tools from Voyant Tools to "pre-read" at least two of the transcribed texts from our Transcription Exercise. Use the primary sources that are in the Workshop on Advanced Skills in Voyant Tools (see below). Your discussion of how you used the tools should focus on pointing out questions worth further analysis, or other subjects of significance that you can discover using the tools. Do NOT focus your assignment on obvious, trivial or banal observations or questions. Do not, for example, bother observing that "slavery" is a common term in books that we all know are about slavery. 

Make sure that you include URLs to the output pages of the data analyses and tools that you are describing.

Voyant output of all 7 transcribed texts [from earlier versions of HIST 2F90]:
To expand this output in a new browser screen, follow these instructions.

Some technical notes

Voyant runs on a supercomputer system. Although it's a very powerful system, it sometimes gets overloaded. If this happens, you might see a window immediately above this text (or in place of your own Voyant analysis) that reports an error instead of the output you expect. If this is the case, DON'T PANIC! The first thing to try is to refresh your screen -- or redo the inputting of texts. If you're not able to get any output, check to see that your browser is up-to-date. If it's not, update it. Another commonsense troubleshooting step to take is to make sure you are connected to the web. Some students last year found that Internet Explorer did not work well with Voyant Tools. Since then Voyant has been updated, and it should now work better with all browsers, but if you're having troubles again and again with Voyant try using it with a different browser (Chrome, Safari, or Firefox generally work well). Voyant Tools can work off-line, but making that possible involves many extra steps.

Primary sources

We intend to include links to the complete, untranscribed texts because there are still gaps and mistakes in our transcribed texts, and you can read the original, untranscribed versions to see the texts as they were printed in the 18th century. You can consult these untranscribed texts if you have questions about what you might be looking at in your Voyant outputs.
Previous classes in HIST 2F90 transcribed and worked with the following documents. Use these for the Workshop.

Secondary sources