spaceweather

File parsing (and updating) is handled by the submodules, but all functions are available through importing spaceweather, for example:

import spaceweather as sw

sw.sw_daily()  # the daily space weather indices from celestrak

It should not be necessary to import the submodule(s) individually as those may still be subject to change.

spaceweather.celestrak

Python interface for space weather indices

Celestrak space weather indices file parser for python [1].

spaceweather.celestrak.ap_kp_3h(*args, **kwargs)[source]

3h values of Ap and Kp

Provides the 3-hourly Ap and Kp indices from the full daily data set.

Accepts the same arguments as sw_daily(). All arguments are optional and changing them from the defaults should not be required neither should it be necessary nor is it recommended.

Parameters:

  • swpath_all (str, optional, default depending on package install location) – Filename for the large combined index file including the historic data, absolute path or relative to the current dir.

  • swpath_5y (str, optional, default depending on package install location) – Filename for the 5-year index file, absolute path or relative to the current dir.

  • update (bool, optional, default False) – Attempt to update the local data if it is older than update_interval.

  • update_interval (str, optional, default "30days") – The time after which the data are considered “old”. By default, no automatic re-download is initiated, set update to true. The online data is updated every 3 hours, thus setting this value to a shorter time is not needed and not recommended.

Returns:

sw_df – The combined Ap and Kp index data (3h values). The index values are centred at the 3h interval, i.e. at 01:30:00, 04:30:00, 07:30:00, … and so on. Raises IOError if the data files cannot be found.

Return type:

pandas.DataFrame

See also

sw_daily

spaceweather.celestrak.get_file_age(swpath, relative=True)[source]

Age of the downloaded data file

Retrieves the last update time of the given file or full path.

Parameters:

  • swpath (str) – Filename to check, absolute path or relative to the current dir.

  • relative (bool, optional, default True) – Return the file’s age (True) or the last update time (False).

Returns:

upd – The last updated time or the file age, depending on the setting of relative above. Raises IOError if the file is not found.

Return type:

pandas.Timestamp or pandas.Timedelta

spaceweather.celestrak.read_sw(swpath)[source]

Read and parse space weather index data file

Reads the given file and parses it according to the space weather data format.

Parameters:

swpath (str) – File to parse, absolute path or relative to the current dir.

Returns:

sw_df – The parsed space weather data (daily values). Raises an IOError if the file is not found.

The dataframe contains the following columns:

”year”, “month”, “day”:

The observation date

”bsrn”:

Bartels Solar Rotation Number. A sequence of 27-day intervals counted continuously from 1832 Feb 8.

”rotd”:

Number of Day within the Bartels 27-day cycle (01-27).

”Kp0”, “Kp3”, “Kp6”, “Kp9”, “Kp12”, “Kp15”, “Kp18”, “Kp21”:

Planetary 3-hour Range Index (Kp) for 0000-0300, 0300-0600, 0600-0900, 0900-1200, 1200-1500, 1500-1800, 1800-2100, 2100-2400 UT

”Kpsum”: Sum of the 8 Kp indices for the day.

Expressed to the nearest third of a unit.

”Ap0”, “Ap3”, “Ap6”, “Ap9”, “Ap12”, “Ap15”, “Ap18”, “Ap21”:

Planetary Equivalent Amplitude (Ap) for 0000-0300, 0300-0600, 0600-0900, 0900-1200, 1200-1500, 1500-1800, 1800-2100, 2100-2400 UT

”Apavg”:

Arithmetic average of the 8 Ap indices for the day.

”Cp”:

Cp or Planetary Daily Character Figure. A qualitative estimate of overall level of magnetic activity for the day determined from the sum of the 8 Ap indices. Cp ranges, in steps of one-tenth, from 0 (quiet) to 2.5 (highly disturbed). “C9”:

”isn”:

International Sunspot Number. Records contain the Zurich number through 1980 Dec 31 and the International Brussels number thereafter.

”f107_adj”:

10.7-cm Solar Radio Flux (F10.7) Adjusted to 1 AU. Measured at Ottawa at 1700 UT daily from 1947 Feb 14 until 1991 May 31 and measured at Penticton at 2000 UT from 1991 Jun 01 on. Expressed in units of 10-22 W/m2/Hz.

