PENCE / CIHR-Group
Joint Software Centre

Funding for this software has been provided in part by the
Canadian Institutes of Health Research (CIHR Group)
and the
Protein Engineering Networks of Centres of Excellence (PENCE).


xcrvfit - Curve Fitting Tool

Version: 4.0.12 - Jan 2008
Download and Installation

Purpose: A graphical X-windows program for binding curve studies and NMR spectroscopic analysis. Starting with version 4.x support for some functionality is provided for multiple datasets.

Table of Contents

  1. Latest News and Release Notes
  2. Overview
  3. Copyright and Acknowledgements
  4. Download and Installation

  5. Basic Use and Tutorial
  6. Fitting Functions
  7. Input Files
  8. Output Files
  9. Customizing and Saving your Plots

  10. Multiple plots
  11. Multiple datasets on one plot
  12. Select Data Range
  13. Parameter Grid Fitting

  14. Appendix: Older versions of xcrvfit

Overview of xcrvfit

The xcrvfit program tries to find the parameters of a function which best fits a given set of data. The user has a wide selection of functions which relate to binding curve studies and spectroscopic analysis.

The power of xcrvfit lies in its convenience to process multiple datasets of various formats, the ability to experiment with fitting parameter scenarios, and the ability to customize the graphics. The program runs quickly and on any platform supporting X-windows. Output from the program includes a graph of the function through the data, the rmse of the fit, a measure of the sensitivity of each fitting function parameter, and a table showing how each datapoint fits the function. The current version allows users to overlay or place multiple fits on one plot.

Copyright and Acknowledgements

Authors: Robert Boyko, Brian Sykes
This software is still not published but we are in the process of doing something about that! You can reference it in the following fashion for now:
xcrvfit: a graphical X-windows program for binding curve studies and NMR
spectroscopic analysis, developed by Boyko, R. and Sykes, B.D.  (University of Alberta).
website: http://www.bionmr.ualberta.ca/bds/software/xcrvfit

Copyright (C) 1994 - No portion of this program may be incorporated into other programs or sold for profit without express written consent of the authors.

Download

Select the version of xcrvfit corresponding to your operating system. We are no longer supporting sgi computers.

  1. MacOSX on intel (13.0 MB)
  2. MacOSX on power mac (13.0 MB)
  3. Linux or Solaris (13.0 MB)

Installation

  1. MacOSX aqua:

  2. Linux, Solaris, or X11 on MacOSX:

Note: It is assumed your operating system is supporting tcl/tk. Older systems may not have this support but you can find/download it easily from the internet. If you type "wish" in a terminal window and get "command not found" then you will need to address this issue first before trying xcrvfit.

Note: To save xcrvfit plots in png/tiff format you may also need to install the tcl Img package. On my machine, I get this functionality by using an enhanced version of tcl called activetcl which is available on the internet. You will need to download and install this package.

