.. _moduleAnalysis.discrete:

music21.analysis.discrete
=========================

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

.. module:: music21.analysis.discrete

Modular analysis procedures for use alone or
applied with :class:`music21.analysis.windowed.WindowedAnalysis` class.

All procedures should inherit from
:class:`music21.analysis.discrete.DiscreteAnalysis`,
or provide a similar interface.

The :class:`music21.analysis.discrete.KrumhanslSchmuckler`
(for algorithmic key detection) and
:class:`music21.analysis.discrete.Ambitus` (for pitch range analysis) provide examples.




.. function:: analyzeStream(streamObj, *args, **keywords)

    Public interface to discrete analysis methods to be applied to a Stream given as an argument. Methods return process-specific data format. See base-classes for details.

    Analysis methods can be specified as arguments or by use of a `method` keyword argument. If `method` is the class name, that class is returned. Otherwise, the :attr:`~music21.analysis.discrete.DiscreteAnalysis.indentifiers` list of all :class:`~music21.analysis.discrete.DiscreteAnalysis` subclass objects will be searched for matches. The first match that is found is returned.

    :class:`~music21.analysis.discrete.Ambitus`
    :class:`~music21.analysis.discrete.KrumhanslSchmuckler`



    >>> from music21 import *
    >>> s = corpus.parse('bach/bwv66.6')
    >>> analysis.discrete.analyzeStream(s, 'Krumhansl')
    <music21.key.Key of f# minor>
    >>> analysis.discrete.analyzeStream(s, 'ambitus')
    <music21.interval.Interval m21>
    ⁠ 
    >>> analysis.discrete.analyzeStream(s, 'key')
    <music21.key.Key of f# minor>
    >>> analysis.discrete.analyzeStream(s, 'range')
    <music21.interval.Interval m21>


    Note that the same results can be obtained by calling "analyze" directly on the stream object:


    >>> s.analyze('key')
    <music21.key.Key of f# minor>
    >>> s.analyze('range')
    <music21.interval.Interval m21>




DiscreteAnalysis
----------------



.. class:: DiscreteAnalysis(referenceStream=None)

    Parent class for analytical methods.

       Each analytical method returns a discrete numerical (or other) results as well as a color. Colors can be used in mapping output.

       Analytical methods may make use of a `referenceStream` to configure the processor on initialization.



    **DiscreteAnalysis** **attributes**

        Attributes without Documentation: `identifiers`, `name`

    **DiscreteAnalysis** **methods**

        .. method:: clearSolutionsFound()

            Clear all stored solutions



        .. method:: getColorsUsed()

            Based on solutions found so far with with this processor, return the colors that have been used.



        .. method:: getSolution(subStream)

            For a given Stream, apply the analysis and return the best solution.



        .. method:: getSolutionsUsed()

            Based on solutions found so far with with this processor, return the solutions that have been used.



        .. method:: process(subStream)

            Given a Stream, apply the analysis to all components of this Stream. Expected return is a solution (method specific) and a color value.



        .. method:: solutionLegend(compress=False)

            A list of pairs showing all discrete results and the assigned color. Data should be organized to be passed to :class:`music21.graph.GraphColorGridLegend`.

            If `compress` is True, the legend will only show values for solutions that have been encountered.



        .. method:: solutionToColor(result)

            Given a analysis specific result, return the appropriate color. Must be able to handle None in the case that there is no result.



        .. method:: solutionUnitString()

            Return a string describing the solution values. Used in Legend formation.




Ambitus
-------

Inherits from: :class:`~music21.analysis.discrete.DiscreteAnalysis`

