@cache(level=30)
def nn_filter(S, rec=None, aggregate=None, axis=(- 1), **kwargs):
    'Filtering by nearest-neighbors.\n\n    Each data point (e.g, spectrogram column) is replaced\n    by aggregating its nearest neighbors in feature space.\n\n    This can be useful for de-noising a spectrogram or feature matrix.\n\n    The non-local means method [1]_ can be recovered by providing a\n    weighted recurrence matrix as input and specifying `aggregate=np.average`.\n\n    Similarly, setting `aggregate=np.median` produces sparse de-noising\n    as in REPET-SIM [2]_.\n\n    .. [1] Buades, A., Coll, B., & Morel, J. M.\n        (2005, June). A non-local algorithm for image denoising.\n        In Computer Vision and Pattern Recognition, 2005.\n        CVPR 2005. IEEE Computer Society Conference on (Vol. 2, pp. 60-65). IEEE.\n\n    .. [2] Rafii, Z., & Pardo, B.\n        (2012, October).  "Music/Voice Separation Using the Similarity Matrix."\n        International Society for Music Information Retrieval Conference, 2012.\n\n    Parameters\n    ----------\n    S : np.ndarray\n        The input data (spectrogram) to filter\n\n    rec : (optional) scipy.sparse.spmatrix or np.ndarray\n        Optionally, a pre-computed nearest-neighbor matrix\n        as provided by `librosa.segment.recurrence_matrix`\n\n    aggregate : function\n        aggregation function (default: `np.mean`)\n\n        If `aggregate=np.average`, then a weighted average is\n        computed according to the (per-row) weights in `rec`.\n\n        For all other aggregation functions, all neighbors\n        are treated equally.\n\n\n    axis : int\n        The axis along which to filter (by default, columns)\n\n    kwargs\n        Additional keyword arguments provided to\n        `librosa.segment.recurrence_matrix` if `rec` is not provided\n\n    Returns\n    -------\n    S_filtered : np.ndarray\n        The filtered data\n\n    Raises\n    ------\n    ParameterError\n        if `rec` is provided and its shape is incompatible with `S`.\n\n    See also\n    --------\n    decompose\n    hpss\n    librosa.segment.recurrence_matrix\n\n\n    Notes\n    -----\n    This function caches at level 30.\n\n\n    Examples\n    --------\n\n    De-noise a chromagram by non-local median filtering.\n    By default this would use euclidean distance to select neighbors,\n    but this can be overridden directly by setting the `metric` parameter.\n\n    >>> y, sr = librosa.load(librosa.util.example_audio_file(),\n    ...                      offset=30, duration=10)\n    >>> chroma = librosa.feature.chroma_cqt(y=y, sr=sr)\n    >>> chroma_med = librosa.decompose.nn_filter(chroma,\n    ...                                          aggregate=np.median,\n    ...                                          metric=\'cosine\')\n\n    To use non-local means, provide an affinity matrix and `aggregate=np.average`.\n\n    >>> rec = librosa.segment.recurrence_matrix(chroma, mode=\'affinity\',\n    ...                                         metric=\'cosine\', sparse=True)\n    >>> chroma_nlm = librosa.decompose.nn_filter(chroma, rec=rec,\n    ...                                          aggregate=np.average)\n\n    >>> import matplotlib.pyplot as plt\n    >>> plt.figure(figsize=(10, 8))\n    >>> plt.subplot(5, 1, 1)\n    >>> librosa.display.specshow(chroma, y_axis=\'chroma\')\n    >>> plt.colorbar()\n    >>> plt.title(\'Unfiltered\')\n    >>> plt.subplot(5, 1, 2)\n    >>> librosa.display.specshow(chroma_med, y_axis=\'chroma\')\n    >>> plt.colorbar()\n    >>> plt.title(\'Median-filtered\')\n    >>> plt.subplot(5, 1, 3)\n    >>> librosa.display.specshow(chroma_nlm, y_axis=\'chroma\')\n    >>> plt.colorbar()\n    >>> plt.title(\'Non-local means\')\n    >>> plt.subplot(5, 1, 4)\n    >>> librosa.display.specshow(chroma - chroma_med,\n    ...                          y_axis=\'chroma\')\n    >>> plt.colorbar()\n    >>> plt.title(\'Original - median\')\n    >>> plt.subplot(5, 1, 5)\n    >>> librosa.display.specshow(chroma - chroma_nlm,\n    ...                          y_axis=\'chroma\', x_axis=\'time\')\n    >>> plt.colorbar()\n    >>> plt.title(\'Original - NLM\')\n    >>> plt.tight_layout()\n    '
    if (aggregate is None):
        aggregate = np.mean
    if (rec is None):
        kwargs = dict(kwargs)
        kwargs['sparse'] = True
        rec = segment.recurrence_matrix(S, axis=axis, **kwargs)
    elif (not scipy.sparse.issparse(rec)):
        rec = scipy.sparse.csr_matrix(rec)
    if ((rec.shape[0] != S.shape[axis]) or (rec.shape[0] != rec.shape[1])):
        raise ParameterError('Invalid self-similarity matrix shape rec.shape={} for S.shape={}'.format(rec.shape, S.shape))
    return __nn_filter_helper(rec.data, rec.indices, rec.indptr, S.swapaxes(0, axis), aggregate).swapaxes(0, axis)
