• NAME
• SYNOPSIS
• OPTIONS
• CONFIGFILE
• DESCRIPTION
• FEATURES
• AUTHORS
• LICENSE

NAME

pvconv.pl - converts Bruker format data to other image formats

SYNOPSIS

pvconv.pl [@configfile] [options] paravision_data_dir [output_dir]

e.g.

If the Bruker data is stored in a directory ``/brukerdata/mysession'', and you want to create analyze format files in the current directory, then:

pvconv.pl /brukerdata/mysession/ -verbose -all

will convert all the series in the Bruker data directory.

See http://pvconv.sourceforge.net for more information.

Options:

    -help          print help message and quit
    -man           full documentation and quit
    -verbose       more messages, more detailed help output
    -quiet         no messages during operation
    -version       returns version no
    -clobber       overwrite pre-existing files
    -all           convert all series in the directory [default]
    -series        one or more series to convert
    -dbpath        one or more directories to search for PV data
    -ptype         one or more file name <-> protocol name pairs
    -outtype       output type, "analyze" or "minc"
    -outdir        directory to output files
    -outfile       name of file to output (extension ignored)
    -radio         use radiological orientation for orientation output 
    -noradio       use neurological orientation for orientation output [default]
    -showmat       display verbose sequential listing of orientation data
    -dirext        adds PV directory ext to output names
    -frecofix      fix reported byte ordering for FRECO and other reconstructions
    -rawfile       specify rawfile (2dseq) to use
    -anon          do not save subject data into brkhdr files
    -noanon        save subject data into brkhdr files
    -timelength    specify no of volumes in time series 
    -layers        separate images according to layer information [default]
    -nolayers      do not separate images according to layer information 
    -recono        reconstruction no to convert
    -reshape       whether to reshape (MINC only so far)
    -stepdir       directions of increase x, y, z
    -view          show image after conversion (MINC only)

    @configfile

    Configuration file containing any of the options above in format
    given by Getopts::Argvfile (www.cpan.org) - the format is
    the same as for the command line, but allowing multiple
    lines and comments.

OPTIONS

-help

Print a long help message and exit.

-man

Prints the manual page and exit.

-verbose

Gives out moderately helpful warning and other messages during image conversion. Adding -verbose to -help outputs more help.

-quiet

Turn off any messages during conversion

-version

Returns version no to the console.

-clobber

Will overwrite preexisting files. If there are preexisting files, and you do not use -clobber, pvconv will exit with an error message.

-all

Convert all series in the directory. This is the default behaviour.

-series

Specify series to convert, e.g.

pvconv.pl /brukerdata/mysession/ -series 1 -series 3

will convert series 1 and 3 only. Defaults to -all

-dbpath

Specify one or more directories to search for PV data. This can be used to give default search paths in which to look for the specified paravision subject data. e.g.

pvconv.pl mysession -dbpath /brukerdata -dbpath /another/dir

If (as here) the required directory does not contain a path component, seachpath is used to search for a matching dataset. Paths specified later are searched first: here, ``/another/dir'' will be searched before ``/brukerdata''.

If (as here) the required directory (``mysession'') does not contain an extension, then the program will search for any directory matching ``<inputname>*'' - here ``mysession*''. This allows you to search for data where you know only the first few characters of the directory name.

-ptype

One or more file suffix / protocol name pairs for clever file naming - e.g:

pvconv.pl /brukerdata/mysession/ -ptype T3=tripilot -series 1

This -ptype string will cause pvconv to match the contents of the Bruker ACQ_protocol_name field with the regular expression after the equals sign (here the regexp is just the string ``tripilot''). If pvconv finds a match, it will append the first string in the pair (here ``T3'') to the output file name, preceded by an underscore. Here the output might be:

    ./mysession_01_T3.img
    ./mysession_01_T3.hdr
    ./mysession_01_T3.mat

The protocol name is treated as a perl regular expression; for example, you might specify ``-ptype EPI=(epi|fmri)'' if you wanted files with either ``epi'' or ``fmri'' in the protocol_name field to have ``EPI'' appended to the output file name. The match is not case sensitive.

These file suffix / protocol name pairs are probably best stored in configuration files.

-outtype

Specify output type, currently one of ``analyze'' or ``minc''. ``analyze'' is the default.

-outdir

Directory to output converted image files; e.g.

pvconv.pl /brukerdata/mysession/ -all -outdir /home/me/images

The default output directory is the current directory.

-outfile

Root name of image files to output (extension ignored); e.g.

pvconv.pl /brukerdata/mysession/ -series 2 -outname image2

will create Analyze format output files:

 ./image2.img
 ./image2.hdr
 ./image2.mat

pvconv derives the default file name from the name of the Bruker data directory, the series number, and any matches it finds of the protocol name with preset strings identifying image types (see -ptype option).

-frecofix

Fix reported byte ordering for FRECO reconstructions in paravision 2.0, and for some other reconstructions. If the reco file specifies that the reconstructed data has a different endianness from the raw (FID) data, then the reconstructed data is assumed to have the endianness of the raw data. Try this flag if you get a snowstorm effect in converted images without it.

