.. _moduleRoman:

music21.roman
=============

.. WARNING: DO NOT EDIT THIS FILE: AUTOMATICALLY GENERATED.  Edit the .py file directly

.. module:: music21.roman

Music21 class for dealing with Roman Numeral analysis 


.. function:: fromChordAndKey(inChord, inKey)

    return a RomanNumeral object from the given chord in the given key. 

    >>> from music21 import *
    >>> dim7chord = chord.Chord(["E2", "C#3", "B-3", "G4"])
    >>> viio65 = roman.fromChordAndKey(dim7chord, key.Key('D'))
    >>> viio65
    'VII' 
    >>> roman.fromChordAndKey(["E-3","G4","B-5"], key.Key('D'))
    'bII' 
    >>> roman.fromChordAndKey(["G#3","B#4","D#5"], key.Key('D'))
    '#IV' 

    
    #>>> viio65.pitches   # retains octave 
    #['E2', 'C#3', 'B-3', 'G4'] 
    #>>> viio65.figure 
    #'viio65' 

.. function:: expandShortHand(shorthand)

    expands shorthand notation into comma notation 

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

RomanNumeral
------------

Inherits from: :class:`~music21.chord.Chord`, :class:`~music21.note.NotRest`, :class:`~music21.note.GeneralNote`, :class:`~music21.base.Music21Object`, :class:`~music21.base.JSONSerializer`

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

    

    

    >>> from music21 import *
    >>> 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
    [G4, B4, D5] 

    
    >>> neapolitan = roman.RomanNumeral('N6', 'c#') # could also use "bII6"
    >>> neapolitan.isMajorTriad()
    True 
    >>> neapolitan.scaleDegreeWithAlteration
    (2, <accidental flat>) 
    >>> neapolitan.pitches  # default octaves
    [F#4, A4, D5] 

    
    >>> neapolitan2 = roman.RomanNumeral('bII6', 'g#')
    >>> neapolitan2.pitches
    [C#5, E5, A5] 
    >>> neapolitan2.scaleDegree
    2 
    >>> em = key.Key('e')
    >>> dominantV = roman.RomanNumeral('V7', em)
    >>> dominantV.pitches
    [B4, D#5, F#5, A5] 
    >>> minorV = roman.RomanNumeral('V43', em, caseMatters = False)
    >>> minorV.pitches
    [F#4, A4, B4, D5] 

    
    >>> majorFlatSeven = roman.RomanNumeral('VII', em)
    >>> majorFlatSeven.pitches
    [D5, F#5, A5] 
    >>> diminishedSharpSeven = roman.RomanNumeral('vii', em)
    >>> diminishedSharpSeven.pitches
    [D#5, F#5, A5] 
    >>> majorFlatSix = roman.RomanNumeral('VI', em)
    >>> majorFlatSix.pitches
    [C5, E5, G5] 
    >>> minorSharpSix = roman.RomanNumeral('vi', em)
    >>> 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)
    >>> minoriii.pitches
    [G4, B-4, D5] 
    >>> minoriiiB = roman.RomanNumeral('IIIb', em, caseMatters = False)
    >>> 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>) 
    >>> sharp3.pitches
    [A#4, C#5, F#5] 

    
    >>> leadingToneSeventh = roman.RomanNumeral('viio', scale.MajorScale('F'))
    >>> leadingToneSeventh.pitches
    [E5, G5, B-5] 
    A little modal mixture: 
    >>> lessObviousDiminished = roman.RomanNumeral('vio', scale.MajorScale('c'))
    >>> lessObviousDiminished.pitches
    [A4, C5, E-5] 
    >>> diminished7th = roman.RomanNumeral('vio7', scale.MajorScale('c'))
    >>> diminished7th.pitches
    [A4, C5, E-5, G-5] 
    >>> diminished7th1stInv = roman.RomanNumeral('vio65', scale.MajorScale('c'))
    >>> diminished7th1stInv.pitches
    [C4, E-4, G-4, A4] 
    >>> halfDim7th2ndInv = roman.RomanNumeral('iv/o43', scale.MajorScale('F'))
    >>> halfDim7th2ndInv.pitches
    [F-4, A-4, B-4, D-5] 
    >>> alteredChordHalfDim3rdInv = roman.RomanNumeral('bii/o42', scale.MajorScale('F'))
    >>> 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
    [C5, 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'))
    >>> 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)
    >>> rn.pitches
    [C2, E-2, G-2, A2, C3] 
    >>> rn2 = roman.RomanNumeral('V7#5b3', ots, caseMatters = False)
    >>> rn2.pitches
    [G-2, A-2, C#3, E-3] 
    >>> r = roman.RomanNumeral('v64/V', key.Key('e'))
    >>> r.figure
    'v64/V' 
    >>> r.pitches
    [C#5, F#5, A5] 
    >>> r2 = roman.RomanNumeral('V42/V7/vi', key.Key('C'))
    >>> r2.pitches
    [A4, B4, D#5, F#5] 

    

    **RomanNumeral** **attributes**

        Attributes without Documentation: `scale`, `impliedScale`, `caseMatters`, `scaleCardinality`, `figure`

        Attributes inherited from :class:`~music21.chord.Chord`: :attr:`~music21.chord.Chord.isChord`, :attr:`~music21.chord.Chord.isNote`, :attr:`~music21.chord.Chord.isRest`, :attr:`~music21.chord.Chord.beams`

        Attributes inherited from :class:`~music21.note.NotRest`: :attr:`~music21.note.NotRest.stemDirection`

        Attributes inherited from :class:`~music21.note.GeneralNote`: :attr:`~music21.note.GeneralNote.articulations`, :attr:`~music21.note.GeneralNote.expressions`, :attr:`~music21.note.GeneralNote.editorial`, :attr:`~music21.note.GeneralNote.lyrics`

        Attributes inherited from :class:`~music21.base.Music21Object`: :attr:`~music21.base.Music21Object.classSortOrder`, :attr:`~music21.base.Music21Object.hideObjectOnPrint`, :attr:`~music21.base.Music21Object.id`, :attr:`~music21.base.Music21Object.groups`

    **RomanNumeral** **properties**

        Properties inherited from :class:`~music21.chord.Chord`: :attr:`~music21.chord.Chord.pitches`, :attr:`~music21.chord.Chord.chordTablesAddress`, :attr:`~music21.chord.Chord.commonName`, :attr:`~music21.chord.Chord.duration`, :attr:`~music21.chord.Chord.fifth`, :attr:`~music21.chord.Chord.forteClass`, :attr:`~music21.chord.Chord.forteClassNumber`, :attr:`~music21.chord.Chord.forteClassTn`, :attr:`~music21.chord.Chord.forteClassTnI`, :attr:`~music21.chord.Chord.hasZRelation`, :attr:`~music21.chord.Chord.intervalVector`, :attr:`~music21.chord.Chord.intervalVectorString`, :attr:`~music21.chord.Chord.isPrimeFormInversion`, :attr:`~music21.chord.Chord.midiEvents`, :attr:`~music21.chord.Chord.midiFile`, :attr:`~music21.chord.Chord.multisetCardinality`, :attr:`~music21.chord.Chord.mx`, :attr:`~music21.chord.Chord.normalForm`, :attr:`~music21.chord.Chord.normalFormString`, :attr:`~music21.chord.Chord.orderedPitchClasses`, :attr:`~music21.chord.Chord.orderedPitchClassesString`, :attr:`~music21.chord.Chord.pitchClassCardinality`, :attr:`~music21.chord.Chord.pitchClasses`, :attr:`~music21.chord.Chord.pitchNames`, :attr:`~music21.chord.Chord.pitchedCommonName`, :attr:`~music21.chord.Chord.primeForm`, :attr:`~music21.chord.Chord.primeFormString`, :attr:`~music21.chord.Chord.quality`, :attr:`~music21.chord.Chord.scaleDegrees`, :attr:`~music21.chord.Chord.seventh`, :attr:`~music21.chord.Chord.third`, :attr:`~music21.chord.Chord.tie`

        Properties inherited from :class:`~music21.note.GeneralNote`: :attr:`~music21.note.GeneralNote.color`, :attr:`~music21.note.GeneralNote.lily`, :attr:`~music21.note.GeneralNote.lyric`, :attr:`~music21.note.GeneralNote.musicxml`, :attr:`~music21.note.GeneralNote.quarterLength`

        Properties inherited from :class:`~music21.base.Music21Object`: :attr:`~music21.base.Music21Object.activeSite`, :attr:`~music21.base.Music21Object.beat`, :attr:`~music21.base.Music21Object.beatDuration`, :attr:`~music21.base.Music21Object.beatStr`, :attr:`~music21.base.Music21Object.beatStrength`, :attr:`~music21.base.Music21Object.classes`, :attr:`~music21.base.Music21Object.derivationHierarchy`, :attr:`~music21.base.Music21Object.measureNumber`, :attr:`~music21.base.Music21Object.offset`, :attr:`~music21.base.Music21Object.priority`

        Properties inherited from :class:`~music21.base.JSONSerializer`: :attr:`~music21.base.JSONSerializer.json`

    **RomanNumeral** **methods**

        .. method:: bassScaleDegreeFromNotation(notationObject)

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

            >>> from music21 import *
            >>> 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 

        .. method:: setKeyOrScale(keyOrScale)

            Provide a new key or scale, and re-configure the RN with the existing figure. 

            >>> from music21 import *
            >>> r1 = RomanNumeral('V')
            >>> r1.pitches
            [G4, B4, D5] 
            >>> r1.setKeyOrScale(key.Key('A'))
            >>> r1.pitches
            [E5, G#5, B5] 
            >>> r1
            <music21.roman.RomanNumeral V in A major> 

        Methods inherited from :class:`~music21.chord.Chord`: :meth:`~music21.chord.Chord.annotateIntervals`, :meth:`~music21.chord.Chord.areZRelations`, :meth:`~music21.chord.Chord.bass`, :meth:`~music21.chord.Chord.canBeDominantV`, :meth:`~music21.chord.Chord.canBeTonic`, :meth:`~music21.chord.Chord.closedPosition`, :meth:`~music21.chord.Chord.containsSeventh`, :meth:`~music21.chord.Chord.containsTriad`, :meth:`~music21.chord.Chord.findRoot`, :meth:`~music21.chord.Chord.getChordStep`, :meth:`~music21.chord.Chord.getTie`, :meth:`~music21.chord.Chord.getZRelation`, :meth:`~music21.chord.Chord.hasAnyRepeatedDiatonicNote`, :meth:`~music21.chord.Chord.hasRepeatedChordStep`, :meth:`~music21.chord.Chord.intervalFromChordStep`, :meth:`~music21.chord.Chord.inversion`, :meth:`~music21.chord.Chord.inversionName`, :meth:`~music21.chord.Chord.isAugmentedTriad`, :meth:`~music21.chord.Chord.isConsonant`, :meth:`~music21.chord.Chord.isDiminishedSeventh`, :meth:`~music21.chord.Chord.isDiminishedTriad`, :meth:`~music21.chord.Chord.isDominantSeventh`, :meth:`~music21.chord.Chord.isFalseDiminishedSeventh`, :meth:`~music21.chord.Chord.isHalfDiminishedSeventh`, :meth:`~music21.chord.Chord.isIncompleteMajorTriad`, :meth:`~music21.chord.Chord.isIncompleteMinorTriad`, :meth:`~music21.chord.Chord.isMajorTriad`, :meth:`~music21.chord.Chord.isMinorTriad`, :meth:`~music21.chord.Chord.isSeventh`, :meth:`~music21.chord.Chord.isTriad`, :meth:`~music21.chord.Chord.removeRedundantPitchClasses`, :meth:`~music21.chord.Chord.removeRedundantPitchNames`, :meth:`~music21.chord.Chord.removeRedundantPitches`, :meth:`~music21.chord.Chord.root`, :meth:`~music21.chord.Chord.seekChordTablesAddress`, :meth:`~music21.chord.Chord.semiClosedPosition`, :meth:`~music21.chord.Chord.semitonesFromChordStep`, :meth:`~music21.chord.Chord.setTie`, :meth:`~music21.chord.Chord.sortAscending`, :meth:`~music21.chord.Chord.sortChromaticAscending`, :meth:`~music21.chord.Chord.sortDiatonicAscending`, :meth:`~music21.chord.Chord.sortFrequencyAscending`, :meth:`~music21.chord.Chord.transpose`

        Methods inherited from :class:`~music21.note.GeneralNote`: :meth:`~music21.note.GeneralNote.addLyric`, :meth:`~music21.note.GeneralNote.augmentOrDiminish`, :meth:`~music21.note.GeneralNote.compactNoteInfo`, :meth:`~music21.note.GeneralNote.hasLyrics`

        Methods inherited from :class:`~music21.base.Music21Object`: :meth:`~music21.base.Music21Object.addContext`, :meth:`~music21.base.Music21Object.addLocation`, :meth:`~music21.base.Music21Object.addLocationAndActiveSite`, :meth:`~music21.base.Music21Object.freezeIds`, :meth:`~music21.base.Music21Object.getAllContextsByClass`, :meth:`~music21.base.Music21Object.getCommonSiteIds`, :meth:`~music21.base.Music21Object.getCommonSites`, :meth:`~music21.base.Music21Object.getContextAttr`, :meth:`~music21.base.Music21Object.getContextByClass`, :meth:`~music21.base.Music21Object.getOffsetBySite`, :meth:`~music21.base.Music21Object.getSiteIds`, :meth:`~music21.base.Music21Object.getSites`, :meth:`~music21.base.Music21Object.getSpannerSites`, :meth:`~music21.base.Music21Object.hasContext`, :meth:`~music21.base.Music21Object.mergeAttributes`, :meth:`~music21.base.Music21Object.purgeLocations`, :meth:`~music21.base.Music21Object.removeLocationBySite`, :meth:`~music21.base.Music21Object.removeLocationBySiteId`, :meth:`~music21.base.Music21Object.searchParentByAttr`, :meth:`~music21.base.Music21Object.setContextAttr`, :meth:`~music21.base.Music21Object.setOffsetBySite`, :meth:`~music21.base.Music21Object.show`, :meth:`~music21.base.Music21Object.splitAtDurations`, :meth:`~music21.base.Music21Object.splitAtQuarterLength`, :meth:`~music21.base.Music21Object.splitByQuarterLengths`, :meth:`~music21.base.Music21Object.unfreezeIds`, :meth:`~music21.base.Music21Object.unwrapWeakref`, :meth:`~music21.base.Music21Object.wrapWeakref`, :meth:`~music21.base.Music21Object.write`

        Methods inherited from :class:`~music21.base.JSONSerializer`: :meth:`~music21.base.JSONSerializer.jsonAttributes`, :meth:`~music21.base.JSONSerializer.jsonComponentFactory`, :meth:`~music21.base.JSONSerializer.jsonPrint`, :meth:`~music21.base.JSONSerializer.jsonRead`, :meth:`~music21.base.JSONSerializer.jsonWrite`


