Toolbox to perform linear / GAM / hierarchical / deconvolution regression on biological signals.
This kind of modelling is also known as encoding modeling, linear deconvolution, Temporal Response Functions (TRFs), linear system identification, and probably under other names. fMRI models with HRF-basis functions and pupil-dilation bases are also supported.
We clearly recommend Julia π - but Python users can use juliacall/Unfold directly from python!
Click to expand
The recommended way to install julia is juliaup. It allows you to, e.g., easily update Julia at a later point, but also test out alpha/beta versions etc.
TL:DR; If you dont want to read the explicit instructions, just copy the following command
AppStore -> JuliaUp, or winget install julia -s msstore in CMD
curl -fsSL https://install.julialang.org | sh in any shell
using Pkg
Pkg.add("Unfold")Please check out the documentation for extensive tutorials, explanations and more!
You can read the docs online: ?fit, ?effects julia-REPL feature. To filter docs, use e.g. ?fit(::UnfoldModel)
Here is a quick overview on what to expect.
using Unfold
events::DataFrame
# formula with or without random effects
f = @formula 0~1+condA
fLMM = @formula 0~1+condA+(1|subject) + (1|item)
# in case of [overlap-correction] we need continuous data plus per-eventtype one basisfunction (typically firbasis)
data::Array{Float64,2}
basis = firbasis(Ο=(-0.3,0.5),srate=250) # for "timeexpansion" / deconvolution
# in case of [mass univariate] we need to epoch the data into trials, and a accompanying time vector
epochs::Array{Float64,3} # channel x time x epochs (n-epochs == nrows(events))
times = range(0,length=size(epochs,3),step=1/sampling_rate)To fit any of the models, Unfold.jl offers a unified syntax:
| Overlap-Correction | Mixed Modelling | julia syntax |
|---|---|---|
fit(UnfoldModel,[Any=>(f,times)),evts,data_epoch] |
||
| x | fit(UnfoldModel,[Any=>(f,basis)),evts,data] |
|
| x | fit(UnfoldModel,[Any=>(fLMM,times)),evts,data_epoch] |
|
| x | x | fit(UnfoldModel,[Any=>(fLMM,basis)),evts,data] |
Click to expand
The matlab version is still maintained, but active development happens in Julia.
| Feature | Unfold | unmixed (defunct) | Unfold.jl |
|---|---|---|---|
| overlap correction | x | x | x |
| non-linear splines | x | x | x |
| speed | π | β‘ 2-100x | |
| GPU support | π | ||
| plotting tools | x | UnfoldMakie.jl | |
| Interactive plotting | stay tuned - coming soon! | ||
| simulation tools | x | UnfoldSim.jl | |
| BIDS support | x | alpha: UnfoldBIDS.jl) | |
| sanity checks | x | x | |
| tutorials | x | x | |
| unittests | x | x | |
| Alternative bases e.g. HRF (fMRI) | x | ||
| mix different basisfunctions | x | ||
| different timewindows per event | x | ||
| mixed models | x | x | |
| item & subject effects | (x) | x | |
| decoding | UnfoldDecode.jl | ||
| outlier-robust fits | many options (but slower) | ||
| πPython support | via juliacall |
Contributions are very welcome. These could be typos, bugreports, feature-requests, speed-optimization, new solvers, better code, better documentation.
You are very welcome to raise issues and start pull requests!
- We recommend to write a Literate.jl document and place it in
docs/literate/FOLDER/FILENAME.jlwithFOLDERbeingHowTo,Explanation,TutorialorReference(recommended reading on the 4 categories). - Literate.jl converts the
.jlfile to a.mdautomatically and places it indocs/src/generated/FOLDER/FILENAME.md. - Edit make.jl with a reference to
docs/src/generated/FOLDER/FILENAME.md.
This project follows the all-contributors specification.
Contributions of any kind welcome!
For now, please cite
This work was initially supported by the Center for Interdisciplinary Research, Bielefeld (ZiF) Cooperation Group "Statistical models for psychological and linguistic data".
Funded by Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) under GermanyΒ΄s Excellence Strategy β EXC 2075 β 390740016