{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "18d7d651-de23-4173-ad1f-e1b7774ecb1d",
   "metadata": {},
   "source": [
    "# MuonDataLib Tutorial 1: Getting started"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "561c72d6-97ac-4de3-a012-32134123099e",
   "metadata": {},
   "source": [
    "\n",
    "\n",
    "## Introduction\n",
    "\n",
    "The `MuonDataLib` package is for processing ISIS muon event data into a muon nexus version 2 histogram file. The processing includes:\n",
    "\n",
    "* Converting the events into histograms\n",
    "* Filtering the events based on the time at which they occurred\n",
    "\n",
    "The histogram nexus file is currently only compatible with Wimda."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7785d096-a056-4962-91d8-80afa2a3f90e",
   "metadata": {},
   "source": [
    "## Getting started\n",
    "\n",
    "The first task is to install the latest version of `MuonDataLib`. This can easily be done by using Python (supports 3.8 to 3.12 on Windows, Mac and Linux) by using `pip`, see __[here](https://pypi.org/project/MuonDataLib/)__ for more details."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0e127cad-c85c-47a9-8ede-53a46ae52791",
   "metadata": {},
   "source": [
    "## Data file paths\n",
    "\n",
    "When using files in `Python` the path is always relative from where the code is ran (this does not have to be the same place as the file). It is possible to force the path to always be relative to your file with the following code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fb411b46-d7f7-41cf-bf3b-db506d98e506",
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "\n",
    "# path_to_this_dir = os.path.dirname(__file__)\n",
    "name = 'file.txt'\n",
    "\n",
    "# path_to_file = os.path.join(path_to_this_dir, '..', '..', '..', '..', 'test', 'data_files', name)\n",
    "path_to_file = os.path.join( '..', '..', '..', '..', 'test', 'data_files', name)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d40809ff-198f-4e10-abd3-e8016cfa2b87",
   "metadata": {},
   "source": [
    "The commented out line gets the path to the directory (folder) that contains this file, but this does not work in Jupyter and is not needed. The `name` is the name of the file we are interested in, for this example we assume its an input file. \n",
    "\n",
    "This tutorial has 2 directories\n",
    "1. Tutorials\n",
    "2. Output_files\n",
    "\n",
    "this file in in `Tutorials` as part of the documentation, so to get to the input files from the tests then we need to go back a few directories (`..` is go up once). The final line adds the paths together, including the `data_files`. \n",
    "\n",
    "Since these examples are all Jupyter notebooks, they will always be run from the file location. So we will be omitting the `path_to_this_dir` as it is superfluous. \n",
    "\n",
    "## Creating a nexus file\n",
    "\n",
    "The simplest user case is creating a histogram nexus file from events data. The first step is to define the input event file and output histogram nexus file. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0b2a710e-5a40-4b45-9456-b87f33480b22",
   "metadata": {},
   "outputs": [],
   "source": [
    "input_file = os.path.join('..', '..', '..', '..', 'test', 'data_files', 'HIFI00195790.nxs')\n",
    "\n",
    "output_file = os.path.join('..', 'Output_files', 'HIFI00195790.nxs')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "402d699d-5708-498c-8a06-d848954cadd8",
   "metadata": {},
   "source": [
    "The next step is to import the event data loader from `MuonDataLib`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5eafdb71-6012-4417-aace-23434b184d86",
   "metadata": {},
   "outputs": [],
   "source": [
    "from MuonDataLib.data.loader.load_events import load_events"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5eed7410-2aa5-4837-92db-d6a6f6ae03ca",
   "metadata": {},
   "source": [
    "The following two steps will load the event data and then save the histogram nexus file. \n",
    "\n",
    "The `load_events` command takes two arguments, the event file and the number of detectors for that instrument (for HIFI that is 64). It the returns a muon event data object.\n",
    "\n",
    "The `save_histograms` method of the muon event data object creates a histogram nexus file with the name given by `output_file`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ec3d36bc-6553-4954-8596-a28204dabb7e",
   "metadata": {},
   "outputs": [],
   "source": [
    "event_data = load_events(input_file, 64)\n",
    "event_data.save_histograms(output_file)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "44733971-355d-4cd3-a0b3-ec788ab53e4d",
   "metadata": {},
   "source": [
    "This code should have written the histogram nexus file defined by `output_file`. To test that it has written correctly you can load it into Wimda."
   ]
  }
 ],
 "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.12.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}