- - - - - - - - - - - - - - - - - - - - - - - - - - - - 
Purpose: 
    This is the README and guide for the data 
    repository referenced in the publication ‘Event 
    List for Interchange Injections 
    at Saturn: Statistical Survey of Energetic H+ 
    Sudden Flux Intensifications’ by A. R. Azari,
    M. W. Liemohn, X. Jia, M. F. Thomsen, 
    D. G. Mitchell, N. Sergis, A. M. Rymer, G. B. 
    Hospodarsky, C. Paranicas, and J. Vandegriff.

Repository Created by: 
    A. R. Azari, University of Michigan. 
    Department of Climate & Space 
    Sciences & Engineering.
    4/17/2018

Contact Information: 
    azari@umich.edu

Related Data and Acknowledgements: 
    This work is the dataset presented in 
    Azari et al. (2018) - ‘Interchange Injections at 
    Saturn: Statistical Survey of Energetic H+ 
    Sudden Flux Intensifications’. It can be found at   
    https://doi.org/10.1029/2018JA025391. 
    Please see within this work for further 
    details on the methodology. 

    Cassini CHEMS data used to develop this event list 
    can be found on the NASA Planetary Data System.

    Further details on CHEMS data can be found within
    Vandegriff, et al. (2013) - the Cassini / MIMI 
    Instrument Data User Guide.  

    If using any of the comparison columns (see notes 
    on events_CORRECTED.txt), please also accredit the producers
    of the previous surveys. Details can be found 
    below.

Research Summary: 
    We present a statistical study of interchange 
    injections in Saturn's inner and middle 
    magnetosphere focusing on the dependence of 
    occurrence rate and properties on radial distance, 
    partial pressure, and local time distribution. 
    Events are evaluated from over the entirety of the 
    Cassini mission’s equatorial orbits between 2005 
    and 2016. We identified interchange events from 
    CHarge Energy Mass Spectrometer (CHEMS) H+ data 
    using a trained and tested automated algorithm, 
    which has been compared with manual event 
    identification for optimization. We provide 
    estimates of interchange based on intensity, which 
    we use to investigate current inconsistencies in 
    local time occurrence rates. This represents the 
    first automated detection method of interchange, 
    estimation of injection event intensity, and 
    comparison between interchange injection survey 
    results. We find the peak rates of interchange 
    occur between 7 - 9 Saturn radii and that this 
    range coincides with the most intense events as 
    defined by H+ partial particle pressure. We 
    determine that nightside occurrence dominates as 
    compared to the dayside injection rate, supporting 
    the hypothesis of an inversely dependent 
    instability growth rate on local Pedersen 
    ionospheric conductivity. Additionally, we observe 
    a slight preference for intense events on the dawn 
    side, supporting a triggering mechanism related to 
    large-scale injections from downtail reconnection. 
    Our observed local time dependence paints a dynamic 
    picture of interchange triggering due to both the 
    large-scale injection driven process and 
    ionospheric conductivity.

Funding Information:
    A. R. Azari was supported by the NASA Earth and  
    Space Science Fellowship Program – Grant 
    NNX15AQ63H and the NSF Graduate Research 
    Fellowship Program under Grant No. DGE 1256260. 
    Additional support for Michigan co-authors of 
    the related work came from NASA under grants 
    NNX15AH28G, 80NSSC17K0015, and NNX17AB87G. 
    Support for co-authors at the University of 
    Iowa was supported by NASA through contract 
    1415150 with the Jet Propulsion Laboratory 
    (JPL). M. F. Thomsen was supported by the NASA 
    Cassini program through JPL contract 1243218 
    with Southwest Research Institute. 

Contents of the Repository:
    1.  events_CORRECTED.txt (replaces events.txt)
    2.  README.rtf
    3.  LICENSE.rtf

- - - - - - - - - - - - - - - - - - - - - - - - - - - - 
events_CORRECTED.txt
- - - - - - - - - - - - - - - - - - - - - - - - - - - - 
The file events_CORRECTED.txt contains the full 816 H+ flux intensifications identified against the background from reviewing the CHEMS H+ intensity data between 3 - 22 keV from the Cassini spacecraft mission. This data exists as a comma separated text file. To prevent automatic conversions of the date time format we encourage opening in a text editor.

