Mutation

digraph InheritanceGraph { graph [bgcolor=transparent, color=lightsteelblue2, fontname=Arial, fontsize=10, outputorder=edgesfirst, overlap=prism, penwidth=2, rankdir=LR, splines=spline, style="dashed, rounded", truecolor=true]; node [colorscheme=pastel19, fontname=Arial, fontsize=10, height=0, penwidth=2, shape=box, style="filled, rounded", width=0]; edge [color=lightslategrey, penwidth=1]; subgraph "cluster_abjad.core" { graph [label="abjad.core"]; node [color=1]; "abjad.core.Mutation.Mutation" [URL="../api/abjad/core/Mutation.html#abjad.core.Mutation.Mutation", color=black, fontcolor=white, label=Mutation, target=_top]; } subgraph "cluster_abjad.system" { graph [label="abjad.system"]; node [color=2]; "abjad.system.AbjadObject.AbjadObject" [URL="../api/abjad/core/../system/AbjadObject.html#abjad.system.AbjadObject.AbjadObject", label="Abjad\nObject", target=_top]; } subgraph cluster_builtins { graph [label=builtins]; node [color=3]; "builtins.object" [URL="https://docs.python.org/3.6/library/functions.html#object", label=object, target=_top]; } "abjad.system.AbjadObject.AbjadObject" -> "abjad.core.Mutation.Mutation"; "builtins.object" -> "abjad.system.AbjadObject.AbjadObject"; }

class abjad.core.Mutation.Mutation(client=None)

Mutation.

Creates mutation for last two notes in staff:

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

Attributes Summary

client Gets client.
copy Copies client.
eject_contents Ejects contents from outside-of-score container.
extract Extracts mutation client from score.
fuse Fuses mutation client.
replace Replaces mutation client (and contents of mutation client) with recipients.
replace_measure_contents Replaces contents of measures in client with new_contents.
rewrite_meter Rewrites the contents of logical ties in an expression to match meter.
scale Scales mutation client by multiplier.
splice Splices components to the right or left of selection.
split Splits mutation client by durations.
swap Swaps mutation client for empty container.
transpose Transposes notes and chords in mutation client by argument.
wrap Wraps mutation client in empty container.

Special methods

(AbjadObject).__format__(format_specification='')

Formats Abjad object.

Set format_specification to '' or 'storage'. Interprets '' equal to 'storage'.

Returns string.

(AbjadObject).__repr__()

Gets interpreter representation of Abjad object.

Returns string.


Methods

copy()

Copies client.

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

Copy components one time:

>>> staff = abjad.Staff(r"c'8 ( d'8 e'8 f'8 )")
>>> staff.extend(r"g'8 a'8 b'8 c''8")
>>> time_signature = abjad.TimeSignature((2, 4))
>>> abjad.attach(time_signature, staff[0])
>>> abjad.show(staff) 
>>> selection = staff[2:4]
>>> result = selection._copy()
>>> new_staff = abjad.Staff(result)
>>> abjad.show(new_staff) 
>>> staff[2] is new_staff[0]
False

Returns selection of new components.

eject_contents()

Ejects contents from outside-of-score container.

Ejects leaves from container:

>>> container = abjad.Container("c'4 ~ c'4 d'4 ~ d'4")
>>> abjad.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, lilypond_type='RhythmicStaff')
>>> abjad.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.

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')
>>> leaves = abjad.select(staff).leaves()
>>> time_signature = abjad.TimeSignature((3, 4))
>>> abjad.attach(time_signature, leaves[0])
>>> abjad.attach(hairpin, leaves)
>>> abjad.show(staff) 
>>> empty_tuplet = abjad.mutate(staff[-1]).extract()
>>> empty_tuplet = abjad.mutate(staff[0]).extract()
>>> abjad.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"))
>>> leaves = abjad.select(staff).leaves()
>>> hairpin = abjad.Hairpin('p < f')
>>> abjad.attach(hairpin, leaves)
>>> time_signature = abjad.TimeSignature((3, 4))
>>> abjad.attach(time_signature, leaves[0])
>>> abjad.show(staff) 
>>> empty_tuplet = abjad.mutate(staff[-1]).extract(
...     scale_contents=True)
>>> empty_tuplet = abjad.mutate(staff[0]).extract(
...     scale_contents=True)
>>> abjad.show(staff) 

Returns mutation client.

fuse()

Fuses mutation client.

Fuses in-score leaves:

