pullHumdrum: Extract field(s) from humdrumR data

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

Extract field(s) from humdrumR data

Description

Individual fields from the humdrum table can be extracted using pull(). Multiple fields can be extracted using pull_data.frame(), pull_data.table, or pull_tibble() —the resulting data.frames are a column-subset of the humdrum table. You can also use the $ operator to extract a single field, just like pull().

Usage

pull_data.table(humdrumR, ..., dataTypes = "D", null = "charNA2dot")

pull_data.frame(humdrumR, ..., dataTypes = "D", null = "charNA2dot")

pull_tibble(humdrumR, ..., dataTypes = "D", null = "charNA2dot")

## S3 method for class 'humdrumR'
pull(.data, var, dataTypes = "D", null = "asis")

## S4 method for signature 'humdrumR'
x$name

Arguments

humdrumR, .data, x	HumdrumR data. Must be a humdrumR data object.
...	Which fields to output. If no arguments are provided, the object's selected fields are pulled. These arguments can be any combination of character strings, numbers, or symbols used to match fields in the humdrumR input using tidyverse semantics. Unlike in tidyverse select(), field names can be partially matched. You can also include character strings partially matching "Data", "Structure", "Interpretation", "Formal", "Reference" or "Grouping", which will select all fields of those types (see fields() for further explanation).
dataTypes	Which types of humdrum record(s) to include. Only non-null data tokens ("D") are returned by default. 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.)
null	How should null data points be output? Default is "charNA2dot". Must be a single character string, partially matching "NA2dot", "dot2NA", ⁠'charNA2dot"⁠, or "asis".
var	Which field to output. Defaults to selectedFields(humdrumR)[1]. Must be either a single character string or symbol which partially matches a field name, or a single whole-number, which selects the field by the row index of the fields() output. If a negative number is provided, nth-to-last index is used—for example, -1 would grab the last field.

Details

The functions pull(), pull.data.xxx(), pull.tibble(), and $ are the "escape hatch" to pull your data out of the humdrumR data world into "normal" R. Use the pull() function or the $ to access the actual vector content of a single field. The other functions always return a data.frame/data.table/tibble, even if it has only one column.

Choose which field(s) to return using the ..., var, or name arguments. The var and ... options use tidyverse style select semantics (see select()). If no fields are indicated, the data's selected fields are pulled; in the case of pull() and $, only the first selected field is pulled.

The dataTypes argument controls which types of data are pulled—by default, only non-null data (Type == "D") is pulled. The $ operator can only grab non-null data.

The null argument controls how null data is returned, with four options:

• "NA2dot" means all NA values are converted to "."; note that this will cause all output to be coerced to character.

• "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.

Note that pull_tibble() won't work if you don't independently load the tibble (or tidyverse) package— i.e., call library(tibble).

See Also

To know what fields are available to pull, use fields(). To know what fields are selected—the default fields to pull—use selectedFields().

Examples

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

humData |> pull(Token)
humData$Token

humData |> pull_data.table(Token, Spine)
humData |> pull_tibble(everything())

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