=====================================
UNITOV Catalogue of geoeffective CMEs
=====================================

.. contents:: Table of contents

A database associating L1 Time of Arrival and Speed of an interplanetary CME to the kinematic characteristics of the corresponding CME, covering the period 1996-2020.

References
~~~~~~~~~~



Dataset summary
~~~~~~~~~~~~~~~

.. list-table::

  * - **internal_name:**
    - unitov_icme_tableset
  * - **publisher:**
    - University of Rome Tor Vergata Dept. of Physics
  * - **alph_code:**
    - 15
  * - **id_tmp:**
    - 44
  * - **short_name:**
    - UNITOV-ICME
  * - **identifier:**
    - aspis:/unitov/icme_tableset
  * - **dynamic:**
    - +10kB updated every year
  * - **size:**
    - 100kB
  * - **format:**
    - csv
  * - **type:**
    - tableset
  * - **records_number:**
    - 213
  * - **time_start:**
    - 1997-01-01
  * - **time_stop:**
    - 2019-12-31
  * - **spatial:**
    - IP
  * - **messenger:**
    - Photons,Protons
  * - **spectral_min:**
    - 0
  * - **spectral_max:**
    - 0
  * - **spectral_units:**
    - 
  * - **observable:**
    - {CME, SW}
  * - **latest update:**
    - 2024-05-16 06:11:43

Columns specification
~~~~~~~~~~~~~~~~~~~~~

.. list-table:: 
   :widths: 7 20 15 10 48
   :align: right 
   :header-rows: 1

   * - progr
     - column
     - units
     - type
     - description
   * - 1
     - time
     - UTC
     - datetime
     - datetime (1997-01-06T16:23:38) - time of the first detection of the CME in LASCO FoV
   * - 2
     - HPC_Tx
     - arcsec
     - float
     - arcsec (25.21) - Helioprojective Cartesian Longitutude: the angle relative to the plane containing the Sun-observer line and the Sun’s rotation axis, with positive values in the direction of the Sun’s west limb
   * - 3
     - HPC_Ty
     - arcsec
     - float
     - arcsec (-3.22) - Helioprojective Cartesian Latitude: the angle relative to the Sun’s equatorial plane, with positive values in the direction of the Sun’s north pole
   * - 4
     - HPC_distance
     - AU
     - float
     - AU (0.98) - the Sun-observer distance
   * - 5
     - CME_num
     - index
     - int
     - index (1) - progressive number
   * - 6
     - Start_Date
     - UTC
     - datetime
     - datetime (1997-01-06 16:23:38.000) - extimated time of the CME passage at 20 R_Sun
   * - 7
     - Arrival_Date
     - UTC
     - datetime
     - datetime (1997-01-06 16:23:38.000) - time of the CME passage at L1
   * - 8
     - PE_duration
     - hours
     - float
     - hours (22.0) - ICME Plasma Event duration at L1
   * - 9
     - Arrival_v
     - km/s
     - int
     - km/s (450) - measured velocity of the CME at L1
   * - 10
     - Transit_time
     - hours
     - float
     - hours (98.3) - time elapsed from the Start_Date and Arrival_Date
   * - 11
     - Transit_time_err
     - hours
     - float
     - hours (98.3) - error associated to the extimated transit time
   * - 12
     - LASCO_Date
     - UTC
     - datetime
     - datetime (1997-01-06 16:23:38.000) - time of the first detection of the CME in LASCO FoV
   * - 13
     - LASCO_v
     - km/s
     - int
     - km/s (459.5) - plane-of-sky velocity of the CME from LASCO images
   * - 14
     - LASCO_pa
     - deg
     - int
     - deg (263.0) - CME principal angle, counterclockwise from North
   * - 15
     - LASCO_da
     - deg
     - int
     - deg (165.0) - CME angular width
   * - 16
     - LASCO_halo
     - char
     - char
     - string (N/PH/HH/FH) - indicating halo/partial halo CME
   * - 17
     - v_r
     - km/s
     - float
     - km/s (705.35) - estimated radial velocity of the CME
   * - 18
     - v_r_err
     - km/s
     - float
     - km/s (104.89) - error associated to the radial velocity of the CME
   * - 19
     - Theta_source
     - arcsec
     - float
     - arcsec (14.92) - longitude of the most probable source of the CME on the solar disk
   * - 20
     - Phi_source
     - arcsec
     - float
     - arcsec (-25.97) - co-latitude of the most probable source of the CME on the solar disk
   * - 21
     - source_err
     - arcsec
     - float
     - arcsec (20.0) - uncertainty on the source location on the solar disk
   * - 22
     - POS_source_angle
     - deg
     - float
     - deg (64.60) - plane-of-sky angle of the source region of the CME
   * - 23
     - rel_wid
     - rad
     - float
     - rad (0.5585) - estimated deprojected CME angular width
   * - 24
     - Mass
     - g
     - float
     - g (1.8e+16) - Estimated mass of the CME
   * - 25
     - SW_type
     - char
     - char
     - char (F/S) - Solar wind type (Fast/Slow) for the ICME propagation
   * - 26
     - Bz
     - nT
     - int
     - nT (16) - z-component of the ICME magnetic field at L1
   * - 27
     - DST
     - nT
     - int
     - nT (-68.0) - minimum DST during ICME event at L1
   * - 28
     - v_r_stat
     - km/s
     - float
     - km/s (544.73) - statistical de-projection of the CME POS speed
   * - 29
     - Accel.
     - m/s^2
     - float
     - m/s^2 (8.9076) - CME acceleration between the lift-off and 20 solar radii
   * - 30
     - Analyitic_w
     - km/s
     - float
     - km/s (395.56) - solar wind value obtained via analytic inversion of the DBM equations
   * - 31
     - Analyitic_gamma
     - km^-1
     - float
     - km^-1 (3.5029e-06) -value of the drag parameter obtained via analytic inversion of the DBM equations
   * - 32
     - filename
     - char
     - char
     - string (CME_0111_param_inv.txt ) - name of the file containing PDBM information from the statistical inversion procedure

