Grimoire for the Digital Humanities:
The Forbidden Atlas

4. A Gentle Word on Code

Authors: Dr Jon Garber, Dr Mitchell Harrop

This chapter follows on from the gentle introduction to structured data and the gentle reminder about spreadsheets to present a gentle word on code and coding.

Wait, should historians, social scientists and other digital humanists learn to code at all?

Should you perhaps instead learn to collaborate effectively with Computer Scientists? While there are plenty of options in between and some slightly off to the left, let’s keep things simple by focusing on the two extremes. Such a discussion cannot be adequately addressed without considering issues of infrastructure for doing digital work in and across institutions. Often this requires Computer Scientists to run the infrastructure. They install everything and keep it up and running. Where does the labour and fruits of that labour best sit: with a self-taught programmer struggling to work with semi-documented university infrastructure or with a Computer Scientist for which this is all second nature? There’s a much larger discussion here which will slowly be addressed in practical terms in this Grimoire. But put simply, a good collaboration with a Computer Scientist or Software Engineer is one where everyone can write a paper and everyone can contribute intellectually to their respective fields. A poor collaboration is generally one where the non-Computer Scientist is just trying to get some free software development work done. As such, understanding the intellectual motivations of Computer Scientists, Software Engineers and the full spectrum of other technical fields is important for sound collaborations.

For the purposes of largely sidestepping such a debate, this chapter introduces Google’s Colaboratory (Colab) as a means of writing and running Python code without the need to engage a Computer Scientist to install or maintain anything. Google does all that kind of heavy lifting, not a struggling self-taught system administrator who wants to focus on historical research. You just use it. This is also a good option for those dead set on learning to code themselves, as it allows you to fully focus on coding and all of the problems associated with coding. If this sounds like you, we also highly recommend The Programming Historian (ProgrammingHistorian.org) for its peer reviewed tutorials. We’ll direct you to their resources frequently throughout the Grimoire.

4.1 Institutional Python Training

Universities and libraries tend to offer introductory training on Python and/or other coding tools. Garber (2020) “An introduction to Jupyter notebooks and Python” is one such online introduction from The University of Melbourne. This introduction will serve as a stand-in or exemplar for other institutional training. Obviously if you want to go do the Garber training yourself, by all means go ahead. It's probably the greatest python training ever created, according to one of the authors (Garber) of this chapter.

Typically such institutional training offers automation as a rationale for using code. This is often juxtaposed to ... ... PREVIEW ONLY ...

... PREVIEW ONLY ...

We have imported math on line 1. We have used math on line 2 to calculate the square root of 64 (sqrt). But it’s not all simple mathematics, you can import stuff that does some very complicated things:


1 import plotly.express as plxprs
2 data = plxprs.data.gapminder()
3 figure = plxprs.scatter_geo(data, locations="iso_alpha", size="pop", animation_frame="year")
4 figure.show()
World map with time slider

Line 1 imports the express part of plotly, which allows us to quickly plot a map. Line 2 grabs the Gapminder dataset. If you haven’t seen the Gapminder TED talk (Rosling, 2006), we strongly recommend it. It is an important milestone in the modern field of visualisation. Line 3 creates the map using the population by year from the Gapminder dataset. Line 4 renders the map in the code output. The play button in the output changes the map every second or so to progress through the years. Thus you can see populations (circles) grow over time.

Software Engineers love to break up bigger problems into smaller problems. Importing code is all about importing the solutions to those smaller problems and using them for your own nefarious purposes. In this Grimoire, we will import code to process text, to extract locations from spoken word, to process CSV, TSV, XML and other structured data files. We will import code to make maps. All are solved problems. They are solved by someone else. A lot of Software Engineering is trying to work out what the solved problems are and finding them online so that you can put them all together into your own concoction. ... PREVIEW ONLY ...

Next: 5. My Marvellous Melbourne Podcast Locator Spell