Added barrel basic usage notebook

pyspedas_examples/notebooks/BARREL_background_model.ipynb

@@ -0,0 +1,181 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## BARREL Create Background Model\n",
+    "\n",
+    "\n",
+    "### Setup\n",
+    "Start by importing libraries and loading data from a potentially interesting event.\n",
+    "\n",
+    "In this guide, we are going to use interactive plots, so `%matplotlib ipympl` should be set."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%matplotlib ipympl\n",
+    "import pyspedas, pytplot, pprint, numpy\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For our example, we will look at data form flight 1G from January 17th - 19th, 2013.\n",
+    "\n",
+    "FSPC and SSPC data can be downloaded with the `pyspedas.barrel` helper functions:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "trange=['2013-01-17', '2013-01-19']\n",
+    "\n",
+    "pyspedas.barrel.fspc(\n",
+    "    trange=trange,\n",
+    "    probe='1g'\n",
+    ")\n",
+    "\n",
+    "pyspedas.barrel.sspc(\n",
+    "    trange=trange,\n",
+    "    probe='1g'\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Background subtraction\n",
+    "Plot FSPC1 for the loaded data and visually determine the start and stop locations for the background selection."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pytplot.tplot('brl1G_SSPC')\n",
+    "pytplot.tplot('brl1G_FSPC1')"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "By moving the mouse cursor over a quiet area of the plot, we can estimate values for the start and stop times.\n",
+    "In this way we can find one or more periods of time to use for background calculation.\n",
+    "\n",
+    "These start and stop times can be stored in a list of tuples:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "background_periods=[(\"2013-01-17/17:25\", \"2013-01-17/20:35\"), (\"2013-01-18/09:35\", \"2013-01-18/12:04\")]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Similarly, we can use the plot to estimate the time period of the event that we are interested in:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "event_period=(\"2013-01-17/01:54\", \"2013-01-17/03:24\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Next we will extract the SSPC data and send it to the `pyspedas.barrel.average_event_spectrum` function. This will return a background subtracted average spectrum of the event. This data is stored in a new tplot variable with the x axis set to show the energy levels."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ts, cnts, energy_levels = pytplot.get_data('brl1G_SSPC')\n",
+    "spec = pyspedas.barrel.average_event_spectrum(ts, cnts, energy_levels, background_periods, event_period)\n",
+    "pytplot.store_data(\"brl1G_Event_Spec\", data={'x':energy_levels, 'y':spec})\n",
+    "pytplot.options(\"brl1G_Event_Spec\", opt_dict={\"name\": \"Average Event Spectrum\", \"ytitle\": \"cnts/keV/sec\"})\n",
+    "pytplot.tplot(\"brl1G_Event_Spec\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In addition to plotting the event spectrum, we can generate a background-subtracted spectrogram using the `pyspedas.barrel.background_subtracted_spectrogram` function. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#The background subtracted spectrogram function only takes the background time periods, not the event time periods.\n",
+    "bg_sub_spectrogram = pyspedas.barrel.background_subtracted_spectrogram(ts, cnts, energy_levels, background_periods)\n",
+    "pytplot.store_data(\"brl1G_SSPC_BKG_SUB\", data={'x':ts, 'y':bg_sub_spectrogram, 'v':energy_levels})\n",
+    "pytplot.options(\"brl1G_SSPC_BKG_SUB\", \"name\", \"Background Subtracted SSPC\")\n",
+    "\n",
+    "#If the option for the spectrogram plot isn't set, it will plot a stack of line plots\n",
+    "pytplot.options(\"brl1G_SSPC_BKG_SUB\", \"Spec\", 1) \n",
+    "\n",
+    "#We can guess at the y axis range by looking at the event stectum above. Setting the upper limit to 500keV will capture all of the counts\n",
+    "pytplot.options(\"brl1G_SSPC_BKG_SUB\", \"yrange\", [0, 500])\n",
+    "\n",
+    "#Use the estimated event period to set the time range for the plot\n",
+    "pytplot.tlimit(list(event_period))\n",
+    "\n",
+    "pytplot.tplot(\"brl1G_SSPC_BKG_SUB\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": ".venv",
+   "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.11.3"
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}