Web

The web package provides an interface for retrieving data from online sources.

This package allows users to access geomagnetic indices, solar wind parameters, and other space weather data from various providers, such as OMNIWeb.

Main Features:

  • omni: Retrieval of OMNIWeb data.

  • download_unzip: Utility for downloading and extracting model data files.

download_unzip(url[, target_folder, ...])

Download a zip file and extract files from it.

omni(start_date, end_date[, params, ...])

Retrieve space weather data from the OMNIWEB database at various resolutions.

Functions

rbamlib.web.omni(start_date, end_date, params=None, resolution='hour', show_url=False)

Retrieve space weather data from the OMNIWEB database at various resolutions.

Parameters:

  • start_date (str or datetime) – Start date in multiple supported formats, such as ‘YYYY-MM-DD’, or ‘YYYYMMDDHH’.

  • end_date (str or datetime) – End date in multiple supported formats, matching the start_date format.

  • params (list) –

    List of parameter names (e.g., [‘Kp’, ‘Dst’]) or numbers (e.g., [38, ‘Dst’]).

    • If a string is provided, it is mapped to the corresponding OMNIWEB variable number.

    • If a number is provided, it is directly used in the request.

    • Raises an error if an unknown parameter is included.

  • resolution (str, default='hour') –

    The resolution of the data, corresponding to either the Low Resolution OMNI (LRO) or High Resolution OMNI (HRO) datasets:

    LRO Data Set:

    • ’hour’ (Hourly resolution, source ‘omni2’)

    • ’daily’ (Daily resolution, source ‘omni2_daily’)

    • ’27day’ (27-day resolution, source ‘omni2_27day’)

    • ’yearly’ (Yearly resolution, source ‘omni2_yearly’)

    HRO Data Set:

    • ’min’ (1-minute resolution, source ‘omni_min’)

    • ’5min’ (5-minute resolution, source ‘omni_5min’)

Returns:

If multiple parameters are requested, returns (time, *data_values), where:

  • time is a NumPy array of datetime objects.

  • data_values are NumPy arrays ordered according to the requested parameter keys.

Return type:

tuple

Notes

  • The data is retrieved from the NASA OMNIWEB database and includes various space weather indices, such as Kp, Dst, AE, and solar indices.

  • The function automatically converts the retrieved data into numpy arrays and filters them by the specified date range.

  • The OMNIWEB service may return missing or fill values for certain periods.

Available Parameters

Low Resolution OMNI (LRO) Data Set

Short Name

OMNIWeb Index | Description

BRN

3

Bartels Rotation Number

IMF_ID

4

IMF Spacecraft ID

Plasma_ID

5

Plasma Spacecraft ID

IMF_Fine

6

Fine Scale Points in IMF Averages

Plasma_Fine

7

Fine Scale Points in Plasma Averages

IMF_Mag

8

IMF Magnitude Average, nT

IMF_Vr

9

Magnitude, Avg IMF Vr, nT

IMF_Lat

10

Latitude of Avg. IMF, degrees

IMF_Lon

11

Longitude of Avg. IMF, degrees

Bx_GSE

12

Bx component, GSE/GSM, nT

By_GSE

13

By component, GSE, nT

Bz_GSE

14

Bz component, GSE, nT

By_GSM

15

By component, GSM, nT

Bz_GSM

16

Bz component, GSM, nT

Sigma_IMF_Mag

17

Sigma in IMF Magnitude Average

Sigma_IMF_Vec

18

Sigma in IMF Vector Average

Sigma_Bx

19

Sigma Bx, nT

Sigma_By

20

Sigma By, nT

Sigma_Bz

21

Sigma Bz, nT

T_p

22

Proton Temperature, K

N_p

23

Proton Density, n/cc

V_flow

24

Flow Speed, km/sec

Flow_Lon

25

Flow Longitude, degrees

Flow_Lat

26

Flow Latitude, degrees

Alpha_Proton

27

Alpha/Proton Density Ratio

Flow_P

28

Flow Pressure, nPa

Sigma_T

29

Sigma-T

Sigma_Np

30

Sigma-Np

Sigma_V

31

Sigma-V

Sigma_Flow_Lon

32

Sigma-Flow-Longitude

Sigma_Flow_Lat

33

Sigma-Flow-Latitude

Sigma_Alpha

34

Sigma-Alpha/Proton Ratio

Ey

35

Electric Field, mV/m

Plasma_Beta

36

Plasma Beta

Alfven

37

Alfven Mach Number

Kp

38

Kp*10 Index (Geomagnetic Activity)

R_Sunspot

39

R Sunspot Number

Dst

40

Dst Index, nT (Geomagnetic Storm Index)

AE

41

AE Index, nT (Auroral Electrojet)

PFlux_1MeV

42

Proton Flux > 1 MeV

PFlux_2MeV

43

Proton Flux > 2 MeV

PFlux_4MeV

44

Proton Flux > 4 MeV

