scamp_extensions.rhythm.metric_structure.MetricStructure

class scamp_extensions.rhythm.metric_structure.MetricStructure(*groups: Sequence[int, Sequence, MetricStructure], break_up_large_numbers: bool = False)

Bases: object

A highly flexible representation of a metric hierarchy, capable of describing both additive, multiplicative, and hybrid additive/multiplicative meters. Each MetricStructure describes a single layer of a metric grouping, and more complex hierarchies can be created by nesting metric structures inside of one another. For instance, a 2 + 3 + 2 additive meter is simply constructed with MetricStructure(2, 3, 2). If we want each of the eight pulses in this meter to be subdivided in three, we could accomplish this by nesting metric strucures like this: MetricStructure(MetricStructure(3, 3), MetricStructure(3, 3, 3), MetricStructure(3, 3)). Of course, this is quite a cumbersome expression, so it is usually much easier and more intuitive to use the from_string() class method: MetricStructure.from_string("(2+3+2)*3").

Note that instances of MetricStructure do not contain any information as to the speed of fastest subdivision; they simply describe how subdivisions come together to form beats, how beats come together to form meters, etc. A MetricStructure can be asked to calculate an array of indispensibility values (following the theories of Clarence Barlow), or an array of beat depths, showing how nested each pulse is within the underlying meter (i.e. the degree to which it is on or off the beat, and at what layer of structure).

Parameters:

• groups – list of additively combined groups. If all integers, then this is like a simple additive meter without considering subdivisions. For instance, (2, 4, 3) is like the time signature (2+4+3)/8. However, any component of this structure can instead be itself a MetricStructure, allowing for nesting. Nested structures can also be created by having one of the groups be a tuple, or tuple of tuples, etc.

• break_up_large_numbers – if True, groups with number greater than 3 are broken up into a sum of 2’s followed by one 3 if odd. This is the Barlow approach.

Methods

append(other_metric_structure[, in_place])	Adds a new group to this MetricStructure consisting of other_metric_structure.
extend(other_metric_structure[, in_place])	Extends this MetricStructure by appending all of the groups of other_metric_structure.
from_string(input_string[, ...])	Creates a MetricStructure from an appropriately formatted input string.
get_beat_depths()	Returns a list of integers representing how nested each beat/subdivision is within the metric structure.
get_indispensability_array([...])	Resolve the nested structure to a single one-dimensional indispensability array.
join(other_metric_structure)	Creates a new MetricStructure with two groups: this MetricStructure and other_metric_structure.
num_pulses()	The total number of pulses (smallest subdivisions) in this MetricStructure

classmethod from_string(input_string: str, break_up_large_numbers: bool = False) → MetricStructure

Creates a MetricStructure from an appropriately formatted input string. This is the simplest way of creating complex nested structures. For example, “3 * 2 + 5 + (2 + 3)” renders to MetricStructure(MetricStructure(2, 2, 2), 5, MetricStructure(2, 3)).

Parameters:

• input_string – input string consisting of integers, plus signs, multiplication signs, and parentheses

• break_up_large_numbers – see MetricStructure

get_beat_depths() → list[int]

Returns a list of integers representing how nested each beat/subdivision is within the metric structure. For example, MetricStructure(MetricStructure(2, 2, 2), 5, MetricStructure(2, 3)) will give us beat depths [0, 3, 2, 3, 2, 3, 1, 3, 3, 3, 3, 1, 3, 2, 3, 3]. Notice that the first beat has depth zero, and the start of each of the three main groups — (2, 2, 2), 5, and (3, 2) — has depth 1.

get_indispensability_array(upbeats_before_group_length: bool = True, normalize: bool = False) → list[INT_OR_FLOAT]

Resolve the nested structure to a single one-dimensional indispensability array. See Barlow’s “On Musiquantics” (http://clarlow.org/wp-content/uploads/2016/10/On-MusiquanticsA4.pdf) for more detail.

Parameters:

• upbeats_before_group_length – see description in flatten_beat_groups() above. Affects the result when there are groups of uneven length at some level of metric structure. To achieve the standard Barlowian result, set this to False. I think it works better as True, though.

• normalize – if True, indispensabilities range from 0 to 1. If false, they count up from 0.

Returns:

an indispensability array

num_pulses() → int

The total number of pulses (smallest subdivisions) in this MetricStructure

extend(other_metric_structure: MetricStructure, in_place: bool = True) → MetricStructure

Extends this MetricStructure by appending all of the groups of other_metric_structure. For example: MetricStructure(3, 3).extend(MetricStructure(2, 2)) results in MetricStructure(3, 3, 2, 2).

Parameters:

• other_metric_structure – another MetricStructure

• in_place – if True, alters this object; if false returns an extended copy.

append(other_metric_structure: MetricStructure, in_place: bool = True) → MetricStructure

Adds a new group to this MetricStructure consisting of other_metric_structure. For example, MetricStructure(3, 3).append(MetricStructure(2, 2)) results in MetricStructure(3, 3, MetricStructure(2, 2)).

Parameters:

• other_metric_structure – another MetricStructure

• in_place – if True, alters this object; if false returns an extended copy.

join(other_metric_structure) → MetricStructure

Creates a new MetricStructure with two groups: this MetricStructure and other_metric_structure. For example, MetricStructure(3, 3).join(MetricStructure(2, 2)) results in MetricStructure(MetricStructure(3, 3), MetricStructure(2, 2)).

Parameters:

other_metric_structure – another MetricStructure