notearray manpage

COMMAND

notearray -- Extract 2-D array of notes from **kern spines for numeric analysis.

notearray [-md] [-MClaAN] [input(s)] [>output]

The notearray program takes an input Humdrum file with one or more **kern spines and outputs pitch information for the musical score as a two-dimensional array. Each row of the output data represents a sonority within the score with note attacks represented by positive integers, notes sustained from previous sonorities as negative integers, and rests as the value 0. Each column represents a voice in the score.

By default, two columns of rhythmic information are stored at the start of the note array: (1) the measure number in which the sonority occurs, and (2) the starting beat position of the sonority within the measure. Each **kern part should be monophonic by itself; otherwise, only the primary (left-most) notes in a part will be extracted. Here is an example run of the notearray program with no additional options being used:



input data **kern **kern **kern **kern =7 =7 =7 =7 *M3/4 *M3/4 *M3/4 *M3/4 4D 8FL 8A 4f . 8GJ 4d . 4AA 4A . 4e . . 8c# . 4D 4F 4A 4d =8 =8 =8 =8 4D 8BL 4f 8ddL . 8AJ . 8ccJ 4E 4G# 8BL 4b . . 16cL . . . 16dJJ . 4AA 4E 4c 4a = = = = *- *- *- *-

notearray input > output ##bar ##beat ##b40 ##b40 ##b40 ##b40 7 1 128 139 151 179 7 1.5 -128 145 168 -179 7 2 111 151 -168 174 7 2.5 -111 -151 163 -174 7 3 128 139 151 168 8 1 128 157 179 208 8 1.5 -128 151 -179 202 8 2 134 146 157 197 8 2.5 -134 -146 162 -197 8 2.75 -134 -146 168 -197 8 3 111 134 162 191

In this example, the first column of output data shown on the right contains the measure number in which the notes on each line were extracted. The second column list the beat within the measure at which the notes occur. Then there are four columns (one for each input **kern spine) which stores the pitch information of each spine. The default numbering system used in the output data is the base-40 system (described below). In this case the number 128 means D3, or the note D a seventh below middle C. When a note value is negative, this indicates that the note is being sustained from a previous sonority within the score. Note values of 0 represent rests.

Pitch numbering methods

Each of the three output one-dimensional numbering methods for pitches is based on chroma (or pitch-class) and octave values. The base value indicates the octave number, and the chroma can be extracted from the modulo, or remainder:
octave  = number  /  base
chroma = number % base
For example, in base-12, the note number 60 represents middle C, with the octave being 5 and the chroma being 0:
octave  = 60  /  12 = 5
chroma = 60 % 12 = 0

For base-12, the default octave for middle C is 5 so that it matches MIDI key numbers, while in base-40 and base-7, middle C's octave is set to 4 so as to match the ISO labeling of octaves. If the input data contains very low notes, then some pitches will incorrectly be assigned to negative octaves (and 0 may represent a pitch as well as a rest). To avoid these cases, use the -o # option to transpose the integer values for pitch up the specified number of octaves to avoid negative octaves in the output data (since negative values are intended to represent sustained notes).

input **kern *M4/4 =1- 4c 4e 4g 4cc == *-

notearray ##b40 162 174 185 202

notearray -o 1 ##b40 202 214 225 242

notearray -o 2 ##b40 242 254 265 282

Note in the above example that 202 is 40 (the base-40 octave) greater than 162, since the notes in the "-o 1" column are an octave higher, and the notes in the next column are 80 greater than the original data since they are two octaves higher.

Base-40

Base-40 is a method of encoding diatonic pitches with accidentals up to double sharps or flats. The base-40 chroma for pitches can be built up from the property that a minor second is a difference of 5 between pitch numbers in the base-40 system, and major seconds are a difference of 6. The C chroma value is set to the value 2 rather than 0 so that the octave values for C♭ and C♭♭ remain in the same octave as C♮ just above these pitches when using division by the base to extract the octave number. Here is a complete table of the base-40 chroma, using C=2 as the reference:

Base-40 chroma values (pitch classes)
0 = C♭♭ 1 = C♭ 2 = C♮ 3 = C♯ 4 = C♯♯	5 = [D♭♭♭] 6 = D♭♭ 7 = D♭ 8 = D♮ 9 = D♯ 10 = D♯♯	11 = [E♭♭♭] 12 = E♭♭ 13 = E♭ 14 = E♮ 15 = E♯ 16 = E♯♯	17 = F♭♭ 18 = F♭ 19 = F♮ 20 = F♯ 21 = F♯♯	22 = unused 23 = G♭♭ 24 = G♭ 25 = G♮ 26 = G♯ 27 = G♯♯	28 = [A♭♭♭] 29 = A♭♭ 30 = A♭ 31 = A♮ 32 = A♯ 33 = A♯♯	34 = [B♭♭♭] 35 = B♭♭ 36 = B♭ 37 = B♮ 38 = B♯ 39 = B♯♯

To calculate an absolute pitch such as G4 (The G above middle C), multiply the octave by 40 and add the chroma value for the G pitch-class:

G4 = 4 * 40 + 25 = 160 + 25 = 185 Alternatively, G4 can be calculated by adding 3 half-steps (major seconds) and one minor second to C4 (represented as the number 162 in base-40): G4 = C4 + 3 * M2 + m2 = 162 + 3 * 6 + 5 = 162 + 23 = 185

Note that base-40 pitch representations preserve chromatic alterations of diatonic pitch-classes (up to double sharps/flats). Therefore F♯4 (180) is not in the same as the base-40 pitch G♭4 (184). A useful property of the base-40 system is that the difference between pitch numbers in the base-40 system represent one-to-one mappings with diatonic intervals:

Base-40 interval classes (d=diminished, m=minor, M=major, P=perfect, A=augmented)
-2 = dd1 -1 = d1 0 = P1 1 = A1 2 = AA1	3 = [dd2] 4 = d2 5 = m2 6 = M2 7 = A2 8 = AA2	9 = [dd3] 10 = d3 11 = m3 12 = M3 13 = A3 14 = AA3	15 = dd4 16 = d4 17 = P4 18 = A4 19 = AA4	20 = unused 21 = dd5 22 = d5 23 = P5 24 = A5 25 = AA5	26 = [dd6] 27 = d6 38 = m6 29 = M6 30 = A6 31 = AA6	32 = [dd7] 33 = d7 34 = m7 35 = M7 36 = A7 37 = AA7 (40 = octave)

