Converted from a Word document
Spyral notebooks (voyant-tools.org/spyral) are web-based collaborative documents that combine text and code cells for use in literary textual analysis. Spyral is a companion to Voyant Tools (voyant-tools.org), an online digital text analysis tool. Spyral works with Voyant to allow students and researchers to interact with digital texts, save their analysis, and write accompanying prose to explain their analysis. In this way, a Spyral notebook can be thought of as a digital research notebook. In this paper we demonstrate how Spyral’s interoperability with Voyant makes it a powerful didactic and collaborative research tool. We discuss the design decisions behind Spyral, address criticism and opportunities of notebook environments and provide examples of collaborative projects using Spyral notebooks.
Wickman (2017: 12) defines the research notebook as a "dynamic rhetorical space within which groups of scientists and other stakeholders can present, discuss, revise, and circulate information". Spyral notebooks can be thought of as collaborative research notebooks that allow students and researchers to work through digital text analysis together. Like other notebook environments including Mathematica, Jupyter Notebooks and Google Colab, Spyral notebooks have both code and text cells. The design of Spyral Notebooks was influenced by Donald Knuth’s literate programming paradigm. Knuth (1984: 97) discusses the importance of using commentary in computer coding to explain to human beings what a computer should do. In this way, programmers justify their coding decisions, explain in words what may not be obvious just from looking at code, and in turn write more logical, clearer code. Spyral notebooks provide an accessible space for researchers and students alike to work through their analysis and present that analysis to others.
While notebook environments have become increasingly popular in both the data science and software engineering communities, recent criticism of notebook environments highlights some pain points when using notebooks. Such pain points include issues loading and cleaning data; issues with feedback latency and kernel crashes; lack of IDE support; scalability issues and execution issues when working with large amounts of data; versioning and cataloguing issues; security issues; and challenges with sharing and collaborating as well as reproducing notebooks (Chattopadhyay et. al 2020).
Spyral notebooks are designed to be user friendly for both users who have experience coding and for the novice user. Unlike other notebook environments that use the client-server model and thus require initial set-up, Spyral notebooks are entirely web-based and require only an internet connection. Furthermore, the integration with Voyant Tools means that users’ corpora are stored on the Voyant server. This means anyone with access to the notebook URL will be able to view and interact with the data contained in the notebook without downloading any files to their local computer. This also makes sharing and collaboration easy.
Spyral notebooks are open and freely available, making them the ideal platform for creating tutorials and for using with student text analysis assignments. Spyral notebooks’ interoperability with Voyant Tools make them especially powerful. Students can create a corpus in Voyant and export tool results directly into a Spyral Notebook. The notebook will load with a code block containing the relevant JavaScript code and an interactive Voyant panel. This allows students to both experiment with code, rather than writing it from scratch, and to document their results. An instructor can ask a student to study a text with Voyant and document their findings in a Spyral notebook without the student needing to learn JavaScript.
Following the literate coding paradigm, digital humanities instructors can utilize Spyral notebooks to create functional tutorials for their students. Such tutorials use text blocks to explain the code that follows in code blocks. Students can run code blocks on their own, giving them a chance to engage with code without having to start at square one. By tweaking the code in the code blocks, students quickly grasp the relationship between written code and its output. When students expect an output that they do not receive, they need to think critically to understand what their code is really telling the computer and how to re-write the code to obtain the output they desire. One such tutorial, The Art of Literary Text Analysis written by Stefan Sinclair and Geoffrey Rockwell, walks students through both introductory text analysis concepts and demonstrates how to use JavaScript to manipulate Voyant tools in Spyral. This gives students immediate hands-on experience moving between code and visual outputs.
Spyral provides a path for students and researchers to move from using Voyant interactively to creating research notebooks that document original research. The problem with so many interactive tools is that one is limited by the affordances provided. One cannot easily extend a tool like Voyant without a macro language or a similar tool. Spyral provides a fully functional extension to Voyant that is not a macro language within, but a notebook environment that enfolds Voyant with a fully functional programming language, JavaScript, which one can learn as needed. This allows researchers to pursue original projects and to document those experiments for others to replicate. Humanities researchers can learn by example and as they need to, building on what they get from Voyant.
One such example of collaborative work can be viewed at https://voyant-tools.org/spyral/CovidDiscourse2. This notebook explores discourse around the COVID-19 pandemic in Alberta, Canada as part of a CIFAR funded project. The project brought together a team of medical researchers, digital humanities researchers and computing scientists. By using Spyral, this group of researchers was able to work together to utilise the tools, queries and results from Voyant. Ease of access meant that anyone could examine the tools in the notebook, edit the text blocks, or add their own analysis.
In sum, our paper will introduce the capabilities of Spyral Notebooks for teaching text analysis and as a pathway for humanists developing text analysis projects. We will close by talking about the collaboration between Voyant/Spyral and the LINCS project.