cdasws Example Jupyter Notebook

This Jupyter notebook demonstrates using the cdasws Python package to access NetCDF data from cdaweb with the data returned in the xarray.Dataset. This notebook contains the following sections:

1. Prerequisites
2. Setup
3. Get Observatory Groups
4. Get Datasets
5. Get Dataset Variables
6. Get Data
7. Display Metadata
8. Plot Values
9. Additional Documentation

Notes:

1. This example only depends upon pure Python modules and does not require modules that depend upon non-Python code (such as spacepy and pycdf).
2. The use of the dataRepresentation keyword parameter below is only necessary if you also have spacepy installed.
3. It also is possible to have the data returned in a SpasePy data model instead of an xarrayDataset.

Prerequisites

Install the prerequisite software from the Python Package Index if it is not already installed.

#%pip install xarray
#%pip install cdflib
#%pip install cdasws

Setup

Execute some preliminary code that is necessary before the code that follows.

from cdasws import CdasWs
from cdasws.datarepresentation import DataRepresentation as dr
import matplotlib.pyplot as plt
cdas = CdasWs()

Get Observatory Groups

The following code demonstrates how to get the available observatory groups.

obs_groups = cdas.get_observatory_groups()
for index, obs_group in enumerate(obs_groups):
    obs_group_name = obs_group['Name']
    if 'ICON' in obs_group_name:
        print(obs_group_name)

ICON

Get Datasets

The following code demontrates how to get a list of datasets.

datasets = cdas.get_datasets(observatoryGroup='ICON')
for index, dataset in enumerate(datasets):
    print(dataset['Id'], dataset['Label'])

ICON_L2-1_MIGHTI-A_LOS-WIND-GREEN Michelson Interferometer for Global High-resolution Thermospheric Imaging (MIGHTI) Sensor A: Line-of-sight Wind Profiles - T. J. Immel (UC Berkeley>SSL)
ICON_L2-1_MIGHTI-A_LOS-WIND-RED Michelson Interferometer for Global High-resolution Thermospheric Imaging (MIGHTI) Sensor A: Line-of-sight Wind Profiles - T. J. Immel (UC Berkeley>SSL)
ICON_L2-1_MIGHTI-B_LOS-WIND-GREEN Michelson Interferometer for Global High-resolution Thermospheric Imaging (MIGHTI) Sensor B - Line-of-sight Wind Profiles - T. J. Immel (UC Berkeley>SSL)
ICON_L2-1_MIGHTI-B_LOS-WIND-RED Michelson Interferometer for Global High-resolution Thermospheric Imaging (MIGHTI) Sensor B - Line-of-sight Wind Profiles - T. J. Immel (UC Berkeley>SSL)
ICON_L2-2_MIGHTI_VECTOR-WIND-GREEN MIGHTI - Cardinal Vector Winds - T. J. Immel (UC Berkeley>SSL)
ICON_L2-2_MIGHTI_VECTOR-WIND-RED MIGHTI - Cardinal Vector Winds - T. J. Immel (UC Berkeley>SSL)
ICON_L2-3_MIGHTI-A_TEMPERATURE ICON MIGHTI-A Level 2.3 Retrieved Temperature File - T. J. Immel (UC Berkeley>SSL)
ICON_L2-3_MIGHTI-B_TEMPERATURE ICON MIGHTI-B Level 2.3 Retrieved Temperature File - T. J. Immel (UC Berkeley>SSL)
ICON_L2-4_FUV_DAY ICON FUV Daytime: column density ratio of thermospheric atomic oxygen to molecular nitrogen.  - T. J. Immel (UC Berkeley>SSL)
ICON_L2-5_FUV_NIGHT FUV Short Wavelength Channel - 135.6 Altitude Profiles (night) - T. J. Immel (UC Berkeley>SSL)
ICON_L2-6_EUV ICON EUV derived ionospheric data products - T. J. Immel (UC Berkeley>SSL)
ICON_L2-7_IVM-A ICON Ion Velocity Meter (IVM) Thermal Plasma Measurements - T. J. Immel (UC Berkeley>SSL)
ICON_L2-7_IVM-B ICON IVM Thermal Plasma Measurements B - T. J. Immel (UC Berkeley>SSL)

Get Dataset Variables

The following code demonstrates how to get a dataset's variables.

ds_id = 'ICON_L2-4_FUV_DAY'
var_names = []
variables = cdas.get_variables(ds_id)
for variable in variables:
    var_name = variable['Name']
    var_names.append(var_name)
    print(var_name, variable['LongDescription'])

ICON_L24_1356_Emission Disk short wave emission
ICON_L24_Ap Ap used in retreival
ICON_L24_Disk_LOS_Zen_Angle Retrieved disk LOS zenith angle
ICON_L24_Disk_Latitude Retrieved disk latitude
ICON_L24_Disk_Longitude Retrieved disk longitude
ICON_L24_Disk_ON2 Retrieved disk column O/N2
ICON_L24_Disk_SZA Retrieved disk SZA
ICON_L24_Disk_Sigma_ON2 Retrieved disk column O/N2 uncertainty
ICON_L24_LBH_Emission Disk long wave emission

Get Data

The following code demonstrates how to get NetCDF data from the ICON_L2-4_FUV_DAY dataset.

data = cdas.get_data(ds_id, var_names,
                     '2022-11-24T23:00:00Z', '2022-11-24T23:05:00Z',
                     dataRepresentation = dr.XARRAY)[1]
print(data)

<xarray.Dataset>
Dimensions:                      (Epoch_cdf: 24, record0: 6951)
Coordinates:
  * Epoch_cdf                    (Epoch_cdf) datetime64[ns] 2022-11-24T23:00:...