As an example, consider the interval between E4 (174) and C4 (162) which is 174-162 = 12, representing a major third according to the table shown above. All intervals can be constructed by observing that major seconds are 6 and minor seconds are 5, so note that a major third, consisting of two major seconds, is 6 + 6 = 12. Below is an example segment of music with the pitches labeled in the base-40 system. Try subtracting values and comparing the results to numbers in the base-40 interval-class table above.



Base-12

Base-12 numbering of pitches assigns 12 notes to an octave as on a standard musical keyboard. The values output by the notearray program match the values used as MIDI key numbers, where middle C is assigned to be 60, C♯4/D♭4 to 61, D4 to 62, etc. This makes the octave value for middle C up to the B a major seventh above to be one higher than for the base-40 or base-7 outputs from notearray at 5, compared to 4 for the other numbering methods' middle octave. Using the option "-o -1" will make the base-12 numbers match the same octaves as base-40 and base-7; or conversely, you can use "-o 1" for base-40 and base-7 outputs so that the middle-C octave is 5 to match that of the base-12 output.

Base-12 chroma do not map one-to-one with diatonic-based pitch-classes. For example, C♯4 and D♭4 belong to different diatonic pitch-classes, but they have the same base-12 pitch value (represented by the number 61).

Base-12 chroma values
0 = B♯, C♮, D♭♭, etc. 1 = B♯♯, C♯, D♭, etc. 2 = C♯♯, D♮, E♭♭, etc. 3 = D♯, E♭, F♭♭, etc.	4 = D♯♯, E♮, F♭, etc. 5 = E♯, F♮, G♭♭, etc. 6 = E♯♯, F♯, G♭, etc. 7 = F♯♯, G♮, A♭♭, etc.	8 = G♯, A♭, B♭♭♭, etc. 9 = G♯♯, A♮, B♭♭, etc. 10 = A♯, B♭, C♭♭, etc. 11 = A♯♯, B♮, C♭, etc.

Base-12 maps one-to-one with pitch frequencies in an equal-tempered scale, but not necessarily in other temperaments. For example C♯4 and D♭4 are both represented by the base-12 number 61, and they also map to 277.183 Hz in equal temperament when setting A4 to 440 Hz. However, in other tuning systems and temperaments with more than 12 notes, C♯4 and D♭4 may map to different fundamental frequencies (for example in string-quartet performances).

Essentially, representing pitches in base-12 is equivalent to stripping off the accidental information of base-40 diatonic values. Or another way of stating this is that you can unambiguously map base-40 values to base-12 values, but not the other way around. Here is the same example segment of music, with pitches given base-12 numbers:



Base-7

Base-7 is a representation of the pitches in diatonic form without any accidental alterations. For example, C♭4, C♮4, and C♯4 are all represented by the number 28 = 0 + 4 * 7, where 0 is the base-7 C chroma, 4 is the octave and 7 is the base. Base-7 values are another method of stripping accidental information off of base-40 values.

Base-7 chroma values
0 = C♭♭, C♭, C♮, C♯, C♯♯ etc. 1 = D♭♭, D♭, D♮, D♯, D♯♯ etc. 2 = E♭♭, E♭, E♮, E♯, E♯♯ etc. 3 = F♭♭, F♭, F♮, F♯, F♯♯ etc.	4 = G♭♭, G♭, G♮, G♯, G♯♯ etc. 5 = A♭♭, A♭, A♮, A♯, A♯♯ etc. 6 = B♭♭, B♭, B♮, B♯, B♯♯ etc.

Here is the same example segment of music, with pitches given base-7 numbers:



Note names

The -k option can be used to include a column of note names before each numeric column describing the notes. The --quote option may be used to enclose the kern pitch name in quotes. The --no-tie option can be given to hide tied note information on the **kern note name. The -T option can be used to mark a tie-start ([) and tie-end (]) on a note which only exists on a single row (i.e., it does not sustain past the current row).

Output formats

The output note array data can be formatted in three styles. The default output style is suitable for loading into matlab, where the data represents a matrix with tab characters separating values in each row. The -H option will generate data in a proper Humdrum file format. The --math option will format the output data into a form which can be read into Mathematica.

For automatic identification of each column's data type, the -c option can be specified. This will insert a row of integers at the top of the array which describes the data stored in each column:

1000	=	**kern-style (text-based) note names.
1007	=	Note column for a voice/part in the score, specifically in base-7 encoding (diatonic pitches without accidentals).
1012	=	Note column for a voice/part in the score, specifically in base-12 encoding (MIDI key numbers).
1040	=	Note column for a voice/part in the score, specifically in base-40 encoding (diatonic pitches with up to double accidentals).
2000	=	Line number of sonority/matrix row in input file.
3000	=	Measure number of row.
4000	=	Beat position of row within the measure.
5000	=	Absolute beat position of the row within the score.
6000	=	Duration of the current row of notes.
7100	=	Indices to the attack of the current note
7200	=	Reverse indices to the attack of the previous note.
7300	=	Forward indices to the attack of the next note

An index column (generated with the -i option) will not have a type number, and all rows in the index column will represent line indices for that row of the array. Typically the index column is not needed by processing program which can count the lines of the array by themselves, and the index column is more useful for human readability of note index values.

In the following example, the -c option adds the column description number, and the -I option suppresses the textual comment describing the column type. The -C option can be used to suppress echoing any comments in the input data into the output, generating purely numeric data:

input data **kern **kern **kern **kern =7 =7 =7 =7 *M3/4 *M3/4 *M3/4 *M3/4 4D 8FL 8A 4f . 8GJ 4d . 4AA 4A . 4e . . 8c# . 4D 4F 4A 4d =8 =8 =8 =8 4D 8BL 4f 8ddL . 8AJ . 8ccJ 4E 4G# 8BL 4b . . 16cL . . . 16dJJ . 4AA 4E 4c 4a = = = = *- *- *- *-

