Selection

class selectiontools.Selection(music=None)

A selection of components.

>>> staff = Staff("c'4 d'4 e'4 f'4")
>>> selection = selectiontools.Selection(staff[:])
>>> selection
Selection([Note("c'4"), Note("d'4"), Note("e'4"), Note("f'4")])

Lineage

digraph InheritanceGraph { graph [background=transparent, bgcolor=transparent, color=lightslategrey, fontname=Arial, outputorder=edgesfirst, overlap=prism, penwidth=2, rankdir=LR, root="__builtin__.object", splines=spline, style="dotted, rounded", truecolor=true]; node [colorscheme=pastel19, fontname=Arial, fontsize=12, penwidth=2, style="filled, rounded"]; edge [color=lightsteelblue2, penwidth=2]; subgraph cluster_selectiontools { graph [label=selectiontools]; "abjad.tools.selectiontools.Descendants.Descendants" [color=2, group=1, label=Descendants, shape=box]; "abjad.tools.selectiontools.Lineage.Lineage" [color=2, group=1, label=Lineage, shape=box]; "abjad.tools.selectiontools.LogicalTie.LogicalTie" [color=2, group=1, label=LogicalTie, shape=box]; "abjad.tools.selectiontools.Parentage.Parentage" [color=2, group=1, label=Parentage, shape=box]; "abjad.tools.selectiontools.Selection.Selection" [color=black, fontcolor=white, group=1, label=<<B>Selection</B>>, shape=box, style="filled, rounded"]; "abjad.tools.selectiontools.VerticalMoment.VerticalMoment" [color=2, group=1, label=VerticalMoment, shape=box]; "abjad.tools.selectiontools.Selection.Selection" -> "abjad.tools.selectiontools.Descendants.Descendants"; "abjad.tools.selectiontools.Selection.Selection" -> "abjad.tools.selectiontools.Lineage.Lineage"; "abjad.tools.selectiontools.Selection.Selection" -> "abjad.tools.selectiontools.LogicalTie.LogicalTie"; "abjad.tools.selectiontools.Selection.Selection" -> "abjad.tools.selectiontools.Parentage.Parentage"; "abjad.tools.selectiontools.Selection.Selection" -> "abjad.tools.selectiontools.VerticalMoment.VerticalMoment"; } subgraph cluster_builtins { graph [label=builtins]; "builtins.object" [color=1, group=0, label=object, shape=box]; } "builtins.object" -> "abjad.tools.selectiontools.Selection.Selection"; }

Bases

  • builtins.object

Attribute summary

by_class([prototype, reverse, start, stop, ...]) Select components by class.
by_leaf([prototype, reverse, start, stop, ...]) Select components by leaf.
by_logical_tie([nontrivial, pitched, ...]) Select components by logical tie.
by_run([prototype]) Select components by run.
by_timeline([prototype, reverse]) Select components by timeline.
by_timeline_and_logical_tie([nontrivial, ...]) Select components by timeline and logical tie.
get_duration([in_seconds]) Gets duration of contiguous selection.
get_spanners([prototype, in_parentage]) Gets spanners attached to any component in selection.
get_timespan([in_seconds]) Gets timespan of contiguous selection.
get_vertical_moment_at(offset) Select vertical moment at offset.
group_by(predicate) Groups components in contiguous selection by predicate.
partition_by_durations(durations[, cyclic, ...]) Partitions components according to durations.
__add__(expr) Cocatenates expr to selection.
__contains__(expr) Is true when expr is in selection.
__eq__(expr) Is true when selection and expr are of the same type and when music of selection equals music of expr.
__format__([format_specification]) Formats duration.
__getitem__(expr) Gets item expr from selection.
__hash__() Hashes selection.
__illustrate__() Attempts to illustrate selection.
__len__() Number of components in selection.
__ne__(expr) Is true when selection does not equal expr.
__radd__(expr) Concatenates selection to expr.
__repr__() Gets interpreter representation of selection.

Methods

Selection.by_class(prototype=None, reverse=False, start=0, stop=None, with_grace_notes=False)

Select components by class.

>>> staff = Staff()
>>> staff.append(Measure((2, 8), "c'8 d'8"))
>>> staff.append(Measure((2, 8), "e'8 f'8"))
>>> staff.append(Measure((2, 8), "g'8 a'8"))
>>> show(staff) 
>>> for note in select(staff).by_class(prototype=Note):
...     note
...
Note("c'8")
Note("d'8")
Note("e'8")
Note("f'8")
Note("g'8")
Note("a'8")

Returns new selection.

Selection.by_leaf(prototype=None, reverse=False, start=0, stop=None, with_grace_notes=False)

Select components by leaf.

>>> staff = Staff()
>>> staff.append(Measure((2, 8), "<c' bf'>8 <g' a'>8"))
>>> staff.append(Measure((2, 8), "af'8 r8"))
>>> staff.append(Measure((2, 8), "r8 gf'8"))
>>> show(staff) 
>>> for leaf in select(staff).by_leaf():
...     leaf
...
Chord("<c' bf'>8")
Chord("<g' a'>8")
Note("af'8")
Rest('r8')
Rest('r8')
Note("gf'8")

