{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "from lumicks import pylake\n",
    "\n",
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Files and channels\n",
    "\n",
    "[Download this page as a Jupyter notebook](_downloads/file.ipynb)\n",
    "\n",
    "Opening a Bluelake HDF5 file is very simple:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from lumicks import pylake\n",
    "\n",
    "file = pylake.File(\"example.h5\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Contents\n",
    "\n",
    "To see a textual representation of the contents of a file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(file)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For a listing of more specific timeline items:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "list(file.scans)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "list(file.kymos)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "They can also be printed to get more information:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(file.scans)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Channels\n",
    "\n",
    "Just like the Bluelake timeline, exported HDF5 files contain multiple channels of data. They can be easily accessed as shown below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "file.force1x.plot()\n",
    "plt.savefig(\"force1x.png\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The channels have a few convenient methods, like `.plot()` which make it easy to preview the contents, but you can also always access the raw data directly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "f1x_data = file.force1x.data\n",
    "f1x_timestamps = file.force1x.timestamps\n",
    "plt.plot(f1x_timestamps, f1x_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above examples use the `force1x` channel. A full list of available channels can be found on the [`File`](tutorial/../_api/lumicks.pylake.File.html#lumicks.pylake.File) reference page.\n",
    "\n",
    "By default, entire channels are returned from a file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "everything = file.force1x\n",
    "everything.plot()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But channels can easily be sliced:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get the data between 1 and 1.5 seconds\n",
    "part = file.force1x['1s':'1.5s']\n",
    "part.plot()\n",
    "# Or manually\n",
    "f1x_data = part.data\n",
    "f1x_timestamps = part.timestamps\n",
    "plt.plot(f1x_timestamps, f1x_data)\n",
    "\n",
    "# More slicing examples\n",
    "a = file.force1x[:'-5s']  # everything except the last 5 seconds\n",
    "b = file.force1x['-1m':]  # take the last minute\n",
    "c = file.force1x['-1m':'-500ms']  # last minute except the last 0.5 seconds\n",
    "d = file.force1x['1.2s':'-4s']  # between 1.2 seconds and 4 seconds from the end\n",
    "e = file.force1x['5.7m':'1h 40m']  # 5.7 minutes to an hour and 40 minutes\n",
    "\n",
    "# Subslicing is also possible\n",
    "a = file.force1x['1s':]  # from 1 second to the end of the file\n",
    "b = a['1s':]  # 1 second relative to the start of slice `a`\n",
    "              # --> `b` starts at 2 seconds relative to the beginning of the file"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that channels are indexed in time units using numbers with suffixes. The possible suffixes are d, h, m, s, ms, us, ns, corresponding to day, hour, minute, second, millisecond, microsecond and nanosecond. This indexing only applies to channels slices. Once you access the raw data, those are regular arrays which use regular array indexing:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "channel_slice = file.force1x['1.5s':'20s']  # timestamps\n",
    "data_slice = file.force1x.data[20:40]  # indices into the array"
   ]
  }
 ],
 "metadata": {},
 "nbformat": 4,
 "nbformat_minor": 2
}