mutate

---

Functions

copy	Copies argument.
eject_contents	Ejects container contents.
extract	Extracts argument from score.
fuse	Fuses argument.
logical_tie_to_tuplet	Changes logical tie to tuplet.
replace	Replaces argument (and contents of argument) with recipients.
scale	Scales argument by multiplier.
split	Splits argument by durations.
swap	Swaps argument for empty container.
transpose	Transposes notes and chords in argument by interval.
wrap	Wraps argument in empty container.

abjad.mutate.copy(argument, n=1)

Copies argument.

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.copy(staff[:2])
>>> 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.copy(staff[2:4])
>>> 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")
>>> score = abjad.Score([staff], name="Score")
>>> time_signature = abjad.TimeSignature((2, 4))
>>> abjad.attach(time_signature, staff[0])
>>> abjad.show(staff)  

>>> selection = staff[2:4]
>>> result = abjad.mutate.copy(selection)
>>> new_staff = abjad.Staff(result)
>>> abjad.show(new_staff)  

>>> staff[2] is new_staff[0]
False

Return type:

list[Component]

abjad.mutate.eject_contents(container)

Ejects container contents.

Ejects leaves from container:

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

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

Leaves can be added to a new container:

>>> staff = abjad.Staff(leaves, lilypond_type="RhythmicStaff")
>>> abjad.show(staff)  

Old container is empty:

>>> container
Container()

Return type:

list[Component]

abjad.mutate.extract(argument)

Extracts argument from score.

Leaves children of argument in score.

Extract tuplets:

>>> voice = abjad.Voice()
>>> voice.append(abjad.Tuplet((3, 2), "c'4 e'4"))
>>> voice.append(abjad.Tuplet((3, 2), "d'4 f'4"))
>>> leaves = abjad.select.leaves(voice)
>>> staff = abjad.Staff([voice])
>>> score = abjad.Score([staff], name="Score")
>>> time_signature = abjad.TimeSignature((3, 4))
>>> abjad.attach(time_signature, leaves[0])
>>> abjad.hairpin("p < f", leaves)
>>> abjad.show(staff)  

>>> empty_tuplet = abjad.mutate.extract(voice[-1])
>>> empty_tuplet = abjad.mutate.extract(voice[0])
>>> abjad.show(staff)  

Scales tuplet contents and then extracts tuplet:

>>> voice = abjad.Voice()
>>> staff = abjad.Staff([voice])
>>> voice.append(abjad.Tuplet((3, 2), "c'4 e'4"))
>>> voice.append(abjad.Tuplet((3, 2), "d'4 f'4"))
>>> score = abjad.Score([staff], name="Score")
>>> leaves = abjad.select.leaves(staff)
>>> abjad.hairpin("p < f", leaves)
>>> time_signature = abjad.TimeSignature((3, 4))
>>> abjad.attach(time_signature, leaves[0])
>>> abjad.show(staff)  

>>> abjad.mutate.scale(voice[-1], abjad.Fraction(3, 2))
>>> empty_tuplet = abjad.mutate.extract(voice[-1])
>>> abjad.mutate.scale(voice[0], abjad.Fraction(3, 2))
>>> empty_tuplet = abjad.mutate.extract(voice[0])
>>> abjad.show(voice)  

Extracting out-of-score component does nothing and returns component:

>>> tuplet = abjad.Tuplet((3, 2), "c'4 e'4")
>>> abjad.show(tuplet)  

>>> abjad.mutate.extract(tuplet)
Tuplet('2:3', "c'4 e'4")

>>> abjad.show(tuplet)  

Returns argument.

abjad.mutate.fuse(argument)

Fuses argument.

Fuses in-score leaves:

>>> staff = abjad.Staff("c'8 d'8 e'8 f'8")
>>> abjad.show(staff)  

>>> abjad.mutate.fuse(staff[1:])
[Note("d'4.")]

>>> abjad.show(staff)  

Fuses parent-contiguous tuplets in selection:

>>> tuplet_1 = abjad.Tuplet((2, 3), "c'8 d' e'")
>>> tuplet_2 = abjad.Tuplet((2, 3), "c'16 d' e'")
>>> voice = abjad.Voice([tuplet_1, tuplet_2])
>>> staff = abjad.Staff([voice])
>>> abjad.beam(tuplet_1[:])
>>> abjad.slur(tuplet_2[:])
>>> abjad.show(staff)  