Filtering by nearest-neighbors.

Each data point (e.g, spectrogram column) is replaced
by aggregating its nearest neighbors in feature space.

This can be useful for de-noising a spectrogram or feature matrix.

The non-local means method [1]_ can be recovered by providing a
weighted recurrence matrix as input and specifying `aggregate=np.average`.

Similarly, setting `aggregate=np.median` produces sparse de-noising
as in REPET-SIM [2]_.

.. [1] Buades, A., Coll, B., & Morel, J. M.
    (2005, June). A non-local algorithm for image denoising.
    In Computer Vision and Pattern Recognition, 2005.
    CVPR 2005. IEEE Computer Society Conference on (Vol. 2, pp. 60-65). IEEE.

.. [2] Rafii, Z., & Pardo, B.
    (2012, October).  "Music/Voice Separation Using the Similarity Matrix."
    International Society for Music Information Retrieval Conference, 2012.

Parameters
----------
S : np.ndarray
    The input data (spectrogram) to filter

rec : (optional) scipy.sparse.spmatrix or np.ndarray
    Optionally, a pre-computed nearest-neighbor matrix
    as provided by `librosa.segment.recurrence_matrix`

aggregate : function
    aggregation function (default: `np.mean`)

    If `aggregate=np.average`, then a weighted average is
    computed according to the (per-row) weights in `rec`.

    For all other aggregation functions, all neighbors
    are treated equally.


axis : int
    The axis along which to filter (by default, columns)

kwargs
    Additional keyword arguments provided to
    `librosa.segment.recurrence_matrix` if `rec` is not provided

Returns
-------
S_filtered : np.ndarray
    The filtered data

Raises
------
ParameterError
    if `rec` is provided and its shape is incompatible with `S`.

See also
--------
decompose
hpss
librosa.segment.recurrence_matrix


Notes
-----
This function caches at level 30.


Examples
--------

De-noise a chromagram by non-local median filtering.
By default this would use euclidean distance to select neighbors,
but this can be overridden directly by setting the `metric` parameter.

>>> y, sr = librosa.load(librosa.util.example_audio_file(),
...                      offset=30, duration=10)
>>> chroma = librosa.feature.chroma_cqt(y=y, sr=sr)
>>> chroma_med = librosa.decompose.nn_filter(chroma,
...                                          aggregate=np.median,
...                                          metric='cosine')

To use non-local means, provide an affinity matrix and `aggregate=np.average`.

>>> rec = librosa.segment.recurrence_matrix(chroma, mode='affinity',
...                                         metric='cosine', sparse=True)
>>> chroma_nlm = librosa.decompose.nn_filter(chroma, rec=rec,
...                                          aggregate=np.average)

