API reference

seppy.loader

seppy.loader.bepi

seppy.loader.bepi.bepi_sixsp_download(date, path=None)[source]

Download BepiColombo/SIXS-P level 3 data file from SERPENTINE data server to local path

Parameters:

  • date (datetime object) – datetime of data to retrieve

  • path (str) – local path where the files will be stored

Returns:

downloaded_file – full local path to downloaded file

Return type:

str

seppy.loader.bepi.bepi_sixsp_l3_loader(startdate, enddate=None, resample=None, path=None, pos_timestamp='center')[source]

Loads BepiColombo/SIXS-P level 3 data and returns it as Pandas dataframe together with a dictionary providing the energy ranges per channel

Parameters:

  • startdate (str or datetime-like) – start date

  • enddate (str or datetime-like, optional) – end date

  • resample (str, optional) – resample frequency in format understandable by Pandas, e.g. ‘1min’, by default None. Note that this is just a simple wrapper around thepandas resample function that is calculating the mean of the data in the new time bins. This is not necessarily the correct way to resample data, depending on the data type (for example for errors)!

  • path (str, optional) – local path where the files are/should be stored, by default None, in which case the sunpy download folder will be used.

  • pos_timestamp (str, optional) – change the position of the timestamp: ‘center’ or ‘start’ of the accumulation interval, by default ‘center’.

Returns:

  • df (Pandas dataframe) – Pandas dataframe of measured fluxes and uncertaintites

  • channels_dict_df (dict) – Dictionary giving details on the measurement channels

seppy.loader.juice

seppy.loader.juice.juice_radem_download(date, path=None)[source]

Download JUICE/RADEM cruise science data file from ESA’s PSA to local path

Parameters:

  • date (datetime object) – datetime of data to retrieve

  • path (str) – local path where the files will be stored

Returns:

downloaded_file – full local path to downloaded file

Return type:

str

seppy.loader.juice.juice_radem_load(startdate, enddate, resample=None, path=None, pos_timestamp='center')[source]

Download & load JUICE/RADEM cruise science data and returns it as Pandas DataFrame (and metadata dictionaries). Note that the data is provided in counts and not converted to physical units (as of Nov 2025); also the instrument configuration changes over time.

Parameters:

  • startdate (datetime object) – start datetime of data to retrieve

  • enddate (datetime object) – end datetime of data to retrieve

  • resample (str) – resampling frequency (e.g. ‘1min’, ‘10min’, ‘1H’, etc.). If None, no resampling is applied.

  • path (str) – local path where the files are stored / will be downloaded to

  • pos_timestamp (str) – position of the timestamp when resampling (‘start’, ‘center’, ‘end’)

Returns:

  • df (Pandas DataFrame) – DataFrame containing the JUICE/RADEM data

  • energies_dict (dict) – Dictionary containing the JUICE/RADEM data energy and label information

  • metadata_dict (dict) – Dictionary containing the JUICE/RADEM data metadata

seppy.loader.juice.juice_radem_load_metadata(filename)[source]

Load JUICE/RADEM cruise science data metadata and return it as a dictionary

Returns:

  • energies_dict (dict) – Dictionary containing the JUICE/RADEM data energy and label information

  • metadata_dict (dict) – Dictionary containing the JUICE/RADEM data metadata

seppy.loader.psp

seppy.loader.psp.calc_av_en_flux_PSP_EPIHI(df, energies, en_channel, species, instrument, viewing)[source]

This function averages the flux of several energy channels into a combined energy channel channel numbers counted from 0

So far only works for EPIHI-HET

Parameters:

  • df (pd.DataFrame DataFrame containing HET data) – DataFrame containing PSP data

  • energies (dict) – Energy dict returned from psp_load

  • en_channel (int or list) – energy channel number(s) to be used

  • species (string) – ‘e’, ‘electrons’, ‘p’, ‘i’, ‘protons’, ‘ions’

  • instrument (string) – ‘het’

  • viewing (string) – ‘A’, ‘B’

Returns:

flux_out: contains channel-averaged flux

Return type:

pd.DataFrame

seppy.loader.psp.calc_av_en_flux_PSP_EPILO(df, en_dict, en_channel, species, mode, chan, viewing)[source]

This function averages the flux of several energy channels (and viewing directions) into a combined energy channel. channel numbers counted from 0

So far only works for EPILO PE chanF electrons

Parameters:

  • df (pd.DataFrame DataFrame containing HET data) – DataFrame containing PSP data

  • energies (dict) – Energy dict returned from psp_load

  • en_channel (int or list) – energy channel number(s) to be used

  • species (string) – ‘e’, ‘electrons’

  • mode (string) – ‘pe’ or ‘ic’. EPILO mode

  • chan (string) – ‘E’, ‘F’, ‘G’, ‘P’, ‘T’. EPILO chan

  • viewing (int or list) – EPILO viewing. 0 to 7 for electrons; 0 to 79 for ions (ions 70-79 correspond to electrons 7, i.e., the electron wedges are split up into 10 viewings for ions)

Returns:

flux_out: contains channel-averaged flux

Return type:

pd.DataFrame

seppy.loader.psp.psp_isois_load(dataset, startdate, enddate, epilo_channel='F', epilo_threshold=None, path=None, resample=None, all_columns=False)[source]

Downloads CDF files via SunPy/Fido from CDAWeb for ISOIS onboard PSP

Parameters:

  • dataset (str) –

    Name of PSP dataset:

    • ’PSP_ISOIS-EPIHI_L2-HET-RATES60’

    • ’PSP_ISOIS-EPIHI_L2-HET-RATES3600’ (higher coverage than ‘RATES60’ before mid-2021)

    • ’PSP_ISOIS-EPIHI_L2-LET1-RATES60’

    • ’PSP_ISOIS-EPIHI_L2-LET2-RATES60’

    • ’PSP_ISOIS-EPILO_L2-PE’

    • ’PSP_ISOIS-EPILO_L2-IC’

  • startdate (datetime or str) – Datetime object (e.g., dt.date(2021,12,31) or dt.datetime(2021,4,15)) or “standard” datetime string (e.g., “2021/04/15”) (enddate must always be later than startdate)

  • enddate (datetime or str) – Datetime object (e.g., dt.date(2021,12,31) or dt.datetime(2021,4,15)) or “standard” datetime string (e.g., “2021/04/15”) (enddate must always be later than startdate)

  • epilo_channel (string) – ‘E’, ‘F’, ‘G’ (for ‘EPILO PE’), or ‘C’, ‘D’, ‘P’, ‘R’, ‘T’ (for ‘EPILO IC’). EPILO chan, by default ‘F’

  • epilo_threshold (int or float, optional) – Replace ALL flux/countrate values above ‘epilo_threshold’ with np.nan, by default None. Only works for Electron count rates in ‘PSP_ISOIS-EPILO_L2-PE’ dataset

  • path (str, optional) – Local path for storing downloaded data, by default None

  • resample (str, optional) – resample frequency in format understandable by Pandas, e.g. ‘1min’, by default None. Note that this is just a simple wrapper around thepandas resample function that is calculating the mean of the data in the new time bins. This is not necessarily the correct way to resample data, depending on the data type (for example for errors)!

  • all_columns (boolean, optional) – Whether to return all columns of the datafile for EPILO (or skip usually unneeded columns for better performance), by default False

Returns:

  • df (Pandas dataframe) – See links above for the different datasets for a description of the dataframe columns

  • energies_dict (dictionary) – Dictionary containing energy information.

    NOTE: For EPIHI energy values are only loaded from the first day of the interval! For EPILO energy values are the mean of the whole loaded interval.

seppy.loader.psp.psp_load(dataset, startdate, enddate, epilo_channel='F', epilo_threshold=None, path=None, resample=None, all_columns=False)

Modification of sunpy’s read_cdf function to allow skipping of reading variables from a cdf file. This function is copied from sunpy under the terms of the BSD 2-Clause licence. See licenses/SUNPY_LICENSE.rst

seppy.loader.soho

seppy.loader.soho.calc_av_en_flux_ERNE(df, channels_dict_df, avg_channels, species='p', sensor='HED')[source]
avg_channelslist of int, optional

averaging channels m to n if [m, n] is provided (both integers), by default None

seppy.loader.soho.doy2dt(year, doy)[source]

convert decimal day of year to datetime

seppy.loader.soho.soho_ephin_download(date, path=None)[source]

Download SOHO/EPHIN level 2 ascii data file from Kiel university to local path

Parameters:

  • date (datetime object) – datetime of data to retrieve

  • path (str) – local path where the files will be stored

Returns:

downloaded_file – full local path to downloaded file

Return type:

str

seppy.loader.soho.soho_ephin_loader(startdate, enddate, resample=None, path=None, all_columns=False, pos_timestamp='center', use_uncorrected_data_on_own_risk=False)[source]

Load SOHO/EPHIN level 2 ascii data and return it as Pandas dataframe together with a dictionary providing the energy ranges per channel

Parameters:

  • startdate (str) – start date

  • enddate (str) – end date

  • resample (str, optional) – resample frequency in format understandable by Pandas, e.g. ‘1min’, by default None. Note that this is just a simple wrapper around thepandas resample function that is calculating the mean of the data in the new time bins. This is not necessarily the correct way to resample data, depending on the data type (for example for errors)!

  • path (str, optional) – local path where the files are/should be stored, by default None

  • all_columns (boolean, optional) – if True provide all availalbe columns in returned dataframe, by default False

  • pos_timestamp ({str}, optional) – change the position of the timestamp: ‘center’ or ‘start’ of the accumulation interval, or ‘original’ to do nothing, by default ‘center’.