>>> tuplets = voice[:]
>>> abjad.mutate.fuse(tuplets)
Tuplet('3:2', "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.

REGRESSION. Trims tie from fused note:

>>> staff = abjad.Staff("d'8 ~ d'32 ~ d'16 d'32")
>>> abjad.show(staff)  

>>> logical_tie = abjad.select.logical_tie(staff[0])
>>> abjad.mutate.fuse(logical_tie)
[Note("d'8..")]

>>> abjad.show(staff)  

>>> abjad.get.has_indicator(staff[0], abjad.Tie)
False

Return type:

Tuplet | list[Leaf]

abjad.mutate.logical_tie_to_tuplet(argument, proportions, *, tag=None)

Changes logical tie to tuplet.

>>> voice = abjad.Voice(r"df'8 c'8 ~ c'16 cqs''4")
>>> staff = abjad.Staff([voice])
>>> score = abjad.Score([staff], name="Score")
>>> abjad.attach(abjad.Dynamic("p"), voice[0])
>>> abjad.attach(abjad.StartHairpin("<"), voice[0])
>>> abjad.attach(abjad.Dynamic("f"), voice[-1])
>>> abjad.override(staff).DynamicLineSpanner.staff_padding = 3
>>> time_signature = abjad.TimeSignature((9, 16))
>>> abjad.attach(time_signature, voice[0])
>>> abjad.show(staff)  

>>> logical_tie = abjad.select.logical_tie(voice[1])
>>> abjad.mutate.logical_tie_to_tuplet(logical_tie, [2, 1, 1, 1])
Tuplet('5:3', "c'8 c'16 c'16 c'16")

>>> abjad.show(staff)  

>>> voice = abjad.Voice(r"c'8 ~ c'16 cqs''4")
>>> staff = abjad.Staff([voice])
>>> score = abjad.Score([staff], name="Score")
>>> abjad.hairpin("p < f", voice[:])
>>> abjad.override(staff).DynamicLineSpanner.staff_padding = 3
>>> time_signature = abjad.TimeSignature((7, 16))
>>> abjad.attach(time_signature, voice[0])
>>> abjad.show(staff)  

Return type:

Tuplet

abjad.mutate.replace(argument, recipients, wrappers=False)

Replaces argument (and contents of argument) 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")
>>> voice = abjad.Voice([tuplet_1, tuplet_2])
>>> leaves = abjad.select.leaves(voice)
>>> abjad.hairpin("p < f", leaves)
>>> abjad.slur(leaves)
>>> abjad.show(voice)  

>>> notes = abjad.makers.make_notes("c' d' e' f' c' d' e' f'", (1, 16))
>>> abjad.mutate.replace([tuplet_1], notes)
>>> abjad.attach(abjad.Dynamic("p"), voice[0])
>>> abjad.attach(abjad.StartHairpin("<"), voice[0])
>>> abjad.show(voice)  

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.get.effective(leaf, abjad.Clef)
... 
(Note("c'2"), Clef(name='alto', hide=False))
(Note("f'4"), Clef(name='alto', hide=False))
(Note("g'4"), Clef(name='alto', hide=False))

>>> chord = abjad.Chord("<d' e'>2")
>>> abjad.mutate.replace(staff[0], chord)
>>> abjad.show(staff)  

>>> for leaf in staff:
...     leaf, abjad.get.effective(leaf, abjad.Clef)
... 
(Chord("<d' e'>2"), None)
(Note("f'4"), None)
(Note("g'4"), None)

>>> abjad.wf.wellformed(staff)
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.get.effective(leaf, abjad.Clef)
... 
(Note("c'2"), Clef(name='alto', hide=False))
(Note("f'4"), Clef(name='alto', hide=False))
(Note("g'4"), Clef(name='alto', hide=False))

>>> chord = abjad.Chord("<d' e'>2")
>>> abjad.mutate.replace(staff[0], chord, wrappers=True)
>>> abjad.show(staff)  

>>> for leaf in staff:
...     leaf, abjad.get.effective(leaf, abjad.Clef)
... 
(Chord("<d' e'>2"), Clef(name='alto', hide=False))
(Note("f'4"), Clef(name='alto', hide=False))
(Note("g'4"), Clef(name='alto', hide=False))

>>> abjad.wf.wellformed(staff)
True

Todo

Fix.

Introduces duplicate ties:

>>> staff = abjad.Staff("c'2 ~ c'2")
>>> tied_notes = abjad.makers.make_notes(0, abjad.Duration(5, 8))
>>> abjad.mutate.replace(staff[:1], tied_notes)

>>> string = abjad.lilypond(staff)
>>> print(string)
\new Staff
{
    c'2
    ~
    c'8
    c'2
}

Returns none.

abjad.mutate.scale(argument, multiplier)

Scales argument 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.scale(staff[1], abjad.Fraction(3, 2))
>>> abjad.show(staff)  

Scales tied leaves by dot-generating mutliplier:

>>> staff = abjad.Staff(r"c'8 \accent ~ c'8 d'8")
>>> score = abjad.Score([staff], name="Score")
>>> time_signature = abjad.TimeSignature((3, 8))
>>> abjad.attach(time_signature, staff[0])
>>> abjad.show(staff)  

>>> logical_tie = abjad.select.logical_tie(staff[0])
>>> logical_tie = abjad.mutate.scale(logical_tie, abjad.Fraction(3, 2))
>>> abjad.show(staff)  

Scales leaves in container by dot-generating multiplier:

>>> container = abjad.Container(r"c'8 ( d'8 e'8 f'8 )")
>>> abjad.show(container)  

>>> abjad.mutate.scale(container, abjad.Fraction(3, 2))
>>> abjad.show(container)  

Scales leaves in tuplet:

>>> staff = abjad.Staff()
>>> score = abjad.Score([staff], name="Score")
>>> 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.get.leaf(staff, 0)
>>> abjad.attach(time_signature, leaf)
>>> abjad.show(staff)  

>>> abjad.mutate.scale(tuplet, abjad.Fraction(2))
>>> abjad.show(staff)  

Scales leaves carrying LilyPond multiplier:

>>> note = abjad.Note("c'8", multiplier=(1, 2))
>>> abjad.show(note)  

>>> abjad.mutate.scale(note, abjad.Fraction(1, 2))
>>> abjad.show(note)  

Return type:

None

abjad.mutate.split(argument, durations, *, cyclic=False, tag=None)

Splits argument by durations.

Splits leaves cyclically and ties split notes:

>>> voice = abjad.Voice("c'1 d'1")
>>> abjad.hairpin("p < f", voice[:])
>>> abjad.override(voice).DynamicLineSpanner.staff_padding = 3
>>> abjad.show(voice)  

>>> durations = [(3, 4)]
>>> result = abjad.mutate.split(
...     voice[:],
...     durations,
...     cyclic=True,
... )
>>> abjad.show(voice)  

Splits custom voice and preserves context name:

>>> voice = abjad.Voice(
...     "c'4 d' e' f'",
...     lilypond_type="CustomVoice",
...     name="1",
... )
>>> staff = abjad.Staff([voice])
>>> abjad.hairpin("p < f", voice[:])
>>> abjad.override(staff).DynamicLineSpanner.staff_padding = 3
>>> abjad.show(staff)  

>>> durations = [(1, 8)]
>>> result = abjad.mutate.split(
...     staff[:],
...     durations,
...     cyclic=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],
...     simultaneous=True,
... )
>>> abjad.override(voice_2).Stem.direction = abjad.DOWN
>>> staff = abjad.Staff([container])
>>> abjad.show(staff)  