”Q”:

Flux Qualifier. 0 indicates flux required no adjustment; 1 indicates flux required adjustment for burst in progress at time of measurement; 2 indicates a flux approximated by either interpolation or extrapolation; 3 indicates no observation; and 4 indicates CSSI interpolation of missing data.

”f107_81ctr_adj”:

Centered 81-day arithmetic average of F10.7 (adjusted).

”f107_81lst_adj”:

Last 81-day arithmetic average of F10.7 (adjusted).

”f107_obs”:

Observed (unadjusted) value of F10.7.

”f107_81ctr_obs”:

Centered 81-day arithmetic average of F10.7 (observed).

”f107_81lst_obs”:

Last 81-day arithmetic average of F10.7 (observed).

Return type:

pandas.DataFrame

spaceweather.celestrak.sw_daily(swpath_all='/home/docs/checkouts/readthedocs.org/user_builds/pyspaceweather/conda/latest/lib/python3.12/site-packages/spaceweather/data/SW-All.txt', swpath_5y='/home/docs/checkouts/readthedocs.org/user_builds/pyspaceweather/conda/latest/lib/python3.12/site-packages/spaceweather/data/SW-Last5Years.txt', update=False, update_interval='30days')[source]

Combined daily Ap, Kp, and f10.7 index values

Combines the “historic” and last-5-year data into one dataframe.

All arguments are optional and changing them from the defaults should not be required neither should it be necessary nor is it recommended.

Parameters:

  • swpath_all (str, optional, default depending on package install location) – Filename for the large combined index file including the historic data, absolute path or relative to the current dir.

  • swpath_5y (str, optional, default depending on package install location) – Filename for the 5-year index file, absolute path or relative to the current dir.

  • update (bool, optional, default False) – Attempt to update the local data if it is older than update_interval.

  • update_interval (str, optional, default "30days") – The time after which the data are considered “old”. By default, no automatic re-download is initiated, set update to true. The online data is updated every 3 hours, thus setting this value to a shorter time is not needed and not recommended.

Returns:

sw_df – The combined parsed space weather data (daily values). Raises IOError if the data files cannot be found.

Return type:

pandas.DataFrame

See also

ap_kp_3h, read_sw

spaceweather.celestrak.update_data(min_age='3h', swpath_all='/home/docs/checkouts/readthedocs.org/user_builds/pyspaceweather/conda/latest/lib/python3.12/site-packages/spaceweather/data/SW-All.txt', swpath_5y='/home/docs/checkouts/readthedocs.org/user_builds/pyspaceweather/conda/latest/lib/python3.12/site-packages/spaceweather/data/SW-Last5Years.txt', url_all='https://celestrak.com/SpaceData/SW-All.txt', url_5y='https://celestrak.com/SpaceData/SW-Last5Years.txt')[source]

Update the local space weather index data

Updates the local space weather index data from the website [2], given that the 5-year file is older than min_age, or the combined (large) file is older than four years. If the data is missing for some reason, a download will be attempted nonetheless.

All arguments are optional and changing them from the defaults should not be required neither should it be necessary nor is it recommended.

Parameters:

  • min_age (str, optional, default "3h") – The time after which a new download will be attempted. The online data is updated every 3 hours, thus setting this value to a shorter time is not needed and not recommended.

  • swpath_all (str, optional, default depending on package install location) – Filename for the large combined index file including the historic data, absolute path or relative to the current dir.

  • swpath_5y (str, optional, default depending on package install location) – Filename for the 5-year index file, absolute path or relative to the current dir.

  • url_all (str, optional, default sw.DL_URL_ALL) – The url of the “historic” data file.

  • url_5y (str, optional, default sw.DL_URL_5Y) – The url of the data file of containing the indices of the last 5 years.

Return type:

Nothing.

spaceweather.gfz

Python interface for space weather indices from GFZ Potsdam

GFZ space weather indices ASCII file parser for python [3].

spaceweather.gfz.get_gfz_age(gfzpath, relative=True)[source]

Age of the downloaded data file

Retrieves the last update time of the given file or full path.

