{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using multi_d_acquistion_events\n",
    "\n",
    "`multi_d_acquisition_events` is a powerful tool that allows you to specify the acquisition events in a similar manner to using the μmanager gui.\n",
    "\n",
    "You should also read the [Features page for this function](https://pycro-manager.readthedocs.io/en/latest/acq_events.html)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "from pycromanager import multi_d_acquisition_events"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Specifying xy positions\n",
    "\n",
    "To specify the xy positions you need to pass a 2D array with shape (N, 2). However, you may have two separate arrays for `x` and `y`. In the next cells are several different ways to construct an approriate 2D array."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0,  0],\n",
       "       [ 1, -1],\n",
       "       [ 2, -2],\n",
       "       [ 3, -3],\n",
       "       [ 4, -4]])"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "x = np.arange(0, 5)\n",
    "y = np.arange(0, -5, -1)\n",
    "\n",
    "xy = np.hstack([x[:, None], y[:, None]])\n",
    "xy"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'axes': {'position': 0}, 'x': 0, 'y': 0},\n",
       " {'axes': {'position': 1}, 'x': 1, 'y': -1},\n",
       " {'axes': {'position': 2}, 'x': 2, 'y': -2},\n",
       " {'axes': {'position': 3}, 'x': 3, 'y': -3},\n",
       " {'axes': {'position': 4}, 'x': 4, 'y': -4}]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "multi_d_acquisition_events(xy_positions=xy)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adding z positions\n",
    "\n",
    "### Single absolute z position\n",
    "\n",
    "To specify a single z value for each position use the `xyz_positions` argument"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'axes': {'position': 0, 'z': 0}, 'x': 0, 'y': 0, 'z': 0},\n",
       " {'axes': {'position': 1, 'z': 0}, 'x': 1, 'y': -1, 'z': 1},\n",
       " {'axes': {'position': 2, 'z': 0}, 'x': 2, 'y': -2, 'z': 2},\n",
       " {'axes': {'position': 3, 'z': 0}, 'x': 3, 'y': -3, 'z': 3},\n",
       " {'axes': {'position': 4, 'z': 0}, 'x': 4, 'y': -4, 'z': 4}]"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "z = np.arange(0, 5)\n",
    "xyz = np.hstack([x[:, None], y[:, None], z[:, None]])\n",
    "multi_d_acquisition_events(xyz_positions=xyz)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Relative z positions\n",
    "\n",
    "### Relative to each point"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'axes': {'position': 0, 'z': 0}, 'x': 0, 'y': 0, 'z': -1},\n",
       " {'axes': {'position': 0, 'z': 1}, 'x': 0, 'y': 0, 'z': 0},\n",
       " {'axes': {'position': 0, 'z': 2}, 'x': 0, 'y': 0, 'z': 1},\n",
       " {'axes': {'position': 1, 'z': 0}, 'x': 1, 'y': -1, 'z': 0},\n",
       " {'axes': {'position': 1, 'z': 1}, 'x': 1, 'y': -1, 'z': 1},\n",
       " {'axes': {'position': 1, 'z': 2}, 'x': 1, 'y': -1, 'z': 2},\n",
       " {'axes': {'position': 2, 'z': 0}, 'x': 2, 'y': -2, 'z': 1},\n",
       " {'axes': {'position': 2, 'z': 1}, 'x': 2, 'y': -2, 'z': 2},\n",
       " {'axes': {'position': 2, 'z': 2}, 'x': 2, 'y': -2, 'z': 3},\n",
       " {'axes': {'position': 3, 'z': 0}, 'x': 3, 'y': -3, 'z': 2},\n",
       " {'axes': {'position': 3, 'z': 1}, 'x': 3, 'y': -3, 'z': 3},\n",
       " {'axes': {'position': 3, 'z': 2}, 'x': 3, 'y': -3, 'z': 4},\n",
       " {'axes': {'position': 4, 'z': 0}, 'x': 4, 'y': -4, 'z': 3},\n",
       " {'axes': {'position': 4, 'z': 1}, 'x': 4, 'y': -4, 'z': 4},\n",
       " {'axes': {'position': 4, 'z': 2}, 'x': 4, 'y': -4, 'z': 5}]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "multi_d_acquisition_events(xyz_positions=xyz, z_start=-1, z_end=1, z_step=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### A range that is shared by all points"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'axes': {'position': 0, 'z': 0}, 'x': 0, 'y': 0, 'z': -1},\n",
       " {'axes': {'position': 0, 'z': 1}, 'x': 0, 'y': 0, 'z': 0},\n",
       " {'axes': {'position': 0, 'z': 2}, 'x': 0, 'y': 0, 'z': 1},\n",
       " {'axes': {'position': 1, 'z': 0}, 'x': 1, 'y': -1, 'z': -1},\n",
       " {'axes': {'position': 1, 'z': 1}, 'x': 1, 'y': -1, 'z': 0},\n",
       " {'axes': {'position': 1, 'z': 2}, 'x': 1, 'y': -1, 'z': 1},\n",
       " {'axes': {'position': 2, 'z': 0}, 'x': 2, 'y': -2, 'z': -1},\n",
       " {'axes': {'position': 2, 'z': 1}, 'x': 2, 'y': -2, 'z': 0},\n",
       " {'axes': {'position': 2, 'z': 2}, 'x': 2, 'y': -2, 'z': 1},\n",
       " {'axes': {'position': 3, 'z': 0}, 'x': 3, 'y': -3, 'z': -1},\n",
       " {'axes': {'position': 3, 'z': 1}, 'x': 3, 'y': -3, 'z': 0},\n",
       " {'axes': {'position': 3, 'z': 2}, 'x': 3, 'y': -3, 'z': 1},\n",
       " {'axes': {'position': 4, 'z': 0}, 'x': 4, 'y': -4, 'z': -1},\n",
       " {'axes': {'position': 4, 'z': 1}, 'x': 4, 'y': -4, 'z': 0},\n",
       " {'axes': {'position': 4, 'z': 2}, 'x': 4, 'y': -4, 'z': 1}]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "multi_d_acquisition_events(xy_positions=xy, z_start=-1, z_end=1, z_step=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Time points\n",
    "\n",
    "You can specify the number of time points and the delay between them. The `min_start_time` in the events makes it so that there is a garunteed delay between subsequent acquisition events."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'axes': {'time': 0}, 'min_start_time': 0},\n",
       " {'axes': {'time': 1}, 'min_start_time': 10},\n",
       " {'axes': {'time': 2}, 'min_start_time': 20},\n",
       " {'axes': {'time': 3}, 'min_start_time': 30},\n",
       " {'axes': {'time': 4}, 'min_start_time': 40}]"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "multi_d_acquisition_events(num_time_points=5, time_interval_s=10)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When combining a time series with a position series we can specify the order using teh `order` argument which has a default order of:\n",
    "\n",
    "1. time\n",
    "2. position\n",
    "3. channel\n",
    "4. z"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'axes': {'position': 0, 'time': 0, 'z': 0},\n",
       "  'x': 0,\n",
       "  'y': 0,\n",
       "  'min_start_time': 0,\n",
       "  'z': -1},\n",
       " {'axes': {'position': 0, 'time': 0, 'z': 1},\n",
       "  'x': 0,\n",
       "  'y': 0,\n",
       "  'min_start_time': 0,\n",
       "  'z': 0},\n",
       " {'axes': {'position': 0, 'time': 1, 'z': 0},\n",
       "  'x': 0,\n",
       "  'y': 0,\n",
       "  'min_start_time': 10,\n",
       "  'z': -1},\n",
       " {'axes': {'position': 0, 'time': 1, 'z': 1},\n",
       "  'x': 0,\n",
       "  'y': 0,\n",
       "  'min_start_time': 10,\n",
       "  'z': 0},\n",
       " {'axes': {'position': 1, 'time': 0, 'z': 0},\n",
       "  'x': 1,\n",
       "  'y': -1,\n",
       "  'min_start_time': 0,\n",
       "  'z': -1},\n",
       " {'axes': {'position': 1, 'time': 0, 'z': 1},\n",
       "  'x': 1,\n",
       "  'y': -1,\n",
       "  'min_start_time': 0,\n",
       "  'z': 0},\n",
       " {'axes': {'position': 1, 'time': 1, 'z': 0},\n",
       "  'x': 1,\n",
       "  'y': -1,\n",
       "  'min_start_time': 10,\n",
       "  'z': -1},\n",
       " {'axes': {'position': 1, 'time': 1, 'z': 1},\n",
       "  'x': 1,\n",
       "  'y': -1,\n",
       "  'min_start_time': 10,\n",
       "  'z': 0}]"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "xy_small = xy[:2, :]\n",
    "multi_d_acquisition_events(\n",
    "    num_time_points=2,\n",
    "    time_interval_s=10,\n",
    "    xy_positions=xy_small,\n",
    "    order=\"ptz\",\n",
    "    z_start=-1,\n",
    "    z_end=0,\n",
    "    z_step=1,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Channels\n",
    "\n",
    "The `channel_group`, `channels` and `channel_exposure_ms` arguments can be used to control what channels are collected."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'axes': {'position': 0},\n",
       "  'x': 0,\n",
       "  'y': 0,\n",
       "  'channel': {'group': 'your-channel-group', 'config': 'BF'},\n",
       "  'exposure': 0},\n",
       " {'axes': {'position': 0},\n",
       "  'x': 0,\n",
       "  'y': 0,\n",
       "  'channel': {'group': 'your-channel-group', 'config': 'GFP'},\n",
       "  'exposure': 1},\n",
       " {'axes': {'position': 1},\n",
       "  'x': 1,\n",
       "  'y': -1,\n",
       "  'channel': {'group': 'your-channel-group', 'config': 'BF'},\n",
       "  'exposure': 0},\n",
       " {'axes': {'position': 1},\n",
       "  'x': 1,\n",
       "  'y': -1,\n",
       "  'channel': {'group': 'your-channel-group', 'config': 'GFP'},\n",
       "  'exposure': 1},\n",
       " {'axes': {'position': 2},\n",
       "  'x': 2,\n",
       "  'y': -2,\n",
       "  'channel': {'group': 'your-channel-group', 'config': 'BF'},\n",
       "  'exposure': 0},\n",
       " {'axes': {'position': 2},\n",
       "  'x': 2,\n",
       "  'y': -2,\n",
       "  'channel': {'group': 'your-channel-group', 'config': 'GFP'},\n",
       "  'exposure': 1},\n",
       " {'axes': {'position': 3},\n",
       "  'x': 3,\n",
       "  'y': -3,\n",
       "  'channel': {'group': 'your-channel-group', 'config': 'BF'},\n",
       "  'exposure': 0},\n",
       " {'axes': {'position': 3},\n",
       "  'x': 3,\n",
       "  'y': -3,\n",
       "  'channel': {'group': 'your-channel-group', 'config': 'GFP'},\n",
       "  'exposure': 1},\n",
       " {'axes': {'position': 4},\n",
       "  'x': 4,\n",
       "  'y': -4,\n",
       "  'channel': {'group': 'your-channel-group', 'config': 'BF'},\n",
       "  'exposure': 0},\n",
       " {'axes': {'position': 4},\n",
       "  'x': 4,\n",
       "  'y': -4,\n",
       "  'channel': {'group': 'your-channel-group', 'config': 'GFP'},\n",
       "  'exposure': 1}]"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "channel_group = \"your-channel-group\"\n",
    "channels = [\"BF\", \"GFP\"]\n",
    "channel_exposures_ms = [15.5, 200]\n",
    "multi_d_acquisition_events(\n",
    "    xy_positions=xy,\n",
    "    channels=channels,\n",
    "    channel_group=channel_group,\n",
    "    channel_exposures_ms=channel_exposures_ms,\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "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.10.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}