.. _usersGuide_23_romanNumerals:

.. WARNING: DO NOT EDIT THIS FILE:
   AUTOMATICALLY GENERATED.
   PLEASE EDIT THE .py FILE DIRECTLY.

User’s Guide, Chapter 23: Roman Numeral Analysis
================================================

F major is a chord that has the notes F, A, and usually C. Those notes,
placed in the same octave, instrument, dynamics, etc., should have
basically the same acoustical properties each time it’s played, but
human perception of this chord can seem to vary dramatically depending
on the context the chord is placed in. One of the most powerful contexts
that can give the same isolated sound remarkably different meanings
comes from its surrounding key.

Roman numeral analysis is a way to identify certain similarities in
tonal music (whether classical, folk, or popular) that have
traditionally been assigned to different chords that appear on the same
scale degrees in different keys.

.. note::
   For a basic introduction to Roman numeral analysis, see 
   the strong `Wikipedia article <https://en.wikipedia.org/wiki/Roman_numeral_analysis>`_  
   or, for a quick review, the great PDF cheatsheet 
   at `"Learn Music Theory" <https://learnmusictheory.net/PDFs/pdffiles/01-05-02-RomanNumerals.pdf>`_ 

Let’s create an F-major chord but convert it to roman numerals in a few
different contexts by creating different key objects. First the setup:

.. code:: ipython3

    from music21 import *
    f = chord.Chord('F4 C5 A5')
    kf = key.Key('F')
    sf = stream.Measure([kf, f])
    sf.show()



.. image:: usersGuide_23_romanNumerals_4_0.png
   :width: 204px
   :height: 54px


.. code:: ipython3

    kc = key.Key('C')
    sc = stream.Part([kc, f])
    sc.show()



.. image:: usersGuide_23_romanNumerals_5_0.png
   :width: 191px
   :height: 54px


.. code:: ipython3

    kb = key.Key('B') 
    sb = stream.Part([kb, f])
    sb.show()



.. image:: usersGuide_23_romanNumerals_6_0.png
   :width: 299px
   :height: 59px


Now that we have four different keys, let’s create Roman numerals from
the F major chord and each of the keys. We will use a function from the
:ref:`moduleRoman` module called
:func:`~music21.roman.romanNumeralFromChord` (which we saw briefly in
:ref:`Chapter 10 <usersGuide_10_examples1>`). We pass to this function
a ``Chord`` object and a ``Key`` object.

.. code:: ipython3

    rf = roman.romanNumeralFromChord(f, kf)
    rf




.. parsed-literal::
   :class: ipython-result

    <music21.roman.RomanNumeral I in F major>



.. code:: ipython3

    rc = roman.romanNumeralFromChord(f, kc)
    rc




.. parsed-literal::
   :class: ipython-result

    <music21.roman.RomanNumeral IV in C major>



``Music21`` tries its best to find a Roman numeral for almost any
combination of chord and key, even if, like in B major:

.. code:: ipython3

    rb = roman.romanNumeralFromChord(f, kb)
    rb




.. parsed-literal::
   :class: ipython-result

    <music21.roman.RomanNumeral bV in B major>



Each :class:`~music21.roman.RomanNumeral` object has some common
properties, such as ``.figure``, ``.figureAndKey``,
``.romanNumeralAlone``, ``.key``, and ``.scaleDegree``:

.. code:: ipython3

    (rf.figure, rc.figure, rb.figure)




.. parsed-literal::
   :class: ipython-result

    ('I', 'IV', 'bV')



.. code:: ipython3

    rf.figureAndKey




.. parsed-literal::
   :class: ipython-result

    'I in F major'



.. code:: ipython3

    (rf.romanNumeralAlone, rc.romanNumeralAlone, rb.romanNumeralAlone)




.. parsed-literal::
   :class: ipython-result

    ('I', 'IV', 'V')



.. code:: ipython3

    (rf.key, rc.key, rb.key)




.. parsed-literal::
   :class: ipython-result

    (<music21.key.Key of F major>,
     <music21.key.Key of C major>,
     <music21.key.Key of B major>)



.. code:: ipython3

    (rf.scaleDegree, rc.scaleDegree, rb.scaleDegree)




.. parsed-literal::
   :class: ipython-result

    (1, 4, 5)



Note that in the last case, the scale degree is the uninflected degree –
the flat sign isn’t included in the ``.scaleDegree`` tag. For that, use
``.scaleDegreeWithAlteration``

.. code:: ipython3

    rf.scaleDegreeWithAlteration




.. parsed-literal::
   :class: ipython-result

    (1, None)



.. code:: ipython3

    rb.scaleDegreeWithAlteration




.. parsed-literal::
   :class: ipython-result

    (5, <music21.pitch.Accidental flat>)



Or look at the ``.frontAlterationString``,
``frontAlterationAccidental``, and ``frontAlterationTransposeInterval``

.. code:: ipython3

    rb.frontAlterationString




.. parsed-literal::
   :class: ipython-result

    'b'



