Dec 09, 2025

Public workspaceUsing FLAnalyzer V.1

DOI
https://dx.doi.org/10.17504/protocols.io.yxmvmm4jov3p/v1
  • Christopher Esselman1,
  • Arthur Edison1
  • 1University of Georgia
Christopher Esselman
Icon indicating open access to content
QR code linking to this content
DOI: https://dx.doi.org/10.17504/protocols.io.yxmvmm4jov3p/v1
Protocol Citation: Christopher Esselman, Arthur Edison 2025. Using FLAnalyzer. protocols.io https://dx.doi.org/10.17504/protocols.io.yxmvmm4jov3p/v1Version created by Christopher Esselman
License: This is an open access protocol distributed under the terms of the Creative Commons Attribution License,  which permits unrestricted use, distribution, and reproduction in any medium, provided the original author and source are credited
Protocol status: Working
We use this protocol and it's working
Created: December 01, 2025
Last Modified: December 09, 2025
Protocol Integer ID: 233903
Keywords: Fraction Library, SAND, metabolite basis set, metabolite fraction library, metabolite basis set, using flanalyzer, flanalyzer this protocol, flanalyzer, mfl
Funders Acknowledgements:
Network for Advanced NMR/NSF
Grant ID: 1946970
NIH/NIGMS R35
Grant ID: GM145348
Disclaimer
DISCLAIMER – FOR INFORMATIONAL PURPOSES ONLY; USE AT YOUR OWN RISK

The protocol content here is for informational purposes only and does not constitute legal, medical, clinical, or safety advice, or otherwise; content added to protocols.io is not peer reviewed and may not have undergone a formal approval of any kind. Information presented in this protocol should not substitute for independent professional judgment, advice, diagnosis, or treatment. Any action you take or refrain from taking using or relying upon the information presented here is strictly at your own risk. You agree that neither the Company nor any of the authors, contributors, administrators, or anyone else associated with protocols.io, can be held responsible for your use of the information contained in or linked to this protocol or any of our Sites/Apps and Services.
Abstract
This protocol describes how to use FLAnalyzer to create a metabolite basis set (mBS) from a metabolite fraction library (mFL).
Troubleshooting
Before start
This protocol assumes:
  • You have run SAND on each fraction of the library.
  • You have gathered all the SAND CSV files into one directory.
Setting Up
Download the Repository: If you have not done so already, download the FLAnalyzer repository from GitHub. https://github.com/edisonomics/FLAnalyzer
Select Your Environment: Place the repository on either NMRbox or your local machine; if you are using NMRbox, it is preferable to use one of the dedicated MATLAB virtual machines for this analysis.
Open the Script: Launch MATLAB and open the create_basis_set.m script, located in the "workflows" folder within the FLAnalyzer repository.

Use the "Open" button (red arrow) to open scripts (.m files) in MATLAB.

How to Run Sections: To run a specific section of code, first click the whitespace to the right of the section text so it highlights in blue, then click the "Run Section" button.

Click the white space to the right of a code section to highlight the section (blue).


Once the code section is highlighted, use the "Run Section" button to run the code.

Update Paths: Carefully follow the directions provided in the green comments within the script to change the necessary file paths and variables, and run each section of code in the script.
Starting FLAnalyzer
Navigate the Interface: In the FLAnalyzer application, click the gray numbered buttons in sequential order, adjusting the orange parameter boxes as needed; during analysis, click button 2 only once, then repeatedly cycle through buttons 3 through 6 until no peaks remain.



Overall Parameters:

1. Norm peak start (ppm) - This parameter and the following parameter are for normalizing the metabolite fraction library to the integral of DSS. The input for the "Norm peak start (ppm)" parameter should be the ppm value of the upfield end of DSS. For example, a value of -0.01 is usually good.

2. Norm peak end (ppm) - This parameter input should be the ppm value of the downfield end of DSS. For example, a value of 0.01 is usually good.

3. Start ppm (Exclude DSS) - This parameter input should be a ppm value downfield of DSS to exclude it from the analysis. For example, a value of 0.1 is usually good.

4. End ppm - This parameter input should be a ppm value that is at least 0.2 ppm downfield of the most downfield peak in the library.

