.. _moduleFeatures.base:

music21.features.base
=====================

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

.. module:: music21.features.base



.. function:: allFeaturesAsList(streamInput)


    returns a tuple containing ALL currentingly implemented feature extractors. The first
    in the tuple are jsymbolic vectors, and the second native vectors. Vectors are NOT nested

    streamInput can be Add a Stream, DataInstance, or path to a corpus or local file to this data set.



    >>> from music21 import *
    >>> s = corpus.parse('bwv66.6')
    >>> f = allFeaturesAsList(s)
    >>> f[1][0:3]
    [[1], [0.6899992497638124], [2]]
    >>> len(f[0]) > 65
    True
    >>> len(f[1]) > 20
    True



.. function:: extractorById(idOrList, library=['jSymbolic', 'native'])

    Get the first feature matched by extractorsById().



    >>> from music21 import *
    >>> s = stream.Stream()
    >>> s.append(pitch.Pitch('a4'))
    >>> fe = features.extractorById('p20')(s) # call class
    >>> fe.extract().vector
    [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0]




.. function:: extractorsById(idOrList, library=['jSymbolic', 'native'])

    Given one or more :class:`~music21.features.FeatureExtractor` ids, return the appropriate  subclass. An optional `library` argument can be added to define which module is used. Current options are jSymbolic and native.



    >>> from music21 import *
    >>> [x.id for x in features.extractorsById('p20')]
    ['P20']
    >>> [x.id for x in features.extractorsById(['p19', 'p20'])]
    ['P19', 'P20']
    ⁠ 
    >>> [x.id for x in features.extractorsById(['r31', 'r32', 'r33', 'r34', 'r35', 'p1', 'p2', 'p3', 'p4', 'p5', 'p6', 'p7', 'p8', 'p9', 'p10', 'p11', 'p12', 'p13', 'p14', 'p15', 'p16', 'p19', 'p20', 'p21'])]
    ['R31', 'R32', 'R33', 'R34', 'R35', 'P1', 'P2', 'P3', 'P4', 'P5', 'P6', 'P7', 'P8', 'P9', 'P10', 'P11', 'P12', 'P13', 'P14', 'P15', 'P16', 'P19', 'P20', 'P21']


    Get all feature extractors from all libraries




    >>> y = [x.id for x in features.extractorsById('all')]
    >>> y[0:3], y[-3:-1]
    (['M1', 'M2', 'M3'], ['MD1', 'MC1'])




