PSP_SPAN-I_VDF_Plot_Tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# PSP SPAN-Ion Velocity Distribution Function (VDF) Plotting Tutorial"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Greetings! Below is a guide to plotting proton velocity-space distribution functions (VDFs) from the PSP SPAN-I instrument. If one is only interested in viewing a VDF at a particular time, the reader may skip to the last two cells.\n",
    "\n",
    "We note that the SPAN-I instrument has many caveats and the data remains preliminary due to ongoing calibration work done by the instrument team. \n",
    "\n",
    "For optimal scientific interpretation of noteworthy event, the reader is strongly encouraged to contact a member of the instrument team:<br>\n",
    "Roberto Livi rlivi@berkeley.edu <br>\n",
    "Ali Rahmati rahmati@berkeley.edu <br>\n",
    "Michael McManus mdmcmanus@berkeley.edu <br>\n",
    "Davin Larson davin@berkeley.edu <br>\n",
    "\n",
    "This tutorial was brought to you by: <br>\n",
    "Jaye Verniero jaye.l.verniero@nasa.gov <br>\n",
    "Kristoff Paulson kristoff.paulson@cfa.harvard.edu <br>\n",
    "who may serve as points of contact for this tutorial. <br>\n",
    "\n",
    "The paper describing the SPAN-I instrument in more detail can be found here: <br>https://doi.org/10.3847/1538-4357/ac93f5\n",
    "\n",
    "This tutorial mirrors the SPAN-e plotting walkthrough found here: https://github.com/kpaulson/PSPGatewayHelp/blob/master/JupyterNotebook_Tutorials/PSP/SPANe_pitchAngleWalkthrough/PSP_SPANe_PitchAnglePlotter%20-%20PythonTutorial.ipynb\n",
    "where the user can also learn about cdf files."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 0\n",
    "\n",
    "First, we import the cdf reader from cdflib (the library able to read the data encoded in the cdf format) and wget (which we will use here to grab and download the file from the remote server). We also import 'numpy' for math operations and 'datetime' for time unit conversions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#!pip install wget\n",
    "import wget\n",
    "import cdflib\n",
    "import numpy as np\n",
    "from datetime import datetime\n",
    "import os.path\n",
    "import bisect\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "from matplotlib import ticker, cm\n",
    "import warnings \n",
    "warnings.filterwarnings(\"ignore\")\n",
    "\n",
    "\n",
    "from warnings import simplefilter \n",
    "simplefilter(action='ignore', category=DeprecationWarning)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 1\n",
    "\n",
    "Let's download the data!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "year=2020\n",
    "month=1\n",
    "day=29\n",
    "\n",
    "user_datetime = datetime(year,month,day)\n",
    "\n",
    "def yyyymmdd(dt) : return f\"{dt.year:04d}{dt.month:02d}{dt.day:02d}\"\n",
    "\n",
    "#Import from file directory\n",
    "VDfile_directoryRemote = f'http://w3sweap.cfa.harvard.edu/pub/data/sci/sweap/spi/L2/spi_sf00/{user_datetime.year:04d}/{user_datetime.month:02d}/'\n",
    "VDfile_filename = f'psp_swp_spi_sf00_L2_8Dx32Ex8A_{yyyymmdd(user_datetime)}_v04.cdf'\n",
    "\n",
    "#check if file is already downloaded. If so, skip download. If not, download in local directory.\n",
    "if os.path.isfile(VDfile_filename):\n",
    "    print(f\"File already exists in local directory - [{VDfile_filename}]\")\n",
    "    VDfile = VDfile_filename\n",
    "else:\n",
    "    print(\"File doesn't exist. Downloading ...\")\n",
    "    VDfile = wget.download(VDfile_directoryRemote + VDfile_filename)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we open the cdf file and look at the variables along with their associated structure."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#open CDF file\n",
    "dat = cdflib.CDF(VDfile)\n",
    "\n",
    "#print variable names in CDF files\n",
    "print(dat._get_varnames())\n",
    "cdf_VDfile=dat\n",
    "\n",
    "#check variable formats in cdf file\n",
    "print(cdf_VDfile)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 2\n",
    "Let's define some variables!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "epoch_ns        = cdf_VDfile['Epoch']\n",
    "theta           = cdf_VDfile['THETA']\n",
    "phi             = cdf_VDfile['PHI']\n",
    "energy          = cdf_VDfile['ENERGY']\n",
    "eflux           = cdf_VDfile['EFLUX']\n",
    "rotMat          = cdf_VDfile['ROTMAT_SC_INST']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Type which timeslice you would like to plot in the format (year, month, day, hour, minute, second)\n",
    "\n",
    "As of now, it is set up to input a single day, but future iterations of this tutorial will implement a time range. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "#convert time\n",
    "import datetime\n",
    "datetime_t0 = datetime.datetime(2000, 1, 1, 12, 0, 0)\n",
    "epoch = cdflib.cdfepoch.to_datetime(cdf_VDfile.varget('Epoch'))\n",
    "\n",
    "hour = 18\n",
    "minute = 10\n",
    "second = 2\n",
    "\n",
    "timeSlice  = datetime.datetime(year, month, day, hour, minute, second)\n",
    "print('Desired timeslice:',timeSlice)\n",
    "\n",
    "#find index for desired timeslice\n",
    "tSliceIndex  = bisect.bisect_left(epoch,timeSlice)\n",
    "print('time Index:',tSliceIndex)\n",
    "print('Time of closest data point:',epoch[tSliceIndex])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now define all variables at this time slice. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "epochSlice  = epoch[tSliceIndex]\n",
    "thetaSlice  = theta[tSliceIndex,:]\n",
    "phiSlice    = phi[tSliceIndex,:]\n",
    "energySlice = energy[tSliceIndex,:]\n",
    "efluxSlice  = eflux[tSliceIndex,:]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And now we rearrange to a more readable format reflecting 8 $\\phi$-direction bins, 32 energy bins, and 8 $\\theta$-direction bins. Note that the $\\phi$ direction is most effected by partial obstruction by the heat shield, and therefore should be treated with extra caution (and ideally guidance from the instrument team)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "thetaReshaped = thetaSlice.reshape((8,32,8))\n",
    "phiReshaped = phiSlice.reshape((8,32,8))\n",
    "energyReshaped = energySlice.reshape((8,32,8))\n",
    "efluxReshaped = efluxSlice.reshape((8,32,8))\n",
    "\n",
    "print(thetaReshaped.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Step 3\n",
    "Now that we downloaded the data and defined the variables in the most optimal format, we are ready to begin our journey toward plotting a VDF."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "mass_p = 0.010438870      #proton mass in units eV/c^2 where c = 299792 km/s\n",
    "charge_p = 1              #proton charge in units eV\n",
    "\n",
    "#Define VDF\n",
    "numberFlux = efluxReshaped/energyReshaped\n",
    "vdf = numberFlux*(mass_p**2)/((2E-5)*energyReshaped)\n",
    "\n",
    "#Convert to velocity units in each energy channel\n",
    "vel = np.sqrt(2*charge_p*energyReshaped/mass_p)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, rotate from energy-angle space to cartesian (vx,vy,vz) space (still in the SPAN-I instrument frame):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "vx = vel * np.cos(np.radians(phiReshaped)) * np.cos(np.radians(thetaReshaped))\n",
    "vy = vel * np.sin(np.radians(phiReshaped)) * np.cos(np.radians(thetaReshaped))\n",
    "vz = vel *                                   np.sin(np.radians(thetaReshaped))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First, we plot the collapsed distribition function f(v), where all angles are summed as an approximation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#sum over both phi and theta \n",
    "vdf_allAngles = np.sum(vdf, axis=(0,2))\n",
    "\n",
    "#plot and set limits/labels\n",
    "plt.plot(vel[0,:,0],vdf_allAngles)\n",
    "plt.yscale('log')\n",
    "plt.xlim(0,1000)\n",
    "plt.ylabel(f'f $(cm^2 \\\\ s \\\\ sr \\\\ eV)^{-1}$')\n",
    "plt.xlabel('Velocity (km/s)')\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, instead of collapsing all angles, we can sum over individual axes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "vdf_allThetas = np.sum(vdf, axis=0)\n",
    "fig = plt.figure(figsize=(12, 6))\n",
    "ax = fig.add_subplot(111)\n",
    "ax.plot(vel[0,:,:],vdf_allThetas)\n",
    "\n",
    "ax.set(xlim=(0, 1000),yscale='log', xlabel='Velocity (km/s)', ylabel=f'f $(cm^2 \\\\ s \\\\ sr \\\\ eV)^{-1}$',title='f(v) summed over $\\\\theta$');\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "vdf_allPhis = np.sum(vdf, axis=2)\n",
    "fig = plt.figure(figsize=(12, 6))\n",
    "ax = fig.add_subplot(111)\n",
    "ax.plot(np.transpose(vel[:,:,0]),np.transpose(vdf_allPhis))\n",
    "\n",
    "ax.set(xlim=(0, 1000),yscale='log', xlabel='Velocity (km/s)', ylabel=f'f $(cm^2 \\\\ s \\\\ sr \\\\ eV)^{-1}$',title='f(v) summed over $\\phi$');\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "An alternative way to represent this data is to produce 2D contour plots through cuts in the $\\theta$ and $\\phi$ planes. This will reproduce the VDFs in the same formatting to the ones shown in Verniero et al. 2020 (DOI: 10.3847/1538-4365/ab86af)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#theta is along dimension 0, while phi is along 2\n",
    "#first cut through theta\n",
    "theta_cut=0 \n",
    "\n",
    "phi_plane = phiReshaped[theta_cut,:,:]\n",
    "theta_plane = thetaReshaped[theta_cut,:,:]\n",
    "energy_plane = energyReshaped[theta_cut,:,:]\n",
    "vel_plane = np.sqrt(2*charge_p*energy_plane/mass_p)\n",
    "\n",
    "df_theta=np.nansum(vdf,axis=0)\n",
    "\n",
    "vx_plane_theta = vel_plane * np.cos(np.radians(phi_plane)) * np.cos(np.radians(theta_plane))\n",
    "vy_plane_theta = vel_plane * np.sin(np.radians(phi_plane)) * np.cos(np.radians(theta_plane))\n",
    "vz_plane_theta = vel_plane *                                   np.sin(np.radians(theta_plane))\n",
    "\n",
    "fig,ax=plt.subplots()\n",
    "cs=ax.contourf(vx_plane_theta, vz_plane_theta, df_theta,locator=ticker.LogLocator(),cmap=cm.cool)\n",
    "cbar = fig.colorbar(cs)\n",
    "cbar.set_label(f'f $(cm^2 \\\\ s \\\\ sr \\\\ eV)^{-1}$')\n",
    "\n",
    "ax.set_xlim(-700,0)\n",
    "ax.set_ylim(-500,500)\n",
    "ax.set_xlabel('$v_x$ km/s')\n",
    "ax.set_ylabel('$v_z$ km/s')\n",
    "ax.set_title('VDF SPAN-I $\\\\theta$-plane')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that this particular time slice is the ``hammerhead\" distribution described in Verniero et al. 2022 (DOI: 10.3847/1538-4357/ac36d5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#now repeat for phi dimension\n",
    "phi_cut = 1\n",
    "\n",
    "phi_plane = phiReshaped[:,:,phi_cut]\n",
    "theta_plane = thetaReshaped[:,:,phi_cut]\n",
    "energy_plane = energyReshaped[:,:,phi_cut]\n",
    "vel_plane = np.sqrt(2*charge_p*energy_plane/mass_p)\n",
    "\n",
    "df_phi=np.nansum(vdf,axis=2)\n",
    "\n",
    "vx_plane_phi = vel_plane * np.cos(np.radians(phi_plane)) * np.cos(np.radians(theta_plane))\n",
    "vy_plane_phi = vel_plane * np.sin(np.radians(phi_plane)) * np.cos(np.radians(theta_plane))\n",
    "vz_plane_phi = vel_plane *                                   np.sin(np.radians(theta_plane))\n",
    "\n",
    "fig,ax=plt.subplots()\n",
    "cs=ax.contourf(np.transpose(vx_plane_phi), np.transpose(vy_plane_phi), np.transpose(df_phi),locator=ticker.LogLocator(),cmap=cm.cool)\n",
    "cbar = fig.colorbar(cs)\n",
    "cbar.set_label(f'f $(cm^2 \\\\ s \\\\ sr \\\\ eV)^{-1}$')\n",
    "\n",
    "ax.set_xlim(-700,0)\n",
    "ax.set_ylim(-200,500)\n",
    "ax.set_xlabel('$v_x$ km/s')\n",
    "ax.set_ylabel('$v_y$ km/s')\n",
    "ax.set_title('VDF SPAN-I $\\\\phi$-plane')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that not all of the VDF is plotted. This is because the $\\phi$ plane is most obstructed by the heat shield. One could use this visualization as a way to determine whether SPAN-I has sufficient field-of-view (FOV) for reliable measurements. One can see in this particular time slice, most of the \"core\" of the distribution is present, i.e. there exists a peak at the solar wind velocity around -150 km/s. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Magnetic Field-Aligned-Coordinates"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This visualization of the VDF is in SPAN-I instrument coordinates. To extract more physical meaning, we can rotate to magnetic field-aligned coordinates (FAC) to plot the VDF in ($\\mathbf{v}_\\parallel$,$\\mathbf{v}_\\perp$) coordinate space. Here, the perpendcular and parallel directions are with respect to the mean magentic field direction, $\\mathbf{B}_0$. Since the magnetic field data is at a much higher cadence than SPAN-I measures the plasma, we can define $\\mathbf{B}_0$ as the magnetic field vector rotated into the SPAN-I instrument frame averaged over the 7s cadence of SPAN-I. For this step, we download the L3 SPAN-I data, which contains $\\mathbf{B}_0$ in the SPAN-I instrument frame. In general, data analysis is more reliable when we perform computations in the SPAN-I instrument frame to mitigate FOV effects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#Download L3 plasma moment data\n",
    "#Import from file directory\n",
    "MOMfile_directoryRemote = f'http://w3sweap.cfa.harvard.edu/pub/data/sci/sweap/spi/L3/spi_sf00/{user_datetime.year:04d}/{user_datetime.month:02d}/'\n",
    "MOMfile_filename = f'psp_swp_spi_sf00_L3_mom_{yyyymmdd(user_datetime)}_v04.cdf'\n",
    "\n",
    "#check if file is already downloaded. If so, skip download. If not, download in local directory.\n",
    "if os.path.isfile(MOMfile_filename):\n",
    "    print(f\"File already exists in local directory - [{MOMfile_filename}]\")\n",
    "    MOMfile = MOMfile_filename\n",
    "else:\n",
    "    print(\"File doesn't exist. Downloading ...\")\n",
    "    MOMfile = wget.download(MOMfile_directoryRemote + MOMfile_filename)\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#open plasma moment CDF file\n",
    "#print variable names in CDF files\n",
    "MOMdat = cdflib.CDF(MOMfile)\n",
    "\n",
    "print(MOMdat._get_varnames())\n",
    "cdf_MOMfile=MOMdat\n",
    "#check variable formats in cdf file\n",
    "print(cdf_MOMfile)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following is a description of each variable: <br>\n",
    "QUALITY FLAG - Data quality indicator <br>\n",
    "DENS - Density (1/cm^3)<br>\n",
    "VEL_INST - Velocity in SPAN-I instrument coordinates (km/s) <br>\n",
    "VEL_SC - Spacecraft Velocity (km/s)<br>\n",
    "VEL_RTN_SUN - Ion Velocity in RTN coordinates (km/s)<br>\n",
    "TEMP - Ion Temperature (eV)<br>\n",
    "T_TENSOR_INST - Temperature Tensor SPAN-I instrument coordinates <br>\n",
    "EFLUX_VS_ENERGY - Proton Differential Energy Flux vs eV <br>\n",
    "EFLUX_VS_THETA - Proton Differential Energy Flux vs Theta (deflectors)<br>\n",
    "EFLUX_VS_PHI - Proton Differential Energy Flux vs Phi (anodes)<br>\n",
    "SUN-DIST - Distance from Sun (km)<br>\n",
    "VENUS-DIST - Distance from Venus (km)\n",
    "SC_VEL_RTN- Spacecraft Velocity in RTN coordinates (km/s)<br>\n",
    "QUAT_SC_TO_RTN - Quaternion rotation of spacecraft in RTN coordinates<br>\n",
    "MAGF_SC - Magnetic field downsampled to SPAN_I time resolution in spacecraft coordinates (nT)<br>\n",
    "MAGF_INST - Magnetic field downsampled to SPAN_I time resolution in SPAN-I instrument coordinates (nT)<br>\n",
    "\n",
    "Specific details on these variables will be left for a future tutorial. An existing one to get started using PySPEDAS is located in this directory.\n",
    "For now, we are interested in only the MAGF-INST variable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#Define variables\n",
    "\n",
    "epoch_nsMOM = cdf_MOMfile['Epoch']\n",
    "B_SPAN = cdf_MOMfile['MAGF_INST']\n",
    "\n",
    "B_SPANslice = B_SPAN[tSliceIndex,:]\n",
    "\n",
    "if B_SPANslice.ndim == 2:\n",
    "    Bx_SPAN = B_SPANslice[:,0]\n",
    "    By_SPAN = B_SPANslice[:,1]\n",
    "    Bz_SPAN = B_SPANslice[:,2]\n",
    "elif B_SPANslice.ndim == 1:\n",
    "    Bx_SPAN = B_SPANslice[0]\n",
    "    By_SPAN = B_SPANslice[1]\n",
    "    Bz_SPAN = B_SPANslice[2]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that we have the magnetic field direction in the SPANi instrument coordinates, we can rotate the processed data into field-aligned coordinates. We will define two processes here below, one of which will output the elements of a rotation matrix from instrument to field-aligned coordinates (made up of the three unit vectors defining those coordinates), and another which will rotate an input vector from instrument to field-aligned coordinates.\n",
    "\n",
    "This process will make several assumptions, the largest being that the magnetic field is perfectly defined by each measurement over the course of the SPANi collection period. \n",
    "\n",
    "(Future Work: The field measurment can be defined at each anode measurement time for each sub-frame of SPANi data, but we would have to use the merged FGM-SCM data product and better pinpoint the timestamps on each submeasurement of the instrument.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def fieldAlignedCoordinates(Bx, By, Bz):\n",
    "    '''\n",
    "    INPUTS:\n",
    "         Bx, By, Bz = rank1 arrays of magnetic field measurements in instrument frame\n",
    "    '''\n",
    "    import numpy as np\n",
    "\n",
    "\n",
    "    Bmag = np.sqrt(Bx**2 + By**2 + Bz**2)\n",
    "\n",
    "    # Define field-aligned vector\n",
    "    Nx = Bx/Bmag\n",
    "    Ny = By/Bmag\n",
    "    Nz = Bz/Bmag\n",
    "\n",
    "    # Make up some unit vector\n",
    "    if np.isscalar(Nx):\n",
    "        Rx = 0\n",
    "        Ry = 1.\n",
    "        Rz = 0\n",
    "    else:\n",
    "        Rx = np.zeros(Nx.len())\n",
    "        Ry = np.ones(len(Nx))\n",
    "        Rz = np.zeros(len(Nx))\n",
    "\n",
    "    # Find some vector perpendicular to field NxR \n",
    "    TEMP_Px = ( Ny * Rz ) - ( Nz * Ry )  # P = NxR\n",
    "    TEMP_Py = ( Nz * Rx ) - ( Nx * Rz )  # This is temporary in case we choose a vector R that is not unitary\n",
    "    TEMP_Pz = ( Nx * Ry ) - ( Ny * Rx )\n",
    "\n",
    "\n",
    "    Pmag = np.sqrt( TEMP_Px**2 + TEMP_Py**2 + TEMP_Pz**2 ) #Have to normalize, since previous definition does not imply unitarity, just orthogonality\n",
    "  \n",
    "    Px = TEMP_Px / Pmag # for R=(0,1,0), NxR = P ~= RTN_N\n",
    "    Py = TEMP_Py / Pmag\n",
    "    Pz = TEMP_Pz / Pmag\n",
    "\n",
    "\n",
    "    Qx = ( Pz * Ny ) - ( Py * Nz )   # N x P\n",
    "    Qy = ( Px * Nz ) - ( Pz * Nx )  \n",
    "    Qz = ( Py * Nx ) - ( Px * Ny )  \n",
    "\n",
    "    return(Nx, Ny, Nz, Px, Py, Pz, Qx, Qy, Qz)\n",
    "\n",
    "\n",
    "# ###\n",
    "# ### TRANSFORM VECTOR DATA INTO FIELD-ALIGNED COORDINATES\n",
    "# ###\n",
    "\n",
    "def rotateVectorIntoFieldAligned(Ax, Ay, Az, Nx, Ny, Nz, Px, Py, Pz, Qx, Qy, Qz):\n",
    "    # For some Vector A in the SAME COORDINATE SYSTEM AS THE ORIGINAL B-FIELD VECTOR:\n",
    "\n",
    "    An = (Ax * Nx) + (Ay * Ny) + (Az * Nz)  # A dot N = A_parallel\n",
    "    Ap = (Ax * Px) + (Ay * Py) + (Az * Pz)  # A dot P = A_perp (~RTN_N (+/- depending on B), perpendicular to s/c y)\n",
    "    Aq = (Ax * Qx) + (Ay * Qy) + (Az * Qz)  # \n",
    "\n",
    "    return(An, Ap, Aq)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we will run the data selected earlier in the tutorial through the rotation subprocesses"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "(Nx, Ny, Nz, Px, Py, Pz, Qx, Qy, Qz) = fieldAlignedCoordinates(Bx_SPAN, By_SPAN, Bz_SPAN)\n",
    "\n",
    "(vn_plane, vp_plane, vq_plane) = rotateVectorIntoFieldAligned(vx_plane_theta, vy_plane_theta, vz_plane_theta, Nx, Ny, Nz, Px, Py, Pz, Qx, Qy, Qz)\n",
    "\n",
    "\n",
    "print(vn_plane.shape)\n",
    "print(vp_plane.shape)\n",
    "\n",
    "fig,ax=plt.subplots()\n",
    "cs=ax.contourf(vn_plane, vp_plane, df_theta,locator=ticker.LogLocator(),cmap=cm.cool)\n",
    "cbar = fig.colorbar(cs)\n",
    "ax.set_xlim(-800,0)\n",
    "ax.set_ylim(-500,500)\n",
    "ax.set_xlabel('$v_\\parallel$ km/s')\n",
    "ax.set_ylabel('$v_\\perp1$ km/s')\n",
    "ax.set_title('VDF FAC coordinates')\n",
    "\n",
    "fig,ax=plt.subplots()\n",
    "cs=ax.contourf(vn_plane, vq_plane, df_theta,locator=ticker.LogLocator(),cmap=cm.cool)\n",
    "cbar = fig.colorbar(cs)\n",
    "ax.set_xlim(-800,0)\n",
    "ax.set_ylim(-500,500)\n",
    "ax.set_xlabel('$v_\\parallel$ km/s')\n",
    "ax.set_ylabel('$v_\\perp2$ km/s')\n",
    "ax.set_title('VDF FAC coordinates')\n",
    "\n",
    "fig,ax=plt.subplots()\n",
    "cs=ax.contourf(vx_plane_theta, vz_plane_theta, df_theta,locator=ticker.LogLocator(),cmap=cm.cool)\n",
    "cbar = fig.colorbar(cs)\n",
    "ax.set_xlim(-800,0)\n",
    "ax.set_ylim(-500,500)\n",
    "ax.set_xlabel('vx km/s')\n",
    "ax.set_ylabel('vz km/s')\n",
    "ax.set_title('VDF SPAN-I instrument coordinates')\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we can put it all together into a single plotting script where all we input is the timestamp:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def spp_swp_spi_VDF_plot(timeslice):\n",
    "\n",
    "    #!pip install wget\n",
    "    import wget\n",
    "    import cdflib\n",
    "    import numpy as np\n",
    "    from datetime import datetime\n",
    "    import os.path\n",
    "    import bisect\n",
    "    import matplotlib.pyplot as plt\n",
    "\n",
    "    from matplotlib import ticker, cm\n",
    "    import warnings \n",
    "    warnings.filterwarnings(\"ignore\")\n",
    "\n",
    "\n",
    "    from warnings import simplefilter \n",
    "    simplefilter(action='ignore', category=DeprecationWarning)\n",
    "    \n",
    "    year  = timeslice.year\n",
    "    month = timeslice.month\n",
    "    day   = timeslice.day\n",
    "    \n",
    "    if len(str(month)) < 2:\n",
    "        month = '0'+str(month)\n",
    "\n",
    "    \n",
    "    #This is not the best way to do this, but it should at least work (for a while, anyway)\n",
    "    versionList = ['09', '08', '07', '06', '05', '04', '03', '02', '01', '00']\n",
    "\n",
    "    versionTest = 'notFound'\n",
    "    for version in versionList:\n",
    "        if versionTest == 'notFound':\n",
    "            VDfile_directoryRemote = f'http://w3sweap.cfa.harvard.edu/pub/data/sci/sweap/spi/L2/spi_sf00/{year}/{month}/'\n",
    "            VDfile_filename = f'psp_swp_spi_sf00_L2_8Dx32Ex8A_{year}{month}{day}_v{version}.cdf'\n",
    "            \n",
    "            \n",
    "            if os.path.isfile(VDfile_filename):\n",
    "                print(\"Version {version} exists\")\n",
    "                VDfile = VDfile_filename\n",
    "                versionTest = 'found'\n",
    "            else:\n",
    "                try:\n",
    "                    #print(f\"Version {version} doesn't exist locally, searching online..\")\n",
    "                    VDfile = wget.download(VDfile_directoryRemote + VDfile_filename)\n",
    "                    versionTest = 'found'\n",
    "                    print(f'Grabbed version {version}')\n",
    "                except:\n",
    "                    continue\n",
    "        elif versionTest == 'found':\n",
    "            break\n",
    "          \n",
    "\n",
    "    cdf_VDfile = cdflib.CDF(VDfile)\n",
    "\n",
    "    epoch           = cdf_VDfile['Epoch']\n",
    "    theta           = cdf_VDfile['THETA']\n",
    "    phi             = cdf_VDfile['PHI']\n",
    "    energy          = cdf_VDfile['ENERGY']\n",
    "    eflux           = cdf_VDfile['EFLUX']\n",
    "    rotMat          = cdf_VDfile['ROTMAT_SC_INST']\n",
    "    \n",
    "    import datetime\n",
    "    datetime_t0 = datetime.datetime(2000, 1, 1, 12, 0, 0)\n",
    "    epoch = cdflib.cdfepoch.to_datetime(cdf_VDfile.varget('Epoch'))\n",
    "\n",
    "    print('Desired timeslice:',timeslice)\n",
    "    tSliceIndex  = bisect.bisect_left(epoch, timeslice)\n",
    "    print('time Index:',tSliceIndex)\n",
    "    print('Time of closest data point:',epoch[tSliceIndex])\n",
    "\n",
    "    epochSlice  = epoch[tSliceIndex]\n",
    "    thetaSlice  = theta[tSliceIndex,:]\n",
    "    phiSlice    = phi[tSliceIndex,:]\n",
    "    energySlice = energy[tSliceIndex,:]\n",
    "    efluxSlice  = eflux[tSliceIndex,:]\n",
    "\n",
    "    thetaReshaped = thetaSlice.reshape((8,32,8))\n",
    "    phiReshaped = phiSlice.reshape((8,32,8))\n",
    "    energyReshaped = energySlice.reshape((8,32,8))\n",
    "    efluxReshaped = efluxSlice.reshape((8,32,8))\n",
    "\n",
    "    mass_p = 0.010438870      #eV/c^2 where c = 299792 km/s\n",
    "    charge_p = 1              #eV\n",
    "\n",
    "    #Define VDF\n",
    "    numberFlux = efluxReshaped/energyReshaped\n",
    "    vdf = numberFlux*(mass_p**2)/((2E-5)*energyReshaped)\n",
    "\n",
    "    #Convert to velocity units in each energy channel\n",
    "    vel = np.sqrt(2*charge_p*energyReshaped/mass_p)\n",
    "\n",
    "    vx = vel * np.cos(np.radians(phiReshaped)) * np.cos(np.radians(thetaReshaped))\n",
    "    vy = vel * np.sin(np.radians(phiReshaped)) * np.cos(np.radians(thetaReshaped))\n",
    "    vz = vel *                                   np.sin(np.radians(thetaReshaped))\n",
    "\n",
    "\n",
    "    thetaplot_cut = 0\n",
    "    phiplot_cut = 2\n",
    "\n",
    "    #phi_avg = np.nanmean(phiReshaped,axis=thetaplot_cut)\n",
    "    #theta_avg = np.nanmean(thetaReshaped,axis=thetaplot_cut)\n",
    "    #energy_avg=np.nanmean(energyReshaped,axis=thetaplot_cut)\n",
    "\n",
    "    phi_plane = phiReshaped[0,:,:]\n",
    "    theta_plane = thetaReshaped[0,:,:]\n",
    "    energy_plane = energyReshaped[0,:,:]\n",
    "    vel_plane = np.sqrt(2*charge_p*energy_plane/mass_p)\n",
    "\n",
    "    df=np.nansum(vdf,axis=thetaplot_cut)\n",
    "    \n",
    "\n",
    "    vx_plane = vel_plane * np.cos(np.radians(phi_plane)) * np.cos(np.radians(theta_plane))\n",
    "    vy_plane = vel_plane * np.sin(np.radians(phi_plane)) * np.cos(np.radians(theta_plane))\n",
    "    vz_plane = vel_plane *                                   np.sin(np.radians(theta_plane))\n",
    "\n",
    "    fig,ax=plt.subplots()\n",
    "    cs=ax.contourf(vx_plane, vz_plane, df,locator=ticker.LogLocator(),cmap=cm.cool)\n",
    "    cbar = fig.colorbar(cs)\n",
    "    cbar.set_label(f'f $(cm^2 \\\\ s \\\\ sr \\\\ eV)^{-1}$')\n",
    "\n",
    "    ax.set_xlim(-700,0)\n",
    "    ax.set_ylim(-500,500)\n",
    "    ax.set_xlabel('$v_x$ km/s')\n",
    "    ax.set_ylabel('$v_z$ km/s')\n",
    "    ax.set_title('VDF SPAN-I $\\\\theta$-plane')\n",
    "\n",
    "    ax.set_title('VDF SPAN-I $\\\\theta$-plane '+epoch[tSliceIndex].isoformat(timespec='seconds'))\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "\n",
    "import datetime\n",
    "# datetime(YYYY, mm, dd, HH, MM)\n",
    "timeSlice  = datetime.datetime(2020, 1, 29, 18, 10, 2)   # Original test slice  \n",
    "\n",
    "spp_swp_spi_VDF_plot(timeSlice)\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.8.3 ('pyspedas')",
   "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.8.3"
  },
  "vscode": {
   "interpreter": {
    "hash": "5877fce38de90c1fb6dffa61cadcfee3c47ad77488053f147fda735568ebc1ad"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}