Programming Interface
Contents
Example
Computing the spectrogram values
from MagPy4 import alg
# Computes the dynamic spectrogram with a frequency bandwidth of 5
spec = alg.spectrogram(times, bx, bw=5)
# Computes the ellipticity spectrogram with an interval of 256, a shift
# of 64, and it detrends the data sections before passing it to the FFT algorithms
ellip = alg.ellipticity_spec(times, bx, by, bz, fftint=256, fftshift=64, detrend=True)
# Directly access the computed values
xspec, yspec, zspec = spec.values()
xellip, yellip, zellip = spec.values()
Plotting the spectrogram values
# Create a matplotlib figure with a logarithmic y-scale
fig = alg.plot_spec_data(spec, logy=True)
# To display the figure, use fig.show() or matplotlib.pyplot.show()
fig.show()
# To save the figure, use fig.savefig()
fig.savefig('spectrogram.png')
1D Spectral Analysis
calc_spectra(sig, bw, res)
Calculate the power spectral density of a signal
Parameters
----------
sig : array-like
Data to compute power spectra for
bw : int
Number of frequency bands to average over
res : float
Data resolution in seconds
Returns
-------
Array containing power spectra results
calc_coh_pha(sig, bw, res)
Calculate the coherence and phase between two signals
Parameters
----------
sig : array-like
Data to compute power spectra for where each array
is a separate signal
bw : int
Number of frequency bands to average over
res : float
Data resolution in seconds
Returns
--------
A tuple containing the coherence and phase calculations, (coh, phase)
calc_freq(bw, n, res)
Calculates the frequencies needed to plot the power spectra calculations
Parameters
----------
bw : int
Number of frequency bands to average over
n : int
Number of points in data
res : float
Data resolution in seconds
Dynamic Spectral Analysis
spectrogram(times, sig, fftint=None, fftshift=None, bw=3, detrend=False, flag=nan, res=None)
Calculates the dynamic spectrogram for a signal
Parameters
----------
times : array-like
Time array for data in datetime objects
sig : array-like
Signal to compute power spectra values for
fftint : int, optional
FFT interval, number of points to use per FFT
Default is None, which will compute an appropriate value
fftint : int, optional
FFT shift, number of points to shift each section by
Default is None, which will compute an appropriate value
bw : int, optional
Number of frequency bands to average over (must be odd!)
Default value is 3
detrend : boolean, optional
Specifies whether to detrend each data slice before computing the
fast fourier transform;
Default value is False
flag : float or np.nan, optional
Specifies the error flag value to use
Default value is np.nan
res : float, optional
Specifies the resolution of the data in seconds
Default value is None, which will compute an estimated value
Returns
---------
SpecData instance
Contains the calculated spectrogram x, y, and z values and
any other necessary parameters for plotting
coherence_spec(times, sig1, sig2, fftint=None, fftshift=None, bw=3, detrend=False, flag=nan, res=None)
Calculates the dynamic coherence spectrogram for a pair of signals
Parameters
----------
times : array-like
Time array for data in datetime objects
sig1,2 : array-like
Signals to compute coherence values for
fftint : int, optional
FFT interval, number of points to use per FFT
Default is None, which will compute an appropriate value
fftint : int, optional
FFT shift, number of points to shift each section by
Default is None, which will compute an appropriate value
bw : int, optional
Number of frequency bands to average over (must be odd!)
Default value is 3
detrend : boolean, optional
Specifies whether to detrend each data slice before computing the
fast fourier transform;
Default value is False
flag : float or np.nan, optional
Specifies the error flag value to use
Default value is np.nan
res : float, optional
Specifies the resolution of the data in seconds
Default value is None, which will compute an estimated value
Returns
---------
SpecData instance
Contains the calculated spectrogram x, y, and z values and
any other necessary parameters for plotting
phase_spec(times, sig1, sig2, fftint=None, fftshift=None, bw=3, detrend=False, flag=nan, res=None)
Calculates the dynamic phase spectrogram for a pair of signals
Parameters
----------
times : array-like
Time array for data in datetime objects
sig1,2 : array-like
Signals to compute phase values for
fftint : int, optional
FFT interval, number of points to use per FFT
Default is None, which will compute an appropriate value
fftint : int, optional
FFT shift, number of points to shift each section by
Default is None, which will compute an appropriate value
bw : int, optional
Number of frequency bands to average over (must be odd!)
Default value is 3
detrend : boolean, optional
Specifies whether to detrend each data slice before computing the
fast fourier transform;
Default value is False
flag : float or np.nan, optional
Specifies the error flag value to use
Default value is np.nan
res : float, optional
Specifies the resolution of the data in seconds
Default value is None, which will compute an estimated value
Returns
---------
SpecData instance
Contains the calculated spectrogram x, y, and z values and
any other necessary parameters for plotting
ellipticity_spec(times, sig1, sig2, sig3, fftint=None, fftshift=None, bw=3, detrend=False, flag=nan, res=None)
Calculates the dynamic ellipticity spectrogram for a set of signals
Parameters
----------
times : array-like
Time array for data in datetime objects
sig1,2,3 : array-like
Signals to compute ellipticity values for (bx, by, bz)
fftint : int, optional
FFT interval, number of points to use per FFT
Default is None, which will compute an appropriate value
fftint : int, optional
FFT shift, number of points to shift each section by
Default is None, which will compute an appropriate value
bw : int, optional
Number of frequency bands to average over (must be odd!)
Default value is 3
detrend : boolean, optional
Specifies whether to detrend each data slice before computing the
fast fourier transform;
Default value is False
flag : float or np.nan, optional
Specifies the error flag value to use
Default value is np.nan
res : float, optional
Specifies the resolution of the data in seconds
Default value is None, which will compute an estimated value
Returns
---------
SpecData instance
Contains the calculated spectrogram x, y, and z values and
any other necessary parameters for plotting
prop_angle_spec(times, sig1, sig2, sig3, fftint=None, fftshift=None, bw=3, detrend=False, flag=nan, res=None)
Calculates the dynamic propagation angle spectrogram for a set of signals
Parameters
----------
times : array-like
Time array for data in datetime objects
sig1,2,3 : array-like
Signals to compute propagation angle for (bx, by, bz)
fftint : int, optional
FFT interval, number of points to use per FFT
Default is None, which will compute an appropriate value
fftint : int, optional
FFT shift, number of points to shift each section by
Default is None, which will compute an appropriate value
bw : int, optional
Number of frequency bands to average over (must be odd!)
Default value is 3
detrend : boolean, optional
Specifies whether to detrend each data slice before computing the
fast fourier transform;
Default value is False
flag : float or np.nan, optional
Specifies the error flag value to use
Default value is np.nan
res : float, optional
Specifies the resolution of the data in seconds
Default value is None, which will compute an estimated value
Returns
---------
SpecData instance
Contains the calculated spectrogram x, y, and z values and
any other necessary parameters for plotting
power_trace_spec(times, sig1, sig2, sig3, fftint=None, fftshift=None, bw=3, detrend=False, flag=nan, res=None)
Calculates the dynamic power spectra trace (Px + Py + Pz) for
a set of signals
Parameters
----------
times : array-like
Time array for data in datetime objects
sig1,2,3 : array-like
Signal to compute power spectra trace values for (bx, by, bz)
fftint : int, optional
FFT interval, number of points to use per FFT
Default is None, which will compute an appropriate value
fftint : int, optional
FFT shift, number of points to shift each section by
Default is None, which will compute an appropriate value
bw : int, optional
Number of frequency bands to average over (must be odd!)
Default value is 3
detrend : boolean, optional
Specifies whether to detrend each data slice before computing the
fast fourier transform;
Default value is False
flag : float or np.nan, optional
Specifies the error flag value to use
Default value is np.nan
res : float, optional
Specifies the resolution of the data in seconds
Default value is None, which will compute an estimated value
Returns
---------
SpecData instance
Contains the calculated spectrogram x, y, and z values and
any other necessary parameters for plotting
compr_power_spec(times, sig1, sig2, sig3, fftint=None, fftshift=None, bw=3, detrend=False, flag=nan, res=None)
Calculates the dynamic compressional power (Pt) spectrogram for a
set of signals
Parameters
----------
times : array-like
Time array for data in datetime objects
sig1,2,3 : array-like
Signals to compute compressional power for (bx, by, bz)
fftint : int, optional
FFT interval, number of points to use per FFT
Default is None, which will compute an appropriate value
fftint : int, optional
FFT shift, number of points to shift each section by
Default is None, which will compute an appropriate value
bw : int, optional
Number of frequency bands to average over (must be odd!)
Default value is 3
detrend : boolean, optional
Specifies whether to detrend each data slice before computing the
fast fourier transform;
Default value is False
flag : float or np.nan, optional
Specifies the error flag value to use
Default value is np.nan
res : float, optional
Specifies the resolution of the data in seconds
Default value is None, which will compute an estimated value
Returns
---------
SpecData instance
Contains the calculated spectrogram x, y, and z values and
any other necessary parameters for plotting
tranv_power_spec(times, sig1, sig2, sig3, fftint=None, fftshift=None, bw=3, detrend=False, flag=nan, res=None)
Calculates the dynamic tranverse power (Px + Py + Pz - Pt) spectrogram
for a set of signals
Parameters
----------
times : array-like
Time array for data in datetime objects
sig1,2,3 : array-like
Signals to compute tranverse power values for (bx, by, bz)
fftint : int, optional
FFT interval, number of points to use per FFT
Default is None, which will compute an appropriate value
fftint : int, optional
FFT shift, number of points to shift each section by
Default is None, which will compute an appropriate value
bw : int, optional
Number of frequency bands to average over (must be odd!)
Default value is 3
detrend : boolean, optional
Specifies whether to detrend each data slice before computing the
fast fourier transform;
Default value is False
flag : float or np.nan, optional
Specifies the error flag value to use
Default value is np.nan
res : float, optional
Specifies the resolution of the data in seconds
Default value is None, which will compute an estimated value
Returns
---------
SpecData instance
Contains the calculated spectrogram x, y, and z values and
any other necessary parameters for plotting
Plotting
plot_spec_data(spec, figsize=(9, 6), logcolor=True, logy=None, title=None, cmap=None, rng=None)
Plots a SpecData object and onto a matplotlib Figure
Parameters
----------
spec : SpecData object
Data to plot
figsize : tuple of floats, optional
Indicates the fig size (width, height) in inches
Default is (9, 6)
logcolor : boolean or None, optional
Specifies whether grid values should be mapped to log10
values before mapping to color values;
Default value is None, which will use the spec's value
logy : boolean, optional
Indicates whether the y-axis should be on a log-scale or not;
Default value is None, which will use the spec's value
title : str, optional
Title to use for figure
Default is None
cmap : ColorMap, optional
matplotlib colormap to use for colorbar and grid mapping
Default value is None
rng : Tuple of floats, optional
Specifies a range of values to limit color range to;
Default is None, which will use the full range of values in
the data
Returns
---------
Figure object