Basic Usage and Tutorial for New Users

  1. Start the program.

    Either double click the xcrvfit icon (aqua version) or type xcrvfit in a terminal window. If you do not get a graphical window, make sure the software was installed correctly.

    Optional: You can also give command line arguments if you start xcrvfit from a terminal window. Here is a brief description of the arguments.

    xcrvfit [datafile] [dataset] [function] [function parameters] 
    	 datafile  = your data file
    	 dataset  = the label identifying the dataset in your data file
    	 function  = the fitting function name to use (eg, PH_TITR) 
    	 function parameters  = starting values for the function.
    	Fixed Parameters are preceeded with the keyword "const".
    
    > cd my_data_dir
    > xcrvfit test1.data A21 R2X_DIMER  5 const 12 const 6 const 0.01 3500 
    

  2. Enter your datafile.

    Use the entry box provided or use the "Browse" button to find it in your file system. Here is example data that you can use. More example data can be found in the Fitting functions section. For an explanation of the various data formats that xcrvfit recognizes see the Input Files section.

  3. Look at the graph of the data.

    If you do not see a plot, press the return or enter key in the Data File field. The program displays the first data set by default. To display a different dataset, most users prefer to click the Next or Previous buttons.

  4. Select the fitting function.

    Click and hold the button currently labelled "Line" and select from our current collection of functions. For a more detailed explanation of these functions see Fitting Functions . Once the function has been selected, the program displays the appropriate parameter fields. Some functions to the data being fitted, if this is your first use of the program select the default "Line".

  5. Enter each starting parameter value in the box provided and then press the "Calc-rmse" button.

    Calc-rmse stands for calculate root mean square error. A graph of the fitting function is displayed along with a root mean square error value. If you do not see the fitting function, it could be that your starting parameters are not very close. Set a=1 and b=1 if you are treating this section as a tutorial.

  6. Press the "Best Fit" button to calculate the best fit of your function to the data.

    Some functions will converge to the best fit function regardless of the starting parameters. Others are very sensitive and a close approximation is required first. If you have difficulties getting convergence try holding one of more parameters as a constant.

  7. Click the Results button.

    Here you can see how every datapoint corresponds to the fitting function. Also, you can see how sensitive each fitting parameter is by looking at the StdDev field.

Input Files

The xcrvfit program can read data files which are in one of the following formats.

  1. crvfit

  2. kay

  3. jfit

  4. fp
Note: The kay, jfit and fp formats are automatically converted to the crvfit format internally by the software.

Understanding the Output

The log file "xcrvfit.log" contains a record of each convergence achieved through pressing the iterate button. This is particularly useful for stepping through a number of T2 fits.

Here is an example results file.

Data Input.: data.cubic
Num of data: 10

Function...: Cubic Polynomial
Description: Notes: A0*x*x*x + A1*x*x + A2*x + A3
Parameters.: 4

Parameter   Hold Constant          Value         StdDev
A0.......:       no             -0.00506        0.00211
A1.......:       no              1.30573        0.13435
A2.......:       no             -5.14197        2.32052
A3.......:       no              8.09954       10.43368

Stddev.....: 9.5043        
Iterations.: 116
Max It.....: 200

Point by Point Analysis
          X[i]           Y[i]         Y-Calc       Residual
       0.00000        2.00000        8.09954        6.09954
       4.30000       13.00000        9.72971       -3.27029
       9.60000       93.00000       74.59546      -18.40454
      14.70000      190.00000      198.59236        8.59236
      18.70000      319.00000      335.45210       16.45210
      23.30000      537.00000      533.14359       -3.85641
      27.50000      750.00000      748.90418       -1.09582
      32.40000     1044.00000     1040.07185       -3.92815
      36.80000     1340.00000     1334.93300       -5.06700
      41.80000     1700.00000     1704.96881        4.96881

Customizing and Saving Your Plots

Under settings you can select the name of the plot you wish to customize. The following window shows all the options you can change (the defaults are read in from the lib/defaults/X11.defaults file).

Most of the items are self-descriptive. Here are the ones that may require some explanation:

Saving a plot means you probably have to add some extensions to the tcl/tk language. The default tcl/tk installation will support postscript but this is not an effective solution for publication. Also, mac os x tends to have problems with converting the generated tcl/tk postscript files to pdfs (although using the ps2pdf utility seemed to work for me). So if you intend to use the xcrvfit plots for publications, get the extensions!

There are several places to download and install Tkimg like sourceFourge.net or activeTcl from ActiveState.

Multiple Plots