Parameters:

  • gfzpath (str) – Filename to check, absolute path or relative to the current dir.

  • relative (bool, optional, default True) – Return the file’s age (True) or the last update time (False).

Returns:

upd – The last updated time or the file age, depending on the setting of relative above. Raises IOError if the file is not found.

Return type:

pandas.Timestamp or pandas.Timedelta

spaceweather.gfz.gfz_3h(*args, **kwargs)[source]

3h values of Ap and Kp

Provides the 3-hourly Ap and Kp indices from the full daily data set.

Accepts the same arguments as gfz_daily(). All arguments are optional and changing them from the defaults should not be required neither should it be necessary nor is it recommended.

Parameters:

  • gfzpath_all (str, optional, default depending on package install location) – Filename for the large combined index file including the historic data, absolute path or relative to the current dir.

  • gfzpath_30d (str, optional, default depending on package install location) – Filename for the 30-day (nowcast) index file, absolute path or relative to the current dir.

  • update (bool, optional, default False) – Attempt to update the local data if it is older than update_interval.

  • update_interval (str, optional, default "30days") – The time after which the data are considered “old”. By default, no automatic re-download is initiated, set update to true. The online data is updated every 3 hours, thus setting this value to a shorter time is not needed and not recommended.

Returns:

gfz_df – The combined Ap and Kp index data (3h values). The index values are centred at the 3h interval, i.e. at 01:30:00, 04:30:00, 07:30:00, … and so on. Raises IOError if the data files cannot be found.

Return type:

pandas.DataFrame

See also

gfz_daily

spaceweather.gfz.gfz_daily(gfzpath_all='/home/docs/checkouts/readthedocs.org/user_builds/pyspaceweather/conda/latest/lib/python3.12/site-packages/spaceweather/data/Kp_ap_Ap_SN_F107_since_1932.txt', gfzpath_30d='/home/docs/checkouts/readthedocs.org/user_builds/pyspaceweather/conda/latest/lib/python3.12/site-packages/spaceweather/data/Kp_ap_Ap_SN_F107_nowcast.txt', update=False, update_interval='10days')[source]

Combined daily Ap, Kp, and f10.7 index values

Combines the “historic” and last-30-day data into one dataframe.

All arguments are optional and changing them from the defaults should not be required neither should it be necessary nor is it recommended.

Parameters:

  • gfzpath_all (str, optional, default depending on package install location) – Filename for the large combined index file including the historic data, absolute path or relative to the current dir.

  • gfzpath_30d (str, optional, default depending on package install location) – Filename for the 30-day (nowcast) index file, absolute path or relative to the current dir.

  • update (bool, optional, default False) – Attempt to update the local data if it is older than update_interval.

  • update_interval (str, optional, default "30days") – The time after which the data are considered “old”. By default, no automatic re-download is initiated, set update to true. The online data is updated every 3 hours, thus setting this value to a shorter time is not needed and not recommended.

Returns:

gfz_df – The combined parsed space weather data (daily values). Raises IOError if the data files cannot be found.

Return type:

pandas.DataFrame

See also

gfz_3h, read_gfz

spaceweather.gfz.read_gfz(gfzpath)[source]

Read and parse space weather index data file

Reads the given file and parses it according to the space weather data format.

Parameters:

gfzpath (str) – File to parse, absolute path or relative to the current dir.

Returns:

gfz_df – The parsed space weather data (daily values). Raises an IOError if the file is not found.

The dataframe contains the following columns:

”year”, “month”, “day”:

The observation date

”bsrn”:

Bartels Solar Rotation Number. A sequence of 27-day intervals counted continuously from 1832 Feb 8.

”rotd”:

Number of Day within the Bartels 27-day cycle (01-27).

”Kp0”, “Kp3”, “Kp6”, “Kp9”, “Kp12”, “Kp15”, “Kp18”, “Kp21”:

Planetary 3-hour Range Index (Kp) for 0000-0300, 0300-0600, 0600-0900, 0900-1200, 1200-1500, 1500-1800, 1800-2100, 2100-2400 UT

”Kpsum”: Sum of the 8 Kp indices for the day.

Expressed to the nearest third of a unit.