****
****
Critical!!! - Once defined, the Overall Parameters must remain constant throughout the entire analysis. Record these values to ensure consistency between sessions.
****
****
Read in Variables: Click the "2. Read in Variables" button only once per session, ensuring that you have first set the "Overall Parameters" and the parameters for the "Read in Variables" section.

Read in Variables Parameters:

1. CSV Tables Variable Name - The parameter input should be the name of the MATLAB variable containing the SAND CSV tables. The variable is obtained from the first output from the readInSandFL function (Line 107 of the create_basis_set.m script).

2. FT ppm Variable Name - The parameter input should be the name of the MATLAB variable containing the chemical shift vector of the original ft1 data. The variable is obtained from the second output from the Setup1D function (Line 60 of the create_basis_set.m script).

3. X Matrix Variable Name - The parameter input should be the name of the MATLAB variable containing the matrix of the frequency-reconstructed SAND data. The variable is obtained from the second output from the readInSandFL function (Line 107 of the create_basis_set.m script).

Once the "Overall Parameters" and "Read in Variables" parameters are set, click the "Read in Variables" button. The text will be highlighted in green if the variables have been read into the application.
Green highlight indicating the variables were read into the FLAnalyzer application.
Trace Driver
Trace Driver: Use the "Trace Driver" section to identify the driver peak of the current iteration (the peak with the highest intensity). The driver peak will be used to find other peaks that are highly correlated over the same fractions later in the application.

Trace Driver Parameters: Use the following parameters to generate an initial driver trace. You should adjust these parameters to make broad changes to the driver trace, and you can fine-tune the driver trace using the graphical options explained later in this protocol.

1. range next peak (pts) - This parameter input is a ppm cutoff (in points). If the chemical shift of a peak in a subsequent fraction is outside the ppm cutoff, FLAnalyzer will consider it a separate peak from the trace, and the trace will terminate. Increase this value to consider peaks with a larger ppm shift as part of the same trace.

2. Percentage max val - This parameter input is an intensity cutoff. If the intensity of a peak in a subsequent fraction is below the intensity cutoff, the trace will terminate. For example, a value of 10 would mean that the intensity cutoff is 10% of the largest peak in the driver trace. Decrease this value to consider smaller peaks as part of the trace.
Trace Driver Graphical Interface: Clicking the "3. Trace Driver" button will display a figure of the metabolite fraction library, along with a pink trace indicating the driver.



Using MATLAB Figures: In MATLAB, you can use the toolbar to rotate, zoom in and out, pan, etc., to get a better view of the data in figures. Using this toolbar is essential for FLAnalyzer. The toolbar will appear when you hover your mouse over the top-right corner of the figure (shown in the image above, next to the cursor).
Toolbar Buttons from left to right:

1. Restore View (Home Icon) - Clicking the button returns the figure to the original view.

2. Data Tips (Pointed Square) - First, click the button, and it will turn blue to indicate it is active. Second, click on the figure, and a data tip will appear displaying the X (ppm), Y (Fraction number), and Z (Intensity) of the point. Click on a different location in the figure, and the data point will move to that location. Shift + Click on a different location in the figure, and a new data point will be created and appear on the figure.

3. Rotate (Cube In Circle) - First, click the button, and it will turn blue to indicate it is active. Second, click and hold anywhere in the figure, and drag the mouse to rotate. This button is only usable in three-dimensional figures.

4. Pan (Hand) - First, click the button, and it will turn blue to indicate it is active. Second, click and hold anywhere in the figure, and drag the mouse to pan.

5. Zoom In (Plus Magnifying Glass) - First, click the button, and it will turn blue to indicate it is active. Second, click and hold anywhere in the figure, and drag the mouse to zoom in.

6. Zoom Out (Minus Magnifying Glass) - First, click the button, and it will turn blue to indicate it is active. Second, click and hold anywhere in the figure, and drag the mouse to zoom out.
Adjust Driver Trace: Typically, the driver trace does not require adjustment, or it can be adjusted using the "Trace Driver" parameters. However, if necessary, it can also be modified using the graphical interface.

The driver trace can be adjusted using the Data Tips button in the Toolbar and the buttons located at the bottom left of the figure.

Bottom Left Buttons:

1. Save Additions - Data Tips in the figure will be added to the driver trace.

