Skip to contents

Welcome to the main website of humdrum!

What is humdrum?

Humdrum is an R package: a “library” of preexisting code for the R programming language. Humdrum code provides tools for the visualization, manipulation, and analysis of data formatted in the humdrum syntax.

Note: The name of the package is pronounced hum-drum-ARRRRR, with the last syllable emphasized in pirate fashion. The name should always be typeset hμmΔrμm. Failure to pronounce or typeset hμmΔrμm correctly will void the warranty.

What is humdrum?

Humdrum is a system for computational musicology developed by David Huron. The Humdrum “ecosystem” includes two main parts: a data format called the humdrum syntax and a musicological software system called the humdrum toolkit. Another key component of the ecosystem is the Verovio Humdrum Viewer, which is a great way to get to view and edit humdrum data. Humdrum is a complement to the original humdrum toolkit, leveraging the power of R to give us unprecedented power to manipulate and analyze humdrum data using concise, expressive syntax.

Humdrum is mainly used to manipulate and analyze data encoded in the humdrum syntax and/or humdrum interpretations like **kern. The humdrum syntax is an incredibly flexible, and powerful, scheme for encoding musical data. Tens of thousands of musical scores (and other musical data) have been encoded in the humdrum syntax, many available online through repositories such as KernScores. Our humdrum syntax vignette gives a detailed introduction to the data format.

What is R?

R is programming language, designed from the ground up for statistical computing and data analysis. R has many features which make it ideal for data analysis, particularly if research and analysis is your only background in programming. Our R primer introduces the core concepts of R programming.

What can humdrum do?

Humdrum provides a number of tools for working with humdrum data and more generally, musicological analysis. Humdrum does seven main things:

Represent humdrum data in R

To represent humdrum data in R, humdrum defines a special data type—the humdrumR class—which we call “humdrumR objects” throughout the documentation. The most important part of a humdrumR object is the “humdrum table” which it contains. You can read about how the humdrum-syntax data is represented in the getting started with humdrumR vignette.

For more details, read the humdrumR class and humdrum table; If humdrum is installed and loaded, you can read these directly in an R session by typing ?humdrumR-class or ?humTable.

Read and write humdrum data

To create humdrumR data objects, humdrum includes a humdrum data parser, which finds humdrum data on your local machine, reads it into R, then creates a humdrumR object from the data. The Reading and writing data vignette is the best place to realm how this works. You can get more details from the readHumdrum() and writeHumdrum() documentation; If humdrum is installed and loaded, you can read these directly in an R session by typing ?readHumdrum or ?writeHumdrum.

“Reshape” humdrum data

Once you’ve imported humdrum data in R, the next step is often to organize and prepare your data. You’ll often want to pick out specific subsets of the data, or rearrange the data representations to be easier to work with. Humdrum gives us a number of powerful tools for “shaping the data”: The Shaping humdrum data and Filtering humdrum data vignettes are the best places to learn about these processes. You can find more details on sub-setting data in the subset.humdrumR() and indexHumdrum documentation; If humdrum is installed and loaded, you can read these directly in an R session by typing ?subset.humdrumR or ?indexHumdrum.

Analyze humdrum data

Humdrum makes it very easy to manipulate, modify, and analyze humdrum data. The Working with humdrum data vignette gives an overview of this functionality. You can find more details in the withinHumdrum documentation; If humdrum is installed and loaded, you can read this directly in an R session by typing ?withinHumdrum.

Manipulate (musical) pitch information

Humdrum defines tools for manipulating numerous representations of pitch and tonality, including diatonic keys and tertian harmonies. The Pitch and tonality vignette explains how to work with pitch data in humdrum. You can find more details in the humdrumPitch documentation; If humdrum is installed and loaded, you can read this directly in an R session by typing ?humdrumPitch.

Manipulate (musical) rhythm information

Humdrum defines tools for manipulating numerous representations of rhythm, timing, and meter. The Rhythm and meter vignette explains how to work with rhythmic information humdrum. You can find more details in the humdrumRhythm documentation; If humdrum is installed and loaded, you can read this directly in an R session by typing ?humdrumRhythm.

Develop new humdrum tools

To facilitate the development of new functions to work with humdrum tokens—which are simple character strings packed with information—, Humdrum provides several useful development tools, including our struct data type and a useful API we call our regular-expression dispatch system, which makes it easy to dispatch different methods based on matches to regular expressions.

Installing humdrum

Installing R

To use humdrum, you’ll first need to install R, version 4.1 or later. We highly recommend that you install the Integrated Development Environment RStudio as well! This link—Installing R and RStudio—is a good starting place.

Installing humdrum

Humdrum is not yet available on the standard R package repository, CRAN, so (for now) it can only be installed from this github repository. To install the latest version (master branch) of humdrum, you’ll first need to install the R package devtoolsdevtools is used for creating and maintaining R packages. Luckily, devtools is on CRAN, so all you have to do is open an R session on your machine and type:


install.packages('devtools')

Once you have successfully installed devtools, you are now ready to use it to install humdrum straight from github. In an R session, type:


devtools::install_github("Computational-Cognitive-Musicology-Lab/humdrumR")

Humdrum source

Another option—useful, if you want to inspect, or contribute to, the humdrum source code—is to actually download the humdrum package source from github and install it directly. You’ll first need to install git. Once git is installed on your computer, you can download the humdrum repository by clicking on the “Clone or download” on the github page.

Alternatively, you can use git directly: navigate to the directory on machine where you’d like to save the package source and type:


git clone https://github.com/Computational-Cognitive-Musicology-Lab/humdrumR

Once you’ve done this, you can install the source on your computer using devtools: Open an R session and use setwd to move your working directory inside the repository you just downloaded (i.e., cloned). Once there, type


devtools::install()

If you downloaded RStudio, you can make humdrum a RStudio “Project” on your local computer, which enables some useful features. To do this in RStudio, click the “New Project > Existing Directory” option and select the directory where you downloaded the repository. Once the project is created, you can install your local copy of humdrum by clicking “Install and Restart” in RStudio’s “Build” pane.


Once you’ve completed the installation of humdrum you can used it by simply calling:


library(humdrumR)

Updating humdrum

Humdrum is under active development, with new features being added, documentation being updated, and bugs being fixed on a weekly basis. We recommend you keep up to date with the newest version of humdrum. Luckily, you can easily update to the latest version by simply running the same devtools::install_github() command from above in an R session. However, if you have already loaded the humdrumR library in your R session—using library(humdrumR)—you’ll need to “detach” the old version before the new version will work. You can do this be either 1) quitting R studio and opening it again, 2) going to RStudio’s package panel and unchecking humdrumR, or 3) running the command detach("package:humdrumR", unload = TRUE).

If you installed humdrum from source using the git clone command, you can’t simply run clone again. Instead, you should navigate to the package directory and run git pull origin main. This will “pull” the latest changes down to your local machine. You can then rerun devtools::install().

Learning humdrum

To learn how to use humdrum the “Articles” list at the top of this page is the best place to start—in particular, the Getting started with humdrumR article! Documentation for specific functions and other general topics can be found in the “Reference” section.

Once humdrum is installed, you can also access documentation directly in R sessions. On the R command line, use the ? operator with the name of a function or topic to see the documentation:


library(humdrumR)

?humdrumR