Selector

class selectortools.Selector(callbacks=None)

Selector.

Selects note runs:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_run(Note)
>>> string = r"c'4 \times 2/3 { d'8 r8 e'8 } r16 f'16 g'8 a'4"
>>> staff = Staff(string)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'4"), Note("d'8")])
Selection([Note("e'8")])
Selection([Note("f'16"), Note("g'8"), Note("a'4")])

Selects first note in each run:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_run(Note)
>>> selector = selector.get_item(0, apply_to_each=True)
>>> string = r"c'4 \times 2/3 { d'8 r8 e'8 } r16 f'16 g'8 a'4"
>>> staff = Staff(string)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Note("c'4")
Note("e'8")
Note("f'16")

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

Bases

Attribute summary

append_callback(callback) Appends callback to selector.
by_class([prototype, flatten]) Selects by class.
by_contiguity() Selects by contiguity.
by_counts(counts[, cyclic, fuse_overhang, ...]) Partitions by counts.
by_duration([inequality, duration, preprolated]) Selects by duration.
by_leaf([flatten, head, pitched, prototype, ...]) Selects by leaf.
by_length([inequality, length]) Selects by length.
by_logical_measure() Selects by logical measure.
by_logical_tie([flatten, pitched, trivial]) Selects by logical tie.
by_pattern([pattern, apply_to_each]) Selects by pattern.
by_pitch([pitches]) Selects by pitch.
by_run([prototype]) Selects by run.
callbacks Gets callbacks of selector.
first() Selects first item in selection.
flatten([depth]) Flattens selection.
get_item(n[, apply_to_each]) Selects item n.
get_slice([start, stop, apply_to_each]) Selects slice.
group_by_pitch([allow_discontiguity]) Groups by pitch.
last() Selects last item.
middle() Selects middle items.
most() Selects most items.
partition_by_ratio(ratio) Partitions by ratio.
rest() Selects rest of items.
run_selectors(argument, selectors[, rotation]) Processes multiple selectors against a single selection.
select([apply_to_each]) Selects last result.
with_next_leaf() Selects with next leaf.
with_previous_leaf() Selects with previous leaf.
__call__(argument[, rotation]) Calls selector on argument.
__copy__(*arguments) Copies Abjad value object.
__eq__(argument) Is true when all initialization values of Abjad value object equal the initialization values of argument.
__format__([format_specification]) Formats Abjad object.
__getitem__(argument) Gets item or slice identified by argument.
__hash__() Hashes Abjad value object.
__ne__(argument) Is true when Abjad object does not equal argument.
__repr__() Gets interpreter representation of Abjad object.

Read-only properties

Selector.callbacks

Gets callbacks of selector.

Returns tuple.

Methods

Selector.append_callback(callback)

Appends callback to selector.

Composers can create their own selector callback classes with specialized composition-specific logic. Selector.append_callback() allows composers to use those composition-specific selector callbacks in the component selector pipeline.

A custom selector callback class can be created to only select chords containing the pitch-classes C, E and G. A selector can then be configured with that custom callback via append_callback():

>>> class CMajorSelectorCallback(abctools.AbjadValueObject):
...     def __call__(self, argument, rotation=None):
...         c_major_pcs = pitchtools.PitchClassSet("c e g")
...         result = []
...         for subexpr in argument:
...             subresult = []
...             for x in subexpr:
...                 if not isinstance(x, scoretools.Chord):
...                     continue
...                 pitches = x.written_pitches
...                 pcs = pitchtools.PitchClassSet(pitches)
...                 if pcs == c_major_pcs:
...                     subresult.append(x)
...             if subresult:
...                 result.append(tuple(subresult))
...         return tuple(result)
... 
>>> staff = Staff("<g' d'>4 <c' e' g'>4 r4 <e' g' c''>2 fs,4")
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.append_callback(CMajorSelectorCallback())
>>> for x in selector(staff):
...     x
...
Selection([Chord("<c' e' g'>4"), Chord("<e' g' c''>2")])

Returns new selector.

Selector.by_class(prototype=None, flatten=None)

Selects by class.

Selects notes:

>>> selector = select()
>>> selector = selector.by_class(prototype=Note)
>>> staff = Staff("c'4 d'8 ~ d'16 e'16 ~ e'8 r4 g'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'4"), Note("d'8"), Note("d'16"), Note("e'16"), Note("e'8"), Note("g'8")])

Selects notes separately:

>>> selector = select()
>>> selector = selector.by_class(prototype=Note, flatten=True)
>>> staff = Staff("c'4 d'8 ~ d'16 e'16 ~ e'8 r4 g'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Note("c'4")
Note("d'8")
Note("d'16")
Note("e'16")
Note("e'8")
Note("g'8")

Returns new selector.

Selector.by_contiguity()

Selects by contiguity.

Selects contiguous groups of sixteenth notes:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.flatten()
>>> selector = selector.by_duration('==', (1, 16))
>>> selector = selector.by_contiguity()
>>> staff = Staff("c'4 d'16 d' d' d' e'4 f'16 f' f' f'")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("d'16"), Note("d'16"), Note("d'16"), Note("d'16")])
Selection([Note("f'16"), Note("f'16"), Note("f'16"), Note("f'16")])

Selects the first leaf in each contiguous group of short-duration logical ties:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie()
>>> selector = selector.by_duration('<', (1, 4))
>>> selector = selector.by_contiguity()
>>> selector = selector.by_leaf()
>>> selector = selector[0].flatten()
>>> staff = Staff("c'4 d'8 ~ d'16 e'16 ~ e'8 f'4 g'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Note("d'8")
Note("g'8")

Returns new selector.

Selector.by_counts(counts, cyclic=False, fuse_overhang=False, nonempty=False, overhang=False, rotate=False)

Partitions by counts.

Todo

Change name to Selector.partition_by_counts().

Partitions once by counts without overhang:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_counts(
...     [3],
...     cyclic=False,
...     overhang=False,
...     )
>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8"), Rest('r8'), Note("d'8")])

Partitions cyclically by counts without overhang:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_counts(
...     [3],
...     cyclic=True,
...     overhang=False,
...     )
>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8"), Rest('r8'), Note("d'8")])
Selection([Note("e'8"), Rest('r8'), Note("f'8")])

Partitions cyclically by counts with overhang:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_counts(
...     [3],
...     cyclic=True,
...     overhang=True,
...     )
>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8"), Rest('r8'), Note("d'8")])
Selection([Note("e'8"), Rest('r8'), Note("f'8")])
Selection([Note("g'8"), Note("a'8")])

Partitions cyclically by counts with fused overhang:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_counts(
...     [3],
...     cyclic=True,
...     fuse_overhang=True,
...     overhang=True,
...     )
>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8"), Rest('r8'), Note("d'8")])
Selection([Note("e'8"), Rest('r8'), Note("f'8"), Note("g'8"), Note("a'8")])

Partitions cyclically by counts with overhang:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_counts(
...     [1, 2, 3],
...     cyclic=True,
...     overhang=True,
...     )
>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8 b'8 r8 c''8")
>>> result = selector(staff)
>>> label(result).color_alternating(['red', 'blue', 'green'])
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8")])
Selection([Rest('r8'), Note("d'8")])
Selection([Note("e'8"), Rest('r8'), Note("f'8")])
Selection([Note("g'8")])
Selection([Note("a'8"), Note("b'8")])
Selection([Rest('r8'), Note("c''8")])

Partitions cyclically by counts rotated one to the left, with overhang:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_counts(
...     [1, 2, 3],
...     cyclic=True,
...     overhang=True,
...     rotate=True,
...     )
>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8 b'8 r8 c''8")
>>> result = selector(staff, rotation=1)
>>> label(result).color_alternating(['red', 'blue', 'green'])
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8"), Rest('r8')])
Selection([Note("d'8"), Note("e'8"), Rest('r8')])
Selection([Note("f'8")])
Selection([Note("g'8"), Note("a'8")])
Selection([Note("b'8"), Rest('r8'), Note("c''8")])

Returns new selector.

Selector.by_duration(inequality=None, duration=None, preprolated=None)

Selects by duration.

Selects note runs with duration equal to 2/8:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_run(Note)
>>> selector = selector.by_duration(Duration(2, 8))
>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("d'8"), Note("e'8")])

Selects note runs with duration less than 3/8:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_run(Note)
>>> selector = selector.by_duration('<', Duration(3, 8))
>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8")])
Selection([Note("d'8"), Note("e'8")])

Selects note runs with duration greater than or equal to 1/4:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_run(Note)
>>> selector = selector.by_duration('>=', Duration(1, 4))
>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("d'8"), Note("e'8")])
Selection([Note("f'8"), Note("g'8"), Note("a'8")])

