Package: nmrtoolbox
nmrtoolboxIntroductionThis is a simple utility that provides modules for working with NMRPipe peak tables and performing a receiver operator characteristic (ROC) analysis to quantify the quality of the "recovered" peaks relative to a control set of "synthetic" peaks.  The modules in this package are as follows:nmrtoolbox.peak: classes for reading in peak tables (currently supports both synthetically generated and recovered peak tables from NMRPipe)nmrtoolbox.roc: perform receiver operator characteristic (ROC) analysis of a recovered peak table relative to a synthetic peak tablenmrtoolbox.mask: define regions of a spectrum that contain signal or are emptynmrtoolbox.util: various supporting utilities used by other modulesnmrtoolbox.strip_plot: generate color coded strip plots that correspond to the true positive and false positive peaks classified by an ROC analysisApplicationsExample #1 - Formal WorkflowThe tools in this package are utilized by theNUSconsoftware package.  You can access NUScon on the NMRbox platform (free for academic, government, and non-profit users).  Runningnuscon -hwill provide instructions on how to run the NUScon evaluation workflow, which directly utilizes the tools presented here in thenmrtoolboxpackage.Example #2 - Kick the Tiresfrom nmrtoolbox.roc import roc
from nmrtoolbox.strip_plot import strip_plot

# perform ROC analysis and specify filtering criteria
my_roc = roc(
    recPeaks=<file-recovered.tab>,
    synPeaks=<file-synthetic.tab>,
    cluster_type=1,
    chi2prob=.75,
    vol_height_mismatch=True,
    maxLW_percent_SW=0.25,
)

# show and plot results
my_roc.print_stats()
my_roc.plot_roc()

# generate strip plots
strip_plot(
    recSpectrum=<file-recovered-spectrum.ft3>,
    sumSpectrum=<file-sum-spectrum.ft3>,
    empSpectrum=<file-empirical-spectrum.ft3>,
    empPeaks=<file-empirical.tab>,
    roc_obj=my_roc,
)The roc function supports the following filter criteria:numberheightabs_heightroi_listindexcluster_typemask_filechi2proboutliervol_height_mismatchmaxLW_percent_SWNote: Filtering bymaskrequires the external use of NMRPipe to generate a mask file indicating where the spectrum is empty.  This binary data is converted byConnjur Spectrum Translatorinto a "tabular" format file (i.e. plain text) which is then read in bynmrtoolbox.mask.The strip plot function shown above will make pairwise comparisons among the following 3 types of input spectra (all of which are fundamental to the NUScon workflow):empSpectrum: empirical spectrum, this reference is typically obtained by FT processing of a uniformly collected experimentsumSpectrum: sum spectrum, this control is typically obtained by FT processing the uniformly sampled time domain data of the empirical data augmented with synthetic peaksrecSpectrum: recovered spectrum, typically obtained by processing a nonuniformly sampled version of the empirical time data augmented with the synthetic time dataIn addition, the corresponding peak tables are also accepted as inputs:empPeaks: empirical peaks, peak table from the empirical spectrumsynPeaks: synthetic peaks, peak table of just the synthetic peaks used to build the sum spectrumrecPeaks: recovered peaks, peak table from the NUS reconstruction of the synthetic and empirical dataExample data from NUScon archive is available on NMRbox at '/NUScon/archive'Changelogv11major upgrades to strip_plot modulePeakTable and Spectrum classes use enumerated types to define valid input formatsPeakTable and Spectrum classes offer .read() methods to handle multiple input typesrename roc input parameters to be consistent with PeakTable and Spectrum classesuniversal change to variable naming: "injected" is no longer used. "synthetic" refers to only the synthetic peaks/spectra and "sum" refers to "empirical" + "synthetic" peaks/spectrav10major change: ROC now sorts peaks by absolute value of intensity (previously used intensity from largest positive down to largest negative)new module added for generating strip plotsadd more options for peak table filteringv9change in internal data model for storing metadata in Peak, PeakTable, Mask, ROC, and ROI classesallow roc class to accept Mask object (not just mask file)approximate maximum LW for injected peaks from X1/X3, etc. parameters in the injected peak tablefunction to write NMRPipe peak table to filev8change to MIT licensebox_radius for mask filtering is multidimensionalimproved input options for setting carrier frequencyaxis labels used to verify compatibility of Peak, Mask, ROI, and ROC objectsv7addition ofrocmoduleaddition ofmaskmodulev6rename package asnmrtoolboxuse subclasses to handle NMRPipe peak tables coming from genSimTab or from the peak pickerv5new Axis class for containing metadata from peak table header