Parentage

class selectiontools.Parentage(component=None, include_self=True, with_grace_notes=False)

Parentage of a component.

>>> import abjad
>>> score = abjad.Score()
>>> string = r"""\new Voice = "Treble Voice" { e'4 }"""
>>> treble_staff = abjad.Staff(string, name='Treble Staff')
>>> score.append(treble_staff)
>>> string = r"""\new Voice = "Bass Voice" { c4 }"""
>>> bass_staff = abjad.Staff(string, name='Bass Staff')
>>> clef = abjad.Clef('bass')
>>> abjad.attach(clef, bass_staff[0][0])
>>> score.append(bass_staff)
>>> show(score) 
>>> bass_voice = score['Bass Voice']
>>> note = bass_voice[0]
>>> for component in abjad.inspect(note).get_parentage():
...     component
...
Note('c4')
Voice('c4', name='Bass Voice')
<Staff-"Bass Staff"{1}>
<Score<<2>>>

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

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.
component The component from which the selection was derived.
depth Length of proper parentage of component.
get_duration([in_seconds]) Gets duration of contiguous selection.
get_first([prototype]) Gets first instance of prototype in parentage.
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.
is_grace_note Is true when parentage contains a grace container.
is_orphan Is true when component has no parent.
logical_voice Gets logical voice.
parent Gets parent.
partition_by_durations(durations[, cyclic, …]) Partitions selection by durations.
prolation Gets prolation.
root Gets root.
score_index Gets score index.
tuplet_depth Gets tuplet depth.
__add__(argument) Cocatenates argument to selection.
__contains__(argument) Is true when argument is in selection.
__eq__(argument) Is true when selection and argument are of the same type and when music of selection equals music of argument.
__format__([format_specification]) Formats duration.
__getitem__(argument) Gets item or slice identified by argument.
__hash__() Hashes selection.
__illustrate__() Attempts to illustrate selection.
__len__() Gets number of components in selection.
__ne__(argument) Is true when self does not equal argument.
__radd__(argument) Concatenates selection to argument.
__repr__() Gets interpreter representation of selection.

Read-only properties

Parentage.component

The component from which the selection was derived.

Returns component.

Parentage.depth

Length of proper parentage of component.

Returns nonnegative integer.

Parentage.is_grace_note

Is true when parentage contains a grace container. Otherwise false.

Grace notes:

>>> voice = abjad.Voice("c'4 d'4 e'4 f'4")
>>> container = abjad.GraceContainer("c'16 d'16")
>>> abjad.attach(container, voice[1])
>>> show(voice) 
>>> for leaf in abjad.iterate(voice).by_leaf(
...     with_grace_notes=True,
...     ):
...     parentage = abjad.inspect(leaf).get_parentage()
...     print(leaf, parentage.is_grace_note)
...
c'4 False
c'16 True
d'16 True
d'4 False
e'4 False
f'4 False

Returns true or false.

Parentage.is_orphan

Is true when component has no parent. Otherwise false.

Returns true or false.

Parentage.logical_voice

Gets logical voice.

Gets logical voice of note:

>>> voice = abjad.Voice("c'4 d'4 e'4 f'4", name='CustomVoice')
>>> staff = abjad.Staff([voice], name='CustomStaff')
>>> score = abjad.Score([staff], name='CustomScore')
>>> show(score) 
>>> note = voice[0]
>>> parentage = abjad.inspect(note).get_parentage()
>>> logical_voice = parentage.logical_voice
>>> for key, value in logical_voice.items():
...     print('%12s: %s' % (key, value))
... 
       score: Score-'CustomScore'
 staff group: 
       staff: Staff-'CustomStaff'
       voice: Voice-'CustomVoice'

Returns ordered dictionary.

Parentage.parent

Gets parent.

Returns none when component has no parent.

Returns component or none.

Parentage.prolation

Gets prolation.

Returns multiplier.

Parentage.root

Gets root.

Root defined equal to last component in parentage.

Returns component.

Parentage.score_index

Gets score index.

Todo

Define score index for grace notes.

Gets note score indices:

>>> staff_1 = abjad.Staff(r"\times 2/3 { c''2 b'2 a'2 }")
>>> staff_2 = abjad.Staff("c'2 d'2")
>>> score = abjad.Score([staff_1, staff_2])
>>> show(score) 
>>> selector = abjad.select().by_leaf(flatten=True)
>>> leaves = selector(score)
>>> for leaf in leaves:
...     parentage = abjad.inspect(leaf).get_parentage()
...     leaf, parentage.score_index
...
(Note("c''2"), (0, 0, 0))
(Note("b'2"), (0, 0, 1))
(Note("a'2"), (0, 0, 2))
(Note("c'2"), (1, 0))
(Note("d'2"), (1, 1))

