NMRPipe Processing Functions

 Flag Argument Default Description ` -cList` `clist` `1 1` Coefficient List. ` -axis` `aName` `X` X: Co-Add Points. Y: Co-Add Slices.
 ` -time` Adjust valid time-domain size in header to account for reduction in data size.

The COADD function is commonly applied to interleaved data such as In-Phase/Anti-Phase (IPAP) experiments, where it is used to either combine interleaved data by addition or subtraction, or simply to extract a given component of the interleaved data. Data separated in this way can later be re-combined by the program addNMR which can form sums and differences of NMRPipe-format data files.

COADD works by reducing a spectrum or FID by summing groups of two or more points within each 1D vector (`-axis X`) or by summing two or more adjacent 1D vectors (`-axis Y`).

Before summation, the data is multiplied by the coefficients given by "-cList" before summation. So for example:

```           | nmrPipe -fn  COADD -axis Y -cList 1 -1 -time \
```

will form a spectrum from the difference of each pair of adjacent 1D slices. The "-time" argument is used to reduce the recorded number of valid time-domain points according to the reduction in the output data size.

PROCESSING INTERLEAVED DATA WITH FUNCTION COADD

In the input data used for this example, there are 255 complex t1 increments interleaved with a second set of 255 complex increments. The goal is to make 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 we process the data in the t1 dimension, we 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 the corresponding window function) should be 255, rather than the default value of 510.

There are two ways to accommodate this factor-of-two difference in the final result. One way is simply to manually change the conversion parameters so that "-yT 255" is given. The more common way however is to use the `COADD -time` option, which will reduce time-domain size parameter automatically according to the number of values given for `-cList` coefficient list.

```       bruk2pipe -in ser \
-xN           1024    -yN         1020   \
-xT            512    -yT          510   \
-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   \
-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 points from the t1 (Y) axis. The pairs of points will be multiplied by the coefficients given in "-cList" before adding:
```       nmrPipe -in test.fid                                             \
| nmrPipe  -fn COADD -axis Y -cList 1  1 -time                   \
| 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                        \
| nmrPipe  -fn TP                                                \
| nmrPipe  -fn POLY -auto                                        \
-verb -ov -out sum.ft2
```
Alternatively, we can change the coefficients, so that we form the difference between adjacent t1 points instead of the sum; the rest of the processing stays the same:
```       nmrPipe -in test.fid                                             \
| nmrPipe  -fn COADD -axis Y -cList 1 -1 -time                   \
.
.
.
| nmrPipe  -fn POLY -auto                                        \
-verb -ov -out dif.ft2
```
Again, we can change the coefficients this time to process only the odd t1 points:
```nmrPipe -in test.fid                                             \
| nmrPipe  -fn COADD -axis Y -cList 1  0 -time                   \
.
.
.
-verb -ov -out odd.ft2
```
Or the even ones:
```nmrPipe -in test.fid                                             \
| nmrPipe  -fn COADD -axis Y -cList 0  1                         \
.
.
.
-verb -ov -out even.ft2
```

We can also recombine the two separate results using the addNMR program. In this example, we create a new result which consists of odd + 1.2*even:

```       addNMR -in1 odd.ft2 -in2 even.ft1 -c1 1.0 -c2 1.2 -add -out wsum.ft2
```

In addition, the COADD function can also be used directly during conversion, for instance in this case to generate a converted FID which selects only the odd-numbered interleaved channels:

```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   \
| nmrPipe  -fn COADD -axis Y -cList 1  0   \
-out odd.fid -verb -ov
```
INTERLEAVED DATA WITH GRADIENT ENHANCEMENT In NMRPipe, gradient enhanced time-domain data is converted to a conventional complex format by use of a shuffling macro. The shuffling macro can be inserted into a conversion or processing script, for example, this command will adjust gradient data in the Y-Axis of Bruker data:
```   | nmrPipe -fn MAC -macro \$NMRTXT/bruk_ranceY.M -noRd -noWr \
```
There are corresponding shuffling macros for Varian data, for example:
```   | nmrPipe -fn MAC -macro \$NMRTXT/var_ranceY.M  -noRd -noWr \
```
These shuffling macros will be applied automatically if the given dimension is converted with either the "Echo-AntiEcho" or "Rance-Kay" keyword (the two keywords perform the same action). For example, the following two conversion commands are equivalent:
```bruk2pipe -in ser -bad 0.0 -noaswap -DMX -decim 16 -dspfvs 12  \
-xN              2048  -yN               512  \
-xT              1024  -yT               256  \
-xMODE            DQD  -yMODE        Complex  \
-xSW        10000.000  -ySW         1724.138  \
-xOBS         600.141  -yOBS          60.819  \
-xCAR           4.773  -yCAR         118.367  \
-xLAB              HN  -yLAB               N  \
-ndim               2  -aq2D          States  \
| nmrPipe -fn MAC -macro \$NMRTXT/bruk_ranceY.M -noRd -noWr \
-out test.fid -verb -ov

