inital commit

Project.toml

@@ -3,5 +3,29 @@ uuid = "019ae9e0-8363-565c-86e5-97a5a2fe84f4"
 authors = ["Benedikt Ehinger <[email protected]>"]
 version = "0.1.0"
 
+[deps]
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+MixedModels = "ff71e718-51f3-5ec2-a782-8ffcbfa3c316"
+ProgressMeter = "92933f4c-e287-5a05-a399-4b506db050ca"
+Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
+SimpleTraits = "699a6c99-e7fa-54fc-8d76-47d257e15c1d"
+SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
+StatsModels = "3eaba693-59b7-5ba5-a881-562e759f1c8d"
+Unfold = "181c99d8-e21b-4ff3-b70b-c233eddec679"
+
 [compat]
+DataFrames = "1.7.0"
+DocStringExtensions = "0.9.3"
+LinearAlgebra = "1.11.0"
+MixedModels = "4.28.0"
+ProgressMeter = "1.10.2"
+Reexport = "1.2.2"
+SimpleTraits = "0.9.4"
+SparseArrays = "1.11.0"
+StaticArrays = "1.9.10"
+StatsModels = "0.7.4"
+Unfold = "0.8"
 julia = "1.10"

README.md

@@ -10,15 +10,101 @@
 [![DOI](https://zenodo.org/badge/DOI/FIXME)](https://doi.org/FIXME)
 [![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/UnfoldMixedModels.jl?labelColor=5e1ec7&color=c0ffee&style=flat-square)](#contributors)
-[![BestieTemplate](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/JuliaBesties/BestieTemplate.jl/main/docs/src/assets/badge.json)](https://github.com/JuliaBesties/BestieTemplate.jl)
 
-## How to Cite
+|Estimation|Visualisation|Simulation|BIDS pipeline|Decoding|Statistics|
+|---|---|---|---|---|---|
+| <a href="https://github.com/unfoldtoolbox/Unfold.jl/tree/main"><img src="https://github-production-user-asset-6210df.s3.amazonaws.com/10183650/277623787-757575d0-aeb9-4d94-a5f8-832f13dcd2dd.png" alt="Unfold.jl Logo"></a> | <a href="https://github.com/unfoldtoolbox/UnfoldMakie.jl"><img  src="https://github-production-user-asset-6210df.s3.amazonaws.com/10183650/277623793-37af35a0-c99c-4374-827b-40fc37de7c2b.png" alt="UnfoldMakie.jl Logo"></a>|<a href="https://github.com/unfoldtoolbox/UnfoldSim.jl"><img src="https://github-production-user-asset-6210df.s3.amazonaws.com/10183650/277623795-328a4ccd-8860-4b13-9fb6-64d3df9e2091.png" alt="UnfoldSim.jl Logo"></a>|<a href="https://github.com/unfoldtoolbox/UnfoldBIDS.jl"><img src="https://github-production-user-asset-6210df.s3.amazonaws.com/10183650/277622460-2956ca20-9c48-4066-9e50-c5d25c50f0d1.png" alt="UnfoldBIDS.jl Logo"></a>|<a href="https://github.com/unfoldtoolbox/UnfoldDecode.jl"><img src="https://github-production-user-asset-6210df.s3.amazonaws.com/10183650/277622487-802002c0-a1f2-4236-9123-562684d39dcf.png" alt="UnfoldDecode.jl Logo"></a>|<a href="https://github.com/unfoldtoolbox/UnfoldStats.jl"><img  src="https://github-production-user-asset-6210df.s3.amazonaws.com/10183650/277623799-4c8f2b5a-ea84-4ee3-82f9-01ef05b4f4c6.png" alt="UnfoldStats.jl Logo"></a>|
 
-If you use UnfoldMixedModels.jl in your work, please cite using the reference given in [CITATION.cff](https://github.com/unfoldtoolbox/UnfoldMixedModels.jl/blob/main/CITATION.cff).
+Toolbox to perform hierarchical regression / linear mixed models on biological signals - experimental: even with overlap correction
 
----
+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.
 
-### Contributors
+## Getting started
+
+### 🐍Python User?
+
+We clearly recommend Julia 😉 - but [Python users can use juliacall/Unfold directly from python!](https://unfoldtoolbox.github.io/Unfold.jl/dev/generated/HowTo/juliacall_unfold/)
+
+### Julia installation
+
+<details>
+<summary>Click to expand</summary>
+
+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
+</details>
+
+### Unfold.jl installation
+
+```julia
+using Pkg
+Pkg.add("UnfoldMixedModels")
+```
+
+## Usage
+
+Please check out [the documentation](https://unfoldtoolbox.github.io/UnfoldMixedModels.jl) 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/UnfoldMixedModels.jl/stable)  - or use the `?fit`, `?effects` julia-REPL feature. To filter docs, use e.g. `?fit(::UnfoldMixedModel)`
+
+Here is a quick overview on what to expect.
+
+### What you need
+
+```julia
+using UnfoldMixedModels
+
+events::DataFrame
+
+# formula with or without random effects
+
+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 |
+|:---:|:---:|---|
+|  | x | `fit(UnfoldModel,[Any=>(fLMM,times)),evts,data_epoch]` |
+| x | x | `fit(UnfoldModel,[Any=>(fLMM,basis)),evts,data]` |
+
+</details>
+
+## 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/UnfoldMixedModels.jl/blob/main/docs/make.jl) with a reference to `docs/src/generated/FOLDER/FILENAME.md`.
+
+## Contributors
 
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
 <!-- prettier-ignore-start -->
@@ -28,3 +114,19 @@ If you use UnfoldMixedModels.jl in your work, please cite using the reference gi
 <!-- prettier-ignore-end -->
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->
+
+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

docs/Project.toml

@@ -1,11 +1,16 @@
-# Don't forget to run
-#
-#     pkg> dev ..
-#
 [deps]
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+CategoricalArrays = "324d7699-5711-5eae-9e2f-1d82baa6b597"
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+DisplayAs = "0b91fe84-8a4c-11e9-3e1d-67c38462b6d6"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
+MixedModels = "ff71e718-51f3-5ec2-a782-8ffcbfa3c316"
+Unfold = "181c99d8-e21b-4ff3-b70b-c233eddec679"
+UnfoldMakie = "69a5ce3b-64fb-4f22-ae69-36dd4416af2a"
 UnfoldMixedModels = "019ae9e0-8363-565c-86e5-97a5a2fe84f4"
+UnfoldSim = "ed8ae6d2-84d3-44c6-ab46-0baf21700804"
 
 [compat]
 Documenter = "1"

docs/make.jl

@@ -22,7 +22,21 @@ makedocs(;
     format = Documenter.HTML(;
         canonical = "https://unfoldtoolbox.github.io/UnfoldMixedModels.jl",
     ),
-    pages = ["index.md"; numbered_pages],
+    pages = [
+        "index.md",
+        "Tutorials" => [
+            "lmmERP (mass univariate)" => "tutorials/lmm_mu.md",
+            "lmmERP (overlap correction)" => "tutorials/lmm_overlap.md",
+        ],
+        "HowTo" => ["P-values for mixedModels" => "howto/lmm_pvalues.md"],
+        "Explanations" => [],
+        "Reference" => [
+            "API: Types" => "references/types.md",
+            "API: Functions" => "references/functions.md",
+        ],
+        "Contributing" => ["90-contributing.md"],
+        "Developer Guide" => ["91-developer.md"],
+    ],
 )
 
 deploydocs(; repo = "github.com/unfoldtoolbox/UnfoldMixedModels.jl")

docs/src/90-contributing.md

@@ -0,0 +1,25 @@
+# [Contributing guidelines](@id contributing)
+
+First of all, thanks for the interest!
+
+We welcome all kinds of contribution, including, but not limited to code, documentation, examples, configuration, issue creating, etc.
+
+Be polite and respectful, and follow the code of conduct.
+
+## Bug reports and discussions
+
+If you think you found a bug, feel free to open an [issue](https://github.com/unfoldtoolbox/Unfold.jl/issues).
+Focused suggestions and requests can also be opened as issues.
+Before opening a pull request, start an issue or a discussion on the topic, please.
+
+## Working on an issue
+
+If you found an issue that interests you, comment on that issue what your plans are.
+If the solution to the issue is clear, you can immediately create a pull request (see below).
+Otherwise, say what your proposed solution is and wait for a discussion around it.
+
+!!! tip
+    Feel free to ping us after a few days if there are no responses.
+
+If your solution involves code (or something that requires running the package locally), check the [developer documentation](91-developer.md).
+Otherwise, you can use the GitHub interface directly to create your pull request.

docs/src/91-developer.md

@@ -0,0 +1,138 @@
+# [Developer documentation](@id dev_docs)
+
+!!! note "Contributing guidelines"
+    If you haven't, please read the [Contributing guidelines](90-contributing.md) first.
+
+If you want to make contributions to this package that involves code, then this guide is for you.
+
+## First time clone
+
+!!! tip "If you have writing rights"
+    If you have writing rights, you don't have to fork. Instead, simply clone and skip ahead. Whenever **upstream** is mentioned, use **origin** instead.
+
+If this is the first time you work with this repository, follow the instructions below to clone the repository.
+
+1. Fork this repo
+2. Clone your repo (this will create a `git remote` called `origin`)
+3. Add this repo as a remote:
+
+   ```bash
+   git remote add upstream https://github.com/unfoldtoolbox/UnfoldMixedModels.jl
+   ```
+
+This will ensure that you have two remotes in your git: `origin` and `upstream`.
+You will create branches and push to `origin`, and you will fetch and update your local `main` branch from `upstream`.
+
+## Linting and formatting
+
+Install a plugin on your editor to use [EditorConfig](https://editorconfig.org).
+This will ensure that your editor is configured with important formatting settings.
+
+We use [https://pre-commit.com](https://pre-commit.com) to run the linters and formatters.
+In particular, the Julia code is formatted using [JuliaFormatter.jl](https://github.com/domluna/JuliaFormatter.jl), so please install it globally first:
+
+```julia-repl
+julia> # Press ]
+pkg> activate
+pkg> add JuliaFormatter
+```
+
+To install `pre-commit`, we recommend using [pipx](https://pipx.pypa.io) as follows:
+
+```bash
+# Install pipx following the link
+pipx install pre-commit
+```
+
+With `pre-commit` installed, activate it as a pre-commit hook:
+
+```bash
+pre-commit install
+```
+
+To run the linting and formatting manually, enter the command below:
+
+```bash
+pre-commit run -a
+```
+
+**Now, you can only commit if all the pre-commit tests pass**.
+
+## Testing
+
+As with most Julia packages, you can just open Julia in the repository folder, activate the environment, and run `test`:
+
+```julia-repl
+julia> # press ]
+pkg> activate .
+pkg> test
+```
+
+## Working on a new issue
+
+We try to keep a linear history in this repo, so it is important to keep your branches up-to-date.
+
+1. Fetch from the remote and fast-forward your local main
+
+   ```bash
+   git fetch upstream
+   git switch main
+   git merge --ff-only upstream/main
+   ```
+
+2. Branch from `main` to address the issue (see below for naming)
+
+   ```bash
+   git switch -c 42-add-answer-universe
+   ```
+
+3. Push the new local branch to your personal remote repository
+
+   ```bash
+   git push -u origin 42-add-answer-universe
+   ```
+
+4. Create a pull request to merge your remote branch into the org main.
+
+### Branch naming
+
+- If there is an associated issue, add the issue number.
+- If there is no associated issue, **and the changes are small**, add a prefix such as "typo", "hotfix", "small-refactor", according to the type of update.
+- If the changes are not small and there is no associated issue, then create the issue first, so we can properly discuss the changes.
+- Use dash separated imperative wording related to the issue (e.g., `14-add-tests`, `15-fix-model`, `16-remove-obsolete-files`).
+
+### Commit message
+
+- Use imperative or present tense, for instance: *Add feature* or *Fix bug*.
+- Have informative titles.
+- When necessary, add a body with details.
+- If there are breaking changes, add the information to the commit message.
+
+### Before creating a pull request
+
+!!! tip "Atomic git commits"
+    Try to create "atomic git commits" (recommended reading: [The Utopic Git History](https://blog.esciencecenter.nl/the-utopic-git-history-d44b81c09593)).
+
+- Make sure the tests pass.
+- Make sure the pre-commit tests pass.
+- Fetch any `main` updates from upstream and rebase your branch, if necessary:
+
+  ```bash
+  git fetch upstream
+  git rebase upstream/main BRANCH_NAME
+  ```
+
+- Then you can open a pull request and work with the reviewer to address any issues.
+
+## Building and viewing the documentation locally
+
+Following the latest suggestions, we recommend using `LiveServer` to build the documentation.
+Here is how you do it:
+
+1. Run `julia --project=docs` to open Julia in the environment of the docs.
+1. If this is the first time building the docs
+   1. Press `]` to enter `pkg` mode
+   1. Run `pkg> dev .` to use the development version of your package
+   1. Press backspace to leave `pkg` mode
+1. Run `julia> using LiveServer`
+1. Run `julia> servedocs()`