Command reference

Command line help

The following is the output of NESTANMR -h. These flags are explained in more detail in the next section.

************************************************************************************
*                                   NESTA-NMR v1.5                                 *
*     Shangjin Sun, Michelle Gill, Yifei Li, Mitchell Huang, and R. Andrew Byrd    *
*                         Structural Biophysics Laboratory                         *
*                            National Cancer Institute                             *
*                               Frederick, MD 21702                                *
*                                                                                  *
*              Use of NESTA-NMR implies acceptance of the user license             *
************************************************************************************

    Flag           Argument        Information
=============   ==============   ===================================================

-f, --fids         TEMPLATE        Template for input data from NMRPipe
                                   DEFAULT: ./ft/test%04d.dat

-n, --nuslist      FILE            Path to the nuslist
                                   DEFAULT: ./nuslist

-d, --outdir       DIRECTORY       Output directory
                                   DEFAULT: ./nesta

-o, --outname      FILE            Basename for output files
                                   DEFAULT: test

-t, --threads      INTEGER         Number of regularization threads to use
                                   DEFAULT: Determine # CPUs otherwise 1

-m, --method       INTEGER         Regularization method: L1/IRL1 or Gaussian-SL0
                                   Set to 1 for L1/IRL1 or 0 for Gaussian-SL0
                                   DEFAULT: 1

-i, --iter         INTEGER         Maximum number of iterations for regularization
                                   For L1/IRL1 regularization, suggested range is 10-50
                                   For Gaussian-SL0, suggested range is >= 5000
                                   DEFAULT: 30 for L1/IRL1, 5000 for Gaussian-SL0

-r, --rwiter       INTEGER         Number of re-weighted iterations for IRL1 regularization
                                   Improved results, but longer computation time
                                   Suggested range is 2-10, no re-weighting done when <= 1
                                   DEFAULT: 1

-s, --scaling      FLOAT           Scaling value for Gaussian-SL0 optimization.
                                   Suggested range is 0.98-0.99.
                                   Iterations should increase if scaling is set to 0.99.
                                   DEFAULT: 0.98

-c, --cutoff       FLOAT           Cutoff value for Gaussian-SL0 optimization
                                   DEFAULT: 0.1

-a, --alt          CHAR(S)         Set TPPI sign alternation in appropriate dimensions
                                   Dimensions are a case insensitive string of characters:
                                   e.g. yza for all three indirect dimensions.
                                   DEFAULT: no sign alternation (for States or Rance-Kay)
                                   NOTE: only valid for sparse data, will soon be removed

-y, --sizeY        INTEGER         Increase number of points in Y-dimension
                                   DEFAULT: max value from nuslist
                                   NOTE: only valid for sparse data, will soon be removed

-z, --sizeZ        INTEGER         Increase number of points in Z-dimension
                                   DEFAULT: max value from nuslist
                                   NOTE: only valid for sparse data, will soon be removed

-l, --sizeA        INTEGER         Increase number of points in A-dimension
                                   DEFAULT: max value from nuslist
                                   NOTE: only valid for sparse data, will soon be removed

-b, --keepnesta                    Flag to preserve intermediate NESTA-NMR files
                                   DEFAULT: delete intermediate files

-v, --version                      Show version number and quit

-q, --quiet                        Flag to suppress printing of command line output
                                   except error messages.
                                   DEFAULT: print some program, variable,
                                   and progress information.

-u, --unexpanded                   Flag to indicate that sparse input data are used
                                   DEFAULT: use input data that are expanded (not sparse)
                                   NOTE: this option will soon be removed

-h, --help                         Show this help information and quit

Command list

Input flags

-f, –fids

Set the template specifying the input data files. NESTA-NMR uses NMRPipe-style templates where ./ft/test%04d.dat indicates data are called test0001.dat, test0002.dat, etc. The default template is ./ft/test%04d.dat. For 4D data, this may need to be increased, per the number of NUS points. The value should match that used in the pipe2xyz command of the fid.com file.

-n, –nuslist

Set the path to the NUS sampling schedule. This default path is ./nuslist

Output flags

-d, –outdir

Set the directory for all of the output files, including the reconstructed NMRPipe files and logfiles from NESTA-NMR reconstruction. If –keepnesta is used (see below), the intermediate NESTA-NMR data files will also be preserved in this directory. The default directory is ./nesta.

-o, –outname

Set the basename for the output files. If the basename is set to test, the output files will be created in the directory specified by –outdir and will be called test.ft1 for 2D data. For 3D/4D data, the numerical template, e.g. text%04d.ft1, is determined from the template of the input data. The default basename is test. NESTA-NMR uses the suffix ft1 for reconstructed data.

Parallel processing flags

-t, –threads

The number of threads to use during multi-threaded processing. If not set, NESTA-NMR attempts to determine how many cores the computer reports. If this fails, it will default to 1.

Regularization flags

-m, –method

The regularization method, either 1 for L1/IRL1 or 0 for Gaussian-SL0. The default is 1 for L1/IRL1.

-i, –iter

The maximum number of iterations used by NESTA-NMR. The default is 30 for L1/IRL1, and 5000 for Gaussian-SL0. For L1/IRL1, suggested ranges are 10-30. For Gaussian-SL0, 5000 iterations are recommended if scaling is set to 0.98, but iterations should increase if scaling is set to 0.99 (see below).

-r, –rwiter

The number of re-weighted iterations, which applies to L1/IRL1 only. If set to \(\le\) 1, no re-weighting is used (L1). If the value is > 1, re-weighting is used (IRL1).

-s, –scaling

The scaling factor, used for Gaussian-SL0 regularization only. Should be either 0.98 or 0.99. The number of iterations (iter) should increase (> 5000) if set to 0.99. Default is 0.98.

-c, –cutoff

The cutoff threshold, used for Gaussian-SL0 regularization only. Default is 0.1

Sign alternation flags

-a, –alt

NOTE: as described in the section on expanded data, the functionality of the –alt flag is now handled during conversion by nusExpand.tcl. Thus, the –alt flag will soon be removed from NESTA-NMR

If States-TPPI has been used for frequency discrimination in any of the dimensions, the appropriate header flag can be set by NESTA-NMR. Dimensions requiring sign alternation are entered as a single, case sensitive string. For example, –alt yza and –alt ayz and –alt yZa will all set sign alternation in the Y-, Z-, and A-dimensions of a 4D experiment.

If this flag is set for the appropriate dimension, NMRPipe will automatically handle sign alternation during Fourier transformation with NMRPipe (see the processing section) by using FT -auto. If the flag is not set during reconstruction, sign alternation can instead be forced during Fourier transformation by using FT -alt.

For Rance-Kay, no flag needs to be set, but the appropriate conversion must be made during processing of the direct dimension (see the section on conversion with Rance-Kay). For States, no flag needs to be set and no additional changes are required.

Data size flags

-b, –sizeY, -c, –sizeZ, and -e, –sizeA

NOTE: as described in the section on expanded data, the functionality of the –sizeY, –sizeZ, and –sizeA flags is now handled during conversion by nusExpand.tcl. Thus, these flags will soon be removed from NESTA-NMR.

Set the maximum number of reconstructed points in each of the respective dimensions. This is only necessary if it is desirable to reconstruct data beyond the largest NUS point for a respective dimension. The default value is set based on the maximum in the NUS sampling schedule. If flags are set with values less than the maximum in the sampling schedule, they will be ignored.

Other flags

-u, –unexpanded

Add this flag to reconstruct sparse (unexpanded) data with NESTA-NMR. The default is now to assume the data are expanded with nusExpand.tcl as described in the expanded data section. This functionality will soon be removed.

-k, –keepnesta

Add this flag to keep the intermediate NESTA-NMR files, *.nestain and *.nestaout. They are deleted by default.

-v, –version

Print the version number and quit.

-q, –quiet

Flag to suppress printing of all command line information except error messages.

-h, –help

Print the help message listed above and quit.

nusExpand.tcl reference

The expansion of NUS data into a zero-filled, full-sized matrix and creation of a data mask is accomplished with the NMRPipe function nusExpand.tcl. The full list of commands can be determined from the help for the function, which is accessed with nusExpand.tcl -help, however basic usage is described in this section.

The function requires the following:

-mode

An input mode, which is bruker, varian, or pipe

-in

The name of the data input file, usually ser or fid, or stdin if the data are to be read from stdin using xyz2pipe.

-out

The name of the output file, which can be a file template (i.e. test%03d.fid), or simply a path (./ser_full).

-sample

The name of the NUS sampling schedule (nuslist or sampling.sch).

There are also several optional commands that might be of interest:

-sampleCount

The number of NUS samples. This is not required if it can be determined from the sampling schedule.

-off

This is a 0 or 1 to indicate whether the indices in the sampling schedule are zero-based (default) or one-based.

-yT, -zT, or -aT

If it is desired to extend the data beyond the maximum NUS point in a particular dimension, the flag for the complex points in the appropriate dimension (Y, Z, or A) can be manually set during expansion. This functionality replaces that provided by the –size flags in NESTA-NMR (–sizeY, –sizeZ, and –sizeA, see section on NESTA-NMR setup).

Execution of nusExpand.tcl command will produce a fully expanded data matrix that can be used with bruk2pipe or var2pipe during data conversion. This creates an expanded file called ser_full or fid_full that will then be used for the input to bruk2pipe or var2pipe.