>>> staff = abjad.Staff("c'8 d'8 e'8 f'8")
>>> abjad.show(staff) 
>>> abjad.mutate(staff[1:]).fuse()
Selection([Note("d'4.")])
>>> abjad.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])
>>> abjad.show(staff) 
>>> tuplets = staff[:]
>>> abjad.mutate(tuplets).fuse()
Tuplet(Multiplier(2, 3), "c'8 d'8 e'8 c'16 d'16 e'16")
>>> abjad.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).leaves()
>>> abjad.attach(slur, leaves)
>>> abjad.show(staff) 
>>> measures = staff[:]
>>> abjad.mutate(measures).fuse()
Measure((2, 4), "c'8 d'8 e'8 f'8")
>>> abjad.show(staff) 

Returns selection.

replace(recipients, wrappers=False)

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')
>>> leaves = abjad.select(staff).leaves()
>>> abjad.attach(hairpin, leaves)
>>> slur = abjad.Slur()
>>> abjad.attach(slur, leaves)
>>> abjad.show(staff) 
>>> maker = abjad.NoteMaker()
>>> notes = maker("c' d' e' f' c' d' e' f'", (1, 16))
>>> abjad.mutate([tuplet_1]).replace(notes)
>>> abjad.show(staff) 

Preserves both hairpin and slur.

Copies no wrappers when wrappers is false:

>>> staff = abjad.Staff("c'2 f'4 g'")
>>> abjad.attach(abjad.Clef('alto'), staff[0])
>>> abjad.show(staff) 
>>> for leaf in staff:
...     leaf, abjad.inspect(leaf).effective(abjad.Clef)
... 
(Note("c'2"), Clef('alto'))
(Note("f'4"), Clef('alto'))
(Note("g'4"), Clef('alto'))
>>> chord = abjad.Chord("<d' e'>2")
>>> abjad.mutate(staff[0]).replace(chord)
>>> abjad.show(staff) 
>>> for leaf in staff:
...     leaf, abjad.inspect(leaf).effective(abjad.Clef)
... 
(Chord("<d' e'>2"), None)
(Note("f'4"), None)
(Note("g'4"), None)
>>> abjad.inspect(staff).is_well_formed()
True

Set wrappers to true to copy all wrappers from one leaf to another leaf (and avoid full-score update). Only works from one leaf to another leaf:

>>> staff = abjad.Staff("c'2 f'4 g'")
>>> abjad.attach(abjad.Clef('alto'), staff[0])
>>> abjad.show(staff) 
>>> for leaf in staff:
...     leaf, abjad.inspect(leaf).effective(abjad.Clef)
... 
(Note("c'2"), Clef('alto'))
(Note("f'4"), Clef('alto'))
(Note("g'4"), Clef('alto'))
>>> chord = abjad.Chord("<d' e'>2")
>>> abjad.mutate(staff[0]).replace(chord, wrappers=True)
>>> abjad.show(staff) 
>>> for leaf in staff:
...     leaf, abjad.inspect(leaf).effective(abjad.Clef)
... 
(Chord("<d' e'>2"), Clef('alto'))
(Note("f'4"), Clef('alto'))
(Note("g'4"), Clef('alto'))
>>> abjad.inspect(staff).is_well_formed()
True

Todo

Fix.

Introduces duplicate ties:

>>> staff = abjad.Staff("c'2 ~ c'2")
>>> maker = abjad.NoteMaker()
>>> tied_notes = maker(0, abjad.Duration(5, 8))
>>> abjad.mutate(staff[:1]).replace(tied_notes)
>>> abjad.f(staff)
\new Staff
{
    c'2
    ~
    ~
    c'8
    ~
    c'2
}

Returns none.

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)
>>> abjad.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")]
>>> abjad.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.

rewrite_meter(meter, boundary_depth=None, initial_offset=None, maximum_dot_count=None, rewrite_tuplets=True, repeat_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)
>>> abjad.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)
>>> abjad.show(staff) 

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

>>> staff = abjad.Staff(string)
>>> abjad.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)
>>> abjad.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)
>>> abjad.show(measure) 

Without constraining the maximum_dot_count:

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

Constraining the maximum_dot_count to 2:

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

Constraining the maximum_dot_count to 1:

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

Constraining the maximum_dot_count to 0:

>>> measure = abjad.parse(string)
>>> abjad.mutate(measure[:]).rewrite_meter(
...     measure,
...     maximum_dot_count=0,
...     )
>>> abjad.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)
>>> abjad.show(measure) 
>>> abjad.mutate(measure[:]).rewrite_meter(measure)
>>> abjad.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,
...     )
>>> abjad.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,
...     )
>>> abjad.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)
>>> abjad.show(score) 

Here we establish a meter without specifying any boundary depth:

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

Here we reestablish meter at a boundary depth of 1:

>>> for measure in abjad.iterate(score).components(abjad.Measure):
...     abjad.mutate(measure[:]).rewrite_meter(
...         measure,
...         boundary_depth=1,
...         )
... 
>>> abjad.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)
>>> abjad.show(measure) 