>>> import matplotlib.pyplot as plt
>>> plt.figure(figsize=(10, 8))
>>> plt.subplot(5, 1, 1)
>>> librosa.display.specshow(chroma, y_axis='chroma')
>>> plt.colorbar()
>>> plt.title('Unfiltered')
>>> plt.subplot(5, 1, 2)
>>> librosa.display.specshow(chroma_med, y_axis='chroma')
>>> plt.colorbar()
>>> plt.title('Median-filtered')
>>> plt.subplot(5, 1, 3)
>>> librosa.display.specshow(chroma_nlm, y_axis='chroma')
>>> plt.colorbar()
>>> plt.title('Non-local means')
>>> plt.subplot(5, 1, 4)
>>> librosa.display.specshow(chroma - chroma_med,
...                          y_axis='chroma')
>>> plt.colorbar()
>>> plt.title('Original - median')
>>> plt.subplot(5, 1, 5)
>>> librosa.display.specshow(chroma - chroma_nlm,
...                          y_axis='chroma', x_axis='time')
>>> plt.colorbar()
>>> plt.title('Original - NLM')
>>> plt.tight_layout()
@cache(level=30)
def nn_filter(S, rec=None, aggregate=None, axis=(- 1), **kwargs):
    'Filtering by nearest-neighbors.\n\n    Each data point (e.g, spectrogram column) is replaced\n    by aggregating its nearest neighbors in feature space.\n\n    This can be useful for de-noising a spectrogram or feature matrix.\n\n    The non-local means method [1]_ can be recovered by providing a\n    weighted recurrence matrix as input and specifying `aggregate=np.average`.\n\n    Similarly, setting `aggregate=np.median` produces sparse de-noising\n    as in REPET-SIM [2]_.\n\n    .. [1] Buades, A., Coll, B., & Morel, J. M.\n        (2005, June). A non-local algorithm for image denoising.\n        In Computer Vision and Pattern Recognition, 2005.\n        CVPR 2005. IEEE Computer Society Conference on (Vol. 2, pp. 60-65). IEEE.\n\n    .. [2] Rafii, Z., & Pardo, B.\n        (2012, October).  "Music/Voice Separation Using the Similarity Matrix."\n        International Society for Music Information Retrieval Conference, 2012.\n\n    Parameters\n    ----------\n    S : np.ndarray\n        The input data (spectrogram) to filter\n\n    rec : (optional) scipy.sparse.spmatrix or np.ndarray\n        Optionally, a pre-computed nearest-neighbor matrix\n        as provided by `librosa.segment.recurrence_matrix`\n\n    aggregate : function\n        aggregation function (default: `np.mean`)\n\n        If `aggregate=np.average`, then a weighted average is\n        computed according to the (per-row) weights in `rec`.\n\n        For all other aggregation functions, all neighbors\n        are treated equally.\n\n\n    axis : int\n        The axis along which to filter (by default, columns)\n\n    kwargs\n        Additional keyword arguments provided to\n        `librosa.segment.recurrence_matrix` if `rec` is not provided\n\n    Returns\n    -------\n    S_filtered : np.ndarray\n        The filtered data\n\n    Raises\n    ------\n    ParameterError\n        if `rec` is provided and its shape is incompatible with `S`.\n\n    See also\n    --------\n    decompose\n    hpss\n    librosa.segment.recurrence_matrix\n\n\n    Notes\n    -----\n    This function caches at level 30.\n\n\n    Examples\n    --------\n\n    De-noise a chromagram by non-local median filtering.\n    By default this would use euclidean distance to select neighbors,\n    but this can be overridden directly by setting the `metric` parameter.\n\n    >>> y, sr = librosa.load(librosa.util.example_audio_file(),\n    ...                      offset=30, duration=10)\n    >>> chroma = librosa.feature.chroma_cqt(y=y, sr=sr)\n    >>> chroma_med = librosa.decompose.nn_filter(chroma,\n    ...                                          aggregate=np.median,\n    ...                                          metric=\'cosine\')\n\n    To use non-local means, provide an affinity matrix and `aggregate=np.average`.\n\n    >>> rec = librosa.segment.recurrence_matrix(chroma, mode=\'affinity\',\n    ...                                         metric=\'cosine\', sparse=True)\n    >>> chroma_nlm = librosa.decompose.nn_filter(chroma, rec=rec,\n    ...                                          aggregate=np.average)\n\n    >>> import matplotlib.pyplot as plt\n    >>> plt.figure(figsize=(10, 8))\n    >>> plt.subplot(5, 1, 1)\n    >>> librosa.display.specshow(chroma, y_axis=\'chroma\')\n    >>> plt.colorbar()\n    >>> plt.title(\'Unfiltered\')\n    >>> plt.subplot(5, 1, 2)\n    >>> librosa.display.specshow(chroma_med, y_axis=\'chroma\')\n    >>> plt.colorbar()\n    >>> plt.title(\'Median-filtered\')\n    >>> plt.subplot(5, 1, 3)\n    >>> librosa.display.specshow(chroma_nlm, y_axis=\'chroma\')\n    >>> plt.colorbar()\n    >>> plt.title(\'Non-local means\')\n    >>> plt.subplot(5, 1, 4)\n    >>> librosa.display.specshow(chroma - chroma_med,\n    ...                          y_axis=\'chroma\')\n    >>> plt.colorbar()\n    >>> plt.title(\'Original - median\')\n    >>> plt.subplot(5, 1, 5)\n    >>> librosa.display.specshow(chroma - chroma_nlm,\n    ...                          y_axis=\'chroma\', x_axis=\'time\')\n    >>> plt.colorbar()\n    >>> plt.title(\'Original - NLM\')\n    >>> plt.tight_layout()\n    '
    if (aggregate is None):
        aggregate = np.mean
    if (rec is None):
        kwargs = dict(kwargs)
        kwargs['sparse'] = True
        rec = segment.recurrence_matrix(S, axis=axis, **kwargs)
    elif (not scipy.sparse.issparse(rec)):
        rec = scipy.sparse.csr_matrix(rec)
    if ((rec.shape[0] != S.shape[axis]) or (rec.shape[0] != rec.shape[1])):
        raise ParameterError('Invalid self-similarity matrix shape rec.shape={} for S.shape={}'.format(rec.shape, S.shape))
    return __nn_filter_helper(rec.data, rec.indices, rec.indptr, S.swapaxes(0, axis), aggregate).swapaxes(0, axis)