Previous topic

music21.repeat

Next topic

music21.romanText

Table Of Contents

Table Of Contents

This Page

music21.roman

Music21 class for dealing with Roman Numeral analysis

Functions

music21.roman.expandShortHand(shorthand)

Expands shorthand notation into a list with all figures expanded:

::
>>> from music21 import roman
>>> roman.expandShortHand("64")
['6', '4']
>>> roman.expandShortHand("973")
['9', '7', '3']
>>> roman.expandShortHand("11b3")
['11', 'b3']
>>> roman.expandShortHand("b13#9-6")
['b13', '#9', '-6']
>>> roman.expandShortHand("-")
['5', '-3']

Slashes don’t matter

>>> roman.expandShortHand("6/4")
['6', '4']

Note that this is not where abbreviations get expanded

>>> roman.expandShortHand("7") # not 7,5,3
['7']

>>> roman.expandShortHand("4/3") # not 6,4,3
['4', '3']

Returns a list of expanded abbreviations.

music21.roman.figureFromChordAndKey(chordObj, keyObj=None)

Returns the post RN figure for a given chord in a given key.

If keyObj is none, it uses the root as a major key:

>>> from music21 import roman
>>> roman.figureFromChordAndKey(
...     chord.Chord(['F#2','D3','A-3','C#4']),
...     key.Key('C'),
...     )
'6#5b3'

The method substitutes shorthand (e.g., ‘6’ not ‘63’)

>>> roman.figureFromChordAndKey(
...     chord.Chord(['E3','C4','G4']),
...     key.Key('C'),
...     )
'6'
>>> roman.figureFromChordAndKey(
...     chord.Chord(['E3','C4','G4','B-5']),
...     key.Key('F'),
...     )
'65'
>>> roman.figureFromChordAndKey(
...     chord.Chord(['E3','C4','G4','B-5']),
...     key.Key('C'),
...     )
'6b5'

We reduce common omissions from seventh chords to be ‘7’ instead of ‘75’, ‘73’, etc.

>>> roman.figureFromChordAndKey(
...     chord.Chord(['A3','E-4','G-4']),
...     key.Key('b-'),
...     )
'7'

Return string.

music21.roman.figureTupletSolo(pitchObj, keyObj, bass)

Return a single tuple for a pitch and key showing the interval above the bass, its alteration from a step in the given key, an alteration string, and the pitch object.

For instance, in C major, an A-3 above an F# bass would be:

>>> from music21 import roman
>>> roman.figureTupletSolo(
...     pitch.Pitch('A-3'),
...     key.Key('C'),
...     pitch.Pitch('F#2'),
...     )
(3, -1.0, 'b', <music21.pitch.Pitch A-3>)

Return tuple.

music21.roman.figureTuplets(chordObject, keyObject)

Return a set of tuplets for each pitch showing the presence of a note, its interval above the bass its alteration (float) from a step in the given key, an alterationString, and the pitch object.

Note though that for roman numerals, the applicable key is almost always the root.

For instance, in C major, F# D A- C# would be:

