.. _moduleFiguredBass.segment:

music21.figuredBass.segment
===========================

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

.. module:: music21.figuredBass.segment



.. function:: getPitches(pitchNames=['C', 'E', 'G'], bassPitch=C3, maxPitch=C8)


    Given a list of pitchNames, a bassPitch, and a maxPitch, returns a sorted list of
    pitches between the two limits (inclusive) which correspond to items in pitchNames.



    >>> from music21.figuredBass import segment
    >>> from music21 import pitch
    >>> segment.getPitches()
    [C3, E3, G3, C4, E4, G4, C5, E5, G5, C6, E6, G6, C7, E7, G7, C8]
    >>> segment.getPitches(['G', 'B', 'D', 'F'], bassPitch = pitch.Pitch('B2'))
    [B2, D3, F3, G3, B3, D4, F4, G4, B4, D5, F5, G5, B5, D6, F6, G6, B6, D7, F7, G7, B7]
    >>> segment.getPitches(['F##','A#','C#'], bassPitch = pitch.Pitch('A#3'))
    [A#3, C#4, F##4, A#4, C#5, F##5, A#5, C#6, F##6, A#6, C#7, F##7, A#7]



.. function:: printRules(rulesList, maxLength=4)


    Method which can print to the console rules inputted into
    :meth:`~music21.figuredBass.segment.Segment.singlePossibilityRules`,
    :meth:`~music21.figuredBass.segment.Segment.consecutivePossibilityRules`, and
    :meth:`~music21.figuredBass.segment.Segment.specialResolutionRules`.
    For the first two methods, maxLength is 4. For the third method, maxLength is 3.



OverlayedSegment
----------------

Inherits from: :class:`~music21.figuredBass.segment.Segment`

.. class:: OverlayedSegment(bassNote=<music21.note.Note C>, notationString=None, fbScale=<music21.figuredBass.realizerScale FiguredBassScale>, fbRules=<music21.figuredBass.rules Rules>, numParts=4, maxPitch=B5, listOfPitches=None)


    Class to allow Segments to be overlayed with non-chord notes.




    A Segment corresponds to a 1:1 realization of a bassNote and notationString of a :class:`~music21.figuredBass.realizer.FiguredBassLine`.
    It is created by passing six arguments: a :class:`~music21.figuredBass.realizerScale.FiguredBassScale`, a bassNote, a notationString,
    a :class:`~music21.figuredBass.rules.Rules` object, a number of parts and a maximum pitch. Realizations of a Segment are represented
    as possibility tuples (see :mod:`~music21.figuredBass.possibility` for more details).

    Methods in Python's `itertools <http://docs.python.org/library/itertools.html>`_ module are used extensively. Methods
    which generate possibilities or possibility progressions return iterators, which are turned into lists in the examples
    for display purposes only.


    Here, a Segment is created using the default values: a FiguredBassScale in C, a bassNote of C3, an empty notationString, and a default
    Rules object.



    >>> from music21.figuredBass import segment
    >>> s1 = segment.Segment()
    >>> s1.bassNote
    <music21.note.Note C>
    >>> s1.numParts
    4
    >>> s1.pitchNamesInChord
    ['C', 'E', 'G']
    >>> s1.allPitchesAboveBass
    [C3, E3, G3, C4, E4, G4, C5, E5, G5]
    >>> s1.segmentChord
    <music21.chord.Chord C3 E3 G3 C4 E4 G4 C5 E5 G5>




Segment
-------



.. class:: Segment(bassNote=<music21.note.Note C>, notationString=None, fbScale=<music21.figuredBass.realizerScale FiguredBassScale>, fbRules=<music21.figuredBass.rules Rules>, numParts=4, maxPitch=B5, listOfPitches=None)



    A Segment corresponds to a 1:1 realization of a bassNote and notationString of a :class:`~music21.figuredBass.realizer.FiguredBassLine`.
    It is created by passing six arguments: a :class:`~music21.figuredBass.realizerScale.FiguredBassScale`, a bassNote, a notationString,
    a :class:`~music21.figuredBass.rules.Rules` object, a number of parts and a maximum pitch. Realizations of a Segment are represented
    as possibility tuples (see :mod:`~music21.figuredBass.possibility` for more details).

    Methods in Python's `itertools <http://docs.python.org/library/itertools.html>`_ module are used extensively. Methods
    which generate possibilities or possibility progressions return iterators, which are turned into lists in the examples
    for display purposes only.


    Here, a Segment is created using the default values: a FiguredBassScale in C, a bassNote of C3, an empty notationString, and a default
    Rules object.



    >>> from music21.figuredBass import segment
    >>> s1 = segment.Segment()
    >>> s1.bassNote
    <music21.note.Note C>
    >>> s1.numParts
    4
    >>> s1.pitchNamesInChord
    ['C', 'E', 'G']
    >>> s1.allPitchesAboveBass
    [C3, E3, G3, C4, E4, G4, C5, E5, G5]
    >>> s1.segmentChord
    <music21.chord.Chord C3 E3 G3 C4 E4 G4 C5 E5 G5>



    **Segment** **attributes**

        .. attribute:: bassNote

            A :class:`~music21.note.Note` whose pitch forms the bass of each possibility.


        .. attribute:: numParts

            The number of parts (including the bass) that possibilities should contain, which
            comes directly from :attr:`~music21.figuredBass.rules.Rules.numParts` in the Rules object.


        .. attribute:: segmentChord

            :attr:`~music21.figuredBass.segment.Segment.allPitchesAboveBass` represented as a :class:`~music21.chord.Chord`.


        .. attribute:: allPitchesAboveBass

            A list of allowable pitches in the upper parts of a possibility. This is derived using
            :meth:`~music21.figuredBass.segment.getPitches`, providing bassNote.pitch, :attr:`~music21.figuredBass.rules.Rules.maxPitch`
            from the Rules object, and :attr:`~music21.figuredBass.segment.Segment.pitchNamesInChord` as arguments.


        .. attribute:: fbRules

            A deepcopy of the :class:`~music21.figuredBass.rules.Rules` object provided.


        .. attribute:: pitchNamesInChord

            A list of allowable pitch names. This is derived from bassNote.pitch and notationString
            using :meth:`~music21.figuredBass.realizerScale.FiguredBassScale.getPitchNames`.


    **Segment** **methods**

        .. method:: allSinglePossibilities()


            Returns an iterator through a set of naive possibilities for
            a Segment, using :attr:`~music21.figuredBass.segment.Segment.numParts`,
            the pitch of :attr:`~music21.figuredBass.segment.Segment.bassNote`, and
            :attr:`~music21.figuredBass.segment.Segment.allPitchesAboveBass`.



            >>> from music21.figuredBass import segment
            >>> segmentA = segment.Segment()
            >>> allPossib = segmentA.allSinglePossibilities()
            >>> allPossib.__class__
            <type 'itertools.product'>


            The number of naive possibilities is always the length of
            :attr:`~music21.figuredBass.segment.Segment.allPitchesAboveBass`
            raised to the (:attr:`~music21.figuredBass.segment.Segment.numParts` - 1)
            power. The power is 1 less than the number of parts because
            the bass pitch is constant.




            >>> allPossibList = list(allPossib)
            >>> len(segmentA.allPitchesAboveBass)
            9
            >>> segmentA.numParts
            4
            >>> len(segmentA.allPitchesAboveBass) ** (segmentA.numParts-1)
            729
            >>> len(allPossibList)
            729
            >>> allPossibList[81]
            (E3, C3, C3, C3)
            >>> allPossibList[275]
            (C4, C4, G4, C3)
            >>> allPossibList[426]
            (G4, G3, C4, C3)



        .. method:: singlePossibilityRules(fbRules=<music21.figuredBass.rules Rules>)


            A framework for storing single possibility rules and methods to be applied
            in :meth:`~music21.figuredBass.segment.Segment.allCorrectSinglePossibilities`.
            Takes in a :class:`~music21.figuredBass.rules.Rules` object, fbRules.


            Items are added within this method in the following form:


            (willRunOnlyIfTrue, methodToRun, keepSolnsWhichReturn, optionalArgs)


            These items are compiled internally when :meth:`~music21.figuredBass.segment.Segment.allCorrectSinglePossibilities`
            is called on a Segment. Here, the compilation of rules and methods bases on a default fbRules is shown.



            >>> from music21.figuredBass import segment
            >>> segmentA = segment.Segment()
            >>> allSingleRules = segmentA.singlePossibilityRules()
            >>> segment.printRules(allSingleRules)
            Will run:  Method:                       Keep solutions which return:  Arguments:
            True       isIncomplete                  False                         ['C', 'E', 'G']
            True       upperPartsWithinLimit         True                          12
            True       voiceCrossing                 False                         None


            Here, a modified fbRules is provided, which allows for incomplete possibilities.




            >>> from music21.figuredBass import rules
            >>> fbRules = rules.Rules()
            >>> fbRules.forbidIncompletePossibilities = False
            >>> allSingleRules = segmentA.singlePossibilityRules(fbRules)
            >>> segment.printRules(allSingleRules)
            Will run:  Method:                       Keep solutions which return:  Arguments:
            False      isIncomplete                  False                         ['C', 'E', 'G']
            True       upperPartsWithinLimit         True                          12
            True       voiceCrossing                 False                         None



        .. method:: allCorrectSinglePossibilities()


            Uses :meth:`~music21.figuredBass.segment.Segment.allSinglePossibilities` and
            returns an iterator through a set of correct possibilities for
            a Segment, all possibilities which pass all filters in
            :meth:`~music21.figuredBass.segment.Segment.singlePossibilityRules`.




            >>> from music21.figuredBass import segment
            >>> segmentA = segment.Segment()
            >>> allPossib = segmentA.allSinglePossibilities()
            >>> allCorrectPossib = segmentA.allCorrectSinglePossibilities()


            Most of the 729 naive possibilities were filtered out using the default rules set,
            leaving only 21.




            >>> allPossibList = list(allPossib)
            >>> len(allPossibList)
            729
            >>> allCorrectPossibList = list(allCorrectPossib)
            >>> len(allCorrectPossibList)
            21
            >>> allCorrectPossibList[5]
            (E4, G3, G3, C3)
            >>> allCorrectPossibList[12]
            (C5, G4, E4, C3)
            >>> allCorrectPossibList[20]
            (G5, G5, E5, C3)



        .. method:: consecutivePossibilityRules(fbRules=<music21.figuredBass.rules Rules>)


            A framework for storing consecutive possibility rules and methods to be applied
            in :meth:`~music21.figuredBass.segment.Segment.allCorrectConsecutivePossibilities`.
            Takes in a :class:`~music21.figuredBass.rules.Rules` object, fbRules.


            Items are added within this method in the following form:


            (willRunOnlyIfTrue, methodToRun, keepSolnsWhichReturn, optionalArgs)


            These items are compiled internally when :meth:`~music21.figuredBass.segment.Segment.allCorrectConsecutivePossibilities`
            is called on a Segment. Here, the compilation of rules and methods bases on a default fbRules is shown.



            >>> from music21.figuredBass import segment
            >>> segmentA = segment.Segment()
            >>> allConsecRules = segmentA.consecutivePossibilityRules()
            >>> segment.printRules(allConsecRules)
            Will run:  Method:                       Keep solutions which return:  Arguments:
            True       partsSame                     True                          []
            False      upperPartsSame                True                          None
            True       voiceOverlap                  False                         None
            True       partMovementsWithinLimits     True                          []
            True       parallelFifths                False                         None
            True       parallelOctaves               False                         None
            True       hiddenFifth                   False                         None
            True       hiddenOctave                  False                         None
            False      couldBeItalianA6Resolution    True                          [C3, C3, E3, G3], True


            Now, a modified fbRules is provided, allowing hidden octaves and
            voice overlap, and limiting the soprano line to stepwise motion.




            >>> from music21.figuredBass import rules
            >>> fbRules = rules.Rules()
            >>> fbRules.forbidVoiceOverlap = False
            >>> fbRules.forbidHiddenOctaves = False
            >>> fbRules.partMovementLimits.append((1,2))
            >>> allConsecRules = segmentA.consecutivePossibilityRules(fbRules)
            >>> segment.printRules(allConsecRules)
            Will run:  Method:                       Keep solutions which return:  Arguments:
            True       partsSame                     True                          []
            False      upperPartsSame                True                          None
            False      voiceOverlap                  False                         None
            True       partMovementsWithinLimits     True                          [(1, 2)]
            True       parallelFifths                False                         None
            True       parallelOctaves               False                         None
            True       hiddenFifth                   False                         None
            False      hiddenOctave                  False                         None
            False      couldBeItalianA6Resolution    True                          [C3, C3, E3, G3], True



        .. method:: specialResolutionRules(fbRules=<music21.figuredBass.rules Rules>)


            A framework for storing methods which perform special resolutions
            on Segments. Unlike the methods in
            :meth:`~music21.figuredBass.segment.Segment.singlePossibilityRules` and
            :meth:`~music21.figuredBass.segment.Segment.consecutivePossibilityRules`,
            these methods deal with the Segment itself, and rely on submethods
            to resolve the individual possibilities accordingly depending on what
            the resolution Segment is.


            Items are added within this method in the following form:


            (willRunOnlyIfTrue, methodToRun, optionalArgs)


            These items are compiled internally when :meth:`~music21.figuredBass.segment.Segment.allCorrectConsecutivePossibilities`
            is called on a Segment. Here, the compilation of rules and methods based on a default fbRules is shown.



            >>> from music21.figuredBass import segment
            >>> segmentA = segment.Segment()
            >>> allSpecialResRules = segmentA.specialResolutionRules()
            >>> segment.printRules(allSpecialResRules, maxLength = 3)
            Will run:  Method:                          Arguments:
            False      resolveDominantSeventhSegment    None
            False      resolveDiminishedSeventhSegment  False
            False      resolveAugmentedSixthSegment     None


            Dominant Seventh Segment:




            >>> from music21 import note
            >>> segmentA = segment.Segment(bassNote = note.Note('B2'), notationString = "6,5")
            >>> allSpecialResRules = segmentA.specialResolutionRules()
            >>> segment.printRules(allSpecialResRules, maxLength = 3)
            Will run:  Method:                          Arguments:
            True       resolveDominantSeventhSegment    None
            False      resolveDiminishedSeventhSegment  False
            False      resolveAugmentedSixthSegment     None


            Fully-Diminished Seventh Segment:




            >>> segmentA = segment.Segment(bassNote = note.Note('B2'), notationString = "-7")
            >>> allSpecialResRules = segmentA.specialResolutionRules()
            >>> segment.printRules(allSpecialResRules, maxLength = 3)
            Will run:  Method:                          Arguments:
            False      resolveDominantSeventhSegment    None
            True       resolveDiminishedSeventhSegment  False
            False      resolveAugmentedSixthSegment     None


            Augmented Sixth Segment:




            >>> segmentA = segment.Segment(bassNote = note.Note('A-2'), notationString = "#6,b5")
            >>> allSpecialResRules = segmentA.specialResolutionRules()
            >>> segment.printRules(allSpecialResRules, maxLength = 3)
            Will run:  Method:                          Arguments:
            False      resolveDominantSeventhSegment    None
            False      resolveDiminishedSeventhSegment  False
            True       resolveAugmentedSixthSegment     None



        .. method:: allCorrectConsecutivePossibilities(segmentB)


            Returns an iterator through correct (possibA, possibB) pairs.


            * If segmentA (self) is a special Segment, meaning that one of the Segment
              resolution methods in :meth:`~music21.figuredBass.segment.Segment.specialResolutionRules`
              needs to be applied, then this method returns every correct possibility of segmentA
              matched up with exactly one resolution possibility.


            * If segmentA is an ordinary, non-special Segment, then this method returns every
              combination of correct possibilities of segmentA and correct possibilities of segmentB
              which passes all filters in :meth:`~music21.figuredBass.segment.Segment.consecutivePossibilityRules`.


            Two notes on segmentA being a special Segment:


            1. By default resolution possibilities are not filtered using :meth:`~music21.figuredBass.segment.Segment.singlePossibilityRules`
               rules of segmentB. Filter by setting :attr:`~music21.figuredBass.rules.Rules.applySinglePossibRulesToResolution` to True.


            2. By default, (possibA, possibB) pairs are not filtered using :meth:`~music21.figuredBass.segment.Segment.consecutivePossibilityRules`
               rules of segmentA. Filter by setting :attr:`~music21.figuredBass.rules.Rules.applyConsecutivePossibRulesToResolution` to True.



            >>> from music21.figuredBass import segment
            >>> from music21 import note
            >>> segmentA = segment.Segment(bassNote = note.Note('C3'), notationString = "")
            >>> segmentB = segment.Segment(bassNote = note.Note('D3'), notationString = "4,3")


            Here, an ordinary resolution is being executed, because segmentA is an ordinary Segment.




            >>> consecPairs1 = segmentA.allCorrectConsecutivePossibilities(segmentB)
            >>> consecPairsList1 = list(consecPairs1)
            >>> len(consecPairsList1)
            31
            >>> consecPairsList1[29]
            ((G5, G5, E5, C3), (G5, F5, B4, D3))


            Here, a special resolution is being executed, because segmentA below is a
            special Segment.




            >>> segmentA = segment.Segment(bassNote = note.Note('D3'), notationString = "4,3")
            >>> segmentB = segment.Segment(bassNote = note.Note('C3'), notationString = "")
            >>> consecPairs2 = segmentA.allCorrectConsecutivePossibilities(segmentB)
            >>> consecPairsList2 = list(consecPairs2)
            >>> len(consecPairsList2)
            6
            >>> consecPairsList2[5]
            ((G5, F5, B4, D3), (G5, E5, C5, C3))



        .. method:: resolveDominantSeventhSegment(segmentB)


            Can resolve a Segment whose :attr:`~music21.figuredBass.segment.Segment.segmentChord`
            spells out a dominant seventh chord. If no applicable method in
            :mod:`~music21.figuredBass.resolution` can be used, the Segment is resolved
            as an ordinary Segment.




            >>> from music21.figuredBass import segment
            >>> from music21 import note
            >>> segmentA = segment.Segment(bassNote = note.Note('G2'), notationString = "7")
            >>> allDomPossib = segmentA.allCorrectSinglePossibilities()
            >>> allDomPossibList = list(allDomPossib)
            >>> len(allDomPossibList)
            8
            >>> allDomPossibList[2]
            (D4, B3, F3, G2)
            >>> allDomPossibList[5]
            (D5, B4, F4, G2)
            >>> allDomPossibList[7] # Soprano pitch of resolution (C6) exceeds default maxPitch of B5, filtered out.
            (B5, F5, D5, G2)




            >>> segmentB = segment.Segment(bassNote = note.Note('C3'), notationString = "")
            >>> domResPairs = segmentA.resolveDominantSeventhSegment(segmentB)
            >>> domResPairsList = list(domResPairs)
            >>> len(domResPairsList)
            7
            >>> domResPairsList[2]
            ((D4, B3, F3, G2), (C4, C4, E3, C3))
            >>> domResPairsList[5]
            ((D5, B4, F4, G2), (C5, C5, E4, C3))



        .. method:: resolveDiminishedSeventhSegment(segmentB, doubledRoot=False)


            Can resolve a Segment whose :attr:`~music21.figuredBass.segment.Segment.segmentChord`
            spells out a diminished seventh chord. If no applicable method in
            :mod:`~music21.figuredBass.resolution` can be used, the Segment is resolved
            as an ordinary Segment.



            >>> from music21.figuredBass import segment
            >>> from music21 import note
            >>> segmentA = segment.Segment(bassNote = note.Note('B2'), notationString = "b7")
            >>> allDimPossib = segmentA.allCorrectSinglePossibilities()
            >>> allDimPossibList = list(allDimPossib)
            >>> len(allDimPossibList)
            7
            >>> allDimPossibList[4]
            (D5, A-4, F4, B2)
            >>> allDimPossibList[6]
            (A-5, F5, D5, B2)




            >>> segmentB = segment.Segment(bassNote = note.Note('C3'), notationString = "")
            >>> dimResPairs = segmentA.resolveDiminishedSeventhSegment(segmentB)
            >>> dimResPairsList = list(dimResPairs)
            >>> len(dimResPairsList)
            7
            >>> dimResPairsList[4]
            ((D5, A-4, F4, B2), (E5, G4, E4, C3))
            >>> dimResPairsList[6]
            ((A-5, F5, D5, B2), (G5, E5, E5, C3))



        .. method:: resolveAugmentedSixthSegment(segmentB)


            Can resolve a Segment whose :attr:`~music21.figuredBass.segment.Segment.segmentChord` spells out a
            French, German, or Swiss augmented sixth chord. Italian augmented sixth Segments are solved as an
            ordinary Segment using :meth:`~music21.figuredBass.possibility.couldBeItalianA6Resolution`. If no
            applicable method in :mod:`~music21.figuredBass.resolution` can be used, the Segment is resolved
            as an ordinary Segment.




            >>> from music21.figuredBass import segment
            >>> from music21 import note
            >>> segmentA = segment.Segment(bassNote = note.Note("A-2"), notationString = "#6,b5,3")
            >>> segmentA.pitchNamesInChord # spell out a Gr+6 chord
            ['A-', 'C', 'E-', 'F#']
            >>> allAugSixthPossib = segmentA.allCorrectSinglePossibilities()
            >>> allAugSixthPossibList = list(allAugSixthPossib)
            >>> len(allAugSixthPossibList)
            7
            >>> allAugSixthPossibList[1]
            (C4, F#3, E-3, A-2)
            >>> allAugSixthPossibList[4]
            (C5, F#4, E-4, A-2)




            >>> segmentB = segment.Segment(bassNote = note.Note("G2"), notationString = "")
            >>> allAugResPossibPairs = segmentA.resolveAugmentedSixthSegment(segmentB)
            >>> allAugResPossibPairsList = list(allAugResPossibPairs)
            >>> len(allAugResPossibPairsList)
            7
            >>> allAugResPossibPairsList[1]
            ((C4, F#3, E-3, A-2), (B3, G3, D3, G2))
            >>> allAugResPossibPairsList[4]
            ((C5, F#4, E-4, A-2), (B4, G4, D4, G2))




