API Reference#

This page contains the complete API reference for all timecorr functions. Each function includes detailed parameter descriptions, return values, and usage examples.

Core Functions#

The main functions for computing dynamic correlations and exploring temporal structure.

timecorr

Computes dynamics correlations in single-subject or multi-subject data.

Primary Analysis Function#

timecorr.timecorr(data, weights_function=<function gaussian_weights>, weights_params=None, include_timepoints='all', exclude_timepoints=None, combine=<function null_combine>, cfun=<function isfc>, rfun=None)[source]#

Computes dynamics correlations in single-subject or multi-subject data.

Parameters:

data: numpy array, pandas dataframe, or a list of numpy arrays/dataframes

Each numpy array (or dataframe) should have size timepoints by features. If a list of arrays are passed, there should be one array per subject.

weights_function: a function of the form func(T, params) where

T is a non-negative integer specifying the number of timepoints to consider.

The function should return a T by T array containing the timepoint-specific weights for each consecutive time point from 0 to T (not including T).

Default: gaussian_weights; options: laplace_weights, gaussian_weights, t_weights, eye_weights, mexican_hat_weights

weights_params: used to pass parameters to the weights_params function. This

can be specified in any format (e.g. a scalar, list, object, dictionary, etc.).

Default: None (use default parameters for the given weights function). Options: gaussian_params, laplace_params, t_params, eye_params, mexican_hat_params.

include_timepoints: determines which timepoints are used to estimate the correlations

at each timepoint. This is applied after the weights function to further constrain which timepoints may be considered in computing the correlations at each timepoint.

Options: ‘all’ (default; include all timepoints), ‘pre’ (only include timepoints before the given timepoint), ‘post’ (only include timepoints after the given timepoint).

exclude_timepoints: additional option, used to filter out any timepoints less than x units

of the timepoint whose correlations are being estimated. For example, passing exclude_timepoints=3 will exclude any timepoints 3 or more samples from the given timepoint. When exclude timepoints is negative, it works inversely– e.g. exclude_timepoints=-5 will exclude any timepoints within 5 or fewer samples of the given timepoint. Real-valued scalars are supported but are rounded to the nearest Integer.

Default: None (no filtering).

combine: a function applied to either a single matrix of vectorized correlation

matrices, or a list of such matrices. The function should return either a numpy array or a list of numpy arrays.

Default: helpers.null_combine (a function that returns its input). Other useful functions:

helpers.corrmean_combine: take the element-wise average correlations across matrices helpers.tstat_combine: return element-wise t-statistics across matrices

cfun: function to apply to the data array(s)

This function should be of the form func(data, weights)

The function should support data as a numpy array or list of numpy arrays. When a list of numpy arrays is passed, the function should apply the “across subjects” version of the analysis. When a single numpy array is passed, the function should apply the “within subjects” version of the analysis.

weights is a numpy array with per-timepoint weights

The function should return a single numpy array with 1 row and an arbitrary number of columns (the number of columns may be determined by the function).

