# Utility Functions¶

## Download functions¶

- SSVEPAnalysisToolbox.utils.download.download_single_file()¶
Download one file.

- Parameters
**source_url**– Source URL.**desertation**– Local path for storing the downloaded file. The path should be an absolute path with the file name.**known_hash**– Hash code of the downloaded file. Set`None`

if the hash code is unknown.

## IO functions¶

- SSVEPAnalysisToolbox.utils.io.savedata()¶
Save a dictionary data.

- Parameters
**file**– Path of saving file including the absolute path and file name.**data**– Dictionary data that will be saved.

- Save_type
There are two options of the saving data type:

`'mat'`

: Save data as a matlab`.mat`

file. The varaible names are the key values of the dictionary. The variable values are the values of the dictionary. If use this option, this function will work like “scipy.io.savemat”. If the data cannot be saved as`.mat`

file, the data will be saved as numpy`.npy`

binary file.`'np'`

: Save data as a numpy`.npy`

binary file. If use this option, this function will work like “numpy.save”. If the data cannot be saved as numpy`.npy`

binary file, the data will be saved as pickle`.pkl`

binary file.

- SSVEPAnalysisToolbox.utils.io.loaddata()¶
Load a local data file.

- Parameters
**file**– Local data path including the absolute path and file name.**save_type**–There are two options of the local data type:

`'mat'`

: Local data is a matlab`.mat`

file. The varaible names are the key values of the dictionary. The variable values are the values of the dictionary. If use this option, this function will work like “scipy.io.loadmat” or “mat73.loadmat”.`'np'`

: Local data is a numpy`.npy`

binary file. If use this option, this function will work like “numpy.load”. For pickle`.pkl`

binary file, you may directly use “pickle.load” to load the data.

- Returns
`data`

: Loaded dictionary data.

## Computation functions¶

- SSVEPAnalysisToolbox.utils.algsupport.gen_ref_sin()¶
Generate sine-cosine-based reference signal of one stimulus. This function is similar as “get_ref_sig” function in dataset class. But this function is more flexible, requires more input parameters, and is only for one stimulus.

- Parameters
**freq**– One stimulus frequency.**srate**– Sampling rate.**L**– Signal length (in samples).**N**– Total number of harmonic components.**phase**– One stimulus phase.

- Returns
`ref_sig`

: Reference signals of one stimulus. The dimention is (2N × L).

- SSVEPAnalysisToolbox.algorithms.utils.sum_list()¶
Iteratively sum all values in a list. If the input list contains lists, these contained lists will be summed first.

- Parameters
**X**– List that will be sumed.- Returns
`sum_X`

: Summation result.

- SSVEPAnalysisToolbox.algorithms.utils.mean_list()¶
Iteratively calculate average value of a list. If the input list contains lists, these contained lists will be averaged first.

- Parameters
**X**– List that will be averaged.- Returns
`mean_X`

: Average result.

- SSVEPAnalysisToolbox.algorithms.utils.sort()¶
Sort the given list

- Parameters
**X**– List that will be sorted.- Returns
`sorted_X`

: Sorted`X`

.`sort_idx`

: List of indices that can transfer`X`

to`sorted_X`

.`return_idx`

: List of indices that can transfer`sorted_X`

to`X`

.

- SSVEPAnalysisToolbox.algorithms.utils.gen_template()¶
Generate averaged templates. For each stimulus, EEG signals of all trials are averaged as the template signals.

- Parameters
**X**– List of EEG signals. Each element is one single trial EEG signal. The dimentions of EEG signals should be (filterbanks × channels × samples).**Y**– List of labels. Each element is one single trial label. The labels should be integer numbers.

- Returns
`template_sig`

: List of template signals. Each element is one class template signals. The dimentions of template signals are (filterbanks × channels × samples).

- SSVEPAnalysisToolbox.algorithms.utils.canoncorr()¶
Calculate canoncial correlation of two matrices following “canoncorr” in MATLAB.

- Parameters
**X**– First input matrix. The rows correspond to observations, and the columns correspond to variables.**Y**– Second input matrix. The rows correspond to observations, and the columns correspond to variables.**force_output_UV**– If`True`

, canonical coefficients will be calculated and provided. Otherwise, only the correlations are computed and provided.

- Returns
`A`

: Canonical coefficients of`X`

. If`force_output_UV == True`

, this value will be returned.`B`

: Canonical coefficients of`Y`

. If`force_output_UV == True`

, this value will be returned.`r`

: Canonical correlations.

- SSVEPAnalysisToolbox.algorithms.utils.qr_inverse()¶
Inverse QR decomposition.

- Parameters
**Q**– Orthogonal factor obtained from the QR decomposition.**R**– Upper-triangular factor obtained from the QR decomposition.**P**– Permutation information obtained from the QR decomposition.

- Returns
`X`

: Results of the inverse QR decomposition. \(\mathbf{X}=\mathbf{Q}\times\mathbf{R}\). The column order of`X`

has been adjusted according to`P`

.

Note

In “qr_inverse” function, the inputs `Q`

, `R`

and `P`

can be 2D or 3D. If the dimension is 2D, it is the conventional inverse QR decomposition. If the dimension is 3D, the conventional inverse QR decomposition will be applied along the first dimension.

- SSVEPAnalysisToolbox.algorithms.utils.qr_remove_mean()¶
QR decomposition. Before the QR decomposition, the column means are firstly removed from the input matrix.

- Parameters
**X**– Input matrix.- Returns
`Q`

: Orthogonal factor.`R`

: Upper-triangular factor.`P`

: Permutation information.

- SSVEPAnalysisToolbox.algorithms.utils.qr_list()¶
Apply “qr_remove_mean” function to each element in the given list.

- Parameters
**X**– List of input matrices for the QR decomposition.- Returns
`Q`

: List of orthogonal factors.`R`

: List of upper-triangular factors.`P`

: List of permutation information.

Note

In “qr_list” function, elements of the input list can be 2D or 3D. If 2D, “qr_remove_mean” function is directly applied to each element. If 3D, “qr_remove_mean” function is applied to each element along the first dimension.

- SSVEPAnalysisToolbox.algorithms.utils.mldivide()¶
Calculate A\B. The minimum norm least-squares solution of solving \(\mathbf{A}\times \mathbf{x} = \mathbf{B}\) for \(\mathbf{x}\).

- Parameters
**A**– First input matrix.**B**– Second input matrix.

- Returns
`x`

: Minimum norm least-squares solution. \(\mathbf{x} = \mathbf{A}^{-1}\times\mathbf{B}\). The inverse of the matrix`A`

is performed by the pseudo-inverse.