Methods

Several methods exist to help combine multiple data sets and convert between equivalent indices.

ACE

Supports the ACE instrument by providing reference and acknowledgement information.

Provides general routines for the ACE space weather instruments.

pysatSpaceWeather.instruments.methods.ace.ace_swepam_hourly_omni_norm(as_inst, speed_key='sw_bulk_speed', dens_key='sw_proton_dens', temp_key='sw_ion_temp')[source]

Normalize ACE SWEPAM variables as described in the OMNI processing _[1].

Parameters
as_instpysat.Instrument

pysat Instrument object with ACE SWEPAM data.

speed_keystr

Data key for bulk solar wind speed data in km/s (default=’sw_bulk_speed’)

dens_keystr

Data key for solar wind proton density data in P/cm^3 (default=’sw_proton_dens’)

temp_keystr

Data key for solar wind ion temperature data in K (default=’sw_ion_temp’)

References

[1] https://omniweb.gsfc.nasa.gov/html/omni_min_data.html

pysatSpaceWeather.instruments.methods.ace.acknowledgements()[source]

Define the acknowledgements for the specified ACE instrument.

Returns
acknstr

Acknowledgements for the ACE instrument

pysatSpaceWeather.instruments.methods.ace.clean(inst)[source]

Clean the common aspects of the ACE space weather data.

Parameters
instpysat.Instrument

ACE pysat.Instrument object

Returns
max_statusint

Maximum allowed status

pysatSpaceWeather.instruments.methods.ace.common_metadata()[source]

Define the common metadata information for all ACE instruments.

Returns
metapysat.Meta

pysat Meta class with ‘jd’ and ‘sec’ initiated

status_descstr

Description of the status flags

pysatSpaceWeather.instruments.methods.ace.download(date_array, name, tag='', inst_id='', data_path='', now=None)[source]

Download the requested ACE Space Weather data.

Parameters
date_arrayarray-like

Array of datetime values

namestr

ACE Instrument name.

tagstr

ACE Instrument tag. (default=’’)

inst_idstr

ACE instrument ID. (default=’’)

data_pathstr

Path to data directory. (default=’’)

nowdt.datetime or NoneType

Current universal time, if None this is determined for each download. (default=None)

Warning

  • Only able to download current real-time data

  • File requested not available on server

pysatSpaceWeather.instruments.methods.ace.list_files(name, tag='', inst_id='', data_path='', format_str=None)[source]

List the local ACE data files.

Parameters
namestr

ACE Instrument name.

tagstr

ACE Instrument tag. (default=’’)

inst_idstr

Specifies the ACE instrument ID. (default=’’)

data_pathstr

Path to data directory. (default=’’)

format_strstr or NoneType

User specified file format. If None is specified, the default formats associated with the supplied tags are used. (default=None)

Returns
filespysat.Files

A class containing the verified available files

pysatSpaceWeather.instruments.methods.ace.load_csv_data(fnames, read_csv_kwargs=None)[source]

Load CSV data from a list of files into a single DataFrame.

Deprecated since version 0.0.5: load_csv_data will be removed in pysatSpaceWeather 0.0.6+, as it has been moved to pysat.instruments.methods.general as of pysat 3.0.1.

Parameters
fnamesarray-like

Series, list, or array of filenames

read_csv_kwargsdict or NoneType

Dict of kwargs to apply to pds.read_csv. (default=None)

Returns
datapds.DataFrame

Data frame with data from all files in the fnames list

See also

pds.read_csv, pysat.instruments.methods.general.load_csv_data
pysatSpaceWeather.instruments.methods.ace.references(name)[source]

Define the references for the specified ACE instrument.

Parameters
namestr

Instrument name of the ACE instrument

Returns
refstr

Reference for the ACE instrument paper

Dst

Supports the Dst ring current index by providing reference and acknowledgement information.

Provides default routines for Dst.

pysatSpaceWeather.instruments.methods.dst.acknowledgements(tag)[source]

Define the acknowledgements for the Dst data.

Parameters
tagstr

Tag of the space weather index

Returns
acknstr

Acknowledgements string associated with the appropriate Dst tag.

pysatSpaceWeather.instruments.methods.dst.references(tag)[source]

Define the references for the Dst data.

Parameters
tagstring

Tag of the space weather index

Returns
refsstr

Reference string associated with the appropriate Dst tag.

F 10.7

