{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Masking"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import scipp as sc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating and manipulating masks\n",
    "\n",
    "Masks are simply variables with `dtype=bool`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mask = sc.Variable(dims=['x'], values=[False, False, True])\n",
    "sc.table(mask)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Boolean operators can be used to manipulate such variables:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(~mask)\n",
    "print(mask ^ mask)\n",
    "print(mask & ~mask)\n",
    "print(mask | ~mask)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Comparison operators such as `==`, `!=`, `<`, or `>=` (see also the [list of comparison functions](../reference/api.rst#comparison)) are a common method of defining masks:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "var = sc.Variable(dims=['x'], values=np.random.random(5), unit=sc.units.m)\n",
    "mask2 = var < 0.5 * sc.units.m\n",
    "mask2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Masks in data arrays and items of dataset\n",
    "\n",
    "Data arrays and equivalently items of dataset can store arbitrary masks.\n",
    "Datasets themselves do not support masks.\n",
    "Masks are accessible using the `masks` keyword-argument and property, which behaves in the same way as `coords`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a = sc.DataArray(\n",
    "    data = sc.Variable(dims=['y', 'x'], values=np.arange(1.0, 7.0).reshape((2, 3))),\n",
    "    coords={\n",
    "        'y': sc.Variable(dims=['y'], values=np.arange(2.0), unit=sc.units.m),\n",
    "        'x': sc.Variable(dims=['x'], values=np.arange(3.0), unit=sc.units.m)},\n",
    "    masks={\n",
    "        'x': sc.Variable(dims=['x'], values=[False, False, True])}\n",
    "    )\n",
    "sc.show(a)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "b = a.copy()\n",
    "b.masks['x'].values[1] = True\n",
    "b.masks['y'] = sc.Variable(dims=['y'], values=[False, True])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that setting a mask does *not* affect the data.\n",
    "\n",
    "Masks of dataset items are accessed using the `masks` property of the item:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ds = sc.Dataset(data={'a':a})\n",
    "ds['a'].masks['x']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Operations with masked objects\n",
    "\n",
    "### Element-wise binary operations\n",
    "\n",
    "The result of operations between data arrays or dataset with masks contains the masks of both inputs.\n",
    "If both inputs contain a mask with the same name, the output mask is the combination of the input masks with an  **OR** operation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "a + b"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Reduction operations\n",
    "\n",
    "Operations like `sum` and `mean` over a particular dimension cannot preserve masks that depend on this dimension.\n",
    "If this is the case, the mask is applied during the operation and is not present in the output:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.sum(a, 'x')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `mean` operation takes into account that masking is reducing the number of points in the mean, i.e., masked elements are not counted (in contrast to, e.g., treating them as 0):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sc.mean(a, 'x')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If a mask does not depend on the dimension used for the `sum` or `mean` operation, it is preserved.\n",
    "Here `b` has two masks, one that is applied and one that is preserved:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "sc.sum(b, 'x')"
   ]
  }
 ],
 "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.7.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}