doc/change_navigation_signal_shapes.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": "hidden"
   },
   "source": [
    "This notebook is part of the `kikuchipy` documentation https://kikuchipy.org.\n",
    "Links to the documentation won't work from the notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Change navigation and signal shapes\n",
    "\n",
    "Patterns in an [EBSD](reference.rst#kikuchipy.signals.EBSD) or\n",
    "[EBSDMasterPattern](reference.rst#kikuchipy.signals.EBSDMasterPattern) signal\n",
    "`s` are stored in the `s.data` attribute as either [numpy.ndarray](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html) or\n",
    "[dask.array.Array](https://docs.dask.org/en/latest/array.html).\n",
    "[HyperSpy's user guide](http://hyperspy.org/hyperspy-doc/current/user_guide/signal.html#indexing)\n",
    "explains how to access, i.e. index, the data. This section details example uses\n",
    "of navigation (scan) and signal (pattern) indexing specific to EBSD and\n",
    "EBSDMasterPattern signals.\n",
    "\n",
    "Let's import the necessary libraries, a larger Nickel EBSD test data set from\n",
    "the [kikuchipy.data](reference.rst#kikuchipy.data.nickel_ebsd_large) module\n",
    "<cite data-cite=\"aanes2019electron\">Ånes et al. (2019)</cite>, and the Nickel\n",
    "master pattern, also from the data module"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# exchange inline for qt5 for interactive plotting from the pyqt package\n",
    "%matplotlib inline\n",
    "\n",
    "import hyperspy.api as hs\n",
    "import kikuchipy as kp\n",
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "\n",
    "plt.rcParams[\"font.size\"] = 15\n",
    "\n",
    "\n",
    "# Use kp.load(\"data.h5\") to load your own data\n",
    "s = kp.data.nickel_ebsd_large(allow_download=True)  # External download\n",
    "print(s)\n",
    "\n",
    "s_mp = kp.data.nickel_ebsd_master_pattern_small(hemisphere=\"both\")\n",
    "print(s_mp, s_mp.projection)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Crop the navigation or signal axes\n",
    "\n",
    "A new `EBSD` or `EBSDMasterPattern` signal `s2` can be created from a region of\n",
    "interest (ROI) in another EBSD or EBSDMasterPattern signal `s` by using\n",
    "HyperSpy's navigation indexing method ``inav``. The new signal keeps the\n",
    "`metadata` and `original_metadata` of `s`. Say we, after plotting and inspecting\n",
    "the EBSD signal, want to create a new, smaller signal of the patterns within a\n",
    "rectangle defined by the upper left pattern with index (5, 7) (column, row) and\n",
    "the bottom right pattern with index (17, 23)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s2 = s.inav[5:17, 7:23]\n",
    "s2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or, we want only the northern hemisphere of the `EBSDMasterPattern`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s_mp2 = s_mp.inav[0]\n",
    "s_mp2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Patterns can also be cropped with the signal indexing method `isig`. Say we\n",
    "wanted to remove the ten outermost pixels in our (60, 60) pixel Nickel patterns"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s3 = s.isig[10:50, 10:50]\n",
    "s3"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx-thumbnail": {
     "tooltip": "Cropping and binning the navigation (scan) and signal (detector) shapes"
    },
    "tags": [
     "nbsphinx-thumbnail"
    ]
   },
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(figsize=(13, 6), ncols=2)\n",
    "ax[0].imshow(s.inav[10, 50].data, cmap=\"gray\")\n",
    "ax[0].set_title(\"Original\")\n",
    "ax[0].axis(\"off\")\n",
    "ax[1].imshow(s3.inav[10, 50].data, cmap=\"gray\")\n",
    "ax[1].set_title(\"Cropped\")\n",
    "ax[1].axis(\"off\")\n",
    "fig.tight_layout(w_pad=-8)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Binning\n",
    "\n",
    "A new `EBSD` signal with patterns binned e.g. by 2 can be obtained using the\n",
    "[rebin()](reference.rst#kikuchipy.signals.EBSD.rebin) method provided by\n",
    "HyperSpy, explained further in\n",
    "[their user guide](http://hyperspy.org/hyperspy-doc/current/user_guide/signal.html#rebinning),\n",
    "by passing in either the `scale` or `new_shape` parameter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(s, s.data.dtype)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s4 = s.rebin(scale=(1, 1, 2, 2))\n",
    "print(s4, s4.data.dtype)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s5 = s.rebin(new_shape=(75, 55, 30, 30))\n",
    "print(s5, s5.data.dtype)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(figsize=(13, 6), ncols=2)\n",
    "ax[0].imshow(s4.inav[10, 50].data, cmap=\"gray\")\n",
    "ax[0].set_title(\"rebin() with scale\")\n",
    "ax[1].imshow(s5.inav[10, 50].data, cmap=\"gray\")\n",
    "ax[1].set_title(\"rebin() with new_shape\")\n",
    "fig.tight_layout()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that `rebin()` casts the data to `uint64`. This means that in this example,\n",
    "each pixel in the binned signals `s4` and `s5` takes up eight times the memory\n",
    "of pixels in the original signal `s` (`uint8`). To revert to `uint8` data type,\n",
    "we must rescale the intensities with\n",
    "[rescale_intensity()](reference.rst#kikuchipy.signals.EBSD.rescale_intensity).\n",
    "\n",
    "This also works for `EBSDMasterPattern` signals."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.8.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}