Meter

class metertools.Meter(arg=None, decrease_durations_monotonically=True, preferred_boundary_depth=None)

A meter.

Meter models a common practice understanding of beats and other levels of rhythmic organization structured as a tree. Meter structure corresponds to the monotonically increasing sequence of factors in the numerator of a given time signature. Successively deeper levels of the tree divide time by successive factors.

Example 1. Duple meter:

>>> meter = metertools.Meter((2, 4))
>>> meter
Meter('(2/4 (1/4 1/4))')
>>> print(meter.pretty_rtm_format)
(2/4 (
    1/4
    1/4))
>>> graph(meter) 

2/4 comprises two beats.

Example 2. Triple meter:

>>> meter = metertools.Meter((3, 4))
>>> print(meter.pretty_rtm_format)
(3/4 (
    1/4
    1/4
    1/4))
>>> graph(meter) 

3/4 comprises three beats.

Example 3. Quadruple meter:

>>> meter = metertools.Meter((4, 4))
>>> meter
Meter('(4/4 (1/4 1/4 1/4 1/4))')
>>> print(meter.pretty_rtm_format)
(4/4 (
    1/4
    1/4
    1/4
    1/4))
>>> graph(meter) 

4/4 comprises four beats.

Example 3. Compound triple meter:

>>> meter = metertools.Meter((6, 8))
>>> print(meter.pretty_rtm_format)
(6/8 (
    (3/8 (
        1/8
        1/8
        1/8))
    (3/8 (
        1/8
        1/8
        1/8))))
>>> graph(meter) 

6/8 comprises two beats of three parts each.

Example 4. Another compound triple meter:

>>> meter = metertools.Meter((12, 8))
>>> print(meter.pretty_rtm_format)
(12/8 (
    (3/8 (
        1/8
        1/8
        1/8))
    (3/8 (
        1/8
        1/8
        1/8))
    (3/8 (
        1/8
        1/8
        1/8))
    (3/8 (
        1/8
        1/8
        1/8))))
>>> graph(meter) 

12/8 comprises four beats of three parts each.

Example 5. An asymmetric meter:

>>> meter = metertools.Meter((5, 4))
>>> print(meter.pretty_rtm_format)
(5/4 (
    (3/4 (
        1/4
        1/4
        1/4))
    (2/4 (
        1/4
        1/4))))
>>> graph(meter) 

5/4 comprises two unequal beats. By default unequal beats are arranged from greatest to least.

Example 6. Another asymmetric meter:

>>> meter = metertools.Meter((7, 4))
>>> print(meter.pretty_rtm_format)
(7/4 (
    (3/4 (
        1/4
        1/4
        1/4))
    (2/4 (
        1/4
        1/4))
    (2/4 (
        1/4
        1/4))))
>>> graph(meter) 

7/4 comprises three unequal beats. Beats are arranged from greatest to least by default.

Example 7. The same asymmetric meter structured differently:

>>> meter = metertools.Meter(
...     (7, 4),
...     decrease_durations_monotonically=False,
...     )
>>> print(meter.pretty_rtm_format)
(7/4 (
    (2/4 (
        1/4
        1/4))
    (2/4 (
        1/4
        1/4))
    (3/4 (
        1/4
        1/4
        1/4))))
>>> graph(meter) 

7/4 with beats arragned from least to greatest.

Example 8a. Meter interpreted by default as containing two compound beats:

>>> meter = metertools.Meter((6, 4))
>>> meter
Meter('(6/4 ((3/4 (1/4 1/4 1/4)) (3/4 (1/4 1/4 1/4))))')
>>> print(meter.pretty_rtm_format)
(6/4 (
    (3/4 (
        1/4
        1/4
        1/4))
    (3/4 (
        1/4
        1/4
        1/4))))
>>> graph(meter) 

Example 8b. Same meter customized to contain four compound beats:

