# music21.roman¶

Music21 class for dealing with Roman Numeral analysis

music21.roman.expandShortHand(shorthand)

Expands shorthand notation into a list with all figures expanded

```>>> 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']
>>> roman.expandShortHand("6/4")
['6', '4']
```

Return list.

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:

```>>> 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 tuplet 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:

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

Return tuplet.

music21.roman.figureTuplets(chordObj, keyObj)

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:

```>>> 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

```>>> 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.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).

```>>> 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:

```>>> rn.pitches
[<music21.pitch.Pitch E-3>, <music21.pitch.Pitch C4>, <music21.pitch.Pitch G-6>]
```
```>>> rn2 = roman.romanNumeralFromChord(chord.Chord(['E3','C4','G4','B-4','E5','G5']), key.Key('F'))
>>> rn2
<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:

```>>> rn3 = roman.romanNumeralFromChord(chord.Chord(['A4','C5','E-5']), key.Key('c'))
>>> rn3
<music21.roman.RomanNumeral vio in c minor>
>>> rn4 = roman.romanNumeralFromChord(chord.Chord(['A-4','C5','E-5']), key.Key('c'))
>>> rn4
<music21.roman.RomanNumeral bVI in c minor>
>>> rn5 = roman.romanNumeralFromChord(chord.Chord(['B4','D5','F5']), key.Key('c'))
>>> rn5
<music21.roman.RomanNumeral viio in c minor>
>>> rn6 = roman.romanNumeralFromChord(chord.Chord(['B-4','D5','F5']), key.Key('c'))
>>> rn6
<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):

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

For reference, odder notes:

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

# >>> rn9 = roman.romanNumeralFromChord(chord.Chord([‘C4’,’E5’,’G5’, ‘C#6’, ‘C7’, ‘C#8’]), key.Key(‘C’)) # >>> rn9 # <music21.roman.RomanNumeral I#853 in C major> # # >>> rn10 = roman.romanNumeralFromChord(chord.Chord([‘F#3’, ‘A3’, ‘E4’, ‘C5’]), key.Key(‘d’)) # >>> rn10 # <music21.roman.RomanNumeral #iiio/7 in d minor>

## RomanNumeral¶

Inherits from: Harmony, Chord, NotRest, GeneralNote, Music21Object

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).

```>>> V = roman.RomanNumeral('V') # could also use 5
>>> V.quality
'major'
>>> V.inversion()
0
>>> V.forteClass
'3-11B'
>>> V.scaleDegree
5
>>> V.pitches  # default key-- C Major
[<music21.pitch.Pitch G4>, <music21.pitch.Pitch B4>, <music21.pitch.Pitch D5>]
```

# TODO: document better! what is inherited from Chord and what is new here...

```>>> neapolitan = roman.RomanNumeral('N6', 'c#') # could also use "bII6"
>>> neapolitan.key
<music21.key.Key of c# minor>
⁠
True
>>> neapolitan.scaleDegreeWithAlteration
(2, <accidental flat>)
>>> neapolitan.pitches  # default octaves
[<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']
```
```>>> majorFlatSeven = roman.RomanNumeral('VII', em)
>>> [str(p) for p in majorFlatSeven.pitches]
['D5', 'F#5', 'A5']
```

TODO: this should give a minor chord soon.

```>>> diminishedSharpSeven = roman.RomanNumeral('vii', em)
>>> [str(p) for p in diminishedSharpSeven.pitches]
['D#5', 'F#5', 'A5']
```

Note that this should be giving D#, F#, A# but it’s incorrect. TODO: Fix

```>>> minorSharpSeven = roman.RomanNumeral('vii#5', em)
>>> [str(p) for p in minorSharpSeven.pitches]
['D#5', 'F#5', 'A5']
⁠
>>> 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'))
>>> lessObviousDiminished.pitches
[<music21.pitch.Pitch A4>, <music21.pitch.Pitch C5>, <music21.pitch.Pitch E-5>]
⁠
>>> diminished7th = roman.RomanNumeral('vio7', scale.MajorScale('c'))
>>> diminished7th.pitches
[<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'))
>>> diminished7th1stInv.pitches
[<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'))
>>> halfDim7th2ndInv.pitches
[<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")
>>> rn = roman.RomanNumeral('I9', ots, caseMatters=False)
>>> [str(p) for p in rn.pitches]
['C2', 'E-2', 'G-2', 'A2', 'C3']
>>> rn2 = roman.RomanNumeral('V7#5b3', ots, caseMatters = False)
>>> [str(p) for p in rn2.pitches]
['G-2', 'A-2', 'C#3', 'E-3']
⁠
>>> r = roman.RomanNumeral('v64/V', key.Key('e'))
>>> r
<music21.roman.RomanNumeral v64/V in e minor>
```
```>>> r.figure
'v64/V'
>>> [str(p) for p in r.pitches]
['C#5', 'F#5', 'A5']
>>> r.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']
```

RomanNumeral attributes

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

pivotChord

default None: if not None, stores another interpretation of the same RN in a different key; stores a RomanNumeral object

impliedScale

A Major Scale

```>>> sc = scale.MajorScale(pitch.Pitch('d'))
>>> sc.pitchFromDegree(7).name
'C#'
```
scaleCardinality

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

Attributes without Documentation: secondaryRomanNumeral, primaryFigure, useImpliedScale, followsKeyChange, secondaryRomanNumeralKey

Attributes inherited from Harmony: chordStepModifications

Attributes inherited from Chord: isChord, isNote, isRest, beams

Attributes inherited from GeneralNote: lyrics, expressions, articulations, editorial

Attributes inherited from Music21Object: classSortOrder, isSpanner, isStream, isVariant, xPosition, id, sites, groups, hideObjectOnPrint

RomanNumeral properties

figure

gets or sets the entire figure (the whole enchilada)

figureAndKey

returns the figure and the key and mode as a string

```>>> rn = roman.RomanNumeral('V65/V', 'e')
>>> rn.figureAndKey
'V65/V in e minor'
```
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.

```>>> rn1 = roman.RomanNumeral('V7')
>>> rn1.functionalityScore
80
⁠
>>> rn2 = roman.RomanNumeral('vi6')
>>> rn2.functionalityScore
10
```
```>>> rn2.functionalityScore = 99
>>> rn2.functionalityScore
99
```
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

```>>> 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

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

```>>> rn = roman.RomanNumeral("#II7")
>>> rn.romanNumeral
'#II'
```
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

Properties inherited from Harmony: writeAsChord

Properties inherited from GeneralNote: lyric, quarterLength

Properties inherited from Music21Object: activeSite, beat, beatDuration, beatStr, beatStrength, classes, derivationHierarchy, fullyQualifiedClasses, isGrace, measureNumber, offset, priority, seconds

RomanNumeral methods

bassScaleDegreeFromNotation(notationObject)

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

```>>> 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
```

Methods inherited from Harmony: addChordStepModification(), findFigure(), getChordStepModifications()

Methods inherited from GeneralNote: addLyric(), augmentOrDiminish(), getGrace(), hasLyrics(), insertLyric()