These intensification periods (interchange injection events) have been identified through the use of an algorithm in which the performance is detailed within the associated publication.

We recommend reading in this text file directly into a Python pandas data frame as this is how the file was generated.

This file supersedes events.txt as of July 31, 2018. The original events.txt uploaded May 9th, 2018 contains a duplication error in the last column, in which InAllSurveys is presented as a duplicate of the column InAnySurvey. This was corrected and a replacement uploaded on July 31, 2018.

The file contains the following values:

COLUMN NAME      DESCRIPTION             UNITS

EventID           Unique identifier       N/A
StartTime         Event start             Universal Time 
StopTime          Event stop              Universal Time 
AvrgSZS_X         Average location (SZS)  Saturn Radii 
AvrgSZS_Y         Average location (SZS)  Saturn Radii 
AvrgSZS_Z         Average location (SZS)  Saturn Radii 
AvrgLT            Average Local time (LT) LT hour
AvrgPhi           Angle from SZS-equator  Degrees            
Classification    Ranking of intensity    (see notes)
DerivedWidth      Width (see notes)       Saturn Radii 
DerivedWidth_Err  Error (see notes)       Saturn Radii
InAnySurvey       If found in other works (see notes)        
InAllSurveys      If found in all works   (see notes)

Average Value and Time Notes:
    Average values are calculated over the duration of   
    the event time. 

    Times are presented to the nearest minute in 
    Universal Time (UT). 

Classification Value Notes:
    The classification value ranges from 1 to 4, with 
    the most intense events rated as 4 and least 
    intense rated as 1. These values are calculated 
    against a background intensity distribution that 
    depends on energy, time period, and radial 
    location.
    
    The values range as follows:
    - Category 1: 0.9 - 1.5 standard deviations above 
                            background   
    - Category 2: 1.5 - 2.0  ‘’
    - Category 3: 2.0 - 3.0  ‘’
    - Category 4: > 3.0      ‘’

These are optimized to maximize event detection as described in the associated work.

DerivedWidth & DerivedWidth_Err Notes:

These values are calculated based off of the work done in:

  Thomsen, M. F., D. B. Reisenfeld, D. M. Delapp, R. L. 
  Tokar, D. T. Young, F. J. Crary, E. C. Sittler, M.  
  A. McGraw, and J. D. Williams (2010), Survey of ion 
  plasma parameters in Saturn’s magnetosphere, J. 
  Geophys. Res., 115, A10220,doi:10.1029/2010JA015267.

We estimate the width and propagate the error based off Thomsen et al., 2010 (Figure 16). We encourage these to be used as estimations of the actual event width as the exact morphology of the instability regions is still an active area of research at the time of writing (2018). 

Comparison to Previous Survey Notes:
   The columns InAnySurvey and InAllSurveys are based 
   off of three previous surveys.
      1) Kennelly, T. J., J. S. Leisner, G. B. 
         Hospodarsky, and D. A. Gurnett (2013), 
         Ordering of injection events within 
         Saturnian SLS longitude and local time, J. 
         Geophys. Res. Space Physics, 118, 832–838, 
         doi:10.1002/jgra.50152.

      2) Lai, H. R., C. T. Russell, Y. D. Jia, H. Y. 
         Wei, and M. K. Dougherty (2016), Transport of 
         magnetic ﬂux and mass in Saturn’s inner 
         magnetosphere, J. Geophys. Res. Space Physics,  
         121, 3050–3057, doi:10.1002/2016JA022436.

      3) Chen, Y., and T. W. Hill (2008), Statistical   
         analysis of injection/dispersion events in 
         Saturn’s inner magnetosphere, J. Geophys. 
         Res., 113, A07215, doi:10.1029/2008JA013166.

	These former works produced event lists over  
    subsections of the Cassini mission (time, radial 
    location, etc) and used different instruments 
    onboard Cassini than CHEMS. Our survey was
    developed using CHEMS.

    Within these columns we provide a comparison to  
    these event surveys. If the integer value in these 
    columns is:

	    NaN: then the lists were not 
             comparable (for example outside 
             of time range or spatial range of 
             previous surveys). 

        1:   then the event has at least one duplicate  
             in a survey (InAnySurvey) or all surveys 
             have found this event (InAllSurveys). 

        0:   there is no duplicate event(s) found in 
             the surveys.