PFlux_10MeV

45

Proton Flux > 10 MeV

PFlux_30MeV

46

Proton Flux > 30 MeV

PFlux_60MeV

47

Proton Flux > 60 MeV

Mag_Flux_Flag

48

Magnetospheric Flux Flag

AP

49

AP index, nT

F10.7

50

Solar Flux Index (F10.7)

PC

51

Polar Cap Index

AL

52

AL Index, nT

AU

53

AU Index, nT

Magnetosonic

54

Magnetosonic Mach Number

Lyman_Alpha

55

Lyman Alpha Solar Index, W/m²

Proton_QI

56

Proton Quasi-Invariant (QI)

High Resolution OMNI (HRO) Data Set

Short Name

OMNIWeb Index

Description

IMF_ID

4

IMF Spacecraft ID

Plasma_ID

5

Plasma Spacecraft ID

IMF_Fine

6

Fine Scale Points in IMF Averages

Plasma_Fine

7

Fine Scale Points in Plasma Averages

Percent_Interpolated

8

Percent interpolated

Timeshift

9

Timeshift, sec

Sigma_Timeshift

10

Sigma Timeshift

Sigma_Min_Var_Vector

11

Sigma Min_var_vector

Time_Between_Obs

12

Time between observations, sec

IMF_Mag

13

IMF Magnitude Avg (Scalar), nT

Bx_GSE

14

Bx component, GSE/GSM, nT

By_GSE

15

By component, GSE, nT

Bz_GSE

16

Bz component, GSE, nT

By_GSM

17

By component, GSM, nT

Bz_GSM

18

Bz component, GSM, nT

Sigma_IMF_Mag

19

Sigma in IMF Magnitude Avg.

Sigma_IMF_Vec

20

Sigma in IMF Vector Avg

Flow_Speed

21

Flow Speed, km/sec

Vx_GSE

22

Vx Velocity, GSE, km/s

Vy_GSE

23

Vy Velocity, GSE, km/s

Vz_GSE

24

Vz Velocity, GSE, km/s

N_p

25

Proton Density, n/cc

T_p

26

Proton Temperature, K

Flow_P

27

Flow Pressure, nPa

Ey

28

Electric Field, mV/m

Plasma_Beta

29

Plasma Beta

Alfven

30

Alfven Mach Number

Magnetosonic

45

Magnetosonic Mach Number

Spacecraft_X

31

Spacecraft X, GSE, Re

Spacecraft_Y

32

Spacecraft Y, GSE, Re

Spacecraft_Z

33

Spacecraft Z, GSE, Re

BSN_X

34

Bow Shock Nose (BSN) location X, GSE, Re

BSN_Y

35

BSN location Y, GSE, Re

BSN_Z

36

BSN location Z, GSE, Re

AE

37

AE Index, nT

AL

38

AL Index, nT

AU

39

AU Index, nT

SYM_D

40

SYM/D, nT

SYM_H

41

SYM/H, nT

ASY_D

42

ASY/D, nT

ASY_H

43

ASY/H, nT

PC

44

Polar Cap (PC) index from Thule

PFlux_10MeV

46

Proton Flux > 10 MeV, 1/(cm²-sec-ster)

PFlux_30MeV

47

Proton Flux > 30 MeV, 1/(cm²-sec-ster)

PFlux_60MeV

48

Proton Flux > 60 MeV, 1/(cm²-sec-ster)

Example

Retrieve the Kp and Dst indices for a given date range:

time, kp, dst = omni('2023-01-01', '2023-01-10', {'Kp', 'Dst'})

time, AL = omni('2023-01-01', '2023-01-10', {'AL'}, resolution='min')

Available Parameters

References

NASA LRO OMNIWEB: https://omniweb.gsfc.nasa.gov/form/dx1.html

NASA HRO OMNIWEB: https://omniweb.gsfc.nasa.gov/form/omni_min.html

rbamlib.web.download_unzip(url, target_folder=None, filename_in_zip=None)

Download a zip file and extract files from it.

Utility for downloading model data files. Used by models that require external data.

Parameters:

  • url (str) – URL to download zip from

  • target_folder (str, optional) – Folder where to extract the file(s). If not provided, extracts to current working directory.

  • filename_in_zip (str, optional) – Specific file to extract from the zip. If not provided, extracts all files from the archive.

Returns:

If filename_in_zip is provided: path to the extracted file (str) If filename_in_zip is None: list of paths to all extracted files

Return type:

str or list of str

Examples

Extract a specific file to a target folder:

>>> from rbamlib.web import download_unzip
>>> file_path = download_unzip(
...     url='https://example.com/data.zip',
...     target_folder='./data',
...     filename_in_zip='model_data.mat')

Extract all files to current directory:

>>> file_paths = download_unzip('https://example.com/data.zip')

Extract all files to a specific folder:

>>> file_paths = download_unzip(
...     'https://example.com/data.zip',
...     target_folder='./output')