>>> parser = rhythmtreetools.RhythmTreeParser()
>>> meter = metertools.Meter('(6/4 ((3/8 (1/8 1/8 1/8)) (3/8 (1/8 1/8 1/8)) (3/8 (1/8 1/8 1/8)) (3/8 (1/8 1/8 1/8))))')
>>> meter
Meter('(6/4 ((3/8 (1/8 1/8 1/8)) (3/8 (1/8 1/8 1/8)) (3/8 (1/8 1/8 1/8)) (3/8 (1/8 1/8 1/8))))')
>>> print(meter.pretty_rtm_format)
(6/4 (
    (3/8 (
        1/8
        1/8
        1/8))
    (3/8 (
        1/8
        1/8
        1/8))
    (3/8 (
        1/8
        1/8
        1/8))
    (3/8 (
        1/8
        1/8
        1/8))))
>>> graph(meter) 

Prime divisions greater than 3 are converted to sequences of 2 and 3 summing to that prime. Summands are arranged from greatest to least by default. This means that 5 becomes 3+2 and 7 becomes 3+2+2 in the examples above.

Lineage

digraph InheritanceGraph { graph [background=transparent, bgcolor=transparent, color=lightslategrey, fontname=Arial, outputorder=edgesfirst, overlap=prism, penwidth=2, rankdir=LR, root="__builtin__.object", splines=spline, style="dotted, rounded", truecolor=true]; node [colorscheme=pastel19, fontname=Arial, fontsize=12, penwidth=2, style="filled, rounded"]; edge [color=lightsteelblue2, penwidth=2]; subgraph cluster_abctools { graph [label=abctools]; "abjad.tools.abctools.AbjadObject.AbjadObject" [color=1, group=0, label=AbjadObject, shape=box]; "abjad.tools.abctools.AbjadObject.AbstractBase" [color=1, group=0, label=AbstractBase, shape=box]; "abjad.tools.abctools.AbjadObject.AbstractBase" -> "abjad.tools.abctools.AbjadObject.AbjadObject"; } subgraph cluster_metertools { graph [label=metertools]; "abjad.tools.metertools.Meter.Meter" [color=black, fontcolor=white, group=2, label=<<B>Meter</B>>, shape=box, style="filled, rounded"]; } subgraph cluster_builtins { graph [label=builtins]; "builtins.object" [color=2, group=1, label=object, shape=box]; } "abjad.tools.abctools.AbjadObject.AbjadObject" -> "abjad.tools.metertools.Meter.Meter"; "builtins.object" -> "abjad.tools.abctools.AbjadObject.AbstractBase"; }

Bases

Attribute summary

decrease_durations_monotonically Is true when meter divides large primes into collections of 2 and 3 that decrease monotonically.
denominator Gets denominator of meter.
depthwise_offset_inventory Gets depthwise offset inventory of meter.
duration Gets duration of meter.
fit_meters_to_expr(argument, meters[, ...]) Finds the best-matching sequence of meters for the offsets contained in argument.
generate_offset_kernel_to_denominator(...[, ...]) Generates a dictionary of all offsets in a meter up to denominator.
implied_time_signature Gets implied time signature of meter.
is_compound Is true when meter is compound.
is_simple Is true when meter is simple.
numerator Gets numerator of meter.
pair Gets pair of numerator and denominator of meter.
preferred_boundary_depth Gets preferred boundary depth of meter.
pretty_rtm_format Gets pretty RTM format of meter.
root_node Gets root node of meter.
rtm_format Gets RTM format of meter.
__eq__(argument) Is true when argument is a meter with an rtm format equal to that of this meter.
__format__([format_specification]) Formats meter.
__graph__(**keywords) Gets Graphviz format of meter.
__hash__() Hashes meter.
__iter__() Iterates meter.
__ne__(argument) Is true when Abjad object does not equal argument.
__repr__() Gets interpreter representation of Abjad object.
__str__() Gets string representation of meter.

