You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+50-45Lines changed: 50 additions & 45 deletions
Original file line number
Diff line number
Diff line change
@@ -1,77 +1,82 @@
1
-
<h2>Overview</h2>
1
+
# Overview
2
2
3
-
The timecorr toolbox provides tools for computing and exploring the correlational structure of timeseries data. There is one main function:
4
-
+`timecorr` is used to compute dynamic correlations from a timeseries of observations and to find higher order structure in the data, organized as a number-of-timepoints by number-of-features matrix. For examples, tutorials, and an API specification, please check out our [readthedocs page](https://timecorr.readthedocs.io/en/latest/).
3
+
The timecorr toolbox provides tools for computing and exploring the correlational structure of timeseries data. Everything in the toolbox is built around one main function, `timecorr`. The `timecorr` function is used to compute dynamic correlations from a timeseries of observations and to find higher order structure in the data, organized as a number-of-timepoints by number-of-features matrix. For examples, tutorials, and an API specification, please check out our [readthedocs page](https://timecorr.readthedocs.io/en/latest/).
5
4
6
5
7
-
<h2>Basic usage</h2>
6
+
# Basic usage
8
7
9
8
The `timecorr` function takes your data and returns moment-by-moment correlations during the same timepoints. `timecorr` also lets you explore higher order structure in the data in a computationally tractable way by specifiying a dimensionality reduction technique.
10
-
+`timecorr` computes dynamic correlations and return a result in the same format, but where each data matrix has number-of-timepoints rows and $\frac{n^2 - n}{2}$ features (i.e. a vectorized version of the upper triangle of each timepoint's correlation matrix).
11
-
+`timecorr` also lets you explore higher order structure in the data by projecting the correlations back onto the original number-of-timepoints by number-of-featuers space.
9
+
-`timecorr` computes dynamic correlations and return a result in the same format, but where each data matrix has number-of-timepoints rows and $\frac{n^2 - n}{2}$ features (i.e. a vectorized version of the upper triangle of each timepoint's correlation matrix).
10
+
-`timecorr` also lets you explore higher order structure in the data by projecting the correlations back onto the original number-of-timepoints by number-of-featuers space.
12
11
13
12
14
-
Format your data
15
-
+ You should format your data as a Numpy array or Pandas dataframe with one row per observation and one column per feature (i.e. things you're tracking over time-- e.g. a voxel, electrode, channel, etc.). You can then pass timecorr a single dataframe or a list of dataframes (each with the same numbers of timepoints and features).
13
+
## Format your data
14
+
- You should format your data as a Numpy array or Pandas dataframe with one row per observation and one column per feature (i.e. things you're tracking over time-- e.g. a voxel, electrode, channel, etc.). You can then pass timecorr a single dataframe or a list of dataframes (each with the same numbers of timepoints and features).
16
15
17
-
Pick a `weights_function`
18
-
+ How much the observed data at every timepoint contributes to the correlations at each timepoint.
16
+
## Pick a `weights_function`
17
+
- How much the observed data at every timepoint contributes to the correlations at each timepoint.
19
18
20
-
Specify the `weights_params`
21
-
+ Parameters for `weights_function`
19
+
## Specify the `weights_params`
22
20
23
-
Choose `cfun` for computing dynamic correlations
24
-
+ The correlations may be computed _within_ a single matrix, or _across_ a list of such matrices. If a list of data matrices are passed, each data matrix is compared to the average of the other data matrices (`isfc` mode) or a similarity-weighted average of the other data matrices (`wisfc` mode). If only a single data matrix is passed, the correlations are computed with respect to the same data matrix.
25
-
+ Computing correlations _across_ a list is for finding shared correlation across sets of observations (e.g. from different experimental participants). If only a single data matrix is passed, `across` mode will behave the same as `within` mode. If a list of data matrices is passed, `isfc` mode computes each matrix's correlations with respect to the average of the others, and then averages across all of those correlations. `wisfc` mode behaves similarly, but computes weighted averages (e.g. based on inter-matrix similarities).
21
+
- Parameters for `weights_function`
26
22
27
-
Choose `rfun` for reducing the data and exploring higher order structure
28
-
+ By specifiying a reduction technique, `rfun`, `timecorr` takes a timeseries of observations and returns a timeseries of correlations _with the same number of features_. This is useful in that it prevents "dimension blowup" whereby running timecorr its own output squares the number of features-- thereby preventing the efficient exploration of higher-order correlations.
29
-
+ This function may be called recursively to compute dynamic correlations ("level 1"), dynamic correlations _between_ correlations ("level 2"), dynamic correlations between correlations between correlations ("level 3"), etc. If `rfun` is not specified, the returned data matrix will have number-of-timepoints rows and $\frac{n^2 - n}{2}$ features.
23
+
## Choose `cfun` for computing dynamic correlations
24
+
25
+
- The correlations may be computed _within_ a single matrix, or _across_ a list of such matrices. If a list of data matrices are passed, each data matrix is compared to the average of the other data matrices (`isfc` mode) or a similarity-weighted average of the other data matrices (`wisfc` mode). If only a single data matrix is passed, the correlations are computed with respect to the same data matrix.
26
+
27
+
- Computing correlations _across_ a list is for finding shared correlation across sets of observations (e.g. from different experimental participants). If only a single data matrix is passed, `across` mode will behave the same as `within` mode. If a list of data matrices is passed, `isfc` mode computes each matrix's correlations with respect to the average of the others, and then averages across all of those correlations. `wisfc` mode behaves similarly, but computes weighted averages (e.g. based on inter-matrix similarities).
28
+
29
+
## Choose `rfun` for reducing the data and exploring higher order structure
30
+
31
+
- By specifiying a reduction technique, `rfun`, `timecorr` takes a timeseries of observations and returns a timeseries of correlations _with the same number of features_. This is useful in that it prevents "dimension blowup" whereby running timecorr its own output squares the number of features-- thereby preventing the efficient exploration of higher-order correlations.
32
+
33
+
- This function may be called recursively to compute dynamic correlations ("level 1"), dynamic correlations _between_ correlations ("level 2"), dynamic correlations between correlations between correlations ("level 3"), etc. If `rfun` is not specified, the returned data matrix will have number-of-timepoints rows and $\frac{n^2 - n}{2}$ features.
30
34
31
35
Toolbox documentation, including a full API specification, tutorials, and gallery of examples may be found [here](http://timecorr.readthedocs.io/) on our readthedocs page.
32
36
33
-
<h2>Installation</h2>
37
+
# Installation
34
38
35
-
<h3>Recommended way of installing the toolbox</h3>
39
+
## Recommended way of installing the toolbox
36
40
You may install the latest stable version of our toolbox using [pip](https://pypi.org):
37
41
38
-
`pip install timecorr`
42
+
```
43
+
pip install timecorr
44
+
```
39
45
40
46
or if you have a previous version already installed:
41
47
42
-
`pip install --upgrade timecorr`
48
+
```
49
+
pip install --upgrade timecorr
50
+
```
43
51
44
52
45
-
<h3>Dangerous (hacker) developer way of installing the toolbox (use caution!)</h3>
53
+
## Dangerous (hacker) developer way of installing the toolbox (use caution!)
46
54
To install the latest (bleeding edge) version directly from this repository use:
The toolbox is currently supported on Mac and Linux. It has not been tested on Windows (and we expect key functionality not to work properly on Windows systems).
54
64
Dependencies:
55
-
+ Python 3.9+
56
-
+ Numpy >= 1.10.4
57
-
+ Scipy >= 1.0.0
58
-
+ Seaborn >= 0.8.1
59
-
+ Matplotlib >=2.0.1
60
-
+ Pandas >= 0.22.0
61
-
+ Hypertools >= 0.4.2
65
+
- hypertools>=0.7.0
66
+
- scipy>=1.2.1
67
+
- scikit-learn>=0.19.2
62
68
63
-
<h2>Citing this toolbox</h2>
69
+
# Citing this toolbox
64
70
65
71
If you use (or build on) this toolbox in your work, we'd appreciate a citation! Please cite the following paper:
66
-
```
67
-
Owen LLW, Chang TH, Manning JR (2019) High-level cognition during story listening is reflected in high-order dynamic correlations in neural activity patterns. bioRxiv: doi.org/10.1101/763821
68
-
```
69
72
70
-
<h2>Contributing</h2>
73
+
> Owen LLW, Chang TH, Manning JR (2021) High-level cognition during story listening is reflected in high-order dynamic correlations in neural activity patterns. Nature Communications 12(5728): [doi.org/10.1038/s41467-021-25876-x](https://doi.org/10.1038/s41467-021-25876-x).
74
+
75
+
# Contributing
71
76
72
77
Thanks for considering adding to our toolbox! Some text below has been borrowed from the [Matplotlib contributing guide](http://matplotlib.org/devdocs/devel/contributing.html).
73
78
74
-
<h3>Submitting a bug report</h3>
79
+
## Submitting a bug report
75
80
76
81
If you are reporting a bug, please do your best to include the following:
77
82
@@ -80,21 +85,21 @@ If you are reporting a bug, please do your best to include the following:
80
85
3. The actual outcome of the code snippet
81
86
4. The expected outcome of the code snippet
82
87
83
-
<h3>Contributing code</h3>
88
+
## Contributing code
84
89
85
90
The preferred way to contribute to timecorr is to fork the main repository on GitHub, then submit a pull request.
86
91
87
-
+ If your pull request addresses an issue, please use the title to describe the issue and mention the issue number in the pull request description to ensure a link is created to the original issue.
92
+
- If your pull request addresses an issue, please use the title to describe the issue and mention the issue number in the pull request description to ensure a link is created to the original issue.
88
93
89
-
+ All public methods should be documented in the README.
94
+
- All public methods should be documented in the README.
90
95
91
-
+ Each high-level plotting function should have a simple example in the examples folder. This should be as simple as possible to demonstrate the method.
96
+
- Each high-level plotting function should have a simple example in the examples folder. This should be as simple as possible to demonstrate the method.
92
97
93
-
+ Changes (both new features and bugfixes) should be tested using `pytest`. Add tests for your new feature to the `tests/` repo folder.
98
+
- Changes (both new features and bugfixes) should be tested using `pytest`. Add tests for your new feature to the `tests/` repo folder.
94
99
95
-
+ Please note that the code is currently in beta thus the API may change at any time. BE WARNED.
100
+
- Please note that the code is currently in beta thus the API may change at any time. BE WARNED.
0 commit comments