https://github.com/unfoldtoolbox/unfold.jl

Neuroimaging (EEG, fMRI, pupil ...) regression analysis in Julia
https://github.com/unfoldtoolbox/unfold.jl

deconvolution eeg erp event-related-potentials julia mass-univariate-modeling mixed-models modeling overlap regression splines

Last synced: 4 months ago
JSON representation

Neuroimaging (EEG, fMRI, pupil ...) regression analysis in Julia

Host: GitHub
URL: https://github.com/unfoldtoolbox/unfold.jl
Owner: unfoldtoolbox
License: mit
Created: 2019-12-23T20:22:49.000Z (about 6 years ago)
Default Branch: main
Last Pushed: 2025-08-25T01:24:00.000Z (5 months ago)
Last Synced: 2025-09-04T23:15:11.728Z (4 months ago)
Topics: deconvolution, eeg, erp, event-related-potentials, julia, mass-univariate-modeling, mixed-models, modeling, overlap, regression, splines
Language: Julia
Homepage:
Size: 70.8 MB
Stars: 62
Watchers: 4
Forks: 14
Open Issues: 39
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Zenodo: .zenodo.json

Awesome Lists containing this project

README

          # [![Unfold.jl EEG toolbox](https://github.com/unfoldtoolbox/Unfold.jl/assets/10183650/3cbe57c1-e1a7-4150-817a-ce3dcc844485)](https://github.com/unfoldtoolbox/Unfold.jl)

[![Stable Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://unfoldtoolbox.github.io/UnfoldDocs/Unfold.jl/stable/)

[![In development documentation](https://img.shields.io/badge/docs-dev-blue.svg)](https://unfoldtoolbox.github.io/UnfoldDocs/Unfold.jl/dev/)

[![Test workflow status](https://github.com/unfoldtoolbox/Unfold.jl/actions/workflows/Test.yml/badge.svg?branch=main)](https://github.com/unfoldtoolbox/Unfold.jl/actions/workflows/Test.yml?query=branch%3Amain)

[![Lint workflow Status](https://github.com/unfoldtoolbox/Unfold.jl/actions/workflows/Lint.yml/badge.svg?branch=main)](https://github.com/unfoldtoolbox/Unfold.jl/actions/workflows/Lint.yml?query=branch%3Amain)

[![Docs workflow Status](https://github.com/unfoldtoolbox/Unfold.jl/actions/workflows/Docs.yml/badge.svg?branch=main)](https://github.com/unfoldtoolbox/Unfold.jl/actions/workflows/Docs.yml?query=branch%3Amain)

[![Coverage](https://codecov.io/gh/unfoldtoolbox/Unfold.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/unfoldtoolbox/Unfold.jl)

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5759066.svg)](https://doi.org/10.5281/zenodo.5759066)

[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)

[![All Contributors](https://img.shields.io/github/all-contributors/unfoldtoolbox/Unfold.jl?labelColor=5e1ec7&color=c0ffee&style=flat-square)](#contributors)

|Estimation|Visualisation|Simulation|BIDS pipeline|Decoding|Statistics|MixedModelling|

|---|---|---|---|---|---|---|

|  | ||||||

Package (-family) 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!](https://unfoldtoolbox.github.io/UnfoldDocs/Unfold.jl/dev/generated/HowTo/juliacall_unfold/)

### Julia installation

Click to expand

The recommended way to install julia is [juliaup](https://github.com/JuliaLang/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

```julia

using Pkg

Pkg.add("Unfold")

```

## Usage

Please check out [the documentation](https://unfoldtoolbox.github.io/UnfoldDocs/Unfold.jl/dev) for extensive tutorials, explanations and more!

### Tipp on Docs

You can read the docs online: [![Stable Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://unfoldtoolbox.github.io/UnfoldDocs/Unfold.jl/stable)  - 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

```julia

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](https://unfoldtoolbox.github.io/UnfoldDocs/UnfoldMakie.jl/dev/)  |

| Interactive plotting  |       |         | stay tuned - coming soon! |

| simulation tools          | x      |         | [UnfoldSim.jl](https://unfoldtoolbox.github.io/UnfoldDocs/UnfoldSim.jl)  |

| BIDS support          | x      |         | alpha: [UnfoldBIDS.jl](https://unfoldtoolbox.github.io/UnfoldDocs/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](https://unfoldtoolbox.github.io/UnfoldDocs/UnfoldDecode.jl)         |

| outlier-robust fits  |        |        |  [many options (but slower)](https://unfoldtoolbox.github.io/UnfoldDocs/Unfold.jl/dev/HowTo/custom_solvers/#Robust-Solvers)   |

| 🐍Python support | | | [via juliacall](https://unfoldtoolbox.github.io/UnfoldDocs/Unfold.jl/dev/generated/HowTo/juliacall_unfold/)|

## 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](https://documentation.divio.com/)).

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](https://github.com/unfoldtoolbox/Unfold.jl/blob/main/docs/make.jl) with a reference to `docs/src/generated/FOLDER/FILENAME.md`.

## Contributors

  

    

      
_{Judith Schepers}
🐛 💻 📖 ✅ 🤔 ⚠️

      
_{Benedikt Ehinger}
🐛 💻 📖 ✅ 🤔 ⚠️ 🚇 ⚠️ 🚧 👀 💬

      
_{René Skukies}
🐛 📖 ✅ 💻 🤔

      
_{Manpa Barman}
🚇

      
_{Phillip Alday}
💻 🚇

      
_{Dave Kleinschmidt}
📖

      
_{Saket Saurabh}
🐛

    

    

      
_suddha-bpn
🐛

      
_{Vladimir Mikheev}
🐛 📖

      
_carmenamme
📖

      
_{Maximilien Van Migem}
🐛

      
_{Till Prölß}
📖 🐛

      
_{Leon von Haugwitz}
🐛

    

  

This project follows the [all-contributors](https://allcontributors.org/docs/en/specification) specification.

Contributions of any kind welcome!

## Citation

For now, please cite

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5759066.svg)](https://doi.org/10.5281/zenodo.5759066) and/or [Ehinger & Dimigen](https://peerj.com/articles/7838/)

## 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

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/unfoldtoolbox/unfold.jl

Awesome Lists containing this project

README