Keycor is a generalization of the key-finding algorithm used in the Humdrum toolkit program key. While key is limited to a fixed set of key-weightings, keycor has a selection of 5 preset weightings, plus the ability for users of the program to provide their own set of weightings.
Pearson correlation is used by the program to identify the best key. Correlation takes two sequences and calculates a value between -1.0 and +1.0. An absolute correlation value near zero indicates a poor match, while a value of +1.0 indicates a good match. Using the Krumhansl-Schmuckler algorithm, Pearson correlation values are calculated between a histogram of the twelve-tone pitch-classes in a musical sample and each of the 24 major and minor key profiles.
Here is the mathematical definition of Pearson correlation:
Generating a pitch histogramAn input pitch histogram for the Krumhansl-Schmuckler key-finding algorithm counts the duration of each pitch-class chroma present in the music. The -D option can be used to turn off duration weighting of note attacks (so that only note attacks and not note durations are stored in the input histogram). Here is an example segmenent of music:
Beneath the music is a list of the twelve pitch-classes present in the example, along with a count of how many eighth-notes worth of duration for each pitch class. Therefore the first input list to the correlation calculation is: (8, 0, 0, 0, 2, 11, 0, 5, 7, 0, 5, 2).
The second input into the correlation calculation is a list of weightings for the major/minor key being compared to. For example, using the simple weight set below the second input would be: (2, 0, 1, 0, 1, 1, 0, 2, 0, 1, 0, 1). And the resulting correlation value is 0.35.
The same process is continued, treating C-sharp/D-flat as the tonic note (which is equivalent to rotating the key-weights to the right by one element: (1, 2, 0, 1, 0, 1, 1, 0, 2, 0, 1, 0) (or equivalently, rotate the pitch-class histogram one element to the left). In this case the correlation value with C-sharp major and the extracted histogram is 0.25. Since 0.25 is less than 0.35, the algorithm thinks that the music fits C major better than C-sharp major. This process continues for the 10 other major keys, and also the 12 minor keys, and the key which generates the highest correlation value is presumed to be the actual key of the music:
For the above musical example, the highest correlation corresponds to F minor, which generates a correlation of 0.79.
By default keycor uses the same weightings as key. These weightings are the experimentally-derived probe-tone ratings of Krumhansl and Kessler (listed below). The above table of calculations and search for the key which yeilds the maximum correlation value can be expressed mathematically in the following equation for the Krumhansl-Schmuckler key-finding algorithm:
Key-profile weightsThere are 5 preset key-profile weight sets available in the keycor program. By default, the Krumhansl-Kessler weights will be used. Other weights can be selected with the option listed above each set in the following table:
Non-standard pitch profiles can be specified in a file which is given as input with the -w option. The weight file must have at least two spine: one **kern spine containing the pitch class -- upper case for major keys and lower case for minor keys; and a **number spine which contains the weighting for that pitch class and mode. There may be other spines in the file, but there should be only one **kern and **number spine in the file for predictable results. Here is an example pitchclass weight file using the same weights used with the -s option:
Here is a plot showing the relative weights of each scale-degree in the above five key-weighting sets. Major keys weights are shown in the top plot, and minor key weights in the bottom plot. The weights are normalized for direct comparison so that their standard deviation is 1 and the mean is 0 (which is what happens to the sequence when pearson correlation is used). KK (light blue) = Krumhansl-Kessler weights; S (red) = simple; KP (green) = Temperley-Kostka-Payne; BB (purple) = Bellman-Budge; AE (dark blue) = Aarden-Essen.
Weightings between the various sets are about the same for scale-degrees outside of the scale (particularly in the major scale). The Krumhansl-Kessler weights have the strongest weighting for the tonic in both major and minor keys. This causes these weightings to confuse the tonic and dominant more often than other weight sets. The sixth scale degree in major scales for all weight sets is mostly ignored.
General characteristics of preset key-weightings
The following table lists key-identification errors for five sets of key-profile weights. Each column represents a set of 24 compositions in all of the major and minor keys. 96 compositions from the Well-tempered Clavier, Books I & II by Johann Sebastian Bach, and 24 preludes, Op. 28 by Frédéric Chopin. Only errors are noted in the table, with blank cells indicating that the correct key was identified by the correlation algorithm using the specified key-profile weights.
Errors are categorized as follows:
program file.krnIt can also read the data over the web:
program http://www.some-computer.com/some-directory/file.krnPiped data works in a somewhat similar manner:
cat file.krn | programis 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.krnwill download the URL:
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