rhRPSrSSKJr SSKrSSKJr SSKJr SSKJ r "SS\R5r "S S \ 5r "S S \R5r\ \ 4r\S :XaSSKr\R$"5 gg)z Internal data structures for timespan collections. This is an implementation detail of the TimespanTree class. Most music21 users can happily ignore this module. ) annotationsN)core) Music21Object) SortTuplec^\rSrSr%SrSrSSSSSS .rS \S 'SU4S jjrS r \ S5r \ S5r SSjr SrSrU=r$) ElementNodea A node containing a single element, which is aware of the element's endTime and index within a stream, as well as the endTimes and indices of the elements to the left and right of it. Here's an element node that is at first is no different from an AVL node, except in representation: >>> n = note.Note('C4') >>> n.duration.quarterLength = 2.0 >>> n.offset = 4.0 >>> elNode = tree.node.ElementNode(n.sortTuple(), n) >>> elNode Indices:(l:-1 *-1* r:-1) Payload:> >>> avlNode = tree.core.AVLNode(4.0, n) >>> avlNode But now let's give n a stream context where it is element 1 in the measure. >>> m = stream.Measure() >>> r = note.Rest(type='whole') >>> m.insert(0.0, r) >>> m.insert(4.0, n) >>> n2 = note.Note('F#4') >>> n2.duration.quarterLength = 3.0 >>> m.insert(6.0, n2) Let's create an ElementNode object for each object and attach them to elNode: >>> rElNode = tree.node.ElementNode(r.sortTuple(), r) >>> n2ElNode = tree.node.ElementNode(n2.sortTuple(), n2) >>> elNode.leftChild = rElNode >>> elNode.update() >>> elNode.rightChild = n2ElNode >>> elNode.update() Everything so far could be done w/ AVLNodes, which are not music21 specific. But now we'll add some specific features, based on the information from the Stream. >>> m[1] is n True >>> m.highestTime 9.0 >>> m.offset 0.0 >>> rElNode.payloadElementIndex = 0 >>> elNode.payloadElementIndex = 1 >>> n2ElNode.payloadElementIndex = 2 >>> elNode.updateIndices() >>> elNode.updateEndTimes() Now let's look at the ElementNode: >>> elNode Indices:(l:0 *1* r:3) Payload:> elNode is at 4.0. With it and underneath it are nodes from 0 <= nodes < 3. This seemingly screwy way of counting is exactly slice notation: [0:3]. So if we wanted to get a certain index number we would know that index 0 is in the leftChild's payload, index 2 is in the rightChild's payload, and index 1 is this node's payload. This information is easy to compute for ElementNodes, since each node holds exactly one element (since the position here is a sortTuple which is unique); for its subclass, OffsetNode, where multiple elements can be in a node, this will become much more important and harder to work with. Here is how you can actually get this information. >>> elNode.subtreeElementsStartIndex 0 >>> elNode.subtreeElementsStopIndex 3 If they've never been set then they return -1, but the .updateIndices() call above set these number for the children also. So they return the node's own index and one above: >>> n2ElNode.subtreeElementsStartIndex 2 >>> n2ElNode.subtreeElementsStopIndex 3 Now here is the thing that actually makes trees based on ElementNodes useful. Each node knows the lowest and highest endTime as well as offset among the nodes below it: >>> elNode.lowestPosition.offset 0.0 >>> elNode.endTimeLow 4.0 >>> elNode.highestPosition.offset 6.0 >>> elNode.endTimeHigh 9.0 What's so great about this? If you're doing a "getElementsByOffset" search, you can know from this information whether there's going to be an element whose start or end time will possibly match the offset span without needing to descend into the tree. The last element in a Stream often doesn't has the highest endTime (think of different voices, flat streams, etc.) so searches for offsets are often O(n) when they could be O(log n) if the information were cached into a tree as this does. ) endTimeHigh endTimeLowpayloadElementIndexsubtreeElementsStartIndexsubtreeElementsStopIndexzb The index in a stream of the element stored in the payload of this node. z] The highest endTime of any node in the subtree rooted on this node. z\ The lowest endTime of any node in the subtree rooted on this node. z The lowest element index of an element in the payload of any node of the subtree rooted on this node. z The highest element index of an element in the payload of any node of the subtree rooted on this node. )r r r r rdict[str, str] _DOC_ATTRcj>[TU]X5 SUlSUlSUlSUlSUlgN)super__init__r r r r r)selfpositionpayload __class__s K/home/james-whalen/.local/lib/python3.13/site-packages/music21/tree/node.pyrElementNode.__init__s7 +#% )+&(*%cURn[US5(aUR5nSRUURUR UR UR5$)N shortReprz=)rhasattrrformatr r rr)rposs r__repr__ElementNode.__repr__s[mm 3 $ $--/CNUU   * *  $ $  ) ) LL   rc`URc UR$URR$)z> Returns the lowest position in the tree rooted on this node. ) leftChildrlowestPositionrs rr&ElementNode.lowestPositions( >> !== >>00 0rc`URc UR$URR$)z? Returns the highest position in the tree rooted on this node. ) rightChildrhighestPositionr's rr+ElementNode.highestPositions( ?? "== ??22 2rcURbPURRUS9 URRUlURRUlOUcSUlSUlO XlXlUR cSnOSnURU-UlUR b?UR RURS9 UR RUlgg)a Updates the payloadElementIndex, and the subtreeElementsStartIndex and subtreeElementsStopIndex (and does so for all child nodes) by traversing the tree structure. Updates cached indices which keep track of the index of the element stored at each node, and of the minimum and maximum indices of the subtrees rooted at each node. Called on rootNode of a tree that uses ElementNodes, such as ElementTree parentStopIndex specifies the stop index of the parent node, if known. It is used internally by the function. Returns None. NparentStopIndexr)r% updateIndicesrr r rr*)rr/ payloadLens rr1ElementNode.updateIndicess" >> % NN ( ( ( I'+~~'N'ND $-1^^-U-UD *  $'(D $-.D *'6 $-< * << JJ(,(@(@:(M% ?? & OO ) )$:W:W ) X,0OO,T,TD ) 'rcFURRnUnURnU(a:UR5 [XR5n[X$R5nURnU(a:UR5 [XR5n[X%R5nXl X lg![aU URn[ U[ 5(a UR nX0RRR-nUnGNf=f)z Traverses the tree structure and updates cached maximum and minimum endTime values for the subtrees rooted at each node. Used internally by ElementTree. Returns None. N)rendTimeAttributeErrorr isinstanceroffsetduration quarterLengthr%updateEndTimesminr maxr r*)rr r r!r%r*s rr;ElementNode.updateEndTimess %--J$KNN   $ $ &Z)=)=>Jk+@+@AK__   % % 'Z)>)>?Jk+A+ABK$&' %--C#y))jj||44BBBJ$K  %sCAD D N)__name__ __module__ __qualname____firstlineno____doc__ __slots__r__annotations__rr"propertyr&r+r1r;__static_attributes__ __classcell__rs@rrrs{k\I &%!I~,+  1133#UJ''rrch^\rSrSr%SrSrSSSS.rS\S 'SU4S jjrS r SS jr S r Sr Sr U=r$) OffsetNodei aL A node representing zero, one, or many elements at an offset. It has all the power of an ElementNode but substantially more. Here's an example of what it means and does: >>> score = tree.makeExampleScore() >>> sf = score.flatten() >>> sf.show('text', addEndTimes=True) {0.0 - 0.0} {0.0 - 0.0} {0.0 - 0.0} {0.0 - 0.0} {0.0 - 0.0} {0.0 - 0.0} {0.0 - 1.0} {0.0 - 2.0} {1.0 - 2.0} {2.0 - 3.0} {2.0 - 4.0} {3.0 - 4.0} {4.0 - 5.0} {4.0 - 6.0} {5.0 - 6.0} {6.0 - 7.0} {6.0 - 8.0} {7.0 - 8.0} {8.0 - 8.0} {8.0 - 8.0} >>> scoreTree = tree.fromStream.asTimespans(sf, flatten=False, classList=None) >>> rn = scoreTree.rootNode The RootNode here represents the starting position of the Note F at 3.0; It is the center of the elements in the flat Stream. Its index is 5 (that is, it's the sixth note in the element list) and its offset is 3.0 >>> rn >>> sf[11] >>> sf[11].offset 3.0 Thus, the indices of 0:5:6:12 indicate that the left-side of the node handles indices from >= 0 to < 5; and the right-side of the node handles indices >= 6 and < 12, and this node handles indices >= 5 and < 6. The `Length: {1}` indicates that there is exactly one element at this location, that is, the F. The "payload" of the node, is just that element wrapped in a list wrapped in an ElementTimespan or PitchedTimespan: >>> rn.payload [>] >>> rn.payload[0].element >>> rn.payload[0].element is sf[11] True We can look at the leftChild of the root node to get some more interesting cases: >>> left = rn.leftChild >>> left In the leftNode of the leftNode of the rootNode there are eight elements: metadata and both notes that begin on offset 0.0: >>> leftLeft = left.leftChild >>> leftLeft >>> leftLeft.payload [>, >, >, >, >, >, >, >] The Indices:0,0,8,8 indicates that `leftLeft` has neither left nor right children >>> leftLeft.leftChild is None True >>> leftLeft.rightChild is None True What makes an OffsetNode more interesting than other AWL Nodes is that it is aware of the fact that it might have objects that end at different times, such as the zero-length metadata and the 2.0 length half note >>> leftLeft.endTimeLow 0.0 >>> leftLeft.endTimeHigh 2.0 )payloadElementsStartIndexpayloadElementsStopIndexa The contents of the node at this point. Usually a list of ElementTimespans or PitchedTimespans. >>> score = tree.makeExampleScore() >>> scoreTree = tree.fromStream.asTimespans(score, flatten=True, ... classList=(note.Note, chord.Chord)) >>> print(scoreTree.rootNode.debug()) L: L: R: R: L: R: R: >>> scoreTree.rootNode.payload [>] >>> scoreTree.rootNode.leftChild.payload [>] >>> for x in scoreTree.rootNode.leftChild.rightChild.payload: ... x ... > > >>> scoreTree.rootNode.rightChild.payload [>] z The timespan start index (i.e., the first x where s[x] is found in this Node's payload) of only those timespans stored in the payload of this node. z The timespan stop index (i.e., the last x where s[x] is found in this Node's payload) of only those timespans stored in the payload of this node. )rrMrNrrcN>[TU]U5 /UlSUlSUlgr)rrrrMrN)rr8rrs rrOffsetNode.__init__s'   )+&(*%rc URnURnURnURnSURS3nUSUSUSUSUS3 - nUS[ UR 5S3- nU$)Nz )r rMrNrrlenr)rsubStartpayStartpayEndsubEndmsgs rr"OffsetNode.__repr__s1111....T]]O1- (1XJaxqBB T\\*+1-- rcURbPURRUS9 URRUlURRUlOUcSUlSUlO XlXlUR[ UR 5-UlURUlURb?URRURS9 URRUlgg)a Updates the payloadElementsStartIndex, the payloadElementsStopIndex and the subtreeElementsStartIndex and subtreeElementsStopIndex (and does so for all child nodes) by traversing the tree structure. Updates cached indices which keep track of the index of the element stored at each node, and of the minimum and maximum indices of the subtrees rooted at each node. Called on rootNode of a tree that uses OffsetNodes, such as OffsetTree or TimespanTree Returns None. Nr.r) r%r1rrMr rUrrNr*)rr/s rr1OffsetNode.updateIndicess >> % NN ( ( ( I-1^^-T-TD *-1^^-U-UD *  $-.D *-.D *-< *-< *(,(F(FT\\IZ(Z%(,(E(E% ?? & OO ) )$:W:W ) X,0OO,T,TD ) 'rc[SUR55n[SUR55nUR nU(a:UR 5 [XR5n[X#R5nURnU(a:UR 5 [XR5n[X$R5nXlX lg![aV UR[SUR55-nUR[SUR55-nGNf=f)z Traverses the tree structure and updates cached maximum and minimum endTime values for the subtrees rooted at each node. Used internally by OffsetTree. Returns None c38# UHoRv M g7fr?r5.0xs r ,OffsetNode.updateEndTimes..s= 1YY c38# UHoRv M g7fr?r`ras rrdres>Aiirfc3L# UHoRRv M g7fr?r9r:ras rrdres,\|!ZZ-E-E|"$c3L# UHoRRv M g7fr?riras rrdres-]P\1jj.F.FP\rjN) r<rr=r6rr%r;r r r*)rr r r%r*s rr;OffsetNode.updateEndTimess ^= ==J>>>K NN   $ $ &Z)=)=>Jk+@+@AK__   % % 'Z)>)>?Jk+A+ABK$&! ^,\t||,\)\\J--#-]PTP\P\-]*]]K ^s8C!!AEEc/nURHgn[U[5(a4URURUR R -5 MLURUR5 Mi U$)a returns a (potentially unsorted) list of all the end times for all TimeSpans or Elements in the payload. Does not trust el.endTime because it might refer to a different offset. Rather, it takes the position and adds it to the duration.quarterLength. >>> offsetNode = tree.node.OffsetNode(40) >>> n = note.Note() >>> offsetNode.payload.append(n) >>> ts = tree.spans.Timespan(40, 44) >>> offsetNode.payload.append(ts) >>> offsetNode.payloadEndTimes() [41.0, 44.0] )rr7rappendrr9r:r5)r outEndTimestsOrEls rpayloadEndTimesOffsetNode.payloadEndTimes s_ llF&-00""4==6??3P3P#PQ""6>>2 # r)r r rrMrNr rr?)r@rArBrCrDrErrFrr"r1r;rqrHrIrJs@rrLrL sQdPI @&%K)!I~)V+ U@'<rrLc\rSrSrSrg)Testi&N)r@rArBrCrHrurrrtrt&srrt__main__)rD __future__runittest music21.treer music21.basermusic21.sortingrAVLNoderrLTestCasert _DOC_ORDERr@music21mainTestrurrrsy #&%@'$,,@'HAAL 8   : &  z r