Peakfind and Faq obtain or use recompilation license for PLS Toolbox: Difference between pages

From Eigenvector Research Documentation Wiki
(Difference between pages)
Jump to navigation Jump to search
imported>Donal
 
imported>Scott
No edit summary
 
Line 1: Line 1:
===Issue:===


===Purpose===
How do I obtain or use a recompilation license for PLS_Toolbox?


Automated identification of peaks.
===Possible Solutions:===


===Synopsis===
The standard [http://www.eigenvector.com/software/license_evri.html PLS_Toolbox license] does not permit recompilation of any part of the code without written permission from Eigenvector Research, Inc. This permission is usually in the form of a recompiliation license (for more information on recompilation licenses, see: our [http://www.eigenvector.com/evriblog/?p=27 Blog post on Compiling PLS_Toolbox] ).


:[i0,iw] = peakfind(x,width,tolfac,w,options)
If you have purchased a recompiliation license for PLS_Toolbox and/or other Matlab-based Eigenvector Research products, you can use the following instructions to compile your application including the licensed Eigenvector Research (EVRI) code.
:[i0,iw] = peakfind(x,width,options)


===Description===
# If you were not supplied an ''evrilicense.lic'' file by EVRI, create one by copying the license code supplied for your compilation license (found on the download tab of your EVRI account) into a plain-text file named: ''evrilicense.lic'' The file should consist of the license code on a single line of the file. For example: <pre>12345678-98765432-ab-1234-1234</pre>
# Copy the ''evrilicense.lic'' file into one of the folders on your Matlab path. This could be either one of the PLS_Toolbox folders, or your application's folder.
# Add the ''evrilicense.lic'' file to the "Shared Resources" list in the Matlab project builder. This will assure that the EVRI license gets included in the compiled application.
# Compile your application as usual using Mathworks' standard instructions. The Matlab dependency logic will automatically include the PLS_Toolbox functions in your compiled application. (See note below regarding "blocking" certain functions from being included.)


Given a set of measured traces (x) PEAKFIND attempts to find the location of the peaks. Different algorithms are available and each is discussed in the Algorithm Section.
'''Blocking Unnecessary Functions'''


====Inputs====
By default, Matlab's compiler automatically identifies all m-files which are necessary to run your application and includes all of these in the compiler output. Because of the integrated nature of many of the PLS_Toolbox functions, this can lead to "sprawl" - inclusion of many more functions than are actually needed. The follow steps can be taken to reduce the size of a compiled application:


* '''x''' =  matrix of measured traces. Each  row of (x) is an individual trace with potential peaks.
* Remove PLS_Toolbox 'dems' folder and 'help' folder from your path prior to compiling. Files in these folders can be large and are unnecessary for compilation.


* '''width''' = number of points in Savitzky-Golay filter.
* Add "dummy" functions to reduce dependencies:
:: One way to help reduce these unnecessary additions is to create empty "shell" functions to overload certain PLS_Toolbox functions. These functions, if placed in a folder above PLS_Toolbox when you are compiling, will shadow (hide) the actual function and help avoid sprawl. In particular the following functions are useful to shadow:


====Optional Inputs====
:* analysis.m
:* browse.m
:* plotgui.m
:* browse.m
:* evriinstall.m
:* evrireporterror.m


* '''tolfac''' = tolerance on the estimated residuals, peaks heights are estimated to be > tolfac\*residuals {default: tolfac = 3}.
:: These functions will not be called in normal operation and, in most cases, our compilation licenses do not permit their inclusion in your application anyway.


* '''w''' = odd scalar window width for determining local maxima {default: w = 3} (see LOCALMAXIMA).
* Find top level functions and see if you can "manually" determine dependencies. Look at the results of the top level dependency check and see what functions are called from the primary PLS_Toolbox function you're working with. If the dependencies are few, you may be able to iterate over the results (get 'toponly' dependencies from results) and get a smaller subset of dependencies. '''NOTE''': This will require some experimentation and time to work through. The dataset object is extensively used by most function so this folder should almost always be included.


* '''options''' = discussed below in the Options Section.
<pre> [fList, pList] = matlab.codetools.requiredFilesAndProducts('peakfind','toponly') </pre>


====Outputs====
'''Uninstall the Stats Toolbox '''


* '''i0''' =  cell array with each cell containing the indices of the location of the major peaks for each of the   traces.
Although moving the Stats Toolbox below PLS_Toolbox on your MATLAB path (or removing the Stats Toolbox folders altogether) will allow the PLS_Toolbox DataSet Object to function normally, you must uninstall the Stats Toolbox before compiling PLS_Toolbox function that require the DataSet Object.  


* '''iw''' =  cell array with each cell containing the indices of the location of the windows containing each peak in (i0). (If not included in the output argument list, it is not calculated and the algorithm is slightly faster.) .
The MathWorks states:


===Algorithm===
"When you compile [a program] into an application and run it, the MATLAB Compiler Run-time references its in-built Dataset function which is higher in its PATH and hence runs the data against this inbuilt Dataset function."


Each peak finding algorithm uses the smoothed and second derivative data (see SAVGOL) and an estimate of the residuals. The smoothed and second derivative are estimated as:
For more information on the DataSet Object history see here:
*[http://www.eigenvector.com/evriblog/?p=10 DataSet Object Conflict]
*[http://www.eigenvector.com/evriblog/?p=11 DataSet Object — Letter to MathWorks March 15, 2007]


:d0 = savgol(x,width,2,0);
'''Troubleshooting'''


:d2 = savgol(x,width,2,2);
* In some cases PLS_Toolbox may need to be moved out of the default installation folder into a folder with more permissions and/or no spaces in the path. For example, "C:\eigenvector\PLS_Toolbox".
'''Still having problems? Please contact our helpdesk at [mailto:helpdesk@eigenvector.com helpdesk@eigenvector.com]'''


The residuals are defined for the  row/trace as
[[Category:FAQ]]
 
:residuals = sqrt(mean((x(i,:)-d0(i,:)).\^2));
 
For options.algorithm = 'd0', locates a candidate set of peaks (pks) by identifying local maxima (within the specified window size) in the smoothed data:
 
:pks = localmaxima(d0(i,:),w);
 
Next, the input (tolfac) is used to estimate two thresholds (tol0) and (tol2) using the smoothed and second derivative data:
 
:tol0 = tolfac\*sqrt(mean((x(i,:)-d0(i,:)).\^2));
 
:tol2 = tol0\*(max(d2(i,:))-min(d2(i,:)))/ ...
 
:            (max(d0(i,:))-min(d0(i,:)));
 
Finally, the set of major peaks are selected from the initial candidate set of peaks . To be accepted, the value of d0 and d2 at the peak location must surpass the estimated noise level of both d0 and d2 by the tolerance factor (tolfac).
 
:i0{i} = pks(d0(i,pks)>tol0 & d2(i,pks)<-tol2);
 
For options.algorithm = 'd2', the algorithm operates similarly to what is described for d0 except that it locates candidate peaks as the local maxima on the second derivative data and to be accepted, a peak must only surpass the estimated noise level of d2 by the tolerance factor. That is, d0 is not considered at all in the calculation except to estimate the noise level.
 
For options.algorithm = 'd2r', as with 'd2', 'd2r' locates peaks in the second derivative data, d2, but selects the final set as those peaks which have a "relative" height (difference between closest d2 peak valley and d2 peak top) which surpasses the estimated noise level of d2 by the tolerance factor, tolfac.
 
===Options===
 
*'''options'''  = structure array with the following fields:
 
* '''name''': 'options', name indicating that this is an options structure.
 
* '''algorithm''': [ {'d0'} | 'd2' | 'd2r' ] selects an algorithm used to identify peak location. These algorithms are complimentary and may work differently in the presense of backgrounds and other peak shape effects.
 
*  ''''d0'''' : locates a candidate set of peaks by identifying local maxima (within the specified window size) in the smoothed data (d0). Next, a threshold on d0 and the second derivative (d2) is used to select a final set of peaks from this candidate set. To be accepted, the value of d0 and d2 at the peak location must surpass the estimated noise level of both d0 and d2 by the tolerance factor (tolfac).
 
*  ''''d2'''' : locates candidate peaks as local maxima in the smoothed 2nd derivative data (d2) and selects a final set of peaks as those candidate peaks which surpass (by the tolerance factor, tolfac) the estimated noise level of d2. d0 position or value is not considered in any part of the selection except to estimate the noise level.
 
*  ''''d2r'''' : as with 'd2', 'd2r' locates peaks in d2, but selects the final set as those peaks which have a "relative" height (difference between closest d2 peak valley and d2 peak top) which surpasses (by the tolerance factor, tolfac) the estimated noise level of d2.
 
* '''npeaks''': The maximum number of peaks to find.
 
*  '''{'all'}''' chooses all peaks that are > tolfac.
 
*  '''1,2,3,''' ... integer maximum number of peaks.
 
===See Also===
 
[[fitpeaks]], [[localmaxima]]

Revision as of 11:28, 28 June 2019

Issue:

How do I obtain or use a recompilation license for PLS_Toolbox?

Possible Solutions:

The standard PLS_Toolbox license does not permit recompilation of any part of the code without written permission from Eigenvector Research, Inc. This permission is usually in the form of a recompiliation license (for more information on recompilation licenses, see: our Blog post on Compiling PLS_Toolbox ).

If you have purchased a recompiliation license for PLS_Toolbox and/or other Matlab-based Eigenvector Research products, you can use the following instructions to compile your application including the licensed Eigenvector Research (EVRI) code.

  1. If you were not supplied an evrilicense.lic file by EVRI, create one by copying the license code supplied for your compilation license (found on the download tab of your EVRI account) into a plain-text file named: evrilicense.lic The file should consist of the license code on a single line of the file. For example: 
    12345678-98765432-ab-1234-1234
  2. Copy the evrilicense.lic file into one of the folders on your Matlab path. This could be either one of the PLS_Toolbox folders, or your application's folder.
  3. Add the evrilicense.lic file to the "Shared Resources" list in the Matlab project builder. This will assure that the EVRI license gets included in the compiled application.
  4. Compile your application as usual using Mathworks' standard instructions. The Matlab dependency logic will automatically include the PLS_Toolbox functions in your compiled application. (See note below regarding "blocking" certain functions from being included.)

Blocking Unnecessary Functions

By default, Matlab's compiler automatically identifies all m-files which are necessary to run your application and includes all of these in the compiler output. Because of the integrated nature of many of the PLS_Toolbox functions, this can lead to "sprawl" - inclusion of many more functions than are actually needed. The follow steps can be taken to reduce the size of a compiled application:

  • Remove PLS_Toolbox 'dems' folder and 'help' folder from your path prior to compiling. Files in these folders can be large and are unnecessary for compilation.
  • Add "dummy" functions to reduce dependencies:
One way to help reduce these unnecessary additions is to create empty "shell" functions to overload certain PLS_Toolbox functions. These functions, if placed in a folder above PLS_Toolbox when you are compiling, will shadow (hide) the actual function and help avoid sprawl. In particular the following functions are useful to shadow:
  • analysis.m
  • browse.m
  • plotgui.m
  • browse.m
  • evriinstall.m
  • evrireporterror.m
These functions will not be called in normal operation and, in most cases, our compilation licenses do not permit their inclusion in your application anyway.
  • Find top level functions and see if you can "manually" determine dependencies. Look at the results of the top level dependency check and see what functions are called from the primary PLS_Toolbox function you're working with. If the dependencies are few, you may be able to iterate over the results (get 'toponly' dependencies from results) and get a smaller subset of dependencies. NOTE: This will require some experimentation and time to work through. The dataset object is extensively used by most function so this folder should almost always be included.
 [fList, pList] = matlab.codetools.requiredFilesAndProducts('peakfind','toponly')

Uninstall the Stats Toolbox

Although moving the Stats Toolbox below PLS_Toolbox on your MATLAB path (or removing the Stats Toolbox folders altogether) will allow the PLS_Toolbox DataSet Object to function normally, you must uninstall the Stats Toolbox before compiling PLS_Toolbox function that require the DataSet Object.

The MathWorks states:

"When you compile [a program] into an application and run it, the MATLAB Compiler Run-time references its in-built Dataset function which is higher in its PATH and hence runs the data against this inbuilt Dataset function."

For more information on the DataSet Object history see here:

Troubleshooting

  • In some cases PLS_Toolbox may need to be moved out of the default installation folder into a folder with more permissions and/or no spaces in the path. For example, "C:\eigenvector\PLS_Toolbox".

Still having problems? Please contact our helpdesk at helpdesk@eigenvector.com

Retrieved from "https://www.wiki.eigenvector.com/index.php?title=Peakfind&oldid=10099"