Dimensions without coordinates: record0
Data variables:
    time_base                    datetime64[ns] 1970-01-01
    ICON_L24_1356_Emission       (Epoch_cdf) float32 3.69e+03 ... 3.435e+03
    ICON_L24_Ap                  (Epoch_cdf) float32 12.0 12.0 ... 12.0 12.0
    ICON_L24_Disk_LOS_Zen_Angle  (Epoch_cdf) float32 119.9 119.9 ... 119.9 119.9
    ICON_L24_Disk_Latitude       (Epoch_cdf) float32 -19.67 -19.66 ... -18.34
    ICON_L24_Disk_Longitude      (Epoch_cdf) float32 200.5 201.3 ... 217.1 217.8
    ICON_L24_Disk_ON2            (Epoch_cdf) float32 0.5691 0.5892 ... 0.5599
    ICON_L24_Disk_SZA            (Epoch_cdf) float32 8.413 9.165 ... 25.11 25.87
    ICON_L24_Disk_Sigma_ON2      (Epoch_cdf) float32 0.01592 0.0184 ... 0.02127
    ICON_L24_LBH_Emission        (Epoch_cdf) float32 1.038e+03 ... 964.8
    Epoch                        (record0) int64 1669248003023 ... 1669334389316
Attributes:
    ACKNOWLEDGEMENT:             This is a data product from the NASA Ionosph...
    ADID_ref:                    NASA Contract>NNG12FA45C
    CALIBRATION_FILE:             
    CONVENTIONS:                 SPDF ISTP/IACG Modified for NetCDF
    DATA_LEVEL:                  L2.4
    Data_type:                   DP24>Data Product 2.4: FUV Daytime
    DESCRIPTION:                 ICON FUV Daytime
    Descriptor:                  ICON FUV Daytime
    Discipline:                  Space Physics>Ionospheric Science
    FILE_DATE:                   2022-11-23T23:59:57 UTC
    GENERATED_BY:                ICON FUV L1 > ICON FUV L2v04r000, R. Meier
    GENERATION_DATE:             Wed Jan 11 02:35:47 2023
    HISTORY:                     Version 003, Frist public release, disk data...
    INSTRUMENT:                  FUV
    Instrument_type:             Imaging and Remote Sensing (ITM/Earth)
    HTTP_LINK:                   http://icon.ssl.berkeley.edu/
    LINK_TEXT:                   ICON FUV
    LINK_TITLE:                  instrument site
    Logical_file_id:             icon_l2-4s_fuv_day_20221124230010_2022112423...
    Logical_source:              ICON_L2-4S_FUV_DAY
    Logical_source_description:  DERIVED FROM: ICON FUV Daytime: column densi...
    Mission_group:               ICON
    PARENTS:                     ['ICON_L1_FUV_LWP_2022-11-24_v05r000.NC', 'I...
    PI_affiliation:              UC Berkeley>SSL
    PI_name:                     T. J. Immel
    Project:                     NASA>ICON
    RULES_OF_USE:                Public Data for Scientific Use
    SOFTWARE_VERSION:            ICON SDC > FUV v04r000
    Source_name:                 ICON>Iconospheric Connection Explorer
    SPACECRAFT_ID:               NASA>ICON - 493
    Text:                        ['CDAWeb interface derived data on Thu Apr  ...
    TEXT_SUPPLEMENT:             This describes the data product for ICON FUV...
    TIME_RESOLUTION:             12 Sec
    TITLE:                       ICON FUV Daytime
    NCO:                         netCDF Operators version 4.7.5 (Homepage = h...
    NC_KIND:                     netCDF-4
    NC_DIMENSIONS_G:             ['Epoch=UNLIMITED', 'Covariance Matrix 2nd D...
    NC_STRINGS_G:                Acknowledgement ADID_Ref Calibration_File Co...

Display Metadata

The following code displays metadata for the ICON_L24_Disk_SZA variable, do

print(data.ICON_L24_Disk_SZA)

<xarray.DataArray 'ICON_L24_Disk_SZA' (Epoch_cdf: 24)>
array([ 8.413165,  9.165311,  9.919736, 10.674797, 11.431073, 12.187651,
       12.945468, 13.703261, 14.462048, 15.220608, 15.980153, 16.739532,
       17.499659, 18.259481, 19.019903, 19.780228, 20.540913, 21.30163 ,
       22.062748, 22.823668, 23.585054, 24.345064, 25.106302, 25.867178],
      dtype=float32)
Coordinates:
  * Epoch_cdf  (Epoch_cdf) datetime64[ns] 2022-11-24T23:00:10.767000 ... 2022...
Attributes:
    FIELDNAM:         Retrieved disk SZA
    NC_DIMENSIONS_V:  Epoch
    NC_DEFLATE:       [6]
    NC_SHUFFLE:       true
    NC_STORAGE:       chunked
    NC_CHUNKSIZES:    [7013]
    CATDESC:          Retrieved disk SZA
    DEPEND_0:         Epoch_cdf
    DISPLAY_TYPE:     time_series
    FILLVAL:          [-999.]
    UNITS:            Degrees
    VALIDMAX:         [180.]
    VALIDMIN:         [0.]
    VAR_NOTES:        Solar zenith angle corresponding to disk retrieval
    VAR_TYPE:         data
    NC_STRINGS_V:     CatDesc Depend_0 Display_Type FieldNam Long_Name Units ...
    DIM_SIZES:        [0]
    standard_name:    Retrieved disk SZA
    units:            Degrees

Plot Values

The following code plots the ICON_L24_Disk_SZA variable's values using the label values from the metadata.

data['ICON_L24_Disk_SZA'].plot()

[<matplotlib.lines.Line2D at 0x7f258882e7b8>]

Additional Documentation

View the cdasws API for additional functions. Additional notebook examples are also available.