Read-only properties

Meter.decrease_durations_monotonically

Is true when meter divides large primes into collections of 2 and 3 that decrease monotonically. Otherwise false.

Example 1. An asymmetric meter with beats arranged greatest to least:

>>> meter = metertools.Meter(
...     (7, 4),
...     decrease_durations_monotonically=True,
...     )
>>> meter.decrease_durations_monotonically
True
>>> print(meter.pretty_rtm_format)
(7/4 (
    (3/4 (
        1/4
        1/4
        1/4))
    (2/4 (
        1/4
        1/4))
    (2/4 (
        1/4
        1/4))))

This is default beahvior.

Example 2. The same asymmetric meter with unequal beats arranged least to greatest:

>>> meter = metertools.Meter(
...     (7, 4),
...     decrease_durations_monotonically=False,
...     )
>>> meter.decrease_durations_monotonically
False
>>> print(meter.pretty_rtm_format)
(7/4 (
    (2/4 (
        1/4
        1/4))
    (2/4 (
        1/4
        1/4))
    (3/4 (
        1/4
        1/4
        1/4))))

Returns true or false.

Meter.denominator

Gets denominator of meter.

>>> meter = metertools.Meter((7, 4))
>>> meter.denominator
4

Returns positive integer.

Meter.depthwise_offset_inventory

Gets depthwise offset inventory of meter.

>>> for depth, offsets in enumerate(
...     meter.depthwise_offset_inventory):
...     print(depth, offsets)
... 
0 (Offset(0, 1), Offset(7, 4))
1 (Offset(0, 1), Offset(3, 4), Offset(5, 4), Offset(7, 4))
2 (Offset(0, 1), Offset(1, 4), Offset(1, 2), Offset(3, 4), Offset(1, 1), Offset(5, 4), Offset(3, 2), Offset(7, 4))

Returns dictionary.

Meter.duration

Gets duration of meter.

>>> meter.duration
Duration(7, 4)

Returns duration.

Meter.implied_time_signature

Gets implied time signature of meter.

>>> metertools.Meter((4, 4)).implied_time_signature
TimeSignature((4, 4))

Returns time signature.

Meter.is_compound

Is true when meter is compound. Otherwise false.

Example 1. Compound meters written over 4:

>>> for numerator in range(1, 13):
...     meter = metertools.Meter((numerator, 4))
...     string = True if meter.is_compound else ''
...     print(str(meter), string)
... 
1/4 
2/4 
3/4 
4/4 
5/4 
6/4 True
7/4 
8/4 
9/4 True
10/4 
11/4 
12/4 True

Example 2. Compound meters written over 8:

>>> for numerator in range(1, 13):
...     meter = metertools.Meter((numerator, 8))
...     string = True if meter.is_compound else ''
...     print(str(meter), string)
... 
1/8 
2/8 
3/8 
4/8 
5/8 
6/8 True
7/8 
8/8 
9/8 True
10/8 
11/8 
12/8 True

Compound meters defined equal to those meters with a numerator divisible by 3 (but not equal to 3).

Returns true or false.

Meter.is_simple

Is true when meter is simple. Otherwise false.

Example 1. Simple meters written over 4:

>>> for numerator in range(1, 13):
...     meter = metertools.Meter((numerator, 4))
...     string = True if meter.is_simple else ''
...     print(str(meter), string)
... 
1/4 True
2/4 True
3/4 True
4/4 True
5/4 True
6/4 
7/4 True
8/4 True
9/4 
10/4 True
11/4 True
12/4 

Example 2. Simple meters written over 8:

>>> for numerator in range(1, 13):
...     meter = metertools.Meter((numerator, 8))
...     string = True if meter.is_simple else ''
...     print(str(meter), string)
... 
1/8 True
2/8 True
3/8 True
4/8 True
5/8 True
6/8 
7/8 True
8/8 True
9/8 
10/8 True
11/8 True
12/8 

