head_music 22.0.0 → 23.0.0

data/Gemfile.lock

@@ -1,15 +1,16 @@
 PATH
   remote: .
   specs:
-    head_music (22.0.0)
+    head_music (23.0.0)
       activesupport (>= 7.0, < 10)
       humanize (>= 2, < 4)
       i18n (~> 1.8)
+      rexml (~> 3.4, >= 3.4.2)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (8.1.3.1)
+    activesupport (8.1.4)
       base64
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.3.1)
@@ -30,7 +31,7 @@ GEM
       ice_nine (~> 0.11.0)
       thread_safe (~> 0.3, >= 0.3.1)
     base64 (0.3.0)
-    bigdecimal (4.1.2)
+    bigdecimal (4.1.3)
     bundler-audit (0.9.3)
       bundler (>= 1.2.0)
       thor (~> 1.0)
@@ -87,7 +88,7 @@ GEM
     i18n (1.15.2)
       concurrent-ruby (~> 1.0)
     ice_nine (0.11.2)
-    json (2.21.2)
+    json (3.1.0)
     kramdown (2.5.2)
       rexml (>= 3.4.4)
     language_server-protocol (3.17.0.6)
@@ -101,7 +102,7 @@ GEM
       drb (~> 2.0)
       prism (~> 1.5)
     ostruct (0.6.3)
-    parallel (2.1.0)
+    parallel (2.3.0)
     parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
@@ -117,7 +118,7 @@ GEM
       parser (~> 3.3.0)
       rainbow (>= 2.0, < 4.0)
       rexml (~> 3.1)
-    regexp_parser (2.12.0)
+    regexp_parser (2.13.1)
     rexml (3.4.4)
     rspec (3.13.2)
       rspec-core (~> 3.13.0)
