class maelzel.scoring.node.Node(ratio=(1, 1), items=None, parent=None, properties=None)[source]

A Node is a recursive container, grouping Notations and other Nodes under one time modifier

Notations within a Node are quantized. When a measure is quantized, its contents are grouped in a tree structure made out of Nodes (see QuantizedMeasure.tree)

A Node consists of a sequence of Notations or Nodes, allowing to define nested tuplets or beats. The notations inside a Node already hold the real beat-duration. The durRatio is a ratio by which to multiply a given duration to obtain the notated duration.

A Node is used to represent the result of quantization.

Quantization happens first at the beat level and after that all quantized beats within a measure are merged together to create a tree structure spanning along the entire measure

See also

QuantizedMeasure.tree

durRatio

a tuple ``(num, den)` indication the ratio by which to multiply the duration of the items to obtain the notated items: the items inside this tree For example, a quarternote triplet would have a durRatio (3, 2) and the items inside it would have a duration of 1/3. When multiplied by the durRatio each item would have a duration of 1/2

items

the items in this tree (an item can be a Notation or a Node)

In the case of a simple triplet, the items would hold something like:

>>> from maelzel.scoring import *
>>> notations = [makeNote(60, duration=F(1, 3)),
...              makeNote(61, duration=F(2, 3))]
>>> Node(ratio=(3, 2), items=notations)
append(item)[source]

Add an item or Node to this Node

Return type:

None

static asTree(nodes)[source]

Transform a list of Nodes into a tree structure

A tree has a root and leaves, where each leave can be the root of a subtree

Parameters:

nodes (list[Node]) – the tree to get/make the root for

Return type:

Node

Returns:

the root of a tree structure

breakBeamsAt(offset)[source]

Breaks beams at the given offset

This method will not split a notation if the given offset is placed inside a syncopation

Parameters:

offset (Fraction) – the offset to break beams at

Return type:

Notation | None

Returns:

the notation at the right of the split, or None if no split was performed

dump(numindents=0, indent='  ', stream=None)[source]

Dump this node, recursively

empty()[source]

Is this node empty?

Return type:

bool

property end: Fraction

The end of the last item within this Node

findNextNotation(notation)[source]

Find the notation next to the given notation

Parameters:

notation (Notation) – the notation to query. The returned notation, if found, will be the notation next to this

Return type:

Notation | None

Returns:

the notation next to the given notation, or None if no notation found. The returned notation does not need to be on the same node.

findNodeForNotation(notation)[source]

Find the node of the given notation

Parameters:

notation (Notation) – the notation for which to find its node

Return type:

Node

Returns:

the node parent to the given notation

findRoot()[source]

Find the root of this node

Nodes are organized in tree structures. This method will climb the tree structure until the root of the tree (the node without a parent) is found

Return type:

Node

firstNotation()[source]

Return the first Notation of this Node (recursively)

Return type:

Notation

fixEnharmonics(options, prevTree=None)[source]

Find the best enharmonic spelling for the notations within this tree, inplace

Parameters:

  • options (EnharmonicOptions) – the enharmonic options used

  • prevTree (Optional[Node]) – the previous tree (the tree corrsponding to the previous measure)

Return type:

None

getProperty(key, default=None)[source]

Get the value of a property for this Node

glissMarkTiedNotesAsHidden()[source]

Within a glissando, notes tied to previous and next notes can be hidden

Return type:

None

lastNotation()[source]

Return the last Notation of this Node (recursively)

Return type:

Notation

logicalTieLocations(measureIndex=None)[source]

Like logicalTies, but for each notation returns a TreeLocation

Parameters:

measureIndex (Optional[int]) – if given, it is used to fill the .measureIndex attribute in the returned TreeLocation

Return type:

list[list[TreeLocation]]

Returns:

a list of ties, where each tie is a list of TreeLocations

logicalTies()[source]

Iterate over all logical ties within self (recursively)

Return type:

list[list[Notation]]

Returns:

an iterator over the logical ties within self (recursively), where a logical tie is a list of Notations which are tied together

mergeWith(other)[source]

Merge this tree with other

It is assumed that these Nodes can merge

Parameters:

other (Node) – the other node

Return type:

Node

Returns:

the merged node / tree

mergedNotations(flatten=True)[source]

Returns a new tree with all items merged (recursively)

Parameters:

flatten – if True, superfluous children are flattened

Return type:

Node

Returns:

a new Node with merged items (whenever possible)

property offset: Fraction

The offset of this Node within the measure

recurse(reverse=False)[source]

Iterate over the items in self, recursively

Parameters:

reverse – if True, iterate backwards

Return type:

Iterator[Notation]

Returns:

an iterator over all Notations within this Node

recurseWithNode(reverse=False)[source]

Iterate over the items if self, recursively

The same as Node.recurse() but for each item yields a tuple (notation, node) where node is the node to which the notation belongs. This is useful in order to modify the tree in the case one needs to, for example, remove a notation from its tree

Parameters:

reverse – if True, iterate in reverse

Return type:

Iterator[tuple[Notation, Node]]

Returns:

an iterator of tuples (notation, node)

removeUnnecessaryGracenotes()[source]

Removes unnecessary gracenotes

Return type:

int

Returns:

the number of modifications

An unnecessary gracenote:

  • has the same pitch as the next real note and starts a glissando. Such gracenotes might be created during quantization.

  • has the same pitch as the previous real note and ends a glissando

  • n0/real – gliss – n1/grace n2/real and n1.pitches == n2.pitches

  • has the same pitch as the previous real note and has no attribute itself

Repair ties and glissandi inplace

Return type:

int

Returns:

the number of modifications

setParentRecursively()[source]

Set the parent of each Node downstream

setProperty(key, value)[source]

Set a property for this Node

Return type:

None

splitNotationAtBoundary(offset, callback=None)[source]

Split any notation which crosses the given offset, inplace

A notation will be split if it crosses the given offset. Raises SplitError if it cannot split at the given offset

Parameters:

  • offset (Fraction) – the offset of the desired split. It should be a beat boundary

  • callback – if given, a function which returns True if the note should be split

Return type:

Notation | None

Returns:

the notation next to the split offset, or None if no split operation was performed

symbolicDuration()[source]

The symbolic total duration of this tree.

This represents the notated figure (1=quarter, 1/2=eighth note, 1/4=16th note, etc) at the level of this node.

Return type:

Fraction

totalDuration()[source]

The duration of the items in this tree, in quarter notes (recursively)

Return type:

Fraction