MutationAgent

class agenttools.MutationAgent(client=None)

Mutation agent.

>>> import abjad
>>> import pytest

Creates mutation agent for last two notes in staff:

>>> staff = abjad.Staff("c'4 e'4 d'4 f'4")
>>> show(staff) 
>>> abjad.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.
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 mutation client by durations.
swap(container) Swaps mutation client for empty container.
transpose(argument) Transposes notes and chords in mutation client by argument.
wrap(container) Wraps mutation client in empty container.
__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.

Copies explicit clefs:

>>> staff = abjad.Staff("c'8 cs'8 d'8 ef'8 e'8 f'8 fs'8 g'8")
>>> clef = abjad.Clef('treble')
>>> abjad.attach(clef, staff[0])
>>> clef = abjad.Clef('bass')
>>> abjad.attach(clef, staff[4])
>>> copied_notes = abjad.mutate(staff[:2]).copy()
>>> staff.extend(copied_notes)
>>> show(staff) 

Does not copy implicit clefs:

>>> staff = abjad.Staff("c'8 cs'8 d'8 ef'8 e'8 f'8 fs'8 g'8")
>>> clef = abjad.Clef('treble')
>>> abjad.attach(clef, staff[0])
>>> clef = abjad.Clef('bass')
>>> abjad.attach(clef, staff[4])
>>> copied_notes = abjad.mutate(staff[2:4]).copy()
>>> staff.extend(copied_notes)

Returns new component.

MutationAgent.eject_contents()

Ejects contents from outside-of-score container.

Ejects leaves from container:

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

Returns container contents as a selection with spanners preserved:

>>> contents = abjad.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 = abjad.Staff(contents, context_name='RhythmicStaff')
>>> show(staff) 

New container is well formed:

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

Scales tuplet contents and then extracts tuplet:

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

Returns mutation client.

MutationAgent.fuse()

Fuses mutation client.

Fuses in-score leaves:

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

Fuses parent-contiguous tuplets in selection:

>>> tuplet_1 = abjad.Tuplet((2, 3), "c'8 d' e'")
>>> beam = abjad.Beam()
>>> abjad.attach(beam, tuplet_1[:])
>>> tuplet_2 = abjad.Tuplet((2, 3), "c'16 d' e'")
>>> slur = abjad.Slur()
>>> abjad.attach(slur, tuplet_2[:])
>>> staff = abjad.Staff([tuplet_1, tuplet_2])
>>> show(staff) 
>>> tuplets = staff[:]
>>> abjad.mutate(tuplets).fuse()
Tuplet(Multiplier(2, 3), "c'8 d'8 e'8 c'16 d'16 e'16")
>>> show(staff) 

Returns new tuplet in selection.

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 = abjad.Staff()
>>> staff.append(abjad.Measure((1, 4), "c'8 d'8"))
>>> staff.append(abjad.Measure((2, 8), "e'8 f'8"))
>>> slur = abjad.Slur()
>>> leaves = abjad.select(staff).by_leaf()
>>> abjad.attach(slur, leaves)
>>> show(staff) 
>>> measures = staff[:]
>>> abjad.mutate(measures).fuse()
Measure((2, 4), "c'8 d'8 e'8 f'8")
>>> show(staff) 

Returns selection.

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 = abjad.Tuplet((2, 3), "c'4 d'4 e'4")
>>> tuplet_2 = abjad.Tuplet((2, 3), "d'4 e'4 f'4")
>>> staff = abjad.Staff([tuplet_1, tuplet_2])
>>> hairpin = abjad.Hairpin('p < f')
>>> selector = abjad.select().by_leaf(flatten=True)
>>> leaves = selector(staff)
>>> abjad.attach(hairpin, leaves)
>>> slur = abjad.Slur()
>>> abjad.attach(slur, leaves)
>>> show(staff) 
>>> maker = abjad.NoteMaker()
>>> notes = maker("c' d' e' f' c' d' e' f'", (1, 16))
>>> abjad.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:

>>> maker = abjad.MeasureMaker()
>>> measures = maker([(1, 8), (3, 16)])
>>> staff = abjad.Staff(measures)
>>> show(staff) 
>>> notes = [
...     abjad.Note("c'16"),
...     abjad.Note("d'16"),
...     abjad.Note("e'16"),
...     abjad.Note("f'16"),
...     ]
>>> abjad.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.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.

Rewrites the contents of a measure in a staff using the default meter for that measure’s time signature:

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

Rewrites the contents of a measure in a staff using a custom meter:

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

Limit the maximum number of dots per leaf using maximum_dot_count:

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

Without constraining the maximum_dot_count:

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

Constraining the maximum_dot_count to 2:

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

Constraining the maximum_dot_count to 1:

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

Constraining the maximum_dot_count to 0:

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

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 = abjad.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:

>>> string = "abj: | 9/8 c'2 d'2 e'8 |"
>>> measure = abjad.parse(string)
>>> show(measure) 
>>> abjad.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 = abjad.parse(string)
>>> abjad.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 = abjad.parse(string)
>>> abjad.mutate(measure[:]).rewrite_meter(
...     measure,
...     boundary_depth=2,
...     )
>>> show(measure) 

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 = abjad.Score([
...     abjad.Staff(triple),
...     abjad.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 abjad.iterate(score).by_class(abjad.Measure):
...     abjad.mutate(measure[:]).rewrite_meter(measure)
... 
>>> show(score) 

Here we reestablish meter at a boundary depth of 1:

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

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

Establishing meter recursively in measures with nested tuplets:

>>> string = "abj: | 4/4 c'16 ~ c'4 d'8. ~ "
>>> string += "2/3 { d'8. ~ 3/5 { d'16 e'8. f'16 ~ } } "
>>> string += "f'4 |"
>>> measure = abjad.parse(string)
>>> 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:

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

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 = abjad.Measure((6, 8), "c'4.. c'16 ~ c'4")
>>> meter = abjad.Meter((6, 8))
>>> abjad.mutate(measure[:]).rewrite_meter(meter)
>>> show(measure) 

Setting boundary depth to 1 subdivides the first note in this measure:

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

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

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

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

Uses Messiaen-style ties:

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

Rewrites notes and tuplets:

>>> measure = abjad.Measure((6, 4), [
...     abjad.Note("c'4."),
...     abjad.Tuplet((6, 7), "c'4. r16"),
...     abjad.Tuplet((6, 7), "r16 c'4."),
...     abjad.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 = abjad.Measure((6, 4), string)
>>> show(measure) 
>>> meter = abjad.Meter((6, 4))
>>> abjad.mutate(measure[:]).rewrite_meter(
...     meter,
...     boundary_depth=1,
...     )
>>> show(measure) 

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

Rewrites notes but not tuplets:

>>> measure = abjad.Measure((6, 4), [
...     abjad.Note("c'4."),
...     abjad.Tuplet((6, 7), "c'4. r16"),
...     abjad.Tuplet((6, 7), "r16 c'4."),
...     abjad.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 = abjad.Measure((6, 4), string)
>>> show(measure) 
>>> meter = abjad.Meter((6, 4))
>>> abjad.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.

Scales note duration by dot-generating multiplier:

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

Scales nontrivial logical tie by dot-generating multiplier:

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

Scales container by dot-generating multiplier:

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

Scales note by tie-generating multiplier:

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

Scales nontrivial logical tie by tie-generating multiplier:

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

Scales container by tie-generating multiplier:

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

Scales note by tuplet-generating multiplier:

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

Scales trivial logical tie by tuplet-generating multiplier:

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

Scales container by tuplet-generating multiplier:

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

Scales note by tie- and tuplet-generating multiplier:

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

Scales note carrying LilyPond multiplier:

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

Scales tuplet:

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

Scales tuplet:

>>> staff = abjad.Staff()
>>> tuplet = abjad.Tuplet((4, 5), "c'8 d'8 e'8 f'8 g'8")
>>> staff.append(tuplet)
>>> time_signature = abjad.TimeSignature((4, 8))
>>> leaf = abjad.inspect(staff).get_leaf(0)
>>> abjad.attach(time_signature, leaf)
>>> show(staff) 
>>> abjad.mutate(tuplet).scale(abjad.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 mutation client by durations.

Splits leaves:

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

Splits leaves and fracture crossing spanners:

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

Splits leaves cyclically:

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

Splits leaves cyclically and fracture spanners:

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

Splits tupletted leaves and fracture crossing spanners:

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

Splits leaves cyclically and ties split notes:

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

As above but with Messiaen-style ties:

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

Splits custom voice and preserves context name:

>>> voice = abjad.Voice(
...     "c'4 d' e' f'",
...     context_name='CustomVoice',
...     name='1',
...     )
>>> staff = abjad.Staff([voice])
>>> hairpin = abjad.Hairpin(descriptor='p < f')
>>> abjad.attach(hairpin, voice[:])
>>> abjad.override(staff).dynamic_line_spanner.staff_padding = 3
>>> show(staff) 
>>> durations = [(1, 8)]
>>> result = abjad.mutate(staff[:]).split(
...     durations,
...     cyclic=True,
...     fracture_spanners=False,
...     tie_split_notes=True,
...     )
>>> show(staff) 
>>> for voice in staff:
...     voice
...
Voice("c'8 ~", context_name='CustomVoice', name='1')
Voice("c'8", context_name='CustomVoice', name='1')
Voice("d'8 ~", context_name='CustomVoice', name='1')
Voice("d'8", context_name='CustomVoice', name='1')
Voice("e'8 ~", context_name='CustomVoice', name='1')
Voice("e'8", context_name='CustomVoice', name='1')
Voice("f'8 ~", context_name='CustomVoice', name='1')
Voice("f'8", context_name='CustomVoice', name='1')

Splits parallel container:

>>> voice_1 = abjad.Voice(
...     "e''4 ( es'' f'' fs'' )",
...     name='Voice 1',
...     )
>>> voice_2 = abjad.Voice(
...     r"c'4 \p \< cs' d' ds' \f",
...     name='Voice 2',
...     )
>>> abjad.override(voice_1).stem.direction = Up
>>> abjad.override(voice_1).slur.direction = Up
>>> container = abjad.Container(
...     [voice_1, voice_2],
...     is_simultaneous=True,
...     )
>>> abjad.override(voice_2).stem.direction = Down
>>> staff = abjad.Staff([container])
>>> show(staff) 
>>> durations = [(3, 8)]
>>> result = abjad.mutate(container).split(
...     durations,
...     cyclic=False,
...     fracture_spanners=False,
...     tie_split_notes=True,
...     )
>>> show(staff) 
>>> f(staff)
\new Staff {
    <<
        \context Voice = "Voice 1" \with {
            \override Slur.direction = #up
            \override Stem.direction = #up
        } {
            e''4 (
            es''8 ~
        }
        \context Voice = "Voice 2" \with {
            \override Stem.direction = #down
        } {
            c'4 \p \<
            cs'8 ~
        }
    >>
    <<
        \context Voice = "Voice 1" \with {
            \override Slur.direction = #up
            \override Stem.direction = #up
        } {
            es''8
            f''4
            fs''4 )
        }
        \context Voice = "Voice 2" \with {
            \override Stem.direction = #down
        } {
            cs'8
            d'4
            ds'4 \f
        }
    >>
}

Splits leaves with articulations:

>>> staff = abjad.Staff("c'4 d' e' f'")
>>> abjad.attach(abjad.Articulation('^'), staff[0])
>>> abjad.attach(abjad.LaissezVibrer(), staff[1])
>>> abjad.attach(abjad.Articulation('^'), staff[2])
>>> abjad.attach(abjad.LaissezVibrer(), staff[3])
>>> show(staff) 
>>> durations = [(1, 8)]
>>> result = abjad.mutate(staff[:]).split(
...     durations,
...     cyclic=True,
...     fracture_spanners=False,
...     tie_split_notes=True,
...     )
>>> show(staff) 

Returns list of selections.

MutationAgent.swap(container)

Swaps mutation client for empty container.

Swaps measures for tuplet:

>>> staff = abjad.Staff()
>>> staff.append(abjad.Measure((3, 4), "c'4 d'4 e'4"))
>>> staff.append(abjad.Measure((3, 4), "d'4 e'4 f'4"))
>>> selector = abjad.select().by_leaf(flatten=True)
>>> leaves = selector(staff)
>>> hairpin = abjad.Hairpin('p < f')
>>> abjad.attach(hairpin, leaves)
>>> measures = staff[:]
>>> slur = abjad.Slur()
>>> abjad.attach(slur, leaves)
>>> show(staff) 
>>> measures = staff[:]
>>> tuplet = abjad.Tuplet((2, 3), [])
>>> tuplet.preferred_denominator = 4
>>> abjad.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 = abjad.Staff()
>>> staff.append(abjad.Measure((4, 4), "c'4 d'4 e'4 r4"))
>>> staff.append(abjad.Measure((3, 4), "d'4 e'4 <f' a' c''>4"))
>>> show(staff) 
>>> abjad.mutate(staff).transpose("+m3")
>>> show(staff) 

Returns none.

MutationAgent.wrap(container)

Wraps mutation client in empty container.

Wraps in-score notes in tuplet:

>>> staff = abjad.Staff("c'8 [ ( d' e' ] ) c' [ ( d' e' ] )")
>>> show(staff) 
>>> tuplet = abjad.Tuplet((2, 3), [])
>>> abjad.mutate(staff[-3:]).wrap(tuplet)
>>> show(staff) 

Wraps outside-score notes in tuplet:

>>> maker = abjad.NoteMaker()
>>> notes = maker([0, 2, 4], [(1, 8)])
>>> tuplet = abjad.Tuplet((2, 3), [])
>>> abjad.mutate(notes).wrap(tuplet)
>>> show(tuplet) 

(This usage merely substitutes for the tuplet initializer.)

Wraps leaves in measure:

>>> notes = [abjad.Note(n, (1, 8)) for n in range(8)]
>>> voice = abjad.Voice(notes)
>>> measure = abjad.Measure((4, 8), [])
>>> abjad.mutate(voice[:4]).wrap(measure)
>>> show(voice) 

Wraps each leaf in measure:

>>> notes = [abjad.Note(n, (1, 1)) for n in range(4)]
>>> staff = abjad.Staff(notes)
>>> for note in staff:
...     measure = abjad.Measure((1, 1), [])
...     abjad.mutate(note).wrap(measure)
...

Raises exception on nonempty container:

>>> staff = abjad.Staff("c'8 [ ( d' e' ] ) c' [ ( d' e' ] )")
>>> tuplet = abjad.Tuplet((2, 3), "g'8 a' fs'")
>>> statement = 'abjad.mutate(staff[-3:]).wrap(tuplet)'
>>> pytest.raises(Exception, statement)
<ExceptionInfo Exception tblen=3>

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.