>>> from music21 import roman
>>> roman.figureTuplets(
...     chord.Chord(['F#2','D3','A-3','C#4']),
...     key.Key('C'),
...     )
[(1, 1.0, '#', <music21.pitch.Pitch F#2>),
(6, 0.0, '', <music21.pitch.Pitch D3>),
(3, -1.0, 'b', <music21.pitch.Pitch A-3>),
(5, 1.0, '#', <music21.pitch.Pitch C#4>)]
>>> roman.figureTuplets(
...     chord.Chord(['E3','C4','G4','B-5']),
...     key.Key('C'),
...     )
[(1, 0.0, '', <music21.pitch.Pitch E3>),
(6, 0.0, '', <music21.pitch.Pitch C4>),
(3, 0.0, '', <music21.pitch.Pitch G4>),
(5, -1.0, 'b', <music21.pitch.Pitch B-5>)]
music21.roman.identifyAsTonicOrDominant(inChord, inKey)

Returns the roman numeral string expression (either tonic or dominant) that best matches the inChord. Useful when you know inChord is either tonic or dominant, but only two pitches are provided in the chord. If neither tonic nor dominant is possibly correct, False is returned

>>> from music21 import roman
>>> roman.identifyAsTonicOrDominant(['B2','F5'], key.Key('C'))
'V65'
>>> roman.identifyAsTonicOrDominant(['B3','G4'], key.Key('g'))
'i6'
>>> roman.identifyAsTonicOrDominant(['C3', 'B4'], key.Key('f'))
'V7'
>>> roman.identifyAsTonicOrDominant(['D3'], key.Key('f'))
False
music21.roman.romanInversionName(inChord)

Extremely similar to Chord’s inversionName() method, but returns string values and allows incomplete triads

music21.roman.romanNumeralFromChord(chordObj, keyObj=None, preferSecondaryDominants=False)
Takes a chord object and returns an appropriate chord name. If keyObj is

omitted, the root of the chord is considered the key (if the chord has a major third, it’s major; otherwise it’s minor):

>>> from music21 import roman
>>> rn = roman.romanNumeralFromChord(
...     chord.Chord(['E-3','C4','G-6']),
...     key.Key('g#'),
...     )
>>> rn
<music21.roman.RomanNumeral bivo6 in g# minor>

The pitches remain the same with the same octaves:

>>> for pitch in rn.pitches:
...     pitch
...
<music21.pitch.Pitch E-3>
<music21.pitch.Pitch C4>
<music21.pitch.Pitch G-6>
>>> romanNumeral2 = roman.romanNumeralFromChord(
...     chord.Chord(['E3','C4','G4','B-4','E5','G5']),
...     key.Key('F'),
...     )
>>> romanNumeral2
<music21.roman.RomanNumeral V65 in F major>

Note that vi and vii in minor signifies what you might think of alternatively as #vi and #vii:

>>> romanNumeral3 = roman.romanNumeralFromChord(
...     chord.Chord(['A4','C5','E-5']),
...     key.Key('c'),
...     )
>>> romanNumeral3
<music21.roman.RomanNumeral vio in c minor>
>>> romanNumeral4 = roman.romanNumeralFromChord(
...     chord.Chord(['A-4','C5','E-5']),
...     key.Key('c'),
...     )
>>> romanNumeral4
<music21.roman.RomanNumeral bVI in c minor>
>>> romanNumeral5 = roman.romanNumeralFromChord(
...     chord.Chord(['B4','D5','F5']),
...     key.Key('c'),
...     )
>>> romanNumeral5
<music21.roman.RomanNumeral viio in c minor>
>>> romanNumeral6 = roman.romanNumeralFromChord(
...     chord.Chord(['B-4','D5','F5']),
...     key.Key('c'),
...     )
>>> romanNumeral6
<music21.roman.RomanNumeral bVII in c minor>

Diminished and half-diminished seventh chords can omit the third and still be diminished: (n.b. we also demonstrate that chords can be created from a string):

>>> romanNumeralDim7 = roman.romanNumeralFromChord(
...     chord.Chord("A3 E-4 G-4"),
...     key.Key('b-'),
...     )
>>> romanNumeralDim7
<music21.roman.RomanNumeral viio7 in b- minor>

For reference, odder notes:

>>> romanNumeral7 = roman.romanNumeralFromChord(
...     chord.Chord(['A--4','C-5','E--5']),
...     key.Key('c'),
...     )
>>> romanNumeral7
<music21.roman.RomanNumeral bbVI in c minor>
>>> romanNumeral8 = roman.romanNumeralFromChord(
...     chord.Chord(['A#4','C#5','E#5']),
...     key.Key('c'),
...     )
>>> romanNumeral8
<music21.roman.RomanNumeral #vi in c minor>

RomanNumeral

class music21.roman.RomanNumeral(figure=None, keyOrScale=None, caseMatters=True)

A RomanNumeral object is a specialized type of Harmony object that stores the function and scale degree of a chord within a Key.

If no Key is given then it exists as a theoretical, keyless RomanNumeral; e.g., V in any key. but when realized, keyless RomanNumerals are treated as if they are in C major).

>>> from music21 import roman
>>> V = roman.RomanNumeral('V') # could also use 5
>>> V.quality
'major'
>>> V.inversion()
0
>>> V.forteClass
'3-11B'
>>> V.scaleDegree
5
>>> for pitch in V.pitches:  # default key-- C Major
...     pitch
...
<music21.pitch.Pitch G4>
<music21.pitch.Pitch B4>
<music21.pitch.Pitch D5>
>>> neapolitan = roman.RomanNumeral('N6', 'c#') # could also use "bII6"
>>> neapolitan.key
<music21.key.Key of c# minor>
>>> neapolitan.isMajorTriad()
True
>>> neapolitan.scaleDegreeWithAlteration
(2, <accidental flat>)
>>> for pitch in neapolitan.pitches:  # default octaves
...     pitch
...
<music21.pitch.Pitch F#4>
<music21.pitch.Pitch A4>
<music21.pitch.Pitch D5>
>>> neapolitan2 = roman.RomanNumeral('bII6', 'g#')
>>> [str(p) for p in neapolitan2.pitches]
['C#5', 'E5', 'A5']
>>> neapolitan2.scaleDegree
2
>>> em = key.Key('e')
>>> dominantV = roman.RomanNumeral('V7', em)
>>> [str(p) for p in dominantV.pitches]
['B4', 'D#5', 'F#5', 'A5']
>>> minorV = roman.RomanNumeral('V43', em, caseMatters = False)
>>> [str(p) for p in minorV.pitches]
['F#4', 'A4', 'B4', 'D5']

In minor – VII and VI are assumed to refer to the flattened scale degree. vii, viio, viio7, vii/o7 and vi, vio, vio7, vi/o7 refer to the sharpened scale degree. To get a minor triad on lowered 6 for instance, you will need to use ‘bvi’ while to get a major triad on raised 6, use ‘#VI’.

The actual rule is that if the chord implies minor, diminished, or half-diminished, an implied “#” is read before the figure. Anything else does not add the sharp. The lowered (natural minor) is the assumed basic chord.

>>> majorFlatSeven = roman.RomanNumeral('VII', em)
>>> [str(p) for p in majorFlatSeven.pitches]
['D5', 'F#5', 'A5']
>>> minorSharpSeven = roman.RomanNumeral('vii', em)
>>> [str(p) for p in minorSharpSeven.pitches]
['D#5', 'F#5', 'A#5']
>>> majorFlatSix = roman.RomanNumeral('VI', em)
>>> [str(p) for p in majorFlatSix.pitches]
['C5', 'E5', 'G5']
>>> minorSharpSix = roman.RomanNumeral('vi', em)
>>> [str(p) for p in minorSharpSix.pitches]
['C#5', 'E5', 'G#5']

Either of these is the same way of getting a minor iii in a minor key:

>>> minoriii = roman.RomanNumeral('iii', em, caseMatters = True)
>>> [str(p) for p in minoriii.pitches]
['G4', 'B-4', 'D5']
>>> minoriiiB = roman.RomanNumeral('IIIb', em, caseMatters = False)
>>> [str(p) for p in minoriiiB.pitches]
['G4', 'B-4', 'D5']

Can also take a scale object, here we build a first-inversion chord on the raised-three degree of D-flat major, that is, F#-major (late Schubert would be proud...)

>>> sharp3 = roman.RomanNumeral('#III6', scale.MajorScale('D-'))
>>> sharp3.scaleDegreeWithAlteration
(3, <accidental sharp>)
>>> [str(p) for p in sharp3.pitches]
['A#4', 'C#5', 'F#5']
>>> sharp3.figure
'#III6'

Figures can be changed:

>>> sharp3.figure = "V"
>>> [str(p) for p in sharp3.pitches]
['A-4', 'C5', 'E-5']
>>> leadingToneSeventh = roman.RomanNumeral(
...     'viio', scale.MajorScale('F'))
>>> [str(p) for p in leadingToneSeventh.pitches]
['E5', 'G5', 'B-5']

A little modal mixture:

>>> lessObviousDiminished = roman.RomanNumeral(
...     'vio', scale.MajorScale('c'))
>>> for pitch in lessObviousDiminished.pitches:
...     pitch
...
<music21.pitch.Pitch A4>
<music21.pitch.Pitch C5>
<music21.pitch.Pitch E-5>
>>> diminished7th = roman.RomanNumeral(
...     'vio7', scale.MajorScale('c'))
>>> for pitch in diminished7th.pitches:
...     pitch
...
<music21.pitch.Pitch A4>
<music21.pitch.Pitch C5>
<music21.pitch.Pitch E-5>
<music21.pitch.Pitch G-5>
>>> diminished7th1stInv = roman.RomanNumeral(
...     'vio65', scale.MajorScale('c'))
>>> for pitch in diminished7th1stInv.pitches:
...     pitch
...
<music21.pitch.Pitch C4>
<music21.pitch.Pitch E-4>
<music21.pitch.Pitch G-4>
<music21.pitch.Pitch A4>
>>> halfDim7th2ndInv = roman.RomanNumeral(
...     'iv/o43', scale.MajorScale('F'))
>>> for pitch in halfDim7th2ndInv.pitches:
...     pitch
...
<music21.pitch.Pitch F-4>
<music21.pitch.Pitch A-4>
<music21.pitch.Pitch B-4>
<music21.pitch.Pitch D-5>
>>> alteredChordHalfDim3rdInv = roman.RomanNumeral(
...     'bii/o42', scale.MajorScale('F'))
>>> [str(p) for p in alteredChordHalfDim3rdInv.pitches]
['F-4', 'G-4', 'B--4', 'D--5']
>>> alteredChordHalfDim3rdInv.intervalVector
[0, 1, 2, 1, 1, 1]
>>> alteredChordHalfDim3rdInv.commonName
'half-diminished seventh chord'
>>> alteredChordHalfDim3rdInv.romanNumeral
'-ii'
>>> alteredChordHalfDim3rdInv.romanNumeralAlone
'ii'
>>> openFifth = roman.RomanNumeral('V[no3]', key.Key('F'))
>>> openFifth.pitches
(<music21.pitch.Pitch C5>, <music21.pitch.Pitch G5>)

Some theoretical traditions express a viio7 as a V9 chord with omitted root. Music21 allows that:

>>> fiveOhNine = roman.RomanNumeral('V9[no1]', key.Key('g'))
>>> [str(p) for p in fiveOhNine.pitches]
['F#5', 'A5', 'C6', 'E-6']

Just for kicks (no worries if this is goobley-gook):

>>> ots = scale.OctatonicScale("C2")
>>> romanNumeral = roman.RomanNumeral('I9', ots, caseMatters=False)
>>> [str(p) for p in romanNumeral.pitches]
['C2', 'E-2', 'G-2', 'A2', 'C3']
>>> romanNumeral2 = roman.RomanNumeral(
...     'V7#5b3', ots, caseMatters = False)
>>> [str(p) for p in romanNumeral2.pitches]
['G-2', 'A-2', 'C#3', 'E-3']
>>> romanNumeral = roman.RomanNumeral('v64/V', key.Key('e'))
>>> romanNumeral
<music21.roman.RomanNumeral v64/V in e minor>
>>> romanNumeral.figure
'v64/V'
>>> [str(p) for p in romanNumeral.pitches]
['C#5', 'F#5', 'A5']
>>> romanNumeral.secondaryRomanNumeral
<music21.roman.RomanNumeral V in e minor>

Dominant 7ths can be specified by putting d7 at end:

>>> r = roman.RomanNumeral('bVIId7', key.Key('B-'))
>>> r.figure
'bVIId7'
>>> [str(p) for p in r.pitches]
['A-5', 'C6', 'E-6', 'G-6']
>>> r = roman.RomanNumeral('VId7')
>>> r.figure
'VId7'
>>> r.key = key.Key('B-')
>>> [str(p) for p in r.pitches]
['G5', 'B5', 'D6', 'F6']
>>> r2 = roman.RomanNumeral('V42/V7/vi', key.Key('C'))
>>> [str(p) for p in r2.pitches]
['A4', 'B4', 'D#5', 'F#5']

# TODO: document better! what is inherited and what is new?

RomanNumeral bases

RomanNumeral read-only properties

RomanNumeral.figureAndKey

Returns the figure and the key and mode as a string

>>> from music21 import roman
>>> rn = roman.RomanNumeral('V65/V', 'e')
>>> rn.figureAndKey
'V65/V in e minor'
RomanNumeral.romanNumeral

Read-only property that returns either the romanNumeralAlone (e.g. just II) or the frontAlterationAccidental.modifier + romanNumeralAlone (e.g. #II)

>>> from music21 import roman
>>> rn = roman.RomanNumeral("#II7")
>>> rn.romanNumeral
'#II'

Read-only properties inherited from Chord:

Read-only properties inherited from Music21Object:

RomanNumeral read/write properties

RomanNumeral.figure

Gets or sets the entire figure (the whole enchilada).

RomanNumeral.functionalityScore

Return or set a number from 1 to 100 representing the relative functionality of this RN.figure (possibly given the mode, etc.).

Numbers are ordinal, not cardinal.

>>> from music21 import roman
>>> rn1 = roman.RomanNumeral('V7')
>>> rn1.functionalityScore
80
>>> rn2 = roman.RomanNumeral('vi6')
>>> rn2.functionalityScore
10
>>> rn2.functionalityScore = 99
>>> rn2.functionalityScore
99
RomanNumeral.key

Gets or Sets the current Key (or Scale object) for a given RomanNumeral object.

If a new key is set, then the pitches will probably change:

>>> from music21 import roman
>>> r1 = roman.RomanNumeral('V')

(implicit C-major)

>>> [str(p) for p in r1.pitches]
['G4', 'B4', 'D5']

Change to A major

>>> r1.key = key.Key('A')
>>> [str(p) for p in r1.pitches]
['E5', 'G#5', 'B5']
>>> r1
<music21.roman.RomanNumeral V in A major>
>>> r1.key
<music21.key.Key of A major>
>>> r1.key = key.Key('e')
>>> [str(p) for p in r1.pitches]
['B4', 'D#5', 'F#5']
>>> r1
<music21.roman.RomanNumeral V in e minor>
RomanNumeral.scaleDegreeWithAlteration

Returns or sets a two element tuple of the scale degree and the accidental that alters the scale degree for things such as #ii or bV.

Note that vi and vii in minor have a frontAlterationAccidental of <sharp> even if it is not preceded by a # sign.

Has the same effect as setting .scaleDegree and .frontAlterationAccidental separately

Read/write properties inherited from Harmony:

Read/write properties inherited from Chord:

Read/write properties inherited from NotRest:

Read/write properties inherited from GeneralNote:

Read/write properties inherited from Music21Object:

RomanNumeral methods

RomanNumeral.bassScaleDegreeFromNotation(notationObject=None)

Given a notationObject from music21.figuredBass.notation.Notation return the scaleDegree of the bass.

>>> from music21 import figuredBass, roman
>>> fbn = figuredBass.notation.Notation('6,3')
>>> V = roman.RomanNumeral('V')
>>> V.bassScaleDegreeFromNotation(fbn)
7
>>> fbn2 = figuredBass.notation.Notation('#6,4')
>>> vi = roman.RomanNumeral('vi')
>>> vi.bassScaleDegreeFromNotation(fbn2)
3

Can figure it out directly from an existing RomanNumeral:

>>> ii65 = roman.RomanNumeral('ii65', 'C')
>>> ii65.bassScaleDegreeFromNotation()
4

Simple test:

::
>>> I = roman.RomanNumeral('I')
>>> I.bassScaleDegreeFromNotation()
1

A bit slow (6 seconds for 1000 operations, but not the bottleneck)

Methods inherited from Harmony:

Methods inherited from Chord:

Methods inherited from GeneralNote:

Methods inherited from Music21Object:

RomanNumeral instance variables

RomanNumeral.caseMatters

Boolean to determine whether the case (upper or lowercase) of the figure determines whether it is major or minor. Defaults to True; not everything has been tested with False yet.

RomanNumeral.pivotChord

Defaults to None; if not None, stores another interpretation of the same RN in a different key; stores a RomanNumeral object.

RomanNumeral.scaleCardinality

Probably you should not need to change this, but stores how many notes are in the scale; defaults to 7 for diatonic, obviously.

Instance variables inherited from Harmony:

  • beams
  • isNote
  • isRest
  • isChord

Instance variables inherited from Chord:

Instance variables inherited from NotRest:

Instance variables inherited from GeneralNote:

Instance variables inherited from Music21Object: