From 3f97bae4dde2a1b2b69115a9d2357ab67b882348 Mon Sep 17 00:00:00 2001 From: Lukasz Mentel Date: Sun, 18 Aug 2024 23:40:50 +0200 Subject: [PATCH] [DOC] Update data documentation (#175) * add docs for ionic radii * add utilities for rendering doc tables * update docs for colors * update property docs * update format for code block * add isotope decay modes * add screening constant docs * more docs updates * update docstring * bumpt year * add notebook rendering docs --- docs/source/conf.py | 2 +- docs/source/data.rst | 119 ++++++++--- docs/source/data_access.rst | 12 +- docs/source/references.bib | 7 + mendeleev/elements.db | Bin 2581504 -> 2587648 bytes mendeleev/models.py | 4 +- mendeleev/utils.py | 74 +++++++ notebooks/render-docs-from-metadata.ipynb | 228 ++++++++++++++++++++++ 8 files changed, 407 insertions(+), 39 deletions(-) create mode 100644 notebooks/render-docs-from-metadata.ipynb diff --git a/docs/source/conf.py b/docs/source/conf.py index d96c0d87..c7127b87 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -117,7 +117,7 @@ # General information about the project. project = "mendeleev" -copyright = "2021, Lukasz Mentel" +copyright = "2024, Lukasz Mentel" # Link to GitHub repo for github_issues extension issues_github_path = "lmmentel/mendeleev" diff --git a/docs/source/data.rst b/docs/source/data.rst index f9a23b74..ffd10fbe 100644 --- a/docs/source/data.rst +++ b/docs/source/data.rst @@ -51,7 +51,7 @@ The following data are currently available: +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ | ``covalent_radius_pyykko`` | Single bond covalent radius by Pyykko et al. | pm | stored | :cite:`Pyykko2009` | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ -| ``cpk_color`` | Element color in CPK convention ([#f_color]_) | | stored | :cite:`wiki-cpk` | +| ``cpk_color`` | Element color in CPK convention as HEX codes. | | stored | :cite:`wiki-cpk` | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ | ``critical_pressure`` | Critical pressure | MPa | stored | :cite:`haynes2016crc` | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ @@ -121,9 +121,9 @@ The following data are currently available: +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ | ``inchi`` | International Chemical Identifier | | computed | :cite:`IUPAC-InChI` | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ -| ``ionenergy`` | See IonizationEnergy class documentation | | stored | | +| ``ionenergy`` | See IonizationEnergy class documentation | | stored | :cite:`ionization_energies` | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ -| ``ionic_radii`` | See IonicRadius class documentation | | stored | | +| ``ionic_radii`` | See IonicRadius class documentation | | stored | :cite:`Shannon1976,Lundberg2016` | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ | ``is_monoisotopic`` | Is the element monoisotopic | | stored | | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ @@ -131,7 +131,7 @@ The following data are currently available: +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ | ``isotopes`` | See Isotope class documentation | | stored | | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ -| ``jmol_color`` | Element color in Jmol convention ([#f_color]_) | | stored | :cite:`jmol-colors` | +| ``jmol_color`` | Element color in Jmol convention as HEX codes. | | stored | :cite:`jmol-colors` | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ | ``lattice_constant`` | Lattice constant | angstrom | stored | | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ @@ -149,7 +149,7 @@ The following data are currently available: +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ | ``molar_heat_capacity`` | Molar heat capacity @ 25 C, 1 bar | J/mol/K | stored | :cite:`haynes2014crc` | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ -| ``molcas_gv_color`` | Element color in MOCAS GV convention ([#f_color]_) | | stored | :cite:`molcas-colors` | +| ``molcas_gv_color`` | Element color in MOCAS GV convention as HEX codes. | | stored | :cite:`molcas-colors` | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ | ``name_origin`` | Origin of the name | | stored | | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ @@ -163,7 +163,7 @@ The following data are currently available: +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ | ``oxides`` | Possible oxides based on oxidation numbers | | computed | | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ -| ``oxistates`` | See OxidationState class documentation | | stored | | +| ``oxistates`` | See OxidationState class documentation | | stored | :cite:`enwiki:1102394064` | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ | ``period`` | Period in periodic table | | stored | | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ @@ -173,7 +173,7 @@ The following data are currently available: +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ | ``protons`` | Number of protons | | computed | | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ -| ``sconst`` | See ScreeningConstant class documentation | | stored | | +| ``sconst`` | See ScreeningConstant class documentation ([#f_sconst]_) | | stored | :cite:`Clementi1963,Clementi1967` | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ | ``series`` | Series in the periodic table | | stored | | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ @@ -214,7 +214,6 @@ The following data are currently available: | ``zeff`` | Effective nuclear charge | | computed | | +-----------------------------------------+----------------------------------------------------------------------+----------------+--------------+------------------------------------------------+ - Isotopes ======== @@ -258,25 +257,24 @@ Isotopes | ``spin`` | Nuclear spin quantum number | | stored | :cite:`Kondev2021` | +-----------------------------------+-------------------------------------------------+----------+--------------+----------------------+ - Isotope Decay Modes =================== -+-------------------------------+-------+---------------------------------------------------------------------------------+----------------------+-------------------------+ -| Name | Type | Comment | Unit | Data Source | -+===============================+=======+=================================================================================+======================+=========================+ -| isotope_id | int | ID of the isotope | | | -+-------------------------------+-------+---------------------------------------------------------------------------------+----------------------+-------------------------+ -| mode | str | ASCII symbol of the decay mode | | :cite:`Kondev2021` | -+-------------------------------+-------+---------------------------------------------------------------------------------+----------------------+-------------------------+ -| relation | str | Uncertainty of relative abundance | | :cite:`Kondev2021` | -+-------------------------------+-------+---------------------------------------------------------------------------------+----------------------+-------------------------+ -| intensity | float | Intensity of the decay mode | % | :cite:`Kondev2021` | -+-------------------------------+-------+---------------------------------------------------------------------------------+----------------------+-------------------------+ -| is_allowed_not_observed | bool | If `True` decay mode is energetically allowed, but not experimentally observed | | :cite:`Kondev2021` | -+-------------------------------+-------+---------------------------------------------------------------------------------+----------------------+-------------------------+ -| is_observed_intensity_unknown | bool | If `True` decay mode is observed, but its intensity is not experimentally known | | :cite:`Kondev2021` | -+-------------------------------+-------+---------------------------------------------------------------------------------+----------------------+-------------------------+ ++-----------------------------------+---------------------------------------------------------------------------------+------+--------------+--------------------+ +| Attribute name | Description | Unit | Value origin | Citation keys | ++===================================+=================================================================================+======+==============+====================+ +| ``intensity`` | Intensity of the decay mode | | stored | :cite:`Kondev2021` | ++-----------------------------------+---------------------------------------------------------------------------------+------+--------------+--------------------+ +| ``is_allowed_not_observed`` | If `True` decay mode is energetically allowed, but not experimentally observed | | stored | :cite:`Kondev2021` | ++-----------------------------------+---------------------------------------------------------------------------------+------+--------------+--------------------+ +| ``is_observed_intensity_unknown`` | If `True` decay mode is observed, but its intensity is not experimentally known | | stored | :cite:`Kondev2021` | ++-----------------------------------+---------------------------------------------------------------------------------+------+--------------+--------------------+ +| ``isotope_id`` | ID of the isotope, links to the `isotopes` table. | | stored | :cite:`Kondev2021` | ++-----------------------------------+---------------------------------------------------------------------------------+------+--------------+--------------------+ +| ``mode`` | ASCII symbol of the decay mode | | stored | :cite:`Kondev2021` | ++-----------------------------------+---------------------------------------------------------------------------------+------+--------------+--------------------+ +| ``relation`` | Uncertainty of relative abundance | | stored | :cite:`Kondev2021` | ++-----------------------------------+---------------------------------------------------------------------------------+------+--------------+--------------------+ The different modes in the table are stores as ASCII representations for compatibility. The table below provides explanations of the symbols. @@ -337,7 +335,6 @@ for compatibility. The table below provides explanations of the symbols. | 24Ne | 24Ne | heavy cluster emission | +---------+----------------------------+------------------------------------------------------------+ - Atomic Scattering Factors ========================= @@ -353,6 +350,72 @@ Atomic Scattering Factors | ``f2`` | Scattering factor f2 | | stored | :cite:`atomic_scattering_factors,henke1993xray` | +-------------------+----------------------------------------------+------+--------------+-------------------------------------------------+ +Ionization Energies +=================== + ++-------------------+---------------------------------------------------+------+--------------+-----------------------------+ +| Attribute name | Description | Unit | Value origin | Citation keys | ++===================+===================================================+======+==============+=============================+ +| ``atomic_number`` | Atomic number | | stored | :cite:`ionization_energies` | ++-------------------+---------------------------------------------------+------+--------------+-----------------------------+ +| ``degree`` | Degree of ionization with respect to neutral atom | | stored | :cite:`ionization_energies` | ++-------------------+---------------------------------------------------+------+--------------+-----------------------------+ +| ``energy`` | Ionization energy | eV | stored | :cite:`ionization_energies` | ++-------------------+---------------------------------------------------+------+--------------+-----------------------------+ + +Ionic Radii +=========== + ++--------------------+-----------------------------------------+------+--------------+----------------------------------+ +| Attribute name | Description | Unit | Value origin | Citation keys | ++====================+=========================================+======+==============+==================================+ +| ``atomic_number`` | Atomic number | | stored | :cite:`Shannon1976` | ++--------------------+-----------------------------------------+------+--------------+----------------------------------+ +| ``charge`` | Charge of the ion | | stored | :cite:`Shannon1976,Lundberg2016` | ++--------------------+-----------------------------------------+------+--------------+----------------------------------+ +| ``coordination`` | Type of coordination | | stored | :cite:`Shannon1976,Lundberg2016` | ++--------------------+-----------------------------------------+------+--------------+----------------------------------+ +| ``crystal_radius`` | Crystal radius | pm | stored | :cite:`Shannon1976,Lundberg2016` | ++--------------------+-----------------------------------------+------+--------------+----------------------------------+ +| ``econf`` | Electronic configuration of the ion | | stored | :cite:`Shannon1976,Lundberg2016` | ++--------------------+-----------------------------------------+------+--------------+----------------------------------+ +| ``ionic_radius`` | Ionic radius | pm | stored | :cite:`Shannon1976,Lundberg2016` | ++--------------------+-----------------------------------------+------+--------------+----------------------------------+ +| ``most_reliable`` | Most reliable value (see reference) | | stored | :cite:`Shannon1976` | ++--------------------+-----------------------------------------+------+--------------+----------------------------------+ +| ``origin`` | Source of the data | | stored | :cite:`Shannon1976` | ++--------------------+-----------------------------------------+------+--------------+----------------------------------+ +| ``spin`` | Spin state: HS: high spin, LS: low spin | | stored | :cite:`Shannon1976,Lundberg2016` | ++--------------------+-----------------------------------------+------+--------------+----------------------------------+ + +Oxidation States +================ + ++---------------------+--------------------------------------------------------------------------+------+--------------+---------------------------+ +| Attribute name | Description | Unit | Value origin | Citation keys | ++=====================+==========================================================================+======+==============+===========================+ +| ``atomic_number`` | Atomic number | | stored | :cite:`enwiki:1102394064` | ++---------------------+--------------------------------------------------------------------------+------+--------------+---------------------------+ +| ``category`` | Either `main` or `extended` flag to indicate the type of oxidation state | | stored | :cite:`enwiki:1102394064` | ++---------------------+--------------------------------------------------------------------------+------+--------------+---------------------------+ +| ``oxidation_state`` | Oxidation state | | stored | :cite:`enwiki:1102394064` | ++---------------------+--------------------------------------------------------------------------+------+--------------+---------------------------+ + +Screening Constants +=================== + ++-------------------+--------------------------------+------+--------------+-----------------------------------+ +| Attribute name | Description | Unit | Value origin | Citation keys | ++===================+================================+======+==============+===================================+ +| ``atomic_number`` | Atomic number | | stored | :cite:`Clementi1963,Clementi1967` | ++-------------------+--------------------------------+------+--------------+-----------------------------------+ +| ``n`` | Principal quantum number | | stored | :cite:`Clementi1963,Clementi1967` | ++-------------------+--------------------------------+------+--------------+-----------------------------------+ +| ``s`` | Subshell label, (s, p, d, ...) | | stored | :cite:`Clementi1963,Clementi1967` | ++-------------------+--------------------------------+------+--------------+-----------------------------------+ +| ``screening`` | Screening constant | | stored | :cite:`Clementi1963,Clementi1967` | ++-------------------+--------------------------------+------+--------------+-----------------------------------+ + .. rubric:: Data Footnotes .. [#f_atomic_weight] **Atomic Weights** @@ -372,10 +435,6 @@ Atomic Scattering Factors :cite:`Cordero2008` the values for 3 different valences for C, also the low and high spin values for Mn, Fe Co, were respectively averaged. -.. [#f_color] **colors** - - HEX codes for colors. - .. [#f_electron_affinity] **Electron affinity** Electron affinities were taken from :cite:`haynes2014crc` for the elements @@ -431,7 +490,7 @@ Atomic Scattering Factors .. [#f9] **Ionic radii for Actinoid (III) ions** Ionic radii values for 3\ :sup:`+` Actinoids were with coordination number 9 were taken - from :cite:`Lundberg2016`. In addition ``crystal_radius`` values were computed + from :cite:`Lundberg2016`. In addition, ``crystal_radius`` values were computed by adding 14 pm to the ``ionic_radius`` values according to :cite:`Shannon1976`. .. [#f_density] **Densities** diff --git a/docs/source/data_access.rst b/docs/source/data_access.rst index c0115074..2bd35987 100644 --- a/docs/source/data_access.rst +++ b/docs/source/data_access.rst @@ -83,9 +83,9 @@ The command will export all the tables from the database to a set of files in th In order to use this functionality you'll need to clone the mendeleev repository and install the package in the development mode. Here's how you can do it: -```bash -gh clone lmmentel/mendeleev -cd mendeleev -poetry install -poetry run inv export -``` \ No newline at end of file +.. code-block:: bash + + gh clone lmmentel/mendeleev + cd mendeleev + poetry install + poetry run inv export diff --git a/docs/source/references.bib b/docs/source/references.bib index 8a729aab..7a25f78c 100644 --- a/docs/source/references.bib +++ b/docs/source/references.bib @@ -874,3 +874,10 @@ @article{henke1993xray month = {July}, publisher = {Elsevier} } +@misc{ionization_energies, + author = {A.~Kramida and {Yu.~Ralchenko} and J.~Reader and {and NIST ASD Team}}, + title = {NIST Atomic Spectra Database Ionization Energies Data}, + howpublished = {{NIST Atomic Spectra Database (ver. 5.11), [Online]. Available: {\tt{https://physics.nist.gov/asd}} [2024, August 17]. National Institute of Standards and Technology, Gaithersburg, MD.}}, + year = {2023}, + note = {Accessed: 2015-04-13} +} \ No newline at end of file diff --git a/mendeleev/elements.db b/mendeleev/elements.db index f52151aaaa8249fe30d316f7fe1a80522ece8d94..1fe9c109f5e4625be2715b6f830efe507046be43 100644 GIT binary patch delta 4656 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 diff --git a/mendeleev/models.py b/mendeleev/models.py index 2e8651d5..471c4495 100644 --- a/mendeleev/models.py +++ b/mendeleev/models.py @@ -1191,8 +1191,8 @@ class ScatteringFactor(Base): Args: atomic_number (int): Atomic number energy (float): Energy in eV - f1 (float): Energy in eV - f1 (float): Energy in eV + f1 (float): Scattering factor f1 + f1 (float): Scattering factor f2 """ __tablename__ = "scattering_factors" diff --git a/mendeleev/utils.py b/mendeleev/utils.py index f768f8e3..7971d7cc 100644 --- a/mendeleev/utils.py +++ b/mendeleev/utils.py @@ -1,6 +1,8 @@ from typing import Union, Tuple import math +import pandas as pd + def coeffs(a: int, b: int = 2) -> Tuple[int, int]: """ @@ -43,3 +45,75 @@ def n_effective(n: int, source: str = "slater") -> Union[float, None]: raise ValueError( f"source '{source}' not found, available sources are: {', '.join(numbers.keys())}" ) + + +def render_rst_table(df: pd.DataFrame) -> str: + """ + Converts a pandas DataFrame to a reStructuredText table. + + Args: + df (pd.DataFrame): The DataFrame to convert. + + Returns: + str: The DataFrame as a reStructuredText table. + """ + # Get the column headers + headers = df.columns.tolist() + + # Get the lengths of each column for formatting + col_lengths = [ + max(len(str(val)) for val in df[col].tolist() + [col]) for col in headers + ] + + # Create the horizontal line for the table + hline = "+" + "+".join(["-" * (length + 2) for length in col_lengths]) + "+" + header_hline = "+" + "+".join(["=" * (length + 2) for length in col_lengths]) + "+" + + # Format the header row + header_row = ( + "|" + + "|".join( + [ + f" {headers[i]}{' ' * (col_lengths[i] - len(headers[i]))} " + for i in range(len(headers)) + ] + ) + + "|" + ) + + data_rows = [] + for _, row in df.iterrows(): + data_row = ( + "|" + + "|".join( + [ + f" {str(row[col])}{' ' * (col_lengths[i] - len(str(row[col])))} " + for i, col in enumerate(headers) + ] + ) + + "|" + ) + data_rows.extend((data_row, hline)) + return "\n".join([hline, header_row, header_hline] + data_rows) + + +def apply_rst_format(df: pd.DataFrame) -> pd.DataFrame: + "Prepare daraframe for printing by intorducing ReST specific formatting" + + # convert the key to cite directive + df.loc[:, "citation_keys"] = ":cite:`" + df["citation_keys"] + "`" + + # identify and add footnote_marks + mask = df["annotations"].notnull() + df.loc[mask, "footnote_mark"] = "[#f_" + df.loc[mask, "attribute_name"] + "]" + df.loc[mask, "description"] = ( + df.loc[mask, "description"] + " (" + df.loc[mask, "footnote_mark"] + "_)" + ) + + # wrap attributes into code blocks + df.loc[:, "attribute_name"] = "``" + df["attribute_name"] + "``" + df.loc[:, "value_origin"] = df["value_origin"].str.lower() + + # capitalize column names which will be table headers + df.columns = [c.replace("_", " ").capitalize() for c in df.columns] + return df.fillna("") diff --git a/notebooks/render-docs-from-metadata.ipynb b/notebooks/render-docs-from-metadata.ipynb new file mode 100644 index 00000000..53cd3d0a --- /dev/null +++ b/notebooks/render-docs-from-metadata.ipynb @@ -0,0 +1,228 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": null, + "id": "dfc08dfa-d54f-47a9-9983-6259839b8313", + "metadata": {}, + "outputs": [], + "source": [ + "from mendeleev.models import ValueOrigin, PropertyMetadata\n", + "from mendeleev.db import get_session, get_engine\n", + "from mendeleev.fetch import fetch_table\n", + "from sqlalchemy import select, distinct" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "bfcf8a73-ecfe-454b-8cd8-ef5690463ca3", + "metadata": {}, + "outputs": [], + "source": [ + "from mendeleev.utils import render_rst_table, apply_rst_format" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d188e6dd-f67d-473b-9bb2-22897794019b", + "metadata": {}, + "outputs": [], + "source": [ + "def render_doc_table(class_name: str) -> str:\n", + " \"\"\"\n", + " Fetch attributes for a specific class and render a table for documentation.\n", + " \"\"\"\n", + " df = fetch_table(\"propertymetadata\")\n", + " df = df.loc[df[\"class_name\"] == class_name]\n", + " df = apply_rst_format(df)\n", + " \n", + " cols = [\n", + " 'Attribute name',\n", + " 'Description',\n", + " 'Unit',\n", + " 'Value origin',\n", + " 'Citation keys'\n", + " ]\n", + " # display version of the column names\n", + " return render_rst_table(df[cols].sort_values(\"Attribute name\"))" + ] + }, + { + "cell_type": "markdown", + "id": "923addd1-f2c6-4cfd-9d6f-6dd2727b292c", + "metadata": {}, + "source": [ + "## Elements" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "140f15ed-bbab-4376-9374-17871698c87f", + "metadata": { + "scrolled": true + }, + "outputs": [], + "source": [ + "table = render_doc_table(\"Element\")\n", + "print(table)" + ] + }, + { + "cell_type": "markdown", + "id": "8c68e88e-e30c-440d-b8ce-981273fe6e7c", + "metadata": {}, + "source": [ + "## IonicRadius" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "5d26ad06-af78-499a-abf6-32e4eff18ef3", + "metadata": {}, + "outputs": [], + "source": [ + "table = render_doc_table(\"IonicRadius\")\n", + "print(table)" + ] + }, + { + "cell_type": "markdown", + "id": "230f1375-8476-4644-b41f-1deed0a29dc4", + "metadata": {}, + "source": [ + "## Isotopes" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b605fec2-d336-4662-9819-837cc8a766f3", + "metadata": {}, + "outputs": [], + "source": [ + "table = render_doc_table(\"Isotope\")\n", + "print(table)" + ] + }, + { + "cell_type": "markdown", + "id": "ad2138e2-4439-4348-81b5-fa00919ca05c", + "metadata": {}, + "source": [ + "## Isotope Decay Modes" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7b529265-14d6-4306-b6d7-8c7f32a4f6df", + "metadata": {}, + "outputs": [], + "source": [ + "table = render_doc_table(\"IsotopeDecayMode\")\n", + "print(table)" + ] + }, + { + "cell_type": "markdown", + "id": "4fbe1d2c-26c2-4c27-94c6-4ae6b66c4685", + "metadata": {}, + "source": [ + "## Atomic Scattering Factors" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "81a79ab6-b0bb-474f-aba7-a7dae85b9ced", + "metadata": {}, + "outputs": [], + "source": [ + "table = render_doc_table(\"ScatteringFactor\")\n", + "print(table)" + ] + }, + { + "cell_type": "markdown", + "id": "2c866a3a-5800-4826-920e-c6cbcc8d504f", + "metadata": {}, + "source": [ + "## Ionization Energies" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "11f567eb-271b-42bc-af49-2d524ab6ec5c", + "metadata": {}, + "outputs": [], + "source": [ + "table = render_doc_table(\"IonizationEnergy\")\n", + "print(table)" + ] + }, + { + "cell_type": "markdown", + "id": "fcc7db46-8ef9-482f-8202-9f2e1138de97", + "metadata": {}, + "source": [ + "## Screening Constants" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "ede28c4c-cb74-4670-8bfb-09b583785d42", + "metadata": {}, + "outputs": [], + "source": [ + "table = render_doc_table(\"ScreeningConstant\")\n", + "print(table)" + ] + }, + { + "cell_type": "markdown", + "id": "f50ff7ef-e18b-47cf-aa08-3e3c3343818f", + "metadata": {}, + "source": [ + "## Oxidation States" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "8601497d-df35-4759-bf78-5228d965f733", + "metadata": {}, + "outputs": [], + "source": [ + "table = render_doc_table(\"OxidationState\")\n", + "print(table)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "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.12.0" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +}