Core Module

This is the core module of the toolbox, containing frequently used classes and functions.

Main Function

core.GenRBModel(name1, value1, name2, value2 ...)

Description:

GenRBModel is the main function in the ROMEG toolbox. It will generate a FOM.mat object and RBModel.mat object in the Results/ folder. These are the full order and reduced order head models respectively. Simply running this function will generate example models but the function comes with many name-value pair options that can be used to tailor the head model. See below for the arguments to this function. After running this function, you are encouraged to run the inverse problem. For guidance with this type: help GenInverse.

Requirements:

A small sized cluster (50 cores ~ 1 large cpu node),
MATLAB R2021a or later,
Statistics and Machine Learning Toolbox.

Parameters:

model – path to head model you want to use. Must contain p,t,f.
mu_min – array of minimum conductivities in order of head tissue.
mu_max – array of maximum conductivities in order of head tissue.
nic – number of beta interpolation points.
anis_tan – array of tissue numbers to tag with tangential conductivity.
anis_rad – array of tissue numbers to tag with radial conductivity.
angles – true if model contains theta values (default: false)
current – injection current used.
tolGREEDY – The minumum error tolerance the greedy algorithm will stop at.
Nmax – The maximum number of snapshots. If specified with tolGREEDY, the algorithm will stop at which ever value is reached first. Recommended < 300.
use_sinks – (boolean) would you like to use the sinks.mat file for injection patterns. default = true
complim – the limit on the number of nodes used at one time on the cluster
use_FOM – is there an existing FOM to look for instead of making a new one.
debug – (boolean) turn debug mode on
Cluster – is there a compute cluster running SLURM accessible
pre_stiff – are the stiffness matrices already in the model.mat file?

Examples

This will create an RBModel with the max and min conductivites specified, with appropriate stopping conditions. The nuber of beta interpolation points will be 100 and ROM will be trained according to the injection pattern file provided. There will alse be a limit of 60 jobs allowed to run in parallel.

GenRBModel(‘model’,model,’mu_min’,mu_min,’mu_max’,mu_max,’tolGREEDY’,… 5e-10,’Nmax’,200,’use_sinks’,true,’nic’,100,’complim’,60)

This will create an RBModel similar to above but where the second layer is isotropic, meaning parameters 2 and 3 are the tangential and radial conductivities for this layer and where the model contains the necessary angle values for the computation.

GenRBModel(‘model’,model,’mu_min’,mu_min,’mu_max’,mu_max,’tolGREEDY’,… 5e-8,’Nmax’,100,’use_sinks’,true,’nic’,80,’anis_tan’,3,… ‘anis_rad’,2,’angles’,true,’complim’,60)

Classes

class core.ROMClass(name1, value1, name2, value2 ...)

Bases: core.OrderedModelClass

Constructor Summary

ROMClass(name1, value1, name2, value2 ...)

Description:: A class object containing the information and functions needed to produce the RBModel. Please use the GenRBModel function to generate the RBModel. Although feel free to use this constructor function for debugging purposes or if using a pre-calculated stability factor interpolant.

Parameters:

electrode – (essential) The number of the desired injection electrode
current – The injection current in Amps.
tolGREEDY – The minumum error tolerance the greedy algorithm will stop at.
Nmax – The maximum number of snapshots. If specified with tolGREEDY, the algorithm will stop at which ever value is reached first.
top – Path to top of ROMEG tree

Property Summary

Nmax: default value for Nmax=30

current: injection current

tolGREEDY: default value for tolGREEDY = 5e-5

Method Summary

cleanROM(): Some cleaning

popFields(): Populate the ROMClass object fields from the arguments.

solvePrelim(FOM): Electrode matrix

class core.FOMClass(p, t, f, name1, value1, name2, value2 ...)

Bases: core.OrderedModelClass

Constructor Summary

FOMClass(p, t, f, name1, value1, name2, value2 ...)

Description:: A class object for the construction of the full order model. Needed for the construction of the Reduced order model in made by using ROMClass. Please use the GenRBModel function to generate this class object although feel free to use this for debugging purposes. See below for arguments.

Parameters:

model – path to head model you want to use. Must contain p,t,f.
mu_min – array of minimum conductivities in order of head tissue.
mu_max – array of maximum conductivities in order of head tissue.
nic – number of beta interpolation points.
anis_tan – array of tissue numbers to tag with tangential conductivity.
anis_rad – array of tissue numbers to tag with radial conductivity.
current – injection current used.