Returns:

  • df (Pandas dataframe) – dataframe with either 15 channels of electron or 30 channels of proton/ion fluxes and their respective uncertainties

  • channels_dict_df (dict) – Pandas dataframe giving details on the measurement channels

seppy.loader.soho.soho_load(dataset, startdate, enddate, path=None, resample=None, pos_timestamp='center', max_conn=5)[source]

Download CDF files via SunPy/Fido from CDAWeb for CELIAS, EPHIN, ERNE onboard SOHO

Parameters:

  • dataset (str) –

    Name of SOHO dataset:

  • startdate (datetime or str) – Datetime object (e.g., dt.date(2021,12,31) or dt.datetime(2021,4,15)) or “standard” datetime string (e.g., “2021/04/15”) (enddate must always be later than startdate)

  • enddate (datetime or str) – Datetime object (e.g., dt.date(2021,12,31) or dt.datetime(2021,4,15)) or “standard” datetime string (e.g., “2021/04/15”) (enddate must always be later than startdate)

  • path (str, optional) – Local path for storing downloaded data, by default None

  • resample (str, optional) – Resample frequency in format understandable by Pandas, e.g. ‘1min’, by default None. Note that this is just a simple wrapper around thepandas resample function that is calculating the mean of the data in the new time bins. This is not necessarily the correct way to resample data, depending on the data type (for example for errors)!

  • pos_timestamp (str, optional) – change the position of the timestamp: ‘center’ or ‘start’ of the accumulation interval, or ‘original’ to do nothing, by default ‘center’.

  • max_conn (int, optional) – The number of parallel download slots used by Fido.fetch, by default 5

Returns:

  • df (Pandas dataframe) – See links above for the different datasets for a description of the dataframe columns

  • metadata (dict) – Dictionary containing different metadata, e.g., energy channels

seppy.loader.solo

seppy.loader.solo.mag_load(startdate, enddate, level='l2', data_type='normal', frame='rtn', path=None)[source]

Load SolO/MAG data

Load-in data for Solar Orbiter/MAG sensor. Supports level 2 and low latency data provided by CDAWeb. Optionally downloads missing data directly. Returns data as Pandas dataframe.

Parameters:

  • startdate ({datetime, str, or int}) – # # Datetime object (e.g., dt.date(2021,12,31) or dt.datetime(2021,4,15)), “standard” datetime string (e.g., “2021/04/15”) or integer of the form yyyymmdd with empty positions filled with zeros, e.g. ‘20210415’ (enddate must always be later than startdate)

  • enddate ({datetime, str, or int}) – # # Datetime object (e.g., dt.date(2021,12,31) or dt.datetime(2021,4,15)), “standard” datetime string (e.g., “2021/04/15”) or integer of the form yyyymmdd with empty positions filled with zeros, e.g. ‘20210415’ (enddate must always be later than startdate)

  • level ({'l2', 'll'}, optional) – Defines level of data product: level 2 (‘l2’) or low-latency (‘ll’). By default ‘l2’.

  • data_type ({'normal', 'normal-1-minute', or 'burst'}, optional) – By default ‘normal’.

  • frame ({'rtn', 'srf', or 'vso'}, optional) – Coordinate frame of MAG data. By default ‘rtn’.

  • path ({str}, optional) – Local path for storing downloaded data, by default None

Return type:

Pandas dataframe with fluxes and errors in ‘particles / (s cm^2 sr MeV)’

seppy.loader.stereo

seppy.loader.stereo.calc_av_en_flux_HET(df, channels_dict_df, avg_channels, species)
avg_channelslist of int, optional

averaging channels m to n if [m, n] is provided (both integers), by default None

seppy.loader.stereo.calc_av_en_flux_SEPT(df, channels_dict_df, avg_channels)[source]
avg_channelslist of int, optional

averaging channels m to n if [m, n] is provided (both integers), by default None

seppy.loader.stereo.calc_av_en_flux_ST_HET(df, channels_dict_df, avg_channels, species)[source]
avg_channelslist of int, optional

averaging channels m to n if [m, n] is provided (both integers), by default None

seppy.loader.stereo.stereo_load(instrument, startdate, enddate, spacecraft='ahead', mag_coord='RTN', sept_species='e', sept_viewing=None, path=None, resample=None, pos_timestamp='center', max_conn=5)[source]

Downloads CDF files via SunPy/Fido from CDAWeb for HET, LET, MAG, and SEPT onboard STEREO