.. class:: Ambitus(referenceStream=None)

    An basic analysis method for measuring register.






    >>> p = Ambitus()
    >>> p.identifiers[0]
    'ambitus'



    **Ambitus** **attributes**

        Attributes without Documentation: `identifiers`, `name`

    **Ambitus** **methods**

        .. method:: getPitchRanges(subStream)

            For a given subStream, return the smallest difference between any two pitches and the largest difference between any two pitches. This is used to get the smallest and largest ambitus possible in a given work.



            >>> from music21 import *
            >>> p = analysis.discrete.Ambitus()
            >>> s = stream.Stream()
            >>> c = chord.Chord(['a2', 'b4', 'c8'])
            >>> s.append(c)
            >>> p.getPitchSpan(s)
            (45, 108)
            >>> p.getPitchRanges(s)
            (26, 63)
            ⁠ 
            >>> s = corpus.parse('bach/bwv66.6')
            >>> p.getPitchRanges(s)
            (0, 34)



        .. method:: getPitchSpan(subStream)

            For a given subStream, return the minimum and maximum pitch space value found.

            This public method may be used by other classes.



            >>> from music21 import *
            >>> s = corpus.parse('bach/bwv66.6')
            >>> p = analysis.discrete.Ambitus()
            >>> p.getPitchSpan(s.parts[0].getElementsByClass('Measure')[3])
            (66, 71)
            >>> p.getPitchSpan(s.parts[0].getElementsByClass('Measure')[6])
            (69, 73)
            ⁠ 
            >>> s = stream.Stream()
            >>> c = chord.Chord(['a2', 'b4', 'c8'])
            >>> s.append(c)
            >>> p.getPitchSpan(s)
            (45, 108)



        .. method:: getSolution(sStream)

            Procedure to only return an Inteval object.



            >>> from music21 import *
            >>> s = corpus.parse('bach/bwv66.6')
            >>> p = analysis.discrete.Ambitus()
            >>> p.getSolution(s)
            <music21.interval.Interval m21>




        .. method:: process(sStream)

            Given a Stream, return a solution (in half steps) and a color string.



            >>> from music21 import *
            >>> p = analysis.discrete.Ambitus()
            >>> s = stream.Stream()
            >>> c = chord.Chord(['a2', 'b4', 'c8'])
            >>> s.append(c)
            >>> p.process(s)
            (63, '#665288')



        .. method:: solutionLegend(compress=False)

            Return legend data.



            >>> from music21 import *
            >>> s = corpus.parse('bach/bwv66.6')
            >>> p = analysis.discrete.Ambitus(s.parts[0]) #provide ref stream
            >>> len(p.solutionLegend())
            2
            >>> [len(x) for x in p.solutionLegend()]
            [2, 2]
            ⁠ 
            >>> [len(y) for y in [x for x in p.solutionLegend()]]
            [2, 2]



            >>> s = corpus.parse('bach/bwv66.6')
            >>> p = Ambitus()
            >>> p.solutionLegend(compress=True) # empty if nothing processed
            [['', []], ['', []]]
            ⁠ 
            >>> x = p.process(s.parts[0])
            >>> [len(y) for y in [x for x in p.solutionLegend(compress=True)]]
            [2, 2]



            >>> x = p.process(s.parts[1])
            >>> [len(y) for y in [x for x in p.solutionLegend(compress=True)]]
            [2, 2]




        .. method:: solutionToColor(result)




            >>> from music21 import *
            >>> p = analysis.discrete.Ambitus()
            >>> s = stream.Stream()
            >>> c = chord.Chord(['a2', 'b4', 'c8'])
            >>> s.append(c)
            >>> min, max = p.getPitchSpan(s)
            >>> p.solutionToColor(max-min).startswith('#')
            True



        .. method:: solutionUnitString()

            Return a string describing the solution values. Used in Legend formation.



        Methods inherited from :class:`~music21.analysis.discrete.DiscreteAnalysis`: :meth:`~music21.analysis.discrete.DiscreteAnalysis.clearSolutionsFound`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getColorsUsed`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getSolutionsUsed`


MelodicIntervalDiversity
------------------------

Inherits from: :class:`~music21.analysis.discrete.DiscreteAnalysis`

.. class:: MelodicIntervalDiversity(referenceStream=None)

    An analysis method to determine the diversity of intervals used in a Stream.







    **MelodicIntervalDiversity** **attributes**

        Attributes without Documentation: `identifiers`, `name`

    **MelodicIntervalDiversity** **methods**

        .. method:: countMelodicIntervals(sStream, found=None, ignoreDirection=True, ignoreUnison=True)


            Find all unique melodic intervals in this Stream.

            If `found` is provided as a dictionary, this dictionary will be used to store Intervals, and counts of Intervals already found will be incremented.



        .. method:: getSolution(sStream)

            Solution is the number of unique intervals.



        .. method:: process(sStream, ignoreDirection=True)


            Find how many unique intervals are used in this Stream



        .. method:: solutionToColor(solution)

            No documentation.


        Methods inherited from :class:`~music21.analysis.discrete.DiscreteAnalysis`: :meth:`~music21.analysis.discrete.DiscreteAnalysis.clearSolutionsFound`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getColorsUsed`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getSolutionsUsed`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.solutionLegend`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.solutionUnitString`