-radio

Set orientation calculations to return radiological orientation.

-noradio

Set orientation calculations to return neuroogical orientation (the pvconv and Bruker default).

-showmat

Shows a verbose output of the orientation matrix as it is built step by step from the Bruker parameters.

-dirext

Adds Bruker directory extension to output names. Bruker data directories usually have an extension that is unique for the particular day of scanning. pvconv usually omits this extension from the default output filename; e.g.

pvconv.pl /brukerdata/mysession.fs1 -series 1

may generate a file: ./mysession_01.img

The -dirext option causes the extension to be added to the filename; e.g.

pvconv.pl /brukerdata/mysession.fs1 -series 1 -dirext

may generate a file: ./mysession_fs1_01.img

-anon

Omit Bruker subject information from .brkhdr txt file. Very useful if real subject names etc are stored in this file. use -noanon to keep subject information in brkhdr file.

-rawfile

Specify raw image file to use as image data instead of 2dseq: e.g.

pvconv.pl /brukerdata/mysession/ -all -rawdata mydata.img

-timelength

Specify no of volumes in time series. This is useful in cases where the reco etc files have incorrect parameters, and you know the actual no of volumes.

-layers

Separate images according to layer information; for example, multiecho sequences such as combined T1/PD acquisitions have images from the two echos interleaved. This option will cause pvconv to split the interleaved slices into two images. Use -nolayers to disable this behaviour.

-recono

Reconstruction number to convert. Usually there is only one; use e.g.

pvconv.pl /brukerdata/mysession/ -series 4 -recono 2

to convert a second reconstruction for series 4.

-reshape

Whether to reshape (MINC only so far)

-stepdir

Directions of increase x, y, z (MINC only)

-view

Show image after conversion (MINC only)

CONFIGFILE

Options can be specified by configuration files in the same format as for the command line, except options can be specified across many lines, and comments can be interposed: e.g

pvconv.pl /brukerdata/mysession @myconfig

where ``myconfig'' is the following text file

 # data search path, in search order
 -dbpath /cbu/imagers/wbic_data

 # file name ending for protocol regexps
 -ptype SPGR=spgr
 -ptype anatomique=anatom
 -ptype T3=tripilot
 -ptype template=template
 -ptype PD-T2=pd-t2
 -ptype EPI=(epi|new90|new100)
 -ptype phasemap=phase

 # frecofix by default
 -frecofix

Configuration files are read in the following order: .pvconv.pl in the directory of the pvconv.pl script; .pvconv.pl in your home directory; .pvconv.pl in the current directory; and any configuration file passed on the command line. Options in files read later override those in earlier files. Options passed on the command line override options passed in .pvconv.pl files, and any options specified earlier on the the command line than the @configfile item.

DESCRIPTION

pvconv.pl converts Bruker format MRI data to Analyze image format. It may also convert Bruker data to MINC format.

The program is based on the converters by Andrew Janke ( http://www.cmr.uq.edu.au/~rotor/software/ ) Many thanks to him for the original programs and helpful suggestions.

FEATURES

pvconv reads the text header files from the Bruker data format ( http://www.mrc-cbu.cam.ac.uk/Imaging/Common/brukerformat.html ), and uses the values therein to fill a header information for Analyze format images ( http://www.mrc-cbu.cam.ac.uk/Imaging/Common/analyze_fmt.html ), and possibly MINC files.

pvconv will try and work out the orientation of the scan in terms of the magnet isocentre, and create reorientation matrices. For Analyze format images, the orientation is stored in Matlab .mat format, of a type that can be read by SPM software: http://www.mrc-cbu.cam.ac.uk/Imaging/Common/spm_format.html. In this way, scans will be automatically coregistered when you use SPM for your analysis.
If two acquisitions have been collected in the same image (e.g. dual echo sequences) it will (by default - see the -layers option) create separate files for each.
A text file containing all the Bruker text file parameters is automatically saved with the analyze image (as a .brkhdr file) for further reference.
Converted files can be saved with semi-sensible file names; for example, let us say that the original data came from a directory ``/brukerdata/mysession''. You have converted files from the fifth series collected in that session; the protocol name stored in the Bruker files was ``EPI_FID''. Somewhere (see Cconfiguration files) you had specified the protocol name / file name link, using ``-ptype EPI=epi'' or similar. The output files would be:

 ./mysession_05_EPI.hdr        (Analyze header)
 ./mysession_05_EPI.img        (Analyze image data)
 ./mysession_05_EPI.mat        (SPM orientation)
 ./mysession_05_EPI.brkhdr     (Bruker parameter text file data)

AUTHORS

Matthew Brett <mailto://matthewb@berkeley.edu>

Andrew Janke <rotor AT cmr.uq.edu DOT au>

LICENSE

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License distributed with Perl version 5.003 or (at your option) any later version. Please refer to the Artistic License that came with your Perl distribution for more details.