bruk2pipe -in ser -bad 0.0 -noaswap -DMX -decim 16 -dspfvs 12  \
-xN              2048  -yN               512  \
-xT              1024  -yT               256  \
-xMODE            DQD  -yMODE      Rance-Kay  \
-xSW        10000.000  -ySW         1724.138  \
-xOBS         600.141  -yOBS          60.819  \
-xCAR           4.773  -yCAR         118.367  \
-xLAB              HN  -yLAB               N  \
-ndim               2  -aq2D          States  \
-out test.fid -verb -ov
```

The gradient shuffling macros assume that adjacent groups of data should be combined to form real and imaginary parts of the result. For example, for Y-Axis gradient data, the shuffling macro assumes that pairs of adjacent 1D complex vectors should be combined to form one complex vector which is a Y-Axis real point, and a second complex vector is the the corresponding Y-Axis imaginary point.

However, if the data are both gradient enhanced and interleaved, depending on the acquisition scheme, the interleaved data must be accommodated before gradient shuffling can be performed. This will be the case for acquisition schemes where the loop which performs interleaving is "inside" the loop which performs gradient enhanced detection. For such cases, we first use COADD to extract one channel of the interleaved data, and send the result through a gradient shuffling macro. Here is such a case for 3 interleaved 3D experiments with gradient enhanced detection in the Y-Axis.

```   #!/bin/csh

set tauList = (0.00193 0.00373 0.00722)

zcat ser.Z | bruk2pipe -tau \$tauList[1] \
-bad 0.0 -noswap -DMX -decim 24 -dspfvs 12  \
-xN              1024  -yN               270  -zN               122  \
-xT               512  -yT               135  -zT                61  \
-xMODE            DQD  -yMODE        Complex  -zMODE        Complex  \
-xSW         8012.821  -ySW         1666.667  -zSW         9090.909  \
-xOBS         600.141  -yOBS          60.819  -zOBS         150.911  \
-xCAR           4.840  -yCAR         117.640  -zCAR          46.159  \
-xLAB              1H  -yLAB             15N  -zLAB             13C  \
-ndim               3  -aq2D          States                         \
| nmrPipe -fn COADD -cList 1 0 0 -axis Y -time                         \
| nmrPipe -fn MAC -macro \$NMRTXT/bruk_ranceY.M -noRd -noWr             \
| pipe2xyz -x -out ./fidA/test%03d.fid -verb -ov

zcat ser.Z | bruk2pipe -tau \$tauList[2] \
-bad 0.0 -noswap -DMX -decim 24 -dspfvs 12  \
-xN              1024  -yN               270  -zN               122  \
-xT               512  -yT               135  -zT                61  \
-xMODE            DQD  -yMODE        Complex  -zMODE        Complex  \
-xSW         8012.821  -ySW         1666.667  -zSW         9090.909  \
-xOBS         600.141  -yOBS          60.819  -zOBS         150.911  \
-xCAR           4.840  -yCAR         117.640  -zCAR          46.159  \
-xLAB              1H  -yLAB             15N  -zLAB             13C  \
-ndim               3  -aq2D          States                         \
| nmrPipe -fn COADD -cList 0 1 0 -axis Y -time                         \
| nmrPipe -fn MAC -macro \$NMRTXT/bruk_ranceY.M -noRd -noWr

