search

robbert-harms / MDT

Microstructure Diffusion Toolbox
GNU Lesser General Public License v3.0
50 stars 18 forks source link

How to compose a new composite model #40

Closed StefaniaOliviero closed 3 years ago

StefaniaOliviero commented 3 years ago

Dear Robbert, I am composing a new model, by adding the description of my model in a file .py in the folder .mdt/1.2.6/components/user/composite_models. I need to know some things: 1) once I did this, what else have I to do to make my new model available? 2) In modeling the signal I would like to introduce the T1 or T2 decay: I found that in the model TimeDependentActiveAx, (maybe) such dependence appears in the function "ExpT1DecTM_simple": where is the description of such a function? 3) In the file free.py, in the folder .mdt/1.2.6/components/standard/parameters, there is the description of T1: class T1(FreeParameterTemplate):

init_value = 0.05
lower_bound = 1e-5
upper_bound = 4.0
parameter_transform = ScaleTransform(1e4)

How does the ScaleTransform mean? Which is the unit, s*10(-4))? For example, a T1 of 500 ms is in the described range?

Thanks a lot for your precious answers.

robbert-harms commented 3 years ago

Hi Stefania,

For completeness sake I provide my answers also here on Github:

To answer your questions:

  1. when you add models to the folder .mdt/.../components/user/composite_models it will be picked up next time you start MDT. If you are using the GUI you have to restart it, if you are using iPython you have to reload the MDT library, if you are using command line it should just pick it up. Typically, if it doesn't pick it up there is something wrong with the model.

  2. MDT was originally based on the premise of multi-compartment models for modelling diffusion MRI signal. As such, the basic components in MDT are "compartments" which, when defined, can be freely mixed into (multi-compartment) models. The compartments were initially items such as "Tensor", "Ball", "Cylinder", "Stick" etc., following the definitions from Basser, Zhang and other early dMRI modellers. Later scientific work experimented with T1 and T2 decay in the dMRI models. Adding this to MDT was easy by defining T1 and T2 decays as additional "compartments", and mixing these in with the multi-compartment models. This works, although at the expense of naming clarity, since T1 and T2 decays are not compartments as defined in multi-compartment dMRI models.

To give an example, the ActiveAx model is defined as such:

model_expression = ''' S0 ((Weight(w_csf) Ball) + (Weight(w_ic) CylinderGPD) + (Weight(w_ec) Zeppelin)) '''

Meaning we have the Ball, CylinderGPD and Zeppelin compartments (these are well-defined dMRI compartments) mixed together using weights and S0 for the unweighted signal.

If you want to add T1 decay to that, you could change it to:

model_expression = ''' S0 ExpT1DecTM_simple ((Weight(w_csf) Ball) + (Weight(w_ic) CylinderGPD) + (Weight(w_ec) * Zeppelin)) '''

And voila, you have T1 decay in the ActiveAx model.

Have a look at the file ".mdt//components/standard/compartment_models/relaxometry.py for an overview of available decay models.

The decay constants are adding as an additional free parameter. These can be fixed using provided methods. Please see the documentation for that.

  1. The parameter transform is used by MDT to scale parameters just prior to optimization, and scale back again for presentation. To the users, MDT uses SI units and you should provide the T1 in seconds. To the optimization routine, MDT scales it such that the ranges of all parameters are approximately equivalent. Optimization routines struggle if one parameter is defined between 0.01 and 0.10 and another between 3000 and 6000 (S0 for example). Scaling helps to put everything in perspective.

Best,

Robbert