{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Plot feature map\n\n\nThis example shows how to compute a feature map from de audio waveform.\n\nThis type of feature map for rhythmic patterns analysis was first proposed in [CIM2014]_.\n\n .. [CIM2014] *Tools for detection and classification of piano drum patterns from candombe\n              recordings.* Rocamora, Jure, Biscainho. 9th Conference on Interdisciplinary\n              Musicology (CIM), Berlin, Germany. 2014.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# Code source: Mart\u00edn Rocamora\n# License: MIT"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Imports\n  - matplotlib for visualization\n\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from __future__ import print_function\nimport matplotlib.pyplot as plt\nimport carat"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The accentuation feature is organized into a feature map.\nFirst, the feature signal is time-quantized to the rhythm metric\nstructure by considering a grid of tatum pulses equally distributed\nwithin the annotated beats. The corresponding feature value is taken\nas the maximum within window centered at the frame closest to each\ntatum instant. This yields feature vectors whose coordinates correspond\nto the tatum pulses of the rhythm cycle (or bar). Finally, a feature map\nof the cycle-length rhythmic patterns of the audio file is obtained by\nbuilding a matrix whose columns are consecutive feature vectors.\n\nFirst, we'll load one of the audio files included in `carat`.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "audio_path = carat.util.example_audio_file(num_file=1)\n\ny, sr = carat.audio.load(audio_path)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Next, we'll load the annotations provided for the example audio file.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "annotations_path = carat.util.example_beats_file(num_file=1)\n\nbeats, beat_labs = carat.annotations.load_beats(annotations_path)\ndownbeats, downbeat_labs = carat.annotations.load_downbeats(annotations_path)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Then, we'll compute the accentuation feature.\n\n**Note:** This example is tailored towards the rhythmic patterns of the lowest\nsounding of the three drum types taking part in the recording, so the analysis\nfocuses on the low frequencies (20 to 200 Hz).\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "acce, times, _ = carat.features.accentuation_feature(y, sr, minfreq=20, maxfreq=200)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Next, we'll compute the feature map. Note that we have to provide the beats,\nthe downbeats, which were loaded from the annotations. Besides, the number of\nbeats per bar and the number of of tatums (subdivisions) per beat has to be provided.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "n_beats = int(round(beats.size/downbeats.size))\nn_tatums = 4\n\nmap_acce, _, _, _ = carat.features.feature_map(acce, times, beats, downbeats, n_beats=n_beats,\n                                               n_tatums=n_tatums)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Finally we plot the feature map for the low frequencies of the audio file.\n\n**Note:** This feature map representation enables the inspection of the patterns evolution\nover time, as well as their similarities and differences, in a very informative way. Note that\nif a certain tatum pulse is articulated for several consecutive bars, it will be shown as a dark\nhorizontal line in the map. Conversely, changes in repetitive patterns are readily distinguishable\nas variations in the distribution of feature values.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "plt.figure(figsize=(12, 6))\nax1 = plt.subplot(211)\ncarat.display.map_show(map_acce, ax=ax1, n_tatums=n_tatums)\nplt.tight_layout()\n\nplt.show()"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.7.3"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}