MutationAgent

class agenttools.MutationAgent(client=None)

Mutation agent.

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() Respells named pitches in mutation client with flats.
respell_with_sharps() Respells named pitches in mutation client with sharps.
rewrite_meter(meter[, boundary_depth, ...]) Rewrites the contents of logical ties in an expression to match 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(argument) Transposes notes and chords in mutation client by argument.
__eq__(argument) Is true when ID of argument equals ID of Abjad object.
__format__([format_specification]) Formats Abjad object.
__hash__() Hashes Abjad object.
__ne__(argument) Is true when Abjad object does not equal argument.
__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.

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.

Extract tuplets:

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

Scales tuplet contents and then extracts 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.

Fuses in-score leaves:

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

Fuses 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.

Fuses 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.

Replaces 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.

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()

Respells named pitches in mutation client with flats.

Todo

Move to pitchtools package.

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()

Respells named pitches in mutation client with sharps.

Todo

Move to pitchtools package.

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)

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

Example 1. Rewrites 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. Rewrites 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. Scales 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. Scales 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. Scales 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. Scales 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. Scales 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. Scales 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. Scales 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. Scales 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. Scales 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. Scales 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. Scales 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. Scales 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. Scales 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.

Splits 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) 

Splits 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) 

Splits 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) 

Splits 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) 

Splits 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) 

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) 

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.

Swaps 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(argument)

Transposes notes and chords in mutation client by argument.

Todo

Move to pitchtools package.

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__(argument)

Is true when ID of argument 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__(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.