NAME
bin2pipe, bruk2Pipe, var2pipe - NMRPipe Format Conversion.
SYNOPSIS
bin2pipe < inStream > outStream [acqOptions] [-in inName]
[-out outTemplate] [-bo byteOff] [-bp bytePad] [-swap |
-noswap | -aswap | -noaswap] [-pad | -nopad] [-il | -noil]
[-i2r] [-ri] [-neg] [-bad badPntThresh] [-ge | -ex | -gsx |
-alpha | -alpha2 | -lambda | -chem | -ftOLD | -ftNEW]
[-noIn] [-noOut] [-ov] [-nodir] [-nofs] [-verb]
bruk2pipe < inStream > outStream [acqOptions] [-in inName]
[-out outTemplate] [-AM | -AMX | -DMX] [-bo byteOff] [-swap
| -noswap | -aswap | -noaswap] [-ext | -noext] [-decim
decimVal] [-dspfvs dspVal] [-skip skipPts] [-zf | -nozf]
[-bad badPntThresh] [-ov] [-nodir] [-nofs] [-mem MBytes]
[-verb]
var2pipe < inStream > outStream [acqOptions] [-in inName]
[-out outTemplate] [-aqORD loopCode] [-hw hdrWords] [-pw
padWords] [-i2r | -noi2r | -dsp] [-short | -long] [-hdr |
-nohdr] [-swap | -noswap | -aswap | -noaswap] [-ov] [-nodir]
[-nofs] [-info] [-verb]
SPECIAL NOTE
This manual page describes the use of the nmrPipe spectrome-
ter format conversion programs. The parameters required for
format conversion are often the most difficult aspect for
new users of nmrPipe, so the details below should be
reviewed carefully.
DESCRIPTION
The programs bruk2pipe, var2pipe, and bin2pipe are used to
convert spectral data, usually unprocessed binary data from
a spectrometer or imager, to the nmrPipe format. These pro-
grams are implemented as UNIX filters; they read a stream of
binary data from a file or pipeline, perform a format
conversion, and write the converted data to a file, file
series, or pipeline.
The bruk2pipe program is used to convert Bruker AM, AMX or
DMX (Avance) format "ser" files to the nmrPipe data format.
The bruk2pipe program can be used to convert data of one to
four dimensions, but 3D and 4D data must have a specific
acquisition order (alternating real and imaginary hypercom-
plex planes) to be converted properly. A complementary com-
mand bruker is now also provided; this command activates a
graphical interface which can interpret "acq" and "pulsepro-
gram" files from the spectrometer to assist in the creation
of conversion scripts.
The var2pipe program performs conversions for Varian Unity
and INOVA "fid" files. Two-byte integer, four-byte integer,
and DSP four-byte floating point data formats are supported.
In many cases, var2pipe can select the correct data format
automatically by interpreting the binary header of the
Varian "fid" file. The var2pipe program can be used to con-
vert data of one to four dimensions, but 3D and 4D conver-
sions are restricted to two kinds of acquisition orders. A
complementary command varian is now also provided; this
command activates a graphical interface which can interpret
"procpar" parameter files from the spectrometer to assist in
the creation of conversion scripts.
The bin2pipe program performs conversions of four-byte
integer or floating point binary files which have a sequen-
tial data order, and a fixed number of bytes between adja-
cent 1D vectors. GE Omega export format, JEOL Alpha, Lambda,
EX, and GSX data, Chemagnetics data, SPIFF spectral images,
and formats of other processing programs may fall into this
category. The bin2pipe program can be used to convert data
of one to four dimensions, but the data must have a specific
acquisition order. Non-default acquisition orders can be
accommodated via use of nmrPipe macro functions.
These programs make it possible to convert and process both
real and complex data: this includes data acquired in
sequential or simultaneous (complex) mode, as well as
indirect detection in the States, TPPI, States-TPPI and Mag-
nitude modes. In addition, conversion of
sensitivity-enhanced (Rance or Rance-Kay gradient mode) data
is also supported.
The use of the conversion programs is essentially the same
in all cases; the conversion program is invoked with the
name of the binary input file, the desired name of the con-
verted output, and a list of relevant acquisition parame-
ters. In addition, there may be one or more parameters
describing hardware-specific or format details, such as the
byte-order used to record intensities on the spectrometer.
In most cases, the conversion programs themselves do not
read or deduce acquisition parameters on their own; the user
must supply each one explicitly as part of the conversion
command.
Since there are many parameters that have to be specified or
confirmed manually, these conversion commands are more com-
plicated than those used by other systems. However, once
the parameters are established, there are many advantages:
Complete multidimensional processing schemes can be con-
structed without the need to anticipate or explicitly
specify data sizes. The dimensions can be processed and
re-processed in any order, with the correct combination
of real and imaginary data supplied automatically.
Spectral axis calibrations are maintained during all
stages of processing, so that processing parameters can
be specified in terms of spectral units where desired.
The processing modules can identify processing schemes
which seem inconsistent with the current data.
The conversion commands can read data from a UNIX com-
mand pipeline rather than a file, allowing such capabil-
ities as conversion of compressed data (as via the UNIX
commands compress and zcat), or conversion of input data
dispersed over more than one file (as via the UNIX com-
mand dd).
USING THE CONVERSION PROGRAMS
In order to understand the use of the conversion programs,
it might be helpful to review the details of the nmrPipe and
the programs xyz2pipe and pipe2xyz program first. Details
are presented in the nmrPipe and xyz2pipe manual pages. In
addition, once spectral data has been converted, it is
advantageous to inspect the converted result visually; this
can be done with the graphical interface nmrDraw.
A typical 2D conversion command is shown here, in this case
for a Bruker AMX 2D HN-correlated FID with States-mode
detection; a description of its contents follows:
bruk2pipe -in hsqcn.ser \
-xN 2048 -yN 256 \
-xT 1024 -yT 128 \
-xMODE Complex -yMODE Complex \
-xSW 9090.91 -ySW 2500.00 \
-xOBS 600.138 -yOBS 60.8108 \
-xCAR 4.73 -yCAR 118.0 \
-xLAB HN -yLAB N \
-ndim 2 -aq2D States \
-out hsqcn.fid -verb -ov
The conversion program is usually invoked by a UNIX C-shell
script, which is a list of commands in a text-file; the
shell-script should always begin with the line:
#!/bin/csh
The conversion command itself has an input specification
which names the input binary FID file, and an output specif-
ication which names the output data file or file series. In
addition, the conversion command includes a list of
axis-specific parameters, which have a particular value for
each dimension of the input data. For example, each dimen-
sion has a spectral width (sweep width), so a conversion
command has one sweep width specification for each dimension
of the data.
The nmrPipe nomenclature uses the terms X-Axis, Y-Axis,
Z-Axis, and A-Axis to refer to the dimensions of the data.
Correspondingly, the conversion command uses the prefixes
-x, -y, -z, and -a for parameters that pertain to these
dimensions. For example, the sweep width arguments are
specified by the flags -xSW, -ySW, -zSW, and -aSW.
In the current implementation, the conversion command should
include specification of all of the following parameters for
each dimension:
Acquisition Mode
This parameter defines the data type of the given dimen-
sion, which controls how the real and imaginary parts
should be stored and processed. The acquisition mode is
usually specified as a keyword. While there are several
possible keywords, in most cases it is sufficient to
specify either "Real" or "Complex"; other options are
described in the ACQUISITION MODES section below. The
acquisition modes are specified by the options -xMODE,
-yMODE, -zMODE, and -aMODE.
Actual Size
This parameter specifies the actual total number of
points (real + imaginary) stored in the input file for a
given dimension. In most cases (complex detection,
States, and States-TPPI modes) this parameter will be
twice the value of the corresponding time-domain size
below. The actual sizes are specified by the parameters
-xN, -yN, -zN, and -aN.
Valid Time-Domain Size
This parameter specifies the the number of valid points
recorded in the input file for a given dimension. Note
Well! If the dimension is type Complex, the time-domain
size should be given in COMPLEX points; if the dimension
is type Real, the time-domain size should be given in
TOTAL points; data types are summarized by a table in
the ACQUISITION MODES section below.
The time-domain size is used to determine the default
length of the window function for a given dimension. In
some cases, the spectrometer format FID may be padded so
that the number of points saved in the input file is
actually larger than the number of points acquired. In
other cases, a dimension may contain interleaved data
which is reduced in size by sums or differences before
Fourier processing. It is for cases like these that
separate parameters for actual size and valid size are
required, as shown in the EXAMPLES section below. The
time-domain sizes are specified by the parameters -xT,
-yT, -zT, and -aT.
Spectral Width
This parameter specifies the full spectral width in
Hertz for a given dimension. The spectral widths are
specified by the parameters -xSW, -ySW, -zSW, and -aSW.
Observe Frequency
This parameter specifies the spectral observe frequency
in Megahertz for a given dimension. These frequencies
are specified by the parameters -xOBS, -yOBS, -zOBS, and
-aOBS.
Carrier Position
This parameter specifies the position of the carrier
(center of the spectrum) in PPM for a given dimension.
It is used to establish spectral axis calibration. In a
spectrum of points 1 to N, the center of the spectrum
lies at point N/2 + 1 (e.g. point 127 of 1 to 256). The
carrier positions are specified by the parameters -xCAR,
-yCAR, -zCAR, and -aCAR. The center of the spectrum is
the only point whose PPM location does not change as a
result of zero filling.
Axis Label
This parameter specifies an 8-character or less label
for the given dimension, with no spaces; each dimension
should have a unique and descriptive label. The labels
are specified by the parameters -xLAB, -yLAB, -zLAB, and
-aLAB.
OTHER CONVERSION PARAMETERS
In addition to the axis-specific parameters detailed above,
the following arguments are commonly found in conversion
commands:
-verb: turns verbose mode on, so that the conversion
program will print status messages during conversion.
-ov: turns over-write mode on, so that the conversion
program will replace existing data automatically if
needed.
-ndim: this required parameter specifies the number of
dimensions in the input data.
-swap or -noswap: depending on the computer platforms
involved, spectrometer format data may require each four
bytes of input to be reversed before conversion. This
is called byte-swapping. It can be enabled or
suppressed via these flags. Having the byte-swap mode
set incorrectly will cause large numbers of "Bad
Points", which will have unusually large intensities.
More recently, complementary options -aswap and -noaswap
have been added; these are system-dependant byte-swap
options whose meanings change depending on the computer
platform. The intent is that conversion commands which
use the -aswap and -noaswap options should work consis-
tantly when given the same input data, regardless of the
computer platform used for the conversion.
-aq2D: this required parameter specifies the kind of 2D
file planes produced by the conversion. It is used pri-
marily to distinguish between TPPI phase-sensitive and
magnitude mode data. The parameter is specified as one
of the following keywords, which are not case-sensitive.
Currently, "States" and "States-TPPI" keywords are
equivalent:
oooooooooooo ooooooooooooooooooooooooooooooooo
AQ2D KEYWORD 2D FILE PLANE TYPE
oooooooooooo ooooooooooooooooooooooooooooooooo
Magnitude Not Phase-Sensitive
TPPI Phase-Sensitive TPPI
States Phase-Sensitive States
States-TPPI Phase-Sensitive States-TPPI
Image Image Data
oooooooooooo ooooooooooooooooooooooooooooooooo
Processing Parameters: conversion scripts can also include
specification of the desired window function, first point
scaling, and phase correction to use during processing. See
the EXAMPLES section below.
ACQUISITION MODES
As mentioned above, the acquisition modes are specified by
the options -xMODE, -yMODE, -zMODE, and -aMODE. The major
purpose of the MODE parameter is to define whether vectors
from a given dimension will be treated as type Complex
(separated vectors of real and imaginary data) or type Real
(individual vectors of all-real or interleaved real-
imaginary points). This also defines whether a real or
complex Fourier transform will be required. Most spectral
data dimensions will be treated as type Complex; exceptions
are TPPI data, and Bruker directly-detected sequential data
(Bruker mode QSEQ).
As a convenience, the MODE parameter can also be used to
define the sign adjustment or other special processing (e.g.
for digital detection) needed for conversion and transforma-
tion of the data. Two kinds of sign adjustment are sup-
ported: sign alternation, and negation of imaginary data.
Sign alternation of a complex FID has the effect of exchang-
ing the left and right halves of the corresponding spectrum,
whereas negation of imaginaries in a complex FID has the
effect of reversing the corresponding spectrum.
The steps of sign adjustment and transformation are per-
formed by the nmrPipe Fourier transform function FT. The FT
function will issue warning messages if the transform being
performed does not seem consistent with the parameters
defined during conversion. If the FT function is used in
auto mode (via argument -auto) it will automatically select
a transform type and sign adjustment mode based on conver-
sion parameters.
As mentioned previously, the data type (Complex or Real, as
given in the second column below) determines the relation-
ship between the "actual size" parameters -xN, -yN... and
the corresponding "valid time-domain size" parameters -xT
-yT... The -xN... parameters are always specified as the
total number of points (real + imaginary) recorded in the
input file. For type complex data, the -xT... parameters
are specified in complex points, so these values will usu-
ally be half of the corresponding -xN... values. In the
case of type real data, the -xT... parameters are specified
as total points, so that the corresponding values for -xN...
and -xT... will usually be the same.
Two special but equivalent MODE keywords, "Rance-Kay" and
"Echo-AntiEcho", are provided for shuffling and conversion
of gradient-enhanced dimensions. If one of these keywords
is used, the data will be automatically sent through an
appropriate shuffling macro during conversion, without the
need for any other special adjustments to the conversion
command.
Possible keywords for the MODE parameter are listed below;
note that the keywords are not case-sensitive, and some key-
words are equivalent to others. Note the special keywords
for Bruker data: "Sequential" (or "Bruker") for data
detected in Bruker's QSEQ mode, and "DQD" for digital over-
sampled complex data detected in Bruker's Digital Quad
Detection mode:
oooooooooooo oooooooo ooooooooooo ooooooooooooooo
ACQ MODE DATA AND NEEDS SIGN NEEDS NEGATION
KEYWORD FT TYPE ALTERNATION OF IMAGINARIES
oooooooooooo oooooooo ooooooooooo ooooooooooooooo
Complex Complex No No
States Complex No No
States-TPPI Complex Yes No
DQD Complex No No
Complex-N Complex No Yes
States-N Complex No Yes
States-TPPI-N Complex Yes Yes
Rance-Kay Complex Sometimes Sometimes
Echo-AntiEcho Complex Sometimes Sometimes
Real Real No No
TPPI Real No No
Sequential Real Yes No
Bruker Real Yes No
oooooooooooo oooooooo ooooooooooo ooooooooooooooo
DISPLAYING PARAMETERS
Once the conversion is complete, the parameters recorded in
the header of the nmrPipe format output files can be
displayed with the showhdr program. For example, "showhdr
hsqcn.fid" would produce the following listing for the exam-
ple above:
FILE: hsqcn.fid DIM: 2 QUAD: Complex 2DMODE: States
BYTES: 2099200 PRED: 2099200 MIN: 0 MAX: 0 VALID: 0
ORDER: 2 1 PIPE: 0 PLANES: 1 1024x256x2 Not Transposed
X-Axis Y-Axis
DATA SIZE: 1024 256
APOD SIZE: 1024 128
SW Hz: 9090.910156 2500.000000
OBS MHz: 600.138000 60.810799
ORIG Hz: -1697.924316 5945.205566
DOMAIN: Time Time
MODE: Complex Complex
NAME: HN N
Note that the X-Axis DATA SIZE is reported in complex
points, because the QUAD type is complex. This is a pecu-
liarity of the nmrPipe data format, which for historical
reasons has separated real and imaginary data in the X-Axis,
but interleaved real and imaginary data in the other dimen-
sions.
When used with the -verb option, the showhdr program will
display a more extensive list of parameters, including pro-
cessing parameters and spectral axis ranges.
Another useful companion program is scale2D, which can be
used to display the highest and lowest intensities in a 2D
file or file plane. This information is often useful for
tracking down the location of a bad data plane in 3D or 4D
data, or for confirming the correctness of a conversion
result, since correctly converted FID data will usually have
maximum values in the range of 1e+2 to 1e+6, while improp-
erly converted data will often have much larger maximum
values. The scale2D program takes as its arguments a list
of converted FIDs or processed spectra; it will read each
file and report the highest and lowest values found in the
real part of the data. For example, the command "scale2D
fid/*.dat" would generate reports for all files "*.dat" in
directory "fid".
CONVERTING 3D AND 4D DATA
Conversion of 3D or 4D data is not much different than for
the 2D case; however, the output will usually be specified
as an output template rather than an output file. This
accommodates the fact that the multidimensional data format
is composed of a series of 2D files, rather than just one
file. The files in a given series have a systematic set of
names, where the plane number of the file is part of the
actual file name.
The template is a single name that stands for an entire file
series. The template name contains an integer format field
that shows where the plane number will be inserted into the
actual file name. The integer field is specified according
to the rules of the C Programming Language; details are
given in the xyz2pipe manual page.
For example, the following conversion script uses the output
template "fid/test%03d.fid". In the template, the "%03d"
format specifies that a 3-digit integer will be inserted
into the file name, to give the output series of files
"test001.fid", "test002.fid", ... in the sub-directory
"fid". If the directory "fid" does not exist, the conver-
sion program will attempt to create it automatically:
#!/bin/csh
var2pipe -in hnco_fid_for_frankie \
-xN 1024 -yN 128 -zN 64 \
-xT 512 -yT 64 -zT 32 \
-xMODE Complex -yMODE Complex -zMODE Complex \
-xSW 8000.00 -ySW 1500.00 -zSW 1650.000 \
-xOBS 499.843 -yOBS 125.6969 -zOBS 50.6530 \
-xCAR 4.73 -yCAR 175.0 -zCAR 118.00 \
-xLAB HN -yLAB CO -zLAB N \
-ndim 3 -aq2D States \
-out fid/test%03d.fid -verb -ov
Conversion of 4D data will be performed in the same way; in
this case, the conversion command will also include a set of
-a parameters for the A-Axis of the data, and the number of
dimensions will be set to 4 rather than 3.
In the case of 4D data, the programs xyz2pipe and pipe2xyz
can be used with two-field templates, which include both an
A-Axis index number and a Z-Axis index number in the file
name. However, the conversion programs do not support this
option. So, if a two-field template is desired, the conver-
sion program should be used in a pipeline with pipe2xyz;
this is shown in the EXAMPLES section below.
BRUKER DATA FORMATS
The bruk2pipe conversion program supports AM 3-byte, AMX
4-byte, and DMX (Avance) 4-byte digital filtered data for-
mats. The default type is AMX. Some details follow:
Header: in all cases, the conversion program expects that
the input FID file contains data with no header. If it
does, use the -bo option to skip past the header bytes dur-
ing conversion. The Bruker header size is usually 768
bytes.
Padding: Bruker spectrometers may pad acquisition vectors
with zeros before recording them on the disk, so that the
recorded size is a multiple of 256 points. This padding can
be stripped during conversion using the -ext flag, provided
that the correct actual and valid sizes have been specified.
Bad Points: older versions of Bruker's data storage and
transfer systems had a tendency to corrupt parts of the
spectra data. As a safeguard, the bruk2pipe conversion pro-
gram prints warning messages if intensities in the input
exceed a bad-point threshold; the corresponding points are
then set to zero. The threshold can be adjusted by the -bad
option; setting the threshold to zero will suppress checking
and adjustment of bad points.
Sensitivity or Gradient Enhanced Data: Bruker's gradient
enhanced data (echo anti-echo) can be by use of an addi-
tional data shuffling macro along with bruk2pipe. More
details are given in the EXAMPLES section, in the descrip-
tion of Rance and Rance-Kay mode data conversion. See also
the manual page for the nmrPipe Macro function MAC.
AM Data: AM 3-byte data taken directly from the AM spectrom-
eter is converted using the -AM switch in the conversion
command. If the AM data has been transferred using Bruker's
conversion option to an X-32 workstation, it will be in the
AMX 4-byte format, and so the -AM flag should not be used.
AMX Data: AMX 4-byte data can be converted using the -AMX
flag. Since this is the default mode, the -AMX flag can
also be safely omitted; it is just included for complete-
ness.
DMX (Avance) Data: DMX 4-byte digital filtered data can be
converted using the -DMX flag. In this case, the parameter
-decim is also always required. Set this parameter to the
DECIM value given by Bruker. The conversion is also influ-
enced by the Bruker parameters DSPFVS and AQ_mod, and so
these values may have to be specified as well. The values
for DECIM, AQ_mod, and DSPFVS are currently reported in the
Bruker acquisition status file "acqus", not to be confused
with the file "acqu".
Currently, only two detection modes are supported for
conversion of DMX digital oversampled data: ordinary complex
detection (Bruker QSIM mode, AQ_mod = 1) and digital quad
detection (Bruker DQD mode, AQ_mod = 3). Both modes gen-
erate type complex data. In the case of Bruker QSIM mode,
data should be converted with the parameter setting "-xMODE
Complex". In the case of Bruker DQD mode, data must be con-
verted with the parameter setting "-xMODE DQD".
The DSPFVS parameter can be set using the -dspfvs option.
DSPFVS values 10, 11, 12, and 13 are currently supported,
with the default value being 10 when "-xMODE Complex" is
given, and 11 when "-xMODE DQD" is given.
During the DMX conversion procedure, the first several
points of the result will be adjusted to compensate for
details of the digital oversampling. The number of points
to be adjusted will be set automatically according to the
-decim and -dspfvs options. In some cases however, it may be
better to limit this adjustment, or suppress it entirely,
because it can sometimes result in oscillations in the pro-
cessed data. The number of points which are corrected can
be reduced by the -skip option; using a value of -1 will
suppress the correction entirely.
The DMX conversion procedure will reduce the size of the
acquisition dimension during conversion. Therefore, zero
filling should be selected carefully, to avoid the speed
penalty for Fourier transforming data which is not a power
of two in size. The -auto flag of the nmrPipe ZF function
is useful for this purpose. Note that since the DMX
conversion procedure involves Fourier processing, it is
slower than other conversions.
Byte-Swap: original implementations of the Bruker integer
format required that every 3 or 4 bytes of data be reversed
during conversion; this is called byte-swapping. More
recent Bruker implementations may no longer require
byte-swapping. The computer used to perform conversions may
also influence the byte-swap mode required. If the
byte-swap mode is set incorrectly, large numbers of "Bad
Points" will result, and the conversion will not work prop-
erly. The flags -swap and -noswap can be used to set the
byte-swap modes.
3D and 4D Format: the 3D Bruker conversion assumes that the
input consists of planes which are alternating real and ima-
ginary in the Z-Axis. The 4D conversion assumes alternating
real and imaginary 3D data cubes within the ser file.
BRUKER CONVERSION INTERFACE
The command "bruker" will activate a Tcl/Tk-based graphical
interface which can be used to assist in the creation of
conversion scripts. This interface expects that the Bruker
"acq*" and "pulseprogram" files are available in the same
directory as the "ser" file. The interface will attempt to
extract acquisition parameters by interpreting the "pul-
seprogram" contents; note that this will not always be suc-
cessful.
Use the interface as follows:
1. Enter the command bruker at the command-line; after a
moment the graphical interface will appear.
2. Specify the Spectrometer Input: by default, this will
be set to "ser" if the ser file is found in the current
directory. If the ser file is not in the current direc-
tory, use the caret button next to the "Spectrometer
Input" field; this will create a File Selection window,
which can be used to locate and select the "ser" input
file. In addition, the "CD" button in the File Selec-
tion window can be used to change the working directory
where the conversion script will be saved and executed.
3. Click the "Read Parameters" button; the interface
will attempt to read the "acq" and "pulseprogram" files.
It will then attempt to extract and display the conver-
sion parameters. Parameters which are likely to need
adjustment will be hilighted.
If the X-Axis "Center Position" is initially given as
"H2O", carrier ppm positions will be computed assuming
that the directly-detected dimension is centered at the
water resonance. The ppm position of the water signal
is computed according to the temperature. If the tem-
perature is initially given as "From File", the tempera-
ture recorded in the Bruker acqus file will be used.
4. Use the various text fields and caret buttons menus
to adjust the conversion parameters. In particular,
selecting from the "Observe Frequency" menus will adjust
not only the observe frequencies, but also the carried
ppm positions and the axis labels.
5. Make any desired final adjustments to the parameters;
the script displayed in the text window can also be
edited directly if desired. It is recommended that the
axis names be reviewed and adjusted so that each one is
unqiue.
6. Use the "Save Script" command to save the conversion
script, and the "Execute Script" to perform the conver-
sion.
VARIAN DATA FORMATS
The Varian conversion program supports two-byte and
four-byte integer data formats, as well as four-byte float-
ing point data format. In many cases, var2pipe can select
the correct data format automatically by interpreting the
binary header of the Varian "fid" file. As a convenience,
the -info flag can be used to display the Varian header
information without actually performing a conversion, for
example:
var2pipe -in fid -info
Automatic extraction of format information can be suppressed
by the -nohdr flag. In this case, format information should
be supplied explicitly via flags -short (two-byte data),
-long (four-byte data), -i2r (integer data), -noi2r (float-
ing point data), or -dsp (same as -noi2r).
In the case of 3D and 4D data, the Varian spectrometer can
support many possible acquisition orders. However, the
var2pipe conversion program only supports two general cases.
By default, the conversion program assumes that all the
phases are incremented in the inner loops of the pulse
sequence, and that the order of the phase loops is the same
as the order of the time loops. In Varian nomenclature,
this is specified as: "d3,d2,phase2,phase" for 3D data, and
"d4,d3,d2,phase3,phase2,phase" for 4D data. The correspond-
ing var2pipe option is "-aqORD 0", which is the default.
In the other case, specified by adding "-aqORD 1" to the
conversion command, the order of the phases is taken to be
opposite to the order of the time increments:
"d3,d2,phase,phase2" for 3D data, and
"d4,d3,d2,phase,phase2,phase3" for 4D data.
Varian's sensitivity or gradient enhanced data can be con-
verted by use of an additional data shuffling macro along
with var2pipe. More details are given in the EXAMPLES sec-
tion, in the description of Rance and Rance-Kay mode data
conversion. See also the manual page for the nmrPipe Macro
function MAC.
VARIAN CONVERSION INTERFACE
The command "varian" will activate a Tcl/Tk-based graphical
interface which can be used to assist in the creation of
conversion scripts. This interface expects that the Varian
"pprocpar" file is available in the same directory as the
"fid" file:
1. Enter the command varian at the command-line; after a
moment the graphical interface will appear.
2. Specify the Spectrometer Input: by default, this will
be set to "fid" if the fid file is found in the current
directory. If the fid file is not in the current direc-
tory, use the caret button next to the "Spectrometer
Input" field; this will create a File Selection window,
which can be used to locate and select the "fid" input
file. In addition, the "CD" button in the File Selec-
tion window can be used to change the working directory
where the conversion script will be saved and executed.
3. Click the "Read Parameters" button; the interface
will attempt to read the "procpar" file. It will then
attempt to extract and display the conversion parame-
ters. Parameters which are likely to need adjustment
will be hilighted.
If the X-Axis "Center Position" is initially given as
"H2O", carrier ppm positions will be computed assuming
that the directly-detected dimension is centered at the
water resonance. The ppm position of the water signal
is computed according to the temperature. If the tem-
perature is initially given as "From File", the tempera-
ture recorded in the "procpar" file will be used.
4. Use the various text fields and caret buttons menus
to adjust the conversion parameters. In particular,
selecting from the "Observe Frequency" menus will adjust
not only the observe frequencies, but also the carried
ppm positions and the axis labels.
5. Make any desired final adjustments to the parameters;
the script displayed in the text window can also be
edited directly if desired. It is recommended that the
axis names be reviewed and adjusted so that each one is
unqiue.
6. Use the "Save Script" command to save the conversion
script, and the "Execute Script" to perform the conver-
sion.
CONVERSION OF IMAGE DATA
Parameters are used and interpreted somewhat differently for
conversion of image data. Consider the following script,
which shows the conversion for a SPIFF format spectral
image:
#!/bin/csh
bin2pipe -in ./d0520c.seq -swap -bo 1024 \
-xN 316 -yN 247 -zN 559 \
-xT 316 -yT 247 -zT 559 \
-xMODE Real -yMODE Real -zMODE Real \
-xSW 5.000e-01 -ySW 5.000e-01 -zSW 1.184e+14 \
-xOBS 1.000 -yOBS 1.000 -zOBS 1.000 \
-xCAR 0.000e+00 -yCAR 0.000e+00 -zCAR 1.184e+14 \
-xFT Freq -yFT Freq -zFT Time \
-xLAB X -yLAB Y -zLAB IR \
-ndim 3 -aq2D Image \
-out d0520c/ir%03d.dat -verb -ov
In this case, the X-Axis and Y-Axis are spatial dimensions,
and the Z-Axis is an unprocessed infrared spectral dimen-
sion. When specifying conversion parameters for a spatial
dimension, the width parameter (-xSW or -ySW here) is speci-
fied in millimeters, and the OBS and CAR parameters are
ignored. Furthermore, the Fourier domain argument (-xFT or
-yFT here) is given explicitly as "Freq" for each spatial
axis. Finally, the 2D Plane type is given as "Image".
OTHER DATA FORMATS
Other data formats may be accommodated by the bin2pipe pro-
gram, which can convert sequentially stored four-byte real
or integer data. In the case of 2D, 3D, and 4D data, the
bin2pipe program assumes the same acquisition order as the
bruk2pipe program does. Non-default acquisition orders can
be accommodated via use of macro functions; in par-
ticular this will be required for recent types of Chemagnet-
ics data, which have a highly unusual format. (see the EXAM-
PLES section).
The bin2pipe program includes options to skip past any
header information which is recorded at the start of the
input file, or between each 1D vector of the input. It is
generally up to the user to determine the sizes of the
header information to be skipped (the byte offset). Several
flags are provided to establish useful default settings (use
bin2pipe -help to display the details):
oooooooo ooooooooooooooooo oooooooooooooooooooooooooooo
FLAG DATA SOURCE COMMENTS
oooooooo ooooooooooooooooo oooooooooooooooooooooooooooo
-alpha JEOL Alpha V1.8 Header size 8704 bytes
-alpha2 JEOL Alpha V2.0 Header size 16384 bytes
-lambda JEOL Lambda Finds offset automatically
-gsx JEOL EX or GSX May require two input files
-chem Chemagnetics
-ge GE Float Export
-ftOLD FTNMR Old Format Required byte offset varies
-ftNEW FTNMR New Format Required byte offset varies
oooooooo ooooooooooooooooo oooooooooooooooooooooooooooo
The flags above provide default settings for the following
options:
-bo: Defines the number of bytes to skip at the beginning of
the input data. In cases where this can be determined
automatically, use a byte offset of -1. Currently,
only the -lambda format supports automatic determina-
tion of byte offset.
-bp: Defines the number of bytes to skip between adjacent 1D
vectors in the input data.
-ri: Enables separation of interleaved real and imaginary
data points in 1D vectors from the input.
-i2r:
Enables conversion of integer input data.
-pad:
Pads missing input data with zeros, in case the input
is smaller than required by the conversion parameters.
-il: Indicates that the input data consists of a series of
2D planes which must be interleaved. This option is
set automatically when bin2pipe is used with two input
names rather than one. The interleave mode is used to
accommodate JEOL GSX and similar formats, which acquire
phase-sensitive 2D data as pairs of complex 2D files.
See the EXAMPLES section below for more.
OTHER OPTIONS
-noIn
(bin2pipe only) This flag will allow the conversion
program to operate without an input file; the input
data will instead be all zeros.
-noOut
(bin2pipe only) This flag will allow the conversion
program to operate without writing output data; only
the header information will be written. It is intended
as a method to create valid headers for other purposes.
-nofs
This flag will suppress any file-size checking of input
or output files (e.g. testing for sufficient disk
space). It is included to accommodate cases where
file-size checking may fail.
-nodir
This flag will suppress automatic directory creation
for output files. It is included to accommodate cases
where automatic creation may fail.
-verb
If this option is used, the conversion program will
print status messages during execution; the status mes-
sages are sent to standard error.
EXAMPLES
The following shows a typical 1D conversion:
#!/bin/csh
var2pipe -in /u1/grahn/n2160.fid/fid \
-xN 32000 \
-xT 16000 \
-xMODE Complex \
-xSW 4000.0 \
-xOBS 499.0 \
-xCAR 4.66 \
-xLAB 1H \
-ndim 1 \
-out hans.n2160.fid -ov -verb
The following four examples show the effect of acquisition
modes on the conversion parameters; note the changes in
time-domain and actual sizes, as well as definition of the
-aq2D parameter.
Example 1: Complex-Complex
#!/bin/csh
bruk2pipe -in hsqcn.ser \
-xN 2048 -yN 256 \
-xT 1024 -yT 128 \
-xMODE Complex -yMODE Complex \
-xSW 9090.91 -ySW 2500.00 \
-xOBS 600.138 -yOBS 60.8108 \
-xCAR 4.73 -yCAR 118.0 \
-xLAB HN -yLAB N \
-ndim 2 -aq2D States \
-out hsqcn.fid -verb -ov
Example 2: Bruker Sequential-Complex
#!/bin/csh
bruk2pipe -in hsqcn.ser \
-xN 2048 -yN 256 \
-xT 2048 -yT 128 \
-xMODE Sequential -yMODE Complex \
-xSW 9090.91 -ySW 2500.00 \
-xOBS 600.138 -yOBS 60.8108 \
-xCAR 4.73 -yCAR 118.0 \
-xLAB HN -yLAB N \
-ndim 2 -aq2D States \
-out hsqcn.fid -verb -ov
Example 3: Bruker Sequential-TPPI
#!/bin/csh
bruk2pipe -in hsqcn.ser \
-xN 2048 -yN 256 \
-xT 2048 -yT 256 \
-xMODE Sequential -yMODE TPPI \
-xSW 9090.91 -ySW 2500.00 \
-xOBS 600.138 -yOBS 60.8108 \
-xCAR 4.73 -yCAR 118.0 \
-xLAB HN -yLAB N \
-ndim 2 -aq2D TPPI \
-out hsqcn.fid -verb -ov
Example 4: Complex-TPPI
#!/bin/csh
bruk2pipe -in hsqcn.ser \
-xN 2048 -yN 256 \
-xT 1024 -yT 256 \
-xMODE Complex -yMODE TPPI \
-xSW 9090.91 -ySW 2500.00 \
-xOBS 600.138 -yOBS 60.8108 \
-xCAR 4.73 -yCAR 118.0 \
-xLAB HN -yLAB N \
-ndim 2 -aq2D TPPI \
-out hsqcn.fid -verb -ov
The following example shows conversion of 2D magnitude-mode
data; an example of processing is given in the manual page
for the nmrPipe function FT. In the case of magnitude-mode
conversion, the option -aq2D Magnitude is used, along with
the -yMODE Real option. The setting for -xMODE will depend
on the data, but the value will usually be "Complex" or
"Sequential".
#!/bin/csh
bruk2pipe -in ser \
-xN 1024 -yN 256 \
-xT 512 -yT 256 \
-xMODE Complex -yMODE Real \
-xOBS 600.144989 -yOBS 600.144989 \
-xSW 21008.4004 -ySW 21008.4004 \
-xCAR 4.9 -yCAR 4.9 \
-xLAB F2 -yLAB F1 \
-ndim 2 -aq2D Magnitude \
-out test.fid -verb -ov
The following example shows conversion of a 2D input which
was already converted for use with other software. Note
that this type of conversion may also require adjustment of
the byte-offset value, which can be specified by the option
-bo:
#!/bin/csh
bin2pipe -in tttt5.dat \
-xN 2048 -yN 650 \
-xT 2048 -yT 325 \
-xMODE Sequential -yMODE Complex \
-xSW 8000.00 -ySW 8000.00 \
-xOBS 500.00 -yOBS 500.00 \
-xCAR 4.77 -yCAR 4.77 \
-xLAB F2 -yLAB F1 \
-ftNEW -ndim 2 -aq2D States -out test.fid -verb -ov
The following script was used to convert a JEOL Lambda For-
mat DQF COSY. The Lambda conversion option -lambda supports
automatic determination of the byte-offset value, which in
this case was reported as 5632 by bin2pipe:
#!/bin/csh
bin2pipe -lambda -in skpdqf.nmfid \
-xN 1024 -yN 512 \
-xT 512 -yT 256 \
-xMODE Complex -yMODE Complex \
-xSW 6189.4 -ySW 6189.4 \
-xOBS 499.952 -yOBS 499.952 \
-xCAR 5.2 -yCAR 5.2 \
-xLAB F2 -yLAB F1 \
-ndim 2 -aq2D States \
-out skpdqf.fid -verb -ov
The following is an example of JEOL GSX 2D phase-sensitive
conversion. This is a special case, since the input con-
sists of two files which are interleaved during conversion
to form the real and imaginary parts of the Y-Axis:
#!/bin/csh
bin2pipe -in gsx2dnoer.gxd gsx2dnoei.gxd -gsx \
-xN 2048 -yN 1024 \
-xT 1024 -yT 512 \
-xMODE Complex -yMODE Complex \
-xSW 4189.4 -ySW 4189.4 \
-xOBS 399.952 -yOBS 399.952 \
-xCAR 5.2 -yCAR 5.2 \
-xLAB F2 -yLAB F1 \
-ndim 2 -aq2D States \
-out test.fid -verb -ov
The following demonstrates a Bruker DMX (Avance) conversion
for ordinary complex detection (Bruker mode QSIM); note use
of the required -decim parameter, as well as use of the
-noswap flag. The -dspfvs option is omitted here, which
means a default value of 10 will be used because the setting
"-xMODE Complex" is given.
#!/bin/csh
bruk2pipe -in ser -DMX -decim 24 -noswap \
-xN 1024 -yN 256 \
-xT 512 -yT 128 \
-xMODE Complex -yMODE Complex \
-xSW 9259.26 -ySW 1330.23 \
-xOBS 499.53 -yOBS 50.62 \
-xCAR 4.79 -yCAR 116.5 \
-xLAB HN -yLAB N \
-ndim 2 -aq2D States \
-out test.fid -verb -ov
The following demonstrates the corresponding Bruker DMX
conversion for digital quad detection data (Bruker mode
DQD); The -dspfvs option is omitted here, which means a
default value of 11 will be used because the setting "-xMODE
DQD" is given.
#!/bin/csh
bruk2pipe -in ser -DMX -decim 24 -noswap \
-xN 1024 -yN 256 \
-xT 512 -yT 128 \
-xMODE DQD -yMODE Complex \
-xSW 9259.26 -ySW 1330.23 \
-xOBS 499.53 -yOBS 50.62 \
-xCAR 4.79 -yCAR 116.5 \
-xLAB HN -yLAB N \
-ndim 2 -aq2D States \
-out test.fid -verb -ov
The following script shows conversion of 2D data with
specification of the window function and parameters (APOD,
Q1, Q2, Q3), first point scale (C1), and phasing (P0 and
P1). These values can later be extracted and used by includ-
ing the -hdr option with nmrPipe processing functions APOD
and PS, as shown in the processing scheme that follows. Note
that when non-zero phase correction values are specified
during conversion, the given dimension must be processed
with PS -hdr in order for the phase values in the header to
remain accurate after processing.
#!/bin/csh
bruk2pipe -in hsqcn.ser \
-xN 2048 -yN 256 \
-xT 1024 -yT 128 \
-xMODE Complex -yMODE Complex \
-xSW 9090.91 -ySW 2500.00 \
-xOBS 600.138 -yOBS 60.8108 \
-xCAR 4.73 -yCAR 118.0 \
-xLAB HN -yLAB N \
-xAPOD GM -yAPOD SP \
-xQ1 20.0 -yQ1 0.50 \
-xQ2 30.0 -yQ2 0.95 \
-xQ3 0.0 -yQ3 1.0 \
-xC1 0.5 -yC1 1.0 \
-xP0 0.0 -yP0 -90.0 \
-xP1 0.0 -yP1 180.0 \
-ndim 2 -aq2D States \
-out hsqcn.fid -verb -ov
nmrPipe -in hsqcn.fid \
| nmrPipe -fn SOL \
| nmrPipe -fn APOD -hdr \
| nmrPipe -fn ZF -auto \
| nmrPipe -fn FT \
| nmrPipe -fn PS -p0 22 -p1 0.0 -di \
| nmrPipe -fn EXT -left -sw -verb \
| nmrPipe -fn TP \
| nmrPipe -fn APOD -hdr \
| nmrPipe -fn ZF -auto \
| nmrPipe -fn FT \
| nmrPipe -fn PS -hdr -di \
-verb -ov -out test.ft2
The following is a typical 3D conversion; in this example,
the results are stored in the sub-directory "fid", which
will be created automatically if possible:
#!/bin/csh
bruk2pipe -in /dat3/linda/3dnmr/cbcaconh.hiv/1/ser \
-xN 1024 -yN 104 -zN 64 \
-xT 512 -yT 52 -zT 32 \
-xMODE Complex -yMODE Complex -zMODE Complex \
-xSW 7575.76 -ySW 8445.95 -zSW 1515.15 \
-xOBS 500.130 -yOBS 125.76 -zOBS 50.6800 \
-xCAR 4.683 -yCAR 46.0 -zCAR 117.00 \
-xLAB HN -yLAB CACB -zLAB N \
-ndim 3 -aq2D States \
-out fid/test%03d.fid -verb -ov
The following shows use of the generic conversion program
with GE Omega Floating-Point Export format 3D data:
#!/bin/csh
bin2pipe -ge -in hnca-ubicm0.3d.xpt \
-xN 512 -yN 64 -zN 64 \
-xT 256 -yT 32 -zT 32 \
-xMODE Complex -yMODE Complex -zMODE Complex \
-xSW 3521.13 -ySW 1650.000 -zSW 1500.00 \
-xOBS 500.163 -yOBS 50.6807 -zOBS 125.765 \
-xCAR 7.83 -yCAR 118.000 -zCAR 50.00 \
-xLAB HN -yLAB N -zLAB CA \
-ndim 3 -aq2D States \
-out fid/test%03d.fid -verb -ov
In this version of a Varian 3D conversion, the -aqORD param-
eter is used to indicate a non-default data order, which
means that the phase increment loops are nested in the oppo-
site order as the time increment loops. Note that only
var2pipe supports this option.
#!/bin/csh
var2pipe -in varian.fid \
-xN 1024 -yN 128 -zN 64 \
-xT 512 -yT 64 -zT 32 \
-xMODE Complex -yMODE Complex -zMODE Complex \
-xSW 8000.00 -ySW 1500.00 -zSW 1650.000 \
-xOBS 499.843 -yOBS 125.6969 -zOBS 50.6530 \
-xCAR 4.73 -yCAR 175.0 -zCAR 118.00 \
-xLAB HN -yLAB CO -zLAB N \
-ndim 3 -aq2D States -aqORD 1 \
-out fid/test%03d.fid -verb -ov
Any of the conversion commands can have their output piped
directly into a processing pipeline, without the need to
save the converted data on disk. In these cases, the -out
and -ov arguments will be omitted from the conversion com-
mand:
#!/bin/csh
bruk2pipe -in /dat3/linda/3dnmr/cbcaconh.hiv/1/ser \
-xN 1024 -yN 104 -zN 64 \
-xT 512 -yT 52 -zT 32 \
-xMODE Complex -yMODE Complex -zMODE Complex \
-xSW 7575.76 -ySW 8445.95 -zSW 1515.15 \
-xOBS 500.130 -yOBS 125.76 -zOBS 50.6800 \
-xCAR 4.683 -yCAR 46.0 -zCAR 117.00 \
-xLAB HN -yLAB CACB -zLAB N \
-ndim 3 -aq2D States \
| nmrPipe -fn SOL \
| nmrPipe -fn SP -off 0.45 -end 1.00 -pow 2 -c 0.5 \
| nmrPipe -fn ZF -auto \
| nmrPipe -fn FT \
| nmrPipe -fn PS -p0 125.0 -p1 0.0 \
| nmrPipe -fn EXT -left -di -sw \
| nmrPipe -fn TP \
| nmrPipe -fn SP -off 0.45 -end 0.95 -pow 1 -c 0.5 \
| nmrPipe -fn ZF -auto \
| nmrPipe -fn FT \
| nmrPipe -fn PS -p0 0.0 -p1 0.0 -di \
| pipe2xyz -out ft/test%03d.ft2 -x
In addition, any of the conversion commands can read their
input from a pipeline rather than a file. In this example,
the data source is the UNIX zcat program, which creates a
data stream by uncompressing a file previously prepared by
the UNIX compress(1) command:
#!/bin/csh
zcat ser.Z | bruk2pipe \
-xN 1024 -yN 104 -zN 64 \
-xT 512 -yT 52 -zT 32 \
-xMODE Complex -yMODE Complex -zMODE Complex \
-xSW 7575.76 -ySW 8445.95 -zSW 1515.15 \
-xOBS 500.130 -yOBS 125.76 -zOBS 50.6800 \
-xCAR 4.683 -yCAR 46.0 -zCAR 117.00 \
-xLAB HN -yLAB CACB -zLAB N \
-ndim 3 -aq2D States \
-out fid/test%03d.fid -verb -ov
Another situation where pipeline input is useful is the case
where the input data is dispersed over more than one file,
either as part of the planned acquisition scheme, or because
an experiment was stopped prematurely and restarted. In the
following example, a single 3D FID is created by converting
part of the data in file "ser" followed by all of the data
in file "ser2". The UNIX command dd is used to supply
appropriate amounts of data from the two files. Note that
the details of such a scheme will depend on the format and
contents of the input data.
In this case, the input data consists of four-byte words,
with no header or padding. In the scheme, file "ser" sup-
plies data for the first 14 2D planes of the result, and
file "ser2" supplies data for the following 12 2D planes.
The ser data is manipulated in blocks of 2048 bytes
(bs=2048), so that each block corresponds to a 512-point 1D
vector from the data. Therefore, since each 2D plane con-
sists of 256 1D vectors, the conversion requires 256 x 14 of
these vectors from file "ser" (count=3584) followed by 256 x
12 vectors from file "ser2" (count=3072). Note the use of
parentheses "(" and ")" to enclose the dd commands, as well
as the semicolon ";" between commands -- This allows the
enclosed commands to act as a single component of the
conversion pipeline:
#!/bin/csh
(dd if=ser bs=2048 count=3584; \
dd if=ser2 bs=2048 count=3072) \
| bruk2pipe -noswap \
-xN 512 -yN 256 -zN 26 \
-xT 256 -yT 128 -zT 13 \
-xMODE Complex -yMODE Complex -zMODE Complex \
-xSW 5555.555 -ySW 5555.555 -zSW 2604.167 \
-xOBS 500.189 -yOBS 500.189 -zOBS 125.780 \
-xCAR 4.77 -yCAR 4.77 -zCAR 63.7 \
-xLAB H-acq -yLAB H-ind -zLAB C \
-ndim 3 -aq2D States \
-out fid/test%03d.fid -verb -ov
In the following example, a 3D acquisition was intentionally
distributed over a series of 2D file planes 1/ser, 2/ser,
etc. As before, details of the corresponding conversion
scheme will depend on the format and contents of the input
data. In this case, an auxiliary shell-script "catser.com"
is used to create a complete input stream by catenating the
contents of each spectrometer file in turn:
#!/bin/csh
(catser.com ./data 1 148) \
| bruk2pipe -noswap \
-xN 1024 -yN 64 -zN 148 \
-xT 512 -yT 32 -zT 74 \
-xMODE Complex -yMODE Complex -zMODE Complex \
-xSW 9615.385 -ySW 1459.854 -zSW 7204.611 \
-xOBS 600.130 -yOBS 60.811 -zOBS 600.130 \
-xCAR 5.089 -yCAR 116.709 -zCAR 5.089 \
-xLAB HN -yLAB N -zLAB 1H \
-ndim 3 -aq2D States \
-out fid/Nnhsqc%03d.fid -verb -ov
#!/bin/csh
# catser.com: catenate a series of Bruker ser files.
# Usage: catser.com dirName firstSerNumber lastSerNumber
set i = $2
while ($i <= $3)
cat $1/$i/ser
@ i++
end
In another example of pipeline input, the byteAdjust program
is used to pre-convert an image from two-byte data to
four-byte data, so that it can be converted in turn by
bin2pipe:
#!/bin/csh
byteAdjust -in delaglio_fmri -iws 2 -ows 4 -is 65536 \
| bin2pipe -i2r -swap \
-xN 64 -yN 64 \
-xT 64 -yT 64 \
-xMODE Real -yMODE Real \
-xFT Freq -yFT Freq \
-xSW 4000.0 -ySW 4000.0 \
-xCAR 0.00 -yCAR 0.00 \
-xOBS 150.00 -yOBS 150.00 \
-xLAB X -yLAB Y \
-ndim 2 -aq2D Image \
-out image.dat -verb -ov
The following example shows how to convert and process spec-
tra which must be formed from the sum or difference of
alternating rows of the input. In the input data used
below, there are 255 complex t1 increments interleaved with
a second set of 255 complex increments. The goal is to per-
form processing using either the sum or difference of these
two sets, or using just one or the other of these two sets.
In the input, there are a total of 255*2 + 255*2 = 1020
real+imag data points in t1. But, when the data is pro-
cessed in the t1 dimension, it will have only 255 complex
points, because we will first take the sum or difference of
the two interleaved sets. So, for this example -yN (total
points real+imag in file) is 1020, while -yT (length of win-
dow function) is 255.
#!/bin/csh
bruk2pipe -in ser \
-xN 1024 -yN 1020 \
-xT 512 -yT 255 \
-xMODE Complex -yMODE Complex \
-xSW 7246.00 -ySW 5000.0 \
-xOBS 600.13 -yOBS 150.91 \
-xCAR 4.65 -yCAR 43.0 \
-xLAB H -yLAB C \
-ndim 2 -aq2D States \
-bad 0.0 \
-out test.fid -verb -ov
The next step is to process the data; as the first step of
processing, the COADD function will be used to add adjacent
points from the t1 (Y) axis. The pairs of points will be
multiplied by the coefficients given in "-cList" before
adding; "-cList 1 1" forms the sum; "-cList 1 -1" forms the
difference; "-cList 1 0" constructs a spectrum from odd
points in the Y-Axis; "-cList 0 1" constructs a spectrum
from even points in the Y-Axis:
#!/bin/csh
nmrPipe -in test.fid \
| nmrPipe -fn COADD -axis Y -cList 1 1 \
| nmrPipe -fn SP -off 0.5 -end 0.98 -pow 2 -c 0.5 \
| nmrPipe -fn ZF -auto \
| nmrPipe -fn FT \
| nmrPipe -fn EXT -x1 4.3ppm -xn -1.0ppm -sw \
| nmrPipe -fn PS -p0 -9.5 -p1 -14.8 -di -verb \
| nmrPipe -fn TP \
| nmrPipe -fn SP -off 0.3 -end 0.98 -pow 1 -c 0.5 \
| nmrPipe -fn ZF -auto \
| nmrPipe -fn FT \
| nmrPipe -fn PS -p0 5.4 -p1 0 -di -verb \
-verb -ov -out sum.ft2
The following example shows a 4D conversion; the command has
been formatted so that it will display properly with these
manual pages. In actual use, the parameters would probably
be more readable if related parameters were not split
between lines, as in all previous examples.
#!/bin/csh
bruk2pipe -in /spry1/lodi/15N15CNOESY/ser \
-xN 1024 -yN 128 \
-xT 400 -yT 64 \
-xMODE Complex -yMODE Complex \
-xSW 6944.444 -ySW 5555.55 \
-xOBS 500.189 -yOBS 500.189 \
-xCAR 4.754 -yCAR 4.754 \
-xLAB acq1H -yLAB indir1H \
\
-zN 36 -aN 36 \
-zT 18 -aT 18 \
-zMODE Complex -aMODE Complex \
-zSW 2604.16 -aSW 1250.00 \
-zOBS 125.779 -aOBS 50.6894 \
-zCAR 63.709 -aCAR 117.499 \
-zLAB 13C -aLAB 15N \
-ndim 4 -aq2D States \
-out fid/test%03d.fid -verb -ov
The following example shows the conversion scheme above used
with pipe2xyz to generate output files with both an A-Axis
index and a Z-Axis index. The -to 0 (time-out zero) argu-
ment is used to avoid delays between repeated attempts to
read data, which speeds up the conversion process.
#!/bin/csh
bruk2pipe -in /spry1/lodi/15N15CNOESY/ser \
-xN 1024 -yN 128 \
-xT 400 -yT 64 \
-xMODE Complex -yMODE Complex \
-xSW 6944.444 -ySW 5555.55 \
-xOBS 500.189 -yOBS 500.189 \
-xCAR 4.754 -yCAR 4.754 \
-xLAB acq1H -yLAB indir1H \
\
-zN 36 -aN 36 \
-zT 18 -aT 18 \
-zMODE Complex -aMODE Complex \
-zSW 2604.16 -aSW 1250.00 \
-zOBS 125.779 -aOBS 50.6894 \
-zCAR 63.709 -aCAR 117.499 \
-zLAB 13C -aLAB 15N \
-ndim 4 -aq2D States \
| pipe2xyz -out fid/test%02d%03d.fid -x -verb -ov -to 0
The following example shows conversion of 2D Rance-Kay mode
gradient enhanced data. The special data shuffling is per-
formed by pre-processing the converted data via the macro
"ranceY.M", in the "nmrtxt" directory. After conversion,
the gradient dimension can be processed like ordinary com-
plex data. Depending on the acquisition details, other
corrections may also be needed, such as a +/- 90 zero-order
phase correction, negation of imaginaries (for "reversed"
data, FT -neg), or sign alternation (FT -alt). For example,
gradient data (Bruker's echo/anti-echo mode) acquired on a
Bruker spectrometer may have to be converted using a
slightly different macro named "ranceY2.M", or an altered
version of this macro.
The approach below can also be used for 3D and 4D data with
gradient enhanced detection in the Y-Axis. The example
assumes that the $NMRTXT environment variable has been
defined according to the location of the "nmrtxt" directory
in your installation. This can be done by adding a line in
your ".cshrc" file, for example:
setenv NMRTXT /u/NMRPipe/nmrtxt
Once the conversion below is complete, the result can be
processed like an ordinary phase-sensitive spectrum:
#!/bin/csh
var2pipe -in varian.fid \
-xN 2048 -yN 600 \
-xT 1024 -yT 300 \
-xMODE Complex -yMODE Complex \
-xSW 8000.00 -ySW 1650.000 \
-xOBS 499.843 -yOBS 50.6530 \
-xCAR 4.73 -yCAR 118.00 \
-xLAB HN -yLAB N \
-ndim 2 -aq2D States \
| nmrPipe -fn MAC -macro $NMRTXT/ranceY.M -noRd -noWr \
-out test.fid -verb -ov
In addition to the older "manual" method above, the follow-
ing newer scheme can be used. In this scheme, the data type
"Rance-Kay" is used instead of explicitly applying a shuf-
fling macro (type "Echo-AntiEcho" will produce the same
result):
#!/bin/csh
var2pipe -in varian.fid \
-xN 2048 -yN 600 \
-xT 1024 -yT 300 \
-xMODE Complex -yMODE Rance-Kay \
-xSW 8000.00 -ySW 1650.000 \
-xOBS 499.843 -yOBS 50.6530 \
-xCAR 4.73 -yCAR 118.00 \
-xLAB HN -yLAB N \
-ndim 2 -aq2D States \
-out test.fid -verb -ov
3D gradient enhanced data can also be pre-processed during
conversion, using a combination of the MAC function to per-
form the shuffling, and pipe2xyz to write the result.
Depending on whether the Y-Axis or Z-Axis is gradient
enhanced, the macros "ranceY.M" or "ranceZ.M" can be used:
#!/bin/csh
var2pipe -in varian.fid \
-xN 1024 -yN 64 -zN 64 \
-xT 512 -yT 32 -zT 32 \
-xMODE Complex -yMODE Complex -zMODE Complex \
-xSW 8000.00 -ySW 8500 -zSW 1650.000 \
-xOBS 499.843 -yOBS 125.75 -zOBS 50.6530 \
-xCAR 4.73 -yCAR 46.0 -zCAR 118.00 \
-xLAB HN -yLAB CACB -zLAB N \
-ndim 3 -aq2D States -aqORD 1 \
| nmrPipe -fn MAC -macro $NMRTXT/ranceZ.M -noRd -noWr \
| pipe2xyz -out fid/test%03d.fid -x -ov -to 0 -verb
As an easier alternative to a shuffling macro, the data type
"Rance-Kay" (or Echo-AntiEcho) can also be used for the
gradient-enhanced dimension, for example:
#!/bin/csh
var2pipe -in varian.fid \
-xN 1024 -yN 64 -zN 64 \
-xT 512 -yT 32 -zT 32 \
-xMODE Complex -yMODE Complex -zMODE Rance-Kay \
-xSW 8000.00 -ySW 8500 -zSW 1650.000 \
-xOBS 499.843 -yOBS 125.75 -zOBS 50.6530 \
-xCAR 4.73 -yCAR 46.0 -zCAR 118.00 \
-xLAB HN -yLAB CACB -zLAB N \
-ndim 3 -aq2D States -aqORD 1 \
-out fid/test%03d.fid -ov -verb
Rance-mode non-gradient sensitivity enhanced acquisition
requires shuffling of the data such that the given dimension
size is reduced by a factor of two via sums or differences.
By default, the script below performs shuffling in the sum-
mation mode, but if the "-dif" argument is added to the MAC
command-line, the shuffling will be performed in difference
mode. Note that the "-yT" parameter has been set to half the
usual value in anticipation of the size reduction.
Depending on the acquisition details, additional processing
such as zero-order phase correction may also be required,
although these details could also be accommodated by adjust-
ing macro "seY.M". Once the conversion below is complete,
the result can be processed like an ordinary phase-sensitive
spectrum:
#!/bin/csh
bruk2pipe -in hnco.ser -noswap \
-xN 2048 -yN 128 \
-xT 1024 -yT 32 \
-xMODE Complex -yMODE Complex \
-xSW 9615.3846 -ySW 1250.000 \
-xOBS 600.13 -yOBS 60.810 \
-xCAR 4.677 -yCAR 116.5 \
-xLAB HN -yLAB N \
-ndim 2 -aq2D States \
| nmrPipe -fn MAC -macro $NMRTXT/seY.M -noRd -noWr -all \
-out test.fid -ov -verb
Processing macros can also be used to compensate for
non-default acquisition and storage orders of real and ima-
ginary data. Recently, Chemagnetics introduced a data for-
mat where the corresponding real and imaginary parts of a
given directly-acquired 1D vector are stored in distantly
separated parts of the input file, rather than near each
other. The following script uses macro "rrii.M" to shuffle
the data into the usual hypercomplex data order:
#!/bin/csh
bin2pipe -in data -chem -noswap \
-xN 512 -yN 128 \
-xT 256 -yT 64 \
-xMODE Complex -yMODE Complex \
-xSW 3333.000 -ySW 3333.000 \
-xOBS 100.4005 -yOBS 100.4005 \
-xCAR 0.0 -yCAR 0.0 \
-xLAB F2 -yLAB F1 \
-ndim 2 -aq2D States \
| nmrPipe -fn MAC -macro $NMRTXT/rrii.M -noRd -noWr \
-out test.fid -ov -verb
The following script was used to convert 3D data acquired in
a particular format on a Chemagnetics spectrometer to the
required interleaved complex 3D format. The details are
described in the macro file "shuf3D.M":
#!/bin/csh
bin2pipe -in d -chem \
-xN 256 -yN 160 -zN 160 \
-xT 128 -yT 80 -zT 80 \
-xMODE Complex -yMODE Complex -zMODE Complex \
-xSW 12500.00 -ySW 10000.00 -zSW 10000.000 \
-xOBS 100.3896 -yOBS 100.3896 -zOBS 100.3896 \
-xCAR 45 -yCAR 45.0 -zCAR 45.0 \
-xLAB F3 -yLAB F1 -zLAB F2 \
-ndim 3 -aq2D States \
| nmrPipe -fn MAC -macro shuf3D.M -noRd -noWr \
| pipe2xyz -out fid/test%03d.fid -verb -ov -to 0
SEE ALSO
FT(1), HT(1), MAC(1), byteAdjust(1), byteSwap(1),
nmrPipe(1), scale2D(1), sethdr(1), showhdr(1), xyz2pipe(1)
BUGS
Some conversion parameters are redundant.
The conversion programs will not issue a warning message if
the input data is larger than the conversion settings indi-
cate.
Rance-mode sensitivity enhanced data is not handled directly
by the conversion programs, and requires special handling.
No A-Axis Rance-mode handling is provided.
The conversion programs will not easily convert a sub-set of
the input or output data.
DIAGNOSTICS
All help text, informational messages, and error messages
are sent to standard error. Many error messages are
intended to be self-explanatory, but some are included for
development and testing purposes. Some common problems
include:
C-Shell: conversion scripts must be explicitly identi-
fied as C-shell scripts in order to run properly. They
should always begin with the following text as the first
characters of the first line:
#!/bin/csh
Data Sizes: first-time users of the conversion programs
often specify dimension sizes which are a factor of two
different from what the correct parameters should be.
Byte-Swap: depending on the computer platforms involved,
spectrometer format data may require each four-bytes of
input to be reversed before conversion. This is called
byte-swapping. It can be enabled or suppressed via the
-swap and -noswap flags. Having the byte-swap mode set
incorrectly will cause large numbers of "Bad Points".
Continuation Characters: a common problem encountered
when using pipeline processing schemes concerns the use
of the backslash character "\" to continue a command
onto the next line of a shell-script. This use of the
backslash character will only work correctly if there
are no trailing blank characters at the end of the line.
Input/Output: problems here include use of an input file
or input directory that doesn't exit, or use of an out-
put directory that can't be created. Failure to omit
the -out argument when sending output directly to a
pipeline will also cause problems.
LEGAL NOTICE
This program and its related software is provided "as
is". The NIH, the Laboratory of Chemical Physics, NIDDK,
and the authors make no warranties, either express or
implied, as to any matter whatsoever with respect to
the software. In particular, any and all warranties of
merchantability and fitness for any particular purpose are
expressly excluded. In no event will the NIH, the Labora-
tory of Chemical Physics, NIDDK, or the authors be liable
for any loss of profits, any incidental, special, exem-
plary, or consequential damages of any nature whatsoever
(including without limitation, loss of use or other com-
mercial or research loss) arising out of or relating to
the use or performance of the software.