E9-Sound_and_music_description.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Exercise 9: Sound and music description\n",
    "\n",
    "With this exercise you will learn to describe sounds with simple machine learning methods. You will learn to use the Freesound API to load pre-computed sound descriptors from Freesound and to perform sound clustering and classification with them. You will work with instrumental sounds, thus learning what audio features are useful for characterizing them.\n",
    "\n",
    "There are four parts in this exercise: 1) Download sounds and descriptors from Freesound, 2) Select two descriptors for a good sound clustering, 3) Cluster sounds using k-means, and 4) Classify sounds using k-NN.\n",
    "\n",
    "We provide the code for each task, thus no need to get involved in much programming. \n",
    "\n",
    "### Relevant Concepts\n",
    "\n",
    "#### Freesound API\n",
    "With the Freesound API you can browse, search, and retrieve information from Freesound, such as automatically extracted features from audio files. You can also perform advanced queries combining content analysis features and other metadata (tags, etc...). With the API you can do text searches similar to what you can do from the advance searches in the website http://freesound.org/search/?q, but implementing the the queries in software. If you are interested in knowing more about the Freesound API, you can see examples of using it with python in: https://github.com/MTG/freesound-python/blob/master/examples.py and you can read the API documentation, http://www.freesound.org/docs/api/\n",
    "\n",
    "#### Sound descriptors\n",
    "In this exercise, you will use sound descriptors that have been pre-computed with Essentia, https://essentia.upf.edu and are stored in the Freesound database together with the corresponding sounds. Many sound descriptors can be extracted using Essentia (http://essentia.upf.edu/documentation/algorithms_reference.html) and in Freesound, a number of them are used. In the Freesound API documentation there is specifc information of the descriptors available in Freesound, https://freesound.org/docs/api/analysis_index.html.\n",
    "\n",
    "### Euclidian distance\n",
    "The Euclidian distance is the straight-line distance between two points in an n-dimensional space, thus the distance between points $p$ and $q$ is the length of the line segment connecting them. If $p = (p_1, p_2,..., p_n)$ and $q = (q_1, q_2,..., q_n)$ are two points in Euclidean n-space, then the distance, $d$, from $p$ to $q$, or from $q$ to $p$ is given by the Pythagorean formula:\n",
    "\n",
    "$ d(p,q) = \\sqrt{\\sum^n_{i=1} (q_i - p_i)^2} $\n",
    "\n",
    "\n",
    "### K-means clustering (k-means)\n",
    "K-means clustering is a method of vector quantization that is popular for cluster analysis in data mining. K-means clustering aims to partition $n$ observations into $k$ clusters in which each observation belongs to the cluster with the nearest mean, serving as a prototype of the cluster. The problem is computationally difficult (NP-hard), however, efficient heuristic algorithms converge quickly to a local optimum. \n",
    "\n",
    "Given a set of observations $(x_1, x_2, …, x_n)$, where each observation is a d-dimensional real vector, k-means clustering aims to partition the $n$ observations into $k (≤ n)$ sets $S = {S_1, S_2, …, S_k}$ so as to minimize the within-cluster sum of squares (WCSS) (i.e. variance). Formally, the objective is to find:\n",
    "\n",
    "$\\underset{\\mathbf{S}} {\\operatorname{arg\\,min}}  \\sum_{i=1}^{k} \\sum_{\\mathbf x \\in S_i} \\left\\| \\mathbf x - \\boldsymbol\\mu_i \\right\\|^2 = \\underset{\\mathbf{S}} {\\operatorname{arg\\,min}}  \\sum_{i=1}^k |S_i| \\operatorname{Var} S_i$, where $μ_i$ is the mean of points in $S_i$.\n",
    "\n",
    "\n",
    "### K-nearest neighbours classifier (k-NN)\n",
    "K-nearest neighbours classification (k-NN) is a non-parametric method in which the input consists of the $k$ closest training examples in the feature space. The output is a class membership. An object is classified by a plurality vote of its neighbors, with the object being assigned to the class most common among its $k$ nearest neighbors ($k$ is a positive integer, typically small). If $k = 1$, then the object is simply assigned to the class of that single nearest neighbor.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Part 1: Download sounds and descriptors from Freesound\n",
    "\n",
    "Download a collection of intrumental sounds and their descriptors from Freesound using the Freesound API.\n",
    "\n",
    "First get a Freesound API key from http://www.freesound.org/apiv2/apply/ and create a directory in the workspace with the name `testDownload` to store the sounds and descriptors. You also need to install the python client for the freesound API. Do this by cloning the repository https://github.com/MTG/freesound-python, into a folder and installing it following the instructions. You will have to import the freesound module in the code.\n",
    "\n",
    "You will be calling the function `download_sounds_freesound()` whose input parameters are:\n",
    "1. `queryText` (string): A single word or a string of words without spaces (use hyphens), typically the name of the instrument. e.g. (eg. \"violin\", \"trumpet\", \"cello\", \"bassoon\", etc.)\n",
    "2. `tag` (string): tag to be used for filtering the searched sounds (e.g., \"multisample\", \"single-note\", \"velocity\", \"tenuto\", etc.).\n",
    "3. `duration` (2 floating point numbers): min and max duration (seconds) of the sound to filter, e.g., (0.2,15).\n",
    "4. `API_Key` (string): your api key.\n",
    "5. `outputDir` (string): path to the directory where you want to store the sounds and their descriptors.\n",
    "6. `topNResults` (integer): number of results (sounds) that you want to download.\n",
    "7. `featureExt` (file extension): file extension for storing sound descriptor (.json, typically).\n",
    "\n",
    "In the call to `download_sounds_freesound()` you will have to choose the appropriate queryText, tag, and duration, to return single notes/strokes of instrumental sounds. The first twenty results of the query should be \"good\". Note that the tag can be empty. Example of a query to obtain single notes of violin could be: `download_sounds_freesound(queryText='violin', API_Key=<your key>, outputDir='testDownload/', topNResults=20, duration=(0,8.5), tag='single-note')`. This returns 20 single notes of violin sounds and the script stores them in the testDownload directory (the directory has to be created beforehand).\n",
    "\n",
    "Download and store twenty sound examples of each instrument using the `download_sounds_freesound()` function given below. The examples need to be representative of the instrument, single notes (melodic instruments) or single strokes (percussion instruments), and shorter than 10 seconds. Specify a good query text, tag, and duration to query for the chosen instruments. Refine your search parameters until you get twenty good samples for each instrument. Select three instruments to be used out of this set: violin, guitar, bassoon, trumpet, clarinet, cello, naobo (cymbals used in Beijing Opera). Listen to the sounds downloaded and look at the descriptor .json files.\n",
    "\n",
    "Before using the API to download the sounds, we recommend to do the same query using the Freesound website and checking that the top 20 results are good."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os, sys\n",
    "import json\n",
    "sys.path.append('../../freesound-python/')  # directory were you installed the freesound-python repository\n",
    "import freesound as fs\n",
    "\n",
    "descriptors = [ 'lowlevel.spectral_centroid.mean',\n",
    "                'lowlevel.spectral_contrast.mean',\n",
    "                'lowlevel.dissonance.mean',\n",
    "                'lowlevel.hfc.mean',\n",
    "                'lowlevel.mfcc.mean',\n",
    "                'sfx.logattacktime.mean',\n",
    "                'sfx.inharmonicity.mean']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {},
   "outputs": [],
   "source": [
    "def download_sounds_freesound(queryText = \"\", tag=None, duration=None, API_Key = \"\", outputDir = \"\", topNResults = 5, featureExt = '.json'):\n",
    "  \"\"\"\n",
    "  This function downloads sounds and their descriptors from freesound using the queryText and the \n",
    "  tag specified in the input. Additionally, you can also specify the duration range to filter sounds \n",
    "  based on duration.\n",
    "  \n",
    "  Inputs:\n",
    "        (Input parameters marked with a * are optional)\n",
    "        queryText (string): query text for the sounds (eg. \"violin\", \"trumpet\", \"cello\", \"bassoon\" etc.)\n",
    "        tag* (string): tag to be used for filtering the searched sounds. (eg. \"multisample\",  \n",
    "                       \"single-note\" etc.)\n",
    "        duration* (tuple): min and the max duration (seconds) of the sound to filter, eg. (0.2,15)\n",
    "        API_Key (string): your api key, which you can obtain from : www.freesound.org/apiv2/apply/\n",
    "        outputDir (string): path to the directory where you want to store the sounds and their \n",
    "                            descriptors\n",
    "        topNResults (integer): number of results(sounds) that you want to download \n",
    "        featureExt (string): file extension for storing sound descriptors\n",
    "  output:\n",
    "        This function downloads sounds and descriptors, and then stores them in outputDir. In \n",
    "        outputDir it creates a directory of the same name as that of the queryText. In this \n",
    "        directory outputDir/queryText it creates a directory for every sound with the name \n",
    "        of the directory as the sound id. Additionally, this function also dumps a text file \n",
    "        containing sound-ids and freesound links for all the downloaded sounds in the outputDir. \n",
    "        NOTE: If the directory outputDir/queryText exists, it deletes the existing contents \n",
    "        and stores only the sounds from the current query. \n",
    "  \"\"\" \n",
    "  \n",
    "  # Checking for the compulsory input parameters\n",
    "  if queryText == \"\":\n",
    "    print(\"\\n\")\n",
    "    print(\"Provide a query text to search for sounds\")\n",
    "    return -1\n",
    "    \n",
    "  if API_Key == \"\":\n",
    "    print(\"\\n\")\n",
    "    print(\"You need a valid freesound API key to be able to download sounds.\")\n",
    "    print(\"Please apply for one here: www.freesound.org/apiv2/apply/\")\n",
    "    print(\"\\n\")\n",
    "    return -1\n",
    "    \n",
    "  if outputDir == \"\" or not os.path.exists(outputDir):\n",
    "    print(\"\\n\")\n",
    "    print(\"Please provide a valid output directory. This will be the root directory for storing sounds and descriptors\")\n",
    "    return -1    \n",
    "  \n",
    "  # Setting up the Freesound client and the authentication key\n",
    "  fsClnt = fs.FreesoundClient()\n",
    "  fsClnt.set_token(API_Key,\"token\")  \n",
    "  \n",
    "  # Creating a duration filter string that the Freesound API understands\n",
    "  if duration and type(duration) == tuple:\n",
    "    flt_dur = \" duration:[\" + str(duration[0])+ \" TO \" +str(duration[1]) + \"]\"\n",
    "  else:\n",
    "    flt_dur = \"\"\n",
    " \n",
    "  if tag and type(tag) == str:\n",
    "    flt_tag = \"tag:\"+tag\n",
    "  else:\n",
    "    flt_tag = \"\"\n",
    "\n",
    "  # Querying Freesound\n",
    "  page_size = 30\n",
    "  if not flt_tag + flt_dur == \"\":\n",
    "    qRes = fsClnt.text_search(query=queryText ,filter = flt_tag + flt_dur,sort=\"score\", fields=\"id,name,previews,username,url,analysis\", descriptors=','.join(descriptors), page_size=page_size, normalized=1)\n",
    "  else:\n",
    "    qRes = fsClnt.text_search(query=queryText ,sort=\"score\",fields=\"id,name,previews,username,url,analysis\", descriptors=','.join(descriptors), page_size=page_size, normalized=1)\n",
    "  \n",
    "  outDir2 = os.path.join(outputDir, queryText)\n",
    "  if os.path.exists(outDir2):             # If the directory exists, it deletes it and starts fresh\n",
    "      os.system(\"rm -r \" + outDir2)\n",
    "  os.mkdir(outDir2)\n",
    "\n",
    "  pageNo = 1\n",
    "  sndCnt = 0\n",
    "  indCnt = 0\n",
    "  totalSnds = min(qRes.count,200)   # System quits after trying to download after 200 times\n",
    "  \n",
    "  # Creating directories to store output and downloading sounds and their descriptors\n",
    "  downloadedSounds = []\n",
    "  while(1):\n",
    "    if indCnt >= totalSnds:\n",
    "      print(\"Not able to download required number of sounds. Either there are not enough search results on freesound for your search query and filtering constraints or something is wrong with this script.\")\n",
    "      break\n",
    "    sound = qRes[indCnt - ((pageNo-1)*page_size)]\n",
    "    print(\"Downloading mp3 preview and descriptors for sound with id: %s\"%str(sound.id))\n",
    "    outDir1 = os.path.join(outputDir, queryText, str(sound.id))\n",
    "    if os.path.exists(outDir1):\n",
    "      os.system(\"rm -r \" + outDir1)\n",
    "    os.system(\"mkdir \" + outDir1)\n",
    "    \n",
    "    mp3Path = os.path.join(outDir1,  str(sound.previews.preview_lq_mp3.split(\"/\")[-1]))\n",
    "    ftrPath = mp3Path.replace('.mp3', featureExt)\n",
    "    \n",
    "    try:\n",
    "      \n",
    "      fs.FSRequest.retrieve(sound.previews.preview_lq_mp3, fsClnt, mp3Path)\n",
    "      # Initialize a dictionary to store descriptors\n",
    "      features = {}\n",
    "      # Obtaining all the descriptors\n",
    "      for desc in descriptors:\n",
    "        features[desc]=[]\n",
    "        features[desc].append(eval(\"sound.analysis.\"+desc))\n",
    "      \n",
    "      # Once we have all the descriptors, store them in a json file\n",
    "      json.dump(features, open(ftrPath,'w'))\n",
    "      sndCnt+=1\n",
    "      downloadedSounds.append([str(sound.id), sound.url])\n",
    "\n",
    "    except:\n",
    "      if os.path.exists(outDir1):\n",
    "        os.system(\"rm -r \" + outDir1)\n",
    "    \n",
    "    indCnt +=1\n",
    "    \n",
    "    if indCnt%page_size==0:\n",
    "      qRes = qRes.next_page()\n",
    "      pageNo+=1\n",
    "      \n",
    "    if sndCnt>=topNResults:\n",
    "      break\n",
    "  # Dump the list of files and Freesound links\n",
    "  fid = open(os.path.join(outDir2, queryText+'_SoundList.txt'), 'w')\n",
    "  for elem in downloadedSounds:\n",
    "    fid.write('\\t'.join(elem)+'\\n')\n",
    "  fid.close()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# call download_sounds_freesound for 3 instruments\n",
    "### your code here\n",
    "key = 'WUxcKwn7VSCRcMRH6yH4WLV7h4dfZYfiBwoK2vyq'\n",
    "\n",
    "download_sounds_freesound(queryText='guitar', API_Key=key, outputDir='testDownload/', topNResults=20, duration=(0,10), tag='single-note')\n",
    "download_sounds_freesound(queryText='trumpet', API_Key=key, outputDir='testDownload/', topNResults=20, duration=(0,10), tag='single-note')\n",
    "download_sounds_freesound(queryText='cello', API_Key=key, outputDir='testDownload/', topNResults=20, duration=(0,10), tag='single-note')\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Part 2: Select two descriptors for a good sound clustering\n",
    "\n",
    "Select two of the sound descriptors obtained from Task 1 in order to obtain a good clustering of the sounds of three instruments in a two dimensional space. By visualizing the descriptor values of the sounds in a 2D plot you can choose the features that can help to better cluster these instruments. \n",
    "\n",
    "You take as inputs the downloaded sounds folder (`targetDir`) and the descriptor pair indices (`descInput`) (see mapping) to create a 2-D scatter plot of the descriptor pair. The data points, sounds, from different instruments are shown with different colors. In addition, you can also plot the Freesound ID of the sounds with the points. Only plot the sounds of the 3 instruments chosen. Make sure that in `targetDir` you only have the 3 instruments chosen.\n",
    "\n",
    "Choose a good pair of descriptors for the sounds of the 3 instruments you downloaded in Part 1. A good pair of descriptors leads to a point distribution where all the sounds of an instrument cluster together, with a good separation from the other instrument clusters. Try out different combinations of descriptor pairs. Write a short paragraph on the descriptor pairs you tried out, justifying your choices for selecting those particular descriptors. Based on the spectral and temporal features of the instruments and sounds, give an explanation of why (or why not) a good clustering is (or is not) achieved with the chosen pairs of descriptors.\n",
    "\n",
    "From the code given you can generate a 2-D scatter plot of all sounds for the chosen descriptor pairs. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os, sys\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "from matplotlib.lines import Line2D\n",
    "from scipy.cluster.vq import vq, kmeans, whiten\n",
    "\n",
    "# Mapping of descriptors\n",
    "descriptorMapping = { 0: 'lowlevel.spectral_centroid.mean',\n",
    "                      1: 'lowlevel.dissonance.mean',\n",
    "                      2: 'lowlevel.hfc.mean',\n",
    "                      3: 'sfx.logattacktime.mean',\n",
    "                      4: 'sfx.inharmonicity.mean',\n",
    "                      5: 'lowlevel.spectral_contrast.mean.0',\n",
    "                      6: 'lowlevel.spectral_contrast.mean.1',\n",
    "                      7: 'lowlevel.spectral_contrast.mean.2',\n",
    "                      8: 'lowlevel.spectral_contrast.mean.3',\n",
    "                      9: 'lowlevel.spectral_contrast.mean.4',\n",
    "                      10: 'lowlevel.spectral_contrast.mean.5',\n",
    "                      11: 'lowlevel.mfcc.mean.0',\n",
    "                      12: 'lowlevel.mfcc.mean.1',\n",
    "                      13: 'lowlevel.mfcc.mean.2',\n",
    "                      14: 'lowlevel.mfcc.mean.3',\n",
    "                      15: 'lowlevel.mfcc.mean.4',\n",
    "                      16: 'lowlevel.mfcc.mean.5'\n",
    "                    }"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "def convFtrDict2List(ftrDict):\n",
    "  \"\"\"\n",
    "  This function converts descriptor dictionary to an np.array. The order in the numpy array (indices) \n",
    "  are same as those mentioned in descriptorMapping dictionary.\n",
    "  \n",
    "  Input: \n",
    "    ftrDict (dict): dictionary containing descriptors downloaded from the freesound\n",
    "  Output: \n",
    "    ftr (np.ndarray): Numpy array containing the descriptors for processing later on\n",
    "  \"\"\"\n",
    "  ftr = []\n",
    "  for key in range(len(descriptorMapping.keys())):\n",
    "    try:\n",
    "      ftrName, ind = '.'.join(descriptorMapping[key].split('.')[:-1]), int(descriptorMapping[key].split('.')[-1])\n",
    "      ftr.append(ftrDict[ftrName][0][ind])\n",
    "    except:\n",
    "      ftr.append(ftrDict[descriptorMapping[key]][0])\n",
    "  return np.array(ftr)\n",
    "\n",
    "def fetchDataDetails(inputDir, descExt = '.json'):\n",
    "  \"\"\"\n",
    "  This function is used by other functions to obtain the information regarding the directory structure \n",
    "  and the location of descriptor files for each sound \n",
    "  \"\"\"\n",
    "  dataDetails = {}\n",
    "  for path, dname, fnames  in os.walk(inputDir):\n",
    "    for fname in fnames:\n",
    "      if descExt in fname.lower():\n",
    "        remain, rname, cname, sname = path.split('/')[:-3], path.split('/')[-3], path.split('/')[-2], path.split('/')[-1]\n",
    "        if cname not in dataDetails:\n",
    "          dataDetails[cname]={}\n",
    "        fDict = json.load(open(os.path.join('/'.join(remain), rname, cname, sname, fname),'r'))\n",
    "        dataDetails[cname][sname]={'file': fname, 'feature':fDict}\n",
    "  return dataDetails"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<matplotlib.legend.Legend at 0x7fe50b4d87f0>"
      ]
     },
     "execution_count": 42,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAA3sAAAJqCAYAAACSMFlpAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAALEgAACxIB0t1+/AAAADl0RVh0U29mdHdhcmUAbWF0cGxvdGxpYiB2ZXJzaW9uIDIuMS4xLCBodHRwOi8vbWF0cGxvdGxpYi5vcmcvAOZPmwAAIABJREFUeJzs3X9wXHd97//X55zdlVYra9cr2ZGJEzu/ZNnOjZRGDbcpxaZ1ILSGUgMd8sVJsUpbXb786BfTAYYZvh3m2146tHy/UNoRlAgKglKGm94GQxOctlKY5l6KTKQ0sdaKQxySxiKW5F1bq5V09pzP9w/9iOzIlmTraKXV85HxjLX6HPkt2XOilz6f834ba60AAAAAAOXFKXUBAAAAAIDlR9gDAAAAgDJE2AMAAACAMkTYAwAAAIAyRNgDAAAAgDIUKXUBS3Xs2LHNkUjky5JuFWEVAAAAwPoRSHqqWCy+94477nh5ocVrLuxFIpEv19fX79y0adNZx3GYGwEAAABgXQiCwJw5c2bX4ODglyW9daH1a3Fn7NZNmzadI+gBAAAAWE8cx7GbNm3KaeqU48LrQ64nDA5BDwAAAMB6NJ2FFpXj1twxzqV48exY9KEfPbfxR8dOpkcnim51RcR/7R03j7z1tTec3bqxyit1fQCAcLx4diz67WPPbXz4+Ml0fqLoJioi/j27bh757Tu4/wPAWvfi2bHot3/y4saHn3n5lXv8LZtHfvsXtnKPv8ha3NlblMefHUp84nPfvzn5wBfr/uzhv7TffuQz3p89/Jc2+cAX6z7xue/f/PizQ4mVquWxxx6res973nOdJB05cmTD0aNHV+zPBoD15vFnhxL3ffX7N3/9P75YNxL7S+ulPuONxP7Sfv0/vlh331dX5v7/+c9/vvb++++/XpI+/OEPv+aTn/zkNWH/mQCwHjz+7FDivr/rufnrIy/XjeyOWe+uam9kd8x+feTluvv+rueK7/FDQ0Pupz/96U3LXe+V+vznP1976tSp6NV+nLIMey+eHYt+8etd13/8sb+17/7Zj4r1k+etK6v6yfP23T/7UfHjj/2t/eLXu65/8ezYVX8BF+P1r3/92Fe/+tUXJOlf/uVfNvzwhz+sXsr1nscPKABgMV48Oxb9xENd1+dif2tjG35UdCPnrTFWbuS8jW34UTEX+1v7iYdW7v4PAFg+L54di37ikePX5xpjNnZjvOhWudY4Rm6Va2M3xou5xpj9xCPHr+gePzw87D7wwAObL369WCwuT/FL1NnZWfezn/2MsDefh3703MY3Pv2Yacy/HMz3/sb8y8HdTz9mvvvvpzZe6Z/xR3/0R1tuuOGG3Xfdddctb3nLW2745Cc/ec2dd96547HHHquSpNOnT0euvfba/yJN7ea94Q1vuPnEiROxr33ta5va29uvaWxs3PXwww9Xf/Ob30zedtttjTt37tx11113NbzwwgsRaeonwffee++2X/7lX77lwIEDN1xpnQCwnnz72HMbs3rMRCvmv/9HK14OsnrMfOfYld3/v/CFL9Q2NDTs2rFjx663ve1tN7z00kuRN73pTTfdeuutO2+99dadP/jBDy77E+XHH3883tTU1NjQ0LDr7rvvvunMmTPuldQBAOvRt3/y4sbsJsdEk9H57/HJaJDd5JjvPPHiku/xhw8f3vrCCy9UNDY27rr11lt3vva1r214y1vecsOOHTt2nzhxInbLLbfsnln7yU9+8poPf/jDr5GkO++8c8fv/u7vXtfS0rLjxhtv3N3d3V31xje+8aZt27bd+sEPfvA1knTixInYDTfcsPvAgQPbGxoadt1zzz03nj9/3pGkH/7wh1W/+Iu/uGP37t07X/e6193y/PPPR7/yla9sfOqpp6ruv//+GxsbG3eNjo6aK/uKlWnY+9Gxk+lfGzzuX27NvsHj/o+OPXNF/7N/7LHHqr773e9u/I//+I/j3/ve95598sknF7VdvGPHjsn777//TFtb288zmczxe+65Z/Tuu+8e7e3tzfT39x9/xzveMfKpT32qfmb9k08+WfXII4+c/O53v/vcldQJAOvNw8dPpt345e//bvy4/0/Hl37/7+npqfzzP//zLd3d3QMnTpw4/sUvfvFnf/AHf3Ddhz/84Z8/9dRT/f/wD//wbFtb2/bLfYz3vOc9N/zpn/7piwMDA8d3795d+OhHP/qapdYBAOvVw8+8nHbrY5e/x9fH/H8aeHnJ9/i/+Iu/ePG6666byGQyxz/96U+/+OSTTyY+85nP/Oezzz779ELXxmKxoKen58ShQ4fOvPOd77z5b/7mb36WyWSe/vu///u6wcFBV5JOnTpV2dbWdmZgYOD4hg0bgs985jObJiYmzAc/+MHr//Ef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\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x7fe50b5a8b70>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# code to select the descriptors to plot\n",
    "inputDir = \"testDownload/\"\n",
    "\n",
    "### this is the main line to modify, select two descriptors, change the XX by a number from 0 to 16\n",
    "\n",
    "descInput = (0,3)\n",
    "\n",
    "\n",
    "# no need to change the code from here\n",
    "anotOn = 0\n",
    "dataDetails = fetchDataDetails(inputDir)\n",
    "colors = ['r', 'g', 'c', 'b', 'k', 'm', 'y']\n",
    "\n",
    "plt.figure(figsize=(15, 10))\n",
    "legArray = []\n",
    "catArray = []\n",
    "for ii, category in enumerate(dataDetails.keys()):\n",
    "    catArray.append(category)\n",
    "    for soundId in dataDetails[category].keys():\n",
    "        filepath = os.path.join(inputDir, category, soundId, dataDetails[category][soundId]['file'])\n",
    "        descSound = convFtrDict2List(json.load(open(filepath, 'r')))\n",
    "        x_cord = descSound[descInput[0]]\n",
    "        y_cord = descSound[descInput[1]]\n",
    "        plt.scatter(x_cord, y_cord, c = colors[ii], s=200, alpha=0.75)\n",
    "        if anotOn==1:\n",
    "            plt.annotate(soundId, xy=(x_cord, y_cord), xytext=(x_cord, y_cord))\n",
    "    circ = Line2D([0], [0], linestyle=\"none\", marker=\"o\", alpha=0.75, markersize=10, markerfacecolor=colors[ii])\n",
    "    legArray.append(circ)\n",
    "  \n",
    "plt.ylabel(descriptorMapping[descInput[1]])\n",
    "plt.xlabel(descriptorMapping[descInput[0]])\n",
    "plt.legend(legArray,catArray,numpoints=1,bbox_to_anchor=(0.,1.02,1.,.102),loc=3,ncol=len(catArray),mode=\"expand\",borderaxespad=0.)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### EXPLANATION\n",
    "\n",
    "**X axis: Spectral centroid.** The spectral centroid allows to classify satisfactorily cello and trumpets because of the different spectral characteristics that they have. However, this descriptor does not allow to classify guitar samples. This is due to the guitar samples are a mixed of spanish guitar and electric guitars with different effects applied, and therefore the spectrum of the samples will be very different from each other.\n",
    "\n",
    "So having cellos and trumpets already classyfied it is only needed a parameter that allows to differentiate between trumpet and cello, and guitar. This is why \"Attack Time\" descriptor is selected. \n",
    "\n",
    "**Y axis: Attack Time.** Because of how each instrument is played a clear difference is shown between cello and trumpet with guitar. Because trumpet is a brass instrument and cello is a bowed string instrument their attacks are slower than the guitar that is a fretted musical instrument. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Part 3: Cluster sounds using k-means\n",
    "\n",
    "After visualizing the sound descriptors, you will now cluster the sounds using more than two descriptors. You can use as many descriptors as you need for the best clustering. Use the same set of sounds obtain in Task 1, starting from the descriptors that you found were good in Part 2, and then adding other descriptors that you feel can improve the kmeans clustering of sounds. The function `cluster_sounds()` takes the sounds folder (targetDir), number of clusters (nCluster) and the descriptor indices (descInput) as input. It then performs a kmeans clustering using the selected descriptors. Make sure that in targetDir you only have the 3 instruments chosen.\n",
    "\n",
    "For this part, you can use as many descriptors as you need to achieve good clustering and classification performance. However it is best to use as few descriptors as possible in order to make it easier to explain the contribution of each descriptor. Choose the number of clusters to be the same as the number of instruments (i.e., 3). Ideally in such a case, all the sounds of an instrument should go into a single cluster. In reality however, there might be sounds that are outliers and can go into a different cluster. The algorithm takes a majority vote on the sounds in each of the three clusters and assigns each cluster to an instrument. We compute the performance of the clustering by checking the number of points (sounds), that have been wrongly assigned to a cluster. The function clusterSounds() prints the clusters and the sounds assigned to each one. The function also prints the resulting classification obtained with the choice of descriptors you made.\n",
    "\n",
    "Write a short paragraph explaining the descriptors you used, the resulting classification accuracy you obtained, and your observations on why you obtained (or not) those errors in clustering. Comment if you see any systematic errors (such as a consistent mix up of sounds from two instruments) and possible reasons for that. You should also try to cluster with different subsets of descriptors and mention the classification accuracy you obtain in each case.\n",
    "\n",
    "Note: Since the cluster centers are randomly initialized every time in k-means, you might see different results every time you run the function. You can report the best result you obtained."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "def cluster_sounds(targetDir, nCluster = -1, descInput=[]):\n",
    "  \"\"\"\n",
    "  This function clusters all the sounds in targetDir using kmeans clustering.\n",
    "  \n",
    "  Input:\n",
    "    targetDir (string): Directory where sound descriptors are stored (all the sounds in this \n",
    "                        directory will be used for clustering)\n",
    "    nCluster (int): Number of clusters to be used for kmeans clustering.\n",
    "    descInput (list) : List of indices of the descriptors to be used for similarity/distance \n",
    "                       computation (see descriptorMapping)\n",
    "  Output:\n",
    "    Prints the class of each cluster (computed by a majority vote), number of sounds in each \n",
    "    cluster and information (sound-id, sound-class and classification decision) of the sounds \n",
    "    in each cluster. Optionally, you can uncomment the return statement to return the same data.\n",
    "  \"\"\"\n",
    "  \n",
    "  dataDetails = fetchDataDetails(targetDir)\n",
    "  \n",
    "  ftrArr = []\n",
    "  infoArr = []\n",
    "  \n",
    "  if nCluster ==-1:\n",
    "    nCluster = len(dataDetails.keys())\n",
    "  for cname in dataDetails.keys():\n",
    "    #iterating over sounds\n",
    "    for sname in dataDetails[cname].keys():\n",
    "      ftrArr.append(convFtrDict2List(dataDetails[cname][sname]['feature'])[descInput])\n",
    "      infoArr.append([sname, cname])\n",
    "  \n",
    "  ftrArr = np.array(ftrArr)\n",
    "  infoArr = np.array(infoArr)\n",
    "  \n",
    "  ftrArrWhite = whiten(ftrArr)\n",
    "  centroids, distortion = kmeans(ftrArrWhite, nCluster)\n",
    "  clusResults = -1*np.ones(ftrArrWhite.shape[0])\n",
    "  \n",
    "  for ii in range(ftrArrWhite.shape[0]):\n",
    "    diff = centroids - ftrArrWhite[ii,:]\n",
    "    diff = np.sum(np.power(diff,2), axis = 1)\n",
    "    indMin = np.argmin(diff)\n",
    "    clusResults[ii] = indMin\n",
    "  \n",
    "  ClusterOut = []\n",
    "  classCluster = []\n",
    "  globalDecisions = []  \n",
    "  for ii in range(nCluster):\n",
    "    ind = np.where(clusResults==ii)[0]\n",
    "    freqCnt = []\n",
    "    for elem in infoArr[ind,1]:\n",
    "      freqCnt.append(infoArr[ind,1].tolist().count(elem))\n",
    "    indMax = np.argmax(freqCnt)\n",
    "    classCluster.append(infoArr[ind,1][indMax])\n",
    "    \n",
    "    print(\"\\n(Cluster: \" + str(ii) + \") Using majority voting as a criterion this cluster belongs to \" + \n",
    "          \"class: \" + classCluster[-1])\n",
    "    print (\"Number of sounds in this cluster are: \" + str(len(ind)))\n",
    "    decisions = []\n",
    "    for jj in ind:\n",
    "        if infoArr[jj,1] == classCluster[-1]:\n",
    "            decisions.append(1)\n",
    "        else:\n",
    "            decisions.append(0)\n",
    "    globalDecisions.extend(decisions)\n",
    "    print (\"sound-id, sound-class, classification decision\")\n",
    "    ClusterOut.append(np.hstack((infoArr[ind],np.array([decisions]).T)))\n",
    "    print (ClusterOut[-1])\n",
    "  globalDecisions = np.array(globalDecisions)\n",
    "  totalSounds = len(globalDecisions)\n",
    "  nIncorrectClassified = len(np.where(globalDecisions==0)[0])\n",
    "  print(\"Out of %d sounds, %d sounds are incorrectly classified considering that one cluster should \"\n",
    "        \"ideally contain sounds from only a single class\"%(totalSounds, nIncorrectClassified))\n",
    "  print(\"You obtain a classification (based on obtained clusters and majority voting) accuracy \"\n",
    "         \"of %.2f percentage\"%round(float(100.0*float(totalSounds-nIncorrectClassified)/totalSounds),2))\n",
    "  # return ClusterOut"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "(Cluster: 0) Using majority voting as a criterion this cluster belongs to class: cello\n",
      "Number of sounds in this cluster are: 20\n",
      "sound-id, sound-class, classification decision\n",
      "[['110455' 'guitar' '0']\n",
      " ['91199' 'guitar' '0']\n",
      " ['246845' 'cello' '1']\n",
      " ['246843' 'cello' '1']\n",
      " ['246830' 'cello' '1']\n",
      " ['246837' 'cello' '1']\n",
      " ['246840' 'cello' '1']\n",
      " ['246836' 'cello' '1']\n",
      " ['246842' 'cello' '1']\n",
      " ['246834' 'cello' '1']\n",
      " ['246827' 'cello' '1']\n",
      " ['246828' 'cello' '1']\n",
      " ['246838' 'cello' '1']\n",
      " ['246831' 'cello' '1']\n",
      " ['246844' 'cello' '1']\n",
      " ['246829' 'cello' '1']\n",
      " ['246832' 'cello' '1']\n",
      " ['246839' 'cello' '1']\n",
      " ['246826' 'cello' '1']\n",
      " ['246841' 'cello' '1']]\n",
      "\n",
      "(Cluster: 1) Using majority voting as a criterion this cluster belongs to class: guitar\n",
      "Number of sounds in this cluster are: 18\n",
      "sound-id, sound-class, classification decision\n",
      "[['399483' 'guitar' '1']\n",
      " ['399468' 'guitar' '1']\n",
      " ['399490' 'guitar' '1']\n",
      " ['399481' 'guitar' '1']\n",
      " ['399478' 'guitar' '1']\n",
      " ['399484' 'guitar' '1']\n",
      " ['52048' 'guitar' '1']\n",
      " ['399475' 'guitar' '1']\n",
      " ['399486' 'guitar' '1']\n",
      " ['399469' 'guitar' '1']\n",
      " ['399470' 'guitar' '1']\n",
      " ['399472' 'guitar' '1']\n",
      " ['399466' 'guitar' '1']\n",
      " ['399471' 'guitar' '1']\n",
      " ['399479' 'guitar' '1']\n",
      " ['399474' 'guitar' '1']\n",
      " ['399467' 'guitar' '1']\n",
      " ['399473' 'guitar' '1']]\n",
      "\n",
      "(Cluster: 2) Using majority voting as a criterion this cluster belongs to class: trumpet\n",
      "Number of sounds in this cluster are: 22\n",
      "sound-id, sound-class, classification decision\n",
      "[['257749' 'cello' '0']\n",
      " ['257996' 'cello' '0']\n",
      " ['357360' 'trumpet' '1']\n",
      " ['357387' 'trumpet' '1']\n",
      " ['357384' 'trumpet' '1']\n",
      " ['357385' 'trumpet' '1']\n",
      " ['357386' 'trumpet' '1']\n",
      " ['357365' 'trumpet' '1']\n",
      " ['357344' 'trumpet' '1']\n",
      " ['357351' 'trumpet' '1']\n",
      " ['357383' 'trumpet' '1']\n",
      " ['357378' 'trumpet' '1']\n",
      " ['357336' 'trumpet' '1']\n",
      " ['357388' 'trumpet' '1']\n",
      " ['357389' 'trumpet' '1']\n",
      " ['357377' 'trumpet' '1']\n",
      " ['357391' 'trumpet' '1']\n",
      " ['357363' 'trumpet' '1']\n",
      " ['357390' 'trumpet' '1']\n",
      " ['357364' 'trumpet' '1']\n",
      " ['357380' 'trumpet' '1']\n",
      " ['357361' 'trumpet' '1']]\n",
      "Out of 60 sounds, 4 sounds are incorrectly classified considering that one cluster should ideally contain sounds from only a single class\n",
      "You obtain a classification (based on obtained clusters and majority voting) accuracy of 93.33 percentage\n"
     ]
    }
   ],
   "source": [
    "# run the function clusterSounds \n",
    "### your code here\n",
    "\n",
    "cluster_sounds('../workspace/testDownload', nCluster = 3, descInput=[0,1,3,7])\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### EXPLANATION\n",
    "\n",
    "Adding the features of **inharmonicity** and **spectral contrast mean** helps to achieve a classification process with an accuracy of 93.33%.\n",
    "\n",
    "**Inharmonicity** helps to concentrate cello and trumpet clusters because is a descriptor that is very specific for each instrument. To help with some error that occur when introducing inharmonicity with 3 guitar samples and 2 cello samples (with low-end components) **Spectral contrast mean 2** which analyzes the spectral components split in octaves, and this improves a bit the classification performance.\n",
    "\n",
    "Still two guitar samples are classified wrongly because of the effects that they have and also two cello samples because of their low-end components."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Part 4: Classify sounds with k-NN\n",
    "\n",
    "Assign a sound different from the sounds of the 3 instruments chosen to one of the 3 instrumental classes you chose in Part 1, using the k-nearest neighbours classifier (k-NN). \n",
    "\n",
    "Given a new sound (query sound) and its descriptors, use the function `classify_sound_kNN()` for doing a k-NN classification. It uses a distance measure based on Euclidian distance which is implemented in `compute_similar_sounds()`. `classify_sound_kNN()` returns the instrument class that the query sound is classified into. \n",
    "\n",
    "The goal of the exercise is to experiment with the k-NN classifier and be able to understand the result by being able to explain why a particular query sound, that is not from any of the defined classes, is actually classified to one of those classes.\n",
    "\n",
    "4.1 Get query sounds from Freesound. To get query sounds and their descriptors, you can use `download_sounds_freesound()` function using different query texts (as you did in Part 1). Get sounds that are not from the 3 instruments you chose in Part 1, or at least that is none of the sounds you used to define the classes. If you use a sound from one of the three instruments make sure that is different enough from the existing sounds in your collections.\n",
    "\n",
    "4.2 Perform 5 classifications. You can use as many descriptors as you need (the fewer you use, the easier it will be, to explain the result). k is usually chosen to be an odd positive integer. Try out with different query sounds, different subsets of descriptors, and different values of k. Explain the reason for choosing the descriptors you used and the value of k you selected. Include cases where you think the classification is incorrect, and cases with a query sound of an instrument different from the starting classes. By trying out a sound from a different instrument, you are classifying the sound into the closest instrument class, which can tell you about similarity between instruments."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "metadata": {},
   "outputs": [],
   "source": [
    "def compute_similar_sounds(queryFile, targetDir, descInput = []):\n",
    "  \"\"\"\n",
    "  This function returns similar sounds for a specific queryFile. Given a queryFile this function \n",
    "  computes the distance of the query to all the sounds found in the targetDir and sorts them in \n",
    "  the increasing order of the distance. This way we can obtain similar sounds to a query sound.\n",
    "  \n",
    "  Input:\n",
    "    queryFile (string): Descriptor file (.json, unless changed)\n",
    "    targetDir (string): Target directory to search for similar sounds (using their descriptor files)\n",
    "    descInput (list) : list of indices of the descriptors to be used for similarity/distance computation \n",
    "                       (see descriptorMapping)\n",
    "  Output: \n",
    "    List containing an ordered list of similar sounds. \n",
    "  \"\"\"\n",
    "  \n",
    "  dataDetails = fetchDataDetails(targetDir)\n",
    "  \n",
    "  #reading query feature dictionary\n",
    "  qFtr = json.load(open(queryFile, 'r'))\n",
    "  dist = []\n",
    "  # Iterating over classes\n",
    "  for cname in dataDetails.keys():\n",
    "    # Iterating over sounds\n",
    "    for sname in dataDetails[cname].keys():\n",
    "      f1 =  convFtrDict2List(qFtr)\n",
    "      f2 =  convFtrDict2List(dataDetails[cname][sname]['feature'])\n",
    "      eucDist = np.sqrt(np.sum(np.power(np.array(f1[descInput]) - np.array(f2[descInput]), 2)))\n",
    "      dist.append([eucDist, sname, cname])\n",
    "  \n",
    "  # Sorting the array based on the distance\n",
    "  indSort = np.argsort(np.array(dist)[:,0])\n",
    "  return (np.array(dist)[indSort,:]).tolist()\n",
    "\n",
    "        \n",
    "def classify_sound_kNN(queryFile, targetDir, K, descInput = []):\n",
    "  \"\"\"\n",
    "  This function performs the KNN classification of a sound. The nearest neighbors are chosen from \n",
    "  the sounds in the targetDir.\n",
    "   \n",
    "  Input:\n",
    "    queryFile (string): Descriptor file (.json, unless changed)\n",
    "    targetDir (string): Target directory to search for similar sounds (using their descriptor files)\n",
    "    K (int) : Number of nearest neighbors to consider for KNN classification.\n",
    "    descInput (list) : List of indices of the descriptors to be used for similarity/distance computation \n",
    "                      (see descriptorMapping)\n",
    "  Output:\n",
    "    predClass (string): Predicted class of the query sound\n",
    "  \"\"\"\n",
    "  distances = compute_similar_sounds(queryFile, targetDir, descInput)\n",
    "  if len(np.where((np.array(distances)[:,0].astype(np.float64))==0)[0])>0:\n",
    "    print(\"Warning: We found an exact copy of the query file in the target directory. \"\n",
    "          \"Beware of duplicates while doing KNN classification.\")\n",
    "  \n",
    "  classes = (np.array(distances)[:K,2]).tolist()\n",
    "  freqCnt = []\n",
    "  for ii in range(K):\n",
    "    freqCnt.append(classes.count(classes[ii]))\n",
    "  indMax = np.argmax(freqCnt)\n",
    "  predClass =  classes[indMax]\n",
    "  print (\"This sample belongs to class: \" + str(predClass))\n",
    "  return predClass\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 82,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Downloading mp3 preview and descriptors for sound with id: 314930\n",
      "Downloading mp3 preview and descriptors for sound with id: 369912\n",
      "Downloading mp3 preview and descriptors for sound with id: 375372\n"
     ]
    }
   ],
   "source": [
    "# 4.1 download one sound \n",
    "### your code here\n",
    "key = 'WUxcKwn7VSCRcMRH6yH4WLV7h4dfZYfiBwoK2vyq'\n",
    "\n",
    "download_sounds_freesound(queryText='piano', API_Key=key, outputDir='../workspace', topNResults=1, duration=(0,4), tag='single-note')\n",
    "\n",
    "download_sounds_freesound(queryText='trumpet', API_Key=key, outputDir='../workspace', topNResults=1, duration=(0,2), tag='single-note')\n",
    "\n",
    "download_sounds_freesound(queryText='snare', API_Key=key, outputDir='../workspace', topNResults=1, duration=(0,8), tag='single-note')\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 100,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Piano sample\n",
      "This sample belongs to class: cello\n",
      "This sample belongs to class: guitar\n",
      "\n",
      "\n",
      "Snare sample\n",
      "This sample belongs to class: guitar\n",
      "This sample belongs to class: guitar\n",
      "\n",
      "\n",
      "This sample belongs to class: trumpet\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "'\\nFor the classification the descriptors that obtained the best accuracy are chosen.\\n\\nPIANO SAMPLE CLASSIFICATION: the best classifiers have been used to try to find the most similar instrument\\nto the piano sample (which is actually a synthesizer sound).\\n\\n1st classification: It is curious that for the first classification, with the 9 nearest neightboors are taken\\nand the best classifiers with a 93.33% of accuracy the piano sample is classified as a cello.\\n\\n2nd classification: with 2 descriptors: \"Spectral centroid\" and \"Attack\" taking also the 9 nearest negihtboors\\nthe sample is classified as guitar. This make sense because the accuracy of the classification with this two \\ndescriptors is of 65% and the guitar is a very noisy class because all the effect that most of the samples have.\\nBecause this class has a high entropy it is more likely a sample to be classified as a guitar.\\n\\n#-----------------------------------------------------------------------------------------------------------#\\n\\nSNARE SAMPLE CLASSIFICATION:the best classifiers have been used to try to find the most similar instrument\\nto the snare sample.\\n\\n1st classification: descriptor with 65% of accuracy are applied and medium value of k and the sound is classified\\nguitar because of the noisy samples (as it is mentioned aboved)\\n\\n2nd classification: descriptors with 93.33% of accuracy have been applied and a medium value of k (7) which should\\nbe one of the best cases to classify a sound and the snare sample is classified as guitar. This can be because of\\nthe descriptors selected defined guitar and snare in a similar way, the both have: low attack, similar\\ninharmonicity,...\\n\\n#-----------------------------------------------------------------------------------------------------------#\\n\\nTRUMPET SAMPLE CLASSIFICATION: a different sound of trumpet is used to see hoy well the classifier works. The \\ndescriptors applied in part 1 are used because they were able to concentrate trumpet samples satisfactorily and \\na high k (13) is applied to ensure the classification task. As it was supposed to happen, the sound is classified \\nas trumpet\\n\\n'"
      ]
     },
     "execution_count": 100,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# 4.2 classify the donwloaded sound\n",
    "### your code here\n",
    "\n",
    "# Piano sample\n",
    "print(\"Piano sample\")\n",
    "classify_sound_kNN('../workspace/piano/314930/314930_2050105-lq.json', '../workspace/testDownload', 9, [0,1,3,7])\n",
    "classify_sound_kNN('../workspace/piano/314930/314930_2050105-lq.json', '../workspace/testDownload', 9, [0,3])\n",
    "print(\"\\n\")\n",
    "\n",
    "#Snare sample\n",
    "print(\"Snare sample\")\n",
    "classify_sound_kNN('../workspace/snare/375372/375372_2475994-lq.json', '../workspace/testDownload', 7, [0,3])\n",
    "classify_sound_kNN('../workspace/snare/375372/375372_2475994-lq.json', '../workspace/testDownload', 5, [0,1,3,7])\n",
    "print(\"\\n\")\n",
    "\n",
    "#Trumpet sample different from the original samples\n",
    "classify_sound_kNN('../workspace/trumpet/369912/369912_6627281-lq.json', '../workspace/testDownload', 13, [0,3])\n",
    "\n",
    "\n",
    "\n",
    "### explain the classification\n",
    "\"\"\"\n",
    "For the classification the descriptors that obtained the best accuracy are chosen.\n",
    "\n",
    "PIANO SAMPLE CLASSIFICATION: the best classifiers have been used to try to find the most similar instrument\n",
    "to the piano sample (which is actually a synthesizer sound).\n",
    "\n",
    "1st classification: It is curious that for the first classification, with the 9 nearest neightboors are taken\n",
    "and the best classifiers with a 93.33% of accuracy the piano sample is classified as a cello.\n",
    "\n",
    "2nd classification: with 2 descriptors: \"Spectral centroid\" and \"Attack\" taking also the 9 nearest negihtboors\n",
    "the sample is classified as guitar. This make sense because the accuracy of the classification with this two \n",
    "descriptors is of 65% and the guitar is a very noisy class because all the effect that most of the samples have.\n",
    "Because this class has a high entropy it is more likely a sample to be classified as a guitar.\n",
    "\n",
    "#-----------------------------------------------------------------------------------------------------------#\n",
    "\n",
    "SNARE SAMPLE CLASSIFICATION:the best classifiers have been used to try to find the most similar instrument\n",
    "to the snare sample.\n",
    "\n",
    "1st classification: descriptor with 65% of accuracy are applied and medium value of k and the sound is classified\n",
    "guitar because of the noisy samples (as it is mentioned aboved)\n",
    "\n",
    "2nd classification: descriptors with 93.33% of accuracy have been applied and a medium value of k (7) which should\n",
    "be one of the best cases to classify a sound and the snare sample is classified as guitar. This can be because of\n",
    "the descriptors selected defined guitar and snare in a similar way, the both have: low attack, similar\n",
    "inharmonicity,...\n",
    "\n",
    "#-----------------------------------------------------------------------------------------------------------#\n",
    "\n",
    "TRUMPET SAMPLE CLASSIFICATION: a different sound of trumpet is used to see hoy well the classifier works. The \n",
    "descriptors applied in part 1 are used because they were able to concentrate trumpet samples satisfactorily and \n",
    "a high k (13) is applied to ensure the classification task. As it was supposed to happen, the sound is classified \n",
    "as trumpet\n",
    "\n",
    "\"\"\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.6.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}