Selector

class selectortools.Selector(callbacks=None)

A selector.

Selectors select components.

Selectors aggregate a sequence of callable classes which describe the process of component selection.

Selectors provide methods for configuring and making new selectors.

Composers may chain selectors together.

Todo

Add notation to every example.

Score for examples:

>>> string = r"c'4 \times 2/3 { d'8 r8 e'8 } r16 f'16 g'8 a'4"
>>> staff = Staff(string)
>>> show(staff) 

Example 1. Selects a component:

>>> selector = selectortools.Selector()
>>> selector(staff)
Selection([<Staff{6}>])

Example 2. Selects all of the leaves in a component:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector(staff)
Selection([Selection([Note("c'4"), Note("d'8"), Rest('r8'), Note("e'8"), Rest('r16'), Note("f'16"), Note("g'8"), Note("a'4")])])

Example 3. Selects runs of notes:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_run(Note)
>>> for selection in selector(staff):
...     selection
...
Selection([Note("c'4"), Note("d'8")])
Selection([Note("e'8")])
Selection([Note("f'16"), Note("g'8"), Note("a'4")])

Example 4. Selects the first item in each selection:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_run(Note)
>>> selector = selector.get_item(0, apply_to_each=True)
>>> selector(staff)
Selection([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]) Configures selector by class.
by_contiguity() Configures selector by contiguity.
by_counts(counts[, cyclic, fuse_overhang, ...]) Configures selector by counts.
by_duration([inequality, duration, preprolated]) Configures selector by duration.
by_leaf([flatten]) Configures selector by leaves.
by_length([inequality, length]) Configures selector by length.
by_logical_measure() Configures selector by logical measure.
by_logical_tie([flatten, pitched, trivial]) Configures selector by logical tie.
by_pattern([pattern, apply_to_each]) Configures selector by pattern.
by_pitch([pitches]) Configures selector by pitch.
by_run([prototype]) Configures selector by run.
callbacks Gets callbacks of selector.
first() Gets first item in selection.
flatten([depth]) Flattens selection.
get_item(item[, apply_to_each]) Gets item in selection.
get_slice([start, stop, apply_to_each]) Gets slice from start to stop in selection.
last() Gets last item in selection.
middle() Gets all but the first and last items in selection.
most() Gets all but the last item in selection.
partition_by_ratio(ratio) Configures selector to partition by ratio.
rest() Gets all but the first item in selection.
run_selectors(expr, selectors[, rotation]) Processes multiple selectors against a single selection.
with_next_leaf() Configures selector with next leaf after each selection.
with_previous_leaf() Configures selector with previous leaf before each selection.
__call__(expr[, rotation]) Calls selector on expr.
__copy__(\*args) Copies Abjad value object.
__eq__(expr) Is true when all initialization values of Abjad value object equal the initialization values of expr.
__format__([format_specification]) Formats Abjad object.
__getitem__(item) Gets item in selector.
__hash__() Hashes Abjad value object.
__ne__(expr) Is true when Abjad object does not equal expr.
__repr__() Gets interpreter representation of Abjad object.

Read-only properties

Selector.callbacks

Gets callbacks of selector.

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.

Example. 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, expr, rotation=None):
...         c_major_pcs = pitchtools.PitchClassSet("c e g")
...         result = []
...         for subexpr in expr:
...             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)

Configures selector by class.

Example 1. Selects notes and does not flatten:

>>> staff = Staff("c'4 d'8 ~ d'16 e'16 ~ e'8 r4 g'8")
>>> show(staff) 
>>> selector = select().by_class(prototype=Note)
>>> for selection in selector(staff):
...     selection
... 
Selection([Note("c'4"), Note("d'8"), Note("d'16"), Note("e'16"), Note("e'8"), Note("g'8")])

Call returns a selection containing a selection of notes.

Example 2. Selects notes and flattens:

>>> staff = Staff("c'4 d'8 ~ d'16 e'16 ~ e'8 r4 g'8")
>>> show(staff) 
>>> selector = select().by_class(prototype=Note, flatten=True)
>>> for note in selector(staff):
...     note
... 
Note("c'4")
Note("d'8")
Note("d'16")
Note("e'16")
Note("e'8")
Note("g'8")

