DOC: add expression for weighted NLL (#221)

* DOC: add expression for weighted NLL
* DOC: merge note on alpha computation into main text
* DOC: recommend installing `make` for `tox -e pdf` job
* DX: set correct wrapping size for commit messages
  With this, one can easily wrap the body of a commit message to the
  convention of 72 characters per line with Alt+Q when editing the
  commit message in VSCode.
* FIX: remove duplicate PNG output from LaTeX build
  When the matplotlib backend is png (the default), matplotlib cell does
  correctly rendering in the LaTeX PDF build, so there is no need to
  save and embed them separately with the `only` directive.

.vscode/settings.json

@@ -1,4 +1,7 @@
 {
+  "[git-commit]": {
+    "rewrap.wrappingColumn": 72
+  },
   "[json]": {
     "editor.defaultFormatter": "esbenp.prettier-vscode"
   },

README.md

@@ -42,7 +42,7 @@ sudo apt install -y cm-super dvipng texlive-latex-extra
 In addition, for [building the documentation as a single PDF file](#building-the-documentation), you need to install XeTeX:
 
 ```shell
-sudo apt install -y inkscape latexmk texlive-fonts-extra texlive-xetex xindy
+sudo apt install -y inkscape latexmk make texlive-fonts-extra texlive-xetex xindy
 ```
 
 <!-- cspell:ignore xetex -->

docs/appendix/polarization-fit.ipynb

@@ -17,7 +17,9 @@
     "I\\left(\\phi,\\theta,\\chi; \\tau\\right) = I_0(\\tau)\\left(1+\\vec{P} R(\\phi,\\theta,\\chi) \\vec{\\alpha}(\\tau)\\right)\n",
     "$$ (eq:master.intensity)\n",
     "\n",
-    "with $R$ the rotation matrix over the decay plane orientation, represented in Euler angles $\\left(\\phi, \\theta, \\chi\\right)$. In this section, we show that it's possible to determine the polarization $\\vec{P}$ from a given toy study intensity distribution $I$."
+    "with $R$ the rotation matrix over the decay plane orientation, represented in Euler angles $\\left(\\phi, \\theta, \\chi\\right)$.\n",
+    "\n",
+    "In this section, we show that it's possible to determine the polarization $\\vec{P}$ from a given intensity distribution $I$ of a $\\lambda_c$ decay if we the $\\vec\\alpha$ fields and the corresponding $I_0$ values of that $\\Lambda_c$ decay. In this example, the intensity and alpha functions are computed from exact amplitude models, but they can be substituted by functions that interpolate the exported polarimeter fields from {ref}`uncertainties:Exported distributions` over a phase space sample. This would remove the need to formulate a complete amplitude model in order to determine polarization. See {ref}`appendix/serialization:Import and interpolate` for how to interpolate these exported distributions over the Dalitz plane."
    ]
   },
   {
@@ -275,32 +277,35 @@
     "axes[0].set_xlabel(R\"$\\phi$\")\n",
     "axes[1].set_xlabel(R\"$\\cos\\theta$\")\n",
     "axes[2].set_xlabel(R\"$\\chi$\")\n",
-    "fig.savefig(\"../_static/images/polarization-fit-euler-distribution.png\", dpi=200)\n",
     "plt.show()\n",
     "\n",
     "fig, ax = plt.subplots(figsize=(12, 3))\n",
     "ax.hist2d(PHSP[\"sigma2\"], PHSP[\"sigma1\"], weights=I, bins=100, cmin=1)\n",
     "ax.set_xlabel(R\"$\\sigma_2$\")\n",
     "ax.set_ylabel(R\"$\\sigma_1$\")\n",
     "ax.set_aspect(\"equal\")\n",
-    "fig.savefig(\"../_static/images/polarization-fit-dalitz-distribution.png\", dpi=200)\n",
     "plt.show()"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    ":::{only} latex\n",
-    "![](../_static/images/polarization-fit-dalitz-distribution.png)\n",
-    "![](../_static/images/polarization-fit-euler-distribution.png)\n",
-    ":::\n",
+    "The generated distribution is now assumed to be a _measured distribution_ $I$ with unknown polarization $\\vec{P}$. It is shown below that the actual $\\vec{P}$ with which the distribution was generated can be found by performing a fit on Eq. {eq}`eq:master.intensity`. This is done with [`iminuit`](https://iminuit.rtfd.io), starting with a certain 'guessed' value for $\\vec{P}$ as initial parameters.\n",
+    "\n",
+    "To avoid having to generate a hit-and-miss intensity test distribution, the parameters $\\vec{P} = \\left(P_x, P_y, P_z\\right)$ are optimized with regard to a **weighted negative log likelihood estimator**:\n",
+    "\n",
+    "$$\n",
+    "\\mathrm{NLL} = -\\sum_i w_i \\log I_{i,\\vec{P}}\\left(\\phi,\\theta,\\chi;\\tau\\right)\\,.\n",
+    "$$ (eq:weighted-nll)\n",
+    "\n",
+    "with the normalized intensities of the generated distribution taken as weights:\n",
     "\n",
-    ":::{note}\n",
-    "In this example, the intensity and alpha functions are exact amplitude models, but they can be substituted by the **interpolation functions** that use the exported polarimeter fields from {ref}`uncertainties:Exported distributions` as input.  This removes the need to formulate a complete amplitude model in order to determine polarization. See {ref}`appendix/serialization:Import and interpolate` for how to interpolate these exported distributions over the Dalitz plane.\n",
-    ":::\n",
+    "$$\n",
+    "w_i = n\\,I_i\\,\\big/\\,\\sum_j^n I_j\\,,\n",
+    "$$ (eq:intensity-as-nll-weight)\n",
     "\n",
-    "The distribution is assumed to be a measured distribution where $\\vec{P}$ is unknown. It is shown below that the actual $\\vec{P}$ with which the distribution was generated can be found by performing a fit on Eq. {eq}`eq:master.intensity`. This is done with [`iminuit`](https://iminuit.rtfd.io), starting with a certain 'guessed' value for $\\vec{P}$ as initial parameters."
+    "such that $\\sum w_i = n$."
    ]
   },
   {