IntrinsicTimescales.jl Documentation
Welcome to the documentation of IntrinsicTimescales.jl. IntrinsicTimescales.jl is a software package for estimating Intrinsic Neural Timescales (INTs) from time-series data. It uses model-free methods (ACW-50, ACW-0, fitting an exponential decay function etc.) and simulation-based methods (adaptive approximate Bayesian computation: aABC, currently experimental automatic differentiation variational inference: ADVI) to estimate INTs.
Installation
This package is written in Julia. If you do not have Julia installed, you can install it from here. Once you have Julia installed, you can install IntrinsicTimescales.jl by running the following command in the Julia REPL:
using Pkg
Pkg.add("IntrinsicTimescales")Soon, there will also be a Python wrapper called INTpy, which will allow you to use IntrinsicTimescales.jl from Python.
Quickstart
IntrinsicTimescales.jl uses two ways to estimate INTs: model-free methods and simulation-based inference. Model-free methods include ACW-50, ACW-0, ACW-e, decay rate of an exponential fit to ACF and knee freqency of a lorentzian fit to PSD. Simulation-based methods are based on Zeraati et al. (2022) paper and do parameter estimation by assuming the data came from an Ornstein-Uhlenbeck process. For estimation, in addition to the aABC method used in Zeraati et al. (2022), we also present ADVI.
For model-free methods, simply use
using IntrinsicTimescales
data = randn(10, 5000) # Data in the form of (trials x time)
fs = 100.0 # Sampling frequency
acwresults = acw(data, fs; acwtypes = [:acw0, :acw50, :acweuler, :auc, :tau, :knee], dims=ndims(data))
# or even simpler:
acwresults = acw(data, fs)where fs is sampling frequency, optional parameters acwtypes is a vector of symbols (indicated with :) telling which methods to use and dims is indicating the dimension of time in your array (by default, the last dimension). The resulting acwresults gives the results in the same order of acwtypes.
For simulation based methods, pick one of the one_timescale_model, one_timescale_with_missing_model, one_timescale_and_osc_model and one_timescale_and_osc_with_missing_model functions. These models correspond to different generative models depending on whether there is an oscillation or not. For each generative model, there are with or without missing variants which use different ways to calculate ACF and PSD. Once you pick the model, the syntax is
data = randn(10, 5000) # Data in the form of (trials x time)
time = 1.0:5000.0 # Vector of time points
model = one_timescale_model(data, time, :abc)
result = int_fit(model)or
model = one_timescale_model(data, time, :advi)
result = int_fit(model)These functions are highly customizable, see the page Simulation Based Timescale Estimation.
Organization of the package
The diagram below shows the rough organization of the package:
Where to go from here?
This documentation is divided in five parts. The fifth part API is an exhaustive list of functions and their signatures in the package. It is boring and most of the functions are not intended for end-user (you). A better place to start is the third and fourth parts, Implementation and Navigating the Forest of INT Metrics. The implementation part documents model-free and simulation-based methods that are used in the package, with the full function signatures. This part should serve as the reference for you. The section longly titled Navigating the Forest of INT Metrics intends to give practical considerations for picking which INT metric to use in which situation. If you are already familiar with calculating INTs and just want to start using the package, these two are right places.
The remaining two parts are to understand the motivation to use various methods for calculating INTs and the motivation to calculate INTs (i.e., practice and theory). The first part is Practice. It is usually easier to understand something after you do it, therefore, I placed the practice section before theory. In Practice, we carefully build our way towards estimating INTs by starting from the autocorrelation function and slowly proceeding to more and more advanced methods. The second part is Theory. This part delves into the history of INT research, what it means in the brain and what it is good for with a particular emphasis on theoretical research, summarizing the cutting edge in this frontier. It is especially useful for researchers working on INT itself. Right now, it is in construction. I will deploy it as soon as it is ready.
Getting Help and Making Contributions
Questions and contributions are welcome. Use the issues section of our github page to report bugs and make feature requests and ask questions. Please see Contributing Guidelines before contributing.
Statement of Need
Intrinsic neural timescales (INTs) were found to be an important metric to probe the brain dynamics and function. On the neuroscientific side, INTs were found to follow the large-scale gradients in the cortex ranging from uni to transmodal areas including local and long-range excitation and proxies of myelination. From a cognitive science perspective, INTs were found to be related to reward, behavior, self, consciousness among others. Proper estimation of INTs to make sure the estimates are not affected by limited data, missingness of the data and oscillatory artifacts is crucial. While several methods exist for estimating INTs, there is a lack of standardized, open-source tools that implement both traditional model-free approaches and modern Bayesian estimation techniques. Existing software solutions are often limited to specific estimation methods, lack proper uncertainty quantification, or are not optimized for large-scale neuroimaging data.
IntrinsicTimescales.jl addresses these limitations by providing a comprehensive, high-performance toolbox for INT estimation. The package implements both established model-free methods and novel Bayesian approaches, allowing researchers to compare and validate results across different methodologies with a simple API. Its implementation in Julia ensures computational efficiency, crucial for analyzing large neuroimaging datasets. The package's modular design facilitates easy extension and integration with existing neuroimaging workflows, while its rigorous testing and documentation make it accessible to researchers across different levels of programming expertise.
About
This package is developed by me, Yasir Çatal during my PhD. I got nerdsniped by Zeraati et al., 2021 paper and started writing the package. the rest evolved from the simple motivation of reimplementing abcTau in Julia with various performance optimizations.
I am doing my PhD on INTs and our lab is specialized on the topic. As a result, I had many conversations with almost every member of our lab about INTs. I designed this documentation while keeping those conversations in mind. My goal was not only to document the package, but also to build up the knowledge to grasp the concept of INTs especially for new researchers starting their journey and active researchers in the trenches if they wish to brush up their basics.
Citations
See Citations to see the papers you can cite specific to methods.