experimenters Package

experimenters Package

aggregator Module

Aggregating experimenters.

class vis.analyzers.experimenters.aggregator.ColumnAggregator(index, settings=None)

Bases: vis.analyzers.experimenter.Experimenter

(Arguments for the constructor are listed below).

Experiment that aggregates data from columns of a DataFrame, or a list of DataFrame objects, by summing each row. Values from columns named 'all' will not be included in the aggregated results. You may provide a 'column' setting to guide the experimenter to include only certain results.

Example 1

Inputting single DataFrame like this:

Index	piece_1	piece_2
M3	12	24
m3	NaN	36
P5	3	9

Yields this DataFrame:

Index	‘aggregator.ColumnAggregator’
M3	36
m3	36
P5	12

Example 2

Inputting two DataFrame objects is similar.

Index	piece_1
M3	12
P5	3

Index	piece_2
M3	24
m3	36
P5	9

The result is the same DataFrame:

Index	‘aggregator.ColumnAggregator’
M3	36
m3	36
P5	12

Example 3

You may also give a DataFrame (or a list of DataFrame objects) that have a pandas.MultiIndex as produced by subclasses of Indexer. In this case, use the 'column' setting to indicate which indexer’s results you wish to aggregate.

Index	‘frequency.FrequencyExperimenter’		‘feelings.FeelingsExperimenter’
	‘0,1’	‘1,2’	‘Christopher’	‘Alex’
M3	12	24	‘delight’	‘exuberance’
m3	NaN	36	‘sheer joy’	‘nonchalance’
P5	3	9	‘emptiness’	‘serenity’

If 'column' is 'frequency.FrequencyExperimenter', yet again you will have this DataFrame:

Index	‘aggregator.ColumnAggregator’
M3	36
m3	36
P5	12

default_settings = {'column': None}

possible_settings = ['column']

Parameters:'column' (str) – The column name to use for aggregation. The default is None, which aggregates across all columns. If you set this to 'all', it will override the default behaviour of not including columns called 'all'.

run()

Run the ColumnAggregator experiment.

Returns:A Series with an index that is the combination of all indices of the provided pandas objects, and the value is the sum of all values in the pandas objects. Return type:pandas.Series

frequency Module

Experimenters that deal with the frequencies (number of occurrences) of events.

class vis.analyzers.experimenters.frequency.FrequencyExperimenter(index, settings=None)

Bases: vis.analyzers.experimenter.Experimenter

Calculate the number of occurrences of objects in an index.

Use the 'column' setting to choose only the results of one previous analyzer. For example, if you wanted to calculate the frequency of vertical intervals, you would specify 'interval.IntervalIndexer'. This would avoid counting, for example, the horizontal intervals if they were also present.

default_settings = {'column': None}

possible_settings = ['column']

Parameters:'column' (str) – The column name to use for counting frequency. The default is None, which counts all columns. Use this to count only the frequency of one previous analyzer.

run()

Run the FrequencyExperimenter.

Returns:The result of the experiment. Data is stored such that column labels correspond to the part (combinations) totalled in the column, and row labels correspond to a type of the kind of objects found in the given index. Note that all columns are totalled in the “all” column, and that not every part combination will have every interval; in case an interval does not appear in a part combination, the value is numpy.NaN. Return type:list of pandas.DataFrame

lilypond Module

Experimenters related to producing LilyPond-format output from the VIS Framework. Also refer to the vis.analyzers.indexers.lilypond module.

The LilyPondExperimenter uses the outputlilypond module to produce a LilyPond file corresponding to the score.

class vis.analyzers.experimenters.lilypond.AnnotateTheNoteExperimenter(index, settings=None)

Bases: vis.analyzers.experimenter.Experimenter

Make a new Note object with the input set to the lily_markup property, the lily_invisible property set to True, and everything else as a default Note.

possible_settings = ['column']

Use the 'column' setting to determine which column of the DataFrame will be used as the annotations for the notes in the outputted list of Series.

