# agmonsynchrony
Compute the jitter-based synchrony index between time series described in Agmon's paper [1].
### Syntax
```python
SI, pval, Nc = synchrony_index(timeseries, tau, Nc_max_exact=1000)
```
### Arguments
- **timeseries** (list or tuple of arrays): a list of two or more time series. Each time series is a sorted array of time instants.
- **tau** (float or array): maximum delay between events of different time series for the identification of coincidences. The width of the jitter window used for computing the expected number of coincidences is set to 2*tau. If tau is an array, all values are used consecutively
- **window** (str): if window is 'bilateral' (default), the original Agmon's method is applied; if window is 'unilateral', only coindidences occurring after (when tau > 0) or before (when tau < 0) the events of the reference time series are considered.
- **Nc_max_exact** (int): number of coincidences above which a normal approximation (Z score) is used for computing the p-values (default: 1000, which is generally appropriate)
### Outputs
- **SI** (array with 2 or 3 dimensions): matrix of synchrony indices. Values normally range between 0 (no synchrony), and 1 (perfect synchrony) but can also be negative (antisynchrony) down to -1. The synchrony index SI[i, j] is computed between time series i (the reference) and j (the target). If 'tau' is an array, SI[i, j, k] is the synchrony index for the k-th value of 'tau'.
- **pval** (array with the same shape as 'SI'): matrix of corresponding p-values for the significance of the synchrony
- **Nc** (int array with the same shape as 'SI'): matrix of the number of observed coincidences
### Example
Let's consider two time series with 4 and 2 samples respectively. We are looking for coincidences within a maximum delay of 0.1:
```python
from agmonsynchrony import synchrony_index
ts1 = [1, 2, 3, 4]
ts2 = [2.03, 3.95]
SI, pval, Nc = synchrony_index([ts1, ts2], tau=0.1)
```
The number of observed coincidences is:
```python
>> print(Nc)
[[4 2]
[2 2]]
```
The matrix of synchrony indices is:
```python
>> print(SI)
[[1. 1.]
[0.5 1.]]
```
The diagonal is 1 because time series are synchronized with themselves. The lower left value is 0.5 because when the time series 'ts2' is taken as a reference, only half of the samples of the time series 'ts1' are within 'tau' of a sample of 'ts2'. Therefore, the matrix is not symmetric.
### Installation
The package can be installed using the command ``pip install agmonsynchrony`` (on Windows, a compiler such as Microsoft Visual C++ is required).
If the code is downloaded from github, local installation on Linux is done by running ``make local`` and including the directory 'agmonsynchrony' in the PYTHONPATH environment variable.
Tested using Anaconda 2023.09 (python 3.11) on Linux and Windows.
### Acknowledgements
This work was supported by the Natural Sciences and Engineering Research
Council of Canada (NSERC grant RGPIN-2020-05252).
### References
1. A. Agmon. [A novel, jitter-based method for detecting and measuring spike synchrony and quantifying temporal firing precision](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3423071/). *Neural Syst. Circuits* 2012, vol. 2, article 5.
2. J.-P. Longpré, S. Salavatian, E. Beaumont, J. A. Armour, J. L. Ardell, V. Jacquemet. [Measure of synchrony in the activity of intrinsic cardiac neurons](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC4019347/). *Physiol Meas.* 2014, vol. 35, no. 4, pp. 549–566.
Raw data
{
"_id": null,
"home_page": "http://github.com/jacquemv/agmonsynchrony",
"name": "agmonsynchrony",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "time series, synchrony, neuron, spikes",
"author": "Vincent Jacquemet",
"author_email": "vincent.jacquemet@umontreal.ca",
"download_url": "https://files.pythonhosted.org/packages/96/b4/7300ae5dcefe9cbdf593343bc066457ca58c7c80732be650fb04c5d445d7/agmonsynchrony-0.1.0.tar.gz",
"platform": null,
"description": "# agmonsynchrony\nCompute the jitter-based synchrony index between time series described in Agmon's paper [1].\n\n\n\n### Syntax\n\n```python\nSI, pval, Nc = synchrony_index(timeseries, tau, Nc_max_exact=1000)\n```\n\n### Arguments\n\n- **timeseries** (list or tuple of arrays): a list of two or more time series. Each time series is a sorted array of time instants.\n- **tau** (float or array): maximum delay between events of different time series for the identification of coincidences. The width of the jitter window used for computing the expected number of coincidences is set to 2*tau. If tau is an array, all values are used consecutively\n- **window** (str): if window is 'bilateral' (default), the original Agmon's method is applied; if window is 'unilateral', only coindidences occurring after (when tau > 0) or before (when tau < 0) the events of the reference time series are considered.\n- **Nc_max_exact** (int): number of coincidences above which a normal approximation (Z score) is used for computing the p-values (default: 1000, which is generally appropriate)\n\n### Outputs\n\n- **SI** (array with 2 or 3 dimensions): matrix of synchrony indices. Values normally range between 0 (no synchrony), and 1 (perfect synchrony) but can also be negative (antisynchrony) down to -1. The synchrony index SI[i, j] is computed between time series i (the reference) and j (the target). If 'tau' is an array, SI[i, j, k] is the synchrony index for the k-th value of 'tau'.\n- **pval** (array with the same shape as 'SI'): matrix of corresponding p-values for the significance of the synchrony\n- **Nc** (int array with the same shape as 'SI'): matrix of the number of observed coincidences\n\n\n### Example\n\nLet's consider two time series with 4 and 2 samples respectively. We are looking for coincidences within a maximum delay of 0.1:\n```python\nfrom agmonsynchrony import synchrony_index\nts1 = [1, 2, 3, 4]\nts2 = [2.03, 3.95]\nSI, pval, Nc = synchrony_index([ts1, ts2], tau=0.1)\n```\nThe number of observed coincidences is:\n```python\n>> print(Nc)\n[[4 2]\n [2 2]]\n```\nThe matrix of synchrony indices is:\n```python\n>> print(SI)\n[[1. 1.]\n [0.5 1.]]\n```\nThe diagonal is 1 because time series are synchronized with themselves. The lower left value is 0.5 because when the time series 'ts2' is taken as a reference, only half of the samples of the time series 'ts1' are within 'tau' of a sample of 'ts2'. Therefore, the matrix is not symmetric.\n\n### Installation\n\nThe package can be installed using the command ``pip install agmonsynchrony`` (on Windows, a compiler such as Microsoft Visual C++ is required).\n\nIf the code is downloaded from github, local installation on Linux is done by running ``make local`` and including the directory 'agmonsynchrony' in the PYTHONPATH environment variable.\n\nTested using Anaconda 2023.09 (python 3.11) on Linux and Windows.\n\n\n### Acknowledgements\n\nThis work was supported by the Natural Sciences and Engineering Research\nCouncil of Canada (NSERC grant RGPIN-2020-05252).\n\n\n### References\n\n1. A. Agmon. [A novel, jitter-based method for detecting and measuring spike synchrony and quantifying temporal firing precision](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3423071/). *Neural Syst. Circuits* 2012, vol. 2, article 5.\n\n2. J.-P. Longpr\u00e9, S. Salavatian, E. Beaumont, J. A. Armour, J. L. Ardell, V. Jacquemet. [Measure of synchrony in the activity of intrinsic cardiac neurons](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC4019347/). *Physiol Meas.* 2014, vol. 35, no. 4, pp. 549\u2013566.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Synchrony index between time series based on Agmon's paper",
"version": "0.1.0",
"project_urls": {
"Homepage": "http://github.com/jacquemv/agmonsynchrony"
},
"split_keywords": [
"time series",
" synchrony",
" neuron",
" spikes"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "96b47300ae5dcefe9cbdf593343bc066457ca58c7c80732be650fb04c5d445d7",
"md5": "6b5a5120ad86800329fb3d6540edd552",
"sha256": "9ac8ce7ca852775fba5fdb3ba0923853f7ab2125e178738a44c33053c44d53f1"
},
"downloads": -1,
"filename": "agmonsynchrony-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "6b5a5120ad86800329fb3d6540edd552",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 163288,
"upload_time": "2024-07-11T19:07:41",
"upload_time_iso_8601": "2024-07-11T19:07:41.815786Z",
"url": "https://files.pythonhosted.org/packages/96/b4/7300ae5dcefe9cbdf593343bc066457ca58c7c80732be650fb04c5d445d7/agmonsynchrony-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-11 19:07:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jacquemv",
"github_project": "agmonsynchrony",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "agmonsynchrony"
}
JSON
