add usage example code fence and WBM summary column glossary to how-to-use/+page.svx

update package.json deps

Author: janosh

site/package.json

@@ -17,29 +17,29 @@
   },
   "devDependencies": {
     "@iconify/svelte": "^3.0.1",
-    "@sveltejs/adapter-static": "1.0.0-next.48",
-    "@sveltejs/kit": "1.0.0-next.571",
-    "@sveltejs/vite-plugin-svelte": "^1.4.0",
-    "@typescript-eslint/eslint-plugin": "^5.45.0",
-    "@typescript-eslint/parser": "^5.45.0",
-    "eslint": "^8.29.0",
+    "@sveltejs/adapter-static": "1.0.0",
+    "@sveltejs/kit": "1.0.1",
+    "@sveltejs/vite-plugin-svelte": "^2.0.2",
+    "@typescript-eslint/eslint-plugin": "^5.47.0",
+    "@typescript-eslint/parser": "^5.47.0",
+    "eslint": "^8.30.0",
     "eslint-plugin-svelte3": "^4.0.0",
     "hastscript": "^7.1.0",
     "highlight.js": "^11.7.0",
     "mdsvex": "^0.10.6",
-    "prettier": "^2.8.0",
-    "prettier-plugin-svelte": "^2.8.1",
+    "prettier": "^2.8.1",
+    "prettier-plugin-svelte": "^2.9.0",
     "rehype-autolink-headings": "^6.1.1",
     "rehype-slug": "^5.1.0",
-    "svelte": "^3.53.1",
-    "svelte-check": "^2.10.0",
+    "svelte": "^3.55.0",
+    "svelte-check": "^3.0.1",
     "svelte-github-corner": "^0.1.0",
-    "svelte-preprocess": "^4.10.7",
-    "svelte-toc": "^0.5.0",
-    "svelte2tsx": "^0.5.21",
+    "svelte-preprocess": "^5.0.0",
+    "svelte-toc": "^0.5.1",
+    "svelte2tsx": "^0.6.0",
     "tslib": "^2.4.1",
-    "typescript": "^4.9.3",
-    "vite": "^3.2.4"
+    "typescript": "^4.9.4",
+    "vite": "^4.0.3"
   },
   "prettier": {
     "semi": false,

site/src/app.css

@@ -44,10 +44,10 @@ a:hover {
 }
 code {
   overflow-wrap: break-word;
-  padding: 0 2pt;
+  padding: 1pt 3pt;
   border-radius: 2pt;
   font-size: 1.2em;
-  background-color: rgba(255, 255, 255, 0.15);
+  background-color: rgba(0, 255, 255, 0.1);
 }
 pre code {
   background-color: transparent;
@@ -57,8 +57,9 @@ pre {
   border-radius: 4pt;
   font-size: 9.5pt;
   background-color: rgba(255, 255, 255, 0.05);
-  padding: 1em;
   overflow-x: auto;
+  padding: 6pt 8pt;
+  margin: 1em auto;
 }
 ul {
   padding-left: 1em;

site/src/routes/how-to-use/+page.svx

@@ -1,16 +1,43 @@
-<script lang="ts">
-  // import * as d3 from 'd3'
+## Installation
 
-  // const promise = d3.csv('https://github.com/janosh/matbench-discovery/raw/main/data/wbm/2022-10-19-wbm-summary.csv')
-  // const promise = d3.csv('https://raw.githubusercontent.com/janosh/pymatviz/main/pymatviz/elements.csv')
-</script>
-
-The primary way to use this benchmark is through the [PyPI Python package](https://pypi.org/project/matbench-discovery):
+The recommended way to use this benchmark is through the [PyPI Python package](https://pypi.org/project/matbench-discovery):
 
 ```zsh
 pip install matbench-discovery
 ```
 
+## Usage
+
+Here's an example script of how to download the training and test set files for training a new model, recording the results and submitting them via pull request to this benchmark:
+
+```py
+from matbench_discovery.data import load_train_test
+
+df_wbm = load_train_test("wbm-summary", version="v1.0.0")
+
+print(df_wbm.shape)
+>>> (256963, 17)
+
+print(list(df_wbm))
+>>> ['formula', 'n_sites', 'volume', 'uncorrected_energy', 'e_form_per_atom_wbm', 'e_hull_wbm', 'bandgap_pbe', 'uncorrected_energy_from_cse', 'e_correction_per_atom_legacy', 'e_correction_per_atom_mp2020', 'e_above_hull_uncorrected_ppd_mp', 'e_above_hull_mp2020_corrected_ppd_mp', 'e_above_hull_legacy_corrected_ppd_mp', 'e_form_per_atom_uncorrected', 'e_form_per_atom_mp2020_corrected', 'e_form_per_atom_legacy_corrected', 'wyckoff_spglib']
+```
+
+Column glossary
+
+1. `formula`: A compound's unreduced alphabetical formula
+1. `n_sites`: Number of sites in the structure's unit cell
+1. `volume`: Relaxed structure volume in cubic Angstrom
+1. `uncorrected_energy`: Raw VASP-computed energy
+1. `e_form_per_atom_wbm`: Original formation energy per atom from [WBM paper]
+1. `e_hull_wbm`: Original energy above the convex hull in (eV/atom) from [WBM paper]
+1. `bandgap_pbe`: PBE-level DFT band gap from [WBM paper]
+1. `uncorrected_energy_from_cse`: Should be the same as `uncorrected_energy`. There are 2 cases where the absolute difference reported in the summary file and in the computed structure entries exceeds 0.1 eV (`wbm-2-3218`, `wbm-1-56320`) which we attribute to rounding errors.
+1. `e_form_per_atom_mp2020_corrected`: Matbench Discovery takes these as ground truth for the formation energy. Includes MP2020 energy corrections (latest correction scheme at time of release).
+1. `e_above_hull_mp2020_corrected_ppd_mp`: Energy above hull distances in eV/atom after applying the MP2020 correction scheme and with respect to the Materials Project convex hull. Matbench Discovery takes these as ground truth for material stability. Any value above 0 is assumed to be an unstable/metastable material.
+<!-- TODO document remaining columns, or maybe drop them from df -->
+
+## Direct Download
+
 You can also download the data files directly:
 
 1. [`2022-10-19-wbm-summary.csv`](https://github.com/janosh/matbench-discovery/raw/v1.0.0/data/wbm/2022-10-19-wbm-summary.csv) [[GitHub](https://github.com/janosh/matbench-discovery/blob/v1/data/wbm/2022-10-19-wbm-summary.csv)]: Computed material properties only, no structures. Available properties are VASP energy, formation energy, energy above the convex hull, volume, band gap, number of sites per unit cell, and more. e_form_per_atom and e_above_hull each have 3 separate columns for old, new and no Materials
@@ -21,6 +48,4 @@ You can also download the data files directly:
 1. [`2022-09-18-ppd-mp.pkl.gz`](https://github.com/janosh/matbench-discovery/raw/v1.0.0/data/wbm/2022-09-18-ppd-mp.pkl.gz) [[GitHub](https://github.com/janosh/matbench-discovery/blob/v1/data/wbm/2022-09-18-ppd-mp.pkl.gz)]: [PatchedPhaseDiagram](https://pymatgen.org/pymatgen.analysis.phase_diagram.html#pymatgen.analysis.phase_diagram.PatchedPhaseDiagram) constructed from all MP ComputedStructureEntries
 1. [`2022-09-19-mp-elemental-ref-energies.json`](https://github.com/janosh/matbench-discovery/raw/v1.0.0/data/wbm/2022-09-19-mp-elemental-ref-energies.json) [[GitHub](https://github.com/janosh/matbench-discovery/blob/v1/data/wbm/2022-09-19-mp-elemental-ref-energies.json)]: Minimum energy PDEntries for each element present in the Materials Project
 
-<!-- {#await promise then data}
-  {JSON.stringify(data)}
-{/await} -->
+[wbm paper]: https://nature.com/articles/s41524-020-00481-6

site/static/prism-vsc-dark-plus.css

@@ -50,13 +50,6 @@ code[class*='language-'] ::selection {
   }
 }
 
-/* Code blocks */
-pre[class*='language-'] {
-  padding: 1em;
-  margin: 0.5em 0;
-  overflow: auto;
-}
-
 :not(pre) > code[class*='language-'],
 pre[class*='language-'] {
   color: white;