Call returns a selection of notes.

Example 3. Selects rests:

>>> staff = Staff("c'4 d'8 ~ d'16 e'16 ~ e'8 r4 g'8")
>>> show(staff) 
>>> selector = select().by_class(prototype=Rest, flatten=True)
>>> for rest in selector(staff):
...     rest
... 
Rest('r4')

Call returns a selection of rests.

Returns new selector.

Selector.by_contiguity()

Configures selector by contiguity.

Example 1. Selects contiguous groups of sixteenth notes:

>>> staff = Staff("c'4 d'16 d' d' d' e'4 f'16 f' f' f'")
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.flatten()
>>> selector = selector.by_duration('==', (1, 16))
>>> selector = selector.by_contiguity()
>>> for x in selector(staff):
...     x
...
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")])

Example 2. Selects contiguous groups of logical ties each less than a quarter note in duration:

>>> staff = Staff("c'4 d'8 ~ d'16 e'16 ~ e'8 f'4 g'8")
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie()
>>> for x in selector(staff):
...     x
...
LogicalTie([Note("c'4")])
LogicalTie([Note("d'8"), Note("d'16")])
LogicalTie([Note("e'16"), Note("e'8")])
LogicalTie([Note("f'4")])
LogicalTie([Note("g'8")])
>>> selector = selector.by_duration('<', (1, 4))
>>> for x in selector(staff):
...     x
...
LogicalTie([Note("d'8"), Note("d'16")])
LogicalTie([Note("e'16"), Note("e'8")])
LogicalTie([Note("g'8")])
>>> selector = selector.by_contiguity()
>>> for x in selector(staff):
...     x
...
Selection([LogicalTie([Note("d'8"), Note("d'16")]), LogicalTie([Note("e'16"), Note("e'8")])])
Selection([LogicalTie([Note("g'8")])])
>>> selector = selector.by_leaf()
>>> for x in selector(staff):
...     x
...
Selection([Note("d'8"), Note("d'16"), Note("e'16"), Note("e'8")])
Selection([Note("g'8")])
>>> selector = selector[0].flatten()
>>> for x in selector(staff):
...     attach(indicatortools.Articulation('snappizzicato'), x)
... 
>>> show(staff) 

Returns new selector.

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

Configures selector by counts.

Partitions components.

Example 1. Selects first three components:

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

Call returns a selection containing a component selection.

Example 2. Selects every complete group of three components:

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

Call returns a selection containing two component selections.

Example 3. Selects every group of three components plus any overhang:

>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_counts(
...     [3],
...     cyclic=True,
...     overhang=True,
...     )
>>> for selection in selector(staff):
...     selection
...
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")])

Call returns a selection containing three component selections.

Example 4. Selects the first three components and then the remaining components:

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

Call returns a selection of two component selections.

Example 5. Selects components grouped by counts 1, 2, 3:

>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8 b'8 r8 c''8")
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_counts(
...     [1, 2, 3],
...     cyclic=True,
...     overhang=True,
...     )
>>> for selection in selector(staff):
...     selection
...
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")])

Call returns a selection containing multiple component selections.

Example 6. Selects components grouped 1, 2, 3 rotated one to the left:

>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8 b'8 r8 c''8")
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_counts(
...     [1, 2, 3],
...     cyclic=True,
...     overhang=True,
...     rotate=True,
...     )
>>> for selection in selector(staff, rotation=1):
...     selection
...
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")])

Call returns a selection containing multiple component selections.

Returns new selector.

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

Configures selector by duration.

Example 1. Selects all runs of notes with duration equal to 2/8:

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

Call returns a selection containing one component selection.

Example 2. Selects all runs of notes with duration shorter than 3/8:

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

Call returns a selection containing component selections.

Example 3. Selects all runs of notes with duration longer than or equal to 1/4:

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

Call returns a selection containing component selections.

Example 4. Selects all logical ties whose leaves sum to 1/8, before prolation:

