tabr (version 0.3.0)

note-equivalence: Note, pitch and chord equivalence

Description

Helper functions to check the equivalence of two noteworthy strings, and other related functions.

Usage

note_is_equal(notes1, notes2, ignore_octave = TRUE)
note_is_identical(notes1, notes2, ignore_octave = TRUE)
pitch_is_equal(notes1, notes2)
pitch_is_identical(notes1, notes2)
octave_is_equal(notes1, notes2)
octave_is_identical(notes1, notes2, single_octave = FALSE)

Arguments

notes1

character, note string, space-delimited or vector of individual entries.

notes2

character, note string, space-delimited or vector of individual entries.

ignore_octave

logical, ignore octave position when considering equivalence.

single_octave

logical, for octave equality, require all notes share the same octave. See details.

Value

logical

Details

Noteworthy strings may contain notes, pitches and chords. Noteworthy strings are equal if they sound the same. This means that if one string contains Eb (e_) and the other contains D# (d#) then the two strings may be equal, but they are not identical.

pitch_is_equal and pitch_is_identical perform these respective tests of equivalence on both notes and chords. These are the strictest functions in terms of equivalent sound because pitch includes the octave number.

note_is_equal and note_is_identical are similar but include a default argument ignore_octave = TRUE, focusing only on the notes and chords. This allows an even more relaxed definition of equivalence. Setting this argument to FALSE is the same as calling the pitch_is_* variant.

Chords can be checked the same as notes. Every timestep in the sequence is checked pairwise between note1 and note2.

These functions will return TRUE or FALSE for every timestep in a sequence. If the two noteworthy strings do not contain the same number of notes at a specific step, such as a single note compared to a chord, this yields a FALSE value, even in a case of an octave dyad with octave number ignored. If the two sequences have unequal length NA is returned. These are bare minimum requirements for equivalence. See examples.

octave_is_equal and octave_is_identical allow much weaker forms of equivalence in that they ignore notes completely. These functions are only concerned with comparing the octave numbers spanned by any pitches present at each timestep. When checking for equality, octave_is_equal only looks at the octave number associated with the first note at each step, e.g., only the root note of a chord. octave_is_identical compares all octaves spanned at a given timestep.

It does not matter when comparing two chords that they may be comprised of a different numbers of notes. If the set of unique octaves spanned by one chord is identical to the set spanned by the other, they are considered to have identical octave coverage. For example, a1b2c3 is identical to d1e1f2g3. To be equal, it only matters that the two chords begin with x1, where x is any note. Alternatively, for octave_is_identical only, setting single_octave = TRUE additionally requires that all notes from both chords being compared at a given timestep share a single octave.

Examples

# NOT RUN {
x <- "b_2 ce_g"
y <- "b_ cd#g"
note_is_equal(x, y)
note_is_identical(x, y)

x <- "b_2 ce_g"
y <- "b_2 cd#g"
pitch_is_equal(x, y)
pitch_is_identical(x, y)

# same number of same notes, same order: unequal sequence length
x <- "b_2 ce_g b_"
y <- "b_2 ce_gb_"
note_is_equal(x, y)

# same number of same notes, same order, equal length: unequal number per timestep
x <- "b_2 ce_g b_"
y <- "b_2 ce_ gb_"
note_is_equal(x, y)

x <- "a1 b_2 a1b2c3 a1b4 g1a1b1"
y <- "a_2 g#2 d1e1f2g3 a1b2b4 d1e1"
octave_is_equal(x, y)
octave_is_identical(x, y)
octave_is_identical(x, y, single_octave = TRUE)
# }