Add DREAM instrument view

docs/api-reference/index.md

@@ -29,4 +29,29 @@
    uncertainty
 
    external.powgen
-```
+```
+
+## ESSdream
+
+### Top-level functions
+
+```{eval-rst}
+.. currentmodule:: ess.dream
+
+.. autosummary::
+   :toctree: ../generated/functions
+
+   instrument_view
+```
+
+### Submodules
+
+```{eval-rst}
+.. autosummary::
+   :toctree: ../generated/modules
+   :template: module-template.rst
+   :recursive:
+
+   data
+   io
+```

docs/conf.py

@@ -130,7 +130,7 @@
     'Thumbs.db',
     '.DS_Store',
     '**.ipynb_checkpoints',
-    'examples/preprocess_files.ipynb',
+    'user-guide/sns-instruments/preprocess_files.ipynb',
 ]
 
 # The name of the Pygments (syntax highlighting) style to use.

docs/index.md

@@ -10,7 +10,7 @@
 hidden:
 ---
 
-examples/index
+user-guide/index
 api-reference/index
 developer/index
 about/index

docs/user-guide/dream/dream-instrument-view.ipynb

@@ -0,0 +1,254 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "4852fe41-3f9a-4cdb-8aba-ff7c7f198e6c",
+   "metadata": {},
+   "source": [
+    "# DREAM instrument view\n",
+    "\n",
+    "This notebook is a simple example of how to use the instrument view for the DREAM instrument.\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."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3f416595-83b4-44d1-b506-9ba73bf0786e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import scipp as sc\n",
+    "from ess import dream"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "228a23dc-17f2-4273-a4c9-3e3276db8c54",
+   "metadata": {},
+   "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."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1ef8f35b-815f-436a-80e5-cbe4b3172b58",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "dg = dream.io.load_geant4_csv(\n",
+    "    dream.data.get_path('data_dream_with_sectors.csv.zip')\n",
+    ")\n",
+    "dg = dg['instrument']  # Extract the instrument data\n",
+    "\n",
+    "# Construct the pixel positions from event positions\n",
+    "for da in dg.values():\n",
+    "    da.coords['position'] = da.bins.coords['position'].bins.mean()\n",
+    "\n",
+    "dg"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e8325797-5651-43c1-b601-3db6d4348758",
+   "metadata": {
+    "editable": true,
+    "nbsphinx": "hidden",
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "# Only plot half of the pixels to reduce html docs size\n",
+    "dg = dg['counter', 0]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "49595486-ab4e-4662-86f7-d301aedcf974",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "source": [
+    "## Full instrument view\n",
+    "\n",
+    "We first histogram the data along the time-of-flight (`tof`) dimension,\n",
+    "making sure the same bins are used for all elements:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e85a8364-e0a1-4c10-8cae-c873f297e651",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "tof_edges = sc.linspace('tof', 1.0e7, 1.0e8, 51, unit='ns', dtype=int)\n",
+    "data = dg.hist(tof=tof_edges)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d08ca911-b1a4-4f17-ba1e-355971531ffe",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "source": [
+    "We now use the `instrument_view` function to show the 3D view of the instrument pixels,\n",
+    "specifying that we wish to have a slider along the `tof` dimension:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "43f9ffbc-6bf5-4407-b3ad-5d1626efc43d",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "full_view = dream.instrument_view(data, dim='tof')\n",
+    "full_view"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a7030d56-a375-47b5-898c-28fd06c2f361",
+   "metadata": {
+    "editable": true,
+    "nbsphinx": "hidden",
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "full_view[2].controls['tof']['slider'].value = 35"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c0b29ebf-21ff-4385-bf8b-0e4fa14dfaf9",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "source": [
+    "Note that it is possible to use any dimension for the slider instead of `tof`, such as `wavelength` (if present in the data).\n",
+    "\n",
+    "## Displaying individual detector elements\n",
+    "\n",
+    "It is also possible to view a single detector element, selecting e.g. `mantle` from the original data:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b417011e-0d12-4287-91d5-c1fb6ecc7cac",
+   "metadata": {
+    "editable": true,
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "mantle_view = dream.instrument_view(dg['mantle'].hist(wavelength=50), dim='wavelength')\n",
+    "mantle_view"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "299ec404-fb18-4533-ad96-e23bf8ba24d6",
+   "metadata": {
+    "editable": true,
+    "nbsphinx": "hidden",
+    "slideshow": {
+     "slide_type": ""
+    },
+    "tags": []
+   },
+   "outputs": [],
+   "source": [
+    "mantle_view[1].controls['wavelength']['slider'].value = 43"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1df1aa56-5251-4555-a4f4-283145747198",
+   "metadata": {},
+   "source": [
+    "The instrument view is designed to be flexible in terms of what it accepts as input.\n",
+    "This means that you can easily inspect, for example, a single module by using the usual slicing notation for data arrays.\n",
+    "\n",
+    "Below, we display the first module in the backward end-cap detector:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0c86e491-3564-498d-9232-39485f5b95d7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "dream.instrument_view(dg['endcap_backward']['module', 0].hist(tof=1))"
+   ]
+  }
+ ],
+ "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.10.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/user-guide/dream/index.md

@@ -0,0 +1,9 @@
+# DREAM
+
+```{toctree}
+---
+maxdepth: 1
+---
+
+dream-instrument-view
+```

docs/user-guide/index.md

@@ -0,0 +1,10 @@
+# User guide
+
+```{toctree}
+---
+maxdepth: 1
+---
+
+dream/index
+sns-instruments/index
+```

docs/user-guide/sns-instruments/index.md

@@ -0,0 +1,12 @@
+# SNS instruments
+
+This page contains guides for reducing data from Spallation Neutron Source (SNS) instruments.
+Those instruments are not fully supported by ESSdiffraction and these pages may be removed in the future.
+
+```{toctree}
+---
+maxdepth: 1
+---
+
+POWGEN_data_reduction
+```