run()

Make a new index of the piece.

Returns:A list of the new indices. The index of each Series corresponds to the index of the Part used to generate it, in the order specified to the constructor. Each element in the Series is a basestring. Return type:list of pandas.Series

class vis.analyzers.experimenters.lilypond.LilyPondExperimenter(index, settings=None)

Bases: vis.analyzers.experimenter.Experimenter

Use the outputlilypond module to produce the LilyPond file that should produce a score of the input.

Note

Perhaps contrary to expectation, you must provide a music21.stream.Score to the LilyPondExperimenter, and any part with annotations belong in the settings.

default_settings = {'annotation_part': None, 'run_lilypond': False, 'output_pathname': None}

possible_settings = ['run_lilypond', 'output_pathname', 'annotation part']

Possible settings for the LilyPondExperimenter include:

Parameters:

• 'run_lilypond' (boolean) – Whether to run LilyPond; if False or omitted, simply produce the input file LilyPond requires.
• 'output_pathname' (basestring) – Pathname for the resulting LilyPond output file. If 'run_lilypond' is True, you must include this setting. If 'run_lilypond' is False and you do not provide 'output_pathname' then the output file is returned by run() as a unicode.
• 'annotation_part' (music21.stream.Part or list of Part) – A Part or list of Part objects with annotation instructions for outputlilypond. This Part will be appended as last in the Score.

required_score_type = 'stream.Score'

This attribute allows IndexedPiece to automatically import and provide the Score for LilyPondExperimenter. Otherwise you would have to do this manually.

run()

Make a string with the LilyPond representation of each score. Run LilyPond, if we’re supposed to.

Returns:A string holding the LilyPond-format representation of the score and its annotation parts. Return type:basestring

class vis.analyzers.experimenters.lilypond.PartNotesExperimenter(score, settings=None)

Bases: vis.analyzers.experimenter.Experimenter

From a Series full of Note objects, craft a music21.stream.Part. The offset of each Note in the output matches its index in the input Series, and each duration property is set to match.

To print a “name” along with the first item in a part, for example to indicate to which part or part combinations the annotations belong, use the optional part_names setting.

default_settings = {}

possible_settings = ['part_names']

Parameters:part_names (list of basestring) – Names for the annotation parts, in order. If there are more part names than parts, extra names will be ignored. If there are fewer part names than parts, some parts will not be named.

required_score_type

alias of Series

run()

Make a new index of the piece.

Returns:A list of the new indices. The index of each Part corresponds to the index of the Series used to generate it, in the order specified to the constructor. Each element in the Part is a Note. Return type:list of music21.stream.Part

vis.analyzers.experimenters.lilypond.annotate_the_note(obj)

Used by AnnotateTheNoteExperimenter to make a Note object with the annotation passed in. Take note (hahaha): the lily_invisible property is set to True!

Parameters:obj (basestring) – A string to put as the lily_markup property of a new Note. Returns:An annotated note. Return type:music21.note.Note

template Module

Template for writing a new experimenter. Use this class to help write a new :class`Experimenter` subclass. The TemplateExperimenter does nothing, and should only be used by programmers.

class vis.analyzers.experimenters.template.TemplateExperimenter(index, settings=None)

Bases: vis.analyzers.experimenter.Experimenter

Template for an Experimenter subclass.

default_settings = {}

The default values for settings named in possible_settings. If a setting doesn’t have a value in this constant, then it must be specified to the constructor at runtime, or the constructor should raise a RuntimeException.

possible_settings = ['fake_setting']

This is a list of basestrings that are the names of the settings used in this experimenter. Specify the types and reasons for each setting as though it were an argument list, like this:

Parameters:'fake_setting' (boolean) – This is a fake setting.

run()

Run an experiment on a piece.

Returns:The result of the experiment. Each experiment should describe its data storage. Return type:pandas.Series or pandas.DataFrame