DOC: provide exported fields as single TAR file (#223)

* DOC: add `README.md` explainer to TAR file * DOC: add text to hidden input cell buttons * DOC: combine Markdown cells into one * DOC: fold exported field listing under dropdown menu * DOC: hide cell with selected models * DOC: list JSON download links on PDF build * DOC: render combined download as button * ENH: embed reference subsystem in JSON metadata * FEAT: provide JSON files as a single TAR file * FIX: cache exported fields on GitLab CI
ComPWA · Oct 17, 2022 · ecea90c · ecea90c
1 parent b8a4071
commit ecea90c
Show file tree

Hide file tree

Showing 7 changed files with 105 additions and 44 deletions.
diff --git a/.gitignore b/.gitignore
@@ -4,6 +4,7 @@
 *.pkl
 *.png
 *.svg
+*.tar.gz
 *.v2
 
 # Build files

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -14,9 +14,9 @@ cache:
     paths:
       - docs/_build/.jupyter_cache
       - docs/_images
+      - docs/_static/export
       - docs/_static/images
       - docs/appendix/export
-      - docs/export
   - key:
       prefix: sympy
       files:

diff --git a/docs/_static/export/.gitkeep b/docs/_static/export/.gitkeep
diff --git a/docs/_static/export/README.md b/docs/_static/export/README.md
@@ -0,0 +1,16 @@
+# Computed polarimetry fields
+
+This folder contains the aligned polarimetry vector field $\vec\alpha$ computed over a 100x100 grid over the Dalitz plane for the decay $\Lambda_c^+ \to p\pi^+K^-$.
+
+The computed fields are made available in JSON format with the following keys:
+
+- **`metadata`**: description of the model used to compute the field. Contains:
+  - `model description`: indicates whether the `"Default amplitude model"` was used or one of the alternative models
+  - `parameters`: a dictionary of parameter names with their values (can be float, integer, or complex).
+  - `reference subsystem`: the subsystem ID (including LaTeX description) of the subsystem that was used to align the amplitudes with [Dalitz Plot Decomposition](https://journals.aps.org/prd/abstract/10.1103/PhysRevD.101.0340330).
+- **`m^2_Kpi`**: an array of 100 values for $\sigma_1 = M^2(K^-,\pi^+)$ that span the $x$-axis of the Dalitz grid.
+- **`m^2_pK`**: an array of 100 values for $\sigma_2 = M^2(p,K^-)$ that span the $y$-axis of the Dalitz grid.
+- **`alpha_x`**, **`alpha_y`**, **`alpha_z`**: computed values for $\alpha_x$, $\alpha_y$, $\alpha_z$ over a 100x100 grid arrays each.[^1]
+- **`intensity`**: computed intensity on each Dalitz grid point.[^1]
+
+[^1]: Grid points that lie outside the phase phase space are given as Not-a-Number (NaN).
diff --git a/docs/conf.py b/docs/conf.py
@@ -239,6 +239,7 @@ def print_missing_file_warning(filename: str) -> None:
     ".DS_Store",
     "Thumbs.db",
     "_build",
+    "_static/export/README.md",
 ]
 extensions = [
     "myst_nb",

diff --git a/docs/uncertainties.ipynb b/docs/uncertainties.ipynb
@@ -22,6 +22,9 @@
     "jupyter": {
      "source_hidden": true
     },
+    "mystnb": {
+     "code_prompt_show": "Import libraries"
+    },
     "tags": [
      "hide-cell",
      "scroll-input"
@@ -34,6 +37,7 @@
     "import json\n",
     "import logging\n",
     "import os\n",
+    "import tarfile\n",
     "from collections import defaultdict\n",
     "from textwrap import wrap\n",
     "\n",
@@ -99,8 +103,12 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
+    "mystnb": {
+     "code_prompt_show": "Selected amplitude models"
+    },
     "tags": [
-     "full-width"
+     "full-width",
+     "hide-input"
     ]
    },
    "outputs": [],
@@ -2098,6 +2106,9 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {
+    "mystnb": {
+     "code_prompt_show": "Define Dalitz grid"
+    },
     "tags": [
      "hide-cell"
     ]
@@ -2118,16 +2129,26 @@
     "jupyter": {
      "source_hidden": true
     },
+    "mystnb": {
+     "code_prompt_show": "Export fields as JSON"
+    },
     "tags": [
-     "remove-input"
+     "hide-cell",
+     "scroll-input"
     ]
    },
    "outputs": [],
    "source": [
-    "src = f\"\"\"\n",
-    ":::{{only}} html\n",
-    "Exported {grid_resolution}x{grid_resolution} JSON grids for each bootstrap (**statistics**):\n",
-    "\"\"\"\n",
+    "def format_subsystem(reference_subsystem) -> str:\n",
+    "    subsystem_names = {\n",
+    "        1: R\"K^{**} \\to \\pi^+ K^-\",\n",
+    "        2: R\"\\Lambda^{**} \\to p K^-\",\n",
+    "        3: R\"\\Delta^{**} \\to p \\pi^+\",\n",
+    "    }\n",
+    "    name = subsystem_names[reference_subsystem]\n",
+    "    return f\"{reference_subsystem}: {name}\"\n",
+    "\n",
+    "\n",
     "STAT_FILENAMES = []\n",
     "for i in tqdm(range(n_bootstraps), disable=NO_TQDM):\n",
     "    new_parameters = {k: v[i] for k, v in bootstrap_parameters.items()}\n",
@@ -2146,32 +2167,11 @@
     "        metadata={\n",
     "            \"model description\": nominal_model_title,\n",
     "            \"parameters\": {k: f\"{v}\" for k, v in new_parameters.items()},\n",
+    "            \"reference subsystem\": format_subsystem(reference_subsystem),\n",
     "        },\n",
     "    )\n",
     "    STAT_FILENAMES.append(filename)\n",
-    "    src += f\"{i+1}. [`{os.path.basename(filename)}`]({filename})\\n\"\n",
-    "src += \":::\"\n",
-    "Markdown(src)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "jupyter": {
-     "source_hidden": true
-    },
-    "tags": [
-     "remove-input"
-    ]
-   },
-   "outputs": [],
-   "source": [
-    "src = f\"\"\"\n",
-    ":::{{only}} html\n",
-    "```{{container}} full-width\n",
-    "Exported {grid_resolution}x{grid_resolution} JSON grids for each model (**systematics**):\n",
-    "\"\"\"\n",
+    "\n",
     "items = list(enumerate(jax_functions.items()))\n",
     "SYST_FILENAMES = []\n",
     "for i, (title, funcs) in tqdm(items, disable=NO_TQDM):\n",
@@ -2189,15 +2189,10 @@
     "        metadata={\n",
     "            \"model description\": title,\n",
     "            \"parameters\": {k: f\"{v}\" for k, v in func.parameters.items()},\n",
+    "            \"reference subsystem\": format_subsystem(reference_subsystem),\n",
     "        },\n",
     "    )\n",
-    "    SYST_FILENAMES.append(filename)\n",
-    "    src += f\"- [[download]]({filename}) {title}\\n\"\n",
-    "src += \"\"\"\\\n",
-    "```\n",
-    ":::\n",
-    "\"\"\"\n",
-    "Markdown(src)"
+    "    SYST_FILENAMES.append(filename)"
    ]
   },
   {
@@ -2207,6 +2202,9 @@
     "jupyter": {
      "source_hidden": true
     },
+    "mystnb": {
+     "code_prompt_show": "Merge into one TAR/JSON file"
+    },
     "tags": [
      "hide-input"
     ]
@@ -2241,9 +2239,15 @@
     "combined_json[s1_key] = s1_values\n",
     "combined_json[s2_key] = s2_values\n",
     "\n",
-    "filename = \"_static/export/polarimetry-field.json\"\n",
-    "with open(filename, \"w\") as f:\n",
-    "    json.dump(combined_json, f)"
+    "json_file = \"_static/export/polarimetry-field.json\"\n",
+    "with open(json_file, \"w\") as f:\n",
+    "    json.dump(combined_json, f)\n",
+    "\n",
+    "tar_file = \"_static/export/polarimetry-field.tar.gz\"\n",
+    "with tarfile.open(tar_file, \"w:gz\") as tar:\n",
+    "    tar.add(\"_static/export/README.md\", arcname=\"README.md\")\n",
+    "    for path in STAT_FILENAMES + SYST_FILENAMES:\n",
+    "        tar.add(path, arcname=os.path.basename(path))"
    ]
   },
   {
@@ -2259,11 +2263,50 @@
    },
    "outputs": [],
    "source": [
-    "byt = os.path.getsize(filename)\n",
     "src = f\"\"\"\n",
-    "```{{only}} html\n",
-    "All data combined can be downloaded **[here]({filename})** ({1e-6*byt:,.1f} MB).\n",
+    "::::{{only}} html\n",
+    ":::{{dropdown}} Exported {grid_resolution}x{grid_resolution} JSON grids for each bootstrap (*statistics*)\n",
+    "\"\"\"\n",
+    "for i, filename in enumerate(STAT_FILENAMES, 1):\n",
+    "    src += f\"{i}. [`{os.path.basename(filename)}`]({filename})\\n\"\n",
+    "src += f\"\"\"\\\n",
+    ":::\n",
+    "\n",
+    ":::{{dropdown}} Exported {grid_resolution}x{grid_resolution} JSON grids for each model (*systematics*)\n",
+    "\"\"\"\n",
+    "for title, filename in zip(models, SYST_FILENAMES):\n",
+    "    src += f\"- [[download]]({filename}) {title}\\n\"\n",
+    "src += \"\"\"\\\n",
+    ":::\n",
+    "\"\"\"\n",
+    "\n",
+    "bytes_json = os.path.getsize(json_file)\n",
+    "bytes_tar = os.path.getsize(tar_file)\n",
+    "src += f\"\"\"\n",
+    ":::{{card}} All data combined can be downloaded here\n",
+    "```{{button-link}} {json_file}\n",
+    ":color: primary\n",
+    ":outline:\n",
+    "{{octicon}}`file-code` **{os.path.basename(json_file)}** ({1e-6*bytes_json:,.1f} MB)\n",
+    "```\n",
+    "```{{button-link}} {tar_file}\n",
+    ":color: primary\n",
+    ":outline:\n",
+    "{{octicon}}`file-zip` **{os.path.basename(tar_file)}** ({1e-6*bytes_tar:,.1f} MB)\n",
     "```\n",
+    ":::\n",
+    "::::\n",
+    "\"\"\"\n",
+    "\n",
+    "src += \"\"\"\n",
+    ":::{only} latex\n",
+    "The polarimetry fields are computed for each parameter bootstrap (statistics) and for each model (systematics) on\n",
+    "[lc2pkpi-polarimetry.docs.cern.ch/uncertainties.html](https://lc2pkpi-polarimetry.docs.cern.ch/uncertainties.html).\n",
+    "All combined fields can be downloaded as single compressed TAR file under\n",
+    "[lc2pkpi-polarimetry.docs.cern.ch/_static/export/polarimetry-field.json](https://lc2pkpi-polarimetry.docs.cern.ch/_static/export/polarimetry-field.json)\n",
+    "and as a single JSON file under\n",
+    "[lc2pkpi-polarimetry.docs.cern.ch/_static/export/polarimetry-field.tar.gz](https://lc2pkpi-polarimetry.docs.cern.ch/_static/export/polarimetry-field.tar.gz).\n",
+    ":::\n",
     "\"\"\"\n",
     "Markdown(src)"
    ]

diff --git a/tox.ini b/tox.ini
@@ -60,7 +60,7 @@ commands =
     --re-ignore docs/_images/.* \
     --re-ignore docs/_static/.* \
     --re-ignore docs/api/.* \
-    --re-ignore docs/export/.* \
+    --re-ignore docs/appendix/export/.* \
     --watch docs \
     --watch src \
     docs/ docs/_build/html
-Original file line number
+Diff line change
@@ Expand Up / @@ -4,6 +4,7 @@ @@
     *.pkl
     *.png
     *.svg
+    *.tar.gz
     *.v2
     # Build files
@@ Expand Down @@