When establishing a meter on a selection of components which contain containers, like tuplets or containers, 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,
...     )
>>> abjad.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)
>>> abjad.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)
>>> abjad.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)
>>> abjad.show(measure) 

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

Uses repeat ties:

>>> measure = abjad.Measure((4, 4), "c'4. c'4. c'4")
>>> abjad.show(measure) 
>>> meter = abjad.Meter((4, 4))
>>> abjad.mutate(measure[:]).rewrite_meter(
...     meter,
...     boundary_depth=1,
...     repeat_ties=True,
...     )
>>> abjad.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)
>>> abjad.show(measure) 
>>> meter = abjad.Meter((6, 4))
>>> abjad.mutate(measure[:]).rewrite_meter(
...     meter,
...     boundary_depth=1,
...     )
>>> abjad.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)
>>> abjad.show(measure) 
>>> meter = abjad.Meter((6, 4))
>>> abjad.mutate(measure[:]).rewrite_meter(
...     meter,
...     boundary_depth=1,
...     rewrite_tuplets=False,
...     )
>>> abjad.show(measure) 

Operates in place and returns none.

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 )")
>>> abjad.show(staff) 
>>> abjad.mutate(staff[1]).scale(abjad.Multiplier(3, 2))
>>> abjad.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])
>>> abjad.show(staff) 
>>> logical_tie = abjad.inspect(staff[0]).logical_tie()
>>> agent = abjad.mutate(logical_tie)
>>> logical_tie = agent.scale(abjad.Multiplier(3, 2))
>>> abjad.show(staff) 

Scales container by dot-generating multiplier:

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

Scales note by tie-generating multiplier:

>>> staff = abjad.Staff("c'8 ( d'8 e'8 f'8 )")
>>> abjad.show(staff) 
>>> abjad.mutate(staff[1]).scale(abjad.Multiplier(5, 4))
>>> abjad.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])
>>> abjad.show(staff) 
>>> logical_tie = abjad.inspect(staff[0]).logical_tie()
>>> agent = abjad.mutate(logical_tie)
>>> logical_tie = agent.scale(abjad.Multiplier(5, 4))
>>> abjad.show(staff) 

Scales container by tie-generating multiplier:

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

Scales note by tuplet-generating multiplier:

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

Scales trivial logical tie by tuplet-generating multiplier:

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

Scales container by tuplet-generating multiplier:

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

Scales note by tie- and tuplet-generating multiplier:

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

Scales note carrying LilyPond multiplier:

>>> note = abjad.Note("c'8")
>>> abjad.attach(abjad.Multiplier(1, 2), note)
>>> abjad.show(note) 
>>> abjad.mutate(note).scale(abjad.Multiplier(5, 3))
>>> abjad.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).leaves()
>>> abjad.attach(time_signature, leaves[0])
>>> abjad.show(staff) 
>>> abjad.mutate(tuplet).scale(abjad.Multiplier(2))
>>> abjad.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).leaf(0)
>>> abjad.attach(time_signature, leaf)
>>> abjad.show(staff) 
>>> abjad.mutate(tuplet).scale(abjad.Multiplier(2))
>>> abjad.show(staff) 

Returns none.

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

Splices components to the right or left of selection.

Todo

Add examples.

Returns list of components.