>>> 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 }
... """)
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie()
>>> selector = selector.by_duration(
...     '==', Duration(1, 8),
...     preprolated=True,
...     )
>>> selections = selector(staff)
>>> for logical_tie in selections:
...     attach(Articulation('accent'), logical_tie[0])
...     print(logical_tie)
...
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")])
>>> show(staff) 

Call returns a selection containing logical tie selections.

Returns new selector.

Selector.by_leaf(flatten=None)

Configures selector by leaves.

Example 1. Selects leaves without flattening:

>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selections = selector(staff)
>>> for selection in selections:
...     selection
...
Selection([Note("c'8"), Rest('r8'), Note("d'8"), Note("e'8"), Rest('r8'), Note("f'8"), Note("g'8"), Note("a'8")])

Returns a selection of leaf selections.

Example 2. Selects leaves with flattening:

>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> show(staff) 
>>> f(staff)
\new Staff {
    c'8
    r8
    d'8
    e'8
    r8
    f'8
    g'8
    a'8
}
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(flatten=True)
>>> selection = selector(staff)
>>> for leaf in selection:
...     leaf
...
Note("c'8")
Rest('r8')
Note("d'8")
Note("e'8")
Rest('r8')
Note("f'8")
Note("g'8")
Note("a'8")

Returns a leaf selection.

Example 3. Selects leaves:

>>> staff = Staff("abj: | 4/4 c'2 d'2 || 3/4 e'4 f'4 g'4 |")
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_class(Measure)
>>> selections = selector(staff)
>>> for selection in selections:
...     selection
...
Selection([Measure((4, 4), "c'2 d'2"), Measure((3, 4), "e'4 f'4 g'4")])

Returns a selection of measure selections.

>>> selector = selector.by_leaf()
>>> selections = selector(staff)
>>> for selection in selections:
...     selection
...
Selection([Note("c'2"), Note("d'2"), Note("e'4"), Note("f'4"), Note("g'4")])

Returns a selection of leaf selections.

Example 4. Selects leaves grouped by measure:

>>> staff = Staff("abj: | 4/4 c'2 d'2 || 3/4 e'4 f'4 g'4 |")
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_class(Measure, flatten=True)
>>> selection = selector(staff)
>>> for measure in selection:
...     measure
...
Measure((4, 4), "c'2 d'2")
Measure((3, 4), "e'4 f'4 g'4")

Returns a measure selection.

>>> selector = selector.by_leaf()
>>> selections = selector(staff)
>>> for selection in selections:
...     selection
...
Selection([Note("c'2"), Note("d'2")])
Selection([Note("e'4"), Note("f'4"), Note("g'4")])

Returns a selection of leaf selections.

Example 5. Selects leaves:

>>> staff = Staff("abj: | 4/4 c'2 d'2 || 3/4 e'4 f'4 g'4 |")
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_class(Measure, flatten=True)
>>> selection = selector(staff)
>>> for measure in selection:
...     measure
...
Measure((4, 4), "c'2 d'2")
Measure((3, 4), "e'4 f'4 g'4")

Returns a measure selection.

>>> selector = selector.by_leaf(flatten=True)
>>> selection = selector(staff)
>>> for leaf in selection:
...     leaf
...
Note("c'2")
Note("d'2")
Note("e'4")
Note("f'4")
Note("g'4")

Returns a leaf selection.

Example 7. Selects leaves with flattening:

>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> show(staff) 
>>> f(staff)
\new Staff {
    c'8
    r8
    d'8
    e'8
    r8
    f'8
    g'8
    a'8
}
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(flatten=True)
>>> selection = selector(staff)
>>> selection
Selection([Note("c'8"), Rest('r8'), Note("d'8"), Note("e'8"), Rest('r8'), Note("f'8"), Note("g'8"), Note("a'8")])

Returns leaf selection.

Returns new selector.

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

Configures selector by length.

Example 1. Selects all runs of more than one note:

>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_run(Note)
>>> selector = selector.by_length('>', 1)
>>> for x in selector(staff):
...     x
...
Selection([Note("d'8"), Note("e'8")])
Selection([Note("f'8"), Note("g'8"), Note("a'8")])

Example 2. Selects all runs of less than three notes:

>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_run(Note)
>>> selector = selector.by_length('<', 3)
>>> for x in selector(staff):
...     x
...
Selection([Note("c'8")])
Selection([Note("d'8"), Note("e'8")])

Returns new selector.

Selector.by_logical_measure()

Configures selector by logical measure.

Returns new selector.

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

Configures selector by logical tie.

Example 1. Selects all logical ties:

>>> staff = Staff("c'8 d' ~ { d' e' r f'~ } f' r")
>>> container = staff[2]
>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie()
>>> for x in selector(staff):
...     x
...
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')])
>>> for x in selector(container):
...     x
...
LogicalTie([Note("d'8"), Note("d'8")])
LogicalTie([Note("e'8")])
LogicalTie([Rest('r8')])
LogicalTie([Note("f'8"), Note("f'8")])

Example 2. Selects pitched logical ties:

>>> staff = Staff("c'8 d' ~ { d' e' r f'~ } f' r")
>>> container = staff[2]
>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(
...     pitched=True,
...     )
>>> for x in selector(staff):
...     x
...
LogicalTie([Note("c'8")])
LogicalTie([Note("d'8"), Note("d'8")])
LogicalTie([Note("e'8")])
LogicalTie([Note("f'8"), Note("f'8")])
>>> for x in selector(container):
...     x
...
LogicalTie([Note("d'8"), Note("d'8")])
LogicalTie([Note("e'8")])
LogicalTie([Note("f'8"), Note("f'8")])

Example 3. Selects pitched nontrivial logical ties:

>>> staff = Staff("c'8 d' ~ { d' e' r f'~ } f' r")
>>> container = staff[2]
>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(
...     pitched=True,
...     trivial=False,
...     )
>>> for x in selector(staff):
...     x
...
LogicalTie([Note("d'8"), Note("d'8")])
LogicalTie([Note("f'8"), Note("f'8")])
>>> for x in selector(container):
...     x
...
LogicalTie([Note("d'8"), Note("d'8")])
LogicalTie([Note("f'8"), Note("f'8")])

Returns new selector.

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

Configures selector by pattern.

Todo

Merge into Selector.get_item().

Example 1. Selects logical tie at index 1:

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> pattern = patterntools.select([1])
>>> selector = selector.by_pattern(pattern=pattern)
>>> selection = selector(staff)
>>> for logical_tie in selection:
...     logical_tie
...
LogicalTie([Note("d'4"), Note("d'4")])

Returns selection of logical tie.

Example 2. Selects every second logical tie:

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> pattern = patterntools.select_every([0], period=2)
>>> selector = selector.by_pattern(pattern=pattern)
>>> selection = selector(staff)
>>> for logical_tie in selection:
...     logical_tie
...
LogicalTie([Note("c'4")])
LogicalTie([Note("e'4"), Note("e'4"), Note("e'4")])

Returns selection of logical ties.

Example 3. Selects every second leaf:

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> label(staff).with_indices(prototype=scoretools.Leaf)
>>> override(staff).text_script.staff_padding = 2
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(flatten=True)
>>> pattern = patterntools.select_every([0], period=2)
>>> selector = selector.by_pattern(pattern=pattern)
>>> selection = selector(staff)
>>> for note in selection:
...     print(staff.index(note), repr(note))
...
0 Note("c'4")
2 Note("d'4")
4 Note("e'4")
6 Rest('r4')

Returns selection of leaves.

Example 4. Selects every other leaf rotated one to the right:

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> label(staff).with_indices(prototype=scoretools.Leaf)
>>> override(staff).text_script.staff_padding = 2
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(flatten=True)
>>> pattern = patterntools.select_every([0], period=2)
>>> selector = selector.by_pattern(pattern=pattern)
>>> selection = selector(staff, rotation=1)
>>> for note in selection:
...     print(staff.index(note), repr(note))
...
1 Note("d'4")
3 Note("e'4")
5 Note("e'4")
7 Note("f'4")

Returns selection of leaves.

Example 5. Selects note at index 1 in each logical tie:

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> label(staff).with_indices(prototype=scoretools.Leaf)
>>> override(staff).text_script.staff_padding = 2
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> pattern = patterntools.select([1])
>>> selector = selector.by_pattern(
...     apply_to_each=True,
...     pattern=pattern,
...     )
>>> selection = selector(staff)
>>> for selection_ in selection:
...     note = selection_[0]
...     print(staff.index(note), repr(note))
... 
2 Note("d'4")
4 Note("e'4")

Returns a selection of note selections.

Returns new selector.

Selector.by_pitch(pitches=None)

Configures selector by pitch.

Example 1. Selects components matching a single pitch:

>>> staff = Staff("c'4 d'4 ~ d'4 e'4")
>>> staff.extend("r4 <c' e' g'>4 ~ <c' e' g'>2")
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(flatten=True)
>>> selector = selector.by_pitch(pitches="c'")
>>> for x in selector(staff):
...     x
...
Note("c'4")
Chord("<c' e' g'>4")
Chord("<c' e' g'>2")

Example 2. Selects components matching multiple pitches:

>>> staff = Staff("c'4 d'4 ~ d'4 e'4")
>>> staff.extend("r4 <c' e' g'>4 ~ <c' e' g'>2")
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf(flatten=True)
>>> selector = selector.by_pitch(pitches="c' e'")
>>> for x in selector(staff):
...     x
...
Note("c'4")
Note("e'4")
Chord("<c' e' g'>4")
Chord("<c' e' g'>2")

Example 3. Selects logical ties containing components matching multiple pitches:

>>> staff = Staff("c'4 d'4 ~ d'4 e'4")
>>> staff.extend("r4 <c' e' g'>4 ~ <c' e' g'>2")
>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie()
>>> selector = selector.by_pitch(pitches=NamedPitch('C4'))
>>> for x in selector(staff):
...     x
...
LogicalTie([Note("c'4")])
LogicalTie([Chord("<c' e' g'>4"), Chord("<c' e' g'>2")])

Returns new selector.

Selector.by_run(prototype=None)

Configures selector by run.

Example 1. Selects run of notes and chords at any depth:

>>> staff = Staff(r"c'8 d' r \times 2/3 { e' r f' } g' a' r")
>>> selector = selectortools.Selector()
>>> prototype = (Note, Chord)
>>> selector = selector.by_leaf()
>>> selector = selector.by_run(prototype)
>>> selections = selector(staff)
>>> for selection in selections:
...     selection
...
Selection([Note("c'8"), Note("d'8")])
Selection([Note("e'8")])
Selection([Note("f'8"), Note("g'8"), Note("a'8")])

Returns new selector.

Selector.first()

Gets first item in selection.

Example 1. Selects first pitched logical tie:

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> for logical_tie in selector(staff):
...     logical_tie
...
LogicalTie([Note("c'4")])
LogicalTie([Note("d'4"), Note("d'4")])
LogicalTie([Note("e'4"), Note("e'4"), Note("e'4")])
LogicalTie([Note("f'4")])
>>> selector = selector.first()
>>> selector(staff)
LogicalTie([Note("c'4")])

Returns new selector.

Selector.flatten(depth=-1)

Flattens selection.

Example 1. Selects all pitched logical ties except the first and last:

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> show(staff) 

Returns logical tie selection:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.middle()
>>> for logical_tie in selector(staff):
...     logical_tie
...
LogicalTie([Note("d'4"), Note("d'4")])
LogicalTie([Note("e'4"), Note("e'4"), Note("e'4")])

Returns leaf selection:

>>> selector = selector.flatten()
>>> selector(staff)
Selection([Note("d'4"), Note("d'4"), Note("e'4"), Note("e'4"), Note("e'4")])

Example 2. Selects leaves:

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> show(staff) 

Returns selection of leaf selections:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector(staff)
Selection([Selection([Note("c'4"), Note("d'4"), Note("d'4"), Note("e'4"), Note("e'4"), Note("e'4"), Rest('r4'), Note("f'4")])])

Returns leaf selection:

>>> selector = selector.flatten()
>>> selector(staff)
Selection([Note("c'4"), Note("d'4"), Note("d'4"), Note("e'4"), Note("e'4"), Note("e'4"), Rest('r4'), Note("f'4")])

Returns new selector.

Selector.get_item(item, apply_to_each=False)

Gets item in selection.

Maps the callback to each item in sequence when apply_to_each is true.

Applies the callback to the entire sequence when apply_to_each is false.

Example 1. Selects leaf at index 1:

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> show(staff) 

Returns selection of leaf selections:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.flatten()
>>> selector = selector.get_item(1)
>>> selector(staff)
Note("d'4")

Example 2. Selects logical tie at index 1:

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> show(staff) 

Returns selection of leaf selections:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.get_item(1)
>>> selector(staff)
LogicalTie([Note("d'4"), Note("d'4")])

Example 3. Selects the first note of each logical tie:

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> show(staff) 

Returns leaf selection:

>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.get_item(0, apply_to_each=True)
>>> selector(staff)
Selection([Note("c'4"), Note("d'4"), Note("e'4"), Note("f'4")])

Returns new selector.

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

Gets slice from start to stop in selection.

Maps the callback to each item in sequence when apply_to_each is true.

Applies the callback to the entire sequence when apply_to_each is false.

Example 1. Gets all notes (except the first) in each pitched logical tie:

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.get_slice(
...     start=1,
...     stop=None,
...     apply_to_each=True,
...     )
>>> logical_ties = selector(staff)
>>> for logical_tie in logical_ties:
...     logical_tie
...
LogicalTie([Note("d'4")])
LogicalTie([Note("e'4"), Note("e'4")])

Returns selection of logical ties.

Example 2. Gets all pitched logical ties (except the last):

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.get_slice(
...     start=None,
...     stop=-1,
...     apply_to_each=False,
...     )
>>> logical_ties = selector(staff)
>>> for logical_tie in logical_ties:
...     logical_tie
...
LogicalTie([Note("c'4")])
LogicalTie([Note("d'4"), Note("d'4")])
LogicalTie([Note("e'4"), Note("e'4"), Note("e'4")])

Returns selection of logical ties.

Example 3. Selects last three leaves:

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> show(staff) 

Returns leaf selection:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.flatten()
>>> selector = selector.get_slice(
...     start=-3,
...     apply_to_each=False,
...     )
>>> selector(staff)
Selection([Note("e'4"), Rest('r4'), Note("f'4")])

Returns new selector.

Selector.last()

Gets last item in selection.

Example 1. Selects the last pitched logical tie:

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.last()
>>> selector(staff)
LogicalTie([Note("f'4")])

Returns new selector.

Selector.middle()

Gets all but the first and last items in selection.

Example 1. Selects all pitched logical ties (except the first and last):

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.middle()
>>> for x in selector(staff):
...     x
...
LogicalTie([Note("d'4"), Note("d'4")])
LogicalTie([Note("e'4"), Note("e'4"), Note("e'4")])

Returns new selector.

Selector.most()

Gets all but the last item in selection.

Example 1. Selects all pitched logical ties (except the last):

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.most()
>>> for x in selector(staff):
...     x
...
LogicalTie([Note("c'4")])
LogicalTie([Note("d'4"), Note("d'4")])
LogicalTie([Note("e'4"), Note("e'4"), Note("e'4")])

Returns new selector.

Selector.partition_by_ratio(ratio)

Configures selector to partition by ratio.

Example 1. Partitions leaves by ratio of 1:1:

>>> staff = Staff(r"c'8 d' r \times 2/3 { e' r f' } g' a' r")
>>> label(staff).with_start_offsets()
>>> show(staff) 

Returns selection of leaf selection:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> result = selector(staff)
>>> for selection in result:
...     selection
...
Selection([Note("c'8"), Note("d'8"), Rest('r8'), Note("e'8"), Rest('r8'), Note("f'8"), Note("g'8"), Note("a'8"), Rest('r8')])

Returns selection of leaf selections:

>>> selector = selector.partition_by_ratio(mathtools.Ratio((1, 1)))
>>> result = selector(staff)
>>> for selection in result:
...     selection
...
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')])

Gets second leaf selection:

>>> selector = selector.get_item(1)
>>> selector(staff)
Selection([Note("f'8"), Note("g'8"), Note("a'8"), Rest('r8')])

Example 2. Partitions leaves by ratio of 1:1:1:

>>> staff = Staff(r"c'8 d' r \times 2/3 { e' r f' } g' a' r")
>>> label(staff).with_start_offsets()
>>> show(staff) 

Returns selection of leaf selection:

>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> result = selector(staff)
>>> for selection in result:
...     selection
...
Selection([Note("c'8"), Note("d'8"), Rest('r8'), Note("e'8"), Rest('r8'), Note("f'8"), Note("g'8"), Note("a'8"), Rest('r8')])

Return selection of leaf selections:

>>> selector = selector.partition_by_ratio(mathtools.Ratio((1, 1, 1)))
>>> result = selector(staff)
>>> for selection in result:
...     selection
...
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')])

Gets second leaf selection:

>>> selector = selector.get_item(1)
>>> selector(staff)
Selection([Note("e'8"), Rest('r8'), Note("f'8")])

Returns new selector.

Selector.rest()

Gets all but the first item in selection.

Example 1. Selects all pitched logical ties (except the first):

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> selector = selectortools.Selector()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.rest()
>>> for x in selector(staff):
...     x
...
LogicalTie([Note("d'4"), Note("d'4")])
LogicalTie([Note("e'4"), Note("e'4"), Note("e'4")])
LogicalTie([Note("f'4")])

Returns new selector.

Selector.with_next_leaf()

Configures selector with next leaf after each selection.

>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_run(Note)
>>> selector = selector.with_next_leaf()
>>> for x in selector(staff):
...     x
...
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")])

Handles flattened selections of leaves.

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.get_item(-1, apply_to_each=True)
>>> selector(staff)
Selection([Note("c'4"), Note("d'4"), Note("e'4"), Note("f'4")])
>>> selector = selector.with_next_leaf()
>>> for selection in selector(staff):
...     selection
...
Selection([Note("c'4"), Note("d'4")])
Selection([Note("d'4"), Note("e'4")])
Selection([Note("e'4"), Rest('r4')])
Selection([Note("f'4")])

Returns new selector.

Selector.with_previous_leaf()

Configures selector with previous leaf before each selection.

>>> staff = Staff("c'8 r8 d'8 e'8 r8 f'8 g'8 a'8")
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_run(Note)
>>> selector = selector.with_previous_leaf()
>>> for selection in selector(staff):
...     selection
...
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")])

Handles flattened selections of leaves.

>>> staff = Staff(r"c'4 d'4 ~ d'4 e'4 ~ e'4 ~ e'4 r4 f'4")
>>> show(staff) 
>>> selector = selectortools.Selector()
>>> selector = selector.by_leaf()
>>> selector = selector.by_logical_tie(pitched=True)
>>> selector = selector.get_item(0, apply_to_each=True)
>>> selector(staff)
Selection([Note("c'4"), Note("d'4"), Note("e'4"), Note("f'4")])
>>> selector = selector.with_previous_leaf()
>>> for selection in selector(staff):
...     selection
...
Selection([Note("c'4")])
Selection([Note("c'4"), Note("d'4")])
Selection([Note("d'4"), Note("e'4")])
Selection([Rest('r4'), Note("f'4")])

Returns new selector.

Class & static methods

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

Processes multiple selectors against a single selection.

Minimizes re-selection 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 x in result[selector]:
...     x
... 
Staff("c'4 d'8 e'8 f'4 g'8 a'4 b'8 c'8")
>>> for x in result[logical_tie_selector]:
...     x
... 
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 x in result[pitched_selector]:
...     x
... 
LogicalTie([Note("c'4")])
LogicalTie([Note("c'8")])
>>> for x in result[duration_selector]:
...     x
... 
LogicalTie([Note("d'8")])
LogicalTie([Note("e'8")])
LogicalTie([Note("g'8")])
LogicalTie([Note("b'8")])
LogicalTie([Note("c'8")])
>>> for x in result[contiguity_selector]:
...     x
...
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__(expr, rotation=None)

Calls selector on expr.

Returns a selection.

(AbjadValueObject).__copy__(*args)

Copies Abjad value object.

Returns new Abjad value object.

(AbjadValueObject).__eq__(expr)

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

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

Gets item in selector.

Returns another selector.

(AbjadValueObject).__hash__()

Hashes Abjad value object.

Returns integer.

(AbjadObject).__ne__(expr)

Is true when Abjad object does not equal expr. Otherwise false.

Returns true or false.

(AbjadObject).__repr__()

Gets interpreter representation of Abjad object.

Returns string.