KeyWeightKeyAnalysis
--------------------

Inherits from: :class:`~music21.analysis.discrete.DiscreteAnalysis`

.. class:: KeyWeightKeyAnalysis(referenceStream=None)

    Base class for all key-weight key analysis subclasses.



    **KeyWeightKeyAnalysis** **attributes**

        Attributes without Documentation: `identifiers`, `keysValidMajor`, `keysValidMinor`, `name`, `sharpFlatCount`

    **KeyWeightKeyAnalysis** **methods**

        .. method:: getSolution(sStream)

            Return a music21 Key object defining the results of the analysis. Do not call process before calling this method, as this method calls process.

            Note that all alternative solutions are returned as Key objects and stored on a list found at Key.alternateInterpretations.



            >>> from music21 import *
            >>> s = corpus.parse('bach/bwv66.6')
            >>> p = analysis.discrete.KrumhanslSchmuckler()
            >>> p.getSolution(s) # this seems correct
            <music21.key.Key of f# minor>
            ⁠ 
            >>> s = corpus.parse('bach/bwv57.8')
            >>> p = analysis.discrete.KrumhanslSchmuckler(s)
            >>> p.getSolution(s)
            <music21.key.Key of B- major>



        .. method:: process(sStream, storeAlternatives=False)


            Takes in a Stream or sub-Stream and performs analysis
            on all contents of the Stream. The
            :class:`~music21.analysis.windowed.WindowedAnalysis`
            windowing system can be used to get numerous results
            by calling this method.

            Returns two values, a solution data list and a color string.

            The data list contains a key (as a string), a mode
            (as a string), and a correlation value (degree of certainty)



        .. method:: solutionLegend(compress=False)

            Returns a list of lists of possible results for the creation of a legend.

                   >>> from music21 import *
                   >>> p = analysis.discrete.KrumhanslSchmuckler()
                   >>> post = p.solutionLegend()



        .. method:: solutionToColor(solution)

            No documentation.


        .. method:: solutionUnitString()

            Return a string describing the solution values. Used in Legend formation.



        Methods inherited from :class:`~music21.analysis.discrete.DiscreteAnalysis`: :meth:`~music21.analysis.discrete.DiscreteAnalysis.clearSolutionsFound`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getColorsUsed`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getSolutionsUsed`


SimpleWeights
-------------

Inherits from: :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`, :class:`~music21.analysis.discrete.DiscreteAnalysis`

.. class:: SimpleWeights(referenceStream=None)

    Implementation of Craig Sapp's simple weights for Krumhansl-Schmuckler key determination algorithm.

    Values from from http://extra.humdrum.org/man/keycor, which describes these weightings as "Performs most consistently with large regions of music, becomes noiser with smaller regions of music."



    **SimpleWeights** **attributes**

        Attributes without Documentation: `identifiers`, `name`

        Attributes inherited from :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`: :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.keysValidMajor`, :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.keysValidMinor`, :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.sharpFlatCount`

    **SimpleWeights** **methods**

        Methods inherited from :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`: :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.getSolution`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.process`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionLegend`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionToColor`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionUnitString`

        Methods inherited from :class:`~music21.analysis.discrete.DiscreteAnalysis`: :meth:`~music21.analysis.discrete.DiscreteAnalysis.clearSolutionsFound`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getColorsUsed`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getSolutionsUsed`


AardenEssen
-----------

Inherits from: :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`, :class:`~music21.analysis.discrete.DiscreteAnalysis`

.. class:: AardenEssen(referenceStream=None)

    Implementation of Aarden-Essen weightings for Krumhansl-Schmuckler key determination algorithm.

    Values from from http://extra.humdrum.org/man/keycor, which describes these weightings as "Weak tendancy to identify the subdominant key as the tonic."



    **AardenEssen** **attributes**

        Attributes without Documentation: `identifiers`, `name`

        Attributes inherited from :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`: :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.keysValidMajor`, :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.keysValidMinor`, :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.sharpFlatCount`

    **AardenEssen** **methods**

        Methods inherited from :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`: :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.getSolution`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.process`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionLegend`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionToColor`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionUnitString`

        Methods inherited from :class:`~music21.analysis.discrete.DiscreteAnalysis`: :meth:`~music21.analysis.discrete.DiscreteAnalysis.clearSolutionsFound`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getColorsUsed`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getSolutionsUsed`


BellmanBudge
------------

