auto_rewrite_meter

auxjad.mutate.auto_rewrite_meter(container: Container, meter_list: list[Meter | TimeSignature] | None = None, *, prettify_rewrite_meter: bool = True, extract_trivial_tuplets: bool = True, fuse_across_groups_of_beats: bool = True, fuse_quadruple_meter: bool = True, fuse_triple_meter: bool = True, boundary_depth: int | None = None, maximum_dot_count: int | None = None, rewrite_tuplets: bool = True, merge_partial_tuplets: bool = True, split_quadruple_meter: bool = True) → None

Mutates an input container (of type abjad.Container or child class) in place and has no return value; this function takes every measure of a container, detects its time signature, and apply both abjad.Meter.rewrite_meter() and auxjad.mutate.prettify_rewrite_meter() to it.

Basic usage:

For this example, the following container will be mutated:

>>> staff = abjad.Staff(
...     r"c'16 d'8 e'16 f'8 g'4 a'4 b'8 "
...     r"c'16 d'4. e'16 f'8 g'4 a'16 b'16"
... )
>>> abjad.show(staff)

Abjad’s abjad.Meter.rewrite_meter() mutates an abjad.Selection of a measure, improving its notation.

>>> for measure in abjad.select(staff[:]).group_by_measure():
...     abjad.Meter.rewrite_meter(measure, abjad.Meter((4, 4)))
>>> abjad.show(staff)

This function mutates an abjad.Container (or child class), identifying the implied meters of each measure and applying both abjad.Meter.rewrite_meter() and auxjad.mutate.prettify_rewrite_meter() to it. See the documentation of the latter for a detailed explanation of what it does.

Applying auxjad.mutate.auto_rewrite_meter() to the same initial container shown in the first figure above outputs:

>>> staff = abjad.Staff(
...     r"c'16 d'8 e'16 f'8 g'4 a'4 b'8 "
...     r"c'16 d'4. e'16 f'8 g'4 a'16 b'16"
... )
>>> auxjad.mutate.auto_rewrite_meter(staff)
>>> abjad.show(staff)

Note

Auxjad automatically adds this function as an extension function to abjad.mutate. It can thus be used from either auxjad.mutate or abjad.mutate namespaces. Therefore, the two lines below are equivalent:

>>> auxjad.mutate.auto_rewrite_meter(staff)
>>> abjad.mutate.auto_rewrite_meter(staff)

Time signature changes:

It automatically handles time signature changes.

>>> staff = abjad.Staff(
...     r"c'16 d'8 e'16 f'8 g'4 a'4 b'8 "
...     r"\time 6/8 b'4 c''4 r4 "
... )
>>> auxjad.mutate.auto_rewrite_meter(staff)
>>> abjad.show(staff)

prettify_rewrite_meter:

By default, this function invokes both abjad.Meter.rewrite_meter() and auxjad.mutate.prettify_rewrite_meter().

>>> staff = abjad.Staff(
...     r"c'16 d'8 e'16 f'8 g'4 a'4 b'8 "
...     r"c'16 d'8 e'16 f'8 g'4 a'4 b'8"
... )
>>> auxjad.mutate.auto_rewrite_meter(staff)
>>> abjad.show(staff)

Set prettify_rewrite_meter to False to not invoke auxjad.mutate.prettify_rewrite_meter().

>>> staff = abjad.Staff(
...     r"c'16 d'8 e'16 f'8 g'4 a'4 b'8 "
...     r"c'16 d'4. e'16 f'8 g'4 a'16 b'16"
... )
>>> auxjad.mutate.auto_rewrite_meter(
...     staff,
...     prettify_rewrite_meter=False,
... )
>>> abjad.show(staff)

meter_list:

When no meter_list is supplied, this function detects the time signature of each measure and uses those when rewritting it:

>>> staff = abjad.Staff(
...     r"\time 7/4 c'8 d'4 e'4 f'4 g'4 a'4 b'4 c''8 "
...     r"\time 5/4 d''8 e''4 f''4 g''4 a''4 b''8"
... )
>>> auxjad.mutate.auto_rewrite_meter(staff)
>>> abjad.show(staff)

To use a custom list of meters (one for each measure), set meter_list to a list of abjad.Meter’s or abjad.TimeSignature’s.