With grace notes:

>>> voice = abjad.Voice("c'8 [ d'8 e'8 f'8 ]")
>>> container = abjad.GraceContainer("cf''16 bf'16")
>>> abjad.attach(container, voice[1])
>>> show(voice) 
>>> leaves = abjad.iterate(voice).by_class(
...     with_grace_notes=True,
...     )
>>> for leaf in leaves:
...     parentage = abjad.inspect(leaf).get_parentage()
...     leaf, parentage.score_index
...
(Voice("c'8 d'8 e'8 f'8"), ())
(Note("c'8"), (0,))
(Note("cf''16"), (0,))
(Note("bf'16"), (1,))
(Note("d'8"), (1,))
(Note("e'8"), (2,))
(Note("f'8"), (3,))

Todo

Incorrect values returned for grace notes.

Returns tuple of zero or more nonnegative integers.

Parentage.tuplet_depth

Gets tuplet depth.

Gets tuplet depth:

>>> tuplet = abjad.Tuplet((2, 3), "c'2 d'2 e'2")
>>> staff = abjad.Staff([tuplet])
>>> note = tuplet[0]
>>> show(staff) 
>>> abjad.inspect(note).get_parentage().tuplet_depth
1
>>> abjad.inspect(tuplet).get_parentage().tuplet_depth
0
>>> abjad.inspect(staff).get_parentage().tuplet_depth
0

Returns nonnegative integer.

Methods

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

Select components by class.

>>> staff = abjad.Staff()
>>> staff.append(abjad.Measure((2, 8), "c'8 d'8"))
>>> staff.append(abjad.Measure((2, 8), "e'8 f'8"))
>>> staff.append(abjad.Measure((2, 8), "g'8 a'8"))
>>> show(staff) 
>>> for note in abjad.select(staff).by_class(prototype=abjad.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 = abjad.Staff()
>>> staff.append(abjad.Measure((2, 8), "<c' bf'>8 <g' a'>8"))
>>> staff.append(abjad.Measure((2, 8), "af'8 r8"))
>>> staff.append(abjad.Measure((2, 8), "r8 gf'8"))
>>> show(staff) 
>>> for leaf in abjad.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.

>>> string = r"c'4 ~ \times 2/3 { c'16 d'8 } e'8 f'4 ~ f'16"
>>> staff = abjad.Staff(string)
>>> show(staff) 
>>> for logical_tie in abjad.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 = abjad.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) 
>>> prototype = (abjad.Note, abjad.Chord)
>>> for group in abjad.select(staff[:]).by_run(prototype):
...     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 = abjad.Score()
>>> score.append(abjad.Staff("c'4 d'4 e'4 f'4"))
>>> score.append(abjad.Staff("g'8 a'8 b'8 c''8"))
>>> show(score) 
>>> for leaf in abjad.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 = abjad.Score()
>>> score.append(abjad.Staff("c''4 ~ c''8 d''8 r4 ef''4"))
>>> score.append(abjad.Staff("r8 g'4. ~ g'8 r16 f'8. ~ f'8"))
>>> show(score) 
>>> for logical_tie in abjad.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.

Parentage.get_first(prototype=None)

Gets first instance of prototype in parentage.

Returns component or none.

