-
Notifications
You must be signed in to change notification settings - Fork 7
8. Usage
After installing Magia as well as its dependencies, you are ready to start using Magia. The main function run_magia requires three input parameters: subject_id, specs, and modeling_options. After they have been properly specified, and the image files are in place, you can use Magia with simply run_magia(subject_id,specs,modeling_options).
Please note that lowercase characters should be used in all strings.
The input argument subject_id is a string variable informing Magia which PET data the user wants to process. The directory getenv('DATA_DIR') must have a subdirectory whose name matches the subject_id, and the PET data must be properly organized within the subfolder. You can check if Magia finds your data using magia_check_found. Your data are properly organized, if the function returns 1.
The input argument specs is a struct variable consisting of two other structs: study and magia. Please see the files under the folder 'examples' for examples of properly specified specs. You can read in the specs to MATLAB using the function magia_read_specs, and write new specs to the disk using the function magia_write_specs.
The struct specs.study is a description of the PET study and the subject. It consists of the following fields:
tracer (string, necessary field) Defines the radiotracer that was used in the study. It must be named following these examples: [11c]carfentanil, [11c]raclopride, [18f]fdg, [18f]fmpep-d2, [11c]pib, etc.
frames (string, necessary field) Defines the frames that were used. The start and end times of the frames are given, with respect to injection time. The frames must be defined following these examples:
- 0 1;1 2;2 3;3 6;6 9;9 12;12 15;15 21;21 27;27 33;33 39;39 45;45 51
- 60 90
dose (number, needed for SUV-conversion) The injected dose in MBq.
weight (number, needed for SUV-conversion) The mass of the subject at the time of the scan, in kilograms.
mri_code (string, needed if MRI is used either to define ROIs or to estimate the MNI-transformation) Defines the MRI study that should be used in the analysis. A folder matching the mri_code must be found in getenv('MRI_DIR'). Please look into here for instructions concerning the organisation of MRI files
glucose (number, needed for GU-conversion in FDG-studies) Defines the average glucose concentration (mmol/l) in plasma from the injection until the end of the brain scan. Note that this field is necessary if gu = 1 (see below). If you do not know the glucose concentration, please set gu = 0.
The struct specs.magia describes how Magia should process the study. It consists of the following fields:
model (string, necessary) Defines how the PET data should be modelled. Magia currently supports the following models:
- suv
- srtm
- logan
- logan_ref
- patlak
- patlak_ref
- ma1
- fur
- suvr
- two_tcm (for ROI-level data only)
dc (binary, necessary) Defines whether the PET data have already been decay-corrected to injection time. If yes, dc = 1; if no, dc = 0. If the data have not been decay-corrected to injection time, Magia will assume that the data have however been corrected to the scan start time, and then apply the correction from the scan start time to injection time. Information about the delay between scan start time and injection time is carried in the definition of the frames.
rc (binary, necessary, 0 by default) Defines whether Magia should apply ROI-correction (rc) to the ROIs. If the user wants to use the ROI-correction, then rc = 1, otherwise rc = 0. In ROI-correction, voxels in each ROI are clustered into three clusters that are functionally more homogenous than the original ROI. Then cluster-specific mean radioactivities are calculated. Finally, the voxels belonging to the cluster with lowest radioactivity are dropped from the ROI. This procedure makes the ROIs less likely to contain voxels outside brain tissue. It also makes the ROIs follow the PET signal more closely. Also humans typically delineate ROIs using information from both MR and PET images, and thus the corrected ROIs may more closely reflect human-drawn ROIs. In practice, the ROI-correction makes the PET-derived outcome measures positively biased (compared to not using it). However, this bias is often meaningful because the correction makes the ROIs more likely to contain signal only from the brain (and not e.g. from the ventricles). Note that this correction is independent of the correction applied to the reference regions.
cut_time (nonnegative number, necessary, 0 by default) Sometimes the user may not want to use data until the very and of the scan (e.g. when comparing how scan duration influences modelling). The frames that end after cut_time will be excluded from the analysis. The default value of 0 means that all frames should be used.
roi_type (either 'atlas' or 'freesurfer'; necessary) Defines whether the ROIs should be defined using an MNI atlas or FreeSurfer. If you have a high-quality MRI of the subject's brain, then it is highly recommended to use FreeSurfer-based ROIs. However, FreeSurfer may have trouble with MRIs if the contrast between grey and white matter is poor. In such cases, atlas-based ROIs may have to be used.
roi_set (string, necessary if roi_type = 'freesurfer') Defines the FreeSurfer-based ROI set that should be used. The function magia_get_freesurfer_roi_info lists the available ROI sets. Note that if you want to define new ROI sets, the ROIs must be entered in alphabetical order, otherwise the ROI labels will be mixed up.
mni_roi_mask_dir (string, necessary if roi_type = 'atlas') Defines the atlas-based ROIs that should be used. The variable should point to a directory that contains binary masks whose filename reflects the anatomical label.
input_type (either 'plasma', 'blood', 'plasma&blood', 'ref' or 'sca_ref'; necessary) Defines the type of input that should be used in the analysis. Note that the input must match the model. For example, SRTM requires either 'ref' or 'sca_ref' as input type. The function magia_match_input_to_model will check if the input matches the model, and if they are not consistent, Magia will assume that the model has been properly specified and the input_type will be changed.
fwhm_pre (nonnegative number, necessary if parametric images are calculated, i.e. if cpi = 1; defaults to 4) Defines the width of the Gaussian kernel that is used the spatially smooth the PET data prior to calculation of parametric images. The smoothing is recommended to increase the signal-to-noise ratio of the voxel-level time-activity curves.
fwhm_post (nonnegative number, necessary if parametric images are calculated, i.e. if cpi = 1; defaults to 6) Defines the width of the Gaussian kernel that is used the spatially smooth the parametric images after spatial normalization. The smoothing is recommended to account for individual differences in brain size and shape.
fwhm_roi (nonnegative number, necessary, defaults to 0) Magia enables the user to enlargen the ROIs prior to extraction of ROI-specific time-activity curves. The enlargement is done by first smoothing the binary masks, after which the resulting image is thresholded. The parameter fwhm_roi defines the width of the Gaussian kernel that is used to spatially smooth the masks.
cpi (binary, necessary, defaults to 1) Acronym standing for 'calculate parametric images'. Describes whether Magia should (cpi = 1) or should not (cpi = 0) calculate parametric images.
norm_method (either 'mri' or 'pet'; necessary if cpi = 1 or if roi_type = 'atlas') Defines whether spatial normalization should be done via MRI (SPM's segmentation routine) or via PET (to a tracer-specific radioactivity template). The MRI-based spatial normalization is recommended whenever a suitable MRI is available for the subject.
template (necessary if norm_method = 'pet') Specifies absolute path of the template which is used to spatially normalise the parametric images. The template is tracer-dependent. Note that the MNI-transformation is estimated using the mean radioactivity images of the study, and thus the templates must be radioactivity images rather than outcome images (such as BPND or Ki).
mc_excluded_frames (a list of numbers, defaults to empty) Defines which frames should be excluded from the motion-correction. It is not unusual that the first frame is not properly reconstructed due to too low count number. In such cases, if the first frame is not removed from the frame-realignment process, it is possible that significant portions of the brain gets masked out in the process. In these cases, setting mc_excluded_frames = 1 will likely help.
mc_fwhm (a nonnegative number, defaults to 7) Defines the width of the smoothing kernel that is used in the motion-correction process.
mc_rtm (binary, defaults to 1) Defines whether the motion-correction should be done in two steps.
mc_ref_frame (a nonnegative number, defaults to 0) Defines the frame to which all other frames are aligned to. The default value of 0 means that the a frame from the middle of the scan (frame number given by ceil(size(images,1)/2)) is used as the reference frame.
gu (binary, needed if Ki's or FUR's need to be converted to GU's, defaults to 0) Defines whether Magia should automatically convert the Ki values (from Patlak) or FUR-values into glucose uptake -estimates. If yes, gu = 1, otherwise gu = 0. This is basically relevant only for FDG-studies.
classfile (string, needed if ref_type = 'sca_ref') Specifies a set of predefined kinetic tissue class TACs describing the average kinetics of the radioligand in different types of brain tissue (gray matter, white matter, blood pool & high specific binding). This set of TACs is used in supervised cluster analysis for extracting reference tissue input curves (J Cereb Blood Flow Metab. 2012 Aug;32(8):1600-8. doi: 10.1038/jcbfm.2012.59. Epub 2012 May 16).
The input argument modeling_options is a struct variable that always includes the field model. In addition, it contains model-specific parameters. Please see the files under the folder 'examples' for examples of properly specified modeling options. You can and write new modeling options to the disk using the function magia_write_modeling_options.
SRTM has different functions for fitting ROI-level and voxel-level data. The ROI-level fitting is done using an iterative approach described by Oikonen & Sederholm in Model equations for reference tissue compartmental models. DOI: 10.13140/2.1.1869.3127. The voxel-level fitting is done using a basis-functions implementation, as described by Gunn and colleagues in a NeuroImage paper Parametric Imaging of Ligand-Receptor Binding in PET Using a Simplified Reference Region Model.
SRTM has the following model-specific fields:
lb Applicable to ROI-level fitting. A vector of length 3 defining the lower boundaries for the parameter estimates R1, k2, and BP.
ub Applicable to ROI-level fitting. A vector of length 3 defining the upper boundaries for the parameter estimates R1, k2, and BP.
theta3_lb Applicable to voxel-level fitting. Defines the lower boundary for the linearisation parameter theta3.
theta3_ub Applicable to voxel-level fitting. Defines the upper boundary for the linearisation parameter theta3
nbases Applicable to voxel-level fitting. Defines the number of basis functions used.
Logan has the following model-specific fields:
start_time Specifies the start time for Logan plot analysis. Frames that begin at or after the parameter are included in Logan plot.
end_time Specifies the end time for Logan plot analysis. Frames that extend outside this parameter are excluded from the line fitting. If end_time = 0, the fitting is done until the end of the scan.
Logan_ref has the following model-specific fields:
start_time Specifies the start time for Logan plot analysis. Frames that begin at or after the parameter are included in Logan plot.
end_time Specifies the end time for Logan plot analysis. Frames that extend outside this parameter are excluded from the line fitting. If end_time = 0, the fitting is done until the end of the scan.
refk2 Specifies the reference region k2 that should be used to correct for the time-dependence of the ROI/reference ROI -ratio. Typically a population-based tracer-dependent average is used.
MA1 has the following model-specific fields:
start_time Specifies the start time for the analysis. Frames that begin at or after the parameter are used in model fitting.
end_time Specifies the end time for the analysis. Frames that extend outside this parameter are excluded from the model fitting. If end_time = 0, the fitting is done until the end of the scan.
Patlak has the following model-specific fields:
start_time Specifies the start time for Patlak plot analysis. Frames that begin at or after the parameter are included in Patlak plot.
end_time Specifies the end time for Patlak plot analysis. Frames that extend outside this parameter are excluded from the line fitting. If end_time = 0, the fitting is done until the end of the scan.
Patlak has the following model-specific fields:
start_time Specifies the start time for Patlak plot analysis. Frames that begin at or after the parameter are included in Patlak plot.
end_time Specifies the end time for Patlak plot analysis. Frames that extend outside this parameter are excluded from the line fitting. If end_time = 0, the fitting is done until the end of the scan.
Magia calculates time-integrals of target-region and reference-region time-activity curves, and defines SUV-ratio as the target-to-reference ratio. SUVR has the following model-specific fields:
start_time Specifies the start time for the analysis. Frames that begin at or after the parameter are included in the analysis.
end_time Specifies the end time for the analysis. Frames that extend outside this parameter are excluded from the analysis. If end_time = 0, the SUV-ratio is calculated until the end of the scan.
FUR has the following model-specific fields:
start_time Specifies the start time for the analysis. Frames that begin at or after the parameter are included in the analysis.
end_time Specifies the end time for the analysis. Frames that extend outside this parameter are excluded from the analysis. If end_time = 0, the SUV-ratio is calculated until the end of the scan.
ic FUR provides biased estimates compared to Patlak-based Ki-estimates. The bias depends on the intercept of the Patlak-plot, as explained here. In traditional FUR-analysis, ic = 0. However, the bias between Patlak-based Ki's and FURs can be decreased by using a population-based intercept as the ic.
Two-tissue compartment model is currently only available for fitting ROI-level data. Its use in voxel-level analysis is prohibited because, with some tracers, even the ROI-level time-activity curves are too noisy for a model with so many parameters that need to be estimated.
Magia parametrises the model with the following parameters: k1, k1/k2, k3, k3/k4, and vb. Because '/' is an invalid character for MATLAB variables, k1/k2 and k3/k4 are referred to as k1k2 and k3k4, respectively.
Two-tissue compartment model has the following model-dependent fields:
k1_lb Specifies the lower boundary for the parameter k1.
k1k2_lb Specifies the lower boundary for the parameter k1/k2.
k3_lb Specifies the lower boundary for the parameter k3.
k3k4_lb Specifies the lower boundary for the parameter k3/k4.
vb_lb Specifies the lower boundary for the parameter vb.
k1_ub Specifies the upper boundary for the parameter k1.
k1k2_ub Specifies the upper boundary for the parameter k1/k2.
k3_ub Specifies the upper boundary for the parameter k3.
k3k4_ub Specifies the upper boundary for the parameter k3/k4.
vb_ub Specifies the upper boundary for the parameter vb.
AIVO database makes use of Magia more convenient, as the user can feed in all the relevant metadata about the study, as well as the preferred processing specifications to the database. After the information has been filled in AIVO, the user can use Magia with simply run_magia(subject_id). Magia will take care of reading the specs and modeling_options from AIVO.