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 (None or str, optional, default None) – Filename for the large combined index file including the historic data, absolute path or relative to the current dir. None uses the package’s default file location.
swpath_5y (None or str, optional, default None) – Filename for the 5-year index file, absolute path or relative to the current dir. None uses the package’s default file location.
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
IOErrorif the data files cannot be found. The index is returned timezone-naive but contains UTC timestamps. To convert to a timezone-aware index, usepandas.DataFrame.tz_localize():sw_df.tz_localize("utc").- Return type:
See also
- 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:
- Returns:
upd – The last updated time or the file age, depending on the setting of relative above. Raises
IOErrorif the file is not found.- Return type:
- 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
IOErrorif the file is not found. The index is returned timezone-naive but contains UTC timestamps. To convert to a timezone-aware index, usepandas.DataFrame.tz_localize():sw_df.tz_localize("utc").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:
- spaceweather.celestrak.sw_daily(swpath_all=None, swpath_5y=None, 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 (None or str, optional, default None) – Filename for the large combined index file including the historic data, absolute path or relative to the current dir. None uses the package’s default file location.
swpath_5y (None or str, optional, default None) – Filename for the 5-year index file, absolute path or relative to the current dir. None uses the package’s default file location.
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
IOErrorif the data files cannot be found. The index is returned timezone-naive but contains UTC timestamps. To convert to a timezone-aware index, usepandas.DataFrame.tz_localize():sw_df.tz_localize("utc").- Return type:
- spaceweather.celestrak.update_data(min_age='3h', swpath_all=None, swpath_5y=None, url_all=None, url_5y=None)[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 (None or str, optional, default None) – Filename for the large combined index file including the historic data, absolute path or relative to the current dir. None uses the package’s default file location.
swpath_5y (None or str, optional, default None) – Filename for the 5-year index file, absolute path or relative to the current dir. None uses the package’s default file location.
url_all (None or str, optional, default None) – The url of the “historic” data file. None uses the default url.
url_5y (None or str, optional, default None) – The url of the data file of containing the indices of the last 5 years. None uses the default url.
- Return type:
Nothing.
spaceweather.gfz
Python interface for space weather indices from GFZ Potsdam
GFZ space weather indices ASCII file parser for python [3]. Includes parser for the GFZ ASCII files, files in WDC format, and for the Hpo 30 and 60 minute ASCII files [4]. For the file formats, see the gfz_xxx_format.txt files.
- 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:
- Returns:
upd – The last updated time or the file age, depending on the setting of relative above. Raises
IOErrorif the file is not found.- Return type:
- 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 (None or str, optional, default None) – Filename for the large combined index file including the historic data, absolute path or relative to the current dir. None uses the package’s default file location.
gfzpath_30d (None or str, optional, default None) – Filename for the 30-day (nowcast) index file, absolute path or relative to the current dir. None uses the package’s default file location.
update (bool, optional, default False) – Attempt to update the local data if it is older than update_interval.
update_interval (str, optional, default "10days") – 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.
gfz_format (None or str, optional, default None) – The file format to parse the files passed via gfzpath_all and gfzpath_all. Use None, “default”, “gfz”, or “standard” for the “standard” GFZ ASCII files. Use “wdc” to parse files in WDC format into a full-length pandas.DataFrame. Use “hp30” or “hp60” to read the Hp30 and Hp60 data files.
- 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
IOErrorif the data files cannot be found. The index is returned timezone-naive but contains UTC timestamps. To convert to a timezone-aware index, usepandas.DataFrame.tz_localize():gfz_df.tz_localize("utc").- Return type:
See also
- spaceweather.gfz.gfz_daily(gfzpath_all=None, gfzpath_30d=None, update=False, update_interval='10days', gfz_format=None)[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 (None or str, optional, default None) – Filename for the large combined index file including the historic data, absolute path or relative to the current dir. None uses the package’s default file location.
gfzpath_30d (None or str, optional, default None) – Filename for the 30-day (nowcast) index file, absolute path or relative to the current dir. None uses the package’s default file location.
update (bool, optional, default False) – Attempt to update the local data if it is older than update_interval.
update_interval (str, optional, default "10days") – 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.
gfz_format (None or str, optional, default None) – The file format to parse the files passed via gfzpath_all and gfzpath_all. Use None, “default”, “gfz”, or “standard” for the “standard” GFZ ASCII files. Use “wdc” to parse files in WDC format into a full-length pandas.DataFrame. Use “hp30” or “hp60” to read the Hp30 and Hp60 data files.
- Returns:
gfz_df – The combined parsed space weather data (daily values). Raises
IOErrorif the data files cannot be found. The index is returned timezone-naive but contains UTC timestamps. To convert to a timezone-aware index, usepandas.DataFrame.tz_localize():gfz_df.tz_localize("utc").- Return type:
- 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
IOErrorif 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:
- spaceweather.gfz.read_gfz_hp(gfzhppath)[source]
Read and parse GFZ Hp30 and Hp60 index data file
Reads the given file and parses it according to the Hp30 and Hp60 file format. File format descriptions in [5] and [6]
- Parameters:
gfzhppath (str) – File to parse, absolute path or relative to the current dir.
- Returns:
hp_df – The parsed space weather data with the 30 min or 60 min index. The index is returned timezone-naive but contains UTC timestamps. To convert to a timezone-aware index, use
pandas.DataFrame.tz_localize():hp_df.tz_localize("utc"). Raises anIOErrorif the file is not found.The dataframe contains the following columns:
- ”index”:
padas.DateTimeIndex of the middle times of the intervals.
- ”year”, “month”, “day”:
The observation date.
- ”hh_h”:
Starting time in hours of interval.
- ”hh_m”:
Middle time in hours of interval.
- ”days”:
Days since 1932-01-01 00:00 UT to start of interval.
- ”days_m”:
Days since 1932-01-01 00:00 UT to middle of interval.
- ”Hp”:
Hp index during to the interval (30 min or 60 min).
- ”ap”:
ap index during to the interval (30 min or 60 min).
- ”D”:
Reserved for future use, D = 0 for now.
- Return type:
- spaceweather.gfz.update_gfz(min_age='1D', gfzpath_all=None, gfzpath_30d=None, url_all=None, url_30d=None)[source]
Update the local space weather index data
Updates the local space weather index data from the website [7], 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 (None or str, optional, default None) – Filename for the large combined index file including the historic data, absolute path or relative to the current dir. None uses the package’s default file location.
gfzpath_30d (None or str, optional, default None) – Filename for the 30-day (nowcast) index file, absolute path or relative to the current dir. None uses the package’s default file location.
url_all (None or str, optional, default None) – The url of the “historic” data file. None uses the default url.
url_30d (None or str, optional, default None) – The url of the data file containing the indices for the last 30 days. None uses the default url.
- Return type:
Nothing.
- spaceweather.gfz.update_gfz_hp30(min_age='1D', gfzpath_all=None, gfzpath_30d=None, url_all=None, url_30d=None)[source]
Updates the local Hp30 index data
See also
spaceweather.omni
Python interface for OMNI space weather data
Omni2 [8] 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 [9] to the local location.
- Parameters:
year (int) – Year of the data.
prefix (None or str, optional, default None) – File prefix for constructing the file name as <prefix>_year.<ext>. None defaults to ‘omni2’.
ext (None or str, optional, default None) – File extension for constructing the file name as <prefix>_year.<ext>. None defaults to ‘dat’.
local_path (None or str, optional, default None) – Path to the locally stored data yearly files, defaults to the data location within the package. None uses the package’s default file location.
url_base (None or str, optional, default None) – URL for the directory that contains the yearly files. None uses the default base url.
- 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 (None or str, optional, default None) – File prefix for constructing the file name as <prefix>_year.<ext>. None defaults to ‘omni2’.
ext (None or str, optional, default None) – File extension for constructing the file name as <prefix>_year.<ext>. None defaults to ‘dat’.
local_path (None or str, optional, default None) – Path to the locally stored data yearly files, defaults to the data location within the package. None uses the package’s default file location.
url_base (None or str, optional, default None) – URL for the directory that contains the yearly files. None uses the default base url.
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
IOErrorif the file is not available. The index is returned timezone-naive but contains UTC timestamps. To convert to a timezone-aware index, usepandas.DataFrame.tz_localize():sw_df.tz_localize("utc").- Return type:
See also
- 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()orread_omnie().- Returns:
df – The same dataframe with the missing values masked with
numpy.nan.- Return type:
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 [10]
Parses the Omni2 extended data files, available at [11], 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
IOErrorif the file is not found. The index is returned timezone-naive but contains UTC timestamps. To convert to a timezone-aware index, usepandas.DataFrame.tz_localize():sw_df.tz_localize("utc").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:
Module contents
Python interface for space weather indices