Skip to contents

humdrumR

Source: R/humdrumR-package.R
humdrumR.Rd

humdrumR is a toolkit for the analysis of data encoded in the humdrum syntax. 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. The humdrumR package is intended as a modernized replacement for the original humdrum toolkit, leveraging the power of R to give us unprecedented power to manipulate and analyze humdrum data using concise, expressive syntax.

humdrumRroot is the path to where the humdrumR package is install on your machine. When you installed humdrumR a few basic humdrum files were stored here as well, in subdirectories examples and HumdrumData.

The humdrumR() function is used to set global package options within an R session, mostly regarding the viewing of humdrumR datasets.

Usage

humdrumRroot

humdrumR(
  view,
  dataTypes,
  maxRecordsPerFile,
  maxTokenLength,
  nullPrint,
  syntaxHighlight,
  censorEmptyRecords
)

Format

An object of class character of length 1.

Arguments

view

How should humdrumR data be printed?

There are three options: "humdrum", "score", and "table" (aliases "data.frame" and "tibble"). These options are partially matched.

Use select() to determine which fields to show.

dataTypes

Which types of humdrum record(s) to view.

Defaults to "GLIMDd" for as.lines() and as.matrix(); "Dd" for as.data.frame(); "LIMDd" for as.matrices() and as.data.frames().

Must be a single character string. Legal values are 'G', 'L', 'I', 'M', 'D', 'd' or any combination of these (e.g., "LIM"). (See the humdrum table documentation for explanation.)

maxRecordsPerFile

How many records should be shown in each file, when more than one file is present?

Defaults to 40.

Can be any positive whole number.

maxTokenLength

Length at which longer tokens are censored with ...

Defaults to 16.

Can be any positive whole number.

nullPrint

How should null data points print?

Default is "NA2dot".

Must be a single character string, partially matching "NA2dot", "dot2NA", 'charNA2dot", or "asis". "NA2dot" means all NA values are converted to "."; "dot2NA means all "." are converted to NA; charNA2dot means NA values in character vectors are converted to NA, but not in other atomic types; "asis" means either NA or "." values may print, depending on what is in the field.

syntaxHighlight

Should syntax highlighting (coloring) be used in printout?

Defaults to TRUE.

Must be a singleton logical value; an on/off switch.

censorEmptyRecords

Should consecutive records be "censored" (compressed) in printout?

Defaults to 30.

Can be any positive whole number, up to Inf. If Inf, no censoring will occur.

Package design

The package humdrumR has seven main components:

  • To represent humdrum data in R, we have the humdrumR S4 class, and it's core component the humdrum table.

  • To create humdrumR data, a sophisticated humdrum data parser: readHumdrum. humdrumR data can also be written back to humdrum-syntax text files using writeHumdrum.

  • To filter humdrumR data, we have the subset()/filter() functions, as well as methhods for R's standard indexing operators ([] and [[]]).

  • To manipulate and modify humdrumR data, we have the with and within methods for humdrumR objects, and tidyverse aliases mutate(), summarise(), and reframe().

  • To facilitate the development of functions to work with humdrum tokens---which are simple character strings packed with information---, a useful API we call our regular-expression dispatch system.

  • Several modules for representing and manipulating musical pitch information, including our core tonalInterval class to represent tonal pitch.

  • A module for representing and manipulating musical rhythm information, with a core rhythmInterval class to represent rhythms.

Package options

The humdrumR() function sets general options for the package, mostly related to how humdrumR data objects are viewed. Each argument to the function manipulates a print/package option: for any argument that is not used, the option remains in its current setting (i.e., unchanged). These package options are all enumerated and explained in the Arguments section above.

Examples


# change default view to table
humdrumR("table")

humdrumR(view = 'humdrum', maxRecordsPerFile = 50)

# see the humdrumR package directory contents
dir(humdrumRroot) 
#>  [1] "CITATION"    "DESCRIPTION" "HumdrumData" "INDEX"       "LICENSE"    
#>  [6] "Meta"        "NAMESPACE"   "NEWS.md"     "R"           "examples"   
#> [11] "extdata"     "help"        "html"