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.