A modular design matrix toolbox

[TimVanMourik]

A Modular Design Matrix Toolbox

Cool acronym to be determined

Project Description

Have you ever created a design matrix and had trouble with adding this one custom regressor? Or adding SPM motion parameters to an FSL design? Or how to orthogonalise some specific regressors, but not the other ones?

Traditional GUIs try to construct design matrices all at once, leaving little room for customisation. Wouldn't it be great to build a GLM design piece by piece, like stacking up Lego bricks? This project is about making such a toolbox.

My proposal is to make a toolbox with which you can connect little pieces of the design to build the full design. I started this at some point by making a dozen components as MATLAB functions that can be connected. This is part of my own code toolbox, but I would like the design matrix to be a separate toolbox, ideally reimplemented in Python.

Goals

Main goals

• Think about the minimal needs for specifying a design matrix (e.g., time unit, regressor specification, etc.).
• Implement a structure (e.g., Python class, file type) to put this into code
• Think of several components that could be implemented (e.g., see these MATLAB functions)

Stretch goals

• Write compatibility functions to SPM, FSL, etc. to export the design to use it in standard pipelines.
• Write design matrix modules for all existing SPM/FSL functionality
• Implement different HRF shapes for the toolbox.
• Thinking about first and second level designs.

Blue sky goals

Connect it to a visual editor such as GiraffeTools to edit and save the design in an open format:

Skills required to participate

• Some knowledge of GLMs (ideally at least on expert on the team)
• Basic Python or interested to learn it. Ideally one Python expert to do the toolbox overhead.
  • As each function can be considered separately (=modular), this is a really good project to hop on if you're a Python beginner.

Integration

The stretch goals and blue sky goals target to provide incremental compatibility and integration with existing software and online visualisation and communication.

Preparation material

• Read up on your GLM basics! :)
• A start of this idea in MATLAB: https://github.com/TimVanMourik/OpenFmriAnalysis/tree/master/Interface/DesignMatrix

Link to your GitHub repo

Non-existent yet.

Communication

Brainhack slack for now. I'll make a dedicated channel or workspace as soon as there's a team.

Additional information

I might be somewhat busy as I'm also organising the OHBM Open Science Room. I can't fully commit to this project just yet, but I'll definitely help out during the Hackathon. I'm completely fine with someone else taking the lead on this.

[PeerHerholz]

Sounds awesome @TimVanMourik! I do think that a close collaboration with the BIDS Stats-Models Specification would be great, no? What do you think (@tyarkoni)?

Rather something for the stretch goals, but hopefully still interesting and useful:

• nipype sparse model functionality from @tylerler & @satra based on their corresponding paper
• python implementation of GLMdenoise from @Charestlab (originally a Matlab toolbox from @kendrickkay described here & in the respective paper)

[effigies]

It would definitely be great if this were able to either emit or accept a BIDS Stats-Models transform sequence.

[TimVanMourik]

Thanks @PeerHerholz, @effigies for the suggestions (pinging @tyarkoni for his BIDS Stats-Models)!

I've always understood BIDS as a data specification, not as a pipeline specification and BIDS-SM is blurring that line a bit. You're absolutely right that the essence is pretty identical to BIDS-SM transform sequence. I suppose the difference is that my suggestion is not so BIDS centric and prescriptive in the nature of exact specs, but rather focusses on the modularity of functions. They're different in focus, rather than different in fundamentals, so conversion of one into the other should be possible!

[effigies]

I agree with all you've written. It would be very good for what you have not to be tied too tightly to BIDS, but if we can have I/O conversions with stats models, this could be very advantageous to the spec and the ecosystem. In particular, it will help us figure out what things in the spec are too tightly coupled to the pybids data model, which is a worry for multiple implementations (making the spec a retrospective description of the software, as opposed to a tooling-independent specification). To extend that a bit further, a MATLAB tool that ingests BIDS-SM and produces a design matrix is what I see as the biggest roadblock for SPM support for BIDS-SM.

[tyarkoni]

There's a project called Portable Format for Analytics (PFA) that does everything the BIDS transformations were intended to do and much, much, more. It's worth looking into that before building something new from scratch. I intend to eventually replace all the transformation functionality in PyBIDS with PFA's implementation in Titus. The (big) downside is that PFA is no longer under active development, and was never very wisely used (a shame, because it's an amazing project).

[effigies]

never very wisely used

They recursed too greedily, and too deep.

[tyarkoni]

Also, @TimVanMourik, have you looked at the PyBIDS Analysis module? It doesn't do any exporting to other formats right now, but that would be easy to add. Given a BIDS dataset, it makes it quite straightforward to generate a design matrix based on arbitrary transformations applied to arbitrary BIDS variables.

[TimVanMourik]

I'm concerned this thread won't be understandable for newcomers anymore because we're about to recurse too greedily, and too deep 🙃

I did not. It looks like a brilliant basis of what I'm proposing, with the caveat that I'm inclined to build something BIDS-agnostic because of aforementioned reasons.

[PeerHerholz]

Sorry, I didn't mean to start a super in depth discussion nor suggesting some sort of BIDS dependency. I rather meant something along the lines of having an interface or functionality that can read, process and export BIDS(-SM) compatible information (comparable to your thoughts @effigies & @TimVanMourik), but of course with the same functionality for FSL, SPM, AFNI, nistats, etc. .

[tyarkoni]

I'd definitely support building something as general as possible. FWIW, the PyBIDS implementation is largely independent of BIDS. There's a variables module that contains tools for representing data in sparse and dense formats, and an analysis module that contains tools for design matrix construction etc. The former is almost completely independent of BIDS once variables are read in (there might be a few small things to fix, e.g., getting the TR). The latter is more dependent on a BIDS-StatsModels input, but most of the machinery could be fairly easily abstracted to work without it. So that might be a good starting point. I'd definitely support breaking that stuff out into its own package, generalizing it, and adding a lightweight wrapper around it in PyBIDS for the BIDS-specific stuff. Would be happy to chat about/work on this at the hackathon.

(Also, not to hijack the thread entirely, but a separate and lower-hanging possibility would be to add FSL, AFNI, SPM etc. exporters to the pybids Analysis class; that would be quite trivial, and would mean that you could immediately generate event files/DMs for any of those packages given a BIDS dataset.)