Parameters:

  • instrument (str) –

    Name of STEREO instrument:

  • startdate (datetime or str) – Datetime object (e.g., dt.date(2021,12,31) or dt.datetime(2021,4,15)) or “standard” datetime string (e.g., “2021/04/15”) (enddate must always be later than startdate)

  • enddate (datetime or str) – Datetime object (e.g., dt.date(2021,12,31) or dt.datetime(2021,4,15)) or “standard” datetime string (e.g., “2021/04/15”) (enddate must always be later than startdate)

  • spacecraft (str, optional) – Name of STEREO spacecraft: ‘ahead’ or ‘behind’, by default ‘ahead’

  • mag_coord (str, optional) – Coordinate system for MAG: ‘RTN’ or ‘SC’, by default ‘RTN’

  • sept_species (str, optional) – Particle species for SEPT: ‘e’lectrons or ‘p’rotons (resp. ions), by default ‘e’

  • sept_viewing (str, optional) – Viewing direction for SEPT: ‘sun’, ‘asun’, ‘north’, or ‘south’, by default ‘sun’

  • path (str, optional) – Local path for storing downloaded data, by default None

  • resample (str, optional) – resample frequency in format understandable by Pandas, e.g. ‘1min’, by default None. Note that this is just a simple wrapper around thepandas resample function that is calculating the mean of the data in the new time bins. This is not necessarily the correct way to resample data, depending on the data type (for example for errors)!

  • pos_timestamp (str, optional) – change the position of the timestamp: ‘center’ or ‘start’ of the accumulation interval, or ‘original’ to do nothing, by default ‘center’.

  • max_conn (int, optional) – The number of parallel download slots used by Fido.fetch, by default 5

Returns:

  • df ({Pandas dataframe}) – See links above for the different datasets for a description of the dataframe columns

  • metadata ({dict}) – Dictionary containing different metadata, e.g., energy channels

seppy.loader.stereo.stereo_sept_download(date, spacecraft, species, viewing, path=None)[source]

Download STEREO/SEPT level 2 data file from Kiel university to local path

Parameters:

  • date (datetime object) – datetime of data to retrieve

  • spacecraft (str) – ‘ahead’ or ‘behind’

  • species (str) – ‘ele’ or ‘ion’

  • viewing (str) – ‘sun’, ‘asun’, ‘north’, ‘south’ - viewing direction of instrument

  • path (str) – local path where the files will be stored

Returns:

downloaded_file – full local path to downloaded file

Return type:

str

seppy.loader.stereo.stereo_sept_loader(startdate, enddate, spacecraft, species, viewing, resample=None, path=None, all_columns=False, pos_timestamp='center')[source]

Loads STEREO/SEPT data and returns it as Pandas dataframe together with a dictionary providing the energy ranges per channel

Parameters:

  • startdate (str) – start date

  • enddate (str) – end date

  • spacecraft (str) – STEREO spacecraft ‘a’head or ‘b’ehind

  • species (str) – particle species: ‘e’lectrons or ‘p’rotons (resp. ions)

  • viewing (str) – ‘sun’, ‘asun’, ‘north’, ‘south’ - viewing direction of instrument

  • resample (str, optional) – resample frequency in format understandable by Pandas, e.g. ‘1min’, by default None. Note that this is just a simple wrapper around thepandas resample function that is calculating the mean of the data in the new time bins. This is not necessarily the correct way to resample data, depending on the data type (for example for errors)!

  • path (str, optional) – local path where the files are/should be stored, by default None

  • all_columns (boolean, optional) – if True provide all availalbe columns in returned dataframe, by default False

Returns:

  • df (Pandas dataframe) – dataframe with either 15 channels of electron or 30 channels of proton/ion fluxes and their respective uncertainties

  • channels_dict_df (dict) – Pandas dataframe giving details on the measurement channels

seppy.loader.wind

seppy.loader.wind.wind3dp_download(dataset, startdate, enddate, path=None, **kwargs)[source]

Downloads Wind/3DP CDF files via SunPy/Fido from CDAWeb

Parameters:

  • dataset ({str}) –

    Name of Wind/3DP dataset:

    • ’WI_SFSP_3DP’: Electron omnidirectional fluxes 27 keV - 520 keV, often at 24 sec

    • ’WI_SFPD_3DP’: Electron energy-angle distributions 27 keV to 520 keV, often at 24 sec

    • ’WI_SOSP_3DP’: Proton omnidirectional fluxes 70 keV - 6.8 MeV, often at 24 sec

    • ’WI_SOPD_3DP’: Proton energy-angle distributions 70 keV - 6.8 MeV, often at 24 sec

  • startdate ({datetime or str}) – Datetime object (e.g., dt.date(2021,12,31) or dt.datetime(2021,4,15)) or “standard” datetime string (e.g., “2021/04/15”) (enddate must always be later than startdate)

  • enddate ({datetime or str}) – Datetime object (e.g., dt.date(2021,12,31) or dt.datetime(2021,4,15)) or “standard” datetime string (e.g., “2021/04/15”) (enddate must always be later than startdate)

  • path ({str}, optional) – Local path for storing downloaded data, by default None

