fix: text in notebook

Author: jokasimr

docs/user-guide/dream/dream-visualize-absorption.ipynb

@@ -7,14 +7,11 @@
    "source": [
     "# DREAM instrument view\n",
     "\n",
-    "This notebook is a simple example of how to use the instrument view for the DREAM instrument.\n",
+    "This notebook is an example of how to use the `compute_transmission_map` function to visualize the effect of (sample) absorption on the intensity in the detector.\n",
     "\n",
-    "- The DREAM-specific instrument view is capable of slicing the data with a slider widget along a dimension (e.g. `tof`) by using the `dim` argument.\n",
-    "- There are also checkboxes to hide/show the different elements that make up the DREAM detectors.\n",
+    "Note that the `compute_transmission_map` function only accounts for the effect of absorption. The measured intensity in the detector can also be impacted by other effects, such as the effect of the solid angle being different for different detector pixels.\n",
     "\n",
-    "We begin with relevant imports.\n",
-    "We will be using tutorial data downloaded with `pooch`.\n",
-    "If you get an error about a missing module `pooch`, you can install it with `!pip install pooch`:"
+    "For more details, see https://scipp.github.io/scippneutron/user-guide/absorption-correction.html."
    ]
   },
   {
@@ -25,8 +22,16 @@
    "outputs": [],
    "source": [
     "import scipp as sc\n",
+    "\n",
+    "from plopp.graphics import Camera\n",
+    "\n",
     "from ess import dream\n",
-    "import ess.dream.data  # noqa: F401"
+    "import ess.dream.data  # noqa: F401\n",
+    "\n",
+    "from scippneutron.absorption import compute_transmission_map\n",
+    "from scippneutron.absorption.cylinder import Cylinder\n",
+    "from scippneutron.absorption.material import Material\n",
+    "from scippneutron.atoms import ScatteringParams"
    ]
   },
   {
@@ -36,9 +41,7 @@
    "source": [
     "## Load the data\n",
     "\n",
-    "We load a dataset from a Geant4 simulation (stored as a `.csv` file).\n",
-    "In each detector bank, the data is organised by `wire`, `strip`, `module`, `segment`, and `counter`.\n",
-    "The high resolution detector also has an additional `sector` dimension."
+    "We load a dataset from a Geant4 simulation only to get access to the detector geometry."
    ]
   },
   {
@@ -48,10 +51,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "dg = dream.io.load_geant4_csv(dream.data.get_path(\"data_dream0_new_hkl_Si_pwd.csv.zip\"))\n",
-    "dg = dg[\"instrument\"]  # Extract the instrument data\n",
-    "\n",
-    "# Extract the events from nested data groups\n",
+    "dg = dream.io.load_geant4_csv(dream.data.get_path(\"data_dream0_new_hkl_Si_pwd.csv.zip\"))[\"instrument\"]\n",
     "dg = sc.DataGroup({key: detector[\"events\"] for key, detector in dg.items()})\n",
     "dg"
    ]
@@ -63,7 +63,7 @@
    "source": [
     "## Display inhomogeneity from absorption\n",
     "\n",
-    "If the sample absorbs or scatters a large fraction of the incoming neutrons the intensity in the detector will vary even if the scattering is inhomogeneous.\n"
+    "If the sample absorbs or scatters a large fraction of the incoming neutrons, the intensity in the detector will vary even if the scattering is inhomogeneous.\n"
    ]
   },
   {
@@ -73,46 +73,77 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import scipp as sc\n",
-    "\n",
-    "from scippneutron.absorption import compute_transmission_map\n",
-    "from scippneutron.absorption.cylinder import Cylinder\n",
-    "from scippneutron.absorption.material import Material\n",
-    "from scippneutron.atoms import ScatteringParams\n",
-    "\n",
-    "\n",
     "material =  Material(\n",
     "    scattering_params=ScatteringParams.for_isotope('V'),\n",
     "    effective_sample_number_density=sc.scalar(0.07192, unit='1/angstrom**3')\n",
     ")\n",
     "sample_shape = Cylinder(\n",
-    "    symmetry_line=sc.vector([0, 1, 0]),\n",
-    "    center_of_base=sc.vector([0, -2.5, 0], unit='cm'),\n",
     "    radius=sc.scalar(1, unit='cm'),\n",
-    "    height=sc.scalar(5., unit='cm')\n",
-    ")\n",
-    "\n",
-    "transmission_fraction = compute_transmission_map(\n",
+    "    height=(height := sc.scalar(5., unit='cm')),\n",
+    "    # Cylinder is oriented along the x-axis\n",
+    "    symmetry_line=(symmetry_line := sc.vector([1, 0, 0])),\n",
+    "    center_of_base=-height * symmetry_line / 2,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "transmission_fraction_mantle = compute_transmission_map(\n",
     "    sample_shape,\n",
     "    material,\n",
     "    beam_direction=sc.vector([0, 0, 1]),\n",
     "    wavelength=sc.linspace('wavelength', 4, 8, 20, unit='angstrom'),\n",
+    "    # To make it faster, don't compute the transmission fraction for every detector pixel, it's not necessary for the visualization.\n",
     "    detector_position=dg['mantle'].coords['position']['strip', ::4]['wire', ::2].copy(),\n",
     "    quadrature_kind='cheap',\n",
     ")\n",
     "\n",
-    "transmission_fraction.coords['position'] = transmission_fraction.coords.pop('detector_position')\n",
-    "dream.instrument_view(transmission_fraction.transpose((*set(transmission_fraction.dims) - {'wavelength'}, 'wavelength')), dim='wavelength')"
+    "# The visualization expects the `position` coord to denote detector positions, and `wavelength` to be the last dimension.\n",
+    "transmission_fraction_mantle.coords['position'] = transmission_fraction_mantle.coords.pop('detector_position')\n",
+    "dream.instrument_view(transmission_fraction_mantle.transpose((*set(transmission_fraction_mantle.dims) - {'wavelength'}, 'wavelength')), dim='wavelength', camera=Camera(position=sc.vector((-1.5, 1.5, -1.5), unit='m'), look_at=sc.vector((1, -1/3, 1/2), unit='m')))"
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "6",
+   "id": "7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "transmission_fraction_mantle"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8",
    "metadata": {},
    "outputs": [],
    "source": [
-    "transmission_fraction"
+    "transmission_fraction_endcap = compute_transmission_map(\n",
+    "    sample_shape,\n",
+    "    material,\n",
+    "    beam_direction=sc.vector([0, 0, 1]),\n",
+    "    wavelength=sc.linspace('wavelength', 4, 8, 20, unit='angstrom'),\n",
+    "    detector_position=dg['endcap_backward'].coords['position']['strip', 0].copy(),\n",
+    "    quadrature_kind='cheap',\n",
+    ")\n",
+    "\n",
+    "transmission_fraction_endcap.coords['position'] = transmission_fraction_endcap.coords.pop('detector_position')\n",
+    "dream.instrument_view(transmission_fraction_endcap.transpose((*set(transmission_fraction_endcap.dims) - {'wavelength'}, 'wavelength')), dim='wavelength', camera=Camera(position=sc.vector((-1, 1, -3), unit='m'), look_at=sc.vector((0.3, -0.3, 1), unit='m')))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9",
+   "metadata": {},
+   "source": [
+    "As expected the impact of absorption on the inhomgenity of the intensity is not nearly as large for the endcap detector as it is for the mantle detector."
    ]
   }
  ],