@@ -135,8 +136,8 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubocop (1.88.2)
-      json (~> 2.3)
+    rubocop (1.91.0)
+      json (>= 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
       parallel (>= 1.10)
@@ -179,12 +180,12 @@ GEM
       tty-which (~> 0.5.0)
       virtus (~> 2.0)
     securerandom (0.4.1)
-    sexp_processor (4.17.5)
+    sexp_processor (4.17.6)
     simplecov (1.0.3)
-    standard (1.56.0)
+    standard (1.57.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.88.0)
+      rubocop (~> 1.91.0)
       standard-custom (~> 1.0.0)
       standard-performance (~> 1.8)
     standard-custom (1.0.2)
@@ -198,10 +199,10 @@ GEM
     tty-which (0.5.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (3.2.0)
-      unicode-emoji (~> 4.1)
-    unicode-emoji (4.2.0)
-    uri (1.1.1)
+    unicode-display_width (3.3.0)
+      unicode-emoji (~> 4.3)
+    unicode-emoji (4.3.0)
+    uri (1.1.2)
     virtus (2.0.0)
       axiom-types (~> 0.1)
       coercible (~> 1.0)
@@ -220,7 +221,6 @@ DEPENDENCIES
   head_music!
   kramdown
   rake (~> 13.0)
-  rexml (~> 3.4)
   rspec (~> 3.0)
   rspec-its (~> 2.0)
   rubocop-rake

data/README.md

@@ -14,7 +14,7 @@ The **head_music** Ruby gem provides a toolkit for working with Western music th
 - **Style Analysis**: Rules for species counterpoint and voice leading
 - **Internationalization**: Support for multiple languages (English, French, German, Italian, Russian, Spanish)
 - **Instrument Modeling**: Extensive database of musical instruments with ranges and properties
-- **Notation Formats**: Read ABC and LilyPond into compositions; write compositions as ABC, LilyPond, and MusicXML
+- **Notation Formats**: Read ABC, LilyPond, and Humdrum `**kern` into compositions; write compositions as ABC, LilyPond, MusicXML, and `**kern`
 
 ## Installation
 
@@ -64,7 +64,17 @@ puts composition.voices.first.pitches.map(&:to_s)  # => ["G3", "A3", "B3", "C4",
 puts composition.to_lilypond                        # => a complete LilyPond document
 ```
 
-The LilyPond reader covers absolute and `\relative` pitches, durations and dots, rests and whole-bar rests, chords, intra-bar ties, `\key`, `\time`, `\clef`, bar checks, `\header` title and composer, and `\new Staff` / `\new Voice` contexts. Constructs outside that subset (tuplets, lyrics, variables, articulations, and so on) raise an `UnsupportedFeatureError` rather than being skipped.
+The LilyPond reader covers absolute and `\relative` pitches, durations and dots, rests and whole-bar rests, chords, ties (including across bar checks), `\key`, `\time`, `\clef`, bar checks, `\header` title and composer, `\new Staff` / `\new Voice` contexts, and grand staves and staff groups with `\change Staff`. Constructs outside that subset (tuplets, lyrics, variables, articulations, and so on) raise an `UnsupportedFeatureError` rather than being skipped.
+
+```ruby
+# Read a Humdrum **kern file, such as a Bach chorale from KernScores
+chorale = HeadMusic::Notation::Kern.parse(File.read("chor001.krn"))
+chorale.parts.map { |part| part.player.name }  # => ["Soprano", "Alto", "Tenor", "Bass"]
+chorale.work.catalog_number                     # => "BWV 269"
+puts chorale.to_kern                            # => the same spines back
+```
+
+The kern reader covers pitches, durations and dots, rests, chords, ties across barlines, pickups and short final bars, repeat barlines, `*k`, key and mode designations, `*M`, `*MM`, `*clef`, `*I` names and vocal and piano codes, `*part` / `*staff` grouping, spine splits, joins, and exchanges, `**text` lyrics, and the reference records of a work. Tuplets, `*+`, and transposed spines raise an `UnsupportedFeatureError`; grace notes, ornaments, articulations, beams, and fermatas are dropped.
 
 ## Style Analysis
 

data/Rakefile

@@ -1,6 +1,8 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
-require "standard/rake"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
 
 # The block runs when the task does, just before rspec is launched.
 RSpec::Core::RakeTask.new(:spec) { ENV["COVERAGE"] = "true" }
@@ -27,15 +29,25 @@ rescue LoadError
   # bundler-audit not available
 end
 
-desc "Run RubyCritic code quality analysis"
+desc "Run only the specs checked against outside tools and files, each missing one skipping with how to set it up"
+RSpec::Core::RakeTask.new(:oracles) { ENV["ORACLES"] = "1" }
+
+desc "Run RubyCritic code quality analysis, failing below .rubycritic.yml's minimum score or on any file graded D or F"
 task :rubycritic do
-  sh "rubycritic lib"
+  require "json"
+  sh "rubycritic"
+  report = JSON.parse(File.read("tmp/rubycritic/report.json"))
+  failing = report["analysed_modules"].select { |file| %w[D F].include?(file["rating"]) }
+  next if failing.empty?
+
+  failing.each { |file| warn format("%s %5.2f %s", file["rating"], file["cost"], file["path"]) }
+  abort "RubyCritic graded #{failing.length} file(s) below C"
 end
 
 task default: :spec
 
 desc "Run all validation checks (tests, linting, security audit, code quality)"
-task validate: [:spec, :standard, "bundle:audit:check", :rubycritic]
+task validate: [:spec, :rubocop, "bundle:audit:check", :rubycritic]
 
 desc "Open an irb session preloaded with this library"
 task :console do
@@ -47,6 +59,73 @@ task :coverage do
   sh "open coverage/index.html" if File.exist?("coverage/index.html")
 end
 
+namespace :music_xml do
+  desc "Regenerate the MuseScore 4 and timewise fixtures (spec/fixtures/notation/music_xml/); MSCORE overrides the mscore path"
+  task :musescore_fixtures do
+    $LOAD_PATH.unshift File.expand_path("lib", __dir__)
+    require "head_music"
+    require "rspec/core"
+    require "shellwords"
+    require_relative "spec/support/musescore"
+
+    with_final_newline = ->(path) { File.write(path, File.read(path).chomp + "\n") }
+    MuseScoreFixtures.names.each do |name|
+      rendered = MuseScoreFixtures.path(name, "head_music")
+      File.write(rendered, MuseScoreFixtures.musicxml(name))
+      MuseScore.convert_file(rendered, MuseScoreFixtures.path(name, "musescore4"))
+      with_final_newline.call(MuseScoreFixtures.path(name, "musescore4"))
+      puts "Wrote #{name}"
+    end
+
+    stylesheet = "/Applications/Dorico 6.app/Contents/Resources/musicxml/parttime.xsl"
+    next puts("Skipped the timewise fixtures: #{stylesheet} not found") unless File.exist?(stylesheet)
+
+    MuseScoreFixtures::TIMEWISE.each do |name|
+      timewise = MuseScoreFixtures.path(name, "timewise")
+      sh "xsltproc --nonet --novalid #{stylesheet.shellescape} #{MuseScoreFixtures.path(name, "head_music").shellescape} > #{timewise.shellescape}"
+      with_final_newline.call(timewise)
+      puts "Wrote #{name} timewise"
+    end
+  end
+end
+
+namespace :mei do
+  desc "Regenerate the MEI golden documents (spec/fixtures/notation/mei/)"
+  task :golden_fixtures do
+    $LOAD_PATH.unshift File.expand_path("lib", __dir__), File.expand_path("spec", __dir__)
+    require "rspec/core"
+    require "spec_helper"
+
+    MEIFixtures.names.each do |name|
+      File.write(MEIFixtures.path(name), MEIFixtures.mei(name))
+      puts "Wrote #{name}"
+    end
+  end
+
+  desc "Regenerate the MuseScore 4 MEI exports (spec/fixtures/notation/mei/musescore/); MSCORE overrides the mscore path"
+  task :musescore_fixtures do
+    $LOAD_PATH.unshift File.expand_path("lib", __dir__)
+    require "head_music"
+    require "rspec/core"
+    require_relative "spec/support/musescore"
+
+    target_directory = File.expand_path("spec/fixtures/notation/mei/musescore", __dir__)
+    FileUtils.mkdir_p(target_directory)
+    sources = Dir[File.join(MuseScoreFixtures::DIRECTORY, "*.head_music.musicxml")].sort
+    failures = sources.filter_map do |source|
+      name = File.basename(source, ".head_music.musicxml")
+      target = File.join(target_directory, "#{name}.musescore4.mei")
+      MuseScore.convert_file(source, target, timeout: 120)
+      File.write(target, File.read(target).chomp + "\n")
+      puts "Wrote #{name}"
+      nil
+    rescue MuseScore::ConversionError => error
+      "#{name}: #{error.message}"
+    end
+    abort "MuseScore failed on:\n#{failures.join("\n")}" if failures.any?
+  end
+end
+
 namespace :style do
   desc "Regenerate the pinned English guide strings (spec/fixtures/style/english_strings.yml)"
   task :snapshot_english do

data/bin/validate

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Runs the full validation: specs with coverage, Standard, the audit, and RubyCritic.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+exec bundle exec rake validate "$@"

data/head_music.gemspec

@@ -35,9 +35,9 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency "activesupport", ">= 7.0", "< 10"
   spec.add_runtime_dependency "humanize", ">= 2", "< 4"
   spec.add_runtime_dependency "i18n", "~> 1.8"
+  spec.add_runtime_dependency "rexml", "~> 3.4", ">= 3.4.2"
 
   spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "rexml", "~> 3.4"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "rspec-its", "~> 2.0"
   spec.add_development_dependency "bundler-audit", "~> 0.9"

data/lib/head_music/analysis/diatonic_interval/naming.rb

@@ -20,10 +20,8 @@ class HeadMusic::Analysis::DiatonicInterval::Naming
   end
 
   def quality_name
-    starting_quality = QUALITY_SEMITONES[simple_number_name.to_sym].keys.first
-    delta = simple_semitones - (QUALITY_SEMITONES[simple_number_name.to_sym][starting_quality] % 12)
-    delta -= 12 while delta >= 6
-    HeadMusic::Rudiment::Quality.from(starting_quality, delta)
+    starting_quality, starting_semitones = QUALITY_SEMITONES[simple_number_name.to_sym].first
+    HeadMusic::Rudiment::Quality.from(starting_quality, semitones - starting_semitones - 12 * compound_octaves)
   end
 
   def simple_number_name
@@ -34,14 +32,15 @@ class HeadMusic::Analysis::DiatonicInterval::Naming
     NUMBER_NAMES[number - 1] || (number.to_s + NAME_SUFFIXES[number % 10])
   end
 
+  # Past the named numbers, an interval is so many octaves and a simple
+  # interval. An octave altered upward adds an octave and alters the unison.
   def name
-    if named_number?
-      [quality_name, number_name].join(" ")
-    elsif simple_name == "perfect octave"
-      "#{octaves.humanize} octaves"
-    else
-      "#{octaves.humanize} octaves and #{quality.article} #{simple_name}"
-    end
+    return [quality_name, number_name].join(" ") if named_number?
+
+    octaves, remainder = octaves_and_remainder
+    return "#{octaves.humanize} octaves" unless remainder
+
+    "#{octaves.humanize} octaves and #{remainder.start_with?(/[aeiou]/) ? "an" : "a"} #{remainder}"
   end
 
   def shorthand
@@ -50,20 +49,23 @@ class HeadMusic::Analysis::DiatonicInterval::Naming
 
   private
 
-  def simple_semitones
-    @simple_semitones ||= semitones % 12
+  def named_number?
+    number <= NUMBER_NAMES.length
   end
 
-  def named_number?
-    number < NUMBER_NAMES.length
+  # The octaves added to the simple interval.
+  def compound_octaves
+    (number - simple_number) / 7
   end
 
   def quality
     @quality ||= HeadMusic::Rudiment::Quality.get(quality_name)
   end
 
-  def octaves
-    @octaves ||= semitones / 12
+  def octaves_and_remainder
+    return [compound_octaves, simple_name] unless simple_number == 8 && !quality_name.include?("diminished")
+
+    [compound_octaves + 1, ("#{quality_name} unison" unless quality_name == "perfect")]
   end
 
   def octave_equivalent?

data/lib/head_music/analysis/key_finder/histograms.rb

@@ -0,0 +1,55 @@
+class HeadMusic::Analysis::KeyFinder
+  # Duration-weighted pitch-class histograms of a NoteInput's notes: of the
+  # whole input, and of the time sounding in each bar.
+  class Histograms
+    def initialize(input)
+      @input = input
+    end
+
+    def whole
+      @input.notes.each_with_object(empty) do |note, histogram|
+        histogram[note.number % 12] += note.duration
+      end
+    end
+
+    # Each bar's histogram summed with +window+ bars on either side.
+    def windowed(window)
+      bars = by_bar
+      prefix = bars.each_with_object([empty]) { |histogram, sums| sums << sums.last.zip(histogram).map(&:sum) }
+      bars.each_index.map do |index|
+        low = [index - window, 0].max
+        high = [index + window, bars.length - 1].min
+        prefix[high + 1].zip(prefix[low]).map { |upper, lower| upper - lower }
+      end
+    end
+
+    # Each note's duration is credited to the bars it sounds in.
+    def by_bar
+      starts = @input.bar_starts.values
+      index_of_bar = @input.bar_starts.keys.each_with_index.to_h
+      histograms = Array.new(starts.length) { empty }
+      @input.notes.each do |note|
+        credit(histograms, starts, note, index_of_bar.fetch(@input.bar_at(note.onset)))
+      end
+      histograms
+    end
+
+    private
+
+    def credit(histograms, starts, note, bar_index)
+      from = note.onset
+      finish = note.onset + note.duration
+      while from < finish
+        bar_end = starts[bar_index + 1]
+        to = (bar_end.nil? || finish < bar_end) ? finish : bar_end
+        histograms[bar_index][note.number % 12] += to - from
+        from = to
+        bar_index += 1
+      end
+    end
+
+    def empty
+      Array.new(12, 0r)
+    end
+  end
+end

data/lib/head_music/analysis/key_finder/key_path.rb

@@ -0,0 +1,39 @@
+class HeadMusic::Analysis::KeyFinder
+  # The key index for each bar that maximizes the summed scores, less the
+  # change penalty for every change of key: Viterbi over bars and keys. A tie
+  # keeps the key in force, then goes by preference. A bar that
+  # scores nothing changes no key, so a change waits for the music.
+  class KeyPath
+    def initialize(scores, change_penalty:, preference:)
+      @scores = scores
+      @change_penalty = change_penalty
+      @preference = preference
+    end
+
+    def to_a
+      totals = @scores.first.dup
+      back_pointers = @scores.drop(1).map do |bar_scores|
+        next totals.each_index.to_a if bar_scores.all?(&:zero?)
+
+        pointers = pointers_from(totals)
+        totals = pointers.each_with_index.map { |from, index| totals[from] - ((from == index) ? 0 : @change_penalty) + bar_scores[index] }
+        pointers
+      end
+      path = [best_index(totals)]
+      back_pointers.reverse_each { |pointers| path.unshift(pointers[path.first]) }
+      path
+    end
+
+    private
+
+    def pointers_from(totals)
+      leader = best_index(totals)
+      moved = totals[leader] - @change_penalty
+      totals.each_index.map { |index| (totals[index] >= moved) ? index : leader }
+    end
+
+    def best_index(totals)
+      totals.each_index.min_by { |index| [-totals[index], *@preference[index]] }
+    end
+  end
+end

data/lib/head_music/analysis/key_finder.rb

@@ -0,0 +1,105 @@
+# A module for musical analysis
+module HeadMusic::Analysis; end
+
+# Infers the key of unspelled notes by correlating their duration-weighted
+# pitch-class histogram with a key profile (Krumhansl, Cognitive Foundations
+# of Musical Pitch, 1990; Temperley, The Cognition of Basic Musical
+# Structures, 2001). The input is anything NoteInput.for reads.
+#
+# Over a whole piece it answers key regions, each starting at a downbeat. Each
+# bar is scored by the histogram of the time sounding in it, summed with
+# +window+ bars on either side. The regions maximize the summed correlation of
+# each bar with its key, less +change_penalty+ for every change of key, so a
+# region is worth starting only where it gains more than the penalty. The
+# first region's tonic is spelled as KEYS spells it, and each later one by the
+# enharmonic nearer the previous region's on the line of fifths, so a piece in
+# B major moves to F♯ major rather than to G♭ major.
+class HeadMusic::Analysis::KeyFinder
+  # The 24 keys a key finder chooses among, fixed by name rather than built
+  # through Key#relative. Of each enharmonic pair the tonic with fewer
+  # accidentals wins; at six apiece, G♭ major and E♭ minor share a signature.
+  KEYS = [
+    *%w[C D♭ D E♭ E F G♭ G A♭ A B♭ B].map { |tonic| "#{tonic} major" },
+    *%w[C C♯ D E♭ E F F♯ G G♯ A B♭ B].map { |tonic| "#{tonic} minor" }
+  ].map { |name| HeadMusic::Rudiment::Key.get(name) }.freeze
+
+  # On equal correlation, the key with fewer accidentals, then major, then the
+  # lower tonic pitch class.
+  PREFERENCE = KEYS.map do |key|
+    [key.key_signature.num_alterations, key.major? ? 0 : 1, key.tonic_spelling.pitch_class.to_i]
+  end.freeze
+
+  Candidate = Data.define(:key, :correlation)
+
+  attr_reader :input, :profile, :change_penalty, :window
+
+  def initialize(input, profile: :aarden_essen, change_penalty: 1.0, window: 0, **note_input_options)
+    unless change_penalty.is_a?(Numeric) && change_penalty.real? && change_penalty >= 0
+      raise ArgumentError, "change_penalty: must be a non-negative Numeric"
+    end
+    raise ArgumentError, "window: must be a non-negative Integer" unless window.is_a?(Integer) && !window.negative?
+
+    @input = HeadMusic::Analysis::NoteInput.for(input, **note_input_options)
+    @profile = HeadMusic::Analysis::KeyProfile.get(profile)
+    @change_penalty = change_penalty
+    @window = window
+  end
+
+  # The best key for the whole input, or nil when nothing sounds.
+  def key
+    candidates.first&.key
+  end
+
+  # All 24 keys, best first, or none when nothing sounds.
+  def candidates
+    @candidates ||= begin
+      histogram = Histograms.new(input).whole
+      if histogram.sum.zero?
+        []
+      else
+        ranked(profile.correlations(histogram)).map { |index, correlation| Candidate.new(KEYS[index], correlation) }.freeze
+      end
+    end
+  end
+
+  # The key regions of the input, in bar order, or none when nothing sounds.
+  # An empty bar scores nothing, so the key in force carries through it.
+  def regions
+    @regions ||= if candidates.empty?
+      []
+    else
+      bar_starts = input.bar_starts.to_a
+      previous = nil
+      key_path.each_with_index.chunk_while { |(a, _), (b, _)| a == b }.map do |run|
+        key_index, bar_index = run.first
+        bar_number, onset = bar_starts[bar_index]
+        previous = previous ? self.class.enharmonic_nearer(KEYS[key_index], previous) : KEYS[key_index]
+        HeadMusic::Analysis::KeyRegion.new(bar_number: bar_number, onset: onset, key: previous)
+      end.freeze
+    end
+  end
+
+  # The spelling of a key whose tonic is nearer another key's on the line of
+  # fifths, within seven accidentals, keeping the key as spelled on a tie.
+  def self.enharmonic_nearer(key, other)
+    line_of_fifths = HeadMusic::Analysis::LineOfFifths
+    tonic = line_of_fifths.index_of(key.tonic_spelling)
+    target = line_of_fifths.index_of(other.tonic_spelling)
+    offset = key.major? ? 0 : -3
+    nearest = [tonic, tonic - 12, tonic + 12].select { |index| (index + offset).abs <= 7 }.min_by { |index| (index - target).abs }
+    return key if nearest == tonic
+
+    HeadMusic::Rudiment::Key.get("#{line_of_fifths.spelling_at(nearest)} #{key.quality}")
+  end
+
+  private
+
+  def key_path
+    scores = Histograms.new(input).windowed(window).map { |histogram| profile.correlations(histogram) }
+    KeyPath.new(scores, change_penalty: change_penalty, preference: PREFERENCE).to_a
+  end
+
+  def ranked(correlations)
+    correlations.each_with_index.sort_by { |correlation, index| [-correlation, *PREFERENCE[index]] }.map(&:reverse)
+  end
+end

data/lib/head_music/analysis/key_profile.rb

@@ -0,0 +1,82 @@
+# A module for musical analysis
+module HeadMusic::Analysis; end
+
+# The weight of each pitch class in a key, from the tonic upward in semitones,
+# for major and for minor. Correlating a pitch-class histogram with each of
+# the 24 rotations scores how well the music fits each key.
+#
+# The values are stored as Rationals, so that keys whose correlations are
+# equal in exact arithmetic tie exactly.
+HeadMusic::Analysis::KeyProfile = Data.define(:name, :major, :minor, :source)
+
+class HeadMusic::Analysis::KeyProfile
+  # Each table was checked against Humdrum keycor (humextra cli/keycor.cpp)
+  # and music21 (analysis/discrete.py), which agree digit for digit.
+  PROFILES = {
+    aarden_essen: {
+      major: [17.7661r, 0.145624r, 14.9265r, 0.160186r, 19.8049r, 11.3587r, 0.291248r, 22.062r, 0.145624r, 8.15494r, 0.232998r, 4.95122r],
+      minor: [18.2648r, 0.737619r, 14.0499r, 16.8599r, 0.702494r, 14.4362r, 0.702494r, 18.6161r, 4.56621r, 1.93186r, 7.37619r, 1.75623r],
+      source: "Aarden, Dynamic Melodic Expectancy, PhD dissertation, Ohio State University (2003), from the Essen Folksong Collection"
+    },
+    krumhansl_kessler: {
+      major: [6.35r, 2.23r, 3.48r, 2.33r, 4.38r, 4.09r, 2.52r, 5.19r, 2.39r, 3.66r, 2.29r, 2.88r],
+      minor: [6.33r, 2.68r, 3.52r, 5.38r, 2.60r, 3.53r, 2.54r, 4.75r, 3.98r, 2.69r, 3.34r, 3.17r],
+      source: "Krumhansl, Cognitive Foundations of Musical Pitch (1990), from Krumhansl and Kessler, Psychological Review 89 (1982)"
+    },
+    temperley: {
+      major: [0.748r, 0.060r, 0.488r, 0.082r, 0.670r, 0.460r, 0.096r, 0.715r, 0.104r, 0.366r, 0.057r, 0.400r],
+      minor: [0.712r, 0.084r, 0.474r, 0.618r, 0.049r, 0.460r, 0.105r, 0.747r, 0.404r, 0.067r, 0.133r, 0.330r],
+      source: "Temperley, Music and Probability (2007), p. 85, from the Kostka-Payne corpus"
+    }
+  }.freeze
+
+  def self.get(name)
+    return name if name.is_a?(self)
+
+    attributes = PROFILES[name&.to_sym]
+    raise ArgumentError, "unknown key profile #{name.inspect}; use one of #{names.join(", ")}" unless attributes
+
+    new(name: name.to_sym, **attributes)
+  end
+
+  def self.names
+    PROFILES.keys
+  end
+
+  def initialize(name:, major:, minor:, source:)
+    super(name: name, major: major.map(&:to_r).freeze, minor: minor.map(&:to_r).freeze, source: source)
+  end
+
+  # The Pearson correlation of the histogram with each key: the twelve major
+  # keys with tonics C upward, then the twelve minor keys. A histogram or
+  # profile with no variance correlates 0 with everything.
+  def correlations(histogram)
+    weights = histogram.map(&:to_r)
+    deviations = deviations_of(weights)
+    variance = sum_of_squares(deviations)
+    [terms_of(major), terms_of(minor)].flat_map do |profile_deviations, profile_variance|
+      (0..11).map do |tonic|
+        next 0.0 if variance.zero? || profile_variance.zero?
+
+        covariance = (0..11).sum { |pitch_class| deviations[pitch_class] * profile_deviations[(pitch_class - tonic) % 12] }
+        covariance.to_f / Math.sqrt((variance * profile_variance).to_f)
+      end
+    end
+  end
+
+  private
+
+  def terms_of(values)
+    deviations = deviations_of(values)
+    [deviations, sum_of_squares(deviations)]
+  end
+
+  def deviations_of(values)
+    mean = values.sum(0r) / values.length
+    values.map { |value| value - mean }
+  end
+
+  def sum_of_squares(values)
+    values.sum(0r) { |value| value * value }
+  end
+end

data/lib/head_music/analysis/key_region.rb

@@ -0,0 +1,5 @@
+# A module for musical analysis
+module HeadMusic::Analysis; end
+
+# A key in force from the downbeat of a bar, at that onset in whole notes.
+HeadMusic::Analysis::KeyRegion = Data.define(:bar_number, :onset, :key)

data/lib/head_music/analysis/line_of_fifths.rb

@@ -0,0 +1,52 @@
+# A module for musical analysis
+module HeadMusic::Analysis; end
+
+# Spellings placed on the line of fifths, after Temperley, The Cognition of
+# Basic Musical Structures (2001), and Meredith, "The ps13 pitch spelling
+# algorithm," Journal of New Music Research 35 (2006). C is 0, each fifth up
+# adds one, and each sharp adds seven: F♭ -8, F -1, C 0, G 1, F♯ 6, B♯ 12.
+module HeadMusic::Analysis::LineOfFifths
+  LETTER_INDICES = {"F" => -1, "C" => 0, "G" => 1, "D" => 2, "A" => 3, "E" => 4, "B" => 5}.freeze
+  LETTERS = LETTER_INDICES.keys.freeze
+  RANGE = (-15..19)
+
+  # Built once, because Alteration.by searches every alteration on each call.
+  SPELLINGS = RANGE.to_h do |index|
+    letter = LETTERS[(index + 1) % 7]
+    semitones = (index + 1).div(7)
+    alteration = HeadMusic::Rudiment::Alteration.by(:semitones, semitones) unless semitones.zero?
+    [index, HeadMusic::Rudiment::Spelling.fetch_or_create(HeadMusic::Rudiment::LetterName.get(letter), alteration)]
+  end.freeze
+
+  module_function
+
+  def index_of(spelling)
+    spelling = HeadMusic::Rudiment::Spelling.get(spelling)
+    LETTER_INDICES.fetch(spelling.letter_name.to_s) + 7 * (spelling.alteration&.semitones || 0)
+  end
+
+  def spelling_at(index)
+    SPELLINGS[index]
+  end
+
+  def pitch_class_of(index)
+    (7 * index) % 12
+  end
+
+  # The pitch of a key number spelled at an index, or nil where the catalog has
+  # none: past a double accidental, or outside registers -1 through 9.
+  def pitch_at(number, index)
+    spelling = SPELLINGS[index]
+    return unless spelling
+
+    offset = number - spelling.semitones_above_c
+    return unless (offset % 12).zero?
+
+    pitch = HeadMusic::Rudiment::Pitch.fetch_or_create(spelling, offset / 12 - 1)
+    pitch if pitch&.midi_note_number == number && pitch.spelling == spelling
+  end
+
+  def pitch_for(number, index)
+    pitch_at(number, index) || HeadMusic::Rudiment::Pitch.from_number(number)
+  end
+end