Simple meters defined equal to those meters with a numerator not divisible by 3.

Meters with numerator equal to 3 are also defined as simple.

Returns true or false.

Meter.numerator

Gets numerator of meter.

>>> meter = metertools.Meter((7, 4))
>>> meter.numerator
7

Returns positive integer.

Meter.pair

Gets pair of numerator and denominator of meter.

>>> meter = metertools.Meter((6, 4))
>>> meter.pair
(6, 4)

Returns pair.

Meter.preferred_boundary_depth

Gets preferred boundary depth of meter.

Example 1. No preferred boundary depth:

>>> metertools.Meter((6, 8)).preferred_boundary_depth is None
True

Example 2. Customized preferred boundary depth:

>>> meter = metertools.Meter(
...     (6, 8),
...     preferred_boundary_depth=1,
...     )
>>> meter.preferred_boundary_depth
1

Used by mutate().rewrite_meter().

Defaults to none.

Set to integer or none.

Returns integer or none.

Meter.pretty_rtm_format

Gets pretty RTM format of meter.

>>> meter = metertools.Meter((7, 4))
>>> print(meter.pretty_rtm_format)
(7/4 (
    (3/4 (
        1/4
        1/4
        1/4))
    (2/4 (
        1/4
        1/4))
    (2/4 (
        1/4
        1/4))))

Returns string.

Meter.root_node

Gets root node of meter.

>>> meter = metertools.Meter((7, 4))
>>> print(format(meter.root_node))
rhythmtreetools.RhythmTreeContainer(
    children=(
        rhythmtreetools.RhythmTreeContainer(
            children=(
                rhythmtreetools.RhythmTreeLeaf(
                    preprolated_duration=durationtools.Duration(1, 4),
                    is_pitched=True,
                    ),
                rhythmtreetools.RhythmTreeLeaf(
                    preprolated_duration=durationtools.Duration(1, 4),
                    is_pitched=True,
                    ),
                rhythmtreetools.RhythmTreeLeaf(
                    preprolated_duration=durationtools.Duration(1, 4),
                    is_pitched=True,
                    ),
                ),
            preprolated_duration=mathtools.NonreducedFraction(3, 4),
            ),
        rhythmtreetools.RhythmTreeContainer(
            children=(
                rhythmtreetools.RhythmTreeLeaf(
                    preprolated_duration=durationtools.Duration(1, 4),
                    is_pitched=True,
                    ),
                rhythmtreetools.RhythmTreeLeaf(
                    preprolated_duration=durationtools.Duration(1, 4),
                    is_pitched=True,
                    ),
                ),
            preprolated_duration=mathtools.NonreducedFraction(2, 4),
            ),
        rhythmtreetools.RhythmTreeContainer(
            children=(
                rhythmtreetools.RhythmTreeLeaf(
                    preprolated_duration=durationtools.Duration(1, 4),
                    is_pitched=True,
                    ),
                rhythmtreetools.RhythmTreeLeaf(
                    preprolated_duration=durationtools.Duration(1, 4),
                    is_pitched=True,
                    ),
                ),
            preprolated_duration=mathtools.NonreducedFraction(2, 4),
            ),
        ),
    preprolated_duration=mathtools.NonreducedFraction(7, 4),
    )

Returns rhythm tree node.

Meter.rtm_format

Gets RTM format of meter.

>>> meter = metertools.Meter((7, 4))
>>> meter.rtm_format
'(7/4 ((3/4 (1/4 1/4 1/4)) (2/4 (1/4 1/4)) (2/4 (1/4 1/4))))'

Returns string.

Methods

Meter.generate_offset_kernel_to_denominator(denominator, normalize=True)

Generates a dictionary of all offsets in a meter up to denominator.

Keys are the offsets and the values are the normalized weights of those offsets.