2. Save Deletions - Selected parts of the current driver trace using Data Tips will be deleted from the driver trace.

3. Intensity - Increase the vertical zoom of the figure.

A demo showing how to use these buttons is in the next sub-step.

After adjusting the driver trace, click on the 'x' in the top right corner of the window to close the figure. You are now ready for the next section of FLAnalyzer. If you made graphical adjustments and then reclicked on "3. Trace Driver", the graphical adjustments will not be saved, so only close the figure once you are ready to continue to the next section or want to retrace the driver after changing the "Trace Driver" parameters.

****
****
Critical!!!!! - The driver trace should cover at least three fractions. So, if a peak is only in one fraction, add a point in the fraction above and below the peak, even if the previous and next fraction is just baseline.
****
****
Trace Driver Demo:

1. Initial Trace - Below shows an image of the driver trace after clicking the "3. Trace Driver" button. A small peak was not initially added to the trace, which will be graphically added next.


2. Add Data Tips - Use the Data Tips button in the Toolbar to mark where the trace should be added. Use Shift + Click to quickly add multiple data tips.


3. Save Additions - Click on the Save Additions button to add the Data Tips to the trace.


Correlate
Correlate: Use the "Correlate" section to correlate peaks to the driver trace over the same number fractions as the driver trace.

Clicking the "4. Correlate" button will produce a figure that displays the peaks in the same fractions as the driver trace, with the intensity of the peaks representing covariance with the driver and the color of the peaks indicating correlation with the driver. The dark red peaks are the peaks most highly correlated with the driver trace.



Keeping the correlation figure open is not necessary for the next section, but it is often helpful to do so.
Trace Correlated
Trace Correlated: Use the "Trace Correlated" section to trace the elutions of highly correlated peaks to the driver trace. These highly correlated peaks will be grouped together to form a basis set element later in the protocol.

Trace Correlated Parameters: Use the following parameters to generate initial traces of the highly correlated peaks. You should adjust these parameters to make broad changes to the correlated traces, and you can fine-tune the traces using the graphical options explained later in this protocol.

1. range next peak (pts) - This parameter input is a ppm cutoff (in points). If the chemical shift of a peak in a subsequent fraction is outside the ppm cutoff, FLAnalyzer will consider it a separate peak from the trace, and the trace will terminate. Increase this value to consider peaks with a larger ppm shift as part of the same trace.

2. Percentage max val - This parameter input is an intensity cutoff within-traces. If the intensity of a peak in a subsequent fraction is below the intensity cutoff, the trace will terminate. For example, a value of 10 would mean that the intensity cutoff is 10% of the largest peak in the trace. Decrease this value to consider smaller peaks as part of the trace.

3. Intensity Less than Driver - This parameter is an intensity cutoff between correlated traces and the driver trace. If the intensity of a peak is below the cutoff, it will not be considered highly correlated with the driver trace. Peaks of two different molecules may have high correlations with each other if they elute in a similar way over the same number of fractions; however, if the intensity of one molecule is much smaller or larger than the other, you can partly distinguish between them by using this parameter. For example, a value of 9 would mean that the intensity cutoff is the maximum value of the driver trace divided by 9. Increase this value to allow smaller peaks to be considered correlated.

4. Correlation Cutoff - This parameter is a correlation cutoff between correlated traces and the driver trace. If the correlation of a peak is below the cutoff, it will not be considered highly correlated with the driver trace. For example, a value of 0.99 would mean that only peaks with a correlation above 0.99 would be considered as highly correlated with the driver trace.

This button will find peaks that are correlated to the driver peak. The correlated peaks will appear gold once the button is pressed.
Trace Correlated Graphical Interface: Clicking the "5. Trace Correlated" button displays a figure of the metabolite fraction library, along with a pink trace indicating the driver and gold traces indicating peaks that are highly correlated with the driver.



Adjust Correlated Traces: The correlated traces can be adjusted using the "Trace Correlated" parameters or graphically using the Data Tips button in the Toolbar and the buttons located at the bottom left of the figure.

Bottom Left Buttons:

Most Important Buttons
1. Add New Trace Quad
2. Delete All Trace Above Frac
3. Delete All Trace Below Frac

Less Important Buttons
4. Delete Trace
5. Add New Trace
6. Add to Existing Trace
7. Add New Trace Group

