Skip to content

unfoldtoolbox/Unfold.jl

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Unfold.jl EEG toolbox

Docs semver Build Status

Estimation Visualisation Simulation BIDS pipeline Decoding Statistics

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.

Getting started

🐍Python User?

We clearly recommend Julia πŸ˜‰ - but Python users can use juliacall/Unfold directly from python!

Julia installation

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

Windows

AppStore -> JuliaUp, or winget install julia -s msstore in CMD

Mac & Linux

curl -fsSL https://install.julialang.org | sh in any shell

Unfold.jl installation

using Pkg
Pkg.add("Unfold")

Usage

Please check out the documentation for extensive tutorials, explanations and more!

Tipp on Docs

You can read the docs online: Docs - or use the ?fit, ?effects julia-REPL feature. To filter docs, use e.g. ?fit(::UnfoldModel)

Here is a quick overview on what to expect.

What you need

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]

Comparison to Unfold (matlab)

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

Contributions are very welcome. These could be typos, bugreports, feature-requests, speed-optimization, new solvers, better code, better documentation.

How-to Contribute

You are very welcome to raise issues and start pull requests!

Adding Documentation

  1. We recommend to write a Literate.jl document and place it in docs/literate/FOLDER/FILENAME.jl with FOLDER being HowTo, Explanation, Tutorial or Reference (recommended reading on the 4 categories).
  2. Literate.jl converts the .jl file to a .md automatically and places it in docs/src/generated/FOLDER/FILENAME.md.
  3. Edit make.jl with a reference to docs/src/generated/FOLDER/FILENAME.md.

Contributors

Judith Schepers
Judith Schepers

πŸ› πŸ’» πŸ“– βœ… πŸ€” ⚠️
Benedikt Ehinger
Benedikt Ehinger

πŸ› πŸ’» πŸ“– βœ… πŸ€” ⚠️ πŸš‡ ⚠️ 🚧 πŸ‘€ πŸ’¬
RenΓ© Skukies
RenΓ© Skukies

πŸ› πŸ“– βœ… πŸ’» πŸ€”
Manpa Barman
Manpa Barman

πŸš‡
Phillip Alday
Phillip Alday

πŸ’» πŸš‡
Dave Kleinschmidt
Dave Kleinschmidt

πŸ“–
Saket Saurabh
Saket Saurabh

πŸ›
suddha-bpn
suddha-bpn

πŸ›
Vladimir Mikheev
Vladimir Mikheev

πŸ› πŸ“–
carmenamme
carmenamme

πŸ“–
Maximilien Van Migem
Maximilien Van Migem

πŸ›

This project follows the all-contributors specification.

Contributions of any kind welcome!

Citation

For now, please cite

DOI and/or Ehinger & Dimigen

Acknowledgements

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