Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/tcp-lab/kym

Wavelet transform-based analyzer of biological signals
https://github.com/tcp-lab/kym

Last synced: 8 months ago
JSON representation

Wavelet transform-based analyzer of biological signals

Awesome Lists containing this project

README 

          
> **Important**: This repository is *silent*. No active development is currently being

carried out, but it is still maintained. Please open an issue to request help

or features.



# kym

###### Wavelet transform-based analyzer of biological signals



### Introduction



*kym* is a software tool for the quantitative analysis of non-stationary

oscillatory signals. It has been developed within the field of neurosciences to

study neuronal activity in terms of cytosolic calcium signals, but it can be

considered as a general-purpose set of MATLAB functions that implement a

wavelet-based time/frequency analysis.



*kym* has been developed starting from 2010 and released for the first time in

2011 as supplementary material for a scientific methodological paper ([1]). From

then on, *kym* has been modified several times to extend its analysis

capabilities, and different methods to handle the cone of influence as well as

many filters in the transformed domain are now available and already used in

many other works (see e.g., [2], [3], [4], [5], [6], [7]).



*kym* ver.0.6 is the last and most up-to-date release of the software. It

consists of a collection of 30 .m files, each of them containing a single MATLAB

function, but **only the "capital" ones (`VX`, `WT`, `WTX`, `IWT`, `KYM`,

`FILT*`, `FEAT`) need to be directly managed by the end user**, while the other

ones are to be considered as auxiliary functions, invoked on the fly by the

previous ones.



In order to use *kym* (`VX`, `WT` and `WTX` functions in particular), data need

to be stored in a .csv (comma separated values) file, organized as it follows:

**the first column must contain the vector of time samples, while the actual

signals should fill all the other columns**. In the case of calcium signal

analysis, columns are the time courses of the fluorescence intensity emitted by

the calcium indicator loaded inside the cells. Each column may represent a

different cell or a different region of interest (ROI) over the same cell. The

file `data.csv` provides an example of this and it can be used to test the

software. It contains the same set of traces showed in [3] to present the

analytical method: 56 time traces of calcium intracellular concentration

recorded from ROIs drawn over the same cell, with a sampling time of *dt = 2 s*.



`WTX` function is specifically tailored for the spatial wavelet analysis of

neural calcium signals as described in [3]. It can take two data arguments when

using a ratiometric fluorescent indicator for calcium (such as Fura-2). Further

details about this function are given in [3], in particular see "Surface to

Volume Ratio Assessment" subsection.



Many other parameters, beyond the raw data, can be passed as argument to the

main functions, in order to specify the unit of measurement of time, the

changing points of *in acuto* treatments, the threshold levels, and so on. For

further information about the meaning and the syntax of each *kym* function you

can use the `help` command followed by the name of the function, or you can

follow the examples below to get started. Nevertheless an exhaustive and

complete user guide for *kym* has never been written, so a future effort will be

to produce such a documentation.



From a technical point of view, wavelet transform computation has been

implemented as a product in the Fourier transformed domain. A standard code for

this algorithm can be found, for instance, in WaveLab850

