Merge pull request #330 from naik-aakash/update_featurizers

Add new functions/methods to featurize module

Author: naik-aakash

.github/workflows/python-package.yml

@@ -37,7 +37,7 @@ jobs:
       fail-fast: false
       matrix:
         python-version: ["3.10", "3.11", "3.12"]
-        split: [1, 2, 3, 4, 5, 6]
+        split: [1, 2, 3, 4, 5]
 
 
     steps:
@@ -67,7 +67,7 @@ jobs:
         MPLBACKEND: Agg  # non-interactive backend for matplotlib
       run: |
         micromamba activate lobpy
-        pytest --cov=lobsterpy --cov-report term-missing --cov-append --splits 6 --group ${{ matrix.split }} -vv --durations-path ./tests/test_data/.pytest-split-durations
+        pytest --cov=lobsterpy --cov-report term-missing --cov-append --splits 5 --group ${{ matrix.split }} -vv --durations-path ./tests/test_data/.pytest-split-durations
 
     - name: Upload coverage
       if: matrix.python-version == '3.10'

.pre-commit-config.yaml

@@ -1,4 +1,4 @@
-exclude: ^(docs|examples|tests|.github)
+exclude: ^(docs|examples|.github|tests/test_data)
 
 ci:
   autoupdate_schedule: monthly

README.md