It can be very informative to visually compare the fits of several datasets. I have chosen an example dataset with multiple data ( T2_RELAX ) and proceeded to fit the dataset labeled 2 as in the first plot above. Now I am interested to compare the next dataset.

  1. First select the Options->Multiple Plots menu item. It is very handy to move this window to a corner of your viewing area especially if you are working with several plots as we are in this case.

  2. Proceed by clicking the Add a New Plot button. Immediately the next dataset is displayed in a new plot on the xcrvfit-plot window. Back to the main panel, you may need to use the Next and Previous buttons or Label entry box to set the desired dataset. In this case we have settled on dataset 11.

  3. If you want to show a fit of this new dataset, now is the time to set/confirm the fitting function and parameters. Hit the Best Fit or Calc-rmse button to generate a fitting function for this data. You should now have a plot similar to the second one in the figure below.

  4. Next, you may want to change some attribute of this current plot (eg, scale of the x or y axis or number of tic marks). The trick here is that when you bring up the Settings->Plot setting for xcrvfit-plot window, you need to click Current Plot before making any attribute changes.

  5. What happens if I now want to change some attribute involving the first plot? Use the Multiple Plots->Current Plot Next/Prev buttons to select the current plot. You can tell which plot is current because the data flashes in the plot whenever the button is pressed.

  6. It is possible to do several plots like this. Use the Plot Layout button to choose a configuration that is different from the default of the program. The first number refers to number of rows of plots, the second is the number of columns. There is a small bug right now, just resize the window to get the plot to update.

Select Data Range

The only purpose of this option is to allow the user to cut the tails off a a dataset before fitting. Sometimes the beginning or end of our data acquisition, the user realizes that the data may be poor quality or noise.

Once the Options->Select Data Range window is invoked, the user clicks the Increase/Decrease buttons until the appropriate data range is found. If the user hits the Best Fit button, only those data between the range bars are used in the calculation. In the example above, you can see how the the outlier points can affect the final fitting function curve.

Multiple data on One Plot

It can be very informative to visually compare the fits of several datasets on one plotting axis. It is also common to display graphs in this format for publication. To demonstrate, we have chosen the ( T2_RELAX ), example dataset which has multiple data in ( kay ) format.

  1. Select the first dataset and proceed to fit it as in the single data case. This would be like the red fitting function in the plot above.

  2. Select the Data Overlays item from the Options menu and drag this window to an open space on your screen.

  3. Proceed by clicking the New Overlay button. Immediately the next dataset is displayed on the plotting window. Note: If this is not the dataset you want, go back to the main xcrvfit panel and use the Next and Previous buttons to select it.

  4. Now is a good time to set the data symbol, colors and any other attribute for this dataset. Click the Settings->Plot setting for xcrvfit-plot menu item. In this example the data symbol was changed to oval and fitting function set to green.

  5. On the xcrvfit main panel, set the function and parameters and use Calc-rmse or the Best Fit button to display the fitting function.

  6. Repeat the previous three steps for any additional datasets.

  7. To tidy up the graph, I set the Apply Changes to item to All Plots and fix any global plot attributes (eg, xMax). Finally I may decide to add a graph title, resize the window and click drag all the labels to their final spot before hitting the Save Plot button.

What happens if I make a mistake and want to change some attribute involving a previous dataset? Use the Data Overlays->Set Current Data button to select this dataset. You can tell which dataset is current because the data flashes in the plot whenever the button is pressed.

Parameter Grid Fitting

Most researchers will have one dataset where the best fit of a particular function indicates the best choice of a parameter of interest. But what happens when the user has several valid datasets that essentially model the same process? Reporting the key parameter of function becomes a complex issue as it is unclear which data to consider and how important that dataset is in relation to others in that family.