Description of coordinate systems:
    The Saturn Equatorial System (SZS) is defined  
    wherein the Z-axis is the Saturn spin axis, the 
    Y-axis is the Z-axis cross Saturn to Sun Line, 
    and the X-axis is Y x Z.

    Local time is a coordinate system used in space 
    physics to denote azimuthal location wherein 
    towards the sun is noon, or 1200 and away is 0000. 
    It ranges from 0000 up to but not including 2400. 

Limitations of Usage: 

    Location: 
             Flux intensifications are only identified 
             from +/- 10 degrees off the equatorial 
             plane in SZS and between 5 and 12 Saturn 
             Radii (1 Rs = 60,268 KM).
    Format:  
             If you would prefer a different format or 
             more events attributes discussed within 
             the associated work please contact 
             the data providers. 
    Time: 
             Due to the low time resolution of the 
             CHEMS instrument as compared to others on  
             board the Cassini spacecraft we encourage 
             users to use these times as general start 
             and stop times. The event times identified  
             have been rounded to the nearest minute in 
             this data list. See discussion in 
             Azari et al., 2018.
    Width:
             Due to the time resolution and the 
             uncertainty in the azimuthal velocity 
             profile of the H+ at Saturn we encourage 
             users to use these widths as an estimation 
             of the scale size given the discussion 
             in Azari et al., 2018 and 
             Thomsen et al.,2010.
    Quality: 
             When using this list we encourage you to 
             review the associated publication for 
             discussion of accuracy or to contact the 
             authors. 
             
             Consider using high category events for  
             increased accuracy as these flux 
             intensifications are far above the 
             background values.
             
             Additionally as discussed within Azari et  
             al., 2018 we find our detection of false 
             positives to rise between 11 and 12 Rs and 
             we identify H+ intensifications which we 
             do not attribute to interchange but other 
             physical processes. We recommend treating 
             events between 11 and 12 Rs with care. 

- - - - - - - - - - - - - - - - - - - - - - - - - - - - 
LICENSE.rtf, Usage, and Relevant Citations
- - - - - - - - - - - - - - - - - - - - - - - - - - - - 
This event list is licensed under a a Creative Commons 
Attribution-NonCommercial-ShareAlike 4.0 International Public License. 

The procedures used in creating this data can be found within the associated work and when using this list we urge you to acknowledge the following source(s) when data is utilized for a publication.
 
- Azari, A. R., M. W. Liemohn, X. Jia, M. F. Thomsen,
  D. G. Mitchell, N. Sergis, A. M. Rymer, G. B. 
  Hospodarsky, C. Paranicas, & J. Vandegriff (2018),
  Interchange Injections at Saturn: Statistical Survey 
  of Energetic H+ Sudden Flux Intensifications. Journal 
  of Geophysical Research: Space Physics, 123. https://
  doi.org/10.1029/2018JA025391.

If using columns DerivedWidth or DerivedWidth_Err also acknowledge:

- Thomsen, M. F., D. B. Reisenfeld, D. M. Delapp, R. L. 
  Tokar, D. T. Young, F. J. Crary, E. C. Sittler, M. A.   
  McGraw, & J. D. Williams (2010), Survey of ion plasma 
  parameters in Saturn’s magnetosphere, J. Geophys. 
  Res., 115, A10220, doi:10.1029/2010JA015267.

If using columns InAnySurvey and InAllSurveys also acknowledge:

- Kennelly, T. J., J. S. Leisner, G. B. Hospodarsky, & 
  D. A. Gurnett (2013), Ordering of injection events 
  within Saturnian SLS longitude and local time, J. 
  Geophys. Res. Space Physics, 118, 832–838, 
  doi:10.1002/jgra.50152.

- Lai, H. R., C. T. Russell, Y. D. Jia, H. Y. Wei, & 
  M. K. Dougherty (2016), Transport of magnetic ﬂux and 
  mass in Saturn’s inner magnetosphere, J. Geophys. 
  Res. Space Physics, 121, 3050–3057, 
  doi:10.1002/2016JA022436.

- Chen, Y. and T. W. Hill (2008), Statistical analysis 
  of injection/dispersion events in Saturn’s inner 
  magnetosphere,J. Geophys. Res., 113, A07215, 
  doi:10.1029/2008JA013166.

Please contact us with any questions on the usage and details of the detection methods.