DOC: indicate orientation in alignment check (#153)

* DOC: normalize intensities in alignment check
* MAINT: rename orientation inset files
* MAINT: remove download buttons if figures unavailable

.cspell/python.txt

@@ -3,6 +3,7 @@ abspath
 ampform
 arange
 bbox
+cairosvg
 caplog
 clim
 cmap
@@ -17,6 +18,8 @@ hashlib
 hexdigest
 hspace
 imag
+imread
+imshow
 interp2d
 ioff
 ipykernel
@@ -79,3 +82,4 @@ ylabel
 ytick
 yticklabels
 yticks
+zorder

docs/appendix/alignment.ipynb

@@ -33,6 +33,7 @@
    "source": [
     "from __future__ import annotations\n",
     "\n",
+    "import cairosvg\n",
     "import jax.numpy as jnp\n",
     "import matplotlib.pyplot as plt\n",
     "import sympy as sp\n",
@@ -288,34 +289,74 @@
    },
    "outputs": [],
    "source": [
+    "def convert_svg_to_png(input_file: str, dpi: int) -> None:\n",
+    "    output_file = input_file.replace(\".svg\", \".png\").replace(\".SVG\", \".png\")\n",
+    "    with open(input_file) as f:\n",
+    "        src = f.read()\n",
+    "    cairosvg.svg2png(bytestring=src, write_to=output_file, dpi=dpi)\n",
+    "\n",
+    "\n",
+    "def overlay_inset(\n",
+    "    png_file: str, ax, position: tuple[float, float], width: float\n",
+    ") -> None:\n",
+    "    image = plt.imread(png_file)\n",
+    "    res_x, res_y, _ = image.shape\n",
+    "    x_min, x_max = ax.get_xlim()\n",
+    "    y_min, y_max = ax.get_ylim()\n",
+    "    aspect_ratio = res_x / res_y\n",
+    "    aspect_ratio /= (x_max - x_min) / (y_max - y_min)\n",
+    "    extent = [\n",
+    "        position[0],\n",
+    "        position[0] + width,\n",
+    "        position[1],\n",
+    "        position[1] + width / aspect_ratio,\n",
+    "    ]\n",
+    "    ax.imshow(image, aspect=\"auto\", extent=extent, zorder=2)\n",
+    "    ax.set_xlim(x_min, x_max)\n",
+    "    ax.set_ylim(y_min, y_max)\n",
+    "\n",
+    "\n",
+    "for subsystem in [\"K\", \"D\", \"L\"]:\n",
+    "    convert_svg_to_png(f\"../_images/orientation-{subsystem}.svg\", dpi=200)\n",
+    "\n",
     "s1_label = R\"$\\sigma_1=m^2\\left(K^-\\pi^+\\right)$ [GeV/$c^2$]\"\n",
     "s2_label = R\"$\\sigma_2=m^2\\left(pK^-\\right)$ [GeV/$c^2$]\"\n",
     "s3_label = R\"$\\sigma_3=m^2\\left(p\\pi^+\\right)$ [GeV/$c^2$]\"\n",
     "\n",
     "X = grid_sample[\"sigma1\"]\n",
     "Y = grid_sample[\"sigma2\"]\n",
     "\n",
+    "plt.rcdefaults()\n",
     "use_mpl_latex_fonts()\n",
     "plt.rc(\"font\", size=18)\n",
     "fig, axes = plt.subplots(\n",
     "    dpi=200,\n",
-    "    figsize=(17, 6),\n",
+    "    figsize=(20, 6),\n",
     "    ncols=3,\n",
-    "    tight_layout=True,\n",
     "    sharey=True,\n",
     "    gridspec_kw={\"width_ratios\": [1, 1, 1.21]},\n",
     ")\n",
-    "global_max = max(map(jnp.nanmax, intensity_grids.values()))\n",
+    "normalized_intensities = {i: I / jnp.nansum(I) for i, I in intensity_grids.items()}\n",
+    "global_max = max(map(jnp.nanmax, normalized_intensities.values()))\n",
     "axes[0].set_ylabel(s2_label)\n",
-    "for i, ax in enumerate(axes, 1):\n",
-    "    ax.set_title(f\"Sub-system {i} as reference\")\n",
+    "subsystem_names = [\"K\", \"L\", \"D\"]\n",
+    "for i, (ax, name) in enumerate(zip(axes, subsystem_names), 1):\n",
     "    ax.set_xlabel(s1_label)\n",
-    "    Z = intensity_grids[i]\n",
+    "    ax.set_box_aspect(1)\n",
+    "    Z = normalized_intensities[i]\n",
     "    mesh = ax.pcolormesh(X, Y, Z)\n",
     "    mesh.set_clim(vmax=global_max)\n",
     "    if ax is axes[-1]:\n",
-    "        c_bar = fig.colorbar(mesh, ax=ax, pad=0.02)\n",
-    "        c_bar.ax.set_ylabel(\"Intensity\")\n",
+    "        c_bar = fig.colorbar(mesh, ax=ax)\n",
+    "        c_bar.ax.set_ylabel(\"Normalized intensity\")\n",
+    "    overlay_inset(\n",
+    "        f\"../_images/orientation-{name}.png\",\n",
+    "        ax=ax,\n",
+    "        position=(1.05, 3.85),\n",
+    "        width=0.75,\n",
+    "    )\n",
+    "fig.subplots_adjust(wspace=0)\n",
+    "\n",
     "plt.show()"
    ]
   }

docs/conf.py

@@ -8,6 +8,36 @@
 from _relink_references import relink_references
 
 
+def download_figure_1() -> str:
+    files = [
+        "figure1.svg",
+        "figure1-inset.svg",
+    ]
+    if any(not os.path.exists(f) for f in files):
+        return ""
+    return f"""
+    High-resolution image can be downloaded here: {{download}}`{files[0]}` / {{download}}`{files[1]}`
+    """.strip()
+
+
+def download_figures_2_and_3() -> str:
+    files = [
+        "figure2.svg",
+        "figure2-inset.svg",
+        "figure3a.svg",
+        "figure3a-inset.svg",
+        "figure3b.svg",
+        "figure3b-inset.svg",
+    ]
+    if any(not os.path.exists(f) for f in files):
+        return ""
+    return f"""**Figures 2 and 3** for the paper can be downloaded here:
+    - {{download}}`{files[0]}` / {{download}}`{files[1]}`
+    - {{download}}`{files[2]}` / {{download}}`{files[3]}`
+    - {{download}}`{files[4]}` / {{download}}`{files[5]}`
+    """.strip()
+
+
 def download_intensity_distribution() -> str:
     filename = "intensity-distribution.png"
     if not os.path.exists(filename):
@@ -162,6 +192,8 @@ def generate_api() -> None:
 myst_render_markdown_format = "myst"
 myst_substitutions = {
     "LINK_TO_JULIA_PAGES": get_link_to_julia_pages(),
+    "download_figure_1": download_figure_1(),
+    "download_figures_2_and_3": download_figures_2_and_3(),
     "download_intensity_distribution": download_intensity_distribution(),
 }
 nb_execution_allow_errors = False

docs/polarization.ipynb

@@ -696,7 +696,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "**Figure 1** for the paper can be downloaded here: {download}`figure1.svg` / {download}`figure1-inset.svg`"
+    "{{ download_figure_1 }}"
    ]
   },
   {
@@ -756,7 +756,7 @@
     "\n",
     "\n",
     "plot_figure(\"figure1.svg\")\n",
-    "overlay_inset(\"figure1.svg\", \"_images/orientation-p.svg\", \"figure1-inset.svg\")"
+    "overlay_inset(\"figure1.svg\", \"_images/orientation-K.svg\", \"figure1-inset.svg\")"
    ]
   },
   {
@@ -911,10 +911,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "**Figures 2 and 3** for the paper can be downloaded here:\n",
-    "- {download}`figure2.svg` / {download}`figure2-inset.svg`\n",
-    "- {download}`figure3a.svg` / {download}`figure3a-inset.svg`\n",
-    "- {download}`figure3b.svg` / {download}`figure3b-inset.svg`"
+    "{{ download_figures_2_and_3 }}"
    ]
   },
   {
@@ -959,7 +956,7 @@
     "\n",
     "\n",
     "plot_figure(\"figure2.svg\")\n",
-    "overlay_inset(\"figure2.svg\", \"_images/orientation-p.svg\", \"figure2-inset.svg\")"
+    "overlay_inset(\"figure2.svg\", \"_images/orientation-K.svg\", \"figure2-inset.svg\")"
    ]
   },
   {
@@ -1005,10 +1002,10 @@
     "\n",
     "\n",
     "plot_figure(\"figure3a.svg\", reference_subsystem=1)\n",
-    "overlay_inset(\"figure3a.svg\", \"_images/orientation-p.svg\", \"figure3a-inset.svg\")\n",
+    "overlay_inset(\"figure3a.svg\", \"_images/orientation-K.svg\", \"figure3a-inset.svg\")\n",
     "\n",
     "plot_figure(\"figure3b.svg\", reference_subsystem=2, right_side=True)\n",
-    "overlay_inset(\"figure3b.svg\", \"_images/orientation-pi.svg\", \"figure3b-inset.svg\")"
+    "overlay_inset(\"figure3b.svg\", \"_images/orientation-L.svg\", \"figure3b-inset.svg\")"
    ]
   }
  ],

setup.cfg

@@ -24,6 +24,7 @@ package_dir =
 
 [options.extras_require]
 doc =
+    cairosvg
     ipywidgets
     matplotlib
     myst-nb >=0.14  # nb_render_markdown_format for Markdown tables