.. _moduleAnalysis.discrete:

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

.. WARNING: DO NOT EDIT THIS FILE: AUTOMATICALLY GENERATED

.. 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.SadoianAmbitus` (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.SadoianAmbitus` :class:`~music21.analysis.discrete.KrumhanslSchmuckler` 

    >>> from music21 import *
    >>> s = corpus.parseWork('bach/bwv66.6')
    >>> analysis.discrete.analyzeStream(s, 'Krumhansl')
    (F#, 'minor', 0.81547089257624916) 
    >>> analysis.discrete.analyzeStream(s, 'ambitus')
    <music21.interval.Interval m21> 
    >>> analysis.discrete.analyzeStream(s, 'key')[:2]
    (F#, 'minor') 
    >>> analysis.discrete.analyzeStream(s, '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. 


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

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

.. class:: KrumhanslSchmuckler(referenceStream=None)

    Implementation of the Krumhansl-Schmuckler key determination algorithm 

    **KrumhanslSchmuckler** **attributes**

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

    **KrumhanslSchmuckler** **methods**

        .. method:: getSolution(sStream)

            procedure to only return a text solution 

            >>> from music21 import *
            >>> s = corpus.parseWork('bach/bwv66.6')
            >>> p = KrumhanslSchmuckler()
            >>> p.getSolution(s) # this seems correct
            (F#, 'minor', 0.81547089257624916) 
            >>> s = corpus.parseWork('bach/bwv57.8')
            >>> p = KrumhanslSchmuckler(s)
            >>> p.getSolution(s)
            (B-, 'major', 0.89772788962941652) 

        .. method:: process(sStream)

            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`


SadoianAmbitus
--------------

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

.. class:: SadoianAmbitus(referenceStream=None)

    An basic analysis method for measuring register. 

    

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

    **SadoianAmbitus** **attributes**

        Attributes without Documentation: `identifiers`, `name`

    **SadoianAmbitus** **methods**

        .. method:: getSolution(sStream)

            Procedure to only return an Inteval object. 

            >>> from music21 import *
            >>> s = corpus.parseWork('bach/bwv66.6')
            >>> p = SadoianAmbitus()
            >>> 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.SadoianAmbitus()
            >>> 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.parseWork('bach/bwv66.6')
            >>> p = analysis.discrete.SadoianAmbitus(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.parseWork('bach/bwv66.6')
            >>> p = SadoianAmbitus()
            >>> 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 = SadoianAmbitus()
            >>> 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`


