From ec6f9ada9691759e84bee2a65c628bb5bc5509ff Mon Sep 17 00:00:00 2001
From: gvarnavi <gvarnavi@mit.edu>
Date: Mon, 29 Jul 2024 08:58:36 -0700
Subject: [PATCH] adding ctf, psf widget

---
 05_algorithms.md                  |  29 ---
 07_CTF.md                         |  10 +-
 environment.yml                   |   1 +
 figures/ctf_psf.png               | Bin 0 -> 28988 bytes
 notebooks/07_ctf_psf_widget.ipynb | 404 ++++++++++++++++++++++++++++++
 5 files changed, 413 insertions(+), 31 deletions(-)
 create mode 100644 figures/ctf_psf.png
 create mode 100644 notebooks/07_ctf_psf_widget.ipynb

diff --git a/05_algorithms.md b/05_algorithms.md
index a1253e5..878c280 100644
--- a/05_algorithms.md
+++ b/05_algorithms.md
@@ -267,32 +267,3 @@ I(\bm{R},n)
 ```
 where $\theta$ is the annular coordinate and $k'$ is the radial coordinate for $\bm{k}$-space.
 
-
-
-(bloch-wave-method)=
-### The Bloch Wave Method
-
-text
-
-
-(prism-method)=
-### PRISM
-
-text
-
-
-(other-method)=
-### Other Methods
-
-text
-
-
-
-<!-- ```{figure} #app:fft_1d
-
-```
-
-```{figure} #app:probe_size
-
-```
- -->
\ No newline at end of file
diff --git a/07_CTF.md b/07_CTF.md
index 967d279..93fe7bf 100644
--- a/07_CTF.md
+++ b/07_CTF.md
@@ -16,7 +16,7 @@ This deviation is typically expressed as a phase error or the aberration functio
 
 Another, possibly more intuitive way of framing the phase error is the point spread function 
 ```{math}