Return type:

List of downloaded files

seppy.loader.wind.wind3dp_download_fido(dataset, startdate, enddate, path=None, max_conn=5)[source]

Downloads Wind/3DP CDF files via SunPy/Fido from CDAWeb

Parameters:

  • dataset (str) –

    Name of Wind/3DP dataset:

    • ’WI_SFSP_3DP’: Electron omnidirectional fluxes 27 keV - 520 keV, often at 24 sec

    • ’WI_SFPD_3DP’: Electron energy-angle distributions 27 keV to 520 keV, often at 24 sec

    • ’WI_SOSP_3DP’: Proton omnidirectional fluxes 70 keV - 6.8 MeV, often at 24 sec

    • ’WI_SOPD_3DP’: Proton energy-angle distributions 70 keV - 6.8 MeV, often at 24 sec

  • startdate (datetime or str) – Datetime object (e.g., dt.date(2021,12,31) or dt.datetime(2021,4,15)) or “standard” datetime string (e.g., “2021/04/15”) (enddate must always be later than startdate)

  • enddate (datetime or str) – Datetime object (e.g., dt.date(2021,12,31) or dt.datetime(2021,4,15)) or “standard” datetime string (e.g., “2021/04/15”) (enddate must always be later than startdate)

  • path (str, optional) – Local path for storing downloaded data, by default None

  • max_conn (int, optional) – The number of parallel download slots used by Fido.fetch, by default 5

Return type:

List of downloaded files

seppy.loader.wind.wind3dp_load(dataset, startdate, enddate, resample='1min', multi_index=True, path=None, threshold=None, **kwargs)[source]

Load-in data for Wind/3DP instrument. Provides released data obtained by SunPy through CDF files from CDAWeb. Returns data as Pandas dataframe.

Parameters:

  • dataset (str) –

    Name of Wind/3DP dataset:

    • ’WI_SFSP_3DP’: Electron omnidirectional fluxes 27 keV - 520 keV, often at 24 sec

    • ’WI_SFPD_3DP’: Electron energy-angle distributions 27 keV to 520 keV, often at 24 sec

    • ’WI_SOSP_3DP’: Proton omnidirectional fluxes 70 keV - 6.8 MeV, often at 24 sec

    • ’WI_SOPD_3DP’: Proton energy-angle distributions 70 keV - 6.8 MeV, often at 24 sec

  • startdate (datetime or str) – Datetime object (e.g., dt.date(2021,12,31) or dt.datetime(2021,4,15)) or “standard” datetime string (e.g., “2021/04/15”) (enddate must always be later than startdate)

  • enddate (datetime or str) – Datetime object (e.g., dt.date(2021,12,31) or dt.datetime(2021,4,15)) or “standard” datetime string (e.g., “2021/04/15”) (enddate must always be later than startdate)

  • resample (str, optional) – Frequency to which the original data (~24 seconds) is resamepled. Pandas frequency (e.g., ‘1min’ or ‘1h’) or None, by default “1min”. Note that this is just a simple wrapper around thepandas resample function that is calculating the mean of the data in the new time bins. This is not necessarily the correct way to resample data, depending on the data type (for example for errors)!

  • multi_index (bool, optional) – Provide output for pitch-angle resolved data as Pandas Dataframe with multiindex, by default True

  • path (str, optional) – Local path for storing downloaded data, by default None

  • threshold (int or float, optional) – Replace all FLUX values above ‘threshold’ with np.nan, by default None

Returns:

_description_

Return type:

_type_

seppy.loader.wind.wind3dp_single_download(file, path=None)[source]

Download a single Wind/3DP level 2 data file from SRL Berkeley to local path

Parameters:

  • file (str) – file to be downloaded, e.g. ‘wi_sfsp_3dp_20220602_v01.cdf’

  • path (str) – local path where the files will be stored

Returns:

downloaded_file – full local path to downloaded file

Return type:

str

seppy.loader.wind.wind_load(dataset, startdate, enddate, resample='1min', multi_index=True, path=None, threshold=None, **kwargs)

Modification of sunpy’s read_cdf function to allow loading of 3-dimensional variables from a cdf file. Adjusted only for Wind/3DP cdf files. Skipping units. This function is copied from sunpy under the terms of the BSD 2-Clause licence. See licenses/SUNPY_LICENSE.rst

