def output_report(wsp, report=None):
"""
Create report pages from output data
:param wsp: Workspace object containing output
"""
if report is None:
report = wsp.report
roi = wsp.rois.mask.data
if wsp.structural.struc is not None:
gm = reg.struc2asl(wsp, wsp.structural.gm_pv).data
wm = reg.struc2asl(wsp, wsp.structural.wm_pv).data
for oxasl_name, multiplier, calibrate, units, normal_gm, normal_wm in OUTPUT_ITEMS.values(
):
name = oxasl_name + "_calib"
img = getattr(wsp, name)
if img is None:
name = oxasl_name
img = getattr(wsp, name)
if img is not None and img.ndim == 3:
page = report.page(name)
page.heading("Output image: %s" % name)
if calibrate and name.endswith("_calib"):
alpha = wsp.ifnone(
"calib_alpha", 1.0 if wsp.asldata.iaf in ("ve", "vediff")
else 0.85 if wsp.asldata.casl else 0.98)
page.heading("Calibration", level=1)
page.text("Image was calibrated using supplied M0 image")
page.text("Inversion efficiency: %f" % alpha)
page.text("Multiplier for physical units: %f" % multiplier)
page.heading("Metrics", level=1)
data = img.data
table = []
table.append([
"Mean within mask",
"%.4g %s" % (np.mean(data[roi > 0.5]), units), ""
])
if wsp.structural.struc is not None:
table.append([
"GM mean",
"%.4g %s" % (np.mean(data[gm > 0.5]), units), normal_gm
])
table.append([
"Pure GM mean",
"%.4g %s" % (np.mean(data[gm > 0.8]), units), normal_gm
])
table.append([
"WM mean",
"%.4g %s" % (np.mean(data[wm > 0.5]), units), normal_wm
])
table.append([
"Pure WM mean",
"%.4g %s" % (np.mean(data[wm > 0.9]), units), normal_wm
])
page.table(table, headers=["Metric", "Value", "Typical"])
page.heading("Image", level=1)
page.image(
"%s_img" % name,
LightboxImage(img,
zeromask=False,
mask=wsp.rois.mask,
colorbar=True))
def get_rois(wsp):
"""
Generate ROIs for GM and noise
Existing ROIs may be provided. If provided in structural space, the ASL data is registered
to the structural image and the ROIS will be transformed to ASL space
If (either) of the noise or GM ROIs are not provided they are automatically generated as follows
- Grey matter: From segmentation of structural image (via FAST or FSL_ANAT output if provided)
- Noise: By inverting brain mask from brain-extracted structural image
A structural image is therefore required if either ROI needs to be generated, or if either ROI
is supplied in structural space.
Optional workspace attributes
-----------------------------
- ``regfrom`` : Reference image for registration of ASL to structural data
- ``asldata`` : Single TI ASL data. Middle volume will be used as reference if ``regfrom`` is required and not set
- ``gm_roi`` : Grey matter ROI in ASL or structural space
- ``noise_roi`` : Noise ROI in ASL or structural space
- ``noise_from_struc`` : If True, existing ``noise_roi`` image is in structural space
- ``gm_from_struc`` : If True, existing ``gm_roi`` image is in structural space
- ``struc`` : Structural image
Workspace attributes set
------------------------
- ``gm_roi`` : Grey matter ROI in ASL space
- ``noise_roi`` : Noise ROI in ASL space
"""
wsp.log.write("Generating ROIs...\n")
if wsp.regfrom is None:
wsp.log.write(" - Reference image for registration not provided - using ASL data middle volume\n")
middle = int(wsp.asldata.shape[3]/2)
wsp.regfrom = Image(wsp.asldata.data[:, :, :, middle], header=wsp.asldata.header)
struc.init(wsp)
if (wsp.gm_roi is None or wsp.noise_roi is None or wsp.noise_from_struc or wsp.gm_from_struc) and wsp.structural.struc is None:
raise RuntimeError("Need to specify a structural image unless you provide both noise and GM ROIs in ASL space")
if wsp.gm_roi is None:
struc.segment(wsp)
wsp.log.write("Taking GM ROI from segmentation of structural image\n")
wsp.gm_roi = Image((wsp.structural.gm_pv.data > 0).astype(np.int), header=wsp.structural.struc.header)
wsp.gm_from_struc = True
if wsp.noise_roi is None:
wsp.log.write("Generating noise ROI by inverting T1 brain mask\n")
wsp.noise_roi = Image(1-wsp.structural.brain_mask.data, header=wsp.structural.struc.header)
wsp.noise_from_struc = True
if wsp.noise_from_struc or wsp.gm_from_struc:
# Need struc->ASL registration space so we can apply to noise and/or GM ROIs
wsp.do_flirt = True
wsp.do_bbr = False
reg.reg_asl2struc(wsp)
if wsp.noise_from_struc:
wsp.log.write(" - Registering noise ROI to ASL space since it was defined in structural space\n\n")
wsp.noise_roi_struc = wsp.noise_roi
wsp.noise_roi = reg.struc2asl(wsp, wsp.noise_roi_struc, interp="nn")
if wsp.gm_from_struc:
wsp.log.write(" - Registering GM ROI to ASL space since it was defined in structural space\n\n")
wsp.gm_roi_struc = wsp.gm_roi
wsp.gm_roi = reg.struc2asl(wsp, wsp.gm_roi_struc, interp="nn")
wsp.log.write("DONE\n\n")
def model_basil(wsp):
"""
Do model fitting on TC/CT or subtracted data
Workspace attributes updated
----------------------------
- ``basil`` - Contains model fitting output on data without partial volume correction
- ``basil_pvcorr`` - Contains model fitting output with partial volume correction if
``wsp.pvcorr`` is ``True``
- ``output.native`` - Native (ASL) space output from last Basil modelling output
- ``output.struc`` - Structural space output
"""
wsp.basil_options = wsp.ifnone("basil_options", {})
basil.basil(wsp, output_wsp=wsp.sub("basil"))
redo_reg(wsp, wsp.basil.finalstep.mean_ftiss)
wsp.sub("output")
output_native(wsp.output, wsp.basil)
output_trans(wsp.output)
# If the user has provided manual PV maps (pvgm and pvgm) then do PVEc, even if they
# have not explicitly given the --pvcorr option
user_pv_flag = ((wsp.pvwm is not None) and (wsp.pvgm is not None))
if (wsp.pvcorr) or (wsp.surf_pvcorr) or user_pv_flag:
# Partial volume correction is very sensitive to the mask, so recreate it
# if it came from the structural image as this requires accurate ASL->Struc registration
if wsp.rois.mask_src == "struc":
wsp.rois.mask_orig = wsp.rois.mask
wsp.rois.mask = None
mask.generate_mask(wsp)
if wsp.pvcorr or user_pv_flag:
# Do partial volume correction fitting
#
# FIXME: We could at this point re-apply all corrections derived from structural space?
# But would need to make sure corrections module re-transforms things like sensitivity map
# Prepare GM and WM partial volume maps from FAST segmentation
if user_pv_flag:
wsp.log.write("\nUsing user-supplied PV estimates\n")
wsp.structural.wm_pv_asl = wsp.pvwm
wsp.structural.gm_pv_asl = wsp.pvgm
else:
struc.segment(wsp)
wsp.structural.wm_pv_asl = reg.struc2asl(
wsp, wsp.structural.wm_pv)
wsp.structural.gm_pv_asl = reg.struc2asl(
wsp, wsp.structural.gm_pv)
wsp.basil_options.update({
"pwm": wsp.structural.wm_pv_asl,
"pgm": wsp.structural.gm_pv_asl
})
basil.basil(wsp, output_wsp=wsp.sub("basil_pvcorr"), prefit=False)
wsp.sub("output_pvcorr")
output_native(wsp.output_pvcorr, wsp.basil_pvcorr)
output_trans(wsp.output_pvcorr)
if wsp.surf_pvcorr:
if oxasl_surfpvc is None:
raise RuntimeError(
"Surface-based PVC requested but oxasl_surfpvc is not installed"
)
if user_pv_flag:
wsp.log.write(
" - WARNING: Performing surface based PVC ignores user-specified PV maps\n"
)
# Prepare GM and WM partial volume maps from surface using Toblerone plugin
# Then reform the ASL ROI mask - Toblerone does not handle the cerebellum so need
# to mask it out
oxasl_surfpvc.prepare_surf_pvs(wsp)
wsp.rois.mask_pvcorr = wsp.rois.mask
min_pv = 0.01
new_roi = (wsp.basil_options["pwm"].data >
min_pv) | (wsp.basil_options["pgm"].data > min_pv)
wsp.rois.mask = Image(new_roi.astype(np.int8),
header=wsp.rois.mask_pvcorr.header)
basil.basil(wsp,
output_wsp=wsp.sub("basil_surf_pvcorr"),
prefit=False)
wsp.sub('output_surf_pvcorr')
output_native(wsp.output_surf_pvcorr, wsp.basil_surf_pvcorr)
output_trans(wsp.output_surf_pvcorr)
def get_sensitivity_correction(wsp):
"""
Get sensitivity correction image
Required workspace attributes
-----------------------------
- ``asldata`` : ASL data
Optional workspace attributes
-----------------------------
- ``isen`` : User supplied sensitivity image
- ``cact`` : Calibration image. Used in conjunction with ``cref`` to calculate sensitivity map
- ``calib`` : Calibration image. Used as alternative to cact provided ``mode`` is ``longtr``
- ``cref`` : Calibration reference image
- ``senscorr_auto`` : If True, automatically calculate sensitivity correction using FAST
- ``senscorr_off`` If True, do not apply sensitivity correction
Updated workspace attributes
----------------------------
- ``sensitivity`` : Sensitivity correction image in ASL space
"""
if wsp.senscorr is not None:
return
wsp.log.write("\nCalculating Sensitivity correction\n")
sensitivity = None
bias = None
if wsp.senscorr_off:
wsp.log.write(" - Sensitivity correction disabled\n")
elif wsp.isen is not None:
wsp.log.write(" - Sensitivity image supplied by user\n")
sensitivity = wsp.isen
elif wsp.cact is not None and wsp.cref is not None:
wsp.log.write(
" - Sensitivity image calculated from calibration actual and reference images\n"
)
cref_data = np.copy(wsp.cref.data)
cref_data[cref_data == 0] = 1
sensitivity = Image(wsp.cact.data.astype(np.float) / cref_data,
header=wsp.calib.header)
elif wsp.calib is not None and wsp.cref is not None:
if wsp.ifnone("mode", "longtr") != "longtr":
raise ValueError(
"Calibration reference image specified but calibration image was not in longtr mode - need to provided additional calibration image using the ASL coil"
)
wsp.log.write(
" - Sensitivity image calculated from calibration and reference images\n"
)
cref_data = np.copy(wsp.cref.data)
cref_data[cref_data == 0] = 1
sensitivity = Image(wsp.calib.data.astype(np.float) / cref_data,
header=wsp.calib.header)
elif wsp.senscorr_auto and wsp.structural.bias is not None:
struc.segment(wsp)
wsp.log.write(" - Sensitivity image calculated from bias field\n")
bias = reg.struc2asl(wsp, wsp.structural.bias)
sensitivity = Image(np.reciprocal(bias.data), header=bias.header)
else:
wsp.log.write(" - No source of sensitivity correction was found\n")
if sensitivity is not None:
sdata = sensitivity.data
sdata[sdata < 1e-12] = 1
sdata[np.isnan(sdata)] = 1
sdata[np.isinf(sdata)] = 1
wsp.sub("senscorr")
wsp.senscorr.sensitivity = Image(sdata, header=sensitivity.header)
page = wsp.report.page("sensitivity")
page.heading("Sensitivity correction", level=0)
page.heading("Sensitivity map", level=1)
page.image("sensitivity", LightboxImage(wsp.senscorr.sensitivity))
if bias is not None:
wsp.senscorr.bias = bias
def generate_mask(wsp):
"""
Generate mask for ASL data
- If a ready-made mask image is provided or has already been generated, this is returned
- If a structural image is provided this will be used. Brain extraction and registration
will be performed if required
- If a calibration image is provided, this is used. It is assumed to be in the same space
as the ASL data
- If none of the above are present, the ASL data itself is averaged and brain extracted
to produce the mask
Required workspace attributes
-----------------------------
Formally there are no required attributes, however at least one image must be provided
which enables a mask to be generated.
Optional workspace attributes
-----------------------------
- ``asldata`` : ASL data image
- ``mask`` : Existing brain mask
- ``struc`` : Structural image (wholehead)
- ``struc_brain``: Already brain-extracted structural image
- ``asl2struc`` : Existring ASL->Structural space transformation matrix
- ``calib`` : Calibration image
- ``regfrom`` : ASL registration source image
"""
if wsp.rois is not None and wsp.rois.mask is not None:
return
wsp.sub("rois")
# Reporting
page = wsp.report.page("mask")
page.heading("Mask generation", level=0)
if wsp.mask is not None:
wsp.rois.mask_src = "user"
mask_source = "provided by user (assumed to be ASL space): %s" % wsp.mask.name
wsp.rois.mask = wsp.mask
elif wsp.structural.struc is not None:
# Preferred option is to use brain extracted structural
wsp.rois.mask_src = "struc"
struc.init(wsp)
page.heading("Brain extracted structural image", level=1)
page.image(
"struc_brain",
LightboxImage(wsp.structural.brain, bgimage=wsp.structural.struc))
brain_mask_asl = reg.struc2asl(wsp, wsp.structural.brain_mask)
wsp.rois.mask = Image(sp.ndimage.morphology.binary_fill_holes(
(brain_mask_asl.data > 0.25)).astype(np.int),
header=brain_mask_asl.header)
mask_source = "generated from brain extracting structural image and registering to ASL space"
else:
# Alternatively, use registration image (which will be BETed calibration or mean ASL image)
reg.get_regfrom(wsp)
wsp.rois.mask_src = "regfrom"
wsp.rois.mask = Image((wsp.reg.regfrom.data != 0).astype(np.int),
header=wsp.reg.regfrom.header)
mask_source = "generated from brain extracted registration ASL image"
wsp.log.write("\nGenerated ASL data mask\n")
wsp.log.write(" - Mask %s\n" % mask_source)
page.heading("Masked ASL brain image", level=1)
page.text("Mask was %s" % mask_source)
page.text("PW ASL image masked by ASL-space mask")
if wsp.asldata.iaf in ("diff", "tc", "ct"):
page.image(
"mask_outline",
LightboxImage(wsp.rois.mask,
bgimage=wsp.asldata.perf_weighted(),
outline=True))
else:
page.image(
"mask_outline",
LightboxImage(wsp.rois.mask,
bgimage=wsp.asldata.mean(),
outline=True))
def get_tissrefmask(wsp):
"""
Calculate a calibration reference mask for a particular known tissue type
"""
struc.segment(wsp)
page = wsp.report.page("auto_calib_mask")
page.heading("Calibration reference region")
page.text(
"Reference region was automatically generated for tissue type: %s" %
wsp.tissref.upper())
page.heading(
"Partial volume map for %s tissue (from structural segmentation)" %
wsp.tissref.upper(),
level=1)
wsp.calibration.refpve = getattr(wsp.structural,
"%s_pv" % wsp.tissref.lower())
page.image(
"refpve",
LightboxImage(wsp.calibration.refpve, bgimage=wsp.structural.brain))
if wsp.tissref == "csf" and not wsp.csfmaskingoff:
wsp.log.write(
" - Doing automatic ventricle selection using standard atlas\n")
# By deafult now we do FNRIT transformation of ventricle mask
# FIXME disabled as not being used in ASL_CALIB at present
#wsp.calibration.struc2stdfnirt = wsp.ifnone("stdmaskfnirt", True)
# Select ventricles based on standard space atlas
page.heading("Automatic ventricle selection", level=1)
page.text(
"Standard space ventricles mask (from Harvard-Oxford atlas) eroded by 1 pixel"
)
atlases = AtlasRegistry()
atlases.rescanAtlases()
atlas = atlases.loadAtlas("harvardoxford-subcortical",
loadSummary=False,
resolution=2)
ventricles = ((atlas.data[..., 2] + atlas.data[..., 13]) > 0.1).astype(
np.int)
wsp.calibration.ventricles = Image(
scipy.ndimage.binary_erosion(ventricles,
structure=np.ones([3, 3, 3]),
border_value=1).astype(np.int),
header=atlas.header)
std_img = Image(
os.path.join(os.environ["FSLDIR"], "data", "standard",
'MNI152_T1_2mm_brain'))
page.image("ventricles_std",
LightboxImage(wsp.calibration.ventricles, bgimage=std_img))
page.heading("Structural space ventricles mask", level=1)
reg.reg_struc2std(wsp)
# FIXME nearest neighbour interpolation?
wsp.calibration.ventricles_struc = reg.std2struc(
wsp, wsp.calibration.ventricles)
page.text(
"This is the above image transformed into structural space. The transformation was obtained by registering the structural image to the standard brain image"
)
page.image(
"ventricles_struc",
LightboxImage(wsp.calibration.ventricles_struc,
bgimage=wsp.structural.brain))
wsp.log.write(
" - Masking FAST output with standard space derived ventricle mask\n"
)
wsp.calibration.refpve_pre_mask = wsp.calibration.refpve
refpve_data = np.copy(wsp.calibration.refpve.data)
refpve_data[wsp.calibration.ventricles_struc.data == 0] = 0
wsp.calibration.refpve = Image(refpve_data,
header=wsp.calibration.refpve.header)
wsp.calibration.refpve_post = wsp.calibration.refpve
page.heading("Structural space ventricles PVE", level=1)
page.text(
"This is the CSF partial volume masked by the ventricles mask. It should select only the ventricles from the original partial volume image."
)
page.image(
"refpve_post",
LightboxImage(wsp.calibration.refpve,
bgimage=wsp.structural.brain))
wsp.log.write(" - Transforming tissue reference mask into ASL space\n")
# FIXME calibration image may not be in ASL space! Oxford_asl does not handle this currently
wsp.calibration.refpve_calib = reg.struc2asl(wsp, wsp.calibration.refpve)
#wsp.calibration.refpve_calib.data[wsp.calibration.refpve_calib.data < 0.001] = 0 # Better for display
page.heading("Reference region in ASL space", level=1)
page.text("Partial volume map")
page.image("refpve_calib",
LightboxImage(wsp.calibration.refpve_calib, bgimage=wsp.calib))
# Threshold reference mask conservatively to select only reference tissue
wsp.log.write(" - Thresholding reference mask\n")
wsp.calibration.refmask = Image(
(wsp.calibration.refpve_calib.data > 0.9).astype(np.int),
header=wsp.calibration.refpve_calib.header)
page.text("Reference Mask (thresholded at 0.9")
page.image("refmask",
LightboxImage(wsp.calibration.refmask, bgimage=wsp.calib))
def get_m0_wholebrain(wsp):
"""
Get a whole-brain M0 value
This calculates an M0 map for the whole brain using the T1, T2 and PC
values for each tissue type with the contribution at each voxel weighted
by the tissue partial volume
:param wsp: Workspace object
:return: Image containing voxelwise M0 map
Required Workspace attributes
-----------------------------
- ``calib`` - Calibration Image in ASL native space
- ``rois.mask`` - Brain mask Image in ASL native space
- ``struc`` - Structural image
"""
struc.segment(wsp)
wsp.log.write("\n - Doing wholebrain region calibration\n")
tr = wsp.ifnone("tr", 3.2)
te = wsp.ifnone("te", 0)
taq = wsp.ifnone("taq", 0)
wsp.log.write(" - Using TE=%f, TR=%f, Readout time (TAQ)=%f\n" %
(te, tr, taq))
t2star = wsp.ifnone("t2star", False)
if t2star:
t2b = wsp.ifnone("t2sb", 50)
else:
t2b = wsp.ifnone("t2b", 150)
# Check the data and masks
calib_data = np.copy(wsp.calib.data)
if wsp.rois is not None and wsp.rois.mask is not None:
brain_mask = wsp.rois.mask.data
else:
brain_mask = np.ones(wsp.calib.shape[:3])
### Sensitivity image calculation (if we have a sensitivity image)
if wsp.sens:
wsp.log.write(" - Using sensitivity image: %s\n" % wsp.sens.name)
calib_data /= wsp.sens.data
m0 = np.zeros(calib_data.shape, dtype=np.float)
for tiss_type in ("wm", "gm", "csf"):
pve_struc = getattr(wsp.structural, "%s_pv" % tiss_type)
wsp.log.write(" - Transforming %s tissue PVE into ASL space\n" %
tiss_type)
pve = reg.struc2asl(wsp, pve_struc)
t1r, t2r, t2sr, pcr = tissue_defaults(tiss_type)
if t2star:
t2r = t2sr
t1_corr = 1 / (1 - math.exp(-(tr - taq) / t1r))
t2_corr = 1 / math.exp(-te / t2r)
wsp.log.write("Correction factors: T1: %f, T2 %f, PC: %f" %
(t1_corr, t2_corr, pcr))
tiss_m0 = calib_data * t1_corr * t2_corr / pcr
wsp.log.write(" - Mean %s M0: %f (weighted by PV)\n" %
(tiss_type, np.average(tiss_m0, weights=pve.data)))
tiss_m0 *= pve.data
setattr(wsp.calibration, "m0_img_%s" % tiss_type,
Image(tiss_m0, header=wsp.calib.header))
m0 += tiss_m0
m0 = m0 * math.exp(-te / t2b)
gain = wsp.ifnone("calib_gain", 1)
wsp.log.write(" - Calibration gain: %f\n" % gain)
if gain != 1:
m0 = m0 * gain
wsp.calibration.m0_img = Image(m0, header=wsp.calib.header)
m0 = np.mean(m0[brain_mask != 0])
wsp.log.write(" - M0 of brain: %f\n" % m0)
# Reporting
page = wsp.report.page("m0")
page.heading("Whole-brain M0 calculation")
page.text(
"Whole-brain calibration calculates an M0 value for each voxel from the calibration image based on partial volume estimates"
)
page.text("- Calibration gain: %f" % gain)
page.text(" - TR: %f" % tr)
page.text(" - TE: %f" % te)
page.heading("M0", level=1)
page.text("Mean M0 value (within mask): %f" % m0)
page.image("m0img", LightboxImage(wsp.calibration.m0_img))
return float(m0)