zcat ser.Z | bruk2pipe -tau \$tauList[3] \
-bad 0.0 -noswap -DMX -decim 24 -dspfvs 12  \
-xN              1024  -yN               270  -zN               122  \
-xT               512  -yT               135  -zT                61  \
-xMODE            DQD  -yMODE        Complex  -zMODE        Complex  \
-xSW         8012.821  -ySW         1666.667  -zSW         9090.909  \
-xOBS         600.141  -yOBS          60.819  -zOBS         150.911  \
-xCAR           4.840  -yCAR         117.640  -zCAR          46.159  \
-xLAB              1H  -yLAB             15N  -zLAB             13C  \
-ndim               3  -aq2D          States                         \
| nmrPipe -fn COADD -cList 0 0 1 -axis Y -time                         \
| nmrPipe -fn MAC -macro \$NMRTXT/bruk_ranceY.M -noRd -noWr             \
| pipe2xyz -x -out ./fidC/test%03d.fid -verb -ov
```
DATA WITH MANY INTERLEAVED VALUES In this example, there are 16 interleaved 2D planes in the given gradient-enhanced data, with tau values which in this case can be calculated from the contents of the spectrometer file "vclist". In this scheme, the COADD `-cList` argument is built "automatically" as 1.0 in one position and zero everywhere else, and the position of the non-zero value is changed over the course of a loop.
```   bruk2pipe -in \$d/ser -bad 0.0 -noaswap -DMX -decim 24 -dspfvs 12 \
-xN              1024  -yN              4000  \
-xT               512  -yT               125  \
-xMODE            DQD  -yMODE  Echo-AntiEcho  \
-xSW         8012.821  -ySW         5000.000  \
-xOBS         600.141  -yOBS         150.917  \
-xCAR           4.754  -yCAR           00.00  \
-xLAB              1H  -yLAB             13C  \
-ndim               2  -aq2D          States  \
-verb -ov -out ./test.fid

#!/bin/csh

if (!(-d ft)) then
mkdir ft
endif

set tauList = ""
set cList   = ""

foreach vc (`cat vclist`)
set tauList = (\$tauList `MATH 20\*\$vc`)
set cList   = (\$cList 0)
end

nmrPipe -in test.fid \
| nmrPipe -fn SP -off 0.5 -pow 2 -end 0.99 -c 0.5 \
| nmrPipe -fn ZF -size 2048 \
| nmrPipe -fn FT -auto \
| nmrPipe -fn PS -p0 -89 -p1 -28.4  -di \
| nmrPipe -fn POLY -auto -ord 2 \
| nmrPipe -fn EXT -x1 3.5ppm -xn 6.5ppm -sw -verb \
| nmrPipe -fn TP \
-out test.ft1 -ov

set i = 1

foreach tau (\$tauList)
set cList[\$i] = 1
set outName   = `printf ft/relax%03d.ft2 \$i`

echo \$outName \$tau

nmrPipe -in test.ft1 \
| nmrPipe -fn COADD -axis X -cList \$cList \
| nmrPipe -fn SP -off 0.5 -pow 2 -end 0.99 -c 0.5 \
| nmrPipe -fn ZF -size 2048 \
| nmrPipe -fn FT -neg \
| nmrPipe -fn PS -p0 14.6 -p1 -26.2  -di \
| nmrPipe -fn POLY -auto -ord 2 \
| nmrPipe -fn EXT -x1 -8ppm -xn 8ppm -sw -verb   \
-ov -out \$outName

sethdr \$outName -tau \$tau

set cList[\$i] = 0
@ i++
end
```
Since it reduces the size of the data, the COADD function will adjust NDSIZE accordingly. The the `-time` flag is given, it will also update the time-domain size values NDAPOD and NDTDSIZE.