PREdator v0.9
PREdator is an analysis, evaluation and fitting tool for series of data points. The initial motivation behind PREdator was to provide a user-friendly GUI-based interface for the analysis of relaxation rates in order to provide paramagnetic relaxation enhancement (PRE) information on backbone protons in proteins.
You are welcome to implement, use and share script. However, we know the script is not perfect, so you are welcome to improve the script or change it to your particular needs.
Requirements:
The script is written in Python3. You need a Python3 version installed on your computer. Please, ensure that you have the following packages installed in their Python3 version:
- matplotlib (www.http://matplotlib.org/index.html)
- scipy (http://www.numpy.org)
- numpy (http://www.numpy.org) and
- dill (https://pypi.python.org/pypi/dill).
To create an executable desktop shortcut:
On Mac OS X/ Linux:
-Download PREdator.zip and unpack the folder.
-copy the script PREdator.py to a directory.
-Open the Terminal.
-Navigate to the /where/you/saved/PREdator.py.
-Type into the command line:
"touch PREdator.command". This creates a file called PREDATOR.
-Open an editor (e.g. type in the command line: nano PREdator.command or nedit
PREdator.command; or use any other text editor) and write a short shell script:
#!/bin/sh
cd /Path/to/directory/were/you/saved/PREdator.py/
python3.x PREdator.py &
-the x in the command python3.x depends on your installed Python3 version.
-Save this short shell script.
-Type in the terminal: chmod 755 PREdator.command Ð this will make PREDATOR.command
executable.
-Double clicking on the icon of PREdator should run the script.
On Mac: you may create a Mac OS app using AppleScript:
-open AppleScript and type into the editor field:
tell application "Terminal"
try
do script "/path/to/where/you/saved/the/above/shortcut/PREdator.command; exit"
activate
end try
end tell
-click on Translate (sledge hammer symbol)
-in the File menu go to "Export"
-save the script as app
-now you can insert your own icon:
get the "Info" about PREdator.app window by command+i
copy an icon to temporary storage (command+c), you may use the png provided in the package
-click on the small icon in the "Info" window which gets highlighted in blue and insert your
own icon with command+v
-now you may drag the app to your dock and run PREdator from there
On Windows:
-Rightclick on the script -> Send to Desktop
-This creates a shortcut on the desktop.
-Rightclick -> Properties.
-Change the target field: add "C:\Python3.x\python.exe" in front of it separated by a space. Or whatever the location of python.exe is on your machine.
-Then right click -> Pin to taskbar.
-That should give you the proper link in the taskbar.
Data input files:
The input file should contain comma separated data in the following order:
Specifier,data point(x),Value(y),Series (numbers only)
NOTE: "Series" is not required if the specifier in the first column occurs only once in the data set
Example:
631GluH, 0.0,1.39334e+05,0
631GluH, 0.2,1.56741e+06,0
631GluH, 0.5,2.53424e+06,0
631GluH, 1.0,5.11570e+06,0
631GluH, 1.5,5.84129e+06,0
631GluH, 2.0,6.97206e+06,0
631GluH, 4.0,8.35225e+06,0
631GluH, 6.0,8.30966e+06,0
631GluH, 8.0,7.81506e+06,0
631GluH, 0.0,3.85366e+05,2
631GluH, 0.2,5.81085e+05,2
631GluH, 0.5,2.78194e+06,2
631GluH, 1.0,4.97757e+06,2
631GluH, 1.5,6.06696e+06,2
631GluH, 2.0,5.47899e+06,2
631GluH, 4.0,6.02326e+06,2
631GluH, 6.0,6.44079e+06,2
631GluH, 8.0,5.85769e+06,2
........
The first column represents a certain specifier or measurement, e.g. a particular amino acid within a protein sequence, a protein, a cell type or, more general, the object under investigation.
The second column represents the data points, i.e. the points at which the Values are recorded (x-axis). The points could be for example a time series or a range of different drug concentrations. The Values (y-axis) recorded at a certain data point are given in column three.
The last column including the preceding comma "Series (numbers only)" is optional and can be omitted if the specifier in the first column occurs only once. In situations were you took measurements of the same object (e.g. same amino acid or the same cell type) but under different conditions (e.g. different concentrations of a paramagnetic cosolvent or at different temperatures) then you should provide this information as number in the last column. An example would be a range of concentrations: 0.0, 0.1, 0.2, 0.5, ...
For further examples of input data please see additional example data files (expample_1.txt, expample_2.txt, PRE_full.txt, PRE_minimal.txt) provided with the PREdator package.
***
Fitting:
It is advantageous if the user has a rough idea about the data and the order of magnitude of the fitting parameters (a,b,c).
However, PREdator provides an initial estimate of the parameters to be fitted, which can be refined by the user in consecutive runs of the script. If the user has knowledge about the order of magnitude of the fitting parameters then there is the possibility to enter the initial fitting parameters before attempting the first fitting.
In an initial dialog the user has the opportunity to choose a predefined fitting function from a list (see below) or to enter a self-defined fitting function with up to three fitting parameters.
If you have no idea on the principal nature of the required fitting function, a little trick might help:
just run the script with "a+b*x" as fitting function (select this in the initial dialogue window). This will give you an output most likely showing an inacceptable lousy fit (blue line) but you'll see the data points (red points) plotted, which in turn should give you an idea about the principal nature of your required fitting function, e.g. an exponential growth (a*np.exp(b*x), see expo_1.txt) or a fit approaching a saturation for large data point (x) values (a*(1-np.exp(-b*x), see first series (Series '1.0') of expo_2.txt). Incidentally, the other series of expo_2.txt (Series 2.0 etc) are different - so this data set provides a nice playground for learning of how to get around in PREdator.
When using a self-defined fitting function the user has to enter the fitting function with a,b or c as fit parameter.
When providing a self-defined fitting function, we recommend the parameter b as a fit parameter modulating the values in the second column (x-axis).
The implementation of NumPy gives the user the opportunity to define and use own fitting functions with predefined mathematical expressions (e.g. sin, cos or tan).
For further information see: http://docs.scipy.org/doc/numpy/reference/routines.math.html.
When entering a self created fitting function which includes predefined mathematical expressions it is mandatory to prefix this expression with the tag "np."! (e.g. np.sin, np.exp, for examples see also the list of predefined functions).
List of predefined functions in PREdator:
'a+b*x'
'np.log(a*np.exp(-b*x))'
'a*np.exp(-b*x)'
'a*np.exp(b*x)'
'a*np.exp(-b*x)+c'
'a*np.exp(b*x)+c'
'a*(1-np.sin(b*x)/b*x)+c'
'a*(0.5-np.exp(-b*x))'
'a*x/(1+a*x)'
'a*np.exp(-b*x**2)'
'a*np.cos(b*x)'
'a*np.cos(b*x)+c'
'a*np.sin(b*x)'
'a*np.sin(b*x)+c'
'a*(1+np.exp(-b*x)+np.exp(-c*x))'
'a*(1+np.exp(b*x)+np.exp(c*x))'
'a*(1-np.exp(-b*x))+c'
'a*(1-np.exp(b*x))+c'
'a*(1-np.exp(-b*x))'
'a*(1-np.exp(b*x))'
'Enter your own function'
***
Licence:
Copyright (C) 2014 Christoph Wiedeman and Peter Bellstedt
email: cwiede@fli-leibniz.de or pbell@fli-leibniz.de
Leibniz-Institute for Age Reasearch - Fritz-Lipmann-Institute
Research Group Biomolecular NMR Spectroscopy
Beutenbergstr. 11
07743 Jena, Germany
This program is free software: you may redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful.
Disclaimer of Warranty: This program is provided ''as is'' and for use at user's own risk. FLI and its directors, officers, employees and agents make no representations or warranties of any kind, expressed or implied, as to quality of the program or fitness for any particular purpose, that it is free from defects, or that its use will not infringe any copyright, patent, trade mark or other third party rights. In no event shall FLI and/or its directors, officers, employees and agents be liable for any damages whatsoever arising, including but not limited to the use of or inability to use the program, even if FLI and/or its directors, officers, employees and agents were aware of the possibility of such damages.
To see the GNU General Public License for more details go to:
http://www.gnu.org/licenses/ for the GNU General Public License