>>> meter = metertools.Meter((4, 4))
>>> kernel = meter.generate_offset_kernel_to_denominator(8)
>>> for offset, weight in sorted(kernel.kernel.items()):
...     print('{!s}\t{!s}'.format(offset, weight))
... 
0	3/16
1/8	1/16
1/4	1/8
3/8	1/16
1/2	1/8
5/8	1/16
3/4	1/8
7/8	1/16
1	3/16

This is useful for testing how strongly a collection of offsets responds to a given meter.

Returns dictionary.

Class & static methods

static Meter.fit_meters_to_expr(argument, meters, denominator=32, discard_final_orphan_downbeat=True, maximum_run_length=None, starting_offset=None)

Finds the best-matching sequence of meters for the offsets contained in argument.

>>> meters = [(3, 4), (4, 4), (5, 4)]
>>> meters = [metertools.Meter(_) for _ in meters]

Example 1. Matches a series of hypothetical 4/4 measures:

>>> argument = [(0, 4), (4, 4), (8, 4), (12, 4), (16, 4)]
>>> for x in metertools.Meter.fit_meters_to_expr(
...     argument, meters):
...     print(x.implied_time_signature)
...
4/4
4/4
4/4
4/4

Example 2. Matches a series of hypothetical 5/4 measures:

>>> argument = [(0, 4), (3, 4), (5, 4), (10, 4), (15, 4), (20, 4)]
>>> for x in metertools.Meter.fit_meters_to_expr(
...     argument, meters):
...     print(x.implied_time_signature)
...
3/4
4/4
3/4
5/4
5/4

Coerces offsets from argument via MetricAccentKernel.count_offsets().

Coerces Meters from meters via MeterList.

Returns list.

Special methods

Meter.__eq__(argument)

Is true when argument is a meter with an rtm format equal to that of this meter. Otherwise false.

Returns true or false.

Meter.__format__(format_specification='')

Formats meter.

Example 1. Gets storage format of 7/4:

>>> meter = metertools.Meter((7, 4))
>>> print(format(meter))
metertools.Meter(
    '(7/4 ((3/4 (1/4 1/4 1/4)) (2/4 (1/4 1/4)) (2/4 (1/4 1/4))))'
    )

Set format_specification to ‘’ or ‘storage’. Interprets ‘’ equal to ‘storage’.

Returns string.

Meter.__graph__(**keywords)

Gets Graphviz format of meter.

Example 1. Graphs 7/4:

>>> meter = metertools.Meter((7, 4))
>>> meter_graph = meter.__graph__()
>>> graph(meter_graph) 

Returns Graphviz graph.

Meter.__hash__()

Hashes meter.

Meter.__iter__()

Iterates meter.

Example 1. Iterates 5/4:

>>> meter = metertools.Meter((5, 4))
>>> for x in meter:
...    x
...
(NonreducedFraction(0, 4), NonreducedFraction(1, 4))
(NonreducedFraction(1, 4), NonreducedFraction(2, 4))
(NonreducedFraction(2, 4), NonreducedFraction(3, 4))
(NonreducedFraction(0, 4), NonreducedFraction(3, 4))
(NonreducedFraction(3, 4), NonreducedFraction(4, 4))
(NonreducedFraction(4, 4), NonreducedFraction(5, 4))
(NonreducedFraction(3, 4), NonreducedFraction(5, 4))
(NonreducedFraction(0, 4), NonreducedFraction(5, 4))

Yields pairs.

(AbjadObject).__ne__(argument)

Is true when Abjad object does not equal argument. Otherwise false.

Returns true or false.

(AbjadObject).__repr__()

Gets interpreter representation of Abjad object.

Returns string.

Meter.__str__()

Gets string representation of meter.

Example 1. Gets string representation of meters over 8:

>>> for numerator in range(1, 9):
...     meter = metertools.Meter((numerator, 8))
...     print(str(meter))
... 
1/8
2/8
3/8
4/8
5/8
6/8
7/8
8/8

Returns string.