Supports the F 10.7 radio flux by providing reference and acknowledgement information as well as a routine to combine F 10.7 data obtained from multiple sources.

Routines for the F10.7 solar index.

pysatSpaceWeather.instruments.methods.f107.acknowledgements(tag)[source]

Define the acknowledgements for the F10.7 data.

Parameters
tagstr

Tag of the space waether index

Returns
acknstr

Acknowledgements string associated with the appropriate F10.7 tag.

pysatSpaceWeather.instruments.methods.f107.calc_f107a(f107_inst, f107_name='f107', f107a_name='f107a', min_pnts=41)[source]

Calculate the 81 day mean F10.7.

Parameters
f107_instpysat.Instrument

pysat Instrument holding the F10.7 data

f107_namestr

Data column name for the F10.7 data (default=’f107’)

f107a_namestr

Data column name for the F10.7a data (default=’f107a’)

min_pntsint

Minimum number of points required to calculate an average (default=41)

pysatSpaceWeather.instruments.methods.f107.combine_f107(standard_inst, forecast_inst, start=None, stop=None)[source]

Combine the output from the measured and forecasted F10.7 sources.

Parameters
standard_instpysat.Instrument or NoneType

Instrument object containing data for the ‘sw’ platform, ‘f107’ name, and ‘historic’, ‘prelim’, or ‘daily’ tag

forecast_instpysat.Instrument or NoneType

Instrument object containing data for the ‘sw’ platform, ‘f107’ name, and ‘prelim’, ‘45day’ or ‘forecast’ tag

startdt.datetime or NoneType

Starting time for combining data, or None to use earliest loaded date from the pysat Instruments (default=None)

stopdt.datetime or NoneType

Ending time for combining data, or None to use the latest loaded date from the pysat Instruments (default=None)

Returns
f107_instpysat.Instrument

Instrument object containing F10.7 observations for the desired period of time, merging the standard, 45day, and forecasted values based on their reliability

Raises
ValueError

If appropriate time data is not supplied, or if the date range is badly formed.

Notes

Merging prioritizes the standard data, then the 45day data, and finally the forecast data

Will not attempt to download any missing data, but will load data

pysatSpaceWeather.instruments.methods.f107.parse_45day_block(block_lines)[source]

Parse the data blocks used in the 45-day Ap and F10.7 Flux Forecast file.

Parameters
block_lineslist

List of lines containing data in this data block

Returns
dateslist

List of dates for each date/data pair in this block

valueslist

List of values for each date/data pair in this block

pysatSpaceWeather.instruments.methods.f107.parse_daily_solar_data(data_lines, year, optical)[source]

Parse the data in the SWPC daily solar index file.

Parameters
data_lineslist

List of lines containing data

yearlist

Year of file

opticalboolean

Flag denoting whether or not optical data is available

Returns
dateslist

List of dates for each date/data pair in this block

valuesdict

Dict of lists of values, where each key is the value name

pysatSpaceWeather.instruments.methods.f107.references(tag)[source]

Define the references for the F10.7 data.

Parameters
tagstr

Instrument tag for the F10.7 data.

Returns
refsstr

Reference string associated with the appropriate F10.7 tag.

pysatSpaceWeather.instruments.methods.f107.rewrite_daily_file(year, outfile, lines)[source]

Rewrite the SWPC Daily Solar Data files.

Parameters
yearint

Year of data file (format changes based on date)

outfilestr

Output filename

linesstr

String containing all output data (result of ‘read’)

Kp and Ap

Supports the Kp instrument by providing reference and acknowledgement information, a routine to combine Kp from multiple sources, routines to convert between Kp and Ap, and a routine that uses Kp data as a geomagnetic activity filter for other data sets.

Provides routines to support the geomagnetic indeces, Kp and Ap.

pysatSpaceWeather.instruments.methods.kp_ap.acknowledgements(name, tag)[source]

Define the acknowledgements for the geomagnetic data sets.

Parameters
namestr

Instrument name of space weather index, accepts ‘kp’ or ‘ap’.

tagstr

Instrument tag.

pysatSpaceWeather.instruments.methods.kp_ap.calc_daily_Ap(ap_inst, ap_name='3hr_ap', daily_name='Ap', running_name=None)[source]

Calculate the daily Ap index from the 3hr ap index.

Parameters
ap_instpysat.Instrument

pysat instrument containing 3-hourly ap data

ap_namestr

Column name for 3-hourly ap data (default=’3hr_ap’)

