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.