quantizationtools.QGridQuantizer

class abjad.tools.quantizationtools.QGridQuantizer.QGridQuantizer.QGridQuantizer(search_tree=None, beatspan=Fraction(1, 4), tempo=TempoMark(Duration(1, 4), 60), threshold=None)

An Abjad implementation of Paul Nauert’s Q-grid quantization algorithm.

Input is converted into timepoints, which are grouped according to which beat - or beatspan - they fall in, given a target tempo. Each beatspan is then divided into grids called Q-grids, which are based upon a nesting division structure (similar to nested tuplets). The Q-grids generated for each beatspan are then tested against the timepoints falling within that beatspan, and the grid with least deviation is chosen to represent the rhythmic skeleton for that beat.

abjad> from abjad.tools.quantizationtools import QGridQuantizer
abjad> q = QGridQuantizer()

QGridQuantizer is immutable, but cheap to instantiate. Various attributes can be defined on instantiation. Please consult the documentation for each attribute respectively, for proper usage.

abjad> from abjad.tools.quantizationtools import QGridSearchTree
abjad> target_tempo = contexttools.TempoMark((1, 8), 73)
abjad> beatspan = Fraction(1, 4)
abjad> search_tree = QGridSearchTree({2: {2: None, 3: None}, 5: None})
abjad> threshold = 250
abjad> q = QGridQuantizer(tempo = target_tempo, beatspan = beatspan, search_tree = search_tree, threshold = threshold)

QGridQuantizer can quantize lists of leaves. If the source leaves have no effective tempo, one must be provided with the tempo keyword.

abjad> q = QGridQuantizer()
abjad> source = Staff("c'4 d'4 e'4. r8 <c' e' g'>2. <d' g' b'>4")
abjad> source_tempo = contexttools.TempoMark((1, 4), 54)
abjad> result = q(source[:], tempo = source_tempo)

abjad> q = QGridQuantizer()
abjad> source = Staff("c'4 d'4 e'4. r8 <c' e' g'>2. <d' g' b'>4")
abjad> t = contexttools.TempoMark((1, 8), 34, target_context = Staff)(source)
abjad> t = contexttools.TempoMark((1, 4), 135, target_context = Staff)(source[3])
abjad> result = q(source[:])

QGridQuantizer can quantize lists of millisecond durations. Negative values can be used to indicate silences.

abjad> q = QGridQuantizer()
abjad> milliseconds = [100, 120, -133, 500, -1003, 125]
abjad> result = q(milliseconds)

QGridQuantizer can also quantize lists of rationals, if a tempo is provided. As with quantizing millisecond durations, negative values can be used to indicate silences.

abjad> q = QGridQuantizer()
abjad> rationals = [1, Fraction(1, 2), Fraction(-1, 4), 3, Fraction(-1, 3), 2]
abjad> tempo = contexttools.TempoMark((1, 4), 45)
abjad> result = q(rationals, tempo = tempo)

Lastly, QGridQuantizer can quantize lists of pairs, where the first value in each pair is a millisecond duration, and the second value is an int or float - indicating a single pitch -, None - indicating silence, or a list of ints or floats - indicating a chord. This is probably most useful for assisting in the importation of audio analyses from other tools.

abjad> q = QGridQuantizer()
abjad> pairs = [(130, 0), (250, 2), (500, None), (1303, [0, 1, 4])]
abjad> result = q(pairs)

Todo

Write a documentation chapter on quantization.

Todo

Implement multiprocessing-based QGrid comparison

Read-only Properties

QGridQuantizer.beatspan

The basic division of the beat for quantization.

Read-only, defaults to Duration(1, 4).

QGridQuantizer.beatspan_ms

The duration of beatspan in milliseconds, as determined by tempo.

Read-only, defaults to Duration(1000).

QGridQuantizer.search_tree

Reference to a QGridSearchTree object, which defines the permissible divisions for each QGrid comprising a quantization attempt.

Read-only, defaults to QGridSearchTree().

Please consult the documentation for QGrid and QGridSearchTree for more information.

QGridQuantizer.tempo

Reference to a TempoMark, defining the target tempo for all quantization results.

Read-only, defaults to TempoMark((1, 4), 60).

QGridQuantizer.tempo_lookup

Reference to a QGridTempoLookup object, a utility class for mapping rational divisions of a beat into milliseconds.

Read-only.

QGridQuantizer.threshold

Millisecond duration, which if specified at instantiation will be used to call the quantizer’s QGridSearchTree‘s prune() method, in order to generate a pruned search tree for the quantizer, instead of either the user-provided or default search trees.

Read-only, defaults to None. See the documentation for QGridSearchTree for more information on pruning.

Special Methods

QGridQuantizer.__call__(args, **kwargs)

Note

Inherited from quantizationtools._Quantizer

QGridQuantizer.__delattr__()

x.__delattr__(‘name’) <==> del x.name

Note

Inherited from __builtin__.object

QGridQuantizer.__eq__(arg)

True when id(self) equals id(arg).

Return boolean.

Note

Inherited from abctools.AbjadObject

QGridQuantizer.__ge__(arg)

Abjad objects by default do not implement this method.

Raise exception.

Note

Inherited from abctools.AbjadObject

QGridQuantizer.__gt__(arg)

Abjad objects by default do not implement this method.

Raise exception

Note

Inherited from abctools.AbjadObject

QGridQuantizer.__hash__() <==> hash(x)

Note

Inherited from __builtin__.object

QGridQuantizer.__le__(arg)

Abjad objects by default do not implement this method.

Raise exception.

Note

Inherited from abctools.AbjadObject

QGridQuantizer.__lt__(arg)

Abjad objects by default do not implement this method.

Raise exception.

Note

Inherited from abctools.AbjadObject

QGridQuantizer.__ne__(arg)

True when id(self) does not equal id(arg).

Return boolean.

Note

Inherited from abctools.AbjadObject

QGridQuantizer.__repr__()

Note

Inherited from quantizationtools._Quantizer

QGridQuantizer.__setattr__()

x.__setattr__(‘name’, value) <==> x.name = value

Note

Inherited from __builtin__.object

QGridQuantizer.__str__() <==> str(x)

Note

Inherited from __builtin__.object