plots module¶

Module containing plotting functions.

Part of the MagPySV package for geomagnetic data analysis. This module provides various plotting functions.

magpysv.plots.compare_proxies(*, fname1, fname2, legend_text, fig_size=(8, 6), font_size=12, label_size=16, save_fig=False, write_path=None)[source]¶

Compare proxies of unmodelled external signal for different analyses.

Calculates the correlation coefficients of two given proxies for unmodelled external signals and includes it on a plot of the two series. Each proxy is formed of the SV residuals projected into the eigendirection(s) of the largest eigenvalues of the residual covariance matriloc. The proxies are reduced to zero-mean and unit-variance on the plots (zscore).

Parameters:

fname1 (str) – path to file containing a time series of proxy for noise.
fname2 (str) – path to a second file containing a proxy for noise.
legend_text (str) – text to include on the plot legend.
fig_size (array) – figure size in inches. Defaults to 8 inches by 6 inches.
font_size (int) – font size for axes. Defaults to 12 pt.
label_size (int) – font size for axis labels. Defaults to 16 pt.
save_fig (bool) – option to save figure. Defaults to False.
write_path (str) – output path for figure if saved.

magpysv.plots.plot_eigenvalues(*, values, fig_size=(8, 6), font_size=12, label_size=16, save_fig=False, write_path=None)[source]¶

Plot eigenvalues of the covariance matrix of SV residuals.

Produces a plot of the eigenvalues obtained during the principal component analysis (PCA) of SV residuals. The largest eigenvalue represents the eigendirection with the largest contribution to the residuals (i.e. the “noisy” direction.). The smallest eigenvalue represents the eigendirection with the smallest contribution to the residuals (the “clean” direction). See Wardinski & Holme (2011, GJI, https://doi.org/10.1111/j.1365-246X.2011.04988.x) for further details.

Parameters:

values (array) – the eigenvalues obtained from the principal component analysis of the SV residuals.
fig_size (array) – figure size in inches. Defaults to 8 inches by 6 inches.
font_size (int) – font size for axes. Defaults to 12 pt.
label_size (int) – font size for axis labels. Defaults to 16 pt.
save_fig (bool) – option to save figure. Defaults to False.
write_path (str) – output path for figure if saved.

magpysv.plots.plot_eigenvectors(*, obs_names, eigenvecs, fig_size=(8, 6), font_size=12, label_size=16, save_fig=False, write_path=None)[source]¶

Plot eigenvectors of the covariance matrix of SV residuals.

Produces a plot of the eigenvectors corresponding to the n largest eigenvalues of the covariance matrix obtained during PCA of SV residuals, where n is the number of eigenvalues used as a proxy for unmodelled external field signal. The n eigenvectors corresponding to the n largest eigenvalue represent the directions with the largest contribution to the residuals (i.e. the “noisiest” directions). See Wardinski & Holme (2011, GJI, https://doi.org/10.1111/j.1365-246X.2011.04988.x) for further details.

Parameters:

obs_names (list) – list of observatory names given as three digit IAGA codes.
eigenvecs (array) – the eigenvalues obtained from the principal
analysis of the SV residuals. (component) –
fig_size (array) – figure size in inches. Defaults to 8 inches by 6 inches.
font_size (int) – font size for axes. Defaults to 12 pt.
label_size (int) – font size for axis labels. Defaults to 16 pt.
save_fig (bool) – option to save figure. Defaults to False.
write_path (str) – output path for figure if saved.

magpysv.plots.plot_index(*, index_file, dates, projected_residuals, fig_size=(8, 6), font_size=12, label_size=16, plot_legend=True, save_fig=False, write_path=None, index_name='Dst')[source]¶

Compare the proxy used to denoise the SV data with a geomagnetic index.

Loads geomagnetic index and plots it alongside the signal used as a proxy for unmodelled external signal. Both time series are reduced to zero mean and unit variance (i.e. their zscore) for plotting.

Parameters:

dates (datetime.datetime) – dates of time series measurements.
index_file (str) – path to the file containing index data.
projected_residuals (time series) – difference between modelled and SV rotated into the eigendirections obtained during denoising (principal component analysis). The proxy for unmodelled external signal is the residual projected in the noisiest eigendirection(s).
index_name (str) – name of index used in comparison e.g. Dst or ap. Defaults to Dst.
fig_size (array) – figure size in inches. Defaults to 8 inches by 6 inches.
font_size (int) – font size for axes. Defaults to 12 pt.
label_size (int) – font size for axis labels. Defaults to 16 pt.
plot_legend (bool) – option to include a legend on the plot. Defaults to True.
save_fig (bool) – option to save figure. Defaults to False.
write_path (str) – output path for figure if saved.

magpysv.plots.plot_index_dft(*, index_file, dates, signal, fig_size=(8, 6), font_size=12, label_size=16, plot_legend=True, save_fig=False, write_path=None, index_name='Dst')[source]¶

Compare the DFTs of the proxy signal with that of a geomagnetic index.

Loads index data, calculates its DFT using an FFT algorithm and plots it alongside the DFT of the signal used as a proxy for unmodelled external signal. The length of the time series are padded with zeroes up to the next power of two.

Parameters:

dates (datetime.datetime) – dates of time series measurements.
signal (time series) – proxy for unmodelled external signal used in the denoising process (principal component analysis). The proxy is the residual in the noisiest eigendirection(s).
index_file (str) – path to the file containing index data.
index_name (str) – name of index used in comparison e.g. Dst or Dcx. Defaults to Dst.
fig_size (array) – figure size in inches. Defaults to 8 inches by 6 inches.
font_size (int) – font size for axes. Defaults to 12 pt.
label_size (int) – font size for axis labels. Defaults to 16 pt.
plot_legend (bool) – option to include a legend on the plot. Defaults to True.
save_fig (bool) – option to save figure. Defaults to False.
write_path (str) – output path for figure if saved.

magpysv.plots.plot_mf(*, dates, mf, model, obs, model_name, fig_size=(8, 6), font_size=12, label_size=16, plot_legend=True, save_fig=False, write_path=None)[source]¶

Plot the SV and model prediction for a single observatory.

Produces a plot of the X, Y and Z components of the SV and field model prediction for a single observatory.

Parameters:

dates (datetime.datetime) – dates of time series measurements.
mf (time series) – X, Y and Z components of magnetic field at a single location.
model (time series) – X, Y and Z components of the field predicted by a field model for the same location as the data.
obs (str) – observatory name given as three digit IAGA code.
model_name (str) – field model name.
fig_size (array) – figure size in inches. Defaults to 8 inches by 6 inches.
font_size (int) – font size for axes. Defaults to 12 pt.
label_size (int) – font size for axis labels. Defaults to 16 pt.
plot_legend (bool) – option to include a legend on the plot. Defaults to True.
save_fig (bool) – option to save figure. Defaults to False.
write_path (str) – output path for figure if saved.

magpysv.plots.plot_outliers(*, dates, signal, obs_name, outliers, signal_type='SV', fig_size=(8, 6), font_size=12, label_size=16, save_fig=False, write_path=None)[source]¶

Plot the SV and identified outliers.

Parameters:

dates (datetime.datetime) – dates of time series measurements.
signal (time series) – single component of SV at a single location.
obs_name (str) – states the SV component and observatory name given as three digit IAGA code. For example, the X component at NGK would be x_ngk if obs_name is taken from the pandas.DataFrame containing SV data for all observatories combined.
outliers (array) – outliers identified by the denoise.detect_outliers function
signal_type (str) – specify whether magnetic field (‘MF’) or secular variation (‘SV’) is plotted. Defaults to SV.
fig_size (array) – figure size in inches. Defaults to 8 inches by 6 inches.
font_size (int) – font size for axes. Defaults to 12 pt.
label_size (int) – font size for axis labels. Defaults to 16 pt.
save_fig (bool) – option to save figure. Defaults to False.
write_path (str) – output path for figure if saved.

magpysv.plots.plot_residuals_dft(*, projected_residuals, dates, fig_size=(10, 8), font_size=12, label_size=16, plot_legend=True, save_fig=False, write_path=None)[source]¶

Compare the DFTs of the projected residuals with each other.

Calculates the DFT of the residuals in each eigendirection given and plots it alongside the residuals themselves. Produces a single figure with each eigendirection included as a subplot. Use plot_residuals_dft_all if a separate figure per eigendirection is desired. The length of the time series are padded with zeroes up to the next power of two.

Parameters:

dates (datetime.datetime) – dates of time series measurements.
projected_residuals (time series) – difference between modelled and SV rotated into the eigendirections obtained during denoising (principal component analysis). The proxy for unmodelled external signal is the residual projected in the noisiest eigendirection(s).
fig_size (array) – figure size in inches. Defaults to 8 inches by 6 inches.
font_size (int) – font size for axes. Defaults to 12 pt.
label_size (int) – font size for axis labels. Defaults to 16 pt.
plot_legend (bool) – option to include a legend on the plot. Defaults to True.
save_fig (bool) – option to save figure. Defaults to False.
write_path (str) – output path for figure if saved.

magpysv.plots.plot_residuals_dft_all(*, projected_residuals, dates, fig_size=(10, 8), font_size=12, label_size=16, save_fig=False, write_path=None)[source]¶

Compare the DFTs of the projected residuals with each other.

Calculates the DFT of the residuals in each eigendirection given and plots it alongside the residuals themselves. Produces a separate figure per eigendirection. Use plot_residuals_dft if a single figure with each eigendirection included as a subplot is desired. The length of the time series are padded with zeroes up to the next power of two.

Parameters:

dates (datetime.datetime) – dates of time series measurements.
projected_residuals (time series) – difference between modelled and SV rotated into the eigendirections obtained during denoising (principal component analysis). The proxy for unmodelled external signal is the residual projected in the noisiest eigendirection(s).
fig_size (array) – figure size in inches. Defaults to 8 inches by 6 inches.
font_size (int) – font size for axes. Defaults to 12 pt.
label_size (int) – font size for axis labels. Defaults to 16 pt.
plot_legend (bool) – option to include a legend on the plot. Defaults to True.
save_fig (bool) – option to save figure. Defaults to False.
write_path (str) – output path for figure if saved.

magpysv.plots.plot_sv(*, dates, sv, model, obs, model_name, fig_size=(8, 6), font_size=12, label_size=16, plot_legend=False, plot_average=False, window_length=12, min_samples=3, save_fig=False, write_path=None)[source]¶

Plot the SV and model prediction for a single observatory.

Produces a plot of the X, Y and Z components of the SV and field model prediction for a single observatory.

Parameters:

dates (datetime.datetime) – dates of time series measurements.
sv (time series) – X, Y and Z components of SV at a single location.
model (time series) – X, Y and Z components of the SV predicted by a field model for the same location as the data.
obs (str) – observatory name given as three digit IAGA code.
model_name (str) – field model name.
fig_size (array) – figure size in inches. Defaults to 8 inches by 6 inches.
font_size (int) – font size for axes. Defaults to 12 pt.
label_size (int) – font size for axis labels. Defaults to 16 pt.
plot_legend (bool) – option to include a legend on the plot. Defaults to False.
plot_average (bool) – option to include a running average of the SV time series on the plot. Defaults to False.
window_length (int) – number of months over which to take the running average if this is plotted. Defaults to 12 months.
min_samples (int) – minimum number of non-NaN values that must be present in the window in order for the running average to be calculated rather than set to NaN. Defaults to 3 (e.g. for monthly first differences this means that at least 3 months of data per window are required to calculate the 12-month running average.)
save_fig (bool) – option to save figure. Defaults to False.
write_path (str) – output path for figure if saved.

magpysv.plots.plot_sv_comparison(*, dates, noisy_sv, denoised_sv, model, obs, model_name, fig_size=(8, 6), font_size=12, label_size=16, plot_legend=False, plot_average=False, window_length=12, min_samples=3, save_fig=False, write_path=None, corrected_residuals, residuals, plot_rms=False)[source]¶

Plot noisy/denoised SV and model prediction for a single observatory.

Produces a plot of the X, Y and Z components of the noisy SV, the denoised SV and field model prediction for a single observatory.

Parameters:

dates (datetime.datetime) – dates of time series measurements.
noisy_sv (time series) – X, Y and Z components of uncorrected SV at a single location.
denoised_sv (time series) – X, Y and Z components of denoised SV at a single location.
residuals (time series) – difference between modelled and observed SV.
corrected_residuals (time series) – difference between modelled and denoised observed SV.
model (time series) – X, Y and Z components of the SV predicted by a field model for the same location as the data.
model_name (str) – field model name.
obs (str) – observatory name given as three digit IAGA code.
fig_size (array) – figure size in inches. Defaults to 8 inches by 6 inches.
font_size (int) – font size for axes. Defaults to 12 pt.
label_size (int) – font size for axis labels. Defaults to 16 pt.
plot_legend (bool) – option to include a legend on the plot. Defaults to False.
plot_average (bool) – option to include a running average of the SV time series on the plot. Defaults to False.
window_length (int) – number of months over which to take the running average if this is plotted. Defaults to 12 months.
min_samples (int) – minimum number of non-NaN values that must be present in the window in order for the running average to be calculated rather than set to NaN. Defaults to 3 (e.g. for monthly first differences this means that at least 3 months of data per window are required to calculate the 12-month running average.)
plot_rms (bool) – option to calculate the rms before and after denoising
display the values on the figure. Defaults to False. (and) –
save_fig (bool) – option to save figure. Defaults to False.
write_path (str) – output path for figure if saved.

Returns:

tuple containing:

rms_ratio_x (float):

ratio of rms values for X component residuals before and after denoising.
rms_ratio_y (float):

ratio of rms values for Y component residuals before and after denoising.
rms_ratio_z (float):

ratio of rms values for Z component residuals before and after denoising.

Return type:

(tuple)

magpysv.plots.rms_ratios(*, rms, fig_size=(8, 6), font_size=12, label_size=16, save_fig=False, write_path=None)[source]¶

Plot the rms of residuals after removing successive eigendirections.

Plots the ratio of the residuals rms values before and after denoising, for different numbers of eigendirections are removed from the data. Removing all eigendirections gives a ratio of zero as the denoised SV now equals the model prediction. Requires the dnoising to be run several times, each time using a different number of eigendirections for the external signal proxy (i.e. different values of the argument proxy_number in calls to eigenvalue_analysis.) Uses output from plot_sv_comparison when that function is run with the option plot_rms=True.

Parameters:

rms (dict) – rms ratios for each component after running eigenvalue_analysis with different values for the proxy_number argument.
fig_size (array) – figure size in inches. Defaults to 8 inches by 6 inches.
font_size (int) – font size for axes. Defaults to 12 pt.
label_size (int) – font size for axis labels. Defaults to 16 pt.
save_fig (bool) – option to save figure. Defaults to False.
write_path (str) – output path for figure if saved.