humdrumRclass: 'humdrumR' class

In Computational-Cognitive-Musicology-Lab/humdrumR: humdrumR

humdrumR class

Description

This S4 class is the basic unit of the humdrumR package. Each ⁠humdrumR object⁠ represents data read from one or more humdrum files. In the documentation, we refer to these objects interchangeably as "humdrumR corpora", "humdrumR objects," or humdrumR data(sets). In coding examples we name them "humData." Test is an object/variable is a humdrumR dataset using is.humdrumR().

Usage

is.humdrumR(x)

## S3 method for class 'humdrumR'
print(
  humdrumR,
  view = humdrumRoption("view"),
  dataTypes = humdrumRoption("dataTypes"),
  firstAndLast = TRUE,
  screenWidth = options("width")$width - 10L,
  null = humdrumRoption("nullPrint"),
  syntaxHighlight = humdrumRoption("syntaxHighlight"),
  maxRecordsPerFile = if (length(humdrumR) == 1L) 800L else
    humdrumRoption("maxRecordsPerFile"),
  maxTokenLength = humdrumRoption("maxTokenLength"),
  censorEmptyRecords = humdrumRoption("censorEmptyRecords")
)

Arguments

humdrumR	HumdrumR data. Must be a humdrumR data object.
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.)
syntaxHighlight	Should syntax highlighting (coloring) be used in printout? Defaults to TRUE. Must be a singleton logical value; an on/off switch.
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.
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.

Details

The most important part of a humdrumR object is the humdrum table it holds within it; In essence, a humdrumR object is simply a wrapper around its humdrum table, which helps users to to visualize, filter, summarize, and manipulate the table in a variety of ways.

Basic information about the size and shape of humdrumR objects can be obtained with calls to nrecord, npiece, length, ncol, etc.. More detailed summary information can be obtained with the humdrumR corpus summary functions. humdrumR data can also be coerced to more basic R data types using as.matrix, as.data.frame, etc.. A number of helpful functions are also defined to "reshape" or reorganize the data (e.g., cleave(), rend(), collapseHumdrum()).

The most powerful features of humdrumR are the tools it gives you to...

• Print a readable view of the data in shorthand/curtailed humdrum syntax.

• Filter humdrumR data, using subset.humdrumR() and the standard R indexing operators: ⁠[]⁠ and ⁠[[]]⁠.

• Apply arbitrary commands to humtable fields using the with(in)Humdrum routines, and related tidyverse commands (mutate(), summarize(), etc.).

Slots

Humtable

A humdrum tables—i.e, a data.table::data.table() with particular fields.

Files

A list of two elements. The first, "Search", contains a single character representing the pattern used in the call to readHumdrum() which created this humdrumR object. The second, "Names," is a vector of strings representing all the files which matched the pattern and were read into the humdrumR object, with names() corresponding to their "subcorpora" labels (Label).

Fields

A data.table indicating the existing fields in the humdrumR object's humdrum table. The fields are divided into five categories: "Data", "Structure", "Interpretation", "Formal", and "Reference."

LoadTime

A POSIXct value, indicating the time at which readHumdrum() was called to create this humdrumR object.

Context

A data.table with two columns: Open and Close. Each row represents a contextual window to apply to the data.

Viewing your Data

If you type the name of an object on the R command line, R will "print" the object in the console. This can be also be done explicitly using the humdrumR method of the print() function. The humdrumR print method contains a number of arguments, which can be manipulated directly in calls to print(). However, the humdrumR print argument draws its defaults from global humdrumR options which can be also controlled with the humdrumR() function. Generaly, changing print options with humdrumR() is the best option, as once you change them, all automatic printing will follow your new settings—this means you can avoid explicitly calling print().

When printing, only the selected fields in the data are shown.

View types

There are three options for how to view humdrumR data, which can be toggled between using the view argument to print() or humdrumR(). Since view is the first argument to the humdrumR() function, you can switch between views by simply calling humdrumR('humdrum') or humdrumR('score') or humdrumR('table'). The options are:

• "humdrum" (the default): prints a humdrum-syntax score representation, with record numbers enumerated at the left side.

  When the Token field is selected, and you haven't applied any filters, this view will show your original data as it was in the files you read.

  If more than one field is selected, they are pasted together in the printed output.

• "table": prints a view of the underlying humdrum table.

  In addition to the selected fields, the Piece, Spine, and Record fields will always print in the output table, as well as Path and Stop if any paths/stops are present.

• "score": will (attempt to) show a rendered score of (the first piece) in your data.

  This view is only likely to work correctly if you are using Rstudio and connected to the internet. Score rendering is accomplished using Craig Sapp's Humdrum Notation Plugin.

For table and humdrum views, if there are more than one pieces in the object, the beginning of the first piece is printed, followed by the end of the last piece; How much of the first/last piece are printed is controlled by the maxRecordsPerFile print argument. Both of these views also highlight the output with different colors representing different types of data tokens: this can be disabled using syntaxHighlight = FALSE. For score view, only the first piece is shown.

See Also

The actual data is stored in the internal humdrum table. You can set printing options globally using the humdrumR() function.

Examples

humData <- readHumdrum(humdrumRroot, "HumdrumData/BachChorales/chor00[1-4].krn")

humData 

humData |> print(view = 'table')

Computational-Cognitive-Musicology-Lab/humdrumR documentation built on Oct. 22, 2024, 9:28 a.m.