librosa.segment.recurrence_matrix(data, k=None, width=1, metric='euclidean', sym=False, sparse=False, mode='connectivity', bandwidth=None, self=False, axis=- 1)[source]

Compute a recurrence matrix from a data matrix.

rec[i, j] is non-zero if data[:, i] is a k-nearest neighbor of data[:, j] and |i - j| >= width

The specific value of rec[i, j] can have several forms, governed by the mode parameter below:

  • Connectivity: rec[i, j] = 1 or 0 indicates that frames i and j are repetitions

  • Affinity: rec[i, j] > 0 measures how similar frames i and j are. This is also known as a (sparse) self-similarity matrix.

  • Distance: rec[i, j] > 0 measures how distant frames i and j are. This is also known as a (sparse) self-distance matrix.

The general term recurrence matrix can refer to any of the three forms above.


A feature matrix

kint > 0 [scalar] or None

the number of nearest-neighbors for each sample

Default: k = 2 * ceil(sqrt(t - 2 * width + 1)), or k = 2 if t <= 2 * width + 1

widthint >= 1 [scalar]

only link neighbors (data[:, i], data[:, j]) if |i - j| >= width

width cannot exceed the length of the data.


Distance metric to use for nearest-neighbor calculation.

See sklearn.neighbors.NearestNeighbors for details.

symbool [scalar]

set sym=True to only link mutual nearest-neighbors

sparsebool [scalar]

if False, returns a dense type (ndarray) if True, returns a sparse type (scipy.sparse.csc_matrix)

modestr, {‘connectivity’, ‘distance’, ‘affinity’}

If ‘connectivity’, a binary connectivity matrix is produced.

If ‘distance’, then a non-zero entry contains the distance between points.

If ‘affinity’, then non-zero entries are mapped to exp( - distance(i, j) / bandwidth) where bandwidth is as specified below.

bandwidthNone or float > 0

If using mode='affinity', this can be used to set the bandwidth on the affinity kernel.

If no value is provided, it is set automatically to the median distance between furthest nearest neighbors.


If True, then the main diagonal is populated with self-links: 0 if mode='distance', and 1 otherwise.

If False, the main diagonal is left empty.


The axis along which to compute recurrence. By default, the last index (-1) is taken.

recnp.ndarray or scipy.sparse.csc_matrix, [shape=(t, t)]

Recurrence matrix


This function caches at level 30.


Find nearest neighbors in MFCC space

>>> y, sr = librosa.load(librosa.ex('nutcracker'))
>>> hop_length = 1024
>>> chroma = librosa.feature.chroma_cqt(y=y, sr=sr, hop_length=hop_length)
>>> # Use time-delay embedding to get a cleaner recurrence matrix
>>> chroma_stack = librosa.feature.stack_memory(chroma, n_steps=10, delay=3)
>>> R = librosa.segment.recurrence_matrix(chroma_stack)

Or fix the number of nearest neighbors to 5

>>> R = librosa.segment.recurrence_matrix(chroma_stack, k=5)

Suppress neighbors within +- 7 frames

>>> R = librosa.segment.recurrence_matrix(chroma_stack, width=7)

Use cosine similarity instead of Euclidean distance

>>> R = librosa.segment.recurrence_matrix(chroma_stack, metric='cosine')

Require mutual nearest neighbors

>>> R = librosa.segment.recurrence_matrix(chroma_stack, sym=True)

Use an affinity matrix instead of binary connectivity

>>> R_aff = librosa.segment.recurrence_matrix(chroma_stack, metric='cosine',
...                                           mode='affinity')

Plot the feature and recurrence matrices

>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots(ncols=2, sharex=True, sharey=True)
>>> imgsim = librosa.display.specshow(R, x_axis='s', y_axis='s',
...                          hop_length=hop_length, ax=ax[0])
>>> ax[0].set(title='Binary recurrence (symmetric)')
>>> imgaff = librosa.display.specshow(R_aff, x_axis='s', y_axis='s',
...                          hop_length=hop_length, cmap='magma_r', ax=ax[1])
>>> ax[1].set(title='Affinity recurrence')
>>> ax[1].label_outer()
>>> fig.colorbar(imgsim, ax=ax[0], orientation='horizontal', ticks=[0, 1])
>>> fig.colorbar(imgaff, ax=ax[1], orientation='horizontal')