time_series.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "5d1aaa53-884e-48a8-a898-17a7f78205b2",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Plotting time series in ARTop\n",
    "\n",
    "Time series in ARTop are based on Pandas DataFrames (https://pandas.pydata.org/) which are highly portable. Here we present some examples of the time series functionality in ARTop.\n",
    "\n",
    "\n",
    "The time series variables in ARTop have the names:\n",
    "\n",
    "```\n",
    "windCur   : current-carrying part of winding rate (km^4/s)\n",
    "helCur    : current-carrying part of field line helicity rate (Gauss^2km^4/s)\n",
    "windPot   : potential part of winding rate (km^4/s)\n",
    "helPot    : potential part of helicity rate (Gauss^2km^4/s)\n",
    "windBraid : braiding component of winding rate (km^4/s)\n",
    "helBraid  : braiding component of helicity rate (Gauss^2km^4/s)\n",
    "wind      : total winding rate (km^4/s)\n",
    "hel       : total helicity rate (Gauss^2km^4/s)\n",
    "dL        : delta winding rate (km^4/s)\n",
    "dH        : delta helicity rate (Gauss^2km^4/s)\n",
    "```\n",
    "\n",
    "These are stored in a Pandas DataFrame, and each variable is accessed using one of the above keys. \n",
    "\n",
    "\n",
    "For time-integrated versions of these variables (see Example 1), `_int` is added to every variable name.\n",
    "\n",
    "For running mean and envelope calculations (see Example 2), `_ms` is added to every variable name.\n",
    "\n",
    "Example variables are included below, but you should adapt them for the data you have."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dcc9ef84-2461-4f16-9a02-6ebce25bd58a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Example 1: Plot the time series of a time-integrated quantity\n",
    "import os\n",
    "import sys\n",
    "cwd = os.getcwd()\n",
    "sys.path.insert(1, os.path.join(cwd,'source','python'))    # If your version of analysis.py is in another location, change this path.\n",
    "from analysis import *\n",
    "\n",
    "# Get the data.\n",
    "outputDir = os.path.join(cwd,'output')                                        # Set the output directory (containing the Data folder and *.txt).\n",
    "raw_series = readSeries(outputDir)                                            # Load the time series of all the basic ARTop time series variables.\n",
    "accum = integrate_series(raw_series)                                          # Create accumulations of the raw variables, i.e. integrate in time.\n",
    "time = accum['times(seconds)']                                                # Get the times (in seconds) from the relevant DataFrame.\n",
    "\n",
    "\n",
    "# Plot the data\n",
    "var = [accum['dL_int']]                                                       # Choose the variable to be plotted.\n",
    "colour = ['r-']                                                               # The colour of the time series.\n",
    "label = ['$\\delta$L']                                                         # Set the label (variables that begin with an underscore will not be shown).\n",
    "y_label = r'$\\delta$L'+' '+ '$(km^4)$'                                        # Set the label of the y-axis.\n",
    "title = ' '                                                                   # Set the title. This must be set but put ' ' if no title is wanted. \n",
    "\n",
    "plot(time, var, colour,label,y_label,title,unit='h')                          # Plot the time series with time in hours on the x-axis.\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6109d07e-c1f0-4cd0-8761-f097b7578b2a",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Example 2: Overplot a time series with a running mean plus envelope and flare times.\n",
    "\n",
    "import os\n",
    "import sys\n",
    "cwd = os.getcwd()\n",
    "sys.path.insert(1, os.path.join(cwd,'source','python'))    # If your version of analysis.py is in another location, change this path.\n",
    "from analysis import *\n",
    "\n",
    "# Get the time series data.\n",
    "outputDir = os.path.join(cwd,'output')                                             # Set the output directory (containing the Data folder and *.txt).\n",
    "raw_series = readSeries(outputDir)                                                 # Load the time series of all the basic ARTop time series variables.\n",
    "offset = 3                                                                         # The offset (in time dumps) for calculating the running mean.  \n",
    "num_std = 3                                                                        # The height (number of standard deviations) of the envelope above the running mean.\n",
    "mean = running_mean_std(raw_series,offset,0)                                       # Calculate the running mean.\n",
    "env = running_mean_std(raw_series,offset,num_std)                                  # Calculate the envelope. \n",
    "\n",
    "# Get the flare times from NOAA reports.\n",
    "start_time = '2011-02-10 10:00:00'                                                 # Choose the start time.\n",
    "end_time = '2011-02-19 06:00:00'                                                   # Choose the end time.\n",
    "variable = 'FLA'                                                                   # Choose the variable to read (FLA for flare, XRA for X-ray) \n",
    "activeregion = 'AR11158'                                                           # Set the NOAA active region number. \n",
    "time_col = 'Begin'                                                                 # Select the Begin, Max or End. \n",
    "\n",
    "report = flare_times(start_time,end_time)                                          # Download the NOAA reports from the specified period.\n",
    "\n",
    "                       \n",
    "FL = report.toseconds(activeregion, variable, time_col)                            # Get the flare times in seconds (for overplotting). Note that the start time corresponds to t=0.\n",
    "\n",
    "# Plot the data\n",
    "\n",
    "time = raw_series['times(seconds)']                                                # Get the times (in seconds).\n",
    "overplot_variables = [raw_series['dL'], mean['dL_ms'], env['dL_ms']]               # List the variables to be overplotted.   \n",
    "colour = ['c-','r-','b:']                                                          # Select colours for the different curves.\n",
    "label = ['$\\dot{\\delta L}$', '$\\mu(\\dot{\\delta L})$', '$\\mu+3\\sigma$']             # Label the time series variables\n",
    "y_label = '$\\dot{\\delta L}$ (km$^4$/s)'                                            # Label the y-axis.\n",
    "title = ' '                                                                        # Set a plot title \n",
    "plot(time, overplot_variables, colour,label,y_label, title ,unit='h',oplot=[FL])\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e3fc0ff3-a0bd-4eb2-b0a5-cedc59f1c439",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Example 3: Displaying flare reports\n",
    "\n",
    "# This example shows what can be read from the NOAA reports and how it is structured for plotting within ARTop.\n",
    "\n",
    "import os\n",
    "import sys\n",
    "cwd = os.getcwd()\n",
    "sys.path.insert(1, os.path.join(cwd,'source','python'))    # If your version of analysis.py is in another location, change this path.\n",
    "from analysis import *\n",
    "\n",
    "# Get the flare times from NOAA reports.\n",
    "start_time = '2011-02-10 10:00:00'                                                 # Choose the start time.\n",
    "end_time = '2011-02-19 06:00:00'                                                   # Choose the end time.\n",
    "variable1 = 'FLA'                                                                  # Choose the FLA flare time option. \n",
    "variable2 = 'XRA'                                                                  # Choose the GOES X-ray option.  \n",
    "activeregion = 'AR11158'                                                           # Set the NOAA active region number. \n",
    "time_col = 'Begin'                                                                 # Select the Begin, Max or End. \n",
    "\n",
    "report = flare_times(start_time,end_time)                                          # Download the NOAA reports from the specified period.\n",
    "FL = report.toseconds(activeregion, variable1, time_col)                           # Get the flare times in seconds.\n",
    "XR = report.toseconds(activeregion, variable2, time_col)                           # Get the GOES X-ray times in seconds.\n",
    "\n",
    "print(FL)                                                                          # Display the results. Colours correspond to how ARTop plots these quantities.  \n",
    "print(XR)\n",
    "# Note that the start time corresponds to t=0."
   ]
  }
 ],
 "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.9.15"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}