.. code:: ipython3

    rb.frontAlterationAccidental




.. parsed-literal::
   :class: ipython-result

    <music21.pitch.Accidental flat>



.. code:: ipython3

    rb.frontAlterationTransposeInterval




.. parsed-literal::
   :class: ipython-result

    <music21.interval.Interval d1>



Of course, some RomanNumerals make more sense than others, so there’s a
``.functionalityScore`` which returns a number from 0 to 100 as a rough
approximation of how “functional” this chord is:

.. code:: ipython3

    (rf.functionalityScore, rc.functionalityScore, rb.functionalityScore)




.. parsed-literal::
   :class: ipython-result

    (100, 59, 0)



As I hinted at above, ``RomanNumeral`` objects are ``Music21Objects`` so
they can be put into Streams and showed:

.. code:: ipython3

    s = stream.Measure()
    s.insert(0, rf)
    s.show()



.. image:: usersGuide_23_romanNumerals_28_0.png
   :width: 179px
   :height: 54px


Note that the spacing of the roman numeral is preserved from the chord
that it was converted from. If we create a ``RomanNumeral`` object
directly, then it is created in closed position above a tonic note in
octave 4:

.. code:: ipython3

    rf2 = roman.RomanNumeral('I', kf)
    rf2




.. parsed-literal::
   :class: ipython-result

    <music21.roman.RomanNumeral I in F major>



.. code:: ipython3

    rf2.show()



.. image:: usersGuide_23_romanNumerals_31_0.png
   :width: 179px
   :height: 49px


It is possible to pass in just a roman numeral (“I”, “ii”, “iii”, “IV”,
etc.) and a string (“C” = C major, “c” = c minor) to create a
RomanNumeral object:

.. code:: ipython3

    subDom7 = roman.RomanNumeral("IV7", "B-")
    subDom7.show()



.. image:: usersGuide_23_romanNumerals_33_0.png
   :width: 205px
   :height: 62px


.. code:: ipython3

    e65 = roman.RomanNumeral("ii65", "E")
    e65.show()



.. image:: usersGuide_23_romanNumerals_34_0.png
   :width: 229px
   :height: 49px


For these romanNumerals, there is information after the
``.romanNumeralAlone`` this can be found as a string in
``.figuresWritten``:

.. code:: ipython3

    (subDom7.figuresWritten, e65.figuresWritten)




.. parsed-literal::
   :class: ipython-result

    ('7', '65')



These numbers can also be found as part of a more powerful
``figuredBass.Notation`` object (to be discussed later) in the
``.figuresNotationObj`` attribute:

.. code:: ipython3

    (subDom7.figuresNotationObj, e65.figuresNotationObj)




.. parsed-literal::
   :class: ipython-result

    (<music21.figuredBass.notation.Notation 7>,
     <music21.figuredBass.notation.Notation 6,5>)



.. code:: ipython3

    e65.figuresNotationObj.numbers




.. parsed-literal::
   :class: ipython-result

    (6, 5, 3)



Many of these properties can be changed:

.. code:: ipython3

    rf.key = key.Key('D')
    rf.show()



.. image:: usersGuide_23_romanNumerals_41_0.png
   :width: 196px
   :height: 49px


Changing the key removes any information about pitch spacing. You can’t
have everything. :-)

We’ll put the key of F back and the original pitches before we forget:

.. code:: ipython3

    rf = roman.romanNumeralFromChord(f, kf)

RomanNumerals as Chords
-----------------------

A ``RomanNumeral`` object is a subclass of a Chord object, therefore we
can do everything with them that we could do with a chord. For instance:

.. code:: ipython3

    rf.isMajorTriad()




.. parsed-literal::
   :class: ipython-result

    True



.. code:: ipython3

    rfc = rf.closedPosition()
    rfc.show()



.. image:: usersGuide_23_romanNumerals_47_0.png
   :width: 179px
   :height: 49px


.. code:: ipython3

    rb.lyric = rb.figure
    rb.show()



.. image:: usersGuide_23_romanNumerals_48_0.png
   :width: 190px
   :height: 71px


.. code:: ipython3

    (rf.quality, rc.quality, rb.quality)




.. parsed-literal::
   :class: ipython-result

    ('major', 'major', 'major')



.. code:: ipython3

    e65.inversion()




.. parsed-literal::
   :class: ipython-result

    1



.. code:: ipython3

    e65.primeForm




.. parsed-literal::
   :class: ipython-result

    [0, 3, 5, 8]



.. code:: ipython3

    e65.semitonesFromChordStep(7)




.. parsed-literal::
   :class: ipython-result

    10



That’s all we have for RomanNumerals for now – we will return to
RomanNumeral like objects later when we look at other Harmony objects
such as ChordSymbols and FiguredBass and we look at the romanText
module. But we’ll take a break from musical objects and get acquainted a
bit better with how your system works when running ``music21`` with a
look at :ref:`Chapter 24, Environment <usersGuide_24_environment>`.