Method Summary

buildFOM(): FOM(p,t,f,mu_min,value,mu_max,value,anis_tan,value,anis_rad,value,nic,value)

computeMuTrain(): Compute a positive RBF interpolant of the stability factor

static loadFOM(top)

Description:: Load a previously constructed Full Order Model object from the Results/ folder.

Parameters:: top – path to top of ROMEG tree

class core.RBModelClass

Bases: core.OrderedModelClass

Constructor Summary

RBModelClass(varargin): obj = obj.processArgs(varargin);

Method Summary

saveROM(top)

Description:: A function to save the reduce order model as RBModel.mat in the Results/ folder.

Parameters:: top – Path to the top of the ROMEG tree

class core.OrderedModelClass

Property Summary

Cluster: is ROM being run on the cluster

Ind_E: Tetrahedron number related to electrode

angles: true if model contains theta values (default: false)

close: see patterns function

cmdLevel: level of output for cmd logging, default is info

debug: (boolean) turn debug mode on for logs with ‘true’

electrodes: list of injection electrodes for sink patterns

logLevel: level of logging for the log files, defualt is info

model: path to model

new_sinks: (boolean) use a new set of sinks called new_sinks.mat

num_patterns: number of injection patterns

num_sinks: number of current sinks in the injection pattern

out: extraction electrodes

pre_stiff: are the stiff mats already in head_model file?

sample_num: sample number to use for the inverse problem

sinks: injection and sink patterns for each electrode

sinks_path: path to the sink.mat file

top: path to top of the ROMEG tree

use_sinks: do you want to use the sinks file for ROM/inverse, defualt = true

Method Summary

static EEGFiles(name1, value1, name2, value2, ...)

Parameters:

sample_num – sample number
num_dipoles – number of dipoles being used

checkPaths(name1, value1, name2, value2, ...)

Description:: A function to check that the required directories to save results are present and if not then it creates them.

Parameters:

type – ROM, measurement, inverse
num – sample number (essential if type=measurement,eeg or inverse)
RB_path – path to RB model if NOT in $ROMEG_DATA
num_dipoles – number of dipole folders to set up if using EEG

static makeWeights(name1, value1, name2, value2...)

Description:: A script to make the weights for the measurements on each eelctrode for each injection pattern in the inverse problem.

Parameters:

model – (essential) path to the head model
num_weights – how many current sinks for each injection would you like.
distance – should the weights be a function of distance from the injection electrode.
sinks – matrix containing all the injection patterns

static patterns(name1, value1, name2, value2...)

Description:: Function for making injection patterns with many sinks on the other side of the head model. Default behaviour is for every electrode but the last to be an injection and the last electrode being the extraction. If out is specified then all injection electrodes will have the extraction electrodes that are specified with the injection electrodes matching and of the extraction electordes being removed. For opposite extraction electrodes use the num_sinks option.

Parameters:

model – (essential) path to the head model
num_sinks – how many current sinks for each injection would you like.
elec_height – (optional) a given minimum height the sink electrodes should be on the head model.
electrodes – list of electrodes for injection (defaults to all)
top – (optional if ROMEG_TOP env var has been set) path to the top of the ROMEG tree
out – specific list of extraction electrodes for injection patterns.
new_sinks – are these new sinks being made for inverse
close – select the closest electrodes. Default is furthest away
no_repeats – do not use the same electrodes in opposite patterns

Examples

This example takes a model, with the electrode positions indicated in variable f and specifies 10 sink electrodes for each of the elctrodes listed, resulting in 8 patterns.

OrderedModelClass.patterns(‘model’,model,’num_sinks’,10,… ‘electrodes’,[1,20,35,56,42,120,13,67])

static sensitivityFiles(name1, value1, name2, value2, ...)

Parameters:

num_layers – total number of active layers
recursion – number of layers to use
sample_num – sample number
layers – array of active layers where each row is new active layer set
order – ROM or TRAD?

static setupFiles(name1, value1, name2, value2...)

Description:: Sets up folder structure for results from measurements and inverse runs. If not core then a symbolic link will be formed between the ROM folders.

Parameters:

ROM – (boolean) will this folder contain the RBModel?
RB_path – path to RBModel for sym link if NOT in $ROMEG_DATA