Code Documentation

exception src.signalsnap.analysis.MissingValueError

Base class for missing value exceptions

class src.signalsnap.analysis.Spectrum(path=None, group_key=None, dataset=None, delta_t=None, data=None, corr_data=None, corr_path=None, corr_group_key=None, corr_dataset=None, f_unit='Hz')

Spectrum class stores signal data, calculated spectra and error of spectral values. Allows for the calculation of the polyspectra of the signal and their visualization. Also hold methods for saving spectrum objects.

pathstr

Path to h5 file with stored signal

group_keystr

Group key for h5 file

datasetstr

Name of the dataset in h5 file

dataarray

Signal to be analyzed as Numpy array

corr_dataarray

Second signal used as correlation data as Numpy array

corr_pathstr

Path to h5 file with stored second signal for correlation

corr_group_keystr

Group key for h5 file with correlation signal

corr_datasetstr

Name of the dataset in h5 file with correlation signal

corr_data_path: str

Path to h5 file with a second stored signal to be correlated with the first on (see path)

T_windowfloat

Length of window in seconds (or unit of choice) used for the calculation of any spectra

pathstr

Path to h5 file with stored signal

freqarray

Stores frequencies at with the spectra are calculated

f_maxfloat

Used to limit the upper frequency to calculate spectral values at (especially important for high sampling rates)

fsfloat

Stores the sampling rate of the signal

f_lists: dict

Used for the calculation of Poisson spectra. Stores all frequency values for the calculation of the non-uniform discreet Fourier transformation. (Also used for plotting with broken frequency axis.)

Sdict

Stores spectra values (final storage at the end of the calculation)

S_gpudict

Temporarily stores spectra values during calculation on the GPU

S_errdict

Stores errors of spectra values (final storage at the end of the calculation)

S_err_gpudict

Temporarily stores errors of spectra values during calculation on the GPU

S_errsdict

Temporarily stores m_var spectra used for the calculation of the errors

S_stationarity_tempdict

Stores m_stationarity spectra which are then averaged and used for the stationarity plot

S_stationaritydict

Stores the m_stationarity averaged spectra used for the stationarity plot

group_keystr

Group key of the dataset within the h5 file

datasetstr

Name of the dataset in the h5 file

window_pointsint

Number of points in a window

mint

Number of windows for the estimation of the cumulant

m_varint

m_var single spectra are used at a time for the calculation of the spectral errors

m_stationarityint

Number of spectra which are then averaged and used for the stationarity plot

first_frame_plottedbool

If true the first frame is plotted during the calculation of the spectra

delta_tfloat

Inverse of the sampling rate of the signal

dataarray / pointer

Stores the full dataset or is a pointer to the data in the h5 file (recommended of the dataset is larger than your RAM)

corr_dataarray / pointer

Stores the full second dataset or is a pointer to the data in the h5 file (recommended of the dataset is larger than your RAM)

corr_group_keystr

Group key of the second dataset within the h5 file

corr_datasetstr

Name of the second dataset in the h5 file

main_dataarray / pointer

(outdated / for old methods) Stores the full dataset or is a pointer to the data in the h5 file (recommended of the dataset is larger than your RAM)

err_counterdict

Counts the number single spectra already stored for the calculation of errors

stationarity_counterdict

Counts the number single spectra already stored for the averaging for the stationarity plot

calc_overlap(t_unit=None, imag=False, scale_t=1)

The overlap between all m_stationarity spectra and the overall mean spectrum is calculated and plotted against time. Can be used to see slow drifts and singular events that differ from the mean spectrum

t_unitstr

Unit of time

imagbool

If set, the imaginary part of all spectra are used for the calculation and plotting

scale_tfloat

Option to scale the time axis

calc_spec(order_in, T_window, f_max, backend='cpu', scaling_factor=1, corr_shift=0, filter_func=False, verbose=True, coherent=False, corr_default=None, break_after=1000000.0, m=10, m_var=10, m_stationarity=None, window_shift=1, random_phase=False, rect_win=False, full_import=True, show_first_frame=True)

Calculation of spectra of orders 2 to 4 with the arrayfire library.

order_in: array of int, str (‘all’)

orders of the spectra to be calculated, e.g., [2,4]

T_window: int

Spectra for m windows with temporal length T_window are calculated.

f_max: float

maximum frequency of the spectra to be calculated

backend: {‘cpu’, ‘opencl’, ‘cuda’}

backend for arrayfire

scaling_factorfloat

Can be used to scale all data points.

corr_shiftint

Can be used to shift the correlation data by a certain number of points relative to the main data.

filter_funcfunction