notearray -cIC input > output 3000 4000 1040 1040 1040 1040 7 1 128 139 151 179 7 1.5 -128 145 168 -179 7 2 111 151 -168 174 7 2.5 -111 -151 163 -174 7 3 128 139 151 168 8 1 128 157 179 208 8 1.5 -128 151 -179 202 8 2 134 146 157 197 8 2.5 -134 -146 162 -197 8 2.75 -134 -146 168 -197 8 3 111 134 162 191

Matlab

This is the default output format. Each data row consists of a constant number of values (unless multiple input files containing different numbers of parts are given) which can be loaded into a matrix in matlab or octave with the following command:

   load('data')

where "data" is the name of the file in which the output data is stored, plus the extension ".mat". Alternatively, if the filename is data.dat or with some other extension, then load with the command load('data.dat'). The loaded data will be stored in a matrix with the same name as the file (without the extension) which can be further processed, such as with the size() function which reports the number of rows and columns in the matrix:

         octave:2> size(data)
         ans =
      
            190     5

The matlab-style note array can be loaded into python with code like this:

file = open("tap.dat", "r") data = [] for line in file.readlines(): if line[0] != "#": data.append(line.rstrip("\n").split("\t")) # process with numpy as an n-dimensional array from numpy import * npdata = array(data, dtype=float) # list the dimensions of the matrix npdata.shape # access an element [row, column], zero indexed # second row, fifth number in row: npdata[1, 4]

Humdrum

Specifying the -H option will format the output data as a Humdrum file which can be further processed with Humdrum tools.

notearray -H input > output **bar **beat **b40 **b40 **b40 **b40 7 1 128 139 151 179 7 1.5 -128 145 168 -179 7 2 111 151 -168 174 7 2.5 -111 -151 163 -174 7 3 128 139 151 168 8 1 128 157 179 208 8 1.5 -128 151 -179 202 8 2 134 146 157 197 8 2.5 -134 -146 162 -197 8 2.75 -134 -146 168 -197 8 3 111 134 162 191 *- *- *- *- *- *-

Note that the two commands in the following example will produce the same results, where rid is a standard Humdrum Toolkit program which is removing interpretations and global comments, leaving only data lines:

notearray -CI input 7 1 128 139 151 7 1.5 -128 145 168 7 2 111 151 -168 7 2.5 -111 -151 163 7 3 128 139 151 8 1 128 157 179 8 1.5 -128 151 -179 8 2 134 146 157 8 2.5 -134 -146 162 8 2.75 -134 -146 168 8 3 111 134 162

notearray -H | rid -GI input 7 1 128 139 151 7 1.5 -128 145 168 7 2 111 151 -168 7 2.5 -111 -151 163 7 3 128 139 151 8 1 128 157 179 8 1.5 -128 151 -179 8 2 134 146 157 8 2.5 -134 -146 162 8 2.75 -134 -146 168 8 3 111 134 162

Mathematica

For generating data which can be loaded into Mathematica, use the --math option. When using the --math option, you must also specify a variable name for the array in the output data. For example:

notearray -am --math twobars input > data.ma (*bar **beat **abs **b12 **b12 **b12 **b12 *) twobars = { {7, 1, 0, 50, 53, 57, 65}, {7, 1.5, 0.5, -50, 55, 62, -65}, {7, 2, 1, 45, 57, -62, 64}, {7, 2.5, 1.5, -45, -57, 61, -64}, {7, 3, 2, 50, 53, 57, 62}, {8, 1, 3, 50, 59, 65, 74}, {8, 1.5, 3.5, -50, 57, -65, 72}, {8, 2, 4, 52, 56, 59, 71}, {8, 2.5, 4.5, -52, -56, 60, -71}, {8, 2.75, 4.75, -52, -56, 62, -71}, {8, 3, 5, 45, 52, 60, 69} };

Notice that the text string after the --math option name (twobars) was used to set the name of the data in the above output. The -a option was used to add an additional column of information showing the absolute beat position within the score of each data row (the score duration since the start of the music). The -m option was used to display pitches in base-12 (MIDI key number) format.

The Mathematica output data can be loaded into Mathematica using the Read[] function:

       SetDirectory["C:/wherever"];
       Read["data.ma"]

An example application of this data would be to load into Mathematica, and then generate piano-roll notation from the data with the following function:

