WIP_models

How to add Work In Progress (WIP) models in AMICO

Environment setup

.
└── directory
    └── amicowipmodels.py

# Windows (pwsh)
$env:AMICO_WIP_MODELS = path_to_wip_models

# MacOS/Linux
export AMICO_WIP_MODELS=path_to_wip_models

Template

class MyModel:
    def __init__(self):
        """To define the parameters of the model, e.g. id and name, returned maps, model-specific parameters etc.
        """
        self.id         = 'MyModel'
        self.name       = 'My Model'
        self.maps_name  = []
        self.maps_descr = []

        self.param1 = 0
        self.param2 = 0


    def set(self, param1, param2):
        """For setting all the parameters specific to the model.
        NB: the parameters are model-dependent.
        """
        self.param1 = param1
        self.param2 = param2


    def get_params(self):
        """For getting the actual values of all the parameters specific to the model.
        NB: the parameters are model-dependent.
        """
        params = {}
        params['param1'] = self.param1
        params['param2'] = self.param2
        return params


    def set_solver(self, solver_param1=0, solver_param2=0):
        """For setting the parameters required by the solver to fit the model.
        NB: the parameters are model-dependent.

        Returns
        -------
        params : dictionary
            All the parameters that the solver will need to fit the model
        """
        self.solver_params['solver_param1'] = solver_param1
        self.solver_params['solver_param2'] = solver_param2


    def generate(self, out_path, aux, idx_in, idx_out, ndirs):
        """For generating the signal response-functions and createing the LUT.
        NB: do not change the signature!

        Parameters
        ----------
        out_path : string
            Path where the response function have to be saved
        aux : structure
            Auxiliary structures to perform SH fitting and rotations
        idx_in : array
            Indices of the samples belonging to each shell
        idx_out : array
            Indices of the SH coefficients corresponding to each shell
        ndirs : int
            Number of directions on the half of the sphere representing the possible orientations of the response functions
        """


    def resample(self, in_path, idx_out, Ylm_out, doMergeB0, ndirs):
        """For projecting the LUT to the subject space.
        NB: do not change the signature!

        Parameters
        ----------
        in_path : Scheme class
            Acquisition scheme of the acquired signal
        idx_out : array
            Indices of the samples belonging to each shell
        Ylm_out : array
            SH bases to project back each shell to signal space
        doMergeB0: bool
            Merge b0-volumes into a single volume if True
        ndirs : int
            Number of directions on the half of the sphere representing the possible orientations of the response functions

        Returns
        -------
        KERNELS : dictionary
            Contains the LUT and all corresponding details. In particular, it is
            required to have a field 'model' set to "self.id".
        """


    def fit(self, evaluation):
        """For fitting the model to the data.
        NB: do not change the signature!

        Parameters
        ----------
        evaluation: amico.core.Evaluation
            AMICO Evaluaton instance

        Returns
        -------
        estimates: np.ndarray
            Scalar values eastimated in each voxel
        rmse: np.ndarray (optional)
            Fitting error (Root Mean Square Error)
        nrmse: np.ndarray (optional)
            Fitting error (Normalized Root Mean Square Error)
        y_corrected: np.ndarray (optional)
            Corrected DWI (only FreeWater model)
        estimates_mod: np.ndarray (optional)
            Modulated maps (only NODDI model)
        """