-    \mathrm{PSF}(\bm{r}) = F \mathrm{e} ^ {-i \chi(\bm{k})} ,
+    \mathrm{PSF}(\bm{r}) = \mathscr{F}^{-1}_{\bm{k} \rightarrow \bm{r}}\left\{ \mathrm{e} ^ {-i \chi(\bm{k})} \right\} ,
 ```
 the point spread function describes how an imaging system responds to a point source. In STEM, the PSF would be the image of the probe, given an infinite objective aperture, in HRTEM the PSF would be how a perfect point source is imaged by an objective lens with an infinite collection angle.  
 
@@ -30,4 +30,10 @@ For an uncorrected microscope the dominant aberration is ther third order spheri
 ```{math}
     \chi(k) \approx \frac{2\pi}{\lambda}\left( \frac{\lambda^2 k^2}{2} \Delta f + \frac{\lambda^4 k^4}{4} C_s \right) \quad .
 ```
-Here we used the common aliases of the aberration coefficients, so $C10 = -\Delta f$ is the negative defocus and $C_{30} = C_s$ is the third order spherical aberration. 
\ No newline at end of file
+Here we used the common aliases of the aberration coefficients, so $C10 = -\Delta f$ is the negative defocus and $C_{30} = C_s$ is the third order spherical aberration. 
+
+```{figure} #app:ctf_psf
+:name: fig_ctf_psf
+:placeholder: ./figures/ctf_psf.png
+**Interactive widget showing the influence of common aberrations on the point spread function (PSF) and contact transfer function (CTF) **: 
+```
diff --git a/environment.yml b/environment.yml
index 6a5d498..f8e9257 100644
--- a/environment.yml
+++ b/environment.yml
@@ -7,6 +7,7 @@ dependencies:
   - scipy
   - h5py
   - matplotlib
+  - colorspacious
   - abtem
   - ipywidgets
   - jupyterlab
diff --git a/figures/ctf_psf.png b/figures/ctf_psf.png
new file mode 100644
index 0000000000000000000000000000000000000000..7036643d657c21477626d3827b1dc785ee69ecd4
GIT binary patch
literal 28988
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

literal 0
HcmV?d00001

diff --git a/notebooks/07_ctf_psf_widget.ipynb b/notebooks/07_ctf_psf_widget.ipynb
new file mode 100644
index 0000000..4428102
--- /dev/null
+++ b/notebooks/07_ctf_psf_widget.ipynb
@@ -0,0 +1,404 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "d8b4092d-2746-469e-80d2-f6772c84fe72",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "title: Interactive CTF/PSF\n",
+    "authors: [Stephanie Ribet, Georgios Varnavides]\n",
+    "date: 2024/07/29\n",
+    "---"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "f6f34ef2-57c9-449a-a57c-e7c04e642fb4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%matplotlib widget\n",
+    "import numpy as np\n",
+    "import abtem\n",
+    "\n",
+    "from matplotlib import cm, colors as mcolors, pyplot as plt\n",
+    "import numpy as np\n",
+    "from mpl_toolkits.axes_grid1 import make_axes_locatable\n",
+    "from colorspacious import cspace_convert\n",
+    "\n",
+    "from IPython.display import display\n",
+    "import ipywidgets"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 40,
+   "id": "c5af5325-bb12-4499-a9ea-ff202c6167be",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def Complex2RGB(complex_data, vmin=None, vmax=None, power=None, chroma_boost=1):\n",
+    "    \"\"\"\n",
+    "    complex_data (array): complex array to plot\n",
+    "    vmin (float)        : minimum absolute value\n",
+    "    vmax (float)        : maximum absolute value\n",
+    "    power (float)       : power to raise amplitude to\n",
+    "    chroma_boost (float): boosts chroma for higher-contrast (~1-2.5)\n",
+    "    \"\"\"\n",
+    "    amp = np.abs(complex_data)\n",
+    "    phase = np.angle(complex_data)\n",
+    "\n",
+    "    if power is not None:\n",
+    "        amp = amp**power\n",
+    "\n",
+    "    if np.isclose(np.max(amp), np.min(amp)):\n",
+    "        if vmin is None:\n",
+    "            vmin = 0\n",
+    "        if vmax is None:\n",
+    "            vmax = np.max(amp)\n",
+    "    else:\n",
+    "        if vmin is None:\n",
+    "            vmin = 0.02\n",
+    "        if vmax is None:\n",
+    "            vmax = 0.98\n",
+    "        vals = np.sort(amp[~np.isnan(amp)])\n",
+    "        ind_vmin = np.round((vals.shape[0] - 1) * vmin).astype(\"int\")\n",
+    "        ind_vmax = np.round((vals.shape[0] - 1) * vmax).astype(\"int\")\n",
+    "        ind_vmin = np.max([0, ind_vmin])\n",
+    "        ind_vmax = np.min([len(vals) - 1, ind_vmax])\n",
+    "        vmin = vals[ind_vmin]\n",
+    "        vmax = vals[ind_vmax]\n",
+    "\n",
+    "    amp = np.where(amp < vmin, vmin, amp)\n",
+    "    amp = np.where(amp > vmax, vmax, amp)\n",
+    "    amp = ((amp - vmin) / vmax).clip(1e-16, 1)\n",
+    "\n",
+    "    J = amp * 61.5  # Note we restrict luminance to the monotonic chroma cutoff\n",
+    "    C = np.minimum(chroma_boost * 98 * J / 123, 110)\n",
+    "    h = np.rad2deg(phase) + 180\n",
+    "\n",
+    "    JCh = np.stack((J, C, h), axis=-1)\n",
+    "    rgb = cspace_convert(JCh, \"JCh\", \"sRGB1\").clip(0, 1)\n",
+    "\n",
+    "    return rgb\n",
+    "\n",
+    "\n",
+    "def add_colorbar_arg(ax, chroma_boost=1, c=49, j=61.5):\n",
+    "    \"\"\"\n",
+    "    cax                 : axis to add cbar to\n",
+    "    chroma_boost (float): boosts chroma for higher-contrast (~1-2.25)\n",
+    "    c (float)           : constant chroma value\n",
+    "    j (float)           : constant luminance value\n",
+    "    \"\"\"\n",
+    "\n",
+    "    divider = make_axes_locatable(ax)\n",
+    "    cax = divider.append_axes(\"right\", size=\"5%\", pad=\"2.5%\")\n",
+    "    \n",
+    "    h = np.linspace(0, 360, 256, endpoint=False)\n",
+    "    J = np.full_like(h, j)\n",
+    "    C = np.full_like(h, np.minimum(c * chroma_boost, 110))\n",
+    "    JCh = np.stack((J, C, h), axis=-1)\n",
+    "    rgb_vals = cspace_convert(JCh, \"JCh\", \"sRGB1\").clip(0, 1)\n",
+    "    newcmp = mcolors.ListedColormap(rgb_vals)\n",
+    "    norm = mcolors.Normalize(vmin=-np.pi, vmax=np.pi)\n",
+    "\n",
+    "    cb = plt.colorbar(cm.ScalarMappable(norm=norm, cmap=newcmp), cax=cax)\n",
+    "\n",
+    "    cb.set_label(\"arg\", rotation=0, ha=\"center\", va=\"bottom\")\n",
+    "    cb.ax.yaxis.set_label_coords(0.5, 1.01)\n",
+    "    cb.set_ticks(np.array([-np.pi, -np.pi / 2, 0, np.pi / 2, np.pi]))\n",
+    "    cb.set_ticklabels(\n",
+    "        [r\"$-\\pi$\", r\"$-\\dfrac{\\pi}{2}$\", \"$0$\", r\"$\\dfrac{\\pi}{2}$\", r\"$\\pi$\"]\n",
+    "    )\n",
+    "    return None"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 59,
+   "id": "33a64997-5076-4526-b701-71e85e04bbb1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "probe_init = abtem.Probe(\n",
+    "    energy=300*1e3,\n",
+    "    semiangle_cutoff=25,\n",
+    "    gpts=(256,256),\n",
+    "    sampling=0.4,\n",
+    ").build()\n",
+    "\n",
+    "ctf = abtem.CTF(\n",
+    "    energy=300*1e3,\n",
+    "    semiangle_cutoff=25,\n",
+    "    defocus=100,\n",
+    ")\n",
+    "\n",
+    "probe = probe_init.apply_ctf(ctf)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 67,
+   "id": "f83e7c71-e8e1-4a64-a746-522eedeee990",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "/tmp/ipykernel_33501/13827917.py:9: RuntimeWarning: More than 20 figures have been opened. Figures created through the pyplot interface (`matplotlib.pyplot.figure`) are retained until explicitly closed and may consume too much memory. (To control this warning, see the rcParam `figure.max_open_warning`). Consider using `matplotlib.pyplot.close()`.\n",
+      "  fig, (ax_ctf,ax_psf) = plt.subplots(1,2,figsize=(675/dpi, 300/dpi), dpi=dpi)\n"
+     ]
+    }
+   ],
+   "source": [
+    "array = probe.array.compute()\n",
+    "array_fourier = np.fft.fftshift(np.fft.fft2(np.fft.ifftshift(array)))\n",
+    "rgb_psf = Complex2RGB(array,vmin=0,vmax=1)\n",
+    "rgb_ctf = Complex2RGB(array_fourier,vmin=0,vmax=1)\n",
+    "\n",
+    "# widget figure generation\n",
+    "with plt.ioff():\n",
+    "    dpi = 72\n",
+    "    fig, (ax_ctf,ax_psf) = plt.subplots(1,2,figsize=(675/dpi, 300/dpi), dpi=dpi)\n",
+    "\n",
+    "im_ctf = ax_ctf.imshow(rgb_ctf)\n",
+    "im_psf = ax_psf.imshow(rgb_psf)\n",
+    "\n",
+    "for ax, title in zip((ax_ctf,ax_psf),['contrast transfer function (CTF)','point spread function (PSF)']):\n",
+    "    ax.set_xticks([])\n",
+    "    ax.set_yticks([])\n",
+    "    add_colorbar_arg(ax)\n",
+    "    ax.set_title(title)\n",
+    "\n",
+    "fig.tight_layout()\n",
+    "\n",
+    "fig.canvas.resizable = False\n",
+    "fig.canvas.header_visible = False\n",
+    "fig.canvas.footer_visible = False\n",
+    "fig.canvas.toolbar_visible = True\n",
+    "fig.canvas.layout.width = '675px'\n",
+    "fig.canvas.layout.height = '330px'\n",
+    "fig.canvas.toolbar_position = 'bottom'"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 68,
+   "id": "4db48b85-be46-4743-8e10-5b9b0ea83ee0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def update_aberrations(energy, defocus, C30, semiangle):\n",
+    "\n",
+    "    ctf = abtem.CTF(\n",
+    "        energy=energy*1e3, \n",
+    "        semiangle_cutoff = semiangle,\n",
+    "        defocus =  defocus,\n",
+    "        C30 =  C30*1e7,\n",
+    "    )\n",
+    "\n",
+    "    probe_init = abtem.Probe(\n",
+    "        energy=energy*1e3,\n",
+    "        semiangle_cutoff=semiangle,\n",
+    "        gpts=(256,256),\n",
+    "        sampling=0.4,\n",
+    "    ).build()\n",
+    "    \n",
+    "    probe = probe_init.apply_ctf(ctf)\n",
+    "    array = probe.array.compute()\n",
+    "    array_fourier = np.fft.fftshift(np.fft.fft2(np.fft.ifftshift(array)))\n",
+    "    rgb_psf = Complex2RGB(array,vmin=0,vmax=1)\n",
+    "    rgb_ctf = Complex2RGB(array_fourier,vmin=0,vmax=1)\n",
+    "    \n",
+    "    im_ctf.set_data(rgb_ctf)\n",
+    "    im_psf.set_data(rgb_psf)\n",
+    "    fig.canvas.draw_idle()\n",
+    "    return None"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 69,
+   "id": "7ad86424-7685-456e-b02e-6a4543213849",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# List of options\n",
+    "option_list = (\n",
+    "    'select an option',\n",
+    "    'uncorrected STEM',\n",
+    "    'uncorrected STEM at Scherzer',\n",
+    "    'aberration corrected STEM',\n",
+    "    'SEM',\n",
+    "    'boundary artifacts', \n",
+    ")\n",
+    "\n",
+    "# update the plots with a pre-selected function\n",
+    "def select_preset_eventhandler(change):\n",
+    "    if change.new == option_list[1]: #uncorrected STEM\n",
+    "        energy.value = 300\n",
+    "        defocus.value = 0\n",
+    "        C30.value = 1.3\n",
+    "        semiangle.value = 10\n",
+    "    \n",
+    "    if change.new == option_list[2]: #uncorrected STEM @ Scherzer\n",
+    "        #calculate scherzer \n",
+    "        lambda_300kv = abtem.core.energy.energy2wavelength(300e3)\n",
+    "        C1_Scherzer = 0.87 * (1.3e7*lambda_300kv) ** 0.5 \n",
+    "        \n",
+    "        energy.value = 300\n",
+    "        defocus.value = C1_Scherzer\n",
+    "        C30.value = 1.3\n",
+    "        semiangle.value = 10\n",
+    "        \n",
+    "    if change.new == option_list[3]: #corrected STEM\n",
+    "        energy.value = 300\n",
+    "        defocus.value = 0\n",
+    "        C30.value = 0.001\n",
+    "        semiangle.value = 10\n",
+    "    \n",
+    "    if change.new == option_list[4]: #SEM\n",
+    "        energy.value = 20\n",
+    "        defocus.vaue = 0\n",
+    "        C30.value = 5\n",
+    "        semiangle.value = 2.5\n",
+    "    \n",
+    "    if change.new == option_list[5]: #artifacts\n",
+    "        energy.value = 10\n",
+    "        defocus.value = 2000\n",
+    "        C30.value = 0\n",
+    "        semiangle.value = 20     \n",
+    "            \n",
+    "# Widgets\n",
+    "dropdown = ipywidgets.Dropdown(\n",
+    "    options = option_list,\n",
+    "    layout = ipywidgets.Layout(width='200px',height='30px'),\n",
+    ")\n",
+    "dropdown.observe(select_preset_eventhandler, names='value')\n",
+    "\n",
+    "style = {\n",
+    "    'description_width': 'initial',\n",
+    "}\n",
+    "\n",
+    "energy = ipywidgets.IntSlider(\n",
+    "    value=60, min=10, max=300, \n",
+    "    step = 2,\n",
+    "    description = \"energy (kV)\",\n",
+    "    style = style,\n",
+    ")\n",
+    "\n",
+    "defocus = ipywidgets.IntSlider(\n",
+    "    value = 0, min = -2000, max = 2000, \n",
+    "    step = 20,\n",
+    "    description = \"defocus / -1*C1 (A)\",\n",
+    "    style = style\n",
+    ")\n",
+    "\n",
+    "C30 = ipywidgets.FloatSlider(\n",
+    "    value = 0, min = 0, max =5, \n",
+    "    step = 0.1,\n",
+    "    description = \"C3 (mm)\",\n",
+    "    style = style\n",
+    ")\n",
+    "\n",
+    "semiangle = ipywidgets.FloatLogSlider(\n",
+    "    value=20,\n",
+    "    base=10,\n",
+    "    min=0, # min exponent of base\n",
+    "    max=1.6021, # max exponent of base\n",
+    "    step=0.05, # exponent step\n",
+    "    description = \"semiangle (mrad)\",\n",
+    "    style = style,\n",
+    ")\n",
+    "\n",
+    "ipywidgets.interactive_output(\n",
+    "    update_aberrations, \n",
+    "    {\n",
+    "        'energy':energy,\n",
+    "        'defocus':defocus,\n",
+    "        'semiangle':semiangle,\n",
+    "        'C30':C30,\n",
+    "    },\n",
+    ")\n",
+    "None"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 71,
+   "id": "37ec6eba-1870-48c0-82c3-882c310c553b",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "0a02f03f4d75477e9ccf81621b12aab7",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "VBox(children=(Canvas(footer_visible=False, header_visible=False, layout=Layout(height='330px', width='675px')…"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "#| label: app:ctf_psf\n",
+    "\n",
+    "widget = ipywidgets.VBox(\n",
+    "    [\n",
+    "        fig.canvas,\n",
+    "        ipywidgets.HBox([\n",
+    "            ipywidgets.VBox([\n",
+    "                energy,\n",
+    "                defocus,\n",
+    "                semiangle,\n",
+    "                C30,  \n",
+    "            ]),\n",
+    "            ipywidgets.VBox([\n",
+    "                ipywidgets.Label('Preset probes',layout=ipywidgets.Layout(width='100px',height='30px')), \n",
+    "                dropdown,\n",
+    "            ])\n",
+    "        ]),\n",
+    "    ],\n",
+    ")\n",
+    "\n",
+    "display(widget);"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "44634d55-85d4-40f8-a32b-da5817fb1d2d",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}