Code example
~~~~~~~~~~~~

``"""``

``This is an example script for accessing client-side ASPIS datasets.``

``The client is provided by the ASPISpy package and in particular the connection is resolved by the CaesarAPI class.``

``This example code allows the user to fetch a product from the ASPIS DB and``

``save it in a ready-to-use pandas.DataFrame structure.``

``To use this code to fetch another product, simply change``

``the product name and possibly the time range and columns of the dataset``

``(for the filtered_search method).``

``Notes:``

``- The CaesarAPI class provides a complete interface to the ASPIS DB through several methods,``

``each of which corresponds to a different API endpoint.``

``- Once CaesarAPI has been instantiated through authentication, the user can call the different methods``

``(e.g., CaesarAPI.download_data, CaesarAPI.filtered_search, etc. etc.).``

``- The import and initialization are the same for each code fragment.``

``"""``

``#### The following lines of code should be executed only once``

``#### during session initialization. If they are re-executed,``

``#### the session in ASPIS DB is recreated from scratch.``

``#### Once the session is initialized, the user can use of all``

``#### the methods provided by the CaesarAPI class.``

``import ASPISpy.aspis as aps``

``import pandas as pd``

``# The following lines to disable SSL certificate warning.``

``# Note: In this prototype version, the certificate is not available``

``import requests``

``from requests.packages.urllib3.exceptions import InsecureRequestWarning``

``requests.packages.urllib3.disable_warnings(InsecureRequestWarning)``

``# Initialize the CaesarAPI connector``

``api = aps.CaesarAPI(credentials={'email': '<your_email>','password': '<your_password>'})``

``# [INFO] user <your_email> authenticated``

``# Define the product to be fetched``

``product_name = "unitov_icme_tableset"``

``# FETCH THE FULL DATASET``

``r, df = api.get_product_detail(product_name)``

``# r is the full response of the request, df is the pandas.DataFrame``

``# which contains the dataset.``

``# > print(df.head())``

``#     id                 time     HPC_Tx     HPC_Ty  HPC_distance  CME_num  ...``

``# 0   0  1997-01-06T15:10:42  25.210143  -3.221796      0.983319        1   ...``

``# 1   1  1997-02-07T00:30:05  53.055793  -7.993757      0.986300        2   ...``

``# 2   2  1997-04-07T14:27:44  14.917489 -25.972924      1.001209        3   ...``

``# 3   3  1997-05-12T05:30:05   6.568649  21.393300      1.010308        4   ...``

``# 4   4  1997-05-21T21:00:53 -63.993601 -35.996400      1.012279        5   ...``

``# FETCH A SUBSET of <product_name>``

``df = api.filtered_search(prod_id=product_name,filters=['time < 2005-01-01','time > 2000-01-01'],cols=['time','bz','dst','v_r'],return_dataframe=True)``

``# [INFO] Executing the following query:``

``#     query MyQuery {``

``#       filtered_search(filters: [{field: "time", operator: "lt", value: "2005-01-01"}{field: "time", operator: "gt", value: "2000-01-01"}]) {``

``#         ... on UnitovIcmeTablesetType {``

``#           time``

``#           bz``

``#           dst``

``#           v_r``

``#         }``

``#       }``

``#     }``

``# > print(df.head())``

``#                   time  bz  dst      v_r``

``# 0  2000-01-18T17:54:05  16  -97  1132.60``

``# 1  2000-02-08T09:30:05   7  -25  1364.00``

``# 2  2000-02-10T02:30:05  13 -133  1097.20``

``# 3  2000-02-12T04:31:20   5  -67  1286.90``

``# 4  2000-02-17T19:31:23  15  -26   566.07``

``
``