daily_namestr

Column name for daily Ap data (default=’Ap’)

running_namestr or NoneType

Column name for daily running average of ap, not output if None (default=None)

Raises
ValueError

If ap_name or daily_name aren’t present in ap_inst

pysatSpaceWeather.instruments.methods.kp_ap.combine_kp(standard_inst=None, recent_inst=None, forecast_inst=None, start=None, stop=None, fill_val=nan)[source]

Combine the output from the different Kp sources for a range of dates.

Parameters
standard_instpysat.Instrument or NoneType

Instrument object containing data for the ‘sw’ platform, ‘kp’ name, and ‘’ tag or None to exclude (default=None)

recent_instpysat.Instrument or NoneType

Instrument object containing data for the ‘sw’ platform, ‘kp’ name, and ‘recent’ tag or None to exclude (default=None)

forecast_instpysat.Instrument or NoneType

Instrument object containing data for the ‘sw’ platform, ‘kp’ name, and ‘forecast’ tag or None to exclude (default=None)

startdt.datetime or NoneType

Starting time for combining data, or None to use earliest loaded date from the pysat Instruments (default=None)

stopdt.datetime

Ending time for combining data, or None to use the latest loaded date from the pysat Instruments (default=None)

fill_valint or float

Desired fill value (since the standard instrument fill value differs from the other sources) (default=np.nan)

Returns
kp_instpysat.Instrument

Instrument object containing Kp observations for the desired period of time, merging the standard, recent, and forecasted values based on their reliability

Raises
ValueError

If only one Kp instrument or bad times are provided

pysatSpaceWeather.instruments.methods.kp_ap.convert_3hr_kp_to_ap(kp_inst, var_name='Kp')[source]

Calculate 3 hour ap from 3 hour Kp index.

Parameters
kp_instpysat.Instrument

Instrument containing Kp data

var_namestr

Variable name for the Kp data (default=’Kp’)

Raises
ValueError

If var_name is not present in kp_inst.

pysatSpaceWeather.instruments.methods.kp_ap.convert_ap_to_kp(ap_data, fill_val=- 1, ap_name='ap', kp_name='Kp')[source]

Convert Ap into Kp.

Parameters
ap_dataarray-like

Array-like object containing Ap data

fill_valint, float, NoneType

Fill value for the data set (default=-1)

ap_namestr

Name of the input ap (default=’ap’)

kp_namestr

Name of the output Kp (default=’Kp’)

Returns
kp_dataarray-like

Array-like object containing Kp data

metaMetadata

Metadata object containing information about transformed data

pysatSpaceWeather.instruments.methods.kp_ap.filter_geomag(inst, min_kp=0, max_kp=9, filter_time=24, kp_inst=None, var_name='Kp')[source]

Filter pysat.Instrument data for given time after Kp drops below gate.

Parameters
instpysat.Instrument

Instrument with non-Kp data to be filtered by geomagnetic activity

min_kpfloat

Minimum Kp value allowed. Kp values below this filter the data in inst (default=0)

max_kpfloat

Maximum Kp value allowed. Kp values above this filter the data in inst (default=9)

filter_timeint

Number of hours to filter data after Kp drops below max_kp (default=24)

kp_instpysat.Instrument or NoneType

Kp pysat.Instrument object with or without data already loaded. If None, will load GFZ historic kp data for the instrument date (default=None)

var_namestr

String providing the variable name for the Kp data (default=’Kp’)

pysatSpaceWeather.instruments.methods.kp_ap.initialize_kp_metadata(meta, data_key, fill_val=- 1)[source]

Initialize the Kp meta data using our knowledge of the index.

Parameters
metapysat._meta.Meta

Pysat Metadata

data_keystr

String denoting the data key

fill_valint or float

File-specific fill value (default=-1)

pysatSpaceWeather.instruments.methods.kp_ap.references(name, tag)[source]

Define the references for the geomagnetic data sets.

Parameters
namestr

Instrument name of space weather index, accepts kp or ap.

tagstr

Instrument tag.

pysatSpaceWeather.instruments.methods.kp_ap.round_ap(ap_in, fill_val=nan)[source]

Round an ap value to the nearest Kp value.

Parameters
ap_infloat

Ap value as a floating point number.

fill_valfloat

Value for unassigned or bad indices. (default=np.nan)

Returns
float

Fill value for infinite or out-of-range data, otherwise the best kp index is provided.