Returns new selection.

Selection.by_logical_tie(nontrivial=False, pitched=False, reverse=False, parentage_mask=None, with_grace_notes=False)

Select components by logical tie.

>>> staff = Staff(r"c'4 ~ \times 2/3 { c'16 d'8 } e'8 f'4 ~ f'16")
>>> show(staff) 
>>> for logical_tie in select(staff).by_logical_tie():
...     logical_tie
...
LogicalTie([Note("c'4"), Note("c'16")])
LogicalTie([Note("d'8")])
LogicalTie([Note("e'8")])
LogicalTie([Note("f'4"), Note("f'16")])

Returns new selection.

Selection.by_run(prototype=None)

Select components by run.

>>> staff = Staff(r"\times 2/3 { c'8 d'8 r8 }")
>>> staff.append(r"\times 2/3 { r8 <e' g'>8 <f' a'>8 }")
>>> staff.extend("g'8 a'8 r8 r8 <b' d''>8 <c'' e''>8")
>>> show(staff) 
>>> for group in select(staff[:]).by_run((Note, Chord)):
...     group
...
Selection([Note("g'8"), Note("a'8")])
Selection([Chord("<b' d''>8"), Chord("<c'' e''>8")])

Returns new selection.

Selection.by_timeline(prototype=None, reverse=False)

Select components by timeline.

>>> score = Score([])
>>> score.append(Staff("c'4 d'4 e'4 f'4"))
>>> score.append(Staff("g'8 a'8 b'8 c''8"))
>>> show(score) 
>>> for leaf in select(score).by_timeline():
...     leaf
...
Note("c'4")
Note("g'8")
Note("a'8")
Note("d'4")
Note("b'8")
Note("c''8")
Note("e'4")
Note("f'4")

Returns new selection.

Selection.by_timeline_and_logical_tie(nontrivial=False, pitched=False, reverse=False)

Select components by timeline and logical tie.

>>> score = Score([])
>>> score.append(Staff("c''4 ~ c''8 d''8 r4 ef''4"))
>>> score.append(Staff("r8 g'4. ~ g'8 r16 f'8. ~ f'8"))
>>> show(score) 
>>> for logical_tie in select(score).by_timeline_and_logical_tie():
...     logical_tie
...
LogicalTie([Note("c''4"), Note("c''8")])
LogicalTie([Rest('r8')])
LogicalTie([Note("g'4."), Note("g'8")])
LogicalTie([Note("d''8")])
LogicalTie([Rest('r4')])
LogicalTie([Rest('r16')])
LogicalTie([Note("f'8."), Note("f'8")])
LogicalTie([Note("ef''4")])

Returns new selection.

Selection.get_duration(in_seconds=False)

Gets duration of contiguous selection.

Returns duration.

Selection.get_spanners(prototype=None, in_parentage=False)

Gets spanners attached to any component in selection.

Returns set.

Selection.get_timespan(in_seconds=False)

Gets timespan of contiguous selection.

Returns timespan.

Selection.get_vertical_moment_at(offset)

Select vertical moment at offset.

Selection.group_by(predicate)

Groups components in contiguous selection by predicate.

Returns list of tuples.

Selection.partition_by_durations(durations, cyclic=False, fill=Exact, in_seconds=False, overhang=False)

Partitions components according to durations.

When fill is Exact then parts must equal durations exactly.

When fill is Less then parts must be less than or equal to durations.

When fill is More then parts must be greater or equal to durations.

Reads durations cyclically when cyclic is true.

Reads component durations in seconds when in_seconds is true.

Returns remaining components at end in final part when overhang is true.

Special methods

Selection.__add__(expr)

Cocatenates expr to selection.

Returns new selection.

Selection.__contains__(expr)

Is true when expr is in selection. Otherwise false.

Returns true or false.

Selection.__eq__(expr)

Is true when selection and expr are of the same type and when music of selection equals music of expr. Otherwise false.

Returns true or false.

Selection.__format__(format_specification='')

Formats duration.

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

Returns string.

Selection.__getitem__(expr)

Gets item expr from selection.

Returns component from selection.

Selection.__hash__()

Hashes selection.

Required to be explicitly redefined on Python 3 if __eq__ changes.

Returns integer.

Selection.__illustrate__()

Attempts to illustrate selection.

Evaluates the storage format of the selection (to sever any references to the source score from which the selection was taken). Then tries to wrap the result in a staff; in the case that notes of only C4 are found then sets the staff context name to 'RhythmicStaff'. If this works then the staff is wrapped in a LilyPond file and the file is returned. If this doesn’t work then the method raises an exception.

The idea is that the illustration should work for simple selections of that represent an essentially contiguous snippet of a single voice of music.

Returns LilyPond file.

Selection.__len__()

Number of components in selection.

Returns nonnegative integer.

Selection.__ne__(expr)

Is true when selection does not equal expr. Otherwise false.

Returns true or false.

Selection.__radd__(expr)

Concatenates selection to expr.

Returns newly created selection.

Selection.__repr__()

Gets interpreter representation of selection.

Returns string.