>>> durations = [(3, 8)]
>>> result = abjad.mutate.split(
...     container,
...     durations,
...     cyclic=False,
... )
>>> abjad.show(staff)  

>>> string = abjad.lilypond(staff)
>>> print(string)
\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.split(
...     staff[:],
...     durations,
...     cyclic=True,
... )
>>> abjad.show(staff)  

REGRESSION. Preserves tie:

>>> staff = abjad.Staff("d'2 ~ d'")
>>> abjad.show(staff)  

>>> result = abjad.mutate.split(staff[0], [(1, 32)])
>>> abjad.show(staff)  

Returns list of selections.

abjad.mutate.swap(argument, container)

Swaps argument for empty container.

Swaps containers for tuplet:

>>> voice = abjad.Voice()
>>> staff = abjad.Staff([voice])
>>> score = abjad.Score([staff], name="Score")
>>> voice.append(abjad.Container("c'4 d'4 e'4"))
>>> voice.append(abjad.Container("d'4 e'4 f'4"))
>>> abjad.attach(abjad.TimeSignature((3, 4)), voice[0][0])
>>> leaves = abjad.select.leaves(voice)
>>> abjad.hairpin("p < f", leaves)
>>> measures = voice[:]
>>> abjad.slur(leaves)
>>> abjad.show(voice)  