A function can be passed which will be applied to the data points in each window.

verbosebool

Can be unset to supress printing of various information.

coherentbool

(Experimental) Set if moment-based instead of cumulant-based S2 should be calculated. Maybe usefull in the case of non-independent windows.

corr_default{‘white noise’, None}

(TODO) Use white noise as correlation data. Then all higher-order correlations should vanish if the main dataset is stationary and windows are independent.

break_afterint

Number of frames can set to premature termination of spectrum calculation to use only part of the dataset to calculate a quick preview.

m: int

Spectra for m windows with temporal length T_window are calculated.

m_var: int

number of spectra to calculate the variance from (should be set as high as possible)

m_stationarity: int

number of spectra after which their mean is stored to varify stationarity of the data

window_shiftint

Sets the time interval between selective windows in units of window length. 1 (default) means window are seamlessly attached. Smaller than 1 mean windows overlap. Can be used to waste less information due to small wight given to values close to the borders of the window due to the window function.

random_phasebool

(Experimental) Set if phase of the Fourier coefficients of each window should be randomized. Maybe usefull for non-independent windows.

rect_win: bool

if true no window function will be applied to the window

full_import: bool

whether to load all data into RAM (should be set true if possible)

calc_spec_mini_bins(order_in, T_window, T_bin, f_max, backend='opencl', coherent=False, m=10, m_var=10, m_stationarity=None, rect_win=False, verbose=False)

order_in: array of int, str (‘all’)

orders of the spectra to be calculated, e.g., [2,4]

T_window: int

spectra for m windows of window_points is calculated

T_bin: int

number of points in bin

f_max: float

maximum frequency of the spectra to be calculated

backend: str

backend for arrayfire

coherent: bool

set if second moment should be used instead of cumulant

m: int

spectra for m windows of window_points is calculated

m_var: int

number of spectra to calculate the variance from (should be set as high as possible)

m_stationarity: int

number of spectra after which their mean is stored to varify stationarity of the data

rect_win: bool

set if no window function should be applied

verbose: bool

set for more prints

calc_spec_poisson(order_in, T_window, f_max, f_lists=None, backend='opencl', m=10, m_var=10, m_stationarity=None, full_import=False, scale_t=1, sigma_t=0.14, rect_win=False)

order_in: array of int, str (‘all’)

orders of the spectra to be calculated, e.g., [2,4]

T_window: int

spectra for m windows of window_points is calculated

f_max: float

maximum frequency of the spectra to be calculated

f_lists: list of arrays

frequencies at which the spectra will be calculated (can be multiple arrays with different frequency steps)

backend: str

backend for arrayfire

m: int

spectra for m windows of window_points is calculated

m_var: int

number of spectra to calculate the variance from (should be set as high as possible)

m_stationarity: int

number of spectra after which their mean is stored to varify stationarity of the data

full_import: bool

whether to load all data into RAM (should be set true if possible)

scale_t: float

scaling factor to scale timestamps and dt (not yet implemented, due to type error)

sigma_t: float

width of approximate confined gaussian windows

rect_win: bool

if true no window function will be applied to the window

plot(order_in=2, 3, 4, f_max=None, f_min=None, f_unit=None, sigma=1, green_alpha=0.3, arcsinh_plot=False, arcsinh_const=0.02, contours=False, s3_filter=0, s4_filter=0, s2_data=None, s2_err=None, s3_data=None, s3_err=None, s4_data=None, s4_err=None, s2_f=None, s3_f=None, s4_f=None, imag_plot=False, plot_error=True, broken_lims=None)

Plots the spectral data of any combination of spectral orders together with errors. Has many options to customize the appearance and choose the plotted frequencies.

order_inlist {2,3,4}

Spectral orders to be plotted. Multiple orders can be chosen.

f_maxfloat

Sets the upper limit of the frequency axis. If set higher than the Nyquist frequency, the Nyquist frequency will be chosen as limit.

f_minfloat

Sets the lower limit of the frequency axis.

f_unitstr or None

Frequency unit can be passed labeling the plot. If None, the unit which was set when creating the Spectrum object is used.

sigmafloat

Sets the number of standard deviations as error to be shown in the two-dimensional plots of order 3 and 4. The spectral values are colored green if the number of standard deviations is higher than the specific spectral value.

green_alphafloat

Sets the alpha value for the green error tiling. (Value between 0 and 1)

arcsinh_plotbool

if set the spectral values are scale with an arcsinh function (similar to log but also works for negative values). The amount of scaling is given by the arcsinh_const.

arcsinh_constfloat

constant to set amount of arcsinh scaling. The lower, the stronger.

