Create metadata table for stored properties (#156)

* add metadata table

* fix typos

* fix typos

* add metadata table with initial contents

* add ParrPearson on hardness

* update metadata schema and data

* add documentation for PropertyMetadata class

* update docstring

* add propertymetadata to fetch tables

* correct format

* update units

* render updated data docs

* update isotope metadata

* add isotope metadata to PropertyMetadata

* docs

* add PropertyMetadata to models.__all__

README.md

@@ -286,7 +286,7 @@ the `Element` object:
     >>> from mendeleev import element
 
 The `element` method accepts unique identifiers: atomic number, atomic
-symbol or element\'s name in english. To retrieve the entries on Silicon
+symbol or element\'s name in English. To retrieve the entries on Silicon
 by symbol type
 
 ``` {.sourceCode .python}
@@ -340,7 +340,7 @@ following attributes per isotope
 The columns represent the attributes `atomic_number`, `mass`,
 `abundance` and `mass_number` respectively.
 
-### Accesing data tables and the database
+### Accessing data tables and the database
 
 [mendeleev](http://mendeleev.readthedocs.org) offers also methods for
 accessing whole tables of data, e.g. table with the data on all isotopes

alembic/versions/7d745d77a7c1_add_propertymetadata_table.py

@@ -0,0 +1,41 @@
+"""add PropertyMetadata table
+
+Revision ID: 7d745d77a7c1
+Revises: 703682715347
+Create Date: 2024-05-21 13:11:24.427405
+
+"""
+
+# revision identifiers, used by Alembic.
+revision = '7d745d77a7c1'
+down_revision = '703682715347'
+branch_labels = None
+depends_on = None
+
+from alembic import op
+import sqlalchemy as sa
+
+
+value_origin_enum = sa.Enum('STORED', 'COMPUTED', name='valueorigin')
+
+def upgrade():
+
+    op.create_table(
+        'propertymetadata',
+        sa.Column('id', sa.Integer, primary_key=True, autoincrement=True),
+        sa.Column('table_name', sa.String, nullable=True),
+        sa.Column('column_name', sa.String, nullable=True),
+        sa.Column('class_name', sa.String, nullable=False),
+        sa.Column('attribute_name', sa.String, nullable=False),
+        sa.Column('category', sa.String, nullable=False),
+        sa.Column('value_origin', value_origin_enum, nullable=False),
+        sa.Column('description', sa.Text, nullable=False),
+        sa.Column('unit', sa.String, nullable=True),
+        sa.Column('annotations', sa.Text, nullable=True),
+        sa.Column('citation_keys', sa.String, nullable=True)
+    )
+
+
+def downgrade():
+    op.drop_table('propertymetadata')
+    value_origin_enum.drop(op.get_bind())

docs/source/api/mendeleev.cli.rst

@@ -1,29 +1,6 @@
 mendeleev.cli
 =============
 
-.. automodule:: mendeleev.cli
-
-
-
-
-
-
-
-   .. rubric:: Functions
-
-   .. autosummary::
-
-      clielement
-
-
-
-
-
-
-
-
-
-
-
-
+.. currentmodule:: mendeleev
 
+.. autodata:: cli

docs/source/api/mendeleev.ion.rst

@@ -1,29 +1,6 @@
 mendeleev.ion
 =============
 
-.. automodule:: mendeleev.ion
-
-
-
-
-
-
-
-
-
-
-
-   .. rubric:: Classes
-
-   .. autosummary::
-
-      Ion
-
-
-
-
-
-
-
-
+.. currentmodule:: mendeleev
 
+.. autodata:: ion

docs/source/api/mendeleev.models.rst

@@ -33,8 +33,10 @@
       IsotopeDecayMode
       OxidationState
       PhaseTransition
+      PropertyMetadata
       ScreeningConstant
       Series
+      ValueOrigin
 
 
 

docs/source/api/models.rst

@@ -95,6 +95,15 @@ OxidationState
 .. autoclass:: mendeleev.models.OxidationState
    :members:
 
+.. _propertymetadata-class:
+
+PropertyMetadata
+----------------
+
+.. currentmodule:: mendeleev.models
+
+.. autoclass:: mendeleev.models.PropertyMetadata
+   :members:
 
 .. _econf-class:
 

docs/source/data_access.rst

@@ -38,6 +38,7 @@ tables are available:
 - :ref:`oxidationstates <oxidationstate-class>`
 - :ref:`screeningconstants <screeningconstant-class>`
 - :ref:`series <series-class>`
+- :ref:`propertymetadata <propertymetadata-class>`
 
 .. autofunction:: fetch_table
 

docs/source/references.bib

@@ -845,3 +845,15 @@ @book{haynes2016crc
   edition   = {97th},
   pages     = {2704}
 }
+@article{ParrPearson1983,
+  author  = {Parr, Robert G. and Pearson, Ralph G.},
+  title   = {Absolute hardness: companion parameter to absolute electronegativity},
+  journal = {Journal of the American Chemical Society},
+  volume  = {105},
+  number  = {26},
+  pages   = {7512-7516},
+  year    = {1983},
+  doi     = {10.1021/ja00364a005},
+  url     = {https://doi.org/10.1021/ja00364a005},
+  eprint  = {https://doi.org/10.1021/ja00364a005}
+}

mendeleev/fetch.py

@@ -54,6 +54,7 @@ def fetch_table(table: str, **kwargs) -> pd.DataFrame:
         "isotopes",
         "oxidationstates",
         "phasetransitions",
+        "propertymetadata",
         "screeningconstants",
         "series",
     }

mendeleev/models.py

@@ -1,14 +1,15 @@
 # -*- coding: utf-8 -*-
 
-"""module specifying the database models"""
+"""module defining the database models"""
 
 from typing import Any, Callable, Dict, List, Tuple, Union
 from operator import attrgetter
+import enum
 import math
 import urllib.parse
 
 import numpy as np
-from sqlalchemy import Column, Boolean, Integer, String, Float, ForeignKey
+from sqlalchemy import Column, Boolean, Integer, String, Float, ForeignKey, Text, Enum
 from sqlalchemy.orm import declarative_base, relationship, reconstructor
 from sqlalchemy.ext.associationproxy import association_proxy
 from sqlalchemy.ext.hybrid import hybrid_property, hybrid_method
@@ -34,6 +35,7 @@
     "IonicRadius",
     "OxidationState",
     "Isotope",
+    "PropertyMetadata",
     "Series",
     "ScreeningConstant",
 ]
@@ -731,6 +733,54 @@ def __repr__(self) -> str:
         )
 
 
+class ValueOrigin(enum.Enum):
+    "Options for the origin of the property value."
+
+    STORED = "stored"
+    COMPUTED = "computed"
+
+
+class PropertyMetadata(Base):
+    """Metadata for properties of elements and isotopes.
+
+    Args:
+        annotations (str): Additional information about the property.
+        attribute_name (str): Name of the attribute of the ORM class.
+        category (str): Category of the property.
+        citation_keys (str): Comma separated list of citation keys. See references.bib for full bibliography.
+        class_name (str): Name of the ORM class.
+        column_name (str): Name of the column in the database.
+        description (str): Description of the property.
+        table_name (str): Name of the table in the database.
+        unit (str): Unit of the property.
+        value_origin (ValueOrigin): Origin of the value, either stored or computed.
+    """
+
+    __tablename__ = "propertymetadata"
+
+    id = Column(Integer, primary_key=True)
+    annotations = Column(Text)
+    attribute_name = Column(String, nullable=False)
+    category = Column(String)
+    citation_keys = Column(String)
+    class_name = Column(String, nullable=False)
+    column_name = Column(String, nullable=True)
+    description = Column(Text, nullable=False)
+    table_name = Column(String, nullable=True)
+    unit = Column(String)
+    value_origin = Column(Enum(ValueOrigin), nullable=False)
+
+    def __repr__(self) -> str:
+        return "%s(\n%s)" % (
+            self.__class__.__name__,
+            " ".join(
+                "\t%s=%r,\n" % (key, getattr(self, key))
+                for key in sorted(self.__dict__.keys())
+                if not key.startswith("_")
+            ),
+        )
+
+
 def fetch_attrs_for_group(attrs: List[str], group: int = 18) -> Tuple[List[Any]]:
     """
     A convenience function for getting a specified attribute for all