.. _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. 

            >>> 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`


