====== pmbfilter (poly-mask bias filter) ======

===== Motivation =====
Depending on the sequence using for collecting structural MRI data, the output image sometimes exhibits a noticeable amount of intensity inhomogeneity bias. This is demonstrated in the screenshot below:

{{:neuroelf:pmbfilter_pre.jpg?640x640|Structural image showing inhomogeneity}}

In turn, this can lead to reduced performance of algorithms used in subsequent processing steps, for instance when the outcome is hugely depending on the fact that white and gray matter have clearly separate and separable peaks in the intensity histogram and distribution across the brain (which is violated for inhomogeneous data!).

===== Requirements =====
You simply need the data file, which can be in either

  * [[xff - VMR format|VMR format]] for use with BrainVoyager QX files
  * [[xff - HDR format|HDR/NII format]] for use with SPM files
  * or [[xff - HEAD format|HEAD format]] for use with AFNI files

===== Function reference ('help pmbfilter') =====
<file>  pmfilter  - apply a poly-mask bias filter to an image
 
  FORMAT:       [out, bias, b, bo] = pmbfilter(in, order, mask [, opts])
 
  Input fields:
 
        in          input image
        order       polynomial order
        mask        mask(s)
        opts        optional fields
         .bcutoff   bias cutoff value (lower values are removed, 0.2)
         .cmask     flag, mask must be continuous (i.e. 1 cluster, false)
         .debias    which de-biasing method ('biasonly', 'log', {'mult'})
         .robust    perform robust regression (default: false)
 
  Output fields:
 
        out         output image (after filtering)
        bias        bias field in dims of input image
        b           bias field weights
        bo          bias field polynomial orders
 
  Note: if mask is empty, an auto-detection algorithm is employed</file>

===== Options =====

==== .bcutoff ====
At the end of the procedure, the input data (''in'') is corrected with the bias field estimate. This estimate can exhibit too low values so that the correction is likely to fail, hence voxels for which this criterion is not met (bias field too low), output voxels will be set to 0.

==== .cmask ====
Forces the mask to be a contiguous chunk of voxels (one cluster). Usually only useful in the last step, in case a series of corrections is applied.

==== .debias ====
Type of de-bias computation. For '''biasonly''' the input is left unchanged and the bias field is returned as the second output. The '''log''' option is currently experimental and has not been thoroughly tested. The '''mult''' option multiplies the input data with the reciprocal value of the bias field on a voxel-by-voxel basis.

==== .robust ====
If set to true performs the regression robustly.

===== Usage example =====
The images on this page (pre- and post-correction slices) have been produced with this procedure:

<code matlab pmbfilter_ex.m>% load dataset
t1 = xff('*.hdr', 'Please select the dataset to be corrected...');

% apply two rounds of correction with default parameters and PO := 3
% - no mask image is available, auto-detection required!
% - first round will correct basic inhomogeneity (crude mask)
% - second round will correct global inhomogeneity (full mask)
ihc = pmbfilter(t1.VoxelData(:, :, :), 3);
ihc = pmbfilter(ihc, 3);

% apply one last round with
% - slightly lower cutoff (retaining a larger portion of the data)
% - forcing a contiguous mask (only voxels of white matter)
% - using robust regression (takes only slightly longer)
ihc = pmbfilter(ihc, 3, [], struct( ...
    'bcutoff', 0.1, ...
    'cmask',   true, ...
    'robust',  true));

% set back into data
t1.VoxelData = int16(round(ihc));

% save as
t1.SaveAs(strrep(t1.FilenameOnDisk, '.hdr', '_IHC.hdr'));
t1.SaveVoxelData;</code>

The resulting image then looked like this (on the right):

^ Before pmbfilter application  ^ After pmbfilter application  ^
| {{:neuroelf:pmbfilter_pre.jpg?640x640|Image before applying a set of pmbfilter operations}}  | {{:neuroelf:pmbfilter_post.jpg?640x640|Image after applying a set of pmbfilter operations}}  |