”Ap0”, “Ap3”, “Ap6”, “Ap9”, “Ap12”, “Ap15”, “Ap18”, “Ap21”:

Planetary Equivalent Amplitude (Ap) for 0000-0300, 0300-0600, 0600-0900, 0900-1200, 1200-1500, 1500-1800, 1800-2100, 2100-2400 UT

”Apavg”:

Arithmetic average of the 8 Ap indices for the day.

”isn”:

International Sunspot Number. Records contain the Zurich number through 1980 Dec 31 and the International Brussels number thereafter.

”f107_obs”:

Observed (unadjusted) value of F10.7.

”f107_adj”:

10.7-cm Solar Radio Flux (F10.7) Adjusted to 1 AU. Measured at Ottawa at 1700 UT daily from 1947 Feb 14 until 1991 May 31 and measured at Penticton at 2000 UT from 1991 Jun 01 on. Expressed in units of 10-22 W/m2/Hz.

”D”:

Definitive indicator. 0: Kp and SN preliminary 1: Kp definitive, SN preliminary 2: Kp and SN definitive

Return type:

pandas.DataFrame

spaceweather.gfz.update_gfz(min_age='1d', gfzpath_all='/home/docs/checkouts/readthedocs.org/user_builds/pyspaceweather/conda/latest/lib/python3.12/site-packages/spaceweather/data/Kp_ap_Ap_SN_F107_since_1932.txt', gfzpath_30d='/home/docs/checkouts/readthedocs.org/user_builds/pyspaceweather/conda/latest/lib/python3.12/site-packages/spaceweather/data/Kp_ap_Ap_SN_F107_nowcast.txt', url_all='https://kp.gfz-potsdam.de/app/files/Kp_ap_Ap_SN_F107_since_1932.txt', url_30d='https://kp.gfz-potsdam.de/app/files/Kp_ap_Ap_SN_F107_nowcast.txt')[source]

Update the local space weather index data

Updates the local space weather index data from the website [4], given that the 30-day file is older than min_age, or the combined (large) file is older than 30 days. If the data is missing for some reason, a download will be attempted nonetheless.

All arguments are optional and changing them from the defaults should neither be necessary nor is it recommended.

Parameters:

  • min_age (str, optional, default "1d") – The time after which a new download will be attempted. The online data is updated every day, thus setting this value to a shorter time is not needed and not recommended.

  • gfzpath_all (str, optional, default depending on package install location) – Filename for the large combined index file including the historic data, absolute path or relative to the current dir.

  • gfzpath_30d (str, optional, default depending on package install location) – Filename for the 30-day (nowcast) index file, absolute path or relative to the current dir.

  • url_all (str, optional, default gfz.GFZ_URL_ALL) – The url of the “historic” data file.

  • url_30d (str, optional, default gfz.GFZ_URL_30D) – The url of the data file containing the indices for the last 30 days.

Return type:

Nothing.

spaceweather.omni

Python interface for OMNI space weather data

Omni2 [5] space weather data interface for python.

spaceweather.omni.cache_omnie(year, prefix=None, ext=None, local_path=None, url_base=None)[source]

Download OMNI2 data to local cache

Downloads the OMNI2 (extended) data file from [6] to the local location.

Parameters:

  • year (int) – Year of the data.

  • prefix (str, optional) – File prefix for constructing the file name as <prefix>_year.<ext>. Defaults to ‘omni2’.

  • ext (str, optional) – File extension for constructing the file name as <prefix>_year.<ext>. Defaults to ‘dat’.

  • local_path (str, optional) – Path to the locally stored data yearly files, defaults to the data location within the package.

  • url_base (str, optional) – URL for the directory that contains the yearly files.

Return type:

Nothing.

spaceweather.omni.omnie_hourly(year, prefix=None, ext=None, local_path=None, url_base=None, cache=False)[source]

OMNI hourly data for year year

Loads the OMNI hourly data for the given year, from the locally cached data. Use local_path to set a custom location if you have the omni data already available.

