MutationAgent

class agenttools.MutationAgent(client=None)

Mutation agent.

Example 1. Creates mutation agent for last two notes in staff:

>>> staff = Staff("c'4 e'4 d'4 f'4")
>>> show(staff) 
>>> mutate(staff[2:])
MutationAgent(client=Selection([Note("d'4"), Note("f'4")]))

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_agenttools { graph [label=agenttools]; "abjad.tools.agenttools.MutationAgent.MutationAgent" [color=black, fontcolor=white, group=1, label=<<B>MutationAgent</B>>, shape=box, style="filled, rounded"]; } subgraph cluster_builtins { graph [label=builtins]; "builtins.object" [color=3, group=2, label=object, shape=box]; } "abjad.tools.abctools.AbjadObject.AbjadObject" -> "abjad.tools.agenttools.MutationAgent.MutationAgent"; "builtins.object" -> "abjad.tools.abctools.AbjadObject.AbstractBase"; }

Bases

Attribute summary

client Returns client of mutation agent.
copy([n, include_enclosing_containers]) Copies component and fractures crossing spanners.
eject_contents() Ejects contents from outside-of-score container.
extract([scale_contents]) Extracts mutation client from score.
fuse() Fuses mutation client.
replace(recipients) Replaces mutation client (and contents of mutation client) with recipients.
replace_measure_contents(new_contents) Replaces contents of measures in client with new_contents.
respell_with_flats() Respell named pitches in mutation client with flats:
respell_with_sharps() Respell named pitches in mutation client with sharps:
rewrite_meter(meter[, boundary_depth, ...]) Rewrite the contents of logical ties in an expression to match a meter.
scale(multiplier) Scales mutation client by multiplier.
splice(components[, direction, grow_spanners]) Splices components to the right or left of selection.
split(durations[, fracture_spanners, ...]) Splits component or selection by durations.
swap(container) Swaps mutation client for empty container.
transpose(expr) Transposes notes and chords in mutation client by expr.
__eq__(expr) Is true when ID of expr equals ID of Abjad object.
__format__([format_specification]) Formats Abjad object.
__hash__() Hashes Abjad object.
__ne__(expr) Is true when Abjad object does not equal expr.
__repr__() Gets interpreter representation of Abjad object.

Read-only properties

MutationAgent.client

Returns client of mutation agent.

Returns selection or component.

Methods

MutationAgent.copy(n=1, include_enclosing_containers=False)

Copies component and fractures crossing spanners.

Todo

Add examples.

Returns new component.

MutationAgent.eject_contents()

Ejects contents from outside-of-score container.

Example 1. Ejects leaves from container:

>>> container = Container("c'4 ~ c'4 d'4 ~ d'4")
>>> show(container) 

Returns container contents as a selection with spanners preserved:

>>> contents = mutate(container).eject_contents()
>>> contents
Selection([Note("c'4"), Note("c'4"), Note("d'4"), Note("d'4")])

Container contents can be safely added to a new container:

>>> staff = Staff(contents, context_name='RhythmicStaff')
>>> show(staff) 

New container is well formed:

>>> inspect_(staff).is_well_formed()
True

Old container is empty:

>>> container
Container()

Returns container contents as selection.

MutationAgent.extract(scale_contents=False)

Extracts mutation client from score.

Leaves children of mutation client in score.

Example 1. Extract tuplet:

>>> staff = Staff()
>>> time_signature = TimeSignature((3, 4))
>>> attach(time_signature, staff)
>>> staff.append(Tuplet((3, 2), "c'4 e'4"))
>>> staff.append(Tuplet((3, 2), "d'4 f'4"))
>>> hairpin = spannertools.Hairpin('p < f')
>>> selector = select().by_leaf(flatten=True)
>>> leaves = selector(staff)
>>> attach(hairpin, leaves)
>>> show(staff) 
>>> empty_tuplet = mutate(staff[-1]).extract()
>>> empty_tuplet = mutate(staff[0]).extract()
>>> show(staff) 

Example 2. Scale tuplet contents and then extract tuplet:

>>> staff = Staff()
>>> time_signature = TimeSignature((3, 4))
>>> attach(time_signature, staff)
>>> staff.append(Tuplet((3, 2), "c'4 e'4"))
>>> staff.append(Tuplet((3, 2), "d'4 f'4"))
>>> hairpin = spannertools.Hairpin('p < f')
>>> selector = select().by_leaf(flatten=True)
>>> leaves = selector(staff)
>>> attach(hairpin, leaves)
>>> show(staff) 
>>> empty_tuplet = mutate(staff[-1]).extract(
...     scale_contents=True)
>>> empty_tuplet = mutate(staff[0]).extract(
...     scale_contents=True)
>>> show(staff) 

Returns mutation client.

MutationAgent.fuse()

Fuses mutation client.

Example 1. Fuse in-score leaves:

>>> staff = Staff("c'8 d'8 e'8 f'8")
>>> show(staff) 
>>> mutate(staff[1:]).fuse()
[Note("d'4.")]
>>> show(staff) 

Example 2. Fuse parent-contiguous fixed-duration tuplets in selection:

>>> tuplet_1 = scoretools.FixedDurationTuplet(
...     Duration(2, 8), [])
>>> tuplet_1.extend("c'8 d'8 e'8")
>>> beam = spannertools.Beam()
>>> attach(beam, tuplet_1[:])
>>> duration = Duration(2, 16)
>>> tuplet_2 = scoretools.FixedDurationTuplet(duration, [])
>>> tuplet_2.extend("c'16 d'16 e'16")
>>> slur = spannertools.Slur()
>>> attach(slur, tuplet_2[:])
>>> staff = Staff([tuplet_1, tuplet_2])
>>> show(staff) 
>>> tuplets = staff[:]
>>> mutate(tuplets).fuse()
FixedDurationTuplet(Duration(3, 8), "c'8 d'8 e'8 c'16 d'16 e'16")
>>> show(staff) 

Returns new tuplet.

Fuses zero or more parent-contiguous tuplets.

Allows in-score tuplets.

Allows outside-of-score tuplets.

All tuplets must carry the same multiplier.

All tuplets must be of the same type.

Example 3. Fuse in-score measures:

>>> staff = Staff()
>>> staff.append(Measure((1, 4), "c'8 d'8"))
>>> staff.append(Measure((2, 8), "e'8 f'8"))
>>> slur = spannertools.Slur()
>>> leaves = select(staff).by_leaf()
>>> attach(slur, leaves)
>>> show(staff) 
>>> measures = staff[:]
>>> mutate(measures).fuse()
Measure((2, 4), "c'8 d'8 e'8 f'8")
>>> show(staff) 

Returns fused mutation client.

MutationAgent.replace(recipients)

Replaces mutation client (and contents of mutation client) with recipients.

Example 1. Replace in-score tuplet (and children of tuplet) with notes. Functions exactly the same as container setitem:

>>> tuplet_1 = Tuplet((2, 3), "c'4 d'4 e'4")
>>> tuplet_2 = Tuplet((2, 3), "d'4 e'4 f'4")
>>> staff = Staff([tuplet_1, tuplet_2])
>>> hairpin = spannertools.Hairpin('p < f')
>>> selector = select().by_leaf(flatten=True)
>>> leaves = selector(staff)
>>> attach(hairpin, leaves)
>>> slur = spannertools.Slur()
>>> attach(slur, leaves)
>>> show(staff) 
>>> notes = scoretools.make_notes(
...     "c' d' e' f' c' d' e' f'",
...     Duration(1, 16),
...     )
>>> mutate([tuplet_1]).replace(notes)
>>> show(staff) 

Preserves both hairpin and slur.

Returns none.

MutationAgent.replace_measure_contents(new_contents)

Replaces contents of measures in client with new_contents.

Example 1. Replaces skip-filled measures with notes:

>>> pairs = [(1, 8), (3, 16)]
>>> measures = scoretools.make_spacer_skip_measures(pairs)
>>> staff = Staff(measures)
>>> show(staff) 
>>> notes = [Note("c'16"), Note("d'16"), Note("e'16"), Note("f'16")]
>>> mutate(staff).replace_measure_contents(notes)
[Measure((1, 8), "c'16 d'16"), Measure((3, 16), "e'16 f'16 s1 * 1/16")]
>>> show(staff) 