A demo and explanation will be provided showing how to use these buttons in the next sub-steps.

After adjusting the traces, click the 'x' in the top-right corner of the window to close the figure. You are now ready for the final section of FLAnalyzer. If you made graphical adjustments and then reclicked on "5. Trace Correlated", the graphical adjustments will not be saved. Therefore, close the figure only when you are ready to proceed to the final section or want to retrace after changing the "Trace Correlated" parameters.
Add New Trace Quad: This is the best button for adding new traces. This button will trace all peaks between 4 points and add them to the basis element. Use the Data Tips button from the Toolbar to add the 4 points: 1. The highest fraction the peaks appear, 2. The lowest fraction the peaks appear, 3. A point downfield of the peaks, 4. A point upfield of the peaks.

1. Add the 4 data tips - Use Shift + Click to quickly add the points.


2. Add the traces - Click the "Add New Trace Quad" button to add the peaks.


Delete All Trace Below and Above Frac Buttons: These are the best buttons for removing traces. These buttons will delete all traces below or above a specific fraction cutoff. Use the Data Tips button from the Toolbar to add 1 point. After adding the Data Tip, clicking one of the buttons will either delete all traces in and below or in and above the fraction where the Data Tip is located.

1. Initial Trace - Below shows an image of correlated traces after clicking the "5. Trace Correlated" button. Traces below a fraction number will be graphically removed next.


2. Select Fraction - Create one datatip. All traces in the chosen fraction and below it will be removed if the "Delete All Trace Below Frac" button is used. All traces in the chosen fraction and above it will be removed if the "Delete All Trace Above Frac" button is used.


3. Result of Using the Delete All Trace Below Frac button-


Delete Trace: Use Data Tips and this button to delete individual traces.

1. Initial Trace - Below shows an image of correlated traces after clicking the "5. Trace Correlated" button. An individual trace will be graphically removed next.


2. Select the Individual Trace - Use Data Tips to select the parts of the trace to be removed.


3. Result of Using the Delete Trace button -



Add New Trace: Use Data Tips and this button to add individual traces.

1. Initial Trace - Below shows an image of correlated traces after clicking the "5. Trace Correlated" button. An individual trace will be added.


2. Add Data Tips - Use the Data Tips at the points where the new trace will be added.


3. Result of Using the Add New Trace button -


Add to Existing Trace: Use Data Tips and this button to add points to an already existing trace.

1. Initial Trace - Below shows an image of correlated traces after clicking the "5. Trace Correlated" button. Points will be added to an already existing trace.


2. Add Data Tips - Use the Data Tips at the points where the new parts of the trace will be added.


3. Result of Using the Add to Existing Trace Button -


Add New Trace Group: Add a group of peaks between 2 Data Tips based on the "Trace Correlated" parameters. !!Not Recommended for Regular Use!!

1. Initial Trace - Below shows an image of correlated traces after clicking the "5. Trace Correlated" button. A group of traces will be added.


2. Add Data Tips - Use the Data Tips to mark two points in the same fraction.


3. Result of Using the Add New Trace Group Button -


Save and Remove Peaks
Save and Remove Peaks: This button generates two figures, one showing the traces before and the other showing the traces after removal from the metabolite fraction library. The removed peaks will be added to the "basis" variable in MATLAB. Only zoom and rotate using the before figure, as the rotation of the figures will only be synced if the rotation is done using this figure.

1. Result of Using the Save and Remove Peaks Button -


Adding More Basis Elements to the Basis Set
Repeat Buttons 3-6 until most of the peaks are removed and the basis set is created. As you go, save the workspace variables. The critical variables to save are all_peak_tables_removed, ppm_ft, basis, and X_removed. If you need to close MATLAB or it crashes, these variables can be reloaded, and the progress can be continued. For example, in the "Read in Variables" section, "CSV Tables Variable Name" can be replaced with all_peak_tables_removed; "FT ppm Variable Name" would be ppm_ft; and "X Matrix Variable Name" would be X_removed.
Other Considerations
Sometimes a peak is used as a driver that is an artifact. To delete this trace or other artifacts, continue through steps 3-6, but hit the "Remove Peaks. Do not Save" button. The traces will be removed and will not be saved to the basis set.