>>> containers = voice[:]
>>> tuplet = abjad.Tuplet((2, 3), [])
>>> tuplet.denominator = 4
>>> abjad.mutate.swap(containers, tuplet)
>>> abjad.show(voice)  

REGRESSION: context indicators survive swap:

>>> prototype = abjad.TimeSignature
>>> for component in abjad.iterate.components(voice):
...     time_signature = abjad.get.effective(component, prototype)
...     print(component, time_signature)
... 
Voice("{ 2/3 c'4 d'4 e'4 d'4 e'4 f'4 }") TimeSignature(pair=(3, 4), hide=False, partial=None)
Tuplet('3:2', "c'4 d'4 e'4 d'4 e'4 f'4") TimeSignature(pair=(3, 4), hide=False, partial=None)
Note("c'4") TimeSignature(pair=(3, 4), hide=False, partial=None)
Note("d'4") TimeSignature(pair=(3, 4), hide=False, partial=None)
Note("e'4") TimeSignature(pair=(3, 4), hide=False, partial=None)
Note("d'4") TimeSignature(pair=(3, 4), hide=False, partial=None)
Note("e'4") TimeSignature(pair=(3, 4), hide=False, partial=None)
Note("f'4") TimeSignature(pair=(3, 4), hide=False, partial=None)

Returns none.

abjad.mutate.transpose(argument, interval)

Transposes notes and chords in argument by interval.

Todo

Move to abjad.pitch package.

Transposes notes and chords in staff:

>>> staff = abjad.Staff()
>>> score = abjad.Score([staff], name="Score")
>>> staff.extend("c'4 d'4 e'4 r4")
>>> abjad.attach(abjad.TimeSignature((4, 4)), staff[0])
>>> staff.extend("d'4 e'4 <f' a' c''>4")
>>> abjad.attach(abjad.TimeSignature((3, 4)), staff[4])
>>> abjad.show(staff)  

>>> abjad.mutate.transpose(staff, "+m3")
>>> abjad.show(staff)  

Returns none.

abjad.mutate.wrap(argument, container)

Wraps argument 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.wrap(staff[-3:], tuplet)
>>> abjad.show(staff)  

Wraps outside-score notes in tuplet:

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

(This usage merely substitutes for the tuplet initializer.)

Wraps leaves in container:

>>> notes = [abjad.Note(n, (1, 8)) for n in range(8)]
>>> staff = abjad.Staff(notes)
>>> score = abjad.Score([staff], name="Score")
>>> abjad.attach(abjad.TimeSignature((4, 8)), staff[0])
>>> container = abjad.Container()
>>> abjad.mutate.wrap(staff[:4], container)
>>> abjad.show(staff)  

Wraps each leaf in tuplet:

>>> notes = [abjad.Note(n, (1, 1)) for n in range(4)]
>>> staff = abjad.Staff(notes)
>>> for note in staff:
...     tuplet = abjad.Tuplet((2, 3))
...     abjad.mutate.wrap(note, tuplet)
... 

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'")
>>> abjad.mutate.wrap(staff[-3:], tuplet)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/trevor/abjad/abjad/mutate.py", line 2715, in wrap
    raise Exception(f"must be empty container: {container!r}.")
Exception: must be empty container: Tuplet('3:2', "g'8 a'8 fs'8").

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

>>> staff = abjad.Staff("c'4 d' e' f'")
>>> score = abjad.Score([staff], name="Score")
>>> leaves = abjad.select.leaves(staff)
>>> abjad.attach(abjad.TimeSignature((3, 8)), leaves[0])
>>> container = abjad.Container()
>>> abjad.mutate.wrap(leaves, container)
>>> abjad.show(staff)  

>>> prototype = abjad.TimeSignature
>>> for component in abjad.iterate.components(staff):
...     time_signature = abjad.get.effective(component, prototype)
...     print(component, time_signature)
... 
Staff("{ c'4 d'4 e'4 f'4 }") TimeSignature(pair=(3, 8), hide=False, partial=None)
Container("c'4 d'4 e'4 f'4") TimeSignature(pair=(3, 8), hide=False, partial=None)
Note("c'4") TimeSignature(pair=(3, 8), hide=False, partial=None)
Note("d'4") TimeSignature(pair=(3, 8), hide=False, partial=None)
Note("e'4") TimeSignature(pair=(3, 8), hide=False, partial=None)
Note("f'4") TimeSignature(pair=(3, 8), hide=False, partial=None)

Returns none.