API

Main Functions

magplots.fill_nan(y)

Fit a linear regression to the non-nan y values

Parameters

ynp.array

1D numpy array with NaNs in it

Returns

ynp.array

1D numpy array with no NaNs in it

Example Use

Creates a 1D array with NaNs and removes them:

y = np.array([40, 41, np.nan, 43, np.nan, 41])
fill_nan(y)

magplots.reject_outliers(y)

Function to reject outliers from a 1D dataset.

Parameters

ynp.array

1D numpy array with outliers

Returns

ynp.array

1D numpy array with outliers replaced by NaN

Example Use

Creates a 1D array with outliers and removes them:

reject_outliers(np.append(y, [-51e100, 41, 2, 45], axis=0))

magplots.magfetch(start=datetime.datetime(2016, 1, 25, 0, 0), end=datetime.datetime(2016, 1, 26, 0, 0), magname='atu', is_detrended=True, tgopw='', resolution='10sec')

Function to fetch data for a given magnetometer. Pulls from ai.cdas or Tromsø Geophysical Observatory.

Arguments

start, enddatetime

Datetimes of the start and end of sampled data range.

magnamestr

IAGA ID for magnetometer being sampled. e.g.: ‘upn’

is_detrendedbool, optional

Boolean for whether the median is subtracted out.

tgopwstr, optional

Password for Tromsø Geophysical Observatory. Calls magfetchtgo().

resolutionstr, optional

Data resolution for TGO data.

Returns

dfpandas.DataFrame

Pandas dataframe with columns [‘UT’, ‘MAGNETIC_NORTH_-_H’, ‘MAGNETIC_EAST_-_E’, ‘VERTICAL_DOWN_-_Z’].

Example Use

Generates dataframe for ATU:

magfetch(start = datetime.datetime(2018, 9, 4, 0, 0, 0),
            end = datetime.datetime(2018, 9, 5, 0, 0, 0),
            magname = 'atu',
            resolution = '1sec'
        )

magplots.magfetchtgo(start, end, magname, tgopw='', resolution='10sec', is_url_printed=False)

Pulls Tromsø Geophysical Observatory data from a RESTful API with a link

based on the date.

Parameters

startdatetime.datetime

The start date of the data to be fetched.

enddatetime.datetime

The end date of the data to be fetched.

magnamestr

The name of the magnetometer station.

tgopwstr

Password for Tromsø Geophysical Observatory.

resolutionstr

String for data resolution; e.g., ’10sec’; default ‘1sec’.

is_url_printedboolean

If set to True/1, prints URL to TGO. (Contains password.)

is_savedboolean

If is_saved == True, saves .gpx versions.

to local output directory

Returns

dfpandas.DataFrame

A pandas DataFrame containing the fetched data.

Example Use

Save the password locally in the file tgopw.txt. Run:

magfetchtgo()

magplots.magdf(start=datetime.datetime(2016, 1, 25, 0, 0), end=datetime.datetime(2016, 1, 26, 0, 0), maglist_a=None, maglist_b=None, is_detrended=True, is_pivoted=False, is_uniform=False, is_saved=False)

Function to create multi-indexable dataframe of all mag parameters for a

given period of time.

Arguments

start, enddatetime

Datetimes of the start and end of period of interest.

maglist_alist, optional

List of Arctic magnetometers. Defaults to [‘upn’, ‘umq’, ‘gdh’, ‘atu’, ‘skt’, ‘ghb’] if not declared.

maglist_blist, optional

Corresponding list of Antarctic magnetometers. Defaults to [‘pg0’, ‘pg1’, ‘pg2’, ‘pg3’, ‘pg4’, ‘pg5’] if not declared.

is_detrendedbool, optional

Boolean for whether median is subtracted from data. Defaults to True.

is_pivotedbool, optional

Boolean for whether returned dataframe is organized by timestamp. Defaults to False.

is_uniformbool, optional

Boolean for whether the resolution is made uniform (i.e., downsampled to slowest cadence). Defaults to True. Time series plots can be native resolution for both sets, but spectrogram plots should be uniform.

is_savedbool, optional

Boolean for whether resulting dataframe is saved to /output directory.

Returns

dataframepandas.DataFrame

Dataframe of Bx, By, Bz for each magnetometer in list.

Example Use

Generates dataframe with default values:

df = magdf(is_saved = True)

magplots.magfig(parameter='Bx', start=datetime.datetime(2016, 1, 25, 0, 0), end=datetime.datetime(2016, 1, 26, 0, 0), maglist_a=None, maglist_b=None, is_detrended=True, is_titled=True, is_saved=False, fstem=None, is_autoscaled=False, ylim=None, events=None, event_fontdict=None)