Selects logical ties with preprolated duration equal to 1/8:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie()
>>> selector = selector.by_duration(
...     '==',
...     Duration(1, 8),
...     preprolated=True,
...     )
>>> staff = Staff(r"""
...     \times 3/4 { c'16 d'16 ~ d'16 e'16 ~ }
...     {e'16 f'16 ~ f'16 g'16 ~ }
...     \times 5/4 { g'16 a'16 ~ a'16 b'16 }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
LogicalTie([Note("d'16"), Note("d'16")])
LogicalTie([Note("e'16"), Note("e'16")])
LogicalTie([Note("f'16"), Note("f'16")])
LogicalTie([Note("g'16"), Note("g'16")])
LogicalTie([Note("a'16"), Note("a'16")])

Returns new selector.

Selector.by_leaf(flatten=None, head=None, pitched=None, prototype=None, tail=None, trim=None)

Selects by leaf.

Selects leaves:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> staff = Staff(r"""
...     \times 2/3 { r8 d' e' } f' r
...     r f' \times 2/3 { e' d' r8 }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Rest('r8'), Note("d'8"), Note("e'8"), Note("f'8"), Rest('r8'), Rest('r8'), Note("f'8"), Note("e'8"), Note("d'8"), Rest('r8')])

Selects leaves separately:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(flatten=True)
>>> staff = Staff(r"""
...     \times 2/3 { r8 d' e' } f' r
...     r f' \times 2/3 { e' d' r8 }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Rest('r8')
Note("d'8")
Note("e'8")
Note("f'8")
Rest('r8')
Rest('r8')
Note("f'8")
Note("e'8")
Note("d'8")
Rest('r8')

Selects pitched leaves:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(pitched=True)
>>> selection = selector(staff)
>>> staff = Staff(r"""
...     \times 2/3 { r8 d' e' } f' r
...     r f' \times 2/3 { e' d' r8 }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("d'8"), Note("e'8"), Note("f'8"), Note("f'8"), Note("e'8"), Note("d'8")])

Selects pitched leaves separately:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(flatten=True, pitched=True)
>>> selection = selector(staff)
>>> staff = Staff(r"""
...     \times 2/3 { r8 d' e' } f' r
...     r f' \times 2/3 { e' d' r8 }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Note("d'8")
Note("e'8")
Note("f'8")
Note("f'8")
Note("e'8")
Note("d'8")

Selects trimmed leaves:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(
...     trim=(MultimeasureRest, Rest, Skip),
...     )
>>> staff = Staff(r"""
...     \times 2/3 { r8 d' e' } f' r
...     r f' \times 2/3 { e' d' r8 }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("d'8"), Note("e'8"), Note("f'8"), Rest('r8'), Rest('r8'), Note("f'8"), Note("e'8"), Note("d'8")])

Use trimmed leaves with ottava spanners:

>>> attach(OctavationSpanner(), result)
>>> show(staff) 

Regression: selects trimmed leaves (even when there are no rests to trim):

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(
...     trim=(MultimeasureRest, Rest, Skip),
...     )
>>> staff = Staff(r"""
...     \times 2/3 { c'8 d' e' } f' r
...     r f' \times 2/3 { e' d' c' }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8"), Note("d'8"), Note("e'8"), Note("f'8"), Rest('r8'), Rest('r8'), Note("f'8"), Note("e'8"), Note("d'8"), Note("c'8")])

Selects trimmed leaves separately:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(
...     flatten=True,
...     trim=(MultimeasureRest, Rest, Skip),
...     )
>>> staff = Staff(r"""
...     \times 2/3 { r8 d' e' } f' r
...     r f' \times 2/3 { e' d' r8 }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Note("d'8")
Note("e'8")
Note("f'8")
Rest('r8')
Rest('r8')
Note("f'8")
Note("e'8")
Note("d'8")

Selects leaves in tuplets:

>>> selector = selectortools.Selector()
>>> selector = selector.by_class(Tuplet)
>>> selector = selector.by_leaf()
>>> staff = Staff(r"""
...     \times 2/3 { r8 d' e' } f' r
...     r f' \times 2/3 { e' d' r8 }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Rest('r8'), Note("d'8"), Note("e'8"), Note("e'8"), Note("d'8"), Rest('r8')])

Selects leaves in tuplets separately:

>>> selector = selectortools.Selector()
>>> selector = selector.by_class(Tuplet, flatten=True)
>>> selector = selector.by_leaf()
>>> staff = Staff(r"""
...     \times 2/3 { r8 d' e' } f' r
...     r f' \times 2/3 { e' d' r8 }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Rest('r8'), Note("d'8"), Note("e'8")])
Selection([Note("e'8"), Note("d'8"), Rest('r8')])

Selects trimmed leaves in tuplets:

>>> selector = selectortools.Selector()
>>> selector = selector.by_class(Tuplet, flatten=True)
>>> selector = selector.by_leaf(
...     trim=(MultimeasureRest, Rest, Skip),
...     )
>>> staff = Staff(r"""
...     \times 2/3 { r8 d' e' } f' r
...     r f' \times 2/3 { e' d' r8 }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("d'8"), Note("e'8")])
Selection([Note("e'8"), Note("d'8")])

Selects pitched heads in tuplets.

This is the correct selection for most articulations:

>>> selector = selectortools.Selector()
>>> selector = selector.by_class(Tuplet, flatten=True)
>>> selector = selector.by_leaf(head=True, pitched=True)
>>> staff = Staff(r"""
...     \times 2/3 { c'8 d' ~ d' } e' r
...     r e' \times 2/3 { d' ~ d' c' }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8"), Note("d'8")])
Selection([Note("d'8"), Note("c'8")])

Selects pitched tails in tuplets.

This is the correct selection for laissez vibrer:

>>> selector = selectortools.Selector()
>>> selector = selector.by_class(Tuplet, flatten=True)
>>> selector = selector.by_leaf(tail=True, pitched=True)
>>> staff = Staff(r"""
...     \times 2/3 { c'8 d' ~ d' } e' r
...     r e' \times 2/3 { d' ~ d' c' }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8"), Note("d'8")])
Selection([Note("d'8"), Note("c'8")])

Selects chord heads in tuplets.

This is the correct selection for arpeggios:

>>> selector = selectortools.Selector()
>>> selector = selector.by_class(Tuplet, flatten=True)
>>> selector = selector.by_leaf(prototype=Chord, head=True)
>>> staff = Staff(r"""
...     \times 2/3 { <c' e' g'>8 ~ <c' e' g'> d' } e' r
...     r <g d' fs'> \times 2/3 { e' <c' d'> ~ <c' d'> }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Chord("<c' e' g'>8")])
Selection([Chord("<c' d'>8")])

Returns new selector.

Selector.by_length(inequality=None, length=None)

Selects by length.

Selects notes runs with length greater than 1:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_run(Note)
>>> selector = selector.by_length('>', 1)
>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("d'8"), Note("e'8")])
Selection([Note("f'8"), Note("g'8"), Note("a'8")])

Selects note runs with length less than 3:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_run(Note)
>>> selector = selector.by_length('<', 3)
>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8")])
Selection([Note("d'8"), Note("e'8")])

Returns new selector.

Selector.by_logical_measure()

Selects by logical measure.

Returns new selector.

Selector.by_logical_tie(flatten=True, pitched=False, trivial=True)

Selects by logical tie.

Todo

Change flatten default to false like other selector methods.

Selects logical ties:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(flatten=False)
>>> staff = Staff("c'8 d' ~ { d' e' r f'~ } f' r")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([LogicalTie([Note("c'8")]), LogicalTie([Note("d'8"), Note("d'8")]), LogicalTie([Note("e'8")]), LogicalTie([Rest('r8')]), LogicalTie([Note("f'8"), Note("f'8")]), LogicalTie([Rest('r8')])])

Selects logical ties separately:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(flatten=True)
>>> staff = Staff("c'8 d' ~ { d' e' r f'~ } f' r")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
LogicalTie([Note("c'8")])
LogicalTie([Note("d'8"), Note("d'8")])
LogicalTie([Note("e'8")])
LogicalTie([Rest('r8')])
LogicalTie([Note("f'8"), Note("f'8")])
LogicalTie([Rest('r8')])

Selects pitched logical ties:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(
...     flatten=False,
...     pitched=True,
...     )
>>> staff = Staff("c'8 d' ~ { d' e' r f'~ } f' r")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([LogicalTie([Note("c'8")]), LogicalTie([Note("d'8"), Note("d'8")]), LogicalTie([Note("e'8")]), LogicalTie([Note("f'8"), Note("f'8")])])

Selects pitched logical ties separately:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(
...     flatten=True,
...     pitched=True,
...     )
>>> staff = Staff("c'8 d' ~ { d' e' r f'~ } f' r")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
LogicalTie([Note("c'8")])
LogicalTie([Note("d'8"), Note("d'8")])
LogicalTie([Note("e'8")])
LogicalTie([Note("f'8"), Note("f'8")])

Selects pitched nontrivial logical ties:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(
...     flatten=False,
...     pitched=True,
...     trivial=False,
...     )
>>> staff = Staff("c'8 d' ~ { d' e' r f'~ } f' r")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([LogicalTie([Note("d'8"), Note("d'8")]), LogicalTie([Note("f'8"), Note("f'8")])])

Selects pitched nontrivial logical ties separately:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(
...     flatten=True,
...     pitched=True,
...     trivial=False,
...     )
>>> staff = Staff("c'8 d' ~ { d' e' r f'~ } f' r")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
LogicalTie([Note("d'8"), Note("d'8")])
LogicalTie([Note("f'8"), Note("f'8")])

Selects pitched logical ties in each tuplet separately:

>>> selector = selectortools.Selector()
>>> selector = selector.by_class(prototype=Tuplet)
>>> selector = selector.flatten()
>>> selector = selector.by_logical_tie(
...     flatten=False,
...     pitched=True,
...     )
>>> staff = Staff(r"""
...     \times 2/3 { c'8 d' e'  ~ } e' f' ~
...     \times 2/3 { f' g' a' ~ } a' b' ~
...     \times 2/3 { b' c'' d'' }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([LogicalTie([Note("c'8")]), LogicalTie([Note("d'8")]), LogicalTie([Note("e'8"), Note("e'8")])])
Selection([LogicalTie([Note("f'8"), Note("f'8")]), LogicalTie([Note("g'8")]), LogicalTie([Note("a'8"), Note("a'8")])])
Selection([LogicalTie([Note("b'8"), Note("b'8")]), LogicalTie([Note("c''8")]), LogicalTie([Note("d''8")])])

Selects pitched logical ties in each of the last two tuplets separately:

>>> selector = selectortools.Selector()
>>> selector = selector.by_class(prototype=Tuplet)
>>> selector = selector.flatten()
>>> selector = selector.get_slice(
...     start=-2,
...     apply_to_each=False,
...     )
>>> selector = selector.by_logical_tie(flatten=False, pitched=True)
>>> staff = Staff(r"""
...     \times 2/3 { c'8 d' e'  ~ } e' f' ~
...     \times 2/3 { f' g' a' ~ } a' b' ~
...     \times 2/3 { b' c'' d'' }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([LogicalTie([Note("f'8"), Note("f'8")]), LogicalTie([Note("g'8")]), LogicalTie([Note("a'8"), Note("a'8")])])
Selection([LogicalTie([Note("b'8"), Note("b'8")]), LogicalTie([Note("c''8")]), LogicalTie([Note("d''8")])])

Returns new selector.

Selector.by_pattern(pattern=None, apply_to_each=None)

Selects by pattern.

Selects every other leaf:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(flatten=True)
>>> selector = selector.by_pattern(
...     pattern=patterntools.select_every([0], period=2),
...     )
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Note("c'8")
Note("d'8")
Note("e'8")
Rest('r8')

Selects every other leaf rotated one to the right:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(flatten=True)
>>> selector = selector.by_pattern(
...     pattern=patterntools.select_every([0], period=2),
...     )
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff, rotation=1)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Note("d'8")
Note("e'8")
Note("e'8")
Note("f'8")

Selects every other logical tie:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.by_pattern(
...     pattern=patterntools.select_every([0], period=2),
...     )
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
LogicalTie([Note("c'8")])
LogicalTie([Note("e'8"), Note("e'8"), Note("e'8")])

Selects note 1 in every pitched logical tie:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> pattern = patterntools.select([1])
>>> selector = selector.by_pattern(
...     apply_to_each=True,
...     pattern=pattern,
...     )
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("d'8")])
Selection([Note("e'8")])

Returns new selector.

Selector.by_pitch(pitches=None)

Selects by pitch.

Selects leaves with C4:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(flatten=True)
>>> selector = selector.by_pitch(pitches="c'")
>>> staff = Staff("c'8 d'8 ~ d'8 e'8")
>>> staff.extend("r8 <c' e' g'>8 ~ <c' e' g'>4")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Note("c'8")
Chord("<c' e' g'>8")
Chord("<c' e' g'>4")

Leaf selection contains C4 somewhere:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_pitch(pitches="c'")
>>> staff = Staff("c'8 d'8 ~ d'8 e'8")
>>> staff.extend("r8 <c' e' g'>8 ~ <c' e' g'>4")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8"), Note("d'8"), Note("d'8"), Note("e'8"), Rest('r8'), Chord("<c' e' g'>8"), Chord("<c' e' g'>4")])

Selects leaves with C4 or E4:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(flatten=True)
>>> selector = selector.by_pitch(pitches="c' e'")
>>> staff = Staff("c'8 d'8 ~ d'8 e'8")
>>> staff.extend("r8 <c' e' g'>8 ~ <c' e' g'>4")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Note("c'8")
Note("e'8")
Chord("<c' e' g'>8")
Chord("<c' e' g'>4")

Selects logical ties with C4:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie()
>>> selector = selector.by_pitch(pitches=NamedPitch('C4'))
>>> staff = Staff("c'8 d'8 ~ d'8 e'8")
>>> staff.extend("r8 <c' e' g'>8 ~ <c' e' g'>4")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
LogicalTie([Note("c'8")])
LogicalTie([Chord("<c' e' g'>8"), Chord("<c' e' g'>4")])

Returns new selector.

Selector.by_run(prototype=None)

Selects by run.

Selects pitched runs:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_run(prototype=(Note, Chord))
>>> staff = Staff(r"c'8 d' r \times 2/3 { e' r f' } g' a' r")
>>> staff.extend("r8 <c' e' g'>8 ~ <c' e' g'>4")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8"), Note("d'8")])
Selection([Note("e'8")])
Selection([Note("f'8"), Note("g'8"), Note("a'8")])
Selection([Chord("<c' e' g'>8"), Chord("<c' e' g'>4")])

Returns new selector.

Selector.first()

Selects first item in selection.

Selects first pitched logical tie:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.first()
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Note("c'8")

Returns new selector.

Selector.flatten(depth=-1)

Flattens selection.

Selects leaves of middle pitched logical ties separately:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.middle()
>>> selector = selector.flatten()
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Note("d'8")
Note("d'8")
Note("e'8")
Note("e'8")
Note("e'8")

Selects leaves separately:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.flatten()
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Note("c'8")
Note("d'8")
Note("d'8")
Note("e'8")
Note("e'8")
Note("e'8")
Rest('r8')
Note("f'8")

Returns new selector.

Selector.get_item(n, apply_to_each=False)

Selects item n.

Selects leaf 1:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.flatten()
>>> selector = selector.get_item(1)
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 

Leaf returns directly (without selection wrapper):

>>> result
Note("d'8")

Selects logical tie 1:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.get_item(1)
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 

Logical tie returns directly (without selection wrapper):

>>> result
LogicalTie([Note("d'8"), Note("d'8")])

Selects tuplet 1:

>>> selector = selectortools.Selector()
>>> selector = selector.by_class(prototype=Tuplet)
>>> selector = selector.flatten()
>>> selector = selector.get_item(n=1)
>>> staff = Staff(r"""
...     \times 2/3 { r8 d' e' } f' r
...     r f' \times 2/3 { e' d' r8 }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 

Tuplet returns directly (without selection wrapper):

>>> result
Tuplet(Multiplier(2, 3), "e'8 d'8 r8")

Selects the first leaf in every pitched logical tie:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.get_item(0, apply_to_each=True)
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Note("c'8")
Note("d'8")
Note("e'8")
Note("f'8")

Returns new selector.

Selector.get_slice(start=None, stop=None, apply_to_each=True)

Selects slice.

Selects nonlast pitched logical ties:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.get_slice(
...     stop=-1,
...     apply_to_each=False,
...     )
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
LogicalTie([Note("c'8")])
LogicalTie([Note("d'8"), Note("d'8")])
LogicalTie([Note("e'8"), Note("e'8"), Note("e'8")])

Gets nonfirst pitched logical ties:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.get_slice(
...     start=1,
...     apply_to_each=False,
...     )
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
LogicalTie([Note("d'8"), Note("d'8")])
LogicalTie([Note("e'8"), Note("e'8"), Note("e'8")])
LogicalTie([Note("f'8")])

Selects nonfirst leaves in pitched logical ties:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.get_slice(
...     start=1,
...     apply_to_each=True,
...     )
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
LogicalTie([Note("d'8")])
LogicalTie([Note("e'8"), Note("e'8")])

Gets nonlast leaves in pitched logical ties:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.get_slice(
...     stop=-1,
...     apply_to_each=True,
...     )
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
LogicalTie([Note("d'8")])
LogicalTie([Note("e'8"), Note("e'8")])

Selects last three leaves:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.get_slice(
...     start=-3,
...     apply_to_each=True,
...     )
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("e'8"), Rest('r8'), Note("f'8")])

Gets last three leaves separately:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(flatten=True)
>>> selector = selector.get_slice(
...     start=-3,
...     apply_to_each=False,
...     )
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Note("e'8")
Rest('r8')
Note("f'8")

Returns new selector.

Selector.group_by_pitch(allow_discontiguity=False)

Groups by pitch.

Groups contiguous pitched leaves by pitch:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(pitched=True)
>>> selector = selector.group_by_pitch()
>>> string = r"c'8 ~ c'16 c'16 r8 c'16 c'16"
>>> staff = Staff(r"""
...     c'8 ~ c'16 c'16 r8 c'16 c'16
...     d'8 ~ d'16 d'16 r8 d'16 d'16
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8"), Note("c'16"), Note("c'16")])
Selection([Note("c'16"), Note("c'16")])
Selection([Note("d'8"), Note("d'16"), Note("d'16")])
Selection([Note("d'16"), Note("d'16")])

Groups discontiguous pitched leaves by pitch:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(pitched=True)
>>> selector = selector.group_by_pitch(
...     allow_discontiguity=True,
...     )
>>> string = r"c'8 ~ c'16 c'16 r8 c'16 c'16"
>>> staff = Staff(r"""
...     c'8 ~ c'16 c'16 r8 c'16 c'16
...     d'8 ~ d'16 d'16 r8 d'16 d'16
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8"), Note("c'16"), Note("c'16"), Note("c'16"), Note("c'16")])
Selection([Note("d'8"), Note("d'16"), Note("d'16"), Note("d'16"), Note("d'16")])

Groups contiguous pitched logical ties by pitch:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.group_by_pitch()
>>> staff = Staff(r"""
...     c'8 ~ c'16 c'16 r8 c'16 c'16
...     d'8 ~ d'16 d'16 r8 d'16 d'16
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([LogicalTie([Note("c'8"), Note("c'16")]), LogicalTie([Note("c'16")])])
Selection([LogicalTie([Note("c'16")]), LogicalTie([Note("c'16")])])
Selection([LogicalTie([Note("d'8"), Note("d'16")]), LogicalTie([Note("d'16")])])
Selection([LogicalTie([Note("d'16")]), LogicalTie([Note("d'16")])])

Groups discontiguous pitched logical ties by pitch:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.group_by_pitch(
...     allow_discontiguity=True,
...     )
>>> staff = Staff(r"""
...     c'8 ~ c'16 c'16 r8 c'16 c'16
...     d'8 ~ d'16 d'16 r8 d'16 d'16
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([LogicalTie([Note("c'8"), Note("c'16")]), LogicalTie([Note("c'16")]), LogicalTie([Note("c'16")]), LogicalTie([Note("c'16")])])
Selection([LogicalTie([Note("d'8"), Note("d'16")]), LogicalTie([Note("d'16")]), LogicalTie([Note("d'16")]), LogicalTie([Note("d'16")])])

Returns new selector.

Selector.last()

Selects last item.

Selects last pitched logical tie:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.last()
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Note("f'8")

Returns new selector.

Selector.middle()

Selects middle items.

Selects middle pitched logical ties:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.middle()
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
LogicalTie([Note("d'8"), Note("d'8")])
LogicalTie([Note("e'8"), Note("e'8"), Note("e'8")])

Returns new selector.

Selector.most()

Selects most items.

Selects most pitched logical ties:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.most()
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
LogicalTie([Note("c'8")])
LogicalTie([Note("d'8"), Note("d'8")])
LogicalTie([Note("e'8"), Note("e'8"), Note("e'8")])

Returns new selector.

Selector.partition_by_ratio(ratio)

Partitions by ratio.

Partitions leaves by ratio of 1:1:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.partition_by_ratio((1, 1))
>>> staff = Staff(r"c'8 d' r \times 2/3 { e' r f' } g' a' r")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8"), Note("d'8"), Rest('r8'), Note("e'8"), Rest('r8')])
Selection([Note("f'8"), Note("g'8"), Note("a'8"), Rest('r8')])

Partitions leaves by ratio of 1:1:1:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.partition_by_ratio((1, 1, 1))
>>> staff = Staff(r"c'8 d' r \times 2/3 { e' r f' } g' a' r")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8"), Note("d'8"), Rest('r8')])
Selection([Note("e'8"), Rest('r8'), Note("f'8")])
Selection([Note("g'8"), Note("a'8"), Rest('r8')])

Returns new selector.

Selector.rest()

Selects rest of items.

Selects rest of pitched logial ties:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.rest()
>>> staff = Staff(r"c'8 d'8 ~ d'8 e'8 ~ e'8 ~ e'8 r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
LogicalTie([Note("d'8"), Note("d'8")])
LogicalTie([Note("e'8"), Note("e'8"), Note("e'8")])
LogicalTie([Note("f'8")])

Returns new selector.

Selector.select(apply_to_each=False)

Selects last result.

Selects last two leaves in tuplet 1:

>>> selector = selectortools.Selector()
>>> selector = selector.by_class(prototype=Tuplet)
>>> selector = selector.flatten()
>>> selector = selector.get_item(n=1)
>>> selector = selector.select()
>>> selector = selector.by_leaf()
>>> selector = selector.get_slice(start=-2)
>>> staff = Staff(r"""
...     \times 2/3 { r8 d' e' } f' r
...     r f' \times 2/3 { e' d' r8 }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("d'8"), Rest('r8')])

Selects each tuplet as a separate selection:

>>> selector = selectortools.Selector()
>>> selector = selector.by_class(prototype=Tuplet)
>>> selector = selector.flatten()
>>> selector = selector.select(apply_to_each=True)
>>> staff = Staff(r"""
...     \times 2/3 { r8 d' e' } f' r
...     r f' \times 2/3 { e' d' r8 }
...     """)
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Tuplet(Multiplier(2, 3), "r8 d'8 e'8")])
Selection([Tuplet(Multiplier(2, 3), "e'8 d'8 r8")])

Returns new selector.

Selector.with_next_leaf()

Selects with next leaf.

Selects note runs (with next leaf):

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_run(Note)
>>> selector = selector.with_next_leaf()
>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8"), Rest('r8')])
Selection([Note("d'8"), Note("e'8"), Rest('r8')])
Selection([Note("f'8"), Note("g'8"), Note("a'8")])

Selects pitched tails (with next leaf):

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.get_item(-1, apply_to_each=True)
>>> selector = selector.with_next_leaf()
>>> staff = Staff(r"c'8 r d' ~ d' e' ~ e' r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8"), Rest('r8')])
Selection([Note("d'8"), Note("e'8")])
Selection([Note("e'8"), Rest('r8')])
Selection([Note("f'8")])

Selects pitched logical ties (with next leaf). This is the correct selection for single-pitch sustain pedal application:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.with_next_leaf()
>>> staff = Staff(r"c'8 r d' ~ d' e' ~ e' r8 f'8")
>>> result = selector(staff)
>>> for selection in result:
...     attach(PianoPedalSpanner(), selection)
...
>>> label(result).color_alternating()
>>> manager = override(staff).sustain_pedal_line_spanner
>>> manager.staff_padding = 6
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8"), Rest('r8')])
Selection([Note("d'8"), Note("d'8"), Note("e'8")])
Selection([Note("e'8"), Note("e'8"), Rest('r8')])
Selection([Note("f'8")])

Returns new selector.

Selector.with_previous_leaf()

Selects with previous leaf.

Selects note runs (with previous leaf):

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_run(Note)
>>> selector = selector.with_previous_leaf()
>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8")])
Selection([Rest('r8'), Note("d'8"), Note("e'8")])
Selection([Rest('r8'), Note("f'8"), Note("g'8"), Note("a'8")])

Selects pitched heads (with previous leaf):

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.get_item(0, apply_to_each=True)
>>> selector = selector.with_previous_leaf()
>>> staff = Staff(r"c'8 r d' ~ d' e' ~ e' r8 f'8")
>>> result = selector(staff)
>>> label(result).color_alternating()
>>> set_(staff).auto_beaming = False
>>> show(staff) 
>>> for item in result:
...     item
...
Selection([Note("c'8")])
Selection([Rest('r8'), Note("d'8")])
Selection([Note("d'8"), Note("e'8")])
Selection([Rest('r8'), Note("f'8")])

Returns new selector.

Class & static methods

static Selector.run_selectors(argument, selectors, rotation=None)

Processes multiple selectors against a single selection.

Minimizes reselection when selectors share identical prefixes of selector callbacks:

>>> staff = Staff("c'4 d'8 e'8 f'4 g'8 a'4 b'8 c'8")
>>> selector = selectortools.Selector()
>>> logical_tie_selector = selector.by_logical_tie()
>>> pitched_selector = logical_tie_selector.by_pitch('C4')
>>> duration_selector = logical_tie_selector.by_duration('==', (1, 8))
>>> contiguity_selector = duration_selector.by_contiguity()
>>> selectors = [
...     selector,
...     logical_tie_selector,
...     pitched_selector,
...     duration_selector,
...     contiguity_selector,
...     ]
>>> result = selectortools.Selector.run_selectors(staff, selectors)
>>> all(selector in result for selector in selectors)
True
>>> for item in result[selector]:
...     item
...
Staff("c'4 d'8 e'8 f'4 g'8 a'4 b'8 c'8")
>>> for item in result[logical_tie_selector]:
...     item
...
LogicalTie([Note("c'4")])
LogicalTie([Note("d'8")])
LogicalTie([Note("e'8")])
LogicalTie([Note("f'4")])
LogicalTie([Note("g'8")])
LogicalTie([Note("a'4")])
LogicalTie([Note("b'8")])
LogicalTie([Note("c'8")])
>>> for item in result[pitched_selector]:
...     item
...
LogicalTie([Note("c'4")])
LogicalTie([Note("c'8")])
>>> for item in result[duration_selector]:
...     item
...
LogicalTie([Note("d'8")])
LogicalTie([Note("e'8")])
LogicalTie([Note("g'8")])
LogicalTie([Note("b'8")])
LogicalTie([Note("c'8")])
>>> for item in result[contiguity_selector]:
...     item
...
Selection([LogicalTie([Note("d'8")]), LogicalTie([Note("e'8")])])
Selection([LogicalTie([Note("g'8")])])
Selection([LogicalTie([Note("b'8")]), LogicalTie([Note("c'8")])])

Returns a dictionary of selector/selection pairs.

Special methods

Selector.__call__(argument, rotation=None)

Calls selector on argument.

Returns a selection.

(AbjadValueObject).__copy__(*arguments)

Copies Abjad value object.

Returns new Abjad value object.

(AbjadValueObject).__eq__(argument)

Is true when all initialization values of Abjad value object equal the initialization values of argument.

Returns true or false.

(AbjadObject).__format__(format_specification='')

Formats Abjad object.

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

Returns string.

Selector.__getitem__(argument)

Gets item or slice identified by argument.

Returns another selector.

(AbjadValueObject).__hash__()

Hashes Abjad value object.

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.