seppy.tools

seppy.tools.Event

class seppy.tools.Event(start_date, end_date, spacecraft, sensor, species, data_level, data_path, viewing=None, radio_spacecraft=None, threshold=None)[source]

Initialize the Event object, for which the analysis functions can be run. This will download and read-in the necessary data.

Parameters:

  • start_date (datetime or str) – Start date for data loading

  • end_date (datetime or str) – End date for data loading

  • spacecraft (str) – Selected spacecraft; supported are ‘BepiColombo’, ‘PSP’, ‘SOHO’, ‘Solar Orbiter’, ‘STEREO-A’, ‘STEREO-B’, ‘Wind’

  • sensor (str) – Selected instrument. Supported options depend on spacecraft

  • species (str) – Selected species. Depending on instrument, this could be ‘electrons’, ‘protons’, or ‘ions’

  • data_level (str) – Selected data level. Usually ‘l2’, sometime ‘l3’.

  • data_path (str) – Full local path where the downloaded data should be stored.

  • viewing (str, optional) – Selected viewing direction; possible options depend on instrument. By default None

  • radio_spacecraft (tuple of str, optional) – Spacecraft from which radio spectrogram should be added. Supported are (‘ahead’, ‘STEREO-A’) and (‘behind’, ‘STEREO-B’). By default None

  • threshold (int or float, optional) – Only applies to Wind/3DP. Replace all FLUX values above given number with np.nan, by default None

dynamic_spectrum(view, cmap: str = 'magma', xlim: tuple = None, resample: str = None, save: bool = False, other=None) → None[source]

Shows all the different energy channels in a single 2D plot, and color codes the corresponding intensity*energy^2 by a colormap.

Parameters:

viewstr or None

The viewing direction of the sensor

cmapstr, default=’magma’

The colormap for the dynamic spectrum plot

xlim2-tuple of datetime strings (str, str)

Pandas-compatible datetime strings for the start and stop of the figure

resamplestr

Pandas-compatibe resampling string, e.g. ‘10min’ or ’30s’. Note that this is just a simple wrapper around thepandas resample function that is calculating the mean of the data in the new time bins. This is not necessarily the correct way to resample data, depending on the data type (for example for errors)!

savebool

Saves the image

find_onset(viewing, bg_start=None, bg_length=None, background_range=None, resample_period=None, channels=[0, 1], yscale='log', cusum_window=30, xlim=None, x_sigma=2, k_model: str = None)[source]

This method runs Poisson-CUSUM onset analysis for the Event object.

Parameters:

viewingstr

The viewing direction of the sensor.

bg_startint or float, default None

The start of background averaging from the start of the time series data in hours.

bg_lengthint or float, default None

The length of the background averaging period in hours.

background_rangetuple or list of datetimes with len=2, default None

The time range of background averaging. If defined, takes precedence over bg_start and bg_length.

resample_periodstr, default None

Pandas-compatible time string to average data. e.g. ’10s’ for 10 seconds or ‘2min’ for 2 minutes.

channelsint or list of 2 ints, default [0,1]

Index or a combination of indices to plot a channel or combination of channels.

yscalestr, default ‘log’

Matplotlib-compatible string for the scale of the y-axis. e.g. ‘log’ or ‘linear’

cusum_windowint, default 30

The amount of consecutive data points above the threshold before identifying an onset.

xlimtuple or list, default None

Panda-compatible datetimes or strings to assert the left and right boundary of the x-axis of the plot.

x_sigmaint, default 2

The multiplier of m_d in the definition of the control parameter k in Poisson-CUSUM method.

k_model{str}, default None

Leave to None to use the current k-parameter. Input ‘legacy’ to use the old definition for k.

print_energies(return_df=False)[source]

Prints out the channel name / energy range pairs

Parameter:

return_df : {bool} default False. If True, returns the df instead of displaying it.

tsa_plot(view, selection=None, xlim=None, resample=None)[source]

Makes an interactive time-shift plot

Parameters:

viewstr or None

Viewing direction for the chosen sensor

selection2-tuple

The indices of the channels one wishes to plot. End-exclusive.

xlim2-tuple

The start and end point of the plot as pandas-compatible datetimes or strings

resamplestr

Pandas-compatible resampling time-string, e.g. “2min” or “50s”. Note that this is just a simple wrapper around thepandas resample function that is calculating the mean of the data in the new time bins. This is not necessarily the correct way to resample data, depending on the data type (for example for errors)!

seppy.util

seppy.util.calc_particle_speed(mass, kinetic_energy)[source]

Calculates the relativistic particle speed.

Parameters:

  • mass (astropy units) – mass of the particle.

  • kinetic_energy (astropy units) – kinetic energy of the particle.

