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

*Example:*

import music21 from vis.analyzers.indexers import noterest from vis.analyzers.experimenters import aggregator, frequency

score = music21.converter.parse(‘example.xml’) notes = noterest.NoteRestIndexer(score).run()

freqs = frequency.FrequencyExperimenter(notes).run() agg = aggregator.ColumnAggregator(freqs).run() print(agg)

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

*Example:*

import music21 from vis.analyzers.indexers import noterest from vis.analyzers.experimenters import frequency

score = music21.converter.parse(‘example.xml’) notes = noterest.NoteRestIndexer(score).run()

freqs = frequency.FrequencyExperimenter(notes).run() print(freqs)

barchart Module

The experimenters in this module all generate bar charts. Currently the only class is RBarChart, which uses Rscript to run a script in the R programming language.

class vis.analyzers.experimenters.barchart.RBarChart(index, settings=None)

Bases: vis.analyzers.experimenter.Experimenter

Use Rscript to run a bar-chart-generating script in the R programming language.

OUTPUT_TYPES = ('eps', 'ps', 'tex', 'pdf', 'jpeg', 'tiff', 'png', 'bmp', 'svg')

R additionally supports the 'wmf' format, which is for Windows only. However, since VIS will likely never run on Windows, and since Windows also supports all the other formats, we do not allow 'wmf' in this experimenter.

RSCRIPT_PATH = '/usr/bin/Rscript'

Full pathname to the Rscript program. If this doesn’t work on your system, you’ll have a hard time getting RbarChart to work.

default_settings = {'column': 'freq', 'token': 'objects', 'type': 'png', 'nr_pieces': None}

Deafult values for the optional settings.

possible_settings = ('pathname', 'column', 'type', 'token', 'nr_pieces')

Only the 'pathname' setting is required. For default values, refer to the descriptions below and the values in default_settings.

Parameters:

• 'pathname' (str) – The pathname to use for the outputted file.
• 'column' (str) – The column of the DataFrame to choose for outputting. If the data you wish to include in the chart is not in the 'freq' column, use this setting to determine which column is used instead.
• 'type' (str) – The output type, chosen from OUTPUT_TYPES.
• 'token' (str) – The “token” to pass onto the bar chart script, telling it what type of object is being displayed. This should either be a string ending with '-gram', the word 'interval' or 'objects', which is the default. Refer to the note below.
• 'nr_pieces' (str or int) – The number of pieces whose results are represented in the outputted chart. If present, the R script uses this to write “for X pieces” in the chart’s title. The default is None, which does not include this statement.

Note

About the 'token' Setting.

The 'token' setting is modified and sent forward to the R script, which uses it to determine the type of object portrayed on the chart. If the token is set to 'interval', the R script will print that “Intervals” are being displayed; if the token is set to a string ending with '-gram', the script will print that whatever-grams are being displayed; if the token is set to None, the script will print that “Objects” are being displayed.

run()

Produce the bar chart.

Returns:The pathname of the outputted PNG file containing a bar chart. Return type:string Raises:RuntimeError if the call to Rscript fails for any reason. The return code and command’s output are included as the RuntimeError.args[0] attribute.

lilypond Module

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