reference: Summarize reference records in a humdrumR corpus

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

Summarize reference records in a humdrumR corpus

Description

reference is used to tabulate the reference records present in a humdrumR corpus. reference is one of humdrumR's basic corpus summary functions.

Usage

reference(x, ...)

reference('OTL')

reference(humdata)

## S3 method for class 'humReference'
refTable[i, j, drop = FALSE]

Arguments

x	Input for extracting reference information. Must be a character string (to look up a reference code) or a humdrumR.
drop	Whether to return normal data.table or a humCensus table. Defaults to FALSE. Must be a singleton logical value: an on/off switch. If drop = TRUE, a normal data.table is returned instead of a humCensus table.
i	Index for rows. If numeric, selects rows by index. If character, the string is matched as a regular expression against filenames in the corpus.
j	Index for columns. If numeric, selects columns by index. If character, partially matched against column names (reference codes).

Details

reference can be used to look up information about common reference codes: supply a reference code as a character string to reference and it will check it against known reference codes and print information about matching codes (if there is one). For instance, reference('OTL') returns a description of the standard humdrum !!!OTL reference record (original title metadata).

When applied to a humdrumR corpus reference returns a special data.frame called a humReference table. A humReference table has one column for each reference code that appears in the corpus. Since reference records can be too long to print on one screen, and humdrum files can have multiple of the same type of reference code, a humReference table normally prints only the number of each type of reference record to appear in each piece. However, if only one type of reference code is present in a humReference table, the complete reference records for that code will be printed for each piece. Likewise, if only one piece is present in the table, all of that piece's complete reference records are printed. Thus, if you want to see actual reference records, try indexing the humReference table down to one column or row (see below).

A humReference table has one row for each piece in the corpus. Rows are labeled with each file name and piece number index. In addition, when a humReference object is printed, three different summary totals are printed for each reference code:

• Any indicates how many pieces in the corpus contain at least one example of each code.

• Sum indicates the total number of each reference code to appear in the corpus, including multiple appearances in one piece (like multiple "!!!COM" records).

• Unique tabulates the number of unique token in the corpus, for each code. If your corpus only has two unique composers (encoded in "!!!COM"), the Unique total will be 2. This assumes that tokens are exactly identical, including white space; so "!!!COM: J.S. Bach" and "!!!COM: JS Bach" will be counted as two unique reference records.

See Also

Other corpus summary functions: census(), humSummary, interpretations(), spines()

Examples

reference('COM')
reference('OTL')

rs <- readHumdrum(humdrumRroot, "HumdrumData/RollingStone/.*hum")
reference(rs)

reference('COC')
reference(rs)[ , 'COC']

reference(rs)[3, ]
       

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