The intent of this section in xcrvfit is not to simplify the above process. The software tries to present the results in a manner that allows the researcher to make the best decision possible. Here is an example using the R2X_DIMER function using several amino acid datasets in search of reporting the global value of kd. Although this is a specific example, it should be clear how we can apply this technique to any function.

  1. Read in the data and set the R2X_DIMER function with reasonable starting values as in the figure below.

  2. Select the Options->Parameter Grid Fitting menu item. You should get a new panel called "gridfit-main" and a new graph called "gridfit-select". Your first job is to select the datasets you want in your test suite by clicking the corresponding label in the tableau below. In this particular case each label represents the data from a particular amino acid (obviously the data was not constructed in sequence order).

    Next, as the user adds each dataset to the test suite, the data is shown in the accompanying graph window (shown in black). The other data that you have selected, if not current, is shown in grey. This is a relatively effective and easy way for the user to evaluate the credibility of each dataset in the test suite. Some users will select Parameter Grid Fitting for this function only!

    At any time the user can include/exclude all the datasets by clicking Select All or Select None.

  3. The next job is setting the parameters. Here we want kd to be held constant where we explore various global values from 0.5 to 9.5 in increments of 0.5. R2D, R2M, and TAU are held constant for all function fitting. DSQU is not held constant and should be optimized for each dataset. In the figure below, I have selected all the datasets and then took out the data from the last three amino acids (this data was quite different than the others). Since the data is in kay format, the x-values are all the same for each y-value (that is why all the data values are stacked in distinct vertical lines).

  4. Press the Go button. You now get a new panel which shows how each dataset in the test suite fits the parameter conditions. Apparantly, all data considered, the best value of kd is at 5.0, but notice the variability of kd which best fits each dataset! Is there a correlation of our supposed best data to a particular kd? Is there a correlation to a particular range of amino acids to a particular kd? The researcher will want to go back and select other data test suites, and this is as easy as closing this window.

  5. Of course, numbers don't really give justice to what was just calculated. At this point, click on the Show Fit for each Dataset button and now we can effectively analyze how our global best fit at kd=5.0 works with each individual dataset. Do some datasets not fit well and why might that be?

    If you have several datasets like this you probably want to resize the window as big as possible. Also don't forget you have the Settings->Plot Settings for gridfit-plot menu option which allows you format and save this output in the nicest way possible for publication. The default settings in xcrvfit are set to maximize the space of each curve. If you only have a few curves you may want to add scales and more space between plots.

  6. Finally, another way to analyze the best fit of a test suite is to see a graph of all the other values of kd that we tried. Click on the Plot Sum of Square Errors button and you can see how that best fit kd=5.0 value compares to the other values we tried (x-axis is kd, y-axis is total error).

Problems and Issues

  1. First, the software can only iterate over one parameter right now. Generalizing for 'n' parameters is complex, although somewhere in the future selecting 2 or 3 parameters for iteration seems desirable (assuming the user understands the computational aspects of this).

  2. The datasets and function selected have to be relatively insensitive to starting parameters. Right now there is no mechanism to set good starting parameters for each dataset for those parameters that are not held constant.

  3. How do we treat these results? What confidence level would we assign to our kd=5.0 parameter? Would not any statistical inference depend on how this curve compares to the case of 'perfect' data? Just be careful when jumping to any conclusions on the graphs and results you see.

Appendix: Older Versions of xcrvfit

The following programs were all pre-cursors which led to the development of this current version of xcrvfit.

Crvfit

Crvfit was developed at the University of Alberta in the Brian Sykes lab in 1989 on a sun using sunview. Crvfit was frequently used in the lab for binding curve studies where some functions are of the form f(x, x2). We also used crvfit to calculate T1 and T2 relaxation curves and J coupling constants.

Fast Crvfit

Fast crvfit is a derivative of crvfit which fits multiple input files to the same function. So if you have lots of data files that you wish to fit with the same function, this program could save alot of time. However it is a risky program in that there is no graphical output. You will not be able to "see" the fit, the output is a statistical report only. Fast crvfit was written in C and later became the back-end software for xcrvfit.

CrvfitS

This program does curve fitting for binding studies for the following cases: However this program was written with sunview graphics and there was not enough impetus to port it to X-windows.

Crvfit_nmrdata

This is a small utility which reformats our vnmr data files to crvfit or jfit data files.

Dimerfit

This program finds chi-square values from fitting data to curves by varying the values for kd1, kd2 and kdimer. There is also an option which allows the user to have the output formatted into a table which is acceptable for input into the macintosh "wingz" program.

Jfit

Graphical curve fitting package for estimating J-coupling constants via absorption/dispersion Lorentzians or Gaussian functions.


Back to Software Centre

This file last updated:

Questions to: bionmr@biochem.ualberta.ca