Parameters:

  • year (int) – Year of the data.

  • prefix (str, optional, default 'omni2') – File prefix for constructing the file name as <prefix>_year.<ext>.

  • ext (str, optional, default 'dat') – File extension for constructing the file name as <prefix>_year.<ext>.

  • local_path (str, optional) – Path to the locally stored data yearly files, defaults to the data location within the package.

  • url_base (str, optional) – URL for the directory that contains the yearly files.

  • cache (boolean, optional, default False) – Download files locally if they are not already available.

Returns:

sw_df – The parsed space weather data (hourly values).

Raises an IOError if the file is not available.

Return type:

pandas.DataFrame

See also

read_omnie

spaceweather.omni.omnie_mask_missing(df)[source]

Mask missing values with NaN

Marks missing values in the OMNI2 data set by NaN. The missing value indicating numbers are taken from the file format description https://spdf.gsfc.nasa.gov/pub/data/omni/low_res_omni/extended/aareadme_extended

Parameters:

df (pandas.DataFrame) – The OMNI2 data set, e.g. from omnie_hourly() or read_omnie().

Returns:

df – The same dataframe with the missing values masked with numpy.nan.

Return type:

pandas.DataFrame

Notes

This function returns a copy of the dataframe, and all the integer columns will be converted to float to support NaN.

spaceweather.omni.read_omnie(omnie_file)[source]

Read and parse OMNI2 extended files [7]

Parses the Omni2 extended data files, available at [8], into a pandas.DataFrame.

Parameters:

omnie_file (str) – File to parse, absolute path or relative to the current dir.

Returns:

sw_df – The parsed OMNI2 space weather data (hourly values). Details in https://spdf.gsfc.nasa.gov/pub/data/omni/low_res_omni/extended/aareadme_extended

Raises an IOError if the file is not found.

The dataframe contains the following columns:

year:

The observation year

doy:

Day of the year

hour:

Hour of the day

bsrn:

Bartels Solar Rotation Number.

id_imf:

ID for IMF spacecraft

id_sw:

ID for SW plasma spacecraft

n_imf:

Number of points in IMF averages

n_plasma:

Numberof points in plasma averages

B_mag_avg:

Magnetic field magnitude average B

B_mag:

Magnetic field vector magnitude

theta_B:

Latitude angle of the magnetic field vector

phi_B:

Longitude angle of the magnetic field vector

B_x:

B_x GSE, GSM

B_y_GSE:

B_y GSE

B_z_GSE:

B_z GSE

B_y_GSM:

B_y GSM

B_z_GSM:

B_z GSM

sigma_B_mag_avg:

RMS standard deviation of B_mag_avg

sigma_B_mag:

RMS standard deviation of B_mag

sigma_B_x_GSE:

RMS standard deviation of B_x_GSE

sigma_B_y_GSE:

RMS standard deviation of B_y_GSE

sigma_B_z_GSE:

RMS standard deviation of B_z_GSE

T_p:

Proton temperature

n_p:

Proton density

v_plasma:

Plasma flow speed

phi_v:

Plasma flow longitude angle

theta_v:

Plasma flow latitude angle

n_alpha_n_p:

Alpha/Proton ratio

p_flow:

Flow pressure

sigma_T:

Standard deviation of T_p

sigma_n:

Standard deviation of n_p

sigma_v:

Standard deviation of v_plasma

sigma_phi_v:

Standard deviation of phi_v

sigma_theta_v:

Standard deviation of theta_v

sigma_na_np:

Standard deviation of n_alpha_n_p

E:

Electric field magnitude

beta_plasma:

Plasma beta

mach:

Alfvén Mach number

Kp:

Kp index value

R:

Sunspot number

Dst:

Dst index value

AE:

AE index value

p_01MeV, p_02MeV, p_04MeV, p_10MeV, p_30MeV, p_60MeV:

Proton fluxes >1 MeV, >2 MeV, >4 MeV, >10 MeV, >30 MeV, > 60 MeV

flag:

Flag (-1, …, 6)

Ap:

Ap index value

f107_adj:

F10.7 radio flux at 1 AU

PC:

PC index value

AL, AU:

AL and AU index values

mach_mag:

Magnetosonic Mach number

The extended dataset contains the addional columns:

Lya:

Solar Lyman-alpha irradiance

QI_p:

Proton QI

Return type:

pandas.DataFrame

Module contents

Python interface for space weather indices