file tables and improved wording in data/wbm/readme.md

Author: janosh

data/wbm/readme.md

@@ -10,59 +10,57 @@ Since repeated substitutions should - on average - increase chemical dissimilari
 
 ## About the IDs
 
-As you may have guessed, the first integer in each material ID following the prefix `wbm-` ranges from 1 to 5 and indicates the substitution iteration count. Each iteration has varying numbers of materials counted by the 2nd integer. Note the 2nd integer is not strictly consecutive. A small number of materials (~0.2%) were removed by the data processing steps detailed below. Don't be surprised to find an ID like `wbm-3-70804` followed by
+The first integer in each material ID ranging from 1 to 5 and coming right after the prefix `wbm-` indicates the substitution step, i.e. in which iteration of the substitution process was this material generated. Each iteration has varying numbers of materials which are counted by the 2nd integer. Note this 2nd number is not always consecutive. A small number of materials (~0.2%) were removed by the data processing steps detailed below. Don't be surprised to find an ID like `wbm-3-70804` followed by `wbm-3-70807`.
 
 ## Data processing steps
 
-The full set of processing steps used to curate the WBM test set from the raw data files (downloaded from the URLs listed below) can be found in [`data/wbm/fetch_process_wbm_dataset.py`](https://github.com/janosh/matbench-discovery/blob/site/data/wbm/fetch_process_wbm_dataset.py). Processing involved
+The full set of processing steps used to curate the WBM test set from the raw data files (downloaded from URLs listed below) can be found in [`data/wbm/fetch_process_wbm_dataset.py`](https://github.com/janosh/matbench-discovery/blob/site/data/wbm/fetch_process_wbm_dataset.py). Processing involved
 
 - re-formatting material IDs
-- correctly aligning initial structures to DFT-relaxed `ComputedStructureEntries`
+- correctly aligning initial structures to DFT-relaxed [`ComputedStructureEntries`](https://pymatgen.org/pymatgen.entries.computed_entries.html#pymatgen.entries.computed_entries.ComputedStructureEntry)
 - remove 6 pathological structures (with 0 volume)
-- remove formation energy outliers below -5 and above 5 eV/atom (removed 502 and 22 crystals respectively out of 257,487 total, including an anomaly of 500 structures at exactly -10 eV/atom)
+- remove formation energy outliers below -5 and above 5 eV/atom (502 and 22 crystals respectively out of 257,487 total, including an anomaly of 500 structures at exactly -10 eV/atom)
   <!-- ![WBM formation energy histogram indicating outlier cutoffs](2022-12-07-hist-e-form-per-atom.png) -->
 - apply the [`MaterialsProject2020Compatibility`](https://pymatgen.org/pymatgen.entries.compatibility.html#pymatgen.entries.compatibility.MaterialsProject2020Compatibility) energy correction scheme to the formation energies
-- compute energy to the convex hull constructed from all MP `ComputedStructureEntries` queried on 2022-09-16 ([database release 2021.05.13](https://docs.materialsproject.org/changes/database-versions#v2021.05.13))
+- compute energy to the Materials Project convex hull constructed from all MP `ComputedStructureEntries` queried on 2022-09-16 ([database release 2021.05.13](https://docs.materialsproject.org/changes/database-versions#v2021.05.13))
 
-The number of materials in each step before and after processing are:
+Invoking the script `python fetch_process_wbm_dataset.py` will auto-download and regenerate the WBM test set files from scratch. If you find
+
+- any questionable structures or data records in the released test set, or
+- inconsistencies between the files on GitHub vs the output of that script,
+
+please [raise an issue](https://github.com/janosh/matbench-discovery/issues).
 
-| step | 1      | 2      | 3      | 4      | 5      | total   |
-| ---- | ------ | ------ | ------ | ------ | ------ | ------- |
-| pre  | 61,848 | 52,800 | 79,205 | 40,328 | 23,308 | 257,487 |
-| post | 61,466 | 52,755 | 79,160 | 40,314 | 23,268 | 256,963 |
+The number of materials in each step before and after processing are:
 
-Invoking that script with `python fetch_process_wbm_dataset.py` will auto-download and regenerate the WBM test set files from scratch. If you find any questionable in the released test set or inconsistencies between the files on GitHub vs the output of that script, please [raise an issue](https://github.com/janosh/matbench-discovery/issues).
+| step   | 1      | 2      | 3      | 4      | 5      | total   |
+| ------ | ------ | ------ | ------ | ------ | ------ | ------- |
+| before | 61,848 | 52,800 | 79,205 | 40,328 | 23,308 | 257,487 |
+| after  | 61,466 | 52,755 | 79,160 | 40,314 | 23,268 | 256,963 |
 
-## Links to WBM data files
+## Links to raw WBM data files
 
 Links to WBM data files have proliferated. This is an attempt to keep track of all of them.
 
-Initial structures were sent as Google Drive links via email by Hai-Chen Wang on 2021-09-01.
-
-step 1: <https://drive.google.com/file/d/1ZUgtYwrfZn_P8bULWRtTXepyAxHVxS5C>
-step 2: <https://drive.google.com/file/d/1-3uu2AcARJxH7GReteGVASZTuttFGiW_>
-step 3: <https://drive.google.com/file/d/1hc5BvDiFfTu_tc5F8m7ONSw2OgL9vN6o>
-step 4: <https://drive.google.com/file/d/1aMYxG5YJUgMHpbWmHpzL4hRfmP26UQqh>
-step 5: <https://drive.google.com/file/d/17kQt2r78ReWle4PhEIOXG7w7BFdezGM1>
-summary: <https://drive.google.com/file/d/1639IFUG7poaDE2uB6aISUOi65ooBwCIg>
-
-The `ComputedStructureEntries` for steps 1-3 were also linked from the [WBM Nature paper][wbm paper]:
-
-Index page: <https://tddft.org/bmg/data.php>
-step 1 CSEs: <https://tddft.org/bmg/files/data/substitutions_000.json.bz2>
-step 2 CSEs: <https://tddft.org/bmg/files/data/substitutions_001.json.bz2>
-step 3 CSEs: <https://tddft.org/bmg/files/data/substitutions_002.json.bz2>
-CIF files: <https://tddft.org/bmg/files/data/similarity-cifs.tar.gz>
-
-Materials Cloud archive: <https://archive.materialscloud.org/record/2021.68>
-File URLs:
-
-- readme: <https://archive.materialscloud.org/record/file?record_id=840&filename=README.txt>
-- summary: <https://archive.materialscloud.org/record/file?record_id=840&filename=summary.txt.bz2>
-- step 1: <https://archive.materialscloud.org/record/file?record_id=840&filename=step_1.json.bz2>
-- step 2: <https://archive.materialscloud.org/record/file?record_id=840&filename=step_2.json.bz2>
-- step 3: <https://archive.materialscloud.org/record/file?record_id=840&filename=step_3.json.bz2>
-- step 4: <https://archive.materialscloud.org/record/file?record_id=840&filename=step_4.json.bz2>
-- step 5: <https://archive.materialscloud.org/record/file?record_id=840&filename=step_5.json.bz2>
+Initial structures (after element substitution but before DFT relaxation) were sent as Google Drive links via email by Hai-Chen Wang on 2021-09-01.
+
+### Google Drive
+
+| Google Drive links | [step 1](https://drive.google.com/file/d/1ZUgtYwrfZn_P8bULWRtTXepyAxHVxS5C) | [step 2](https://drive.google.com/file/d/1-3uu2AcARJxH7GReteGVASZTuttFGiW_) | [step 3](https://drive.google.com/file/d/1hc5BvDiFfTu_tc5F8m7ONSw2OgL9vN6o) | [step 4](https://drive.google.com/file/d/1aMYxG5YJUgMHpbWmHpzL4hRfmP26UQqh) | [step 5](https://drive.google.com/file/d/17kQt2r78ReWle4PhEIOXG7w7BFdezGM1) | [summary](https://drive.google.com/file/d/1639IFUG7poaDE2uB6aISUOi65ooBwCIg) |
+| ------------------ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+
+### Halle University
+
+The [paper itself][wbm paper] links to a [Halle University data page](https://tddft.org/bmg/data.php) which lists download URLs for CIF files and the `ComputedStructureEntries` (CSEs) of steps 1-3:
+
+| [Halle University links](https://tddft.org/bmg/data.php) | [step 1 CSEs](https://tddft.org/bmg/files/data/substitutions_000.json.bz2) | [step 2 CSEs](https://tddft.org/bmg/files/data/substitutions_001.json.bz2) | [step 3 CSEs](https://tddft.org/bmg/files/data/substitutions_002.json.bz2) | [CIF files](https://tddft.org/bmg/files/data/similarity-cifs.tar.gz) |
+| -------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+
+### Materials Cloud
+
+materialscloud:2021.68 includes a readme file with a description of the dataset, meanings of the summary CSV columns and a Python script for loading the data.
+
+| [Materials Cloud archive](https://archive.materialscloud.org/record/2021.68) | [step 1](https://archive.materialscloud.org/record/file?record_id=840&filename=step_1.json.bz2) | [step 2](https://archive.materialscloud.org/record/file?record_id=840&filename=step_2.json.bz2) | [step 3](https://archive.materialscloud.org/record/file?record_id=840&filename=step_3.json.bz2) | [step 4](https://archive.materialscloud.org/record/file?record_id=840&filename=step_4.json.bz2) | [step 5](https://archive.materialscloud.org/record/file?record_id=840&filename=step_5.json.bz2) | [summary](https://archive.materialscloud.org/record/file?record_id=840&filename=summary.txt.bz2) | [readme](https://archive.materialscloud.org/record/file?record_id=840&filename=README.txt) |
+| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
 
 [wbm paper]: https://nature.com/articles/s41524-020-00481-6

readme.md

@@ -13,7 +13,7 @@ Matbench Discovery
 
 </h4>
 
-Matbench is an [interactive leaderboard](https://matbench-discovery.janosh.dev/figures) and associated [PyPI package](https://pypi.org/project/matbench-discovery) for benchmarking ML energy models on a task designed to closely emulate a real-world computational materials discovery workflow in which these models would be used for a pre-triaging step to determine how to allocate limited compute budget on DFT structure relaxations.
+Matbench Discovery is an [interactive leaderboard](https://matbench-discovery.janosh.dev/figures) and associated [PyPI package](https://pypi.org/project/matbench-discovery) for benchmarking ML energy models on a task designed to closely emulate a real-world computational materials discovery workflow in which these models would be used for a pre-triaging step to determine how to allocate limited compute budget on DFT structure relaxations.
 
 We welcome contributions that add new models to the leaderboard through [GitHub PRs](https://github.com/janosh/matbench-discovery/pulls).
 

site/package.json

@@ -13,7 +13,7 @@
     "preview": "vite preview",
     "serve": "vite build && vite preview",
     "check": "svelte-check",
-    "make-api-docs": "cd .. && lazydocs matbench_discovery --output-path site/src/routes/api --no-watermark --src-base-url https://github.com/janosh/matbench-discovery/blob/main"
+    "make-api-docs": "rm -f src/routes/api/*.md && cd .. && lazydocs matbench_discovery --output-path site/src/routes/api --no-watermark --src-base-url https://github.com/janosh/matbench-discovery/blob/main"
   },
   "devDependencies": {
     "@iconify/svelte": "^3.0.1",