{bar, beat, absb, v4, v3, v2, v1} = Transpose[twobars]; PianoRoll[absb_, voice_, rgb_] := Module[{newa, yvals, rects}, newa = Append[absb, Last[absb] + 1]; yvals = Drop[Transpose[{RotateLeft[newa], newa}], -1]; rects = Map[Rectangle[{#[[2]][[2]], #[[1]] - 0.5}, {#[[2]][[1]], #[[1]] + 0.5}]&, Transpose[{Abs[voice], yvals}]]; Graphics[Flatten[{RGBColor[Sequence @@ rgb], rects}]] ] Show[PianoRoll[absb, v1, {1, 0, 0}], PianoRoll[absb, v2, {0.75, 0.85, 0}], PianoRoll[absb, v3, {0, 0.75, 0.75}], PianoRoll[absb, v4, {0, 0, 1}], Frame->True]

which generates this plot, with pitch on the y-axis and score duration (in quarter notes) on the x-axis:

The default output from notearray can also be loaded into Mathematica via a different method, provided that the -C option is used to suppress comment lines in the output data, and the -I is used to suppress the column data-type comments. The raw numeric data (without comments) can be loaded into Mathematica as tab-separated values:

        SetDirectory["C:/wherever"];
  	variable = Import["file.dat", "TSV"];
 

When multiple input files are processed by notearray, the Mathematica-formatted output will contain a nested list of data for each input file.

Position information columns

Five types of positional information can be given on the left side of the note array. By default the first two columns of data for each row in the array are the measure number and the starting beat position of the sonority within the measure. These columns can be suppressed with the -M and -B options, respectively. Use both options to suppress both columns of information, or use the -N option to suppress both columns of positional information, so that only note columns are output:

input data **kern **kern **kern **kern =7 =7 =7 =7 *M3/4 *M3/4 *M3/4 *M3/4 4D 8FL 8A 4f . 8GJ 4d . 4AA 4A . 4e . . 8c# . 4D 4F 4A 4d =8 =8 =8 =8 4D 8BL 4f 8ddL . 8AJ . 8ccJ 4E 4G# 8BL 4b . . 16cL . . . 16dJJ . 4AA 4E 4c 4a = = = = *- *- *- *-

notearray -N ##b40 ##b40 ##b40 ##b40 128 139 151 179 -128 145 168 -179 111 151 -168 174 -111 -151 163 -174 128 139 151 168 128 157 179 208 -128 151 -179 202 134 146 157 197 -134 -146 162 -197 -134 -146 168 -197 111 134 162 191

Two additional informational columns are also available. The -l option will display the line number in the input Humdrum data from which the sonority was extracted. This is useful when linking analysis data back to the orignal score. The -a option will display the absolute beat position which is the duration between the start of the music and the beginning of the sonority. All five information columns can be displayed by using the -A option, which is equivalent to giving the -l, -a and -D options. Information columns will always be displayed in a fixed order: (1) line number in original file, (2) measure number, (3) metric position, (4) absolute beat position, and (5) row duration.

notearray -A ##line ##bar ##beat ##abs ##ldur ####b40 ####b40 ####b40 ####b40 4 7 1 0 0.5 128 139 151 179 5 7 1.5 0.5 0.5 -128 145 168 -179 6 7 2 1 0.5 111 151 -168 174 7 7 2.5 1.5 0.5 -111 -151 163 -174 8 7 3 2 1 128 139 151 168 10 8 1 3 0.5 128 157 179 208 11 8 1.5 3.5 0.5 -128 151 -179 202 12 8 2 4 0.5 134 146 157 197 13 8 2.5 4.5 0.25 -134 -146 162 -197 14 8 2.75 4.75 0.25 -134 -146 168 -197 15 8 3 5 1 111 134 162 191

Using the -i option will cause the first column in the array to display the line index for each row of the array. By default, the indexing starts at 0, but can be started at 1 by using the -1 (numeral one) option. Other positive starting index values can be specified with the --offset # option, where # is a positive integer. This option is useful when concatenating individual arrays together into a larger array.

Here is a summary of the options which can be used to display or suppress position information to the left of the note columns:

-a		Add a column of numbers which indicates the starting position of the sonority relative to the start of the music.
-l		(lowercase L) Add a column of numbers which indicates the line in the input Humdrum data from which the notes in the row were extracted.
-D		Add a column of with the duration of each row. This is equivalent to subtracting the absolute beat position of the next row from the current row. The duration of the last row in the array is similar to including a rest row with the -e option to record the absolute beat position of the ending of the last row sonority.
-i		Add a column of numbers which indicates the row index of the current line in the note array. Index values start at 0 unless the -1 option is used to start them at 1, or the --offset option is used to start the line indexing at another value.
-N		Suppress display of default position information columns (measure numbers and beat positions within the measure). Equivalent to using the two options "-MB".
-A		Display all position information columns (except the index column generated by the -i option). Equivalent to using the two options "-la".
-M		Suppress the display of the measure number column.
-B		Suppress the display of the beat number column.

Rational values for beat positions

Beat and absolute beat positions are displayed as floating-point numbers by default. If you need to avoid round-off errors for tuplets, you can use the -r option to display these values are rational numbers. In the following examples, numbers such as 1.5 in the beat column are converted into numbers such as "1+1/2".

notearray ##bar ##beat ##b40 ##b40 ##b40 7 1 128 139 151 7 1.5 -128 145 168 7 2 111 151 -168 7 2.5 -111 -151 163 7 3 128 139 151 8 1 128 157 179 8 1.5 -128 151 -179 8 2 134 146 157 8 2.5 -134 -146 162 8 2.75 -134 -146 168 8 3 111 134 162

notearray -r ##bar ##beat ##b40 ##b40 ##b40 7 1 128 139 151 7 1+1/2 -128 145 168 7 2 111 151 -168 7 2+1/2 -111 -151 163 7 3 128 139 151 8 1 128 157 179 8 1+1/2 -128 151 -179 8 2 134 146 157 8 2+1/2 -134 -146 162 8 2+3/4 -134 -146 168 8 3 111 134 162

To display the beat values as rational fractions and not as a compound integer value plus fractional part, use the -f option. This will convert 1.5 into "3/2" rather than "1+1/2":

notearray ##bar ##beat ##b40 ##b40 ##b40 7 1 128 139 151 7 1.5 -128 145 168 7 2 111 151 -168 7 2.5 -111 -151 163 7 3 128 139 151 8 1 128 157 179 8 1.5 -128 151 -179 8 2 134 146 157 8 2.5 -134 -146 162 8 2.75 -134 -146 168 8 3 111 134 162

notearray -f ##bar ##beat ##b40 ##b40 ##b40 7 1 128 139 151 7 3/2 -128 145 168 7 2 111 151 -168 7 5/2 -111 -151 163 7 3 128 139 151 8 1 128 157 179 8 3/2 -128 151 -179 8 2 134 146 157 8 5/2 -134 -146 162 8 11/4 -134 -146 168 8 3 111 134 162

Parallel indexing arrays

The note data consists of rows of sonorities which can be composed of note sustains (negative integers), note attacks (positive integers) and rests (zeros). In order to navigate melodically through the columns, several options can be used to store indices of the current, previous and following note within each note column:

--attack		Store an index of the note attack for the currently sounding note. The attack index column will be placed immediately to the right of the note column it describes.
--last		Store an index of the previous note attacked in the note column. The last-note index column will be placed immediately to the right of the note column it describes.
--next		Store an index of the note attack for the currently sounding note. The next-note index column will be placed immediately to the right of the note column it describes.
--mel		Store all melodic index columns for each note column. Equivalent to using the options --attack, --last, and --next.

The current, last and next note-attacks information stored in these index columns can be generated relatively easily in the programming environment which loads the note information, but the indexing options are provided for convenience.

With the information in these index column, the duration of each note can be calculated from a simple algorithm: The duration of the current note is the difference between the absolute attack time of the next note minus the absolute time of the attack of the current note. See the -e option for details on determining the duration of the last note in each note column.

notearray --mel -Naie input ##idx ##abs ##b40 ##attk ##last ##next ##b40 ##attk ##last ##next ##b40 ##attk ##last ##next ##b40 ##attk ##last ##next 0 0 128 0 -1 2 139 0 -1 1 151 0 -1 1 179 0 -1 2 1 0.5 -128 0 -1 2 145 1 0 2 168 1 0 3 -179 0 -1 2 2 1 111 2 0 4 151 2 1 4 -168 1 0 3 174 2 0 4 3 1.5 -111 2 0 4 -151 2 1 4 163 3 1 4 -174 2 0 4 4 2 128 4 2 5 139 4 2 5 151 4 3 5 168 4 2 5 5 3 128 5 4 7 157 5 4 6 179 5 4 7 208 5 4 6 6 3.5 -128 5 4 7 151 6 5 7 -179 5 4 7 202 6 5 7 7 4 134 7 5 10 146 7 6 10 157 7 5 8 197 7 6 10 8 4.5 -134 7 5 10 -146 7 6 10 162 8 7 9 -197 7 6 10 9 4.75 -134 7 5 10 -146 7 6 10 168 9 8 10 -197 7 6 10 10 5 111 10 7 11 134 10 7 11 162 10 9 11 191 10 7 11 11 6 0 11 10 -1 0 11 10 -1 0 11 10 -1 0 11 10 -1

Note that index values of -1 are used to indicate that there are no notes before the first note in the column (for --last data), and no notes after the last note in the column (for --next data). When multiple input files are given to the program, the next and last data columns do not span multiple inputs, so -1 indices will be found at the boundaries. However, the non-negative index values will increment continuously between multiple inputs.

Comments and reference records

By default all global comments and reference records will be echoed into the output data as comments. These comments can be suppressed by using the -C option. To suppress global comments and only echo bibliographic (reference) records, use the -b option. For output formats other than the Humdrum file format (generated with the -H option), an initial comment line before the first data line describing each data column will be given unless the -I option is used to prevent its printing.

Ending rests

By default, the notearray program generates one row in the output array for each data line in the input Humdrum file. The duration of each row can be calculated from the information column produced by the -a option (the absolute beat position for the row). The difference between each absolute beat position is the duration for the sonority of each row. However, the duration of the last row cannot be calculated without knowing when the last sonority is released. Therefore, the -e option can be used to generate a rest sonority after the end of the last sonority in the score to allow calculating the duration of the last row in the note array.

notearray -am ##bar ##beat ##abs ##b12 1 1 0 60 2 1 2 62 3 1 4 64 notearray -ame ##bar ##beat ##abs ##b12 1 1 0 60 2 1 2 62 3 1 4 64 4 1 6 0

In this example, the extra row in the output data allows the duration of the last sonority to be determined (6 - 4 = 2 beats). And the duration of the entire score is the absolute beat position of the rest in the last row (6 beats).

Double-barline rests

A row of rests can be inserted in the output data when double barline occur in the score by specifying the --double option. This is useful to separate phrases in certain types of music.

Sustained sonority suppression

Using the -S option will suppress all output lines which contain only sustained notes. This is used to generate more parsimonious data.

Beat duration

The -t option can be used to specify the duration of beats within the music. For example music in 6/8 will automatically be assumed to be in a compound meter with the beat equal to the dotted quarter note ("-t 4."). However, in certain cases the beats might instead be defined on the eighth-note level ("-t 8").

input **kern *M6/8 =1- 8c 8d 8e 4.f =2 8g 4a 4b 8cc == *-

notearray -r -t 4. ##bar ##beat ##b40 1 1 162 1 1+1/3 168 1 1+2/3 174 1 2 179 2 1 185 2 1+1/3 191 2 2 197 2 2+2/3 202

notearray -t 8 ##bar ##beat ##b40 1 1 162 1 2 168 1 3 174 1 4 179 2 1 185 2 2 191 2 4 197 2 6 202

Multiple input files

The following options work when multiple input files are given to the notearray program.

Measure numbers

The -mo option can be used to generate unique measure numbers in the output data when multiple files are given as an input. The -mo option is useful for keeping track of the source file in the output data when there are multiple input files. The option takes an integer argument which is the an increment in the measure number offset for each input file. For example if --mo 1000 is used, then a value of 1000 will be added to the measure numbers of the first file's output, 2000 to the second file's output, and so on. This allows the originating file to be identified in the output data (provided in this case that no file contains a measure number greater than 1000, in which case the increment should be set to 10,000).

input 1 **kern *M4/4 =1- 2c 2d =2 1e == *-

input 2 **kern *M4/4 =1- 2f 2g =2 2a 2b =3 1cc == *-

notearray -I --mo 1000 input1 input2 1001 1 162 1001 3 168 1002 1 174 2001 1 179 2001 3 185 2002 1 191 2002 3 197 2003 1 202

Absolute beat values

When multiple files are input, the absolute beat values generated by the -a option will continue across multiple files. To rest the absolute beat values for each input, use the --sa (--separate-absolute) option. Note in the following example that the third column (absolute beat) in the first output reset to zero at the start of the output for the second input file, while in the second notearray output starts the absolute beat position of the second file at the ending duration of the first file.

input 1 **kern *M4/4 =1- 2c 2d =2 1e == *-

input 2 **kern *M4/4 =1- 2f 2g =2 2a 2b =3 1cc == *-

notearray -Ia input* 1 1 0 162 1 3 2 168 2 1 4 174 1 1 8 179 1 3 10 185 2 1 12 191 2 3 14 197 3 1 16 202

notearray -Ia --sa input* 1 1 0 162 1 3 2 168 2 1 4 174 1 1 0 179 1 3 2 185 2 1 4 191 2 3 6 197 3 1 8 202

Constant-duration sonorities

To generate note arrays with a constant duration for each row, pre-process the Humdrum data with the standard Humdrum Toolkit program timebase. The timebase command is used to insert null record rows into the original data so that a constant spacing at the given rhythmic duration is given to each line of data.

In the following example, the smallest rhythm is a sixteenth note, so the timebase rhythm is set to 16 which makes each line of data represent a sixteenth note.

timebase -t 16 input **kern **kern **kern **kern *tb16 *tb16 *tb16 *tb16 =7 =7 =7 =7 *M3/4 *M3/4 *M3/4 *M3/4 4D 8FL 8A 4f . . . . . 8GJ 4d . . . . . 4AA 4A . 4e . . . . . . 8c# . . . . . 4D 4F 4A 4d . . . . . . . . . . . . =8 =8 =8 =8 4D 8BL 4f 8ddL . . . . . 8AJ . 8ccJ . . . . 4E 4G# 8BL 4b . . . . . . 16cL . . . 16dJJ . 4AA 4E 4c 4a . . . . . . . . . . . . = = = = *- *- *- *-

timebase -t 16 input | notearray ##bar ##beat ##b40 ##b40 ##b40 ##b40 7 1 128 139 151 179 7 1.25 -128 -139 -151 -179 7 1.5 -128 145 168 -179 7 1.75 -128 -145 -168 -179 7 2 111 151 -168 174 7 2.25 -111 -151 -168 -174 7 2.5 -111 -151 163 -174 7 2.75 -111 -151 -163 -174 7 3 128 139 151 168 7 3.25 -128 -139 -151 -168 7 3.5 -128 -139 -151 -168 7 3.75 -128 -139 -151 -168 8 1 128 157 179 208 8 1.25 -128 -157 -179 -208 8 1.5 -128 151 -179 202 8 1.75 -128 -151 -179 -202 8 2 134 146 157 197 8 2.25 -134 -146 -157 -197 8 2.5 -134 -146 162 -197 8 2.75 -134 -146 168 -197 8 3 111 134 162 191 8 3.25 -111 -134 -162 -191 8 3.5 -111 -134 -162 -191 8 3.75 -111 -134 -162 -191

Bach chorales

Here is a demonstration of how to generate data for 370 Bach chorales in a single step:

    notearray --mo 1000 --mel --sep -ali *.krn > bachchorales.txt
 

The output file contains 30279 sonorities from all of the chorales, with a total duration of 19814 quarter notes.

The --sep option is used to place a comment line between analyses from different input files. The "--mo 1000" option is used to store the file name in the 1000's digit of the measure numbers in the output data.

Separating sonorities into beats/offbeats

A simple method of separating sonorities occurring on the beat or off-beat can be done using the hgrep program to select tokens in the **beat column depending on whether they contain a decimal point or not. Sonorities on beats will have an integer beat position without a decimal point, while sonorities on offbeats will have a beat position containing a decimal point and a fractional part.

Extracting sonorities off of the beat:

notearray -HMk h://371chorales/chor002.krn | hgrep -Fx '**beat' '\.' !!!COM: Bach, Johann Sebastian !!!CDT: 1685/02/21/-1750/07/28/ !!!OTL@@DE: Ich dank dir, lieber Herre !!!SCT: BWV 347 !!!PC#: 2 !!!AGN: chorale **beat **kern **b40 **kern **b40 **kern **b40 **kern **b40 4.5 G# 146 c#] -163 e] -174 a] -191 2.5 C#] -123 B 157 e] -174 a] -191 3.5 D] -128 G# 146 f#] -180 a] -191 2.5 BB] -117 A 151 d#] -169 f#] -180 2.5 B] -157 d#] -169 f# 180 b] -197 4.5 A 151 c#] -163 e] -174 f# 180 2.5 BB] -117 A 151 d#] -169 f#] -180 1.5 C#] -123 G#] -146 b 197 ee] -214 1.5 G# 146 B 157 a] -191 dd] -208 2.5 A] -151 d 168 a] -191 cc#] -203 4.5 AA 111 e] -174 g 185 a] -191 1.5 D] -128 d] -168 g# 186 b 197 2.5 D 128 e] -174 a] -191 cc#] -203 1.5 BB] -117 [B 157 a 191 dd] -208 2.5 C#] -123 A# 152 g] -185 cc#] -203 3.5 G 145 B] -157 e 174 b] -197 4.5 C#] -123 G#] -146 d 168 e] -174 2.5 D 128 F# 140 d] -168 b] -197 3.5 C#] -123 e 174 e] -174 cc#] -203 4.5 BB] -117 d] -168 g# 186 dd] -208 1.5 BB 117 d 168 a_ -191 ee] -214 2.5 D 128 f# 180 a] -191 cc# 203 1.5 G# 146 e 174 g# 186 cc#] -203 2.5 A] -151 c# 163 f#] -180 b] -197 3.5 E 134 B] -157 e] -174 ee_ -214 4.5 A] -151 d 168 g# 186 dd 208 1.5 G# 146 e_ -174 a_ -191 b 197 2.5 F#] -140 d 168 a] -191 b 197 3.5 D 128 f# 180 a] -191 cc#] -203 4.5 E_ -134 e 174 g#_ -186 b_ -197 4.75 E] -134 d 168 g#] -186 b] -197 *- *- *- *- *- *- *- *- *- !!!hum2abc: -Q '' !!!title: @{PC#}. @{OTL@@DE} !!!YOR1: 371 vierstimmige Choralgesänge von Johann Sebastian Bach, !!!YOR2: 4th ed. by Alfred Dörffel (Leipzig: Breitkopf und Härtel, !!!YOR2: c.1875). 178 pp. Plate "V.A.10". reprint: J.S. Bach, 371 Four-Part !!!YOR4: Chorales (New York: Associated Music Publishers, Inc., c.1940). !!!SMS: B&H, 4th ed, Alfred Dörffel, c.1875, plate V.A.10 !!!EED: Craig Stuart Sapp !!!EEV: 2009/05/22

Extracting sonorities on the beat:

notearray -HMk h://371chorales/chor002.krn | hgrep -Fvx '**beat' '\.' !!!COM: Bach, Johann Sebastian !!!CDT: 1685/02/21/-1750/07/28/ !!!OTL@@DE: Ich dank dir, lieber Herre !!!SCT: BWV 347 !!!PC#: 2 !!!AGN: chorale **beat **kern **b40 **kern **b40 **kern **b40 **kern **b40 4 A 151 [c# 163 [e 174 [a 191 1 F# 140 c# 163 f# 180 a 191 2 [C# 123 c# 163 [e 174 [a 191 3 [D 128 A 151 [f# 180 [a 191 4 D# 129 F# 140 f# 180 b 197 1 E 134 [B 157 e 174 g 185 2 [BB 117 B] -157 [d# 169 [f# 180 3 EE 94 G# 146 B 157 e 174 4 E 134 e 174 g# 186 b 197 1 A 151 e 174 a 191 cc# 203 2 [B 157 [d# 169 g# 186 [b 197 3 c# 163 [c# 163 [e 174 a 191 4 B 157 c#_ -163 e_ -174 g# 186 1 B 157 [B 157 e 174 g# 186 2 [BB 117 B] -157 [d# 169 [f# 180 3 E 134 G# 146 B 157 e 174 1 [C# 123 [G# 146 cc# 203 [ee 214 1 F# 140 A 151 [a 191 [dd 208 2 [A 151 c# 163 [a 191 [cc# 203 3 E 134 e 174 g# 186 b 197 4 C# 123 [e 174 a 191 [a 191 1 [D 128 [d 168 f# 180 a 191 2 C# 123 [e 174 [a 191 [cc# 203 3 E 134 e 174 g# 186 b 197 4 C# 123 e 174 a# 192 cc# 203 1 [BB 117 f# 180 b 197 [dd 208 2 [C# 123 B] -157 [g 185 [cc# 203 3 D 128 [B 157 f# 180 [b 197 4 F# 140 c# 163 f# 180 a# 192 1 BB 117 d 168 f# 180 b 197 4 [C# 123 [G# 146 e 174 [e 174 1 F# 140 A 151 c# 163 a 191 2 E 134 G# 146 [d 168 [b 197 3 [C# 123 E 134 [e 174 [cc# 203 4 [BB 117 [d 168 f# 180 [dd 208 1 AA 111 c# 163 [a 191 [ee 214 2 C# 123 e 174 a_ -191 dd 208 3 E 134 g# 186 e 174 b 197 4 BB 117 f# 180 b 197 dd 208 1 F# 140 f# 180 a 191 [cc# 203 2 [A 151 d 168 [f# 180 [b 197 3 G# 146 [B 157 [e 174 [ee 214 4 [A 151 c# 163 f# 180 ee] -214 1 A 151 [e 174 [a 191 cc# 203 2 [F# 140 e] -174 a_ -191 a 191 3 E 134 c# 163 [a 191 [cc# 203 4 [E 134 B 157 [g# 186 [b 197 1 AA 111 c# 163 e 174 a 191 *- *- *- *- *- *- *- *- *- !!!hum2abc: -Q '' !!!title: @{PC#}. @{OTL@@DE} !!!YOR1: 371 vierstimmige Choralgesänge von Johann Sebastian Bach, !!!YOR2: 4th ed. by Alfred Dörffel (Leipzig: Breitkopf und Härtel, !!!YOR2: c.1875). 178 pp. Plate "V.A.10". reprint: J.S. Bach, 371 Four-Part !!!YOR4: Chorales (New York: Associated Music Publishers, Inc., c.1940). !!!SMS: B&H, 4th ed, Alfred Dörffel, c.1875, plate V.A.10 !!!EED: Craig Stuart Sapp !!!EEV: 2009/05/22

Extract sonorities on the beat, including sonorities containing only sustained notes:

humcat h://371chorales/chor002.krn | timebase -t 8 \    | notearray -HMk | hgrep -Fvx '**beat' '\.' !!!COM: Bach, Johann Sebastian !!!CDT: 1685/02/21/-1750/07/28/ !!!OTL@@DE: Ich dank dir, lieber Herre !!!SCT: BWV 347 !!!PC#: 2 !!!AGN: chorale **beat **kern **b40 **kern **b40 **kern **b40 **kern **b40 4 A 151 [c# 163 [e 174 [a 191 1 [F# 140 [c# 163 [f# 180 [a 191 2 [C# 123 c# 163 [e 174 [a 191 3 [D 128 A 151 [f# 180 [a 191 4 [D# 129 [F# 140 [f# 180 [b 197 1 [E 134 [B 157 [e 174 [g 185 2 [BB 117 B] -157 [d# 169 [f# 180 3 [EE 94 [G# 146 [B 157 [e 174 4 [E 134 [e 174 [g# 186 [b 197 1 [A 151 [e 174 [a 191 [cc# 203 2 [B 157 [d# 169 g# 186 [b 197 3 [c# 163 [c# 163 [e 174 [a 191 4 B 157 c#_ -163 e_ -174 g# 186 1 [B 157 [B 157 [e 174 [g# 186 2 [BB 117 B] -157 [d# 169 [f# 180 3 [E 134 [G# 146 [B 157 [e 174 1 [C# 123 [G# 146 cc# 203 [ee 214 1 F# 140 A 151 [a 191 [dd 208 2 [A 151 c# 163 [a 191 [cc# 203 3 [E 134 [e 174 [g# 186 [b 197 4 C# 123 [e 174 a 191 [a 191 1 [D 128 [d 168 f# 180 a 191 2 C# 123 [e 174 [a 191 [cc# 203 3 [E 134 [e 174 [g# 186 [b 197 4 [C# 123 [e 174 [a# 192 [cc# 203 1 [BB 117 f# 180 b 197 [dd 208 2 [C# 123 B] -157 [g 185 [cc# 203 3 D 128 [B 157 f# 180 [b 197 4 [F# 140 [c# 163 [f# 180 [a# 192 1 [BB 117 [d 168 [f# 180 [b 197 2 BB_ -117 d_ -168 f#_ -180 b_ -197 3 BB_ -117 d_ -168 f#_ -180 b_ -197 4 [C# 123 [G# 146 e 174 [e 174 1 [F# 140 [A 151 [c# 163 [a 191 2 E 134 G# 146 [d 168 [b 197 3 [C# 123 E 134 [e 174 [cc# 203 4 [BB 117 [d 168 f# 180 [dd 208 1 AA 111 c# 163 [a 191 [ee 214 2 C# 123 e 174 a_ -191 dd 208 3 [E 134 [g# 186 [e 174 [b 197 4 [BB 117 [f# 180 [b 197 [dd 208 1 F# 140 f# 180 a 191 [cc# 203 2 [A 151 d 168 [f# 180 [b 197 3 G# 146 [B 157 [e 174 [ee 214 4 [A 151 c# 163 f# 180 ee] -214 1 A 151 [e 174 [a 191 cc# 203 2 [F# 140 e] -174 a_ -191 a 191 3 E 134 c# 163 [a 191 [cc# 203 4 [E 134 B 157 [g# 186 [b 197 1 [AA 111 [c# 163 [e 174 [a 191 *- *- *- *- *- *- *- *- *- !!!hum2abc: -Q '' !!!title: @{PC#}. @{OTL@@DE} !!!YOR1: 371 vierstimmige Choralgesänge von Johann Sebastian Bach, !!!YOR2: 4th ed. by Alfred Dörffel (Leipzig: Breitkopf und Härtel, !!!YOR2: c.1875). 178 pp. Plate "V.A.10". reprint: J.S. Bach, 371 Four-Part !!!YOR4: Chorales (New York: Associated Music Publishers, Inc., c.1940). !!!SMS: B&H, 4th ed, Alfred Dörffel, c.1875, plate V.A.10 !!!EED: Craig Stuart Sapp !!!EEV: 2009/05/22

Count the pitch classes in sonorities on offbeats:

notearray -HMk h://371chorales/chor002.krn --no-ties \ | hgrep -Fx '**beat' '\.' | extract -i '**kern' \ | serialize | rid -GLId | tr -s "a-g" "A-G" | sort | uniq -c

20 A 1 A# 21 B 15 C# 19 D 3 D# 19 E 10 F# 3 G 13 G#

Count the number of pitch classes attacked on offbeats:

notearray -HMTk h://371chorales/chor002.krn \ | hgrep -Fx '**beat' '\.' | extract -i '**kern' \ | serialize | rid -GLId | grep '\[' | sed 's/[][]//g' \ | tr -s "a-g" "A-G" | sort | uniq -c

5 A 1 A# 8 B 2 C# 11 D 5 E 5 F# 2 G 9 G#

Using data in MS Excel

The output from notearray can be loaded into MS Excel as a tab-deliminated text file (either the default matlab-style output, or the Humdrum output generated by the -H option). In addition, the output data can be copy/pasted from text editors/word processors which preserve tab charcters, such as the following textarea box on this HTML page: ##bar ##beat ##b40 ##b40 ##b40 ##b40 7 1 128 139 151 179 7 1.5 -128 145 168 -179 7 2 111 151 -168 174 7 2.5 -111 -151 163 -174 7 3 128 139 151 168 8 1 128 157 179 208 8 1.5 -128 151 -179 202 8 2 134 146 157 197 8 2.5 -134 -146 162 -197 8 2.75 -134 -146 168 -197 8 3 111 134 162 191

Below is a screenshot of the above data loaded into an MS Excel spreadsheet (xlsx, xls). The intervals between each voice are shown in the dark green box in the middle, with a histogram calculated in the light green box on the right which is plotted underneath. Note that the hightlighed cell (H2) contains the equation "=MOD(ABS(D2))-ABS(C2),40)" which is the interval between the tenor and bass voices (collapsed to less than an octave). Columns O and P contain a mapping of the interval value to a more musical name for the interval, with 11 being a minor third (m3). Click on the image for a larger view.



More example usages of the notearray program are available on the notearray examples page

Input arguments or piped data which are expected to be Humdrum files can also be web addresses. For example, if a program can process files like this:

       program file.krn

It can also read the data over the web:

       program http://www.some-computer.com/some-directory/file.krn

Piped data works in a somewhat similar manner:

       cat file.krn | program

is equivalent to a web file using ths form:

       echo http://www.some-computer.com/some-directory/file.krn | program

Besides the http:// protocol, there is another special resource indicator prefix called humdrum:// which downloads data from the kernscores website. For example, using the URI humdrum://brandenburg/bwv1046a.krn:

      program humdrum://brandenburg/bwv1046a.krn

will download the URL:

http://kern.humdrum.org/cgi-bin/ksdata?file=bwv1046a.krn&l=/brandenburg&format=kern
Which is found in the Musedata Bach Brandenburg Concerto collection.

This online-access of Humdrum data can also interface with the classical Humdrum Toolkit commands by using humcat to download the data from the kernscores website. For example, try the command pipeline:

      humcat humdrum://brandenburg/bwv1046a.krn | census -k

• The notearray program can only process monophonic parts. To process parts containing sub-spines, treated as independent voices, you can use the sub-spine extraction options of extractx.

• Only a single voice will be extracted from each **kern spine. If the music in that spine splits into sub-voices, only the left-most subspine after the split will be stored in the output data. See the subspine options of extractx for methods of generating monophonic lines out of a polyphonic part.
• Only the first note in a chord (left-most note in a multi-stop token) are extractable into the note array.
• For music with very low notes, use the -o option to shift the octave encoding level upwards; otherwise, note attacks and sustains will become mixed up. For piano music, this means the bottom three notes of the keyboard: A-1, B♭-1, and B-1. C0 with the -d option and C♭♭0 for the default base-40 pitch enumerations will also cause problems, since the number 0 is intended to represent rests.
• Fermatas should be used to mark rest segmentation boundaries in the output data. Currently only the --double option will produce a rest segmentation.

The compiled notearray program can be downloaded for the following platforms:
• Linux (i386 processors) (dynamically linked) compiled on 13 Nov 2013.
• Windows compiled on 29 Jun 2012.
• Mac OS X/i386 compiled on 13 Nov 2013.

The source code for the program was last modified on 12 Nov 2013. Click here to go to the full source-code download page.