Default: A continuous verison of Inter-Subject Functional Connectivity (Simony et al. 2017). If only one data array is passed (rather than a list), the default cfun returns the moment-by-moment correlations for that array. (Reference: http://www.nature.com/articles/ncomms12141)

rfun: function to use for dimensionality reduction.

All hypertools and scikit-learn functions are supported: PCA, IncrementalPCA, SparsePCA, MiniBatchSparsePCA, KernelPCA, FastICA, FactorAnalysis, TruncatedSVD, DictionaryLearning, MiniBatchDictionaryLearning, TSNE, Isomap, SpectralEmbedding, LocallyLinearEmbedding, MDS, and UMAP.

Can be passed as a string, but for finer control of the model parameters, pass as a dictionary, e.g. reduction={‘model’ : ‘PCA’, ‘params’ : {‘whiten’ : True}}.

See scikit-learn specific model docs for details on parameters supported for each model.

Another option is to use graph theoretic measures computed for each node. The following measures are supported: eigenvector_centrality, pagerank_centrality, and strength. (Each of these must be specified as a string; dictionaries not supported.)

Default: None (no dimensionality reduction)

Returns:

corrmats: moment-by-moment correlations

Quick Example:

import numpy as np
import timecorr as tc

# Basic usage
data = np.random.randn(100, 5)
correlations = tc.timecorr(data, weights_function=tc.gaussian_weights)

Correlation Functions (cfun)#

Functions for computing correlations within or across datasets.

`isfc`	Compute Inter-Subject Functional Connectivity (ISFC).
`wisfc`	Compute moment-by-moment correlations between sets of observations
`autofc`	Compute auto-correlations within each subject's data.

Inter-Subject Functional Connectivity#

timecorr.isfc(data, timepoint_weights)[source]#

Compute Inter-Subject Functional Connectivity (ISFC).

ISFC computes correlations between each subject’s data and the average of all other subjects, providing a measure of shared neural patterns across participants while avoiding self-correlation artifacts.

Parameters:

datalist of numpy.ndarray or numpy.ndarray: List of timeseries data matrices, each of shape (timepoints, features). If a single array is provided, it will be converted to a list.
timepoint_weightsnumpy.ndarray: T x T matrix of temporal weights for dynamic correlations

Returns:

list of numpy.ndarray: List of correlation matrices (one per subject), each showing correlations between that subject and the average of all others

Examples

>>> import timecorr as tc
>>> import numpy as np
>>> data = [np.random.randn(100, 10) for _ in range(5)]  # 5 subjects
>>> weights = tc.gaussian_weights(100, {'var': 10})
>>> isfc_results = tc.isfc(data, weights)
>>> len(isfc_results)  # 5

timecorr.wisfc(data, timepoint_weights, subject_weights=None)[source]#

Compute moment-by-moment correlations between sets of observations

Data:: a list of number-of-timepoints by V matrices
Timepoint weights:: a number-of-timepoints by number-of-timepoints weights matrix specifying the per-timepoint weights to be considered (for each timepoint)
Subject weights:: number-of-subjects by number-of-subjects weights matrix
Returns:: a list of number-of-timepoints by (V^2 - V)/2 + V correlation matrices

timecorr.autofc(data, timepoint_weights)[source]#

Compute auto-correlations within each subject’s data.

This function computes correlations within each subject’s own data, equivalent to standard within-subject dynamic correlations.

Parameters:

datalist of numpy.ndarray or numpy.ndarray: List of timeseries data matrices, each of shape (timepoints, features). If a single array is provided, it will be converted to a list.
timepoint_weightsnumpy.ndarray: T x T matrix of temporal weights for dynamic correlations

Returns:

list of numpy.ndarray: List of correlation matrices (one per subject), each showing within-subject correlations

Examples

>>> import timecorr as tc
>>> import numpy as np
>>> data = [np.random.randn(100, 10) for _ in range(3)]  # 3 subjects
>>> weights = tc.gaussian_weights(100, {'var': 10})
>>> auto_results = tc.autofc(data, weights)
>>> len(auto_results)  # 3

Examples:

# Multi-subject analysis
subjects = [np.random.randn(100, 5) for _ in range(10)]

# ISFC: Each subject vs. average of others
isfc_result = tc.timecorr(subjects, cfun=tc.isfc)

# WISFC: Weighted similarity-based averaging
wisfc_result = tc.timecorr(subjects, cfun=tc.wisfc)

Weighting Functions#

Kernel functions that control temporal smoothing and local correlation computation.

`gaussian_weights`	Generate Gaussian weighting function for dynamic correlations.
`laplace_weights`	Generate Laplace (exponential) weighting function for dynamic correlations.
`mexican_hat_weights`	Generate Mexican Hat (Ricker) weighting function for dynamic correlations.
`eye_weights`	Generate identity (delta) weighting function for dynamic correlations.

Examples:

# Different kernel types
gaussian_corr = tc.timecorr(data, weights_function=tc.gaussian_weights,
                           weights_params={'var': 10})

laplace_corr = tc.timecorr(data, weights_function=tc.laplace_weights,
                          weights_params={'scale': 5})

Dimensionality Reduction#

Functions for reducing correlation dimensionality and exploring higher-order structure.

`reduce`
`smooth`

String-based reduction options:

'PCA' - Principal Component Analysis
'ICA' - Independent Component Analysis
'FactorAnalysis' - Factor Analysis
'pagerank_centrality' - PageRank centrality
'eigenvector_centrality' - Eigenvector centrality

Example:

# Higher-order correlations with PCA reduction
higher_order = tc.timecorr(data, rfun='PCA')

Data Simulation#

Functions for generating synthetic datasets for testing and validation.

simulate_data

Simulate timeseries data

Example:

# Generate synthetic data
data = tc.simulate_data(datagen='block', T=100, K=5, B=10)

Utility Functions#

Helper functions for data manipulation and analysis.

Matrix Operations#

`mat2vec`	Function that converts correlation matrix to a vector
`vec2mat`	Function that converts vector back to correlation matrix
`wcorr`	Compute moment-by-moment correlations between sets of observations

Examples:

# Convert between matrix and vector formats
correlation_matrix = np.random.randn(5, 5)
correlation_vector = tc.mat2vec(correlation_matrix)
reconstructed_matrix = tc.vec2mat(correlation_vector)

Combination Functions#

`mean_combine`	Compute the element-wise mean across each matrix in a list.
`corrmean_combine`	Compute the mean element-wise correlation across each matrix in a list.

Example:

# Combine multi-subject results
subjects = [np.random.randn(100, 5) for _ in range(3)]
combined = tc.timecorr(subjects, cfun=tc.isfc, combine=tc.mean_combine)

Decoder Functions#

Functions for decoding and cross-validation analysis.

`timepoint_decoder`
`weighted_timepoint_decoder`

Example:

# Decode temporal patterns
subjects_data = [np.random.randn(100, 10) for _ in range(5)]
accuracy = tc.timepoint_decoder(subjects_data, nfolds=3)

Additional Weight Functions#

Other available weighting functions for specialized use cases.

`t_weights`
`uniform_weights`
`boxcar_weights`

Example:

# Additional kernel types
t_corr = tc.timecorr(data, weights_function=tc.t_weights,
                    weights_params={'df': 100})
uniform_corr = tc.timecorr(data, weights_function=tc.uniform_weights)

Function Parameters#

Common Parameters#

Most timecorr functions accept these common parameters:

dataarray-like or list of arrays
Input timeseries data with shape (timepoints, features)
weights_functioncallable
Kernel function for temporal weighting (e.g., gaussian_weights)
weights_paramsdict
Parameters for the weighting function
cfuncallable or None
Correlation function (isfc, wisfc, autofc, or None for within-subject)
rfuncallable, str, or None
Dimensionality reduction function or method name
combinecallable
Function for combining results across subjects/datasets

API Reference

Contents

API Reference#

Core Functions#

Primary Analysis Function#

Correlation Functions (cfun)#

Inter-Subject Functional Connectivity#

Weighting Functions#

Dimensionality Reduction#

Data Simulation#

Utility Functions#

Matrix Operations#

Combination Functions#

Decoder Functions#

Additional Weight Functions#

Function Parameters#

Common Parameters#

See Also#