Inherits from: :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`, :class:`~music21.analysis.discrete.DiscreteAnalysis`

.. class:: BellmanBudge(referenceStream=None)

    Implementation of Bellman-Budge weightings for Krumhansl-Schmuckler key determination algorithm.

    Values from from http://extra.humdrum.org/man/keycor, which describes these weightings as "No particular tendancies for confusions with neighboring keys."



    **BellmanBudge** **attributes**

        Attributes without Documentation: `identifiers`, `name`

        Attributes inherited from :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`: :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.keysValidMajor`, :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.keysValidMinor`, :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.sharpFlatCount`

    **BellmanBudge** **methods**

        Methods inherited from :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`: :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.getSolution`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.process`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionLegend`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionToColor`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionUnitString`

        Methods inherited from :class:`~music21.analysis.discrete.DiscreteAnalysis`: :meth:`~music21.analysis.discrete.DiscreteAnalysis.clearSolutionsFound`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getColorsUsed`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getSolutionsUsed`


KrumhanslSchmuckler
-------------------

Inherits from: :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`, :class:`~music21.analysis.discrete.DiscreteAnalysis`

.. class:: KrumhanslSchmuckler(referenceStream=None)

    Implementation of Krumhansl-Schmuckler weightings for Krumhansl-Schmuckler key determination algorithm.



    **KrumhanslSchmuckler** **attributes**

        Attributes without Documentation: `identifiers`, `name`

        Attributes inherited from :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`: :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.keysValidMajor`, :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.keysValidMinor`, :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.sharpFlatCount`

    **KrumhanslSchmuckler** **methods**

        Methods inherited from :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`: :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.getSolution`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.process`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionLegend`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionToColor`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionUnitString`

        Methods inherited from :class:`~music21.analysis.discrete.DiscreteAnalysis`: :meth:`~music21.analysis.discrete.DiscreteAnalysis.clearSolutionsFound`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getColorsUsed`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getSolutionsUsed`


KrumhanslKessler
----------------

Inherits from: :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`, :class:`~music21.analysis.discrete.DiscreteAnalysis`

.. class:: KrumhanslKessler(referenceStream=None)

    Implementation of Krumhansl-Kessler weightings for Krumhansl-Schmuckler key determination algorithm.

    Values from from http://extra.humdrum.org/man/keycor, which describes these weightings as "Strong tendancy to identify the dominant key as the tonic."



    **KrumhanslKessler** **attributes**

        Attributes without Documentation: `identifiers`, `name`

        Attributes inherited from :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`: :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.keysValidMajor`, :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.keysValidMinor`, :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.sharpFlatCount`

    **KrumhanslKessler** **methods**

        Methods inherited from :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`: :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.getSolution`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.process`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionLegend`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionToColor`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionUnitString`

        Methods inherited from :class:`~music21.analysis.discrete.DiscreteAnalysis`: :meth:`~music21.analysis.discrete.DiscreteAnalysis.clearSolutionsFound`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getColorsUsed`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getSolutionsUsed`


TemperleyKostkaPayne
--------------------

Inherits from: :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`, :class:`~music21.analysis.discrete.DiscreteAnalysis`

.. class:: TemperleyKostkaPayne(referenceStream=None)

    Implementation of Temperley-Kostka-Payne weightings for Krumhansl-Schmuckler key determination algorithm.

    Values from from http://extra.humdrum.org/man/keycor, which describes these weightings as "Strong tendancy to identify the relative major as the tonic in minor keys. Well-balanced for major keys."



    **TemperleyKostkaPayne** **attributes**

        Attributes without Documentation: `identifiers`, `name`

        Attributes inherited from :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`: :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.keysValidMajor`, :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.keysValidMinor`, :attr:`~music21.analysis.discrete.KeyWeightKeyAnalysis.sharpFlatCount`

    **TemperleyKostkaPayne** **methods**

        Methods inherited from :class:`~music21.analysis.discrete.KeyWeightKeyAnalysis`: :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.getSolution`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.process`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionLegend`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionToColor`, :meth:`~music21.analysis.discrete.KeyWeightKeyAnalysis.solutionUnitString`

        Methods inherited from :class:`~music21.analysis.discrete.DiscreteAnalysis`: :meth:`~music21.analysis.discrete.DiscreteAnalysis.clearSolutionsFound`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getColorsUsed`, :meth:`~music21.analysis.discrete.DiscreteAnalysis.getSolutionsUsed`