(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.

>>> maker = abjad.LeafMaker()
>>> leaves = maker([0, 2, 4, None, None, 5, 7], [(1, 8)])
>>> staff = abjad.Staff(leaves)
>>> show(staff) 
>>> for group in leaves.group_by(type):
...     group
...
(Note("c'8"), Note("d'8"), Note("e'8"))
(Rest('r8'), Rest('r8'))
(Note("f'8"), Note("g'8"))

Returns list of tuples.

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

Partitions selection by durations.

Cyclically partitions exactly 3/8 (of a whole note) with overhang returned at end:

>>> staff = abjad.Staff(
...     "abj: | 2/8 c'8 d'8 || 2/8 e'8 f'8 |"
...     "| 2/8 g'8 a'8 || 2/8 b'8 c''8 |"
...     )
>>> show(staff) 
>>> leaves = abjad.select(staff).by_leaf()
>>> selections = leaves.partition_by_durations(
...     [abjad.Duration(3, 8)],
...     cyclic=True,
...     fill=Exact,
...     in_seconds=False,
...     overhang=True,
...     )
>>> for selection in selections:
...     selection
...
Selection([Note("c'8"), Note("d'8"), Note("e'8")])
Selection([Note("f'8"), Note("g'8"), Note("a'8")])
Selection([Note("b'8"), Note("c''8")])

Partitions exactly 3/8 (of a whole note) one time only:

>>> staff = abjad.Staff(
...     "abj: | 2/8 c'8 d'8 || 2/8 e'8 f'8 |"
...     "| 2/8 g'8 a'8 || 2/8 b'8 c''8 |"
...     )
>>> show(staff) 
>>> leaves = abjad.select(staff).by_leaf()
>>> selections = leaves.partition_by_durations(
...     [abjad.Duration(3, 8)],
...     cyclic=False,
...     fill=Exact,
...     in_seconds=False,
...     overhang=False,
...     )
>>> for selection in selections:
...     selection
...
Selection([Note("c'8"), Note("d'8"), Note("e'8")])

Cyclically partitions 3/16 and 1/16 (of a whole note) with part durations allowed to be just more than 3/16 and 1/16 (of a whole note) and with overhang returned at end:

>>> staff = abjad.Staff(
...     "abj: | 2/8 c'8 d'8 || 2/8 e'8 f'8 |"
...     "| 2/8 g'8 a'8 || 2/8 b'8 c''8 |"
...     )
>>> show(staff) 
>>> leaves = abjad.select(staff).by_leaf()
>>> selections = leaves.partition_by_durations(
...     [abjad.Duration(3, 16), abjad.Duration(1, 16)],
...     cyclic=True,
...     fill=More,
...     in_seconds=False,
...     overhang=True,
...     )
>>> for selection in selections:
...     selection
...
Selection([Note("c'8"), Note("d'8")])
Selection([Note("e'8")])
Selection([Note("f'8"), Note("g'8")])
Selection([Note("a'8")])
Selection([Note("b'8"), Note("c''8")])

Cyclically partitions 3/16 (of a whole note) with part durations allowed to be just less than 3/16 (of a whole note):

>>> staff = abjad.Staff(
...     "abj: | 2/8 c'8 d'8 || 2/8 e'8 f'8 |"
...     "| 2/8 g'8 a'8 || 2/8 b'8 c''8 |"
...     )
>>> show(staff) 
>>> leaves = abjad.select(staff).by_leaf()
>>> selections = leaves.partition_by_durations(
...     [abjad.Duration(3, 16)],
...     cyclic=True,
...     fill=Less,
...     in_seconds=False,
...     overhang=False,
...     )
>>> for selection in selections:
...     selection
...
Selection([Note("c'8")])
Selection([Note("d'8")])
Selection([Note("e'8")])
Selection([Note("f'8")])
Selection([Note("g'8")])
Selection([Note("a'8")])
Selection([Note("b'8")])

Partitions 3/16 (of a whole note) just once with part duration allowed to be just less than 3/16 (of a whole note):

>>> staff = abjad.Staff(
...     "abj: | 2/8 c'8 d'8 || 2/8 e'8 f'8 |"
...     "| 2/8 g'8 a'8 || 2/8 b'8 c''8 |"
...     )
>>> show(staff) 
>>> leaves = abjad.select(staff).by_leaf()
>>> selections = leaves.partition_by_durations(
...     [abjad.Duration(3, 16)],
...     cyclic=False,
...     fill=Less,
...     in_seconds=False,
...     overhang=False,
...     )
>>> for selection in selections:
...     selection
...
Selection([Note("c'8")])

Examples in seconds appear below.

Cyclically partitions exactly 1.5 seconds at a time:

>>> staff = abjad.Staff(
...     "abj: | 2/8 c'8 d'8 || 2/8 e'8 f'8 |"
...     "| 2/8 g'8 a'8 || 2/8 b'8 c''8 |"
...     )
>>> mark = abjad.MetronomeMark((1, 4), 60)
>>> leaf = abjad.inspect(staff).get_leaf(0)
>>> abjad.attach(mark, leaf, scope=abjad.Staff)
>>> show(staff) 
>>> leaves = abjad.select(staff).by_leaf()
>>> selections = leaves.partition_by_durations(
...     [1.5],
...     cyclic=True,
...     fill=Exact,
...     in_seconds=True,
...     overhang=False,
...     )
>>> for selection in selections:
...     selection
...
Selection([Note("c'8"), Note("d'8"), Note("e'8")])
Selection([Note("f'8"), Note("g'8"), Note("a'8")])

Cyclically partitions exactly 1.5 seconds at a time with overhang returned at end:

>>> staff = abjad.Staff(
...     "abj: | 2/8 c'8 d'8 || 2/8 e'8 f'8 |"
...     "| 2/8 g'8 a'8 || 2/8 b'8 c''8 |"
...     )
>>> mark = abjad.MetronomeMark((1, 4), 60)
>>> leaf = abjad.inspect(staff).get_leaf(0)
>>> abjad.attach(mark, leaf, scope=abjad.Staff)
>>> show(staff) 
>>> leaves = abjad.select(staff).by_leaf()
>>> selections = leaves.partition_by_durations(
...     [1.5],
...     cyclic=True,
...     fill=Exact,
...     in_seconds=True,
...     overhang=True,
...     )
>>> for selection in selections:
...     selection
...
Selection([Note("c'8"), Note("d'8"), Note("e'8")])
Selection([Note("f'8"), Note("g'8"), Note("a'8")])
Selection([Note("b'8"), Note("c''8")])

Partitions exactly 1.5 seconds one time only:

>>> staff = abjad.Staff(
...     "abj: | 2/8 c'8 d'8 || 2/8 e'8 f'8 |"
...     "| 2/8 g'8 a'8 || 2/8 b'8 c''8 |"
...     )
>>> mark = abjad.MetronomeMark((1, 4), 60)
>>> leaf = abjad.inspect(staff).get_leaf(0)
>>> abjad.attach(mark, leaf, scope=abjad.Staff)
>>> show(staff) 
>>> leaves = abjad.select(staff).by_leaf()
>>> selections = leaves.partition_by_durations(
...     [1.5],
...     cyclic=False,
...     fill=Exact,
...     in_seconds=True,
...     overhang=False,
...     )
>>> for selection in selections:
...     selection
...
Selection([Note("c'8"), Note("d'8"), Note("e'8")])

Cyclically partitions 0.75 seconds with part durations allowed to be just less than 0.75 seconds:

>>> staff = abjad.Staff(
...     "abj: | 2/8 c'8 d'8 || 2/8 e'8 f'8 |"
...     "| 2/8 g'8 a'8 || 2/8 b'8 c''8 |"
...     )
>>> mark = abjad.MetronomeMark((1, 4), 60)
>>> leaf = abjad.inspect(staff).get_leaf(0)
>>> abjad.attach(mark, leaf, scope=abjad.Staff)
>>> show(staff) 
>>> leaves = abjad.select(staff).by_leaf()
>>> selections = leaves.partition_by_durations(
...     [0.75],
...     cyclic=True,
...     fill=Less,
...     in_seconds=True,
...     overhang=False,
...     )
>>> for selection in selections:
...     selection
...
Selection([Note("c'8")])
Selection([Note("d'8")])
Selection([Note("e'8")])
Selection([Note("f'8")])
Selection([Note("g'8")])
Selection([Note("a'8")])
Selection([Note("b'8")])

Partitions 0.75 seconds just once with part duration allowed to be just less than 0.75 seconds:

>>> staff = abjad.Staff(
...     "abj: | 2/8 c'8 d'8 || 2/8 e'8 f'8 |"
...     "| 2/8 g'8 a'8 || 2/8 b'8 c''8 |"
...     )
>>> mark = abjad.MetronomeMark((1, 4), 60)
>>> leaf = abjad.inspect(staff).get_leaf(0)
>>> abjad.attach(mark, leaf, scope=abjad.Staff)
>>> show(staff) 
>>> leaves = abjad.select(staff).by_leaf()
>>> selections = leaves.partition_by_durations(
...     [0.75],
...     cyclic=False,
...     fill=Less,
...     in_seconds=True,
...     overhang=False,
...     )
>>> for selection in selections:
...     selection
...
Selection([Note("c'8")])

Parts must equal durations exactly when fill is Exact.

Parts must be less than or equal to durations when fill is Less.

Parts must be greater or equal to durations when fill is More.

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.

Returns list of selections.

Special methods

(Selection).__add__(argument)

Cocatenates argument to selection.

Returns new selection.

(Selection).__contains__(argument)

Is true when argument is in selection. Otherwise false.

Returns true or false.

(Selection).__eq__(argument)

Is true when selection and argument are of the same type and when music of selection equals music of argument. 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__(argument)

Gets item or slice identified by argument.

Returns component from selection.

(Selection).__hash__()

Hashes selection.

Note

Hash defines explicitly in terms of storage format. Most Abjad classes don’t need to do this. But selection classes do need to.

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

Gets number of components in selection.

Returns nonnegative integer.

(Selection).__ne__(argument)

Is true when self does not equal argument.

Note

this definition can be removed after support for Python is dropped.

Returns true or false.

(Selection).__radd__(argument)

Concatenates selection to argument.

Returns newly created selection.

(Selection).__repr__()

Gets interpreter representation of selection.

Returns string.