Preserves duration of all measures.

Skips measures that are too small.

Pads extra space at end of measures with spacer skip.

Raises stop iteration if not enough measures.

Returns measures iterated.

MutationAgent.respell_with_flats()

Respell named pitches in mutation client with flats:

Example 1. Respells notes in staff:

>>> staff = Staff("c'8 cs'8 d'8 ef'8 e'8 f'8")
>>> show(staff) 
>>> mutate(staff).respell_with_flats()
>>> show(staff) 

Returns none.

MutationAgent.respell_with_sharps()

Respell named pitches in mutation client with sharps:

Example 1. Respells notes in staff:

>>> staff = Staff("c'8 cs'8 d'8 ef'8 e'8 f'8")
>>> show(staff) 
>>> mutate(staff).respell_with_sharps()
>>> show(staff) 

Returns none.

MutationAgent.rewrite_meter(meter, boundary_depth=None, initial_offset=None, maximum_dot_count=None, rewrite_tuplets=True, use_messiaen_style_ties=False)

Rewrite the contents of logical ties in an expression to match a meter.

Example 1. Rewrite the contents of a measure in a staff using the default meter for that measure’s time signature:

>>> parseable = "abj: | 2/4 c'2 ~ |"
>>> parseable += "| 4/4 c'32 d'2.. ~ d'16 e'32 ~ |"
>>> parseable += "| 2/4 e'2 |"
>>> staff = Staff(parseable)
>>> show(staff) 
>>> meter = metertools.Meter((4, 4))
>>> print(meter.pretty_rtm_format)
(4/4 (
    1/4
    1/4
    1/4
    1/4))
>>> mutate(staff[1][:]).rewrite_meter(meter)
>>> show(staff) 

Example 2. Rewrite the contents of a measure in a staff using a custom meter:

>>> staff = Staff(parseable)
>>> show(staff) 
>>> rtm = '(4/4 ((2/4 (1/4 1/4)) (2/4 (1/4 1/4))))'
>>> meter = metertools.Meter(rtm)
>>> print(meter.pretty_rtm_format) 
(4/4 (
    (2/4 (
        1/4
        1/4))
    (2/4 (
        1/4
        1/4))))
>>> mutate(staff[1][:]).rewrite_meter(meter)
>>> show(staff) 

Example 3. Limit the maximum number of dots per leaf using maximum_dot_count:

>>> parseable = "abj: | 3/4 c'32 d'8 e'8 fs'4... |"
>>> measure = parse(parseable)
>>> show(measure) 

Without constraining the maximum_dot_count:

>>> mutate(measure[:]).rewrite_meter(measure)
>>> show(measure) 

Constraining the maximum_dot_count to 2:

>>> measure = parse(parseable)
>>> mutate(measure[:]).rewrite_meter(
...     measure,
...     maximum_dot_count=2,
...     )
>>> show(measure) 

Constraining the maximum_dot_count to 1:

>>> measure = parse(parseable)
>>> mutate(measure[:]).rewrite_meter(
...     measure,
...     maximum_dot_count=1,
...     )
>>> show(measure) 

Constraining the maximum_dot_count to 0:

>>> measure = parse(parseable)
>>> mutate(measure[:]).rewrite_meter(
...     measure,
...     maximum_dot_count=0,
...     )
>>> show(measure) 

Example 4. Split logical ties at different depths of the Meter, if those logical ties cross any offsets at that depth, but do not also both begin and end at any of those offsets.

Consider the default meter for 9/8:

>>> meter = metertools.Meter((9, 8))
>>> print(meter.pretty_rtm_format)
(9/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))))

We can establish that meter without specifying a boundary_depth:

>>> parseable = "abj: | 9/8 c'2 d'2 e'8 |"
>>> measure = parse(parseable)
>>> show(measure) 
>>> mutate(measure[:]).rewrite_meter(measure)
>>> show(measure) 