@@ -87,9 +87,13 @@ Please cite our papers:
 * A. A. Naik, K. Ueltzen, C. Ertural, A. J. Jackson, J. George, *Journal of Open Source Software* **2024**, *9*, 6286. [https://joss.theoj.org/papers/10.21105/joss.06286](https://joss.theoj.org/papers/10.21105/joss.06286).
 * J. George, G. Petretto, A. Naik, M. Esters, A. J. Jackson, R. Nelson, R. Dronskowski, G.-M. Rignanese, G. Hautier, *ChemPlusChem* **2022**, *87*, e202200123. [https://doi.org/10.1002/cplu.202200123](https://doi.org/10.1002/cplu.202200123) (Information on the methodology of the automatic analysis)
 
+If you use any of the following Featurizers, also cite the respective papers:
+
+* `FeaturizeCharges`: R. Nelson, C. Ertural, P. C. Müller, R. Dronskowski, in Comprehensive Inorganic Chemistry III, *Elsevier*, **2023**, pp. 141–201. [https://doi.org/10.1016/B978-0-12-823144-9.00120-5](https://doi.org/10.1016/B978-0-12-823144-9.00120-5)
+* `FeaturizeIcoxxlist`: V. L. Deringer, W. Zhang, M. Lumeij, S. Maintz, M. Wuttig, R. Mazzarello, R. Dronskowski, *Angewandte Chemie International Edition 2014*, *53*, 10817–10820. [https://doi.org/10.1002/anie.201404223](https://doi.org/10.1002/anie.201404223)
+
 Please cite [pymatgen](https://github.com/materialsproject/pymatgen), [Lobster](https://schmeling.ac.rwth-aachen.de/cohp/index.php?menuID=1), and [ChemEnv](https://doi.org/10.1107/S2052520620007994) correctly as well.
 
-.
 
 ## LobsterPy is now a part of an atomate2 workflow
 ![LobsterWorkflow](https://github.com/JaGeo/LobsterPy/assets/22094846/337615ac-542e-446c-bc63-fb5946b16544)

docs/fundamentals/index.ipynb

@@ -279,6 +279,22 @@
     "\n",
     "It is possible to compute ionicity based on above mentioned formula using either the Mulliken or Löwdin charges obtained from LOBSTER run."
    ]
+  },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "### ICOXX based features (ICOXX: ICOHP / ICOBI / ICOOP)\n",
+    "\n",
+    "Bond weighted distribution function (BWDF) is an extension of radial distribution function (RDF), which encodes information about the bonding character. The formulation for this was introduced in [V. L. Deringer, W. Zhang, M. Lumeij, S. Maintz, M. Wuttig, R. Mazzarello, R. Dronskowski, Angewandte Chemie International Edition 2014, 53, 10817–10820](https://doi.org/10.1002/anie.201404223) and is defined as follows :\n",
+    "\n",
+    "$\\mathrm{BWDF}=\\sum_{\\mathrm{B}>\\mathrm{A}}\\left[\\delta\\left(r-\\left|\\mathbf{r}_{\\mathrm{AB}}\\right|\\right) \\times B_{\\mathrm{AB}}\\right]$\n",
+    "\n",
+    "In the formula above, $\\delta$ is the Dirac delta function, $r$ is the distance between atoms A and B, and $B_{\\mathrm{AB}}$ is the bond strength between atoms A and B. The bond strength can be ICOHPs, ICOBIs, or ICOOPs. The BWDF is thus a histogram of bond strengths as a function of bond length. One can compute this for entire structure, for each unique atom pair in the structure, per site or per bond label.\n",
+    "\n",
+    "Here, from the BWDF mainly statistical features like mean, standard deviation, skewness, kurtosis, weighted mean, and weighted standard deviation are computed.\n"
+   ],
+   "id": "a2f623edafa5efc9"
   }
  ],
  "metadata": {

docs/reference/cli_subcommands/descriptionquality.rst

@@ -1,7 +1,7 @@
 description-quality
 ===================
 
-Deliver a text description of the LOBSTER calc quality analysis. Mandatory required files: POSCAR, POTCAR or POTCAR symbols, lobsterout, lobsterin. Optional files (BVA comparison): CHARGE.lobster, (DOS comparison): DOSCAR.lobster/ DOSCAR.LSO.lobster, Vasprun.xml.
+Deliver a text description of the LOBSTER calc quality analysis. Mandatory required files: structure file (preferably CONTCAR), POTCAR or POTCAR symbols, lobsterout, lobsterin. Optional files (BVA comparison): CHARGE.lobster, (DOS comparison): DOSCAR.lobster/ DOSCAR.LSO.lobster, Vasprun.xml.
 
 .. argparse::
    :module: lobsterpy.cli

docs/tutorial/commandlineinterface.rst

@@ -15,7 +15,7 @@ Creating input files
 
 
 With LobsterPy, these intricate details are handled with a single command. We need the standard VASP input files, i.e. 
-``INCAR, KPOINTS, POTCAR and POSCAR`` in the calculation directory. Once you have these files, one needs to run the following command:
+``INCAR, KPOINTS, POTCAR and CONTCAR`` in the calculation directory. Once you have these files, one needs to run the following command:
 
 ``lobsterpy create-inputs``
 
@@ -182,7 +182,7 @@ Following is the json file produced.
 -  ``lobsterpy description-quality --potcar-symbols "Na_pv Cl" --bvacomp --doscomp`` command will automatically analyze your lobster calculation quality.
 
 .. note::
-   The LOBSTER calculation directory need to have POTCAR, POSCAR, LOBSTER calculation input and output files to run the **lobsterpy calc-description** command successfully. 
+   The LOBSTER calculation directory need to have POTCAR, structure file (preferably CONTCAR), LOBSTER calculation input and output files to run the **lobsterpy description-quality** command successfully.
    If POTCAR is not available then you need to supply **--potcar-symbols** along with the command. Other optional files are vasprun.xml if **--doscomp** is switched on.
 
 .. code:: bash

docs/tutorial/tutorial.ipynb

@@ -51,6 +51,9 @@
    "outputs": [],
    "source": [
     "from pathlib import Path\n",
+    "\n",
+    "from pexpect.replwrap import python\n",
+    "\n",
     "from lobsterpy.cohp.analyze import Analysis\n",
     "from lobsterpy.cohp.describe import Description\n",
     "import warnings\n",
@@ -92,7 +95,7 @@
    "source": [
     "# Initialize Analysis object\n",
     "analyse = Analysis(\n",
-    "    path_to_poscar=directory / \"POSCAR.gz\",\n",
+    "    path_to_poscar=directory / \"CONTCAR.gz\",\n",
     "    path_to_icohplist=directory / \"ICOHPLIST.lobster.gz\",\n",
     "    path_to_cohpcar=directory / \"COHPCAR.lobster.gz\",\n",
     "    path_to_charge=directory / \"CHARGE.lobster.gz\",\n",
@@ -195,7 +198,7 @@
     "\n",
     "```python\n",
     "analyse = Analysis(\n",
-    "    path_to_poscar=directory / \"POSCAR.gz\",\n",
+    "    path_to_poscar=directory / \"CONTCAR.gz\",\n",
     "    path_to_icohplist=directory / \"ICOBILIST.lobster.gz\",\n",
     "    path_to_cohpcar=directory / \"COBICAR.lobster.gz\",\n",
     "    path_to_charge=directory / \"CHARGE.lobster.gz\",\n",
@@ -232,7 +235,7 @@
    "outputs": [],
    "source": [
     "analyse = Analysis(\n",
-    "    path_to_poscar=directory / \"POSCAR.gz\",\n",
+    "    path_to_poscar=directory / \"CONTCAR.gz\",\n",
     "    path_to_icohplist=directory / \"ICOHPLIST.lobster.gz\",\n",
     "    path_to_cohpcar=directory / \"COHPCAR.lobster.gz\",\n",
     "    path_to_charge=directory / \"CHARGE.lobster.gz\",\n",
@@ -358,7 +361,7 @@
    "source": [
     "# Get calculation quality summary dict\n",
     "calc_quality_K3Sb = Analysis.get_lobster_calc_quality_summary(\n",
-    "            path_to_poscar=directory / \"POSCAR.gz\",\n",
+    "            path_to_poscar=directory / \"CONTCAR.gz\",\n",
     "            path_to_charge=directory / \"CHARGE.lobster.gz\",\n",
     "            path_to_lobsterin=directory / \"lobsterin.gz\",\n",
     "            path_to_lobsterout=directory / \"lobsterout.gz\",\n",
@@ -557,7 +560,7 @@
     "# Load Lobster DOS\n",
     "directory = Path(\".\") / \"..\" / \"..\" / \"tests\" / \"test_data\" / \"NaCl_comp_range\"\n",
     "dos = Doscar(doscar=directory / 'DOSCAR.lobster.gz',\n",
-    "             structure_file=directory / 'POSCAR.gz')"
+    "             structure_file=directory / 'CONTCAR.gz')"
    ]
   },
   {
@@ -569,7 +572,7 @@
     "# Load Lobster DOS (Change this cell block type to Code when executing locally)\n",
     "directory = Path(\"LobsterPy\") / \"tests\" / \"test_data\" / \"NaCl_comp_range\"\n",
     "dos = Doscar(doscar=directory / 'DOSCAR.lobster.gz',\n",
-    "             structure_file=directory / 'POSCAR.gz')\n",
+    "             structure_file=directory / 'CONTCAR.gz')\n",
     "```"
    ]
   },
@@ -585,9 +588,7 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "a271f2f0",
-   "metadata": {
-    "scrolled": false
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "style.use('default') # Complete reset the matplotlib figure style\n",
@@ -658,7 +659,7 @@
    "outputs": [],
    "source": [
     "graph_NaCl_all = LobsterGraph(\n",
-    "    path_to_poscar=directory / \"POSCAR.gz\",\n",
+    "    path_to_poscar=directory / \"CONTCAR.gz\",\n",
     "    path_to_charge=directory / \"CHARGE.lobster.gz\",\n",
     "    path_to_cohpcar=directory / \"COHPCAR.lobster.gz\",\n",
     "    path_to_icohplist=directory / \"ICOHPLIST.lobster.gz\",\n",
@@ -679,7 +680,7 @@
     "```python\n",
     "#### (Change this cell block type to Code or copy it from here when executing locally)\n",
     "graph_NaCl_all = LobsterGraph(\n",
-    "    path_to_poscar=directory / \"POSCAR.gz\",\n",
+    "    path_to_poscar=directory / \"CONTCAR.gz\",\n",
     "    path_to_charge=directory / \"CHARGE.lobster.gz\",\n",
     "    path_to_cohpcar=directory / \"COHPCAR.lobster.gz\",\n",
     "    path_to_icohplist=directory / \"ICOHPLIST.lobster.gz\",\n",
@@ -746,7 +747,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from lobsterpy.featurize.batch import (BatchCoxxFingerprint, BatchDosFeaturizer,\n",
+    "from lobsterpy.featurize.batch import (BatchCoxxFingerprint, BatchIcoxxlistFeaturizer, BatchDosFeaturizer,\n",
     "                                       BatchSummaryFeaturizer, BatchStructureGraphs)"
    ]
   },
@@ -834,6 +835,72 @@
     "fp_cohp_bonding.get_similarity_matrix_df()"
    ]
   },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": "### BatchIcoxxlistFeaturizer",
+   "id": "a5220531c2082185"
+  },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "`BatchIcoxxlistFeaturizer` provides a convenient way to extract BWDF as features from the LOBSTER calculation directory. The extracted features consist of the following:\n",
+    "\n",
+    "1. BWDF mean, standard deviation , skewness, kurtosis, weighted mean, and weighted standard deviation\n",
+    "2. Complete BWDF as columns in the dataframe\n",
+    "3. BWDF values sorted by bond distances as columns in the dataframe\n",
+    "4. Bond distances sorted by BWDF values as columns in the dataframe"
+   ],
+   "id": "9de31478633c9afc"
+  },
+  {
+   "metadata": {},
+   "cell_type": "code",
+   "outputs": [],
+   "execution_count": null,
+   "source": [
+    "# Initialize the batch ICOXXLIST featurizer\n",
+    "batch_icohp = BatchIcoxxlistFeaturizer(path_to_lobster_calcs=directory / \"..\" / \"Featurizer_test_data\" / \"Lobster_calcs\", # path to parent lobster calcs\n",
+    "            normalization=\"formula_units\", # will normalize the BWDF values by formula units\n",
+    "            max_length=6, # maximum bond length for BWDF computation\n",
+    "            bin_width=0.1, # sets number for bins\n",
+    "            bwdf_df_type=\"stats\", # Type of BWDF dataframe to generate (stats, binned, sorted_bwdf, sorted_dists)\n",
+    "            read_icobis=False, # set to true to read ICOBI data\n",
+    "            read_icoops=False, # set to true to read ICOOP data\n",
+    "            n_jobs=3,)"
+   ],
+   "id": "2ed6793640da4fac"
+  },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "```python\n",
+    "## Initialize batch ICOXXLIST featurizer (Change this cell block type to Code and remove formatting when executing locally)\n",
+    "batch_icohp = BatchIcoxxlistFeaturizer(path_to_lobster_calcs=directory / \"..\" / \"Featurizer_test_data\" / \"Lobster_calcs\", # path to parent lobster calcs\n",
+    "            normalization=\"formula_units\", # will normalize the BWDF values by formula units\n",
+    "            max_length=6, # maximum bond length for BWDF computation\n",
+    "            bin_width=0.1, # sets number for bins\n",
+    "            bwdf_df_type=\"stats\", # Type of BWDF dataframe to generate (stats, binned, sorted_bwdf, sorted_dists)\n",
+    "            read_icobis=False, # set to true to read ICOBI data\n",
+    "            read_icoops=False, # set to true to read ICOOP data\n",
+    "            n_jobs=3,)\n",
+    "```"
+   ],
+   "id": "b3111a3881b29058"
+  },
+  {
+   "metadata": {},
+   "cell_type": "code",
+   "outputs": [],
+   "execution_count": null,
+   "source": [
+    "# get the BWDF stats df\n",
+    "batch_icohp.get_df()"
+   ],
+   "id": "7c731fe3e32065be"
+  },
   {
    "cell_type": "markdown",
    "id": "4bf34582",
@@ -1067,7 +1134,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.4"
+   "version": "3.10.14"
   },
   "widgets": {
    "application/vnd.jupyter.widget-state+json": {

examples/NaCl/POSCAR examples/NaCl/CONTCARexamples/NaCl/POSCAR renamed to examples/NaCl/CONTCAR

@@ -7,7 +7,7 @@
 
 # Setup analysis dict
 analyse = Analysis(
-    path_to_poscar=os.path.join(directory, "POSCAR"),
+    path_to_poscar=os.path.join(directory, "CONTCAR"),
     path_to_icohplist=os.path.join(directory, "ICOHPLIST.lobster"),
     path_to_cohpcar=os.path.join(directory, "COHPCAR.lobster"),
     path_to_charge=os.path.join(directory, "CHARGE.lobster"),