{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook demonstrates use of the code 'retrieve_Citrine.py' in retrieving data from various datasets collected by Citrine Informatics at http://citrination.com/, and output it in the form of a Pandas dataframe. In this example, we query the Citrine API to retrieve all the data on Al2FeO4 contributed by 'Stephan Lany' from NREL to Citrine. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from matminer.data_retrieval.retrieve_Citrine import CitrineDataRetrieval"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "api_key = None     # Set your Citrine API key here. If set as an environment variable 'CITRINE_KEY', set it to 'None'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create an adapter to the Citrine database"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "c = CitrineDataRetrieval(api_key)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Retrive data from the Citrine database that is contributed by \"NREL\" for all samples with a chemical formula of \"Al2FeO4\". "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": []
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>data_set_id</th>\n",
       "      <th>material.chemicalFormula</th>\n",
       "      <th>material.condition</th>\n",
       "      <th>material.id</th>\n",
       "      <th>reference</th>\n",
       "      <th>Enthalpy wrt decomposition ($\\Delta$H$_{Decomp}$)</th>\n",
       "      <th>Enthalpy wrt ground state ($\\Delta$H$_{Gnd}$)</th>\n",
       "      <th>Final enthalpy ($\\Delta$H$_f$)</th>\n",
       "      <th>Total energy</th>\n",
       "      <th>measurement.condition</th>\n",
       "      <th>measurement.reference</th>\n",
       "      <th>property.units</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>sample</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>149854</td>\n",
       "      <td>Al2FeO4</td>\n",
       "      <td>[{u'scalar': [{u'value': u'True'}], u'name': u...</td>\n",
       "      <td>[{u'name': u'MatDB ID', u'value': u'131812'}, ...</td>\n",
       "      <td>[{u'url': u'http://materials.nrel.gov/queryStd...</td>\n",
       "      <td>-0.0332449</td>\n",
       "      <td>0.00451057</td>\n",
       "      <td>-2.92243</td>\n",
       "      <td>-7.38416</td>\n",
       "      <td>[{u'scalar': [{u'value': u'fere'}], u'name': u...</td>\n",
       "      <td>[{u'url': u'http://dx.doi.org/10.1103/PhysRevB...</td>\n",
       "      <td>{u'Final enthalpy ($\\Delta$H$_f$)': u'eV/atom'...</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>149854</td>\n",
       "      <td>Al2FeO4</td>\n",
       "      <td>[{u'scalar': [{u'value': u'True'}], u'name': u...</td>\n",
       "      <td>[{u'name': u'MatDB ID', u'value': u'131150'}, ...</td>\n",
       "      <td>[{u'url': u'http://materials.nrel.gov/queryStd...</td>\n",
       "      <td>-0.0377554</td>\n",
       "      <td>0</td>\n",
       "      <td>-2.92694</td>\n",
       "      <td>-7.38867</td>\n",
       "      <td>[{u'scalar': [{u'value': u'fere'}], u'name': u...</td>\n",
       "      <td>[{u'url': u'http://dx.doi.org/10.1103/PhysRevB...</td>\n",
       "      <td>NaN</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "        data_set_id material.chemicalFormula                                 material.condition                                        material.id                                          reference Enthalpy wrt decomposition ($\\Delta$H$_{Decomp}$) Enthalpy wrt ground state ($\\Delta$H$_{Gnd}$) Final enthalpy ($\\Delta$H$_f$) Total energy                              measurement.condition                              measurement.reference                                     property.units\n",
       "sample                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    \n",
       "1            149854                  Al2FeO4  [{u'scalar': [{u'value': u'True'}], u'name': u...  [{u'name': u'MatDB ID', u'value': u'131812'}, ...  [{u'url': u'http://materials.nrel.gov/queryStd...                                        -0.0332449                                    0.00451057                       -2.92243     -7.38416  [{u'scalar': [{u'value': u'fere'}], u'name': u...  [{u'url': u'http://dx.doi.org/10.1103/PhysRevB...  {u'Final enthalpy ($\\Delta$H$_f$)': u'eV/atom'...\n",
       "2            149854                  Al2FeO4  [{u'scalar': [{u'value': u'True'}], u'name': u...  [{u'name': u'MatDB ID', u'value': u'131150'}, ...  [{u'url': u'http://materials.nrel.gov/queryStd...                                        -0.0377554                                             0                       -2.92694     -7.38867  [{u'scalar': [{u'value': u'fere'}], u'name': u...  [{u'url': u'http://dx.doi.org/10.1103/PhysRevB...                                                NaN"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df = c.get_dataframe(term='NREL', formula='Al2FeO4')\n",
    "df"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the dataframe above, the search query results in 2 samples/hits from the Citrine API, each with a different space group (70 and 141) and 4 properties as listed in the columns of the dataframe."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note: here we use 'term='NREL'' instead of 'contributor='NREL'' (as in other examples) in our search query as the database on Citrine's website is listed as being contributed by 'Stephan Lany' and not 'NREL' (which is listed in the 'reference' field of the database, as can be seen in the above dataframe). This is confirmed in the search query below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": []
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>property.units</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>sample</th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>{}</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "       property.units\n",
       "sample               \n",
       "1                  {}"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "df = c.get_dataframe(contributor='NREL', formula='Al2FeO4')\n",
    "df"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Raw Cell Format",
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}