split(durations, fracture_spanners=False, cyclic=False, tie_split_notes=True, repeat_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('p < f')
>>> abjad.attach(hairpin, leaves)
>>> abjad.override(staff).dynamic_line_spanner.staff_padding = 3
>>> abjad.show(staff) 
>>> durations = [(3, 16), (7, 32)]
>>> result = abjad.mutate(leaves).split(
...     durations,
...     tie_split_notes=False,
...     )
>>> abjad.show(staff) 

Splits leaves and fracture crossing spanners:

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

Splits leaves cyclically:

>>> staff = abjad.Staff("c'8 e' d' f' c' e' d' f'")
>>> leaves = staff[:]
>>> hairpin = abjad.Hairpin('p < f')
>>> abjad.attach(hairpin, leaves)
>>> abjad.override(staff).dynamic_line_spanner.staff_padding = 3
>>> abjad.show(staff) 
>>> durations = [(3, 16), (7, 32)]
>>> result = abjad.mutate(leaves).split(
...     durations,
...     cyclic=True,
...     tie_split_notes=False,
...     )
>>> abjad.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('p < f')
>>> abjad.attach(hairpin, leaves)
>>> abjad.override(staff).dynamic_line_spanner.staff_padding = 3
>>> abjad.show(staff) 
>>> durations = [(3, 16), (7, 32)]
>>> result = abjad.mutate(leaves).split(
...     durations,
...     cyclic=True,
...     fracture_spanners=True,
...     tie_split_notes=False,
...     )
>>> abjad.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'"))
>>> leaves = abjad.select(staff).leaves()
>>> slur = abjad.Slur()
>>> abjad.attach(slur, leaves)
>>> abjad.show(staff) 
>>> durations = [(1, 4)]
>>> result = abjad.mutate(leaves).split(
...     durations,
...     fracture_spanners=True,
...     tie_split_notes=False,
...     )
>>> abjad.show(staff) 

Splits leaves cyclically and ties split notes:

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

As above but with repeat ties:

>>> staff = abjad.Staff("c'1 d'1")
>>> hairpin = abjad.Hairpin('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,
...     repeat_ties=True,
...     )
>>> abjad.show(staff) 

Splits custom voice and preserves context name:

>>> voice = abjad.Voice(
...     "c'4 d' e' f'",
...     lilypond_type='CustomVoice',
...     name='1',
...     )
>>> staff = abjad.Staff([voice])
>>> hairpin = abjad.Hairpin('p < f')
>>> abjad.attach(hairpin, voice[:])
>>> abjad.override(staff).dynamic_line_spanner.staff_padding = 3
>>> abjad.show(staff) 
>>> durations = [(1, 8)]
>>> result = abjad.mutate(staff[:]).split(
...     durations,
...     cyclic=True,
...     fracture_spanners=False,
...     tie_split_notes=True,
...     )
>>> abjad.show(staff) 
>>> for voice in staff:
...     voice
... 
Voice("c'8 ~", lilypond_type='CustomVoice', name='1')
Voice("c'8", lilypond_type='CustomVoice', name='1')
Voice("d'8 ~", lilypond_type='CustomVoice', name='1')
Voice("d'8", lilypond_type='CustomVoice', name='1')
Voice("e'8 ~", lilypond_type='CustomVoice', name='1')
Voice("e'8", lilypond_type='CustomVoice', name='1')
Voice("f'8 ~", lilypond_type='CustomVoice', name='1')
Voice("f'8", lilypond_type='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 = abjad.Up
>>> abjad.override(voice_1).slur.direction = abjad.Up
>>> container = abjad.Container(
...     [voice_1, voice_2],
...     is_simultaneous=True,
...     )
>>> abjad.override(voice_2).stem.direction = abjad.Down
>>> staff = abjad.Staff([container])
>>> abjad.show(staff) 
>>> durations = [(3, 8)]
>>> result = abjad.mutate(container).split(
...     durations,
...     cyclic=False,
...     fracture_spanners=False,
...     tie_split_notes=True,
...     )
>>> abjad.show(staff) 
>>> abjad.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])
>>> abjad.show(staff) 
>>> durations = [(1, 8)]
>>> result = abjad.mutate(staff[:]).split(
...     durations,
...     cyclic=True,
...     fracture_spanners=False,
...     tie_split_notes=True,
...     )
>>> abjad.show(staff) 

Returns list of selections.

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"))
>>> leaves = abjad.select(staff).leaves()
>>> hairpin = abjad.Hairpin('p < f')
>>> abjad.attach(hairpin, leaves)
>>> measures = staff[:]
>>> slur = abjad.Slur()
>>> abjad.attach(slur, leaves)
>>> abjad.show(staff) 
>>> measures = staff[:]
>>> tuplet = abjad.Tuplet((2, 3), [])
>>> tuplet.denominator = 4
>>> abjad.mutate(measures).swap(tuplet)
>>> abjad.show(staff) 

Returns none.

transpose(argument)

Transposes notes and chords in mutation client by argument.

Todo

Move to abjad.pitch 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"))
>>> abjad.show(staff) 
>>> abjad.mutate(staff).transpose("+m3")
>>> abjad.show(staff) 

Returns none.

wrap(container)

Wraps mutation client in empty container.

Wraps in-score notes in tuplet:

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

>>> import pytest
>>> 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>

REGRESSION. Contexted indicators (like time signature) survive wrap:

>>> staff = abjad.Staff("c'4 d' e' f'")
>>> leaves = abjad.select(staff).leaves()
>>> abjad.attach(abjad.TimeSignature((3, 8)), leaves[0])
>>> container = abjad.Container()
>>> abjad.mutate(leaves).wrap(container)
>>> abjad.show(staff) 
>>> prototype = abjad.TimeSignature
>>> for component in abjad.iterate(staff).components():
...     inspection = abjad.inspect(component)
...     time_signature = inspection.effective(prototype)
...     print(component, time_signature)
... 
<Staff{1}> 3/8
Container("c'4 d'4 e'4 f'4") 3/8
c'4 3/8
d'4 3/8
e'4 3/8
f'4 3/8

Returns none.


Read-only properties

client

Gets client.

Returns selection or component.