matminer_examples/BandGapComparisonCitrinationVsMP.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Banner logo](https://raw.githubusercontent.com/CitrineInformatics/community-tools/master/templates/fig/citrine_banner_2.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Compare Band Gaps From Citrination and Materials Project\n",
    "\n",
    "*Authors: Carena Church, Enze Chen*\n",
    "\n",
    "This notebook demonstrates retrieval of data through the Citrination API client using [matminer's](https://github.com/hackingmaterials/matminer) tools to retrieve experimental band gaps from [Citrine's databases](https://citrination.com/), output it in the form of a [pandas DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html#pandas.DataFrame), and then compare them with computed band gaps from the [Materials Project](https://www.materialsproject.org/) (MP).\n",
    "\n",
    "**WARNING**: Explicit structural information was not checked for or extracted from the experimental datasets this notebook uses, and thus, the below example makes a comparison of the experimental band gap from Citrine with the density functional theory (DFT) computed band gap of the most stable structure from MP. Therefore, it is assumed here that the band gaps obtained from Citrine and MP correspond to the same structure for a particular composition, which may not always be true. In cases where this is not true, the comparison is faulty."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Prerequisites\n",
    "\n",
    "* Have the [`matminer`](https://pypi.org/project/matminer/) package installed (`pip` installable using `pip install matminer`)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Python package imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Standard packages\n",
    "import os\n",
    "\n",
    "# Third-party packages\n",
    "import numpy as np\n",
    "import pandas as pd\n",
    "import matplotlib.pyplot as plt\n",
    "%matplotlib inline\n",
    "\n",
    "# Set pandas view options\n",
    "pd.set_option('display.width', 1000)\n",
    "pd.set_option('display.max_columns', None)\n",
    "pd.set_option('display.max_rows', None)\n",
    "\n",
    "from matminer.data_retrieval.retrieve_Citrine import CitrineDataRetrieval\n",
    "from pymatgen import MPRester\n",
    "\n",
    "# Filter warnings messages from the notebook\n",
    "import warnings\n",
    "warnings.filterwarnings('ignore')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 1: Retrieve data\n",
    "\n",
    "We will first import matminer's CitrineDataRetrieval tool and create an adapter to the Citrination API."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "c = CitrineDataRetrieval(os.environ.get('CITRINATION_API_KEY'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then we will retrieve the first 100 experimental band gaps from the Citrination database and show only selected columns in a pandas DataFrame."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "df = c.get_dataframe(properties=['Band gap'], common_fields=['chemicalFormula'],\n",
    "                     criteria={'data_type':'EXPERIMENTAL', 'max_results':100},\n",
    "                     print_properties_options=False)\n",
    "\n",
    "# Filter out rows with null values of band gap\n",
    "df = df.dropna()\n",
    "\n",
    "# Rename column\n",
    "df = df.rename(columns={'Band gap': 'Experimental band gap'})\n",
    "\n",
    "# Show first few rows of the DataFrame\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 2: Obtain MP band gaps\n",
    "\n",
    "Now we will create a function that for each composition, gets a list of structures from MP. We will loop through this list to get the computed band gap of the structure with the lowest energy. \n",
    "\n",
    "### `get_MP_bandgaps`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "def get_MP_bandgaps(formula):\n",
    "    try:\n",
    "        struct_lst = MPRester().get_data(formula)     # API key set as env variable \"MAPI_KEY\"\n",
    "    except:\n",
    "        return pd.Series({'Computed band gap': None})\n",
    "    if len(struct_lst) > 0:\n",
    "        struct_lst = sorted(struct_lst, key=lambda e: e['energy_per_atom'])\n",
    "        most_stable_entry = struct_lst[0]\n",
    "        return pd.Series({'Computed band gap': most_stable_entry['band_gap']})\n",
    "    else:\n",
    "        return pd.Series({'Computed band gap': None})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then, we apply the above function to each composition in the \"chemicalFormula\" column of the previous DataFrame to get a column of computed band gaps from MP, and concatenate it with the original DataFrame."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mp_df = df.apply(lambda x: get_MP_bandgaps(x['chemicalFormula']), axis=1)\n",
    "df = pd.concat([df, mp_df], axis=1)\n",
    "df.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 3: Plot the comparison\n",
    "\n",
    "Now we will plot experimental vs. computed band gaps."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots()\n",
    "plt.scatter(df['Experimental band gap'].astype(float), df['Computed band gap'].astype(float))\n",
    "plt.xlabel('Experimental band gap')\n",
    "plt.ylabel('Computed band gap')\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 4: Compute the error"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "rmse = ((df['Experimental band gap'].astype(float) - df['Computed band gap'].astype(float)) ** 2).mean() ** .5\n",
    "print('The RMSE is {0:.4f} eV.'.format(rmse))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Conclusion\n",
    "\n",
    "This notebook demonstrates the extraction of material property data, in this case band gaps, from the APIs of Citrination (through matminer) and Materials Project in a Pandas dataframe, and plotting this data using matplotlib. From this comparison, it can be observed that there are many materials for which the experimental band gaps are higher than the computed band gaps. This is expected due to the well-known problem of underestimation of [band gaps by DFT](https://onlinelibrary.wiley.com/doi/pdf/10.1002/qua.560280846) (using LDA and GGA methods that involve self-interaction errors), and hence verifies our analysis to some extent. "
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Raw Cell Format",
  "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.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}