rend: Separate data fields into new spines.

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

Separate data fields into new spines.

Description

Rend, as in "to rend apart," splits data in separate fields into separate spines or paths. Under the hood, rend() essentially runs a specialized call to make the humdrum table "longer"/"taller," similar to R functions like melt(), gather(), or pivot_longer(). In fact, a humdrumR method for pivot_longer() is defined, which is equivalent to rend(). The rend() function is essentially the inverse of cleave().

Usage

rend(humdrumR, ..., fieldName = NULL, removeRended = TRUE, rendEmpty = FALSE)

## S3 method for class 'humdrumR'
pivot_longer(data, cols, ...)

Arguments

humdrumR	HumdrumR data. Must be a humdrumR data object.
...	Which fields to rend? These arguments can be any combination of character strings, numbers, or symbols used to match fields in the humdrumR input using tidyverse semantics. See the select() docs for details.
fieldName	A name for the newly rended field. Defaults to pasting the names of selected fields (...) together, separated by .. Must be either NULL, or a single non-empty character string.
removeRended	Should rended fields be removed from the output? Defaults to TRUE. Must be a singleton logical value: an on/off switch.
rendEmpty	Empty spines be rended? Defaults to TRUE. Must be a singleton logical value: an on/off switch.

Details

The rend() function takes any number of ... arguments to select fields in the humdrumR data. The identified fields are then split into new spines. If no fields are provided, the data's selected fields are rended. New spines are generated from existing spines; if we start with spines 1, 2, 3, and rend two fields...

• the original spine 1 will be rended into new spines 1 and 2;

• the original spine 2 will be rended into new spines 3 and 4;

• the original spine 3 will be rended into new spines 5 and 6.

However, by default, spines are only rended if they contain non-null data points in the target fields. If for example, the original spine 2 had no non-null data in one of the rended fields, if would not be rended into two spines. However, if rendEmpty is set to TRUE, all spines will be rended even if empty (all null data).

Note that, since differnt fields may be different data types, rend() will generally coerce the result to character.

Fields

When you rend fields, a new field is generated. The name of the new field is specified by newField—by default, newField is NULL and the names of the rended fields are simply pasted together. If removeRended = TRUE (the default), the original fields are removed from the data. However, certain fields, like Token and any structural fields cannot be removed from the data. Therefore, if you rend these fields, they will not be deleted, even if removeRended = TRUE.

If you only provide one field name to rend, is automatically take to be Token. Thus, rend(humData, 'Solfa') is equivalent to rend(humData, 'Token', 'Solfa').

See Also

The complement/opposite of rend() is cleave().

Other Humdrum table reshaping functions: cleave(), collapseHumdrum(), expandPaths()

Other Humdrum table pivoting functions: cleave()

Examples

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

humData |> 
   mutate(Recip = recip(Token), 
          Solfa = solfa(Token, simple = TRUE)) -> humData

humData |> rend(c('Recip', 'Solfa'))

humData |> select(c('Recip', 'Solfa')) |> rend()

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