With a boundary_depth of 1, logical ties which cross any offsets created by nodes with a depth of 1 in this Meter’s rhythm tree - i.e. 0/8, 3/8, 6/8 and 9/8 - which do not also begin and end at any of those offsets, will be split:

>>> measure = parse(parseable)
>>> mutate(measure[:]).rewrite_meter(
...     measure,
...     boundary_depth=1,
...     )
>>> show(measure) 

For this 9/8 meter, and this input notation, A boundary_depth of 2 causes no change, as all logical ties already align to multiples of 1/8:

>>> measure = parse(parseable)
>>> mutate(measure[:]).rewrite_meter(
...     measure,
...     boundary_depth=2,
...     )
>>> show(measure) 

Example 5. Comparison of 3/4 and 6/8, at boundary_depths of 0 and 1:

>>> triple = "abj: | 3/4 2 4 || 3/4 4 2 || 3/4 4. 4. |"
>>> triple += "| 3/4 2 ~ 8 8 || 3/4 8 8 ~ 2 |"
>>> duples = "abj: | 6/8 2 4 || 6/8 4 2 || 6/8 4. 4. |"
>>> duples += "| 6/8 2 ~ 8 8 || 6/8 8 8 ~ 2 |"
>>> score = Score([Staff(triple), Staff(duples)])

In order to see the different time signatures on each staff, we need to move some engravers from the Score context to the Staff context:

>>> engravers = [
...     'Timing_translator',
...     'Time_signature_engraver',
...     'Default_bar_line_engraver',
...     ]
>>> score.remove_commands.extend(engravers)
>>> score[0].consists_commands.extend(engravers)
>>> score[1].consists_commands.extend(engravers)
>>> show(score) 

Here we establish a meter without specifying any boundary depth:

>>> for measure in iterate(score).by_class(scoretools.Measure):
...     mutate(measure[:]).rewrite_meter(measure)
... 
>>> show(score) 

Here we re-establish meter at a boundary depth of 1:

>>> for measure in iterate(score).by_class(scoretools.Measure):
...     mutate(measure[:]).rewrite_meter(
...         measure,
...         boundary_depth=1,
...         )
... 
>>> show(score) 

Note that the two time signatures are much more clearly disambiguated above.

Example 6. Establishing meter recursively in measures with nested tuplets:

>>> parseable = "abj: | 4/4 c'16 ~ c'4 d'8. ~ "
>>> parseable += "2/3 { d'8. ~ 3/5 { d'16 e'8. f'16 ~ } } "
>>> parseable += "f'4 |"
>>> measure = parse(parseable)
>>> show(measure) 

When establishing a meter on a selection of components which contain containers, like Tuplets or Containers, metertools.rewrite_meter() will recurse into those containers, treating them as measures whose time signature is derived from the preprolated preprolated_duration of the container’s contents:

>>> mutate(measure[:]).rewrite_meter(
...     measure,
...     boundary_depth=1,
...     )
>>> show(measure) 

Example 7a. Default rewrite behavior doesn’t subdivide the first note in this measure because the first note in the measure starts at the beginning of a level-0 beat in meter:

>>> measure = Measure((6, 8), "c'4.. c'16 ~ c'4")
>>> meter = metertools.Meter((6, 8))
>>> mutate(measure[:]).rewrite_meter(meter)
>>> show(measure) 

Example 7b. Setting boundary depth to 1 subdivides the first note in this measure:

>>> measure = Measure((6, 8), "c'4.. c'16 ~ c'4")
>>> meter = metertools.Meter((6, 8))
>>> mutate(measure[:]).rewrite_meter(meter, boundary_depth=1)
>>> show(measure) 

Example 7c. Another way of doing this is by setting preferred boundary depth on the meter itself:

>>> measure = Measure((6, 8), "c'4.. c'16 ~ c'4")
>>> meter = metertools.Meter(
...     (6, 8),
...     preferred_boundary_depth=1,
...     )
>>> mutate(measure[:]).rewrite_meter(meter)
>>> show(measure) 

This makes it possible to divide different meters in different ways.

Example 8. Uses Messiaen-style ties:

>>> measure = Measure((4, 4), "c'4. c'4. c'4")
>>> show(measure) 
>>> meter = metertools.Meter((4, 4))
>>> mutate(measure[:]).rewrite_meter(
...     meter,
...     boundary_depth=1,
...     use_messiaen_style_ties=True,
...     )
>>> show(measure) 

Example 9a. Rewrites notes and tuplets:

>>> measure = Measure((6, 4), [
...     Note("c'4."),
...     Tuplet((6, 7), "c'4. r16"),
...     Tuplet((6, 7), "r16 c'4."),
...     Note("c'4."),
...     ])
>>> string = r"c'8 ~ c'8 ~ c'8 \times 6/7 { c'4. r16 }"
>>> string += r" \times 6/7 { r16 c'4. } c'8 ~ c'8 ~ c'8"
>>> measure = Measure((6, 4), string)
>>> show(measure) 
>>> meter = metertools.Meter((6, 4))
>>> mutate(measure[:]).rewrite_meter(
...     meter,
...     boundary_depth=1,
...     )
>>> show(measure) 

The tied note rewriting is good while the tuplet rewriting could use some adjustment.

Example 9b. Rewrites notes but not tuplets:

>>> measure = Measure((6, 4), [
...     Note("c'4."),
...     Tuplet((6, 7), "c'4. r16"),
...     Tuplet((6, 7), "r16 c'4."),
...     Note("c'4."),
...     ])
>>> string = r"c'8 ~ c'8 ~ c'8 \times 6/7 { c'4. r16 }"
>>> string += r" \times 6/7 { r16 c'4. } c'8 ~ c'8 ~ c'8"
>>> measure = Measure((6, 4), string)
>>> show(measure) 
>>> meter = metertools.Meter((6, 4))
>>> mutate(measure[:]).rewrite_meter(
...     meter,
...     boundary_depth=1,
...     rewrite_tuplets=False,
...     )
>>> show(measure) 

Operates in place and returns none.

MutationAgent.scale(multiplier)

Scales mutation client by multiplier.

Example 1a. Scale note duration by dot-generating multiplier:

>>> staff = Staff("c'8 ( d'8 e'8 f'8 )")
>>> show(staff) 
>>> mutate(staff[1]).scale(Multiplier(3, 2))
>>> show(staff) 

Example 1b. Scale nontrivial logical tie by dot-generating multiplier:

>>> staff = Staff(r"c'8 \accent ~ c'8 d'8")
>>> time_signature = TimeSignature((3, 8))
>>> attach(time_signature, staff)
>>> show(staff) 
>>> logical_tie = inspect_(staff[0]).get_logical_tie()
>>> logical_tie = mutate(logical_tie).scale(Multiplier(3, 2))
>>> show(staff) 

Example 1c. Scale container by dot-generating multiplier:

>>> container = Container(r"c'8 ( d'8 e'8 f'8 )")
>>> show(container) 
>>> mutate(container).scale(Multiplier(3, 2))
>>> show(container) 

Example 2a. Scale note by tie-generating multiplier:

>>> staff = Staff("c'8 ( d'8 e'8 f'8 )")
>>> show(staff) 
>>> mutate(staff[1]).scale(Multiplier(5, 4))
>>> show(staff) 

Example 2b. Scale nontrivial logical tie by tie-generating multiplier:

>>> staff = Staff(r"c'8 \accent ~ c'8 d'16")
>>> time_signature = TimeSignature((5, 16))
>>> attach(time_signature, staff)
>>> show(staff) 
>>> logical_tie = inspect_(staff[0]).get_logical_tie()
>>> logical_tie = mutate(logical_tie).scale(Multiplier(5, 4))
>>> show(staff) 

Example 2c. Scale container by tie-generating multiplier:

>>> container = Container(r"c'8 ( d'8 e'8 f'8 )")
>>> show(container) 
>>> mutate(container).scale(Multiplier(5, 4))
>>> show(container) 

Example 3a. Scale note by tuplet-generating multiplier:

>>> staff = Staff("c'8 ( d'8 e'8 f'8 )")
>>> show(staff) 
>>> mutate(staff[1]).scale(Multiplier(2, 3))
>>> show(staff) 

Example 3b. Scale trivial logical tie by tuplet-generating multiplier:

>>> staff = Staff(r"c'8 \accent")
>>> show(staff) 
>>> logical_tie = inspect_(staff[0]).get_logical_tie()
>>> logical_tie = mutate(logical_tie).scale(Multiplier(4, 3))
>>> show(staff) 

Example 3c. Scale container by tuplet-generating multiplier:

>>> container = Container(r"c'8 ( d'8 e'8 f'8 )")
>>> show(container) 
>>> mutate(container).scale(Multiplier(4, 3))
>>> show(container) 

Example 4. Scale note by tie- and tuplet-generating multiplier:

>>> staff = Staff("c'8 ( d'8 e'8 f'8 )")
>>> show(staff) 
>>> mutate(staff[1]).scale(Multiplier(5, 6))
>>> show(staff) 

Example 5. Scale note carrying LilyPond multiplier:

>>> note = Note("c'8")
>>> attach(Multiplier(1, 2), note)
>>> show(note) 
>>> mutate(note).scale(Multiplier(5, 3))
>>> show(note) 

Example 6. Scale tuplet:

>>> staff = Staff()
>>> time_signature = TimeSignature((4, 8))
>>> attach(time_signature, staff)
>>> tuplet = scoretools.Tuplet((4, 5), [])
>>> tuplet.extend("c'8 d'8 e'8 f'8 g'8")
>>> staff.append(tuplet)
>>> show(staff) 
>>> mutate(tuplet).scale(Multiplier(2))
>>> show(staff) 

Example 7. Scale fixed-duration tuplet:

>>> staff = Staff()
>>> time_signature = TimeSignature((4, 8))
>>> attach(time_signature, staff)
>>> tuplet = scoretools.FixedDurationTuplet((4, 8), [])
>>> tuplet.extend("c'8 d'8 e'8 f'8 g'8")
>>> staff.append(tuplet)
>>> show(staff) 
>>> mutate(tuplet).scale(Multiplier(2))
>>> show(staff) 

Returns none.

MutationAgent.splice(components, direction=Right, grow_spanners=True)

Splices components to the right or left of selection.

Todo

Add examples.

Returns list of components.

MutationAgent.split(durations, fracture_spanners=False, cyclic=False, tie_split_notes=True, use_messiaen_style_ties=False)

Splits component or selection by durations.

Example 1. Split leaves:

>>> staff = Staff("c'8 e' d' f' c' e' d' f'")
>>> leaves = staff[:]
>>> hairpin = spannertools.Hairpin(descriptor='p < f')
>>> attach(hairpin, leaves)
>>> override(staff).dynamic_line_spanner.staff_padding = 3
>>> show(staff) 
>>> durations = [Duration(3, 16), Duration(7, 32)]
>>> result = mutate(leaves).split(
...     durations,
...     tie_split_notes=False,
...     )
>>> show(staff) 

Example 2. Split leaves and fracture crossing spanners:

>>> staff = Staff("c'8 e' d' f' c' e' d' f'")
>>> hairpin = spannertools.Hairpin(descriptor='p < f')
>>> attach(hairpin, staff[:])
>>> override(staff).dynamic_line_spanner.staff_padding = 3
>>> show(staff) 
>>> durations = [Duration(3, 16), Duration(7, 32)]
>>> leaves = staff[:]
>>> result = mutate(leaves).split(
...     durations,
...     fracture_spanners=True,
...     tie_split_notes=False,
...     )
>>> show(staff) 

Example 3. Split leaves cyclically:

>>> staff = Staff("c'8 e' d' f' c' e' d' f'")
>>> leaves = staff[:]
>>> hairpin = spannertools.Hairpin(descriptor='p < f')
>>> attach(hairpin, leaves)
>>> override(staff).dynamic_line_spanner.staff_padding = 3
>>> show(staff) 
>>> durations = [Duration(3, 16), Duration(7, 32)]
>>> result = mutate(leaves).split(
...     durations,
...     cyclic=True,
...     tie_split_notes=False,
...     )
>>> show(staff) 

Example 4. Split leaves cyclically and fracture spanners:

