diff --git a/pyspedas_examples/notebooks/BARREL_background_model.ipynb b/pyspedas_examples/notebooks/BARREL_background_model.ipynb new file mode 100644 index 0000000..8e9e49b --- /dev/null +++ b/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 +} diff --git a/pyspedas_examples/notebooks/BARREL_basic_usage.ipynb b/pyspedas_examples/notebooks/BARREL_basic_usage.ipynb new file mode 100644 index 0000000..01589d6 --- /dev/null +++ b/pyspedas_examples/notebooks/BARREL_basic_usage.ipynb @@ -0,0 +1,270 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## BARREL PySPEADAS Basic Usage Guide\n", + "\n", + "This notebook will demonstrate how to download and view BARREL data using pySPEDAS. \n", + "\n", + "### Setup\n", + "First, import the pyspedas library and some tplot functions." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [], + "source": [ + "import pyspedas\n", + "from pytplot import tplot, tplot_names, tlimit, tplot_options, options, store_data" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Loading Data\n", + "We will load data the data collected by BARREL flight `1D` from `January 17th and 18th, 2013`. To do this, use the pySPEDAS BARREL data loader to download the data from CDAWeb.\n", + "\n", + "Each type of BARREL data uses a different data loader function. The options are:\n", + "- `sspc` - Slow Specta (256 channels accumulated over 32 seconds)\n", + "- `mspc` - Medium Spectra (48 channels accumulated over 4 seconds)\n", + "- `fspc` - Fast Spectra (4 channels record at 20Hz)\n", + "- `magn` - Magnetometer Data\n", + "- `ephm` - Ephemeris (GPS data and magnetic coordinates)\n", + "- `hkpg` - Housekeeping (Voltages, currents, temperatures)\n", + "- `rcnt` - Rate Counters (Scintillating statistics)\n", + "\n", + "For this example we will download the Fast Spectra data using it's loader function:" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "28-Sep-23 12:12:50: Downloading https://spdf.gsfc.nasa.gov/pub/data/barrel/l2/1d/fspc/bar_1d_l2_fspc_20130117_v10.cdf to barrel_data/l2/1d/fspc/bar_1d_l2_fspc_20130117_v10.cdf\n", + "28-Sep-23 12:13:09: Download complete: barrel_data/l2/1d/fspc/bar_1d_l2_fspc_20130117_v10.cdf\n", + "28-Sep-23 12:13:10: Downloading https://spdf.gsfc.nasa.gov/pub/data/barrel/l2/1d/fspc/bar_1d_l2_fspc_20130118_v10.cdf to barrel_data/l2/1d/fspc/bar_1d_l2_fspc_20130118_v10.cdf\n", + "28-Sep-23 12:13:29: Download complete: barrel_data/l2/1d/fspc/bar_1d_l2_fspc_20130118_v10.cdf\n" + ] + }, + { + "data": { + "text/plain": [ + "['brl1D_Quality',\n", + " 'brl1D_FSPC1',\n", + " 'brl1D_FSPC2',\n", + " 'brl1D_FSPC3',\n", + " 'brl1D_FSPC4',\n", + " 'brl1D_Quality',\n", + " 'brl1D_FSPC1',\n", + " 'brl1D_FSPC2',\n", + " 'brl1D_FSPC3',\n", + " 'brl1D_FSPC4']" + ] + }, + "execution_count": 2, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "#Specify the data range. The end date is non-inclusive, so this will only download for the 17th and 18th.\n", + "trange=['2013-01-17', '2013-01-19']\n", + "\n", + "pyspedas.barrel.fspc( #use the loader for a specific data type\n", + " trange=trange,\n", + " probe='1D' #specify the payload ID\n", + ")" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "The data files `bar_1d_l2_fspc_20130117_v10.cdf` and `bar_1d_l2_fspc_20130118_v10.cdf` should have been downloaded to a sub folder called `./barrel_data`. Once those files have been downloaded, local files will be reused each time the loader is run.\n", + "\n", + "To see what data have been loaded, use the `tplot_names` function to list what is available." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "tplot_names()" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Loading data from another flight adds more tplot variables" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "pyspedas.barrel.fspc( #use the loader for a specific data type\n", + " trange=trange, #specify the time range\n", + " probe='1G' #specify the payload ID\n", + ")\n", + "tplot_names()" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Plot the data" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Data can be plotted by passing the name of a tplot variable to the `tplot` function." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "tplot('brl1D_FSPC1')" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Passing a list of tplot names will create stacked plots" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "tplot(['brl1D_FSPC1', 'brl1G_FSPC1'])" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Adjust the plots" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "metadata": {}, + "source": [ + "By default, the entire range of available data is plotted. We can zoom in to a take a closer look using the `tlimit` function." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "tlimit(['2013-01-18/12:00', '2013-01-18/18:00'])\n", + "tplot(['brl1G_FSPC1', 'brl1G_FSPC2', 'brl1G_FSPC3', 'brl1G_FSPC4'])" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Next, we can add colors, titles, labels, etc using the `ptplot.options` and `pytplot.tplot_options` functions. A full list of options are availible here:\n", + "- [pytplot.tplot_options](https://pytplot.readthedocs.io/en/latest/tplot_options.html)\n", + "- [pytplot.options](https://pytplot.readthedocs.io/en/latest/options.html)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "tplot_options(\"title\", \"1D and 1G Low Energy Fast Spectra Jan 18, 2013\")\n", + "options(\"brl1D_FSPC1\", \"Color\", \"red\")\n", + "options(\"brl1G_FSPC1\", \"Color\", \"blue\")\n", + "tplot([\"brl1D_FSPC1\", \"brl1G_FSPC1\"])" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "NOTE: Options that are set will stay set for future plots. So remember to change plot titles when you change variables." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Creating Psedovariables\n", + "\n", + "Using the `pytplot.store_data` function, we can group of variables together. This is useful if we want to group more than one variable togethr in a single plot." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "pyspedas.barrel.magn(probe=\"1d\", trange=trange)\n", + "tplot_names()\n", + "store_data(\"brl1D_MAG_XYZ\", data=['brl1D_MAG_X_uncalibrated', 'brl1D_MAG_Y_uncalibrated', 'brl1D_MAG_Z_uncalibrated'])\n", + "tplot_options(\"title\", \"1D Magnetomoeter\")\n", + "tplot(\"brl1D_MAG_XYZ\")" + ] + } + ], + "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 +}