Simple function to manipulate DW gradient vector files, b-value files, and b-/g-matrices. Let: g_i be one of Ng spatial gradients in three dimensions; the g-matrix is G_{ij} = g_i*g_j (i.e., dyad of gradients, without b-value included); and the DW-scaled b-matrix is B_{ij} = b*g_i*g_j.
3 rows of gradients (as output from dcm2nii, for example);
3 columns of gradients;
Bxx, Byy, Bzz, Bxy, Bxz, Byz,
which is used in 3dDWItoDT, for example;
Bxx, 2*Bxy, 2*Bxz, Byy, 2*Byz, Bzz,
which is output by TORTOISE, for example;
when specifying input file, one can use the brackets ‘{ }’ in order to specify a subset of rows to keep (NB: probably can’t use this grad-filter when reading in row-data right now).
- RUNNING:
1dDW_GradOrMat
{ -in_grad_rows | -in_grad_cols | -in_gmatT_cols |
-in_gmatA_cols | -in_bmatT_cols | -in_bmatA_cols} INFILE
{ -flip_x -flip_y -flip_z }
{ -keep_b0s -put_zeros_top -out_bval_col }
{ -in_bvals BVAL_IN }
{ -bmax_ref THRESH }
{ -out_grad_cols | -out_gmatT_cols | -out_gmatA_cols |
-out_bmatT_cols | -out_gmatA_cols | -out_grad_rows } OUTFILE
{ -out_bval_row_sep BB }
- where:
- (one of the following six formats of input must be given):
-in_grad_rows INFILE :input file of 3 rows of gradients (e.g., dcm2nii- format output). -in_grad_cols INFILE :input file of 3 columns of gradients.
-out_grad_cols OUTFILE :output file of 3 columns of gradients.
- -out_bmatA_cols OUTFILE :output file of 6 columns of b-matrix in ‘A(FNI)’
- `diagonal first’-format. (See above.)
- -out_bmatT_cols OUTFILE :output file of 6 cols of b-matr in ‘T(ORTOISE)’
- `row first’-format. (See above.)
-out_grad_rows OUTFILE :output file of 3 rows of gradients.
(and any of the following options may be used):
- -proc_dset DSET :input a dataset DSET of X ‘b=0’ and Y DWI bricks,
matching the X zero- and Y nonzero-gradient entries in the INFILE. The ‘processing’ will:
- extract all the ‘b=0’ bricks,
- average them,
- store the result in the zeroth brick of the output PREFIX data set, and
- place the DWIs (kept in their original order) as the next Y bricks of PREFIX.
This option cannot be used with ‘-keep_b0s’. The output set has Y+1 bricks. The option is probably mostly useful only if X>1.
- -pref_dset PREFIX :output dataset filename prefix (required and iff
- using ‘-proc_dset’, above).
- -dwi_comp_fac N_REP :option for averaging DWI bricks in DSET that have
- been acquired with exactly N_REP repeated sets of gradients. You the user must know how many repetitions have been performed (this program will perform a simplistic gradient comparison using dot products to flag possible errors, but this is by no means bulletproof. Use wisely.
-flip_x :change sign of first column of gradients -flip_y :change sign of second column of gradients -flip_z :change sign of third column of gradients -keep_b0s :default function is to get rid of all reference image, but this option acts as switch to keep them. -put_zeros_top :whatever the output format is, add a row at the top with all zeros.
- -in_bvals BVAL_IN :BVAL_IN is a file of b-values, such as the ‘bval’
- file generated by dcm2nii.
- -bmax_ref THRESH :THRESH is a scalar number below which b-values
- (in BVAL_IN) are considered `zero’ or reference. Sometimes, for the reference images, the scanner has a value like b=5 s/mm^2, instead of strictly b=0 strictly. One can still flag such values as being associated with a reference image and trim it out, using, for the example case here, ‘-bmax_ref 5.1’.
-out_bval_col :switch to put a column of the bvalues as the first column in the output data. -out_bval_row_sep BB :output a file BB of bvalues in a single row.
If you use this program, please reference the introductory/description paper for the FATCAT toolbox:
Taylor PA, Saad ZS (2013). FATCAT: (An Efficient) Functional And Tractographic Connectivity Analysis Toolbox. Brain Connectivity 3(5):523-535.