notebooks/explanation_of_the_data_format.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Explanation of the data format"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The raw data underlying the figures is stored in the file `data/eigenmode_info_data_frame.csv`. In this notebook we explain what this file contains and the data format.\n",
    "\n",
    "The data is stored in CSV (= comma-separated values) format. In principle, it is human-readable. The first few lines look as follows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "has_particle,x,y,d,d_particle,Ms_particle,Hx,Hy,Hz,N,freq,freq_diff\r\n",
      "False,,,,,,0,0,80000.0,1,4.44366221658866,\r\n",
      "False,,,,,,0,0,80000.0,2,5.916577999212971,\r\n",
      "False,,,,,,0,0,80000.0,3,7.917764571095144,\r\n",
      "False,,,,,,0,0,80000.0,4,8.415238223354994,\r\n"
     ]
    }
   ],
   "source": [
    "!head -n 5 ../data/eigenmode_info_data_frame.csv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, it is much more convenient to read and explore the data using [pandas](http://pandas.pydata.org/). To do this, we first load the CSV file into a `pandas.DataFrame`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "df = pd.read_csv('../data/eigenmode_info_data_frame.csv')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using `pandas` we can display the data in a nice table format. The first few entries of the data frame (which correspond to the lines listed above) look as follows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>has_particle</th>\n",
       "      <th>x</th>\n",
       "      <th>y</th>\n",
       "      <th>d</th>\n",
       "      <th>d_particle</th>\n",
       "      <th>Ms_particle</th>\n",
       "      <th>Hx</th>\n",
       "      <th>Hy</th>\n",
       "      <th>Hz</th>\n",
       "      <th>N</th>\n",
       "      <th>freq</th>\n",
       "      <th>freq_diff</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>False</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>80000.0</td>\n",
       "      <td>1</td>\n",
       "      <td>4.443662</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>False</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>80000.0</td>\n",
       "      <td>2</td>\n",
       "      <td>5.916578</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>False</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>80000.0</td>\n",
       "      <td>3</td>\n",
       "      <td>7.917765</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>False</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>NaN</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>80000.0</td>\n",
       "      <td>4</td>\n",
       "      <td>8.415238</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "  has_particle   x   y   d  d_particle  Ms_particle  Hx  Hy       Hz  N  \\\n",
       "0        False NaN NaN NaN         NaN          NaN   0   0  80000.0  1   \n",
       "1        False NaN NaN NaN         NaN          NaN   0   0  80000.0  2   \n",
       "2        False NaN NaN NaN         NaN          NaN   0   0  80000.0  3   \n",
       "3        False NaN NaN NaN         NaN          NaN   0   0  80000.0  4   \n",
       "\n",
       "       freq  freq_diff  \n",
       "0  4.443662        NaN  \n",
       "1  5.916578        NaN  \n",
       "2  7.917765        NaN  \n",
       "3  8.415238        NaN  "
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df.head(4)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Each row contains the simulation parameters and computed eigenfrequency for one of the five eigenmodes computed in a particular simulation run. The rows shown above all correspond to a simulation with no particle present, hence the missing values (marked by `NaN` = \"not a number\") for some of the parameters. For illustration, we also show a few rows corresponding to simulations which included a particle."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>has_particle</th>\n",
       "      <th>x</th>\n",
       "      <th>y</th>\n",
       "      <th>d</th>\n",
       "      <th>d_particle</th>\n",
       "      <th>Ms_particle</th>\n",
       "      <th>Hx</th>\n",
       "      <th>Hy</th>\n",
       "      <th>Hz</th>\n",
       "      <th>N</th>\n",
       "      <th>freq</th>\n",
       "      <th>freq_diff</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>103</th>\n",
       "      <td>True</td>\n",
       "      <td>60.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>5.0</td>\n",
       "      <td>20.0</td>\n",
       "      <td>1000000.0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>80000.0</td>\n",
       "      <td>4</td>\n",
       "      <td>8.388506</td>\n",
       "      <td>-0.026732</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>104</th>\n",
       "      <td>True</td>\n",
       "      <td>60.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>5.0</td>\n",
       "      <td>20.0</td>\n",
       "      <td>1000000.0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>80000.0</td>\n",
       "      <td>5</td>\n",
       "      <td>10.694579</td>\n",
       "      <td>0.091395</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>105</th>\n",
       "      <td>True</td>\n",
       "      <td>70.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>5.0</td>\n",
       "      <td>20.0</td>\n",
       "      <td>1000000.0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>80000.0</td>\n",
       "      <td>1</td>\n",
       "      <td>4.447192</td>\n",
       "      <td>0.003530</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>106</th>\n",
       "      <td>True</td>\n",
       "      <td>70.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>5.0</td>\n",
       "      <td>20.0</td>\n",
       "      <td>1000000.0</td>\n",
       "      <td>0</td>\n",
       "      <td>0</td>\n",
       "      <td>80000.0</td>\n",
       "      <td>2</td>\n",
       "      <td>6.021694</td>\n",
       "      <td>0.105116</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "    has_particle     x    y    d  d_particle  Ms_particle  Hx  Hy       Hz  N  \\\n",
       "103         True  60.0  0.0  5.0        20.0    1000000.0   0   0  80000.0  4   \n",
       "104         True  60.0  0.0  5.0        20.0    1000000.0   0   0  80000.0  5   \n",
       "105         True  70.0  0.0  5.0        20.0    1000000.0   0   0  80000.0  1   \n",
       "106         True  70.0  0.0  5.0        20.0    1000000.0   0   0  80000.0  2   \n",
       "\n",
       "          freq  freq_diff  \n",
       "103   8.388506  -0.026732  \n",
       "104  10.694579   0.091395  \n",
       "105   4.447192   0.003530  \n",
       "106   6.021694   0.105116  "
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df.iloc[103:107]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In each simulation run we computed the frequencies of the first five eigenmodes (N=1,...,5) of the nanodisc as illustrated in the following figures (cf. Figs. 3 and 5 in the paper). Each row in the data frame corresponds to one of these eigenmodes, either for the bare nanodisc (as illustrated on the left), or for a nanodisc with particle (as illustrated for selected modes on the right).\n",
    "<table>\n",
    "<tr>\n",
    "<td><img src=\"../images/eigenmodes_bare_disc.png\" width=\"300px\"></td>\n",
    "<td><img src=\"../images/eigenmodes_disc_with_particle.png\" width=\"300px\"></td>\n",
    "</tr>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The meaning of the columns in the data frame is as follows:\n",
    "\n",
    "- `has_particle`: Whether a particle was present in this particular simulation. If `False`, the simulation computed eigenmodes of the bare disc.\n",
    "\n",
    "- `x`, `y`: Position of the centre of the particle relative to the centre of the nanodisc (in nanometres). The value (x,y)=(0,0) means that the particle is located above the centre of the disc.\n",
    "\n",
    "- `d`: Separation (in nanometres) of the bottom surface of the particle from the top surface of the disc. See Fig. 1(c) in the paper for illustration.\n",
    "\n",
    "- `d_particle`: Diameter of the particle (in nanometres).\n",
    "\n",
    "- `Ms_particle`: Saturation magnetisation of the particle (in A/m).\n",
    "\n",
    "- `Hx`, `Hy`, `Hz`: Strength of the external field (in A/m).\n",
    "\n",
    "- `N`: Which eigenmode of the nanodisc this row corresponds to. Valid values are N=1,...,5, corresponding to the first five eigenmodes of the disc. See figures above for illustration.\n",
    "\n",
    "- `freq`: Frequency of the eigenmode (in GHz).\n",
    "\n",
    "- `freq_diff`: Frequency shift $\\Delta f$ (in GHz) of this eigenmode relative to the same mode in the bare disc (i.e., with no particle present)."
   ]
  }
 ],
 "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.5.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}