rhSrSSKJr SSKJrJr SSKrSSKrSSKr SSK r SSK r SSK J r SSK Jr SSK Jr SSKJr SS KJr \ R&(aSS KJr \R,"S 5r"S S \R05r"SS\R45r"SS\ R85r\S:XaSSK r \ R>"\5 gg)z Tools for grouping elements, timespans, and especially pitched elements into kinds of searchable tree organized by start and stop offsets and other positions. ) annotations) GeneratorIterableN)common) environment) exceptions21)spans)treesVerticalitySequenceztree.timespanTreec\rSrSrSrg)TimespanTreeException+N)__name__ __module__ __qualname____firstlineno____static_attributes__rS/home/james-whalen/.local/lib/python3.13/site-packages/music21/tree/timespanTree.pyrr+srrc8\rSrSrSrSr\S5r\S5rSr \ S5r SS jr SS jr SSS jjrSSS jjrS rSrSSSjjrS SSS.S!SjjjrSrSr\S5rSrSr\ S5r\R4S5rSrg)" TimespanTree0a A TimespanTree is a data structure for efficiently slicing a score for pitches, or, like all :class:`~music21.tree.trees.OffsetTree` objects, for searching large scores quickly by time. While you can construct an TimespanTree by hand, inserting timespans one at a time, the common use-case is to construct the TimespanTree from an entire score at once: >>> bach = corpus.parse('bwv66.6') >>> scoreTree = tree.fromStream.asTimespans(bach, flatten=True, ... classList=(note.Note, chord.Chord)) From this representation, we can get what is happening at any given moment as a :class:`~music21.tree.verticality.Verticality` object. >>> print(scoreTree.getVerticalityAt(17.0)) The equivalent call from the stream itself is: `bach.asTrees(flatten=True, asTimespans=True, classList=(note.Note, chord.Chord))` All offsets are assumed to be relative to the score's source if flatten is True Example: How many moments in Bach are consonant and how many are dissonant: >>> totalConsonances = 0 >>> totalDissonances = 0 >>> for v in scoreTree.iterateVerticalities(): ... if v.toChord().isConsonant(): ... totalConsonances += 1 ... else: ... totalDissonances += 1 >>> (totalConsonances, totalDissonances) (34, 17) So 1/3 of the vertical moments in Bach are dissonant! But is this an accurate perception? Let's sum up the total consonant duration vs. dissonant duration. Since verticality objects do not know their end times, we can iterate pairwise to figure out the length. We add "padEnd=True" to include a dummy verticality at the end so that it includes the last object: >>> totalConsonanceDuration = 0 >>> totalDissonanceDuration = 0 >>> iterator = scoreTree.iterateVerticalitiesNwise(n=2, padEnd=True) >>> for verticality1, verticality2 in iterator: ... offset1 = verticality1.offset ... offset2 = verticality2.offset ... quarterLength = offset2 - offset1 ... if verticality1.toChord().isConsonant(): ... totalConsonanceDuration += quarterLength ... else: ... totalDissonanceDuration += quarterLength >>> (totalConsonanceDuration, totalDissonanceDuration) (26.5, 9.5) Example: Remove neighbor tones from the Bach chorale. (It's actually quite viscous in its pruning.) Here in Alto, measure 7, there's a neighbor tone E#. >>> bach.parts['#Alto'].measure(7).show('text') {0.0} {0.5} {1.0} {1.5} {2.0} We'll get rid of it and a lot of other neighbor tones. >>> for verticalities in scoreTree.iterateVerticalitiesNwise(n=3): ... horizontalities = scoreTree.unwrapVerticalities(verticalities) ... for unused_part, horizontality in horizontalities.items(): ... if horizontality.hasNeighborTone: ... merged = horizontality[0].new( ... endTime=horizontality[2].endTime, ... ) # merged is a new PitchedTimespan ... scoreTree.removeTimespan(horizontality[0]) ... scoreTree.removeTimespan(horizontality[1]) ... scoreTree.removeTimespan(horizontality[2]) ... scoreTree.insert(merged) >>> #_DOCS_SHOW newBach = tree.toStream.partwise(scoreTree, templateStream=bach) >>> #_DOCS_SHOW newBach.parts['#Alto'].measure(7).show('text') {0.0} {1.5} {2.0} The second F# is an octave lower, so it wouldn't get merged even if adjacent notes were fused together (which they're not). .. note:: TimespanTree is an implementation of an extended AVL tree. AVL trees are a type of binary tree, like Red-Black trees. AVL trees are very efficient at insertion when the objects being inserted are already sorted - which is usually the case with data extracted from a score. TimespanTree is an extended AVL tree because each node in the tree keeps track of not just the start offsets of PitchedTimespans stored at that node, but also the earliest and latest stop offset of all PitchedTimespans stores at both that node and all nodes which are children of that node. This lets us quickly located PitchedTimespans which overlap offsets or which are contained within ranges of offsets. This also means that the contents of a TimespanTree are always sorted. OMIT_FROM_DOCS TODO: Doc examples for all functions, including privates. rcUR$NendTimexs r_insertCorePayloadSortKey&TimespanTree._insertCorePayloadSortKeys yyrcUR$)z Use so that both OffsetTrees, which have elements which do not have a .endTime, and TimespanTrees, which have element that have an .endTime but not a duration, can use most of the same code. r)el unused_nodes relementEndTimeTimespanTree.elementEndTimeszzrcURnURU5nUbXR;a[USUS35eURR U5UR -nU$)a# Gets index of a TimeSpan in a TimespanTree. Since Timespans do not have .sites, there is only one offset to deal with >>> tsList = [(0, 2), (0, 9), (1, 1), (2, 3), (3, 4), ... (4, 9), (5, 6), (5, 8), (6, 8), (7, 7)] >>> ts = [tree.spans.Timespan(x, y) for x, y in tsList] >>> tsTree = tree.timespanTree.TimespanTree() >>> tsTree.insert(ts) >>> for timespan in ts: ... print("%r %s" % (timespan, tsTree.index(timespan))) ... 0 1 2 3 4 5 6 7 8 9 >>> tsTree.index(tree.spans.Timespan(-100, 100)) Traceback (most recent call last): ValueError: not in Tree at offset -100.0. z not in Tree at offset .)offsetgetNodeByPositionpayload ValueErrorindexpayloadElementsStartIndex)selfspanr*noder.s rr.TimespanTree.indexsh<%%f- <4||3v%>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans(classList=(note.Note,)) >>> timespan = scoreTree[0] >>> timespan > >>> timespan.part >>> timespan = scoreTree.findNextPitchedTimespanInSameStreamByClass(timespan) >>> timespan > >>> timespan.part >>> timespan = scoreTree.findNextPitchedTimespanInSameStreamByClass(timespan) >>> timespan > >>> timespan.part rstreamNPitchedTimespan , must be an PitchedTimespan) music21rGPart isinstancer PitchedTimespanrgetVerticalityAtr*nextVerticalitystartTimespansgetParentageByClass)r0pitchedTimespan classListrGmessage verticalitynextPitchedTimespans r*findNextPitchedTimespanInSameStreamByClass7TimespanTree.findNextPitchedTimespanInSameStreamByClasssB #  I/5+@+@AA((;;WXG'0 0++O,B,BC %%55K"'2'A'A#';;IF';;IFG..(B %rcnSSKJn Uc UR4n[U[R 5(dSU<S3n[ U5eURUR5nUbPURnUcgURH*nURU5URU5LdM(Us $ UbMOgg)a Finds next element timespan in the same Part/Measure, etc. (specify in classList) as the `pitchedTimespan`. >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans(classList=(note.Note,)) >>> timespan = scoreTree[-1] >>> timespan > >>> timespan.part >>> timespan = scoreTree.findPreviousPitchedTimespanInSameStreamByClass(timespan) >>> timespan > >>> timespan.part >>> timespan = scoreTree.findPreviousPitchedTimespanInSameStreamByClass(timespan) >>> timespan > >>> timespan.part rrFNrHrI) rJrGrKrLr rMrrNr*previousVerticalityrPrQ)r0rRrSrGrTrUpreviousPitchedTimespans r.findPreviousPitchedTimespanInSameStreamByClass;TimespanTree.findPreviousPitchedTimespanInSameStreamByClass's@ #  I/5+@+@AA((;;WXG'0 0++O,B,BC %%99K"+6+E+E'+?? J';;IFG22,F %rcbURU5nUR(d URnU$)a Gets the :class:`~music21.tree.verticality.Verticality` in this TimeSpanTree which starts at `offset`. If the found Verticality has no start timespans, the function returns the next previous verticality with start timespans. >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans() >>> scoreTree.getVerticalityAtOrBefore(0.125) >>> scoreTree.getVerticalityAtOrBefore(0.0) )rNrPrZ)r0r*rUs rgetVerticalityAtOrBefore%TimespanTree.getVerticalityAtOrBeforeWs. ++F3 ))%99Krc## UR5n[U5nUR5R 5(d1[U5nUR5R 5(dM1U/nUHXnUR U5 UR5R 5(dM9[ U5S:a [U5v U/nMZ g![a gf=f![a gf=f7f)aU Iterates consonant-bounded verticality subsequences in this offset-tree. >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans() >>> for subsequence in scoreTree.iterateConsonanceBoundedVerticalities(): ... print('Subsequence:') ... for verticality in subsequence: ... verticalityChord = verticality.toChord() ... print(f'\t[{verticality.measureNumber}] ' ... + f'{verticality}: {verticalityChord.isConsonant()}') ... Subsequence: [2] : True [2] : False [2] : True Subsequence: [3] : True [3] : False [3] : True Subsequence: [3] : True [3] : False [3] : True Subsequence: [3] : True [4] : False [4] : False [4] : True Subsequence: [4] : True [4] : False [4] : True Subsequence: [4] : True [4] : False [4] : True Subsequence: [5] : True [5] : False [5] : True Subsequence: [6] : True [7] : False [7] : True Subsequence: [7] : True [7] : False [7] : True Subsequence: [8] : True [8] : False [8] : False [8] : False [8] : False [8] : False [9] : True Subsequence: [9] : True [9] : False [9] : True Subsequence: [9] : True [9] : False [9] : True N)iterateVerticalitiesnext StopIterationtoChord isConsonantappendlentuple)r0iteratorstartingVerticalityverticalityBufferrUs r%iterateConsonanceBoundedVerticalities2TimespanTree.iterateConsonanceBoundedVerticalitieslsJ,,. "&x. &--/;;== &*8n#&--/;;== 11#K  $ $[ 1""$0022()A- 122%0M! $    !  sWC5 C#C5 C%#C53:C51$C5 C"C5!C""C5% C2/C51C22C5Fc#D# U(aKUR5nURU5nUv URnUbUv URnUbMggUR5nURU5nUv URnUbUv URnUbMgg7f)a Iterates all vertical moments in this TimespanTree, represented as :class:`~music21.tree.verticality.Verticality` objects. .. note:: The TimespanTree can be mutated while its verticalities are iterated over. Each verticality holds a reference back to the TimespanTree and will ask for the start-offset after (or before) its own start offset in order to determine the next verticality to yield. If you mutate the tree by adding or deleting timespans, the next verticality will reflect those changes. >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans(classList=(note.Note,)) >>> iterator = scoreTree.iterateVerticalities() >>> for _ in range(10): ... next(iterator) ... Verticalities can also be iterated in reverse: >>> iterator = scoreTree.iterateVerticalities(reverse=True) >>> for _ in range(10): ... next(iterator) ... N)highestPositionrNrZr5rO)r0reverser*rUs rrc!TimespanTree.iterateVerticalitiessb ))+F//7K %99K)!!)== )((*F//7K %55K)!!)99 )sAB A B B )rrpadEndc#~# SSKJnJn [U5nUS::aSnUSU3- n[ U5eU"UR US9nU(a U/US- -nO/n[ R"[R"URUS9U5UU5H)n U(d U"U 5v MU"[U 55v M+ g7f) a Iterates :class:`~music21.tree.verticality.Verticality` objects in groups of length `n`. .. note:: The TimespanTree can be mutated while its verticalities are iterated over. Each verticality holds a reference back to the TimespanTree and will ask for the start-offset after (or before) its own start offset in order to determine the next verticality to yield. If you mutate the tree by adding or deleting timespans, the next verticality will reflect those changes. >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans(classList=(note.Note,)) >>> iterator = scoreTree.iterateVerticalitiesNwise(n=2) >>> for _ in range(4): ... print(next(iterator)) ... Grouped verticalities can also be iterated in reverse, but note that the groups within each iteration are still ordered from earliest to last. >>> iterator = scoreTree.iterateVerticalitiesNwise(n=2, reverse=True) >>> for _ in range(4): ... print(next(iterator)) ... When iterating with `n > 1` and `padEnd=True` will put sentinel Verticalities in the last VerticalitySequences that occur at the `endTime` of the tree, with no elements: >>> iterator = scoreTree.iterateVerticalitiesNwise(n=3, padEnd=True) >>> for v in iterator: ... pass >>> v * Changed in v8: added padEnd. Streams with fewer than n elements also return an empty sentinel entry. r)r Verticalityz4The number of verticalities in the group must be at zleast one. Got ) timespanTree)rrN) music21.tree.verticalityr rvintrrmore_itertoolswindowed itertoolschainrcreversed) r0nrrrtr rvrTsentinelVerticalityending verticalitiess riterateVerticalitiesNwise&TimespanTree.iterateVerticalitiesNwises\ N F 6LG , ,G'0 0)$,,TJ )*a!e4FF+44 OOD55g5F O  M )-88)(=*ABB sB;B=c[U[5(dU/nUHYnURU5nU(dMUH6nURU5 UR U5nUR U5 M8 M[ g)ai Splits all timespans in this TimespanTree at `offsets`, operating in place. >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans() >>> scoreTree.elementsStartingAt(0.1) () >>> for timespan in scoreTree.elementsOverlappingOffset(0.1): ... print("%r, %s" % (timespan, timespan.part.id)) ... >, Soprano >, Tenor >, Bass >, Alto Note that the Alto is last in both of these because currently the sorting is done according to the endTime -- potentially to be changed soon. >>> scoreTree.splitAt(0.1) >>> for timespan in scoreTree.elementsStartingAt(0.1): ... print("%r, %s" % (timespan, timespan.part.id)) ... >, Soprano >, Tenor >, Bass >, Alto >>> scoreTree.elementsOverlappingOffset(0.1) () N)rLrelementsOverlappingOffsetrCsplitAtinsert)r0r=r*overlapsoverlapshardss rrTimespanTree.splitAtskB'8,,iGF55f=H###G, 0 F#$ rc0nUR5Hn[5X'M UH"nXRnURU5 M$ U$)a. Returns a dictionary of TimespanTrees where each entry is indexed by a Part object (TODO: Don't use mutable objects as hash keys!) and each key is a TimeSpan tree containing only element timespans belonging to that part. Used by reduceChords. May disappear at any time without a deprecation notice. )allPartsrpartr)r0partwiseTimespanTreesrtimespanpartwiseTimespanTrees rtoPartwiseTimespanTrees$TimespanTree.toPartwiseTimespanTreessR!#MMOD*6. ! '$H#8#G ' ' 1%$rcBSSKJn U"U5nUR5nU$)a Unwraps a sequence of `Verticality` objects into a dictionary of `Part`:`Horizontality` key/value pairs. >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans(classList=(note.Note,)) >>> iterator = scoreTree.iterateVerticalitiesNwise() >>> verticalities = next(iterator) >>> unwrapped = scoreTree.unwrapVerticalities(verticalities) >>> for part in sorted(unwrapped, key=lambda x: x.partName): ... print(part) ... horizontality = unwrapped[part] ... for timespan in horizontality: ... print('\t%r' % timespan) ... > > > > > > > > > > > rr )ryr unwrap)rr sequence unwrappeds runwrapVerticalities TimespanTree.unwrapVerticalitiess%D A&}5OO% rcx[5nUHnURUR5 M [USS9nU$)Nc6UR5R$r) getInstrumentpartIdrs r'TimespanTree.allParts..sAOO,=,D,Drkey)setaddrsorted)r0partsrs rrTimespanTree.allPartss5H IIhmm $u"DE rcSnUR5H>n[UR5[UR5-nUcUnM5X:dM<UnM@ U$)a  The maximum number of timespans overlapping at any given moment in this timespan collection. >>> score = corpus.parse('bwv66.6') >>> scoreTree = score.asTimespans(classList=(note.Note,)) >>> scoreTree.maximumOverlap() 4 Returns None if there is no verticality here. N)rcrirPoverlapTimespans)r0rvdegreeOfOverlaps rmaximumOverlapTimespanTree.maximumOverlapsX**,A!!"2"23c!:L:L6MMO)*) - rcB[R"UR5$)z defined so a TimespanTree can be used like an PitchedTimespan TODO: Look at subclassing or at least deriving from a common base. )r unwrapWeakref_sourcer6s relementTimespanTree.element s##DLL11rc:[R"U5Ulgr)r wrapWeakrefr)r0exprs rrr)s))$/ r)r)NTr)rRzspans.PitchedTimespanreturnzspans.PitchedTimespan | None)F)rrboolrz=Generator['music21.tree.verticality.Verticality', None, None]))rrzrrrrtrrz*Generator[VerticalitySequence, None, None])rrrr__doc__ __slots__ staticmethodr!r&r.propertyr*r?rCrWr\r_rnrcrrrrrrrsetterrrrrrr0sYrfI#J%%: ://.// & //h.3..3 & .3`*W2v@:@: G@:FeC16ueCeC*.eC@DeC 3eCz*$X%$$$P\22 ^^00rrc \rSrSrSrSrSrg)Testi.c\SSKJn SSKJn SSKJn UR 5nUR SUR S55 UR SURS55 UR5nURS5nURnUR[U5S5 g) NrrFr)noteCzF#4grx) rJrGrrStreamrKeyNote asTimespansrNpitchSet assertEqualri)r0rGrrs scoreTreerpss rtestGetVerticalityAtWithKey Test.testGetVerticalityAtWithKey0s{" MMO CGGCL! DIIe$%MMO  & &s + ZZ R!$rc B[S5GHn[[S55n[[S55n[R"U5 [R"U5 /n[ X#5HVupVXV::a'UR [ R"XV55 M1UR [ R"Xe55 MX [5n[U5GHBupURU 5 [[USUS-SS95n [U5n [SU 55n [SU 55n URU U XU 45 URURR [SU 555 URURR"[S U 555 URUR%5U 5 URUR&U 5 [ X5HupURX5 M GME [R"U5 U(dGM;UR)5n [US S9n UR+U 5 [U5n URU U XU 45 URb[S U 55n [S U 55n URURR [S U 555 URURR"[SU 555 URUR%5U 5 URUR&U 5 [ X5HupURX5 M U(aGMTGM g)Ndrxc2URUR4$rr*rrs rr'Test.testTimespanTree..MsAHHaiiCXrrc38# UHoRv M g7frr*.0r s r (Test.testTimespanTree..Os%O8N1hh8Nc38# UHoRv M g7frrrs rrrP$O8N1YY8Nrc38# UHoRv M g7frrrs rrrVrrc38# UHoRv M g7frrrs rrrXrrc2URUR4$rrrs rrrbsqxx>Src38# UHoRv M g7frrrs rrris)Srs #/  ??<&&':;  L66 { 05##{ 0|D98  D9P z Tr