#!/usr/bin/env python
# coding: utf-8

# # Bulk data access
# 
# This tutorial explains how to retrieve full tables from the database into [pandas DataFrames](http://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html).
# 
# ## Available tables in ``mendeleev``
# 
# - [elements](#elements): The main table with element properties
# - [groups](#groups): Metadata about periodic table groups
# - [ionicradii](#ionicradii): Ionic radii data
# - [ionizationenergies](#ionizationenergies): Ionization energies
# - [isotopes](#isotopes): Isotopes and their properties
# - [isotopedecaymodes](#isotopedecaymodes): Data on isotope decay modes
# - [oxidationstates](#oxidationstates): Oxidation states for elements
# - [phasetransitions](#phasetransitions): Phase transition data for elements
# - [propertymetadata](#propertymetadata): Metadata about properties from all tables
# - [scattering_factors](#scattering_factors): Atomic scattering factors
# - [screeningconstants](#screeningconstants): Nuclear screening constants
# - [series](#series): Metadata about periodic table series
# 
# All data is stored in a sqlite database that is shipped together with the package. You can interact directly with the database if you need more flexibility but for convenience ``mendeleev`` provides a few functions in the `fetch` module to
# retrieve data.
# 
# ## Fetching computed properties in bulk
# 
# - [Electronegativities](#Electronegativities) A collection of [electronegativity](https://mendeleev.readthedocs.io/en/stable/electronegativity.html) scales computed based on other properties.

# To fetch whole tables you can use `fetch_table`. The function can be imported from `mendeleev.fetch`

# In[ ]:


from mendeleev.fetch import fetch_table


# To retrieve a table call the ``fetch_table`` with the table name as argument. Here we'll get probably the most important table ``elements`` with basis data on each element

# ## elements

# In[ ]:


ptable = fetch_table("elements")


# Now we can use [pandas'](http://pandas.pydata.org) capabilities to work with the data. 

# In[ ]:


ptable.info()


# For clarity let's take only a subset of columns 

# In[ ]:


cols = [
    "atomic_number",
    "symbol",
    "atomic_radius",
    "en_pauling",
    "block",
    "vdw_radius_mm3",
]


# In[ ]:


ptable[cols].head()


# It is quite easy now to get descriptive statistics on the data.

# In[ ]:


ptable[cols].describe()


# ## groups
# 
# Periodic table group metadata.

# In[ ]:


groups = fetch_table("groups")
groups


# ## ionicradii
# 
# The function to fetch ionic radii is called `fetch_ionic_radii` and can either fetch ionic or crystal radii depending on the `radius` argument.

# In[ ]:


from mendeleev.fetch import fetch_ionic_radii


# In[ ]:


irs = fetch_ionic_radii(radius="ionic_radius")
irs.head(10)


# ## ionizationenergies
# 
# To fetch ionization energies use `fetch_ionization_energies` that takes a `degree` (default is `degree=1`) argument that can either be a single integer or a list if integers to fetch multiple ionization energies.

# In[ ]:


from mendeleev.fetch import fetch_ionization_energies


# In[ ]:


ies = fetch_ionization_energies(degree=2)
ies.head(10)


# To fetch multiple ionization degress at once simply pass a list of degrees:

# In[ ]:


ies_multiple = fetch_ionization_energies(degree=[1, 3, 5])
ies_multiple.head(10)


# ## isotopes
# 
# Let try and retrieve another table, namely ``isotopes``

# In[ ]:


isotopes = fetch_table("isotopes", index_col="id")


# In[ ]:


isotopes.info()


# Here's a few first records from that dataframe

# In[ ]:


isotopes.head(10)


# ### Merge the elements table with the isotopes
# 
# We can now perform SQL-like merge operation on two ``DataFrame``s and produce an [outer](http://pandas.pydata.org/pandas-docs/stable/merging.html#database-style-dataframe-joining-merging) join 

# In[ ]:


import pandas as pd


# In[ ]:


merged = pd.merge(ptable[cols], isotopes, how="outer", on="atomic_number")


# now we have the following columns in the ``merged`` ``DataFrame``

# In[ ]:


merged.info()


# In[ ]:


merged.head()


# To display all the isotopes of Silicon

# In[ ]:


merged[merged["symbol"] == "Si"]


# ## isotopedecaymodes
# 
# Different modes are explained in [the documentation](https://mendeleev.readthedocs.io/en/stable/data.html#isotope-decay-modes)

# In[ ]:


idm = fetch_table("isotopedecaymodes")
idm


# ## oxidationstates

# In[ ]:


ox = fetch_table("oxidationstates")
ox


# ## phasetransitions
# 
# For most elements a single row is present with phase transition properies, however for elements with multiple allotropes (i.e. Carbon, Phosphorus, Selenium, Sulfur, Tin) values are provided for each allotrope.

# In[ ]:


pt = fetch_table("phasetransitions")
pt.sort_values(by="atomic_number").head(15)


# ## propertymetadata
# 
# This table holds a lot of the metadata that is used to render the data documentation page. Probably the most useful piece of information here is the unit assocaited with a given property. The units are compatible with the [pint](https://pint.readthedocs.io/en/stable/) package so properties might be used direclty with units.

# In[ ]:


metadata = fetch_table("propertymetadata")
metadata.head(10)


# ## scattering_factors

# In[ ]:


scattering_factors = fetch_table("scattering_factors")
scattering_factors.head(10)


# ## screeningconstants

# In[ ]:


screening = fetch_table("screeningconstants")
screening.head(10)


# ## series
# 
# Metadata about periodic table series.

# In[ ]:


series = fetch_table("series")
series


# ## Electronegativities
# 
# To fetch all data from electronegatuivity scales use `fetch_electronegativities`. This can take a few seconds since most of the values need to be computed.

# In[ ]:


from mendeleev.fetch import fetch_electronegativities


# In[ ]:


ens = fetch_electronegativities()
ens.head(10)


# ## Version information

# In[ ]:


import mendeleev

print(f"{mendeleev.__version__=}")