contoursbool

If set contours are shown in the 2D plots.

s3_filterfloat

Applies a Gaussian filter the width s3_filter to the third-order data

s4_filterfloat

Applies a Gaussian filter the width s4_filter to the fourth-order data

s2_dataarray

Spectral data for the power spectrum can be provided and is than used instead of the calculated values stored in the object.

s2_errarray

Spectral errors for the power spectrum can be provided and is than used instead of the calculated values stored in the object.

s3_dataarray

Spectral data for the third-order spectrum can be provided and is than used instead of the calculated values stored in the object.

s3_errarray

Spectral errors for the third-order spectrum can be provided and is than used instead of the calculated values stored in the object.

s4_dataarray

Spectral data for the fourth-order spectrum can be provided and is than used instead of the calculated values stored in the object.

s4_errarray

Spectral errors for the fourth-order spectrum can be provided and is than used instead of the calculated values stored in the object.

s2_farray

Frequency values for the power spectrum can be provided and is than used instead of the values stored in the object.

s3_farray

Frequency values for the third-order spectrum can be provided and is than used instead of the values stored in the object.

s4_farray

Frequency values for the fourth-order spectrum can be provided and is than used instead of the values stored in the object.

imag_plotbool

If set imaginary part of the spectral values are plotted.

plot_errorbool

If set 1 to 5 sigma error bands are shown in the power spectrum.

broken_limslist of lists

The low and upper limit of each section of a broken frequency axis can be provided, given that the frequency arrays (s2_f, s3_f, s4_f) contain disconnected sections.

Return the matplotlib figure.

save_spec(path)

Method for storing the Spectrum object. Pointers and the full dataset are remove from the object before saving.

pathstr

Location of stored file

stationarity_plot(f_unit=None, t_unit=None, contours=False, s2_filter=0, arcsinh_plot=False, arcsinh_const=0.0001, f_max=None, normalize=False)

Plots the S_stationarity spectra versus time to make changes over time visible

f_unitstr

frequency unit

t_unitstr

time unit

contoursbool

if set contours are drawn

s2_filterfloat

value for sigma of a Gaussian filter in direction of time (usefull in the case of noisy data)

arcsinh_plotbool

if set the spectral values are scale with an arcsinh function (similar to log but also works for negative values). The amount of scaling is given by the arcsinh_const.

arcsinh_constfloat

constant to set amount of arcsinh scaling. The lower, the stronger.

f_maxfloat

maximum frequency to plot on the fequency axis

normalize[‘area’, ‘zero’]

for better visualization all spectra can be normalized to set the area under the S2 to 1 or the value at S2(0) to 1.

src.signalsnap.analysis.add_random_phase(a_w, window_size, delta_t, m)

(Experimental function) Adds a random phase proportional to the frequency to deal with ultra coherent signals

mint

number of windows per frame

delta_tfloat

inverse of the sampling rate of the signal

window_sizeint

size of the window in points

a_warray

Fourier coefficients pf the window

src.signalsnap.analysis.apply_window(window_width, t_clicks, fs, sigma_t=0.14)

This function take the timestamps of the detector and applies the window function as an envelope treating the clicks as steps with height one.

window_widthfloat

timely width of the window in unit of choice

t_clicksarray

timestamps of the dataset that lie within the current window

fsfloat

sampling rate of the signal

sigma_tfloat

parameter of the approx. confined gaussian window (here chosen to be 0.14)

src.signalsnap.analysis.arcsinh_scaling(s_data, arcsinh_const, order, s_err=None, s_err_p=None, s_err_m=None)

Helper function to improve visibility in plotting (similar to a log scale but also works for negative values)

s_dataarray

spectral values of any order

arcsinh_constfloat

these parameters sets the rescaling amount (the smaller, the stronger the rescaling)

orderint

important since the error arrays are called differently in the second-order case

s_errarray

spectral errors of order 3 or 4

s_err_parray

spectral values + error of order 2

s_err_marray

spectral values - error of order 2

src.signalsnap.analysis.c2(a_w, a_w_corr, m, coherent)

calculation of c2 for power spectrum

src.signalsnap.analysis.c3(a_w1, a_w2, a_w3, m)

Calculation of c3 for bispectrum (see arXiv:1904.12154) # C_3 = m^2 / (m - 1)(m - 2) * (< a_w1 * a_w2 * a_w3 > # sum_123 # - < a_w1 >< a_w2 * a_w3 > - < a_w1 * a_w2 >< a_w3 > - < a_w1 * a_w3 >< a_w2 > # sum_1 sum_23 sum_12 sum_3 sum_13 sum_2 # + 2 < a_w1 >< a_w2 >< a_w3 >) # sum_1 sum_2 sum_3 # with w3 = - w1 - w2