Function to create a stackplot for a given set of conjugate

magnetometers over a given length of time.

Arguments

parameterstr

The parameter of interest - Bx, By, or Bz. North/South, East/West, and vertical, respectively.

start, enddatetime

Datetimes of the start and end of plots.

maglist_alist, optional

List of Arctic magnetometers. Defaults to [‘upn’, ‘umq’, ‘gdh’, ‘atu’, ‘skt’, ‘ghb’].

maglist_blist, optional

Corresponding list of Antarctic magnetometers. Defaults to [‘pg0’, ‘pg1’, ‘pg2’, ‘pg3’, ‘pg4’, ‘pg5’].

is_detrendedbool, optional

Boolean for whether median is subtracted from data. Defaults to True.

is_titledbool, optional

Boolean for overall plot title. Defaults to True.

is_savedbool, optional

Boolean for whether resulting figure is saved to /output directory.

fstemstr, optional

String for filename prefix. Empty by default.

is_autoscaledbool, optional

Boolean for whether time domain plot is autoscaled. Defaults to False.

ylimlist, optional

y-axis limits for time domain plot, in nanotesla above, below median. Defaults to [-150, 150].

eventslist, optional

List of datetimes for events marked on figure. Empty by default.

Returns

figmatplotlib.figure.Figure

The generated figure.

Example Use

Generate figure for selected time range. Run:

start = datetime.datetime(2019, 8, 2, 0, 0, 0)
end = datetime.datetime(2019, 8, 3, 0, 0, 0)
magfig(start=start, end=end)

magplots.magspect(parameter='Bx', start=datetime.datetime(2016, 1, 25, 0, 0), end=datetime.datetime(2016, 1, 26, 0, 0), maglist_a=None, maglist_b=None, is_detrended=True, is_saved=True, fstem=None, is_uniform=True, is_logaxis=False, is_logcolor=True, colormap='viridis', is_overplotted=True, is_autoscaled=False, ylim=None, color='white', events=None, event_fontdict=None)

Function to create spectrogram plots for conjugate magnetometers.

Arguments

parameterstr

The parameter of interest - Bx, By, or Bz. North/South, East/West, and vertical, respectively.

start, enddatetime

Datetimes of the start and end of plots.

maglist_alist, optional

List of Arctic magnetometers. Defaults to [‘upn’, ‘umq’, ‘gdh’, ‘atu’, ‘skt’, ‘ghb’].

maglist_blist, optional

Corresponding list of Antarctic magnetometers. Defaults to [‘pg0’, ‘pg1’, ‘pg2’, ‘pg3’, ‘pg4’, ‘pg5’].

is_savedbool, optional

Boolean for whether resulting figure is saved to /output directory.

fstemstr, optional

String for filename prefix. Empty by default.

is_uniformbool, optional

Boolean to pass to magdf() so that both sets of plots are the same resolution. Defaults to True.

is_logaxisbool, optional

Boolean for whether the y-axis is logarithmic. Defaults to False.

is_logcolorbool, optional

Boolean for whether colormap is logarithmic. Defaults to True.

colormapstr, optional

matplotlib colormap name. Defaults to Viridis.

is_overplottedbool, optional

Time domain plot is overlaid on spectrogram plot. Defaults to True.

is_autoscaledbool, optional

Boolean for whether time domain plot is autoscaled. Defaults to False.

ylimlist, optional

y-axis limits for time domain plot, in nanotesla above and below median. Defaults to [-150, 150].

colorstr, optional

Color for overplotting time domain data. Defaults to White.

eventslist, optional

List of datetimes for events marked on figure. Empty by default.

event_fontdictdict, optional

Font dict for formatting of event labels. Defaults to {‘size’: 20, ‘weight’: ‘bold’}.

Returns

figurematplotlib.figure.Figure

Figure of stacked plots for date in question, with events marked.

Example Use

Generate figure for selected time range. Run:

start = datetime.datetime(2019, 8, 2, 0, 0, 0)
end = datetime.datetime(2019, 8, 3, 0, 0, 0)
magspect(start=start, end=end)

magplots.wavepwr(station_id, parameter, start, end, f_lower=1.667, f_upper=6.667, is_saved=False, is_detrended=True)

Function to determine Pc5 (by default) wave power for a given

magnetometer, parameter and time frame.

Arguments

station_idstr

Station ID in lowercase, e.g., ‘atu’, ‘pg4’.

parameterstr

‘Bx’, ‘By’ or ‘Bz’.

start, enddatetime

Datetimes of interval.

f_lower, f_upperfloat

Range of frequencies of interest in mHz.

is_savedbool, optional

Boolean for whether loaded data is saved to /output directory. Defaults to False.

is_detrendedbool, optional

Boolean for whether median is subtracted from data. Defaults to True.

Returns

pwrfloat

Calculated wave power in range of interest.

Example Use

Calculate wave power in Pc5 band for selected time range at PG4. Run:

start = datetime.datetime(2019, 8, 2, 0, 0, 0)
end = datetime.datetime(2019, 8, 3, 0, 0, 0)
wavepwr('pg4', parameter = 'Bx', start = start,
         end = end)

magplots.wavefig(stations=None, parameter='Bx', start=datetime.datetime(2016, 1, 25, 0, 0), end=datetime.datetime(2016, 1, 26, 0, 0), maglist_a=None, maglist_b=None, f_lower=1.667, f_upper=6.667, is_maglist_only=True, is_detrended=True, is_saved=False, fstem=None)

Function to create wave power plot for a given set of magnetometers.

Arguments

stationspandas.DataFrame, optional

Dataframe of stations with columns IAGA, AACGMLAT, AACGMLON. If left empty, will pull from local file stations.csv.

parameterstr

The parameter of interest - Bx, By, or Bz. North/South, East/West, and vertical, respectively.

start, enddatetime

Datetimes of the start and end of plots.

maglist_alist, optional

List of Arctic magnetometers. Defaults to [‘upn’, ‘umq’, ‘gdh’, ‘atu’, ‘skt’, ‘ghb’].

maglist_blist, optional

Corresponding list of Antarctic magnetometers. Defaults to [‘pg0’, ‘pg1’, ‘pg2’, ‘pg3’, ‘pg4’, ‘pg5’].

f_lower, f_upperfloat

Range of frequencies of interest in mHz.

is_maglist_onlybool, optional

Boolean for whether only maglist_a and maglist_b stations are included from the complete station list.

is_detrendedbool, optional

Boolean for whether median is subtracted from data. Defaults to True.

is_savedbool, optional

Boolean for whether resulting figure is saved to /output directory.

fstemstr, optional

String for filename prefix. Empty by default.

Returns

figurematplotlib.figure.Figure

Figure showing wave power vs longitude, with Artic and Antarctic magnetometers overlaid.

Example Use

Generate wave power plot for default range:

wavefig(is_saved = True)

magplots.magall(start=datetime.datetime(2016, 1, 25, 0, 0), end=datetime.datetime(2016, 1, 26, 0, 0), maglist_a=None, maglist_b=None, f_lower=1.667, f_upper=6.667, is_detrended=True, is_saved=True, fstem=None, ylim=None, events=None, event_fontdict=None, stations=None, is_maglist_only=True)

Function to create all plots for conjugate magnetometers in a given timespan. Generates plots for all parameters: Bx, By, and Bz: North/South, East/West, and vertical, respectively.

Arguments

start, enddatetime

Datetimes of the start and end of plots.

maglist_alist, optional

List of Arctic magnetometers. Defaults to [‘upn’, ‘umq’, ‘gdh’, ‘atu’, ‘skt’, ‘ghb’].

maglist_blist, optional

Corresponding list of Antarctic magnetometers. Defaults to [‘pg0’, ‘pg1’, ‘pg2’, ‘pg3’, ‘pg4’, ‘pg5’].

f_lower, f_upperfloat

Range of frequencies of interest in mHz.

is_detrendedbool, optional

Boolean for whether median is subtracted from data. Defaults to True.

is_savedbool, optional

Boolean for whether resulting figure is saved to /output directory.

fstemstr, optional

String for filename prefix. Empty by default.

ylimlist, optional

y-axis limits for time domain plot, in nanotesla above and below median. Defaults to [-150, 150].

eventslist, optional

List of datetimes for events marked on figure. Empty by default.

event_fontdictdict, optional

Font dict for formatting of event labels. Defaults to {‘size’: 20, ‘weight’: ‘bold’}.

stationspandas.DataFrame, optional

Table of station coordinates. (Type help(wavefig) for more information.)

is_maglist_onlybool, optional

Boolean for whether only maglist_a and maglist_b stations are included from the complete station list.

Returns

None

Saves all files to output/ directory.

Example Use

Generate all plots for default range:

magall(is_verbose = true)