Returns:

relativistic particle speed.

Return type:

astropy units

seppy.util.calc_spiral_length(radial_dist, sw_speed)[source]

Calculates the Parker spiral length from the Sun up to a given radial distance.

Parameters:

  • radial_dist (astropy units) – radial distance to the Sun.

  • sw_speed (astropy units) – solar wind speed.

Returns:

Parker spiral length.

Return type:

astropy units

seppy.util.energy2momentum(species, kinetic_energy)[source]

Calculates the relativistic particle momentum derived from kinetic energy.

Parameters:

  • species (string) – particle species (electrons ‘e’ or protons ‘p’) used to determine the particle mass

  • kinetic_energy (float/astropy units) – kinetic energy of the particle using astropy units; if only float MeV is used

Returns:

relativistic particle momentum

Return type:

astropy units

seppy.util.energy2speed(species, kinetic_energy)[source]

Calculates the relativistic particle speed derived from kinetic energy.

Parameters:

  • species (string) – particle species (electrons ‘e’ or protons ‘p’) used to determine the particle mass

  • kinetic_energy (astropy units/float) – kinetic energy of the particle using astropy units; if only float, MeV is used

Returns:

relativistic particle speed.

Return type:

astropy units

seppy.util.get_sun_coords(time='now')[source]

Gets the astropy Sun coordinates.

Parameters:

time (datetime.datetime) – time at which coordinates are fetched.

Returns:

sun coordinates.

seppy.util.inf_inj_time(spacecraft, onset_time, species, kinetic_energy, sw_speed)[source]

Calculates the inferred injection time of a particle (electron or proton) from the Sun, given a detection time at some spacecraft.

Parameters:

  • spacecraft (str) – name of the spacecraft.

  • onset_time (datetime.datetime) – time of onset/detection.

  • species (str) – particle species, ‘p’ or ‘e’.

  • kinetic_energy (astropy units) – kinetic energy of particle. If no unit is supplied, is converted to MeV.

  • sw_speed (astropy units) – solar wind speed. If no unit is supplied, is converted to km/s.

Returns:

inferred injection time.

Return type:

datetime.datetime

seppy.util.intensity2psd(species, kinetic_energy, intensity)[source]

Calculates the phase space density (distribution function) derived from kinetic energy and intensity.

Parameters:

  • species (string) – particle species (electrons ‘e’ or protons ‘p’) used to determine the particle mass

  • kinetic_energy (astropy units) – kinetic energy of the particle using astropy units

  • intensity (astropy units) – differential intensity using astropy units

Returns:

phase space density

Return type:

astropy units

Example

import astropy.units as u f = intensity2psd(‘e’, 48*u.keV, 1e4/(u.cm**2 * u.sr * u.s * u.MeV))

seppy.util.intensity2vsd(species, kinetic_energy, intensity)[source]

Calculates the velocity space density (distribution function) derived from kinetic energy and intensity.

Parameters:

  • species (string) – particle species (electrons ‘e’ or protons ‘p’) used to determine the particle mass

  • kinetic_energy (astropy units) – kinetic energy of the particle using astropy units

  • intensity (astropy units) – differential intensity using astropy units

Returns:

phase space density

Return type:

astropy units

Example

import astropy.units as u f = intensity2vsd(‘e’, 48*u.keV, 1e4/(u.cm**2 * u.sr * u.s * u.MeV))

seppy.util.jupyterhub_data_path(path_org, path_hub='/home/jovyan/data')[source]

Checks if Notebook is run within SOLER/SERPENTINE JupyterHub. Returns the path of a common data folder if yes, and the original path if not.

seppy.util.k_legacy(mu: float, sigma: float, sigma_multiplier: float) → float[source]

The old standard k-parameter for SEPpy.

seppy.util.k_parameter(mu: float, sigma: float, sigma_multiplier: int) → float[source]

The standard version of k for the z-standardized intensity CUSUM.

Parameters:

mu{float, np.ndarray}

The mean of the background.

sigma{float, np.ndarray}

The standard deviation of the background.

sigma_multiplier{int,float}

The multiplier for mu_{d} != 0.

Returns:

k_param{float, np.ndarray} Type depends on the input type.

A valid k_parameter value (k >= 0).

seppy.util.propagated_mean_uncertainty(data: Series | DataFrame) → float | Series[source]

Aggregation function for uncertainties, which calculates the square root of the sum of squares divided by the number of samples in the bin.

This differs from the standard Root Mean Square (RMS), where the division by n occurs inside the square root: sqrt(sum(x**2) / n). Here, the division occurs outside: sqrt(sum(x**2)) / n. This form is appropriate for propagating uncertainties when averaging n measurements.

