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 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
characterstrings, numbers, or symbols used to match fields in thehumdrumRinput 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-emptycharacterstring.- removeRended
Should rended fields be removed from the output?
Defaults to
TRUE.Must be a singleton
logicalvalue: an on/off switch.- rendEmpty
Empty spines be rended?
Defaults to
TRUE.Must be a singleton
logicalvalue: 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")
#> Finding and reading files...
#> REpath-pattern '/home/nat/.tmp/Rtmpn4KeFS/temp_libpath7af94615c2ed/humdrumR/HumdrumData/BachChorales/chor00[1-4].krn' matches 4 text files in 1 directory.
#> Four files read from disk.
#> Validating four files...
#> all valid.
#> Parsing four files...
#> Assembling corpus...
#> Done!
humData |>
mutate(Recip = recip(Token),
Solfa = solfa(Token, simple = TRUE)) -> humData
humData |> rend(c('Recip', 'Solfa'))
#> ####################### vvv chor001.krn vvv ########################
#> 8: **recip **recip **recip **recip ***
#> 9: . . . . ***
#> 10: . . . . ***
#> 11: . . . . ***
#> 12: *>[A,A,B] *>[A,A,B] *>[A,A,B] *>[A,A,B] ***
#> 13: *>norep[A,B] *>norep[A,B] *>norep[A,B] *>norep[A,B] ***
#> 14: *>A *>A *>A *>A ***
#> 15: . . . . ***
#> 16: . . . . ***
#> 17: . . . . ***
#> 18: *M3/4 *M3/4 *M3/4 *M3/4 ***
#> 19: *MM100 *MM100 *MM100 *MM100 ***
#> 20: 4 do 4 mi ***
#> 21: =1 =1 =1 =1 ***
#> 22: 4 do 4 mi ***
#> 23: 4 la 8 fa ***
#> 24: . . 8 mi ***
#> 25: 4 ti 4 re ***
#> 26: =2 =2 =2 =2 ***
#> 27: 4 do 4 do ***
#> 28: 4 so 4 ti ***
#> 29: . . . . ***
#> 30: 4 la 4 do ***
#> 31: =3 =3 =3 =3 ***
#> 32: 4 fa 8 fa ***
#> 33: . . 8 mi ***
#> 34: 8 mi 4 fa ***
#> 35: 8 re . . ***
#> 36: 4 do 4 so ***
#> 37: =4 =4 =4 =4 ***
#> 38: 2 so 2 so ***
#> 39: 4 do 4 so ***
#> 40: =5 =5 =5 =5 ***
#> 41: 4 ti 4 re ***
#> 42: 4 do 4 mi ***
#> 43: 4 re 4 fa ***
#> 44: =6 =6 =6 =6 ***
#> 45: 4 mi 4 so ***
#> 46: 4 fa 4 la ***
#> 47: 4 so 8 so ***
#> 48: . . 8 fa ***
#> 49: =7 =7 =7 =7 ***
#> 50: 2 do 2 mi ***
#> 51: =:|! =:|! =:|! =:|! ***
#> 52: *>B *>B *>B *>B ***
#> 53: 4 do 4 so ***
#> 54: =8 =8 =8 =8 ***
#> 55: 4 do 4 so ***
#> 56: . . . . ***
#> 57: 4 re 4 fa ***
#> 58-124::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
#> ####################### ^^^ chor001.krn ^^^ ########################
#>
#> (two more pieces...)
#>
#> ####################### vvv chor004.krn vvv ########################
#> 7-44::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
#> 45: =4 =4 =4 =4 ***
#> 46: 8 ti 8 re ***
#> 47: 16 la 4 so ***
#> 48: 16 so . . ***
#> 49: 4 re . . ***
#> 50: . . 8 fi ***
#> 51: 4 so 4 re ***
#> 52: =:|! =:|! =:|! =:|! ***
#> 53: *>B *>B *>B *>B ***
#> 54: 4 do 4 mi ***
#> 55: . . . . ***
#> 56: =5 =5 =5 =5 ***
#> 57: 4 la 4 la ***
#> 58: . . . . ***
#> 59: 8 ti 4 re ***
#> 60: 8 do . . ***
#> 61: 4 re 4 re ***
#> 62: 4 so 4 re ***
#> 63: =6 =6 =6 =6 ***
#> 64: 8 mi 4 so ***
#> 65: 8 do . . ***
#> 66: 4 re 4 fi ***
#> 67: 4 so 4 ti ***
#> 68: 4 do 4 do ***
#> 69: =7 =7 =7 =7 ***
#> 70: 4 mi 4 so ***
#> 71: . . . . ***
#> 72: 4 do 4 do ***
#> 73: 8 fa 4 do ***
#> 74: 8 so . . ***
#> 75: 4 la 4 la ***
#> 76: . . . . ***
#> 77: =8 =8 =8 =8 ***
#> 78: 4 di 4 te ***
#> 79: 4 re 4 la ***
#> 80: 4 la 4 la ***
#> 81: 4 do 4 so ***
#> 82: =9 =9 =9 =9 ***
#> 83: 4 so 4 so ***
#> 84: 8 la 4 do ***
#> 85: 8 ti . . ***
#> 86: 4 do 4 do ***
#> 87: 4 so 8 ti ***
#> 88: . . 8 so ***
#> 89: =10 =10 =10 =10 ***
#> 90: 4 fi 2 re ***
#> 91: 4 so . . ***
#> 92: 4 do 4 mi ***
#> 93: == == == == ***
#> 94: *- *- *- *- ***
#> ####################### ^^^ chor004.krn ^^^ ########################
#> (***four spines/paths not displayed due to screen size***)
#>
#> humdrumR corpus of four pieces.
#>
#> Data fields:
#> *Recip.Solfa :: character (**recip tokens)
#> Token :: character
#>
humData |> select(c('Recip', 'Solfa')) |> rend()
#> ####################### vvv chor001.krn vvv ########################
#> 8: **recip **recip **recip **recip ***
#> 9: . . . . ***
#> 10: . . . . ***
#> 11: . . . . ***
#> 12: *>[A,A,B] *>[A,A,B] *>[A,A,B] *>[A,A,B] ***
#> 13: *>norep[A,B] *>norep[A,B] *>norep[A,B] *>norep[A,B] ***
#> 14: *>A *>A *>A *>A ***
#> 15: . . . . ***
#> 16: . . . . ***
#> 17: . . . . ***
#> 18: *M3/4 *M3/4 *M3/4 *M3/4 ***
#> 19: *MM100 *MM100 *MM100 *MM100 ***
#> 20: 4 do 4 mi ***
#> 21: =1 =1 =1 =1 ***
#> 22: 4 do 4 mi ***
#> 23: 4 la 8 fa ***
#> 24: . . 8 mi ***
#> 25: 4 ti 4 re ***
#> 26: =2 =2 =2 =2 ***
#> 27: 4 do 4 do ***
#> 28: 4 so 4 ti ***
#> 29: . . . . ***
#> 30: 4 la 4 do ***
#> 31: =3 =3 =3 =3 ***
#> 32: 4 fa 8 fa ***
#> 33: . . 8 mi ***
#> 34: 8 mi 4 fa ***
#> 35: 8 re . . ***
#> 36: 4 do 4 so ***
#> 37: =4 =4 =4 =4 ***
#> 38: 2 so 2 so ***
#> 39: 4 do 4 so ***
#> 40: =5 =5 =5 =5 ***
#> 41: 4 ti 4 re ***
#> 42: 4 do 4 mi ***
#> 43: 4 re 4 fa ***
#> 44: =6 =6 =6 =6 ***
#> 45: 4 mi 4 so ***
#> 46: 4 fa 4 la ***
#> 47: 4 so 8 so ***
#> 48: . . 8 fa ***
#> 49: =7 =7 =7 =7 ***
#> 50: 2 do 2 mi ***
#> 51: =:|! =:|! =:|! =:|! ***
#> 52: *>B *>B *>B *>B ***
#> 53: 4 do 4 so ***
#> 54: =8 =8 =8 =8 ***
#> 55: 4 do 4 so ***
#> 56: . . . . ***
#> 57: 4 re 4 fa ***
#> 58-124::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
#> ####################### ^^^ chor001.krn ^^^ ########################
#>
#> (two more pieces...)
#>
#> ####################### vvv chor004.krn vvv ########################
#> 7-44::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
#> 45: =4 =4 =4 =4 ***
#> 46: 8 ti 8 re ***
#> 47: 16 la 4 so ***
#> 48: 16 so . . ***
#> 49: 4 re . . ***
#> 50: . . 8 fi ***
#> 51: 4 so 4 re ***
#> 52: =:|! =:|! =:|! =:|! ***
#> 53: *>B *>B *>B *>B ***
#> 54: 4 do 4 mi ***
#> 55: . . . . ***
#> 56: =5 =5 =5 =5 ***
#> 57: 4 la 4 la ***
#> 58: . . . . ***
#> 59: 8 ti 4 re ***
#> 60: 8 do . . ***
#> 61: 4 re 4 re ***
#> 62: 4 so 4 re ***
#> 63: =6 =6 =6 =6 ***
#> 64: 8 mi 4 so ***
#> 65: 8 do . . ***
#> 66: 4 re 4 fi ***
#> 67: 4 so 4 ti ***
#> 68: 4 do 4 do ***
#> 69: =7 =7 =7 =7 ***
#> 70: 4 mi 4 so ***
#> 71: . . . . ***
#> 72: 4 do 4 do ***
#> 73: 8 fa 4 do ***
#> 74: 8 so . . ***
#> 75: 4 la 4 la ***
#> 76: . . . . ***
#> 77: =8 =8 =8 =8 ***
#> 78: 4 di 4 te ***
#> 79: 4 re 4 la ***
#> 80: 4 la 4 la ***
#> 81: 4 do 4 so ***
#> 82: =9 =9 =9 =9 ***
#> 83: 4 so 4 so ***
#> 84: 8 la 4 do ***
#> 85: 8 ti . . ***
#> 86: 4 do 4 do ***
#> 87: 4 so 8 ti ***
#> 88: . . 8 so ***
#> 89: =10 =10 =10 =10 ***
#> 90: 4 fi 2 re ***
#> 91: 4 so . . ***
#> 92: 4 do 4 mi ***
#> 93: == == == == ***
#> 94: *- *- *- *- ***
#> ####################### ^^^ chor004.krn ^^^ ########################
#> (***four spines/paths not displayed due to screen size***)
#>
#> humdrumR corpus of four pieces.
#>
#> Data fields:
#> *Recip.Solfa :: character (**recip tokens)
#> Token :: character
#>