.. _moduleFeatures.base:

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

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

.. module:: music21.features.base



.. 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'], ['CS11', 'MD1']) 

    

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

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 opperate 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)

            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. 


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. 


OutputARFF
----------

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

.. class:: OutputARFF(dataSet=None)

    An ARFF (Attribute-Relation File Format) file. http://weka.wikispaces.com/ARFF+(stable+version) 

    >>> 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/tabdelimited.htm 

    **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 cached and on-demand. 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. 