>>> staff = Staff("c'8 e' d' f' c' e' d' f'")
>>> leaves = staff[:]
>>> hairpin = spannertools.Hairpin(descriptor='p < f')
>>> attach(hairpin, leaves)
>>> override(staff).dynamic_line_spanner.staff_padding = 3
>>> show(staff) 
>>> durations = [Duration(3, 16), Duration(7, 32)]
>>> result = mutate(leaves).split(
...     durations,
...     cyclic=True,
...     fracture_spanners=True,
...     tie_split_notes=False,
...     )
>>> show(staff) 

Example 5. Split tupletted leaves and fracture crossing spanners:

>>> staff = Staff()
>>> staff.append(Tuplet((2, 3), "c'4 d' e'"))
>>> staff.append(Tuplet((2, 3), "c'4 d' e'"))
>>> selector = select().by_leaf(flatten=True)
>>> leaves = selector(staff)
>>> slur = spannertools.Slur()
>>> attach(slur, leaves)
>>> show(staff) 
>>> durations = [Duration(1, 4)]
>>> result = mutate(leaves).split(
...     durations,
...     fracture_spanners=True,
...     tie_split_notes=False,
...     )
>>> show(staff) 

Example 6a. Splits leaves cyclically and ties split notes:

>>> staff = Staff("c'1 d'1")
>>> hairpin = spannertools.Hairpin(descriptor='p < f')
>>> attach(hairpin, staff[:])
>>> override(staff).dynamic_line_spanner.staff_padding = 3
>>> show(staff) 
>>> durations = [Duration(3, 4)]
>>> result = mutate(staff[:]).split(
...     durations,
...     cyclic=True,
...     fracture_spanners=False,
...     tie_split_notes=True,
...     )
>>> show(staff) 

Example 6b. As above but with Messiaen-style ties:

>>> staff = Staff("c'1 d'1")
>>> hairpin = spannertools.Hairpin(descriptor='p < f')
>>> attach(hairpin, staff[:])
>>> override(staff).dynamic_line_spanner.staff_padding = 3
>>> durations = [Duration(3, 4)]
>>> result = mutate(staff[:]).split(
...     durations,
...     cyclic=True,
...     fracture_spanners=False,
...     tie_split_notes=True,
...     use_messiaen_style_ties=True,
...     )
>>> show(staff) 

Returns list of selections.

MutationAgent.swap(container)

Swaps mutation client for empty container.

Example 1. Swap measures for tuplet:

>>> staff = Staff()
>>> staff.append(Measure((3, 4), "c'4 d'4 e'4"))
>>> staff.append(Measure((3, 4), "d'4 e'4 f'4"))
>>> selector = select().by_leaf(flatten=True)
>>> leaves = selector(staff)
>>> hairpin = spannertools.Hairpin('p < f')
>>> attach(hairpin, leaves)
>>> measures = staff[:]
>>> slur = spannertools.Slur()
>>> attach(slur, leaves)
>>> show(staff) 
>>> measures = staff[:]
>>> tuplet = Tuplet(Multiplier(2, 3), [])
>>> tuplet.preferred_denominator = 4
>>> mutate(measures).swap(tuplet)
>>> show(staff) 

Returns none.

MutationAgent.transpose(expr)

Transposes notes and chords in mutation client by expr.

Example 1. Transposes notes and chords in staff:

>>> staff = Staff()
>>> staff.append(Measure((4, 4), "c'4 d'4 e'4 r4"))
>>> staff.append(Measure((3, 4), "d'4 e'4 <f' a' c''>4"))
>>> show(staff) 
>>> mutate(staff).transpose("+m3")
>>> show(staff) 

Returns none.

Special methods

(AbjadObject).__eq__(expr)

Is true when ID of expr equals ID of Abjad object. Otherwise false.

Returns true or false.

(AbjadObject).__format__(format_specification='')

Formats Abjad object.

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

Returns string.

(AbjadObject).__hash__()

Hashes Abjad object.

Required to be explicitly redefined on Python 3 if __eq__ changes.

Returns integer.

(AbjadObject).__ne__(expr)

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

Returns true or false.

(AbjadObject).__repr__()

Gets interpreter representation of Abjad object.

Returns string.