(http://www-stat.stanford.edu/~wavelab/). Peak detection is based on image

dilation (see e.g., `localMaximum.m` m-file by Yonathan Nativ,

http://www.mathworks.com/matlabcentral/fileexchange/authors/). The rest of the

code has been written and developed *ad hoc* to perform the analyses presented

in [1] and [3].



**NOTE:** `imdilate` function is required by `peak`, `paths` (and hence by `KYM`

and `WTX`) *kym* functions. Octave users can find `imdilate.m` within the

`image` package, while MATLAB users need to have Image Processing Toolbox

installed.



### References



1. Ruffinatti F.A., Lovisolo D., Distasi C., Ariano P., Erriquez J., Ferraro M. Calcium signals: analysis in time and frequency domains. *J Neurosci Methods.* 2011 Aug; 199(2):310-320.



2. Zamburlin P., Ruffinatti F.A., Gilardino A., Farcito S., Parrini M., Lovisolo D. Calcium signals and FGF-2 induced neurite growth in cultured parasympathetic neurons: spatial localization and mechanisms of activation. *Pflugers Arch.* 2013 Sep; 465(9):1355-1370.



3. Ruffinatti F.A., Gilardino A., Lovisolo D., Ferraro M. Spatial wavelet analysis of calcium oscillations in developing neurons. *PLoS One.* 2013 Oct 14; 8(10):e75986.



4. Moccia F., Ruffinatti F.A., Zuccolo E. Intracellular Ca2+ Signals to Reconstruct a Broken Heart: Still a Theoretical Approach? *Curr Drug Targets.* 2015 Jul; 16(8):793-815.



5. Gilardino A., Catalano F., Ruffinatti F.A., Alberto G., Nilius B., Antoniotti S., Martra G., Lovisolo D. Interaction of SiO2 nanoparticles with neuronal cells: Ionic mechanisms involved in the perturbation of calcium homeostasis. *Int J Biochem Cell Biol.* 2015 Sep; 66:101-111.



6. Dragoni S., Reforgiato M., Zuccolo E., Poletto V., Lodola F., Ruffinatti F.A., Bonetti E., Guerra G., Barosi G., Rosti V., Moccia F. Dysregulation of VEGF-induced proangiogenic Ca2+ oscillations in primary myelofibrosis-derived endothelial colony-forming cells. *Exp Hematol.* 2015 Dec; 43(12):1019-1030.



7. Lodola F., Laforenza U., Cattaneo F., Ruffinatti F.A., Poletto V., Massa M., Tancredi R., Zuccolo E., Kheder D., Riccardi A., Biggiogera M., Rosti V., Guerra G., Moccia F. VEGF-induced intracellular Ca2+ oscillations are down-regulated and do not stimulate angiogenesis in breast cancer-derived endothelial colony forming cells. *Oncotarget. 2017.* IN PRESS



### Syntax to get started



#### Trace Visualization



General Syntax:



`VX(filename,sub,unit,mark,roi,output)`



> Example with comments on function arguments:

>

> `VX('data.csv','C','s',[110],[]);`

>

> `VX` allows a preliminary inspection of time courses of the raw data

  contained in `data.csv` and returns a graph of sampling quality control.

>

> * `'C'` stands for *Color map mode*: it displays the two-variable function

    \[Ca2+\]\(*t*, *x*\) as a color map (*t* = time, *x* = space).

    Different visualization modes are available:

>  * *`n`* (being an integer greater or equal to one) shows the selected traces

     arranging them in subplot groups of *n* traces per window.

>  * `'S'` stands for "Superimposition" and shows all the traces selected

     superimposed according to a color gradient from blue (first ROIs) to red

     (last ROIs).

>  * `'C'` is the already mentioned Color map mode.

>  * `'M'` shows a single trace representing the point-by-point mean and

     standard error of the mean (SEM) computed from all the selected trace.

>

> * Second (`'s'`) is the unit of measurement of the first column entries.

>

> * A time marker is placed at step number 110, that corresponds in this case to

    *t* = 220s being *dt* = 2s the sampling time.

>

> * The last void argument (`[]`) means that all traces included in the file are

    selected and then displayed. As an alternative, you can pass an array of

    ROIs according to MATLAB syntax. E.g. `[3 5 9:12 15:17]` means ROIs 3, 5, 9,

    10, 11, 12, 15, 16, 17.

 

#### Wavelet Transform



General syntax:



`[wt,par,sig] = WT(filename,unit,mark,roi,lft,nvoice,wavelet,cone,output)`



> Example with comments on function arguments:

>

> `[wt,par,sig]=WT('data.csv','s',[110],[2:7],3,48,'M1','PAD');`

>

> Computes the wavelet transform starting from the raw data arranged in the file

  `data.csv`.

>

> * Second (`'s'`) is the unit of measurement of the first column entries.

>

> * A time marker is placed at step number 110, that corresponds in this case to

    *t* = 220s being *dt* = 2s the sampling time.

>

> * The wavelet transform and related scaleogram are computed just for ROIs from

    2 to 7.

>

> * The first 3 lowest frequencies are discarded (low frequency threshold,

    recommended).

>

> * Scaleograms are drawn using 48 inter-octave voices.

>

> * `'M1'` (Morlet version 1) mother wavelet is used to compute wavelet

    transform.

>

> * `'PAD'` technique is use to handle the cone of influence. Three different

    ways to handle the cone of influence (COI) issue have been implemented:

>  * `'NONE'`: this option does nothing on COI artifacts, but it is useful to

     preserve the whole information carried by the original signal within the

     scaleogram.

>  * `'COI'`: this option computes the e-folding cone of influence and masks it

     in order to completely discard those regions out of the scaleogram.

>  * `'PAD'`: this is a less drastic algorithm that provides a linear detrending

     ensuring a matching between the starting and the ending point of the signal

     and, at the same time, pads the original signal with a number of zeros

     equal to the signal length, finally removing them after wavelet

     transformation: this is the procedure we recommend because it allows to

     avoids artificial edge discontinuities and low-frequencies cross talk

     between the two edges of the scaleogram, with a very poor loss of

     information.

>

> * Output variables (`wt`, `par`, `sig`) contain scaleograms, generic

    descriptive parameters and the original signal respectively, concerning last

    ROI analyzed (ROI 7 in this case). They serves as input argument of `PD`

    function.



#### Wavelet Analysis and Peak Detection



General Syntax:



`ratio = KYM(wt,par,sig,thr,output)`



> Example with comments on function arguments:

>

> `KYM(wt,par,sig,50);`

>

> * The first three variables (`wt`, `par`, and `sig`) are the outputs of `WT`

    functions concerning the last ROI analyzed by `WT` (ROI 7 in this case).

>

> * Peak detection and frequency path detection are performed after a 35%

    thresholding of the scaleogram.

>

> * The output consists in several plots deriving the power and the energy

    density of the signal starting from the related wavelet scaleograms: further

    details about them can be found in [1]. Notice that the time-averaged

    activity values and related *r* values are calculate respect to the time

    markers set in `WT`.