Works for both pd.Series and pd.DataFrame. In the case of a DataFrame, the calculation is performed per column.

Parameters:

data (pd.Series or pd.DataFrame) – The data to aggregate

Returns:

Sqrt of sum of squares divided by number of samples. Returns a single float for pd.Series input, or a pd.Series (one value per column) for pd.DataFrame input. Returns np.nan if the input is empty, all-NaN, or (for DataFrames) for any column that is empty or all-NaN.

Return type:

float or pd.Series

Raises:

TypeError – If data is not a pd.Series or pd.DataFrame.

seppy.util.radial_distance_to_sun(spacecraft, time='now')[source]

Gets the 3D radial distance of a spacecraft to the Sun. 3D here means that it’s the real spatial distance and not a projection on, say, the solar equatorial plane.

Parameters:

  • spacecraft (str) – spacecraft to look for.

  • time (datetime.datetime) – time at which to look for.

Returns:

radial distance.

Return type:

astropy units

seppy.util.reduce_list_generic(original_list, placeholder='xx', seperator='_')[source]

Reduces a list by replacing numeric sequences with placeholders.

Parameters:

  • original_list – The list of strings to reduce

  • placeholder – The string to replace numeric parts (default: “xx”)

  • seperator – The character used to split the strings (default: “_”)

Returns:

A sorted list of unique patterns

seppy.util.remove_duplicate_cdf_files(path=None)[source]

Removes duplicate .cdf files in the provided directory, keeping only the one with the highest version number.

Parameters:

path (string, optional) – Directory in which the .cdf files are. If None, current working directory will be used. By default None.

Returns:

deleted_files – List of deleted duplicate .cdf files.

Return type:

list

Examples

>>> from seppy.util import remove_duplicate_cdf_files
>>> deleted_files = remove_duplicate_cdf_files('/Users/johndoe/data/psp')
Removing duplicate .cdf files in /Users/johndoe/data/psp/
>>> print(deleted_files)
[]
seppy.util.resample_df(df: DataFrame | Series, resample: str, pos_timestamp: str = 'center', origin: str = 'start', cols_unc: list[str] | str = 'auto', keywords_unc: list[str] = ['unc', 'err', 'sigma'], verbose: bool = True) → DataFrame | Series[source]

Resamples a Pandas Dataframe or Series to a new frequency. Note that this is just a simple wrapper around the pandas resample function that is calculating the mean of the data in the new time bins. This is not necessarily the correct way to resample data, depending on the data type (for example for errors)!

Parameters:

  • df (pd.DataFrame or pd.Series) – The dataframe or series to resample

  • resample (str) – pandas-compatible time string, e.g., ‘1min’, ‘2H’ or ’25s’

  • pos_timestamp (str, default 'center') – Controls if the timestamp is at the center of the time bin, or at the start of it

  • origin (str, default 'start') – Controls if the origin of resampling is at the first entry of the input dataframe/series (‘start’), or at the start of the day (‘start_day’)

  • cols_unc (list, default 'auto') – List of specific column names in the dataframe (or name of the series) that contain uncertainties. These columns will be resampled using a custom function (sqrt of the sum of squares divided by number of samples in the bin) instead of just the arithmetic mean. If an empty list is provided (i.e. []), all columns will be resampled using the arithmetic mean. If set to ‘auto’ (default), the function will try to automatically detect columns with uncertainties based on their names (looking for the keywords provided in keywords_unc, by default ‘unc’, ‘err’ or ‘sigma’). Note that this automatic detection only works for single-level column DataFrames and Series.

  • keywords_unc (list, default ['unc', 'err', 'sigma']) – List of keywords to use for automatic detection of uncertainty. All columns with these keywords in their name will be treated as uncertainty columns when cols_unc is set to ‘auto’.

  • verbose (bool, default True) – If True, will print additional debug information, e.g., about automatically detected uncertainty columns. Deactivate at own risk and only if you know what you are doing!

Returns:

df

Return type:

pd.DataFrame or Series, depending on the input

seppy.util.speed2energy(species, speed)[source]

Calculates the relativistic kinetic energy derived from particle speed.

Parameters:

  • species (string) – particle species (electrons ‘e’ or protons ‘p’) used to determine the particle mass

  • speed (astropy units/float) – relativistic particle speed of the particle using astropy units; if only float, m/s is used

Returns:

kinetic energy

Return type:

astropy units

seppy.util.speed2momentum(species, speed)[source]

Calculates the relativistic particle momentum derived from speed.

Parameters:

  • species (string) – particle species (electrons ‘e’ or protons ‘p’) used to determine the particle mass

  • speed (float/astropy units) – kinetic energy of the particle using astropy units; if only float m/s is used

Returns:

relativistic particle momentum

Return type:

astropy units