.. function:: getIndex(featureString, extractorType=None)


    returns the list index of the given feature extractor and the feature extractor
    category (jsymbolic or native). If feature extractor string is not in either
    jsymbolic or native feature extractors, returns None

    optionally include the extractorType ('jsymbolic' or 'native' if known
    and searching will be made more efficient



    >>> from music21 import *
    >>> features.getIndex('Range')
    (59, 'jsymbolic')
    >>> features.getIndex('Ends With Landini Melodic Contour')
    (19, 'native')
    >>> features.getIndex('abrandnewfeature!')
    >>> features.getIndex('Fifths Pitch Histogram','jsymbolic')
    (68, 'jsymbolic')
    >>> features.getIndex('Tonal Certainty','native')
    (1, 'native')



.. function:: vectorById(streamObj, id, library=['jSymbolic', 'native'])

    Utility function to get a vector from an extractor



    >>> from music21 import *
    >>> s = stream.Stream()
    >>> s.append(pitch.Pitch('a4'))
    >>> features.vectorById(s, 'p20')
    [0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0]



FeatureExtractor
----------------



.. class:: FeatureExtractor(dataOrStream=None, *arguments, **keywords)

    A model of process that extracts a feature from a Music21 Stream. The main public interface is the extract() method.

    The extractor can be passed a Stream or a reference to a DataInstance. All Stream's are internally converted to a DataInstance if necessary. Usage of a DataInstance offers significant performance advantages, as common forms of the Stream are cached for easy processing.




    **FeatureExtractor** **attributes**

        Attributes without Documentation: `normalize`, `description`, `stream`, `discrete`, `dimensions`, `data`, `isSequential`, `name`

    **FeatureExtractor** **methods**

        .. method:: extract(source=None)

            Extract the feature and return the result.



        .. method:: getAttributeLabels()

            Return a list of string in a form that is appropriate for data storage.



            >>> from music21 import *
            >>> fe = features.jSymbolic.AmountOfArpeggiationFeature()
            >>> fe.getAttributeLabels()
            ['Amount_of_Arpeggiation']
            ⁠ 
            >>> fe = features.jSymbolic.FifthsPitchHistogramFeature()
            >>> fe.getAttributeLabels()
            ['Fifths_Pitch_Histogram_0', 'Fifths_Pitch_Histogram_1', 'Fifths_Pitch_Histogram_2', 'Fifths_Pitch_Histogram_3', 'Fifths_Pitch_Histogram_4', 'Fifths_Pitch_Histogram_5', 'Fifths_Pitch_Histogram_6', 'Fifths_Pitch_Histogram_7', 'Fifths_Pitch_Histogram_8', 'Fifths_Pitch_Histogram_9', 'Fifths_Pitch_Histogram_10', 'Fifths_Pitch_Histogram_11']




        .. method:: getBlankFeature()

            Return a properly configured plain feature as a place holder



            >>> from music21 import features
            >>> fe = features.jSymbolic.InitialTimeSignatureFeature()
            >>> fe.getBlankFeature().vector
            [0, 0]



        .. method:: setData(dataOrStream)

            Set the data that this FeatureExtractor will process. Either a Stream or a DataInstance object can be provided.




DataInstance
------------



.. class:: DataInstance(streamObj=None, id=None)


    A data instance for analysis. This object prepares a Stream
    (by stripping ties, etc.) and stores
    multiple commonly-used stream representations once, providing rapid processing.



    **DataInstance** **attributes**

        Attributes without Documentation: `stream`, `partsCount`

    **DataInstance** **methods**

        .. method:: getClassValue()

            No documentation.


        .. method:: getId()

            No documentation.


        .. method:: setClassLabel(classLabel, classValue=None)

            Set the class label, as well as the class value if known. The class label is the attribute name used to define the class of this data instance.



            >>> from music21 import *
            >>> s = corpus.parse('bwv66.6')
            >>> di = features.DataInstance(s)
            >>> di.setClassLabel('Composer', 'Bach')




DataSet
-------



.. class:: DataSet(classLabel=None, featureExtractors=[])


    A set of features, as well as a collection of data to operate on

    Multiple DataInstance objects, a FeatureSet, and an OutputFormat.



    >>> from music21 import *
    >>> ds = features.DataSet(classLabel='Composer')
    >>> f = [features.jSymbolic.PitchClassDistributionFeature, features.jSymbolic.ChangesOfMeterFeature, features.jSymbolic.InitialTimeSignatureFeature]
    >>> ds.addFeatureExtractors(f)
    >>> ds.addData('bwv66.6', classValue='Bach')
    >>> ds.addData('bach/bwv324.xml', classValue='Bach')
    >>> ds.process()
    >>> ds.getFeaturesAsList()[0]
    ['bwv66.6', 0.0, 1.0, 0.375, 0.03125, 0.5, 0.1875, 0.90625, 0.0, 0.4375, 0.6875, 0.09375, 0.875, 0, 4, 4, 'Bach']
    >>> ds.getFeaturesAsList()[1]
    ['bach/bwv324.xml', 0.12, 0.0, 1.0, 0.12, 0.56..., 0.0, ..., 0.52..., 0.0, 0.68..., 0.0, 0.56..., 0, 4, 4, 'Bach']
    >>> ds = ds.getString()



    **DataSet** **attributes**

        Attributes without Documentation: `streams`, `dataInstances`

    **DataSet** **methods**

        .. method:: addData(dataOrStreamOrPath, classValue=None, id=None)

            Add a Stream, DataInstance, or path to a corpus or local file to this data set.

            The class value passed here is assumed to be the same as the classLable assigned at startup.



        .. method:: addFeatureExtractors(values)

            Add one or more FeatureExtractor objects, either as a list or as an individual object.



        .. method:: getAttributeLabels(includeClassLabel=True, includeId=True)

            Return a list of all attribute labels. Optionally add a class label field and/or an id field.



            >>> from music21 import *
            >>> f = [features.jSymbolic.PitchClassDistributionFeature, features.jSymbolic.ChangesOfMeterFeature]
            >>> ds = features.DataSet(classLabel='Composer', featureExtractors=f)
            >>> ds.getAttributeLabels(includeId=False)
            ['Pitch_Class_Distribution_0', 'Pitch_Class_Distribution_1', 'Pitch_Class_Distribution_2', 'Pitch_Class_Distribution_3', 'Pitch_Class_Distribution_4', 'Pitch_Class_Distribution_5', 'Pitch_Class_Distribution_6', 'Pitch_Class_Distribution_7', 'Pitch_Class_Distribution_8', 'Pitch_Class_Distribution_9', 'Pitch_Class_Distribution_10', 'Pitch_Class_Distribution_11', 'Changes_of_Meter', 'Composer']



        .. method:: getClassLabel()

            No documentation.


        .. method:: getClassPositionLabels(includeId=True)

            Return column labels for the presence of a class definition



            >>> from music21 import *
            >>> f = [features.jSymbolic.PitchClassDistributionFeature, features.jSymbolic.ChangesOfMeterFeature]
            >>> ds = features.DataSet(classLabel='Composer', featureExtractors=f)
            >>> ds.getClassPositionLabels()
            [None, False, False, False, False, False, False, False, False, False, False, False, False, False, True]



        .. method:: getDiscreteLabels(includeClassLabel=True, includeId=True)

            Return column labels for discrete status.



            >>> from music21 import *
            >>> f = [features.jSymbolic.PitchClassDistributionFeature, features.jSymbolic.ChangesOfMeterFeature]
            >>> ds = features.DataSet(classLabel='Composer', featureExtractors=f)
            >>> ds.getDiscreteLabels()
            [None, False, False, False, False, False, False, False, False, False, False, False, False, True, True]



        .. method:: getFeaturesAsList(includeClassLabel=True, includeId=True, concatenateLists=True)

            Get processed data as a list of lists, merging any sub-lists in multi-dimensional features.



        .. method:: getString(format='tab')

            Get a string representation of the data set in a specific format.



        .. method:: getUniqueClassValues()

            Return a list of unique class values.



        .. method:: process()

            Process all Data with all FeatureExtractors. Processed data is stored internally as numerous Feature objects.



        .. method:: write(fp=None, format=None, includeClassLabel=True)

            Set the output format object.




Feature
-------



.. class:: Feature()


    An object representation of a feature, capable of presentation in a variety of formats,
    and returned from FeatureExtractor objects.

    Feature objects are simple. It is FeatureExtractors that store all metadata and processing
    routines for creating Feature objects.



    **Feature** **attributes**

        Attributes without Documentation: `description`, `name`, `discrete`, `vector`, `isSequential`, `dimensions`

    **Feature** **methods**

        .. method:: normalize()

            Normalize the vector between 0 and 1, assuming there is more than one value.



        .. method:: prepareVectors()

            Prepare the vector stored in this feature.




OutputARFF
----------

Inherits from: :class:`~music21.features.base.OutputFormat`

.. class:: OutputARFF(dataSet=None)

    An ARFF (Attribute-Relation File Format) file.

    See http://weka.wikispaces.com/ARFF+%28stable+version%29 for more details



    >>> from music21 import *
    >>> oa = features.OutputARFF()
    >>> oa._ext
    '.arff'



    **OutputARFF** **methods**

        .. method:: getHeaderLines(includeClassLabel=True, includeId=True)

            Get the header as a list of lines.



            >>> from music21 import *
            >>> f = [features.jSymbolic.ChangesOfMeterFeature]
            >>> ds = features.DataSet(classLabel='Composer')
            >>> ds.addFeatureExtractors(f)
            >>> of = features.OutputARFF(ds)
            >>> for x in of.getHeaderLines(): print x
            @RELATION Composer
            @ATTRIBUTE Identifier STRING
            @ATTRIBUTE Changes_of_Meter NUMERIC
            @ATTRIBUTE class {}
            @DATA




        .. method:: getString(includeClassLabel=True, includeId=True, lineBreak=None)

            No documentation.


        Methods inherited from :class:`~music21.features.base.OutputFormat`: :meth:`~music21.features.base.OutputFormat.write`


OutputCSV
---------

Inherits from: :class:`~music21.features.base.OutputFormat`

.. class:: OutputCSV(dataSet=None)

    Comma-separated value list.




    **OutputCSV** **methods**

        .. method:: getHeaderLines(includeClassLabel=True, includeId=True)

            Get the header as a list of lines.



            >>> from music21 import *
            >>> f = [features.jSymbolic.ChangesOfMeterFeature]
            >>> ds = features.DataSet(classLabel='Composer')
            >>> ds.addFeatureExtractors(f)
            >>> of = features.OutputCSV(ds)
            >>> of.getHeaderLines()[0]
            ['Identifier', 'Changes_of_Meter', 'Composer']



        .. method:: getString(includeClassLabel=True, includeId=True, lineBreak=None)

            No documentation.


        Methods inherited from :class:`~music21.features.base.OutputFormat`: :meth:`~music21.features.base.OutputFormat.write`


OutputFormat
------------



.. class:: OutputFormat(dataSet=None)

    Provide output for a DataSet, passed as an initial argument.



    **OutputFormat** **methods**

        .. method:: getHeaderLines()

            Get the header as a list of lines.



        .. method:: write(fp=None, includeClassLabel=True, includeId=True)

            Write the file. If not file path is given, a temporary file will be written.




OutputTabOrange
---------------

Inherits from: :class:`~music21.features.base.OutputFormat`

.. class:: OutputTabOrange(dataSet=None)

    Tab delimited file format used with Orange.

    http://orange.biolab.si/doc/reference/Orange.data.formats/



    **OutputTabOrange** **methods**

        .. method:: getHeaderLines(includeClassLabel=True, includeId=True)

            Get the header as a list of lines.



            >>> from music21 import *
            >>> f = [features.jSymbolic.ChangesOfMeterFeature]
            >>> ds = features.DataSet()
            >>> ds.addFeatureExtractors(f)
            >>> of = features.OutputTabOrange(ds)
            >>> for x in of.getHeaderLines(): print x
            ['Identifier', 'Changes_of_Meter']
            ['string', 'discrete']
            ['meta', '']
            ⁠ 
            >>> ds = features.DataSet(classLabel='Composer')
            >>> ds.addFeatureExtractors(f)
            >>> of = features.OutputTabOrange(ds)
            >>> for x in of.getHeaderLines(): print x
            ['Identifier', 'Changes_of_Meter', 'Composer']
            ['string', 'discrete', 'discrete']
            ['meta', '', 'class']




        .. method:: getString(includeClassLabel=True, includeId=True, lineBreak=None)

            Get the complete DataSet as a string with the appropriate headers.



        Methods inherited from :class:`~music21.features.base.OutputFormat`: :meth:`~music21.features.base.OutputFormat.write`


StreamForms
-----------



.. class:: StreamForms(streamObj, prepareStream=True)

    A dictionary-like wrapper of a Stream, providing
    numerous representations, generated on-demand, and cached.

    A single StreamForms object can be created for an
    entire Score, as well as one for each Part and/or Voice.

    A DataSet object manages one or more StreamForms
    objects, and exposes them to FeatureExtractors for usage.



    **StreamForms** **methods**

        .. method:: keys()

            No documentation.



