.. _moduleFiguredBass.notation:

music21.figuredBass.notation
============================

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

.. module:: music21.figuredBass.notation



.. function:: convertToPitch(pitchString)


    Converts a pitchString to a :class:`~music21.pitch.Pitch`, only if necessary.
    This method is identical to the one in :mod:`~music21.figuredBass.realizerScale`.



    >>> from music21.figuredBass import realizerScale
    >>> pitchString = 'C5'
    >>> realizerScale.convertToPitch(pitchString)
    C5
    >>> realizerScale.convertToPitch(pitch.Pitch('E4')) # does nothing
    E4



Notation
--------



.. class:: Notation(notationColumn=None)


    Breaks apart and stores the information in a figured bass notation
    column, which is a string of figures, each associated with a number
    and an optional modifier. The figures are delimited using commas.
    Examples include "7,5,#3", "6,4", and "6,4+,2".


    Valid modifiers include those accepted by :class:`~music21.pitch.Accidental`,
    such as #, -, and n, as well as those which can correspond to one, such as +,
    /, and b.


    .. note:: If a figure has a modifier but no number, the number is
        assumed to be 3.


    Notation also translates many forms of shorthand notation into longhand. It understands
    all the forms of shorthand notation listed below. This is true even if a number is accompanied
    by a modifier, or if a stand-alone modifier implies a 3.


    * None, "" or "5" -> "5,3"


    * "6" -> "6,3"


    * "7" -> "7,5,3"


    * "6,5" -> "6,5,3"


    * "4,3" -> "6,4,3"


    * "4,2" or "2" -> "6,4,2"


    * "9" -> "9,7,5,3"


    * "11" -> "11,9,7,5,3"


    * "13" -> "13,11,9,7,5,3"


    Figures are saved in order from left to right as found in the notationColumn.



    >>> from music21.figuredBass import notation
    >>> n1 = notation.Notation("4+,2")
    >>> n1.notationColumn
    '4+,2'
    >>> n1.figureStrings
    ['4+', '2']
    >>> n1.origNumbers
    (4, 2)
    >>> n1.origModStrings
    ('+', None)
    >>> n1.numbers
    (6, 4, 2)
    >>> n1.modifierStrings
    (None, '+', None)
    >>> n1.modifiers
    (<modifier None None>, <modifier + <accidental sharp>>, <modifier None None>)
    >>> n1.figures[0]
    <music21.figuredBass.notation Figure 6 <modifier None None>>
    >>> n1.figures[1]
    <music21.figuredBass.notation Figure 4 <modifier + <accidental sharp>>>
    >>> n1.figures[2]
    <music21.figuredBass.notation Figure 2 <modifier None None>>


    Here, a stand-alone # is being passed to Notation.




    >>> n2 = notation.Notation("#")
    >>> n2.numbers
    (5, 3)
    >>> n2.modifiers
    (<modifier None None>, <modifier # <accidental sharp>>)
    >>> n2.figures[0]
    <music21.figuredBass.notation Figure 5 <modifier None None>>
    >>> n2.figures[1]
    <music21.figuredBass.notation Figure 3 <modifier # <accidental sharp>>>


    Now, a stand-alone b is being passed to Notation as part of a larger notationColumn.




    >>> n3 = notation.Notation("b6,b")
    >>> n3.numbers
    (6, 3)
    >>> n3.modifiers
    (<modifier b <accidental flat>>, <modifier b <accidental flat>>)
    >>> n3.figures[0]
    <music21.figuredBass.notation Figure 6 <modifier b <accidental flat>>>
    >>> n3.figures[1]
    <music21.figuredBass.notation Figure 3 <modifier b <accidental flat>>>



    **Notation** **attributes**

        .. attribute:: notationColumn

            A string of figures delimited by commas, each associated with a number and an optional modifier.


        .. attribute:: figureStrings

            A list of figures derived from the original :attr:`~music21.figuredBass.notation.Notation.notationColumn`.


        .. attribute:: numbers

            The numbers associated with the expanded :attr:`~music21.figuredBass.notation.Notation.notationColumn`.


        .. attribute:: modifiers

            A list of :class:`~music21.figuredBass.notation.Modifier` objects associated with the expanded :attr:`~music21.figuredBass.notation.Notation.notationColumn`.


        .. attribute:: figures

            A list of :class:`~music21.figuredBass.notation.Figure` objects associated with figures in the expanded :attr:`~music21.figuredBass.notation.Notation.notationColumn`.


        .. attribute:: origNumbers

            The numbers associated with the original :attr:`~music21.figuredBass.notation.Notation.notationColumn`.


        .. attribute:: origModStrings

            The modifiers associated with the original :attr:`~music21.figuredBass.notation.Notation.notationColumn`, as strings.


        .. attribute:: modifierStrings

            The modifiers associated with the expanded :attr:`~music21.figuredBass.notation.Notation.notationColumn`, as strings.



Figure
------



.. class:: Figure(number=1, modifierString=None)


    A Figure is created by providing a number and a modifierString. The
    modifierString is turned into a :class:`~music21.figuredBass.notation.Modifier`,
    and a ModifierException is raised if the modifierString is not valid.



    >>> from music21.figuredBass import notation
    >>> f1 = notation.Figure(4, '+')
    >>> f1.number
    4
    >>> f1.modifierString
    '+'
    >>> f1.modifier
    <modifier + <accidental sharp>>
    >>> f1
    <music21.figuredBass.notation Figure 4 <modifier + <accidental sharp>>>



    **Figure** **attributes**

        .. attribute:: modifierString

            A modifier string associated with an expanded :attr:`~music21.figuredBass.notation.Notation.notationColumn`.


        .. attribute:: modifier

            A :class:`~music21.figuredBass.notation.Modifier` associated with an expanded :attr:`~music21.figuredBass.notation.Notation.notationColumn`.


        .. attribute:: number

            A number associated with an expanded :attr:`~music21.figuredBass.notation.Notation.notationColumn`.



Modifier
--------



.. class:: Modifier(modifierString=None)


    Turns a modifierString (a modifier in a :attr:`~music21.figuredBass.notation.Notation.notationColumn`)
    to an :class:`~music21.pitch.Accidental`. A ModifierException is raised if the modifierString is not valid.


    Accepted inputs are those accepted by Accidental, as well as the following:


    * '+' or '\' -> '#'


    * 'b' or '/' -> '-'




    >>> from music21.figuredBass import notation
    >>> m1a = notation.Modifier("#")
    >>> m1a.modifierString
    '#'
    >>> m1a.accidental
    <accidental sharp>


    Providing a + in place of a sharp, we get the same result for the accidental.




    >>> m2a = notation.Modifier("+")
    >>> m2a.accidental
    <accidental sharp>


    If None or "" is provided for modifierString, then the accidental is None.




    >>> m2a = notation.Modifier(None)
    >>> m2a.accidental == None
    True
    >>> m2b = notation.Modifier("")
    >>> m2b.accidental == None
    True



    **Modifier** **attributes**

        .. attribute:: modifierString

            A modifier string associated with an expanded :attr:`~music21.figuredBass.notation.Notation.notationColumn`.


        .. attribute:: accidental

            A :class:`~music21.pitch.Accidental` corresponding to :attr:`~music21.figuredBass.notation.Modifier.modifierString`.


    **Modifier** **methods**

        .. method:: modifyPitch(pitchToAlter, inPlace=False)


            Given a :class:`~music21.pitch.Pitch`, modify its :attr:`~music21.pitch.Pitch.accidental`
            given the Modifier's :attr:`~music21.figuredBass.notation.Modifier.accidental`.



            >>> from music21 import pitch
            >>> from music21.figuredBass import notation
            >>> m1 = notation.Modifier('#')
            >>> m2 = notation.Modifier('-')
            >>> m3 = notation.Modifier('n')
            >>> p1a = pitch.Pitch('D5')
            >>> m1.modifyPitch(p1a) # Sharp
            D#5
            >>> m2.modifyPitch(p1a) # Flat
            D-5
            >>> p1b = pitch.Pitch('D#5')
            >>> m3.modifyPitch(p1b)
            D5



        .. method:: modifyPitchName(pitchNameToAlter)


            Given a pitch name, modify its accidental given the Modifier's
            :attr:`~music21.figuredBass.notation.Modifier.accidental`.



            >>> from music21.figuredBass import notation
            >>> m1 = notation.Modifier('#')
            >>> m2 = notation.Modifier('-')
            >>> m3 = notation.Modifier('n')
            >>> m1.modifyPitchName('D') # Sharp
            'D#'
            >>> m2.modifyPitchName('F') # Flat
            'F-'
            >>> m3.modifyPitchName('C#') # Natural
            'C'