>>> staff = abjad.Staff(
...     r"\time 7/4 c'8 d'4 e'4 f'4 g'4 a'4 b'4 c''8 "
...     r"\time 5/4 d''8 e''4 f''4 g''4 a''4 b''8"
... )
>>> meter_list = [abjad.Meter((7, 4), increase_monotonic=True),
...               abjad.Meter((5, 4), increase_monotonic=True),
...               ]
>>> auxjad.mutate.auto_rewrite_meter(staff, meter_list=meter_list)
>>> abjad.show(staff)

Number of measures:

This function handles a container with any number of measures and any number of time signature changes:

>>> staff = abjad.Staff(
...     r"\time 3/4 c'8 d'4 e'4 f'8 "
...     r"\time 5/8 g'4 a'4 r8 "
...     r"\time 6/8 b'4 c''4 r4 "
...     r"\time 4/4 d''8 e''4 f''8 g''16 a''4 r8."
... )
>>> auxjad.mutate.auto_rewrite_meter(staff)
>>> abjad.show(staff)

extract_trivial_tuplets:

By default, tuplets filled with rests or tied notes or chords are extracted:

>>> staff = abjad.Staff(
...     r"\times 2/3 {c'4 ~ c'8} \times 2/3 {d'8 r4} "
...     r"\times 2/3 {r8 r8 r8} \times 2/3 {<e' g'>8 ~ <e' g'>4}"
... )
>>> auxjad.mutate.auto_rewrite_meter(staff)
>>> abjad.show(staff)

Set extract_trivial_tuplets to False to disable this behaviour.

>>> staff = abjad.Staff(
...     r"\times 2/3 {c'4 ~ c'8} \times 2/3 {d'8 r4} "
...     r"\times 2/3 {r8 r8 r8} \times 2/3 {<e' g'>8 ~ <e' g'>4}"
... )
>>> auxjad.mutate.auto_rewrite_meter(
...     staff,
...     extract_trivial_tuplets=False,
... )
>>> abjad.show(staff)

merge_partial_tuplets:

By default, consecutive partial tuplets with the same ratio that sum up to an assignable duration will be merged together:

>>> staff = abjad.Staff(
...     r"\times 2/3 {c'2 d'1}"
...     r"\times 2/3 {e'2} \times 2/3 {f'1}"
... )
>>> auxjad.mutate.auto_rewrite_meter(staff)
>>> abjad.show(staff)

Set merge_partial_tuplets to False to disable this behaviour.

>>> staff = abjad.Staff(
...     r"\times 2/3 {c'2 d'1}"
...     r"\times 2/3 {e'2} \times 2/3 {f'1}"
... )
>>> auxjad.mutate.auto_rewrite_meter(
...     staff,
...     merge_partial_tuplets=False,
... )
>>> abjad.show(staff)

Note

This function also accepts the arguments boundary_depth, maximum_dot_count, and rewrite_tuplets, which are passed on to abjad.Meter.rewrite_meter(), and fuse_across_groups_of_beats, fuse_quadruple_meter, fuse_triple_meter, and split_quadruple_meter, which are passed on to auxjad.mutate.prettify_rewrite_meter(). merge_partial_tuplets is used to invoke auxjad.mutate.merge_partial_tuplets() See the documentation of these functions for more details on these arguments.

Warning

Setting boundary_depth to a value equal to or larger than 1 will automatically disable fuse_across_groups_of_beats, fuse_quadruple_meter, and fuse_triple_meter, regardless of their values. This is because when any of those arguments is True, auxjad.mutate.prettify_rewrite_meter() will fuse across beats, which goes against the purpose of using boundary_depth. Compare the results below. In the first case, simply applying auxjad.mutate.prettify_rewrite_meter() with no arguments results in some logical ties being tied across beats.

>>> staff = abjad.Staff(r"\time 4/4 c'4. d'4. e'4 f'8 g'4 a'4 b'4.")
>>> meter = abjad.Meter((4, 4))
>>> for measure in abjad.select(staff[:]).group_by_measure():
...     abjad.mutate.rewrite_meter(measure, meter, boundary_depth=1)
>>> for measure in abjad.select(staff[:]).group_by_measure():
...     auxjad.mutate.prettify_rewrite_meter(measure, meter)
>>> abjad.show(staff)

By automatically setting all fuse_across_groups_of_beats, fuse_quadruple_meter, and fuse_triple_meter` to ``False when boundary_depth is equal to or larger than 1, this function will not fuse those leaves against the required boundary depth.

>>> staff = abjad.Staff(r"\time 4/4 c'4. d'4. e'4 f'8 g'4 a'4 b'4.")
>>> auxjad.mutate.auto_rewrite_meter(staff, boundary_depth=1)
>>> abjad.show(staff)