a_w1array

Fourier coefficients of signal as vertical array

a_w2array

Fourier coefficients of signal as horizontal array

a_w3array

a_w1+w2 as matrix

mint

Number of windows used for the calculation of one spectrum

Returns the c3 estimator as matrix

src.signalsnap.analysis.c4(a_w, a_w_corr, m)

calculation of c4 for trispectrum # C_4 = (Eq. 60, in arXiv:1904.12154)

a_warray

Fourier coefficients of the signal

a_w_corrarray

Fourier coefficients of the signal or a second signal

mint

Number of windows used for the calculation of one spectrum

Returns the c4 estimator as matrix

src.signalsnap.analysis.calc_a_w3(a_w_all, f_max_ind, m)

Preparation of a_(w1+w2) for the calculation of the bispectrum

a_w_allarray

Fourier coefficients of the signal

f_max_indint

Index of the maximum frequency to be used for the calculation of the spectra

mint

Number of windows per spectrum

a_w3array

Matrix of Fourier coefficients

src.signalsnap.analysis.calc_window(x, N_window, L, sigma_t)

Helper function to calculate the approx. confined gaussian window as defined in https://doi.org/10.1016/j.sigpro.2014.03.033

xarray

points at which to calculate the function

N_windowint

length of window in points

Lint

N_window + 1

sigma_tfloat

parameter of the approx. confined gaussian window (here chosen to be 0.14)

src.signalsnap.analysis.cgw(N_window, fs=None, ones=False)

Helper function to calculate the approx. confined gaussian window as defined in https://doi.org/10.1016/j.sigpro.2014.03.033

onesbool

if true, the window is simply set to one resulting in a rectangular window

fsfloat

sampling rate of the signal

N_windowint

length of window in points

src.signalsnap.analysis.connect_broken_axis(s_f, broken_lims)

Helper function to enable broken axis during plotting

s_farray

frequencies at with the spectra had been calculated

broken_limslist

list of arrays containing the endpoints of the disconnected frequency regions

src.signalsnap.analysis.find_end_index(data, start_index, T_window, m, frame_number, j)

dataarray

timestamps of detector clicks

start_indexint

index of the last timestamp in the whole dataset that fitted into the prior window (zero in case of first window)

T_windowfloat

window length in seconds (or unit of choice)

mint

number of windows to calculate the cumulant estimator from

frame_numberint

keeps track of the current frame (1 frame = m windows)

jint

number of the current window in the frame

src.signalsnap.analysis.g(x_, N_window, L, sigma_t)

Helper function to calculate the approx. confined gaussian window as defined in https://doi.org/10.1016/j.sigpro.2014.03.033

x_array

points at which to calculate the function

N_windowint

length of window in points

Lint

N_window + 1

sigma_tfloat

parameter of the approx. confined gaussian window (here chosen to be 0.14)

src.signalsnap.analysis.import_data(path, group_key, dataset, full_import=False)

Helper function to load data from h5 file into numpy array. Import of .h5 data with format group_key -> data + attrs[dt]

full_import: bool

If true all data is loaded in RAM (recommended if possible)

pathstr

Path for the data to be saved at

group_keystr

Name of the group in the h5 file

datasetstr

Name of the dataset in the h5 file

Returns simulation result and inverse sampling rate

src.signalsnap.analysis.load_spec(path)

Helper function to load pickled objects.

pathstr

Path to pkl file.

Returns the object.

src.signalsnap.analysis.pickle_save(path, obj)

Helper function to pickle system objects

pathstr

Location of saved data

obj : System obj

src.signalsnap.analysis.plot_first_frame(chunk, delta_t, window_size, t_unit=None)

Helper function for plotting one window during the calculation of the spectra for checking data and correct window length

chunkarray

one frame of the dataset

delta_tfloat

inverse sampling rate of the signal

window_sizeint

size of window in points

src.signalsnap.analysis.to_hdf(dt, data, path, group_name, dataset_name)

Helper function to generated h5 file from numpy array.

dtfloat

Inverse sampling rate of the signal (is saved as attribute “dt” to the dataset)

dataarray

E.g. simulation results

pathstr

Path for the data to be saved at

group_namestr

Name of the group in the h5 file

dataset_namestr

Name of the dataset in the h5 file

src.signalsnap.analysis.unit_conversion(f_unit)

Helper function to automatically convert units.

f_unitstr

Frequency unit

Returns the corresponding time unit.