pyMINFLUX user manual

Notation

LMB: Left mouse button: RMB: Right mouse button

Loading and importing data into pyMINFLUX

pyMINFLUX can import MINFLUX datasets exported from Abberior Imspector in either NumPy (*.npy) or Matlab (*.mat) format or load datasets saved in its own .pmx format. The native .pmx format also stores information about performed analysis and settings used.

To open a file:

• use the Load button in the main window (Image 2, A);
• select the File > Load menu;
• drag a file from the system file explorer on the Pipeline Toolbar (left panel of the main window).

The Reset button (Image 2, B) will revert back all filtering steps to their original state.

Importer

Once a file has been loaded, pyMINFLUX will analyse the structure of the dataset and display the following metrics on the Importer window (Image 1):

1. Number of iterations, in the same notation as used in the sequence file.
2. Presence of valid cfr values within a specific iteration.
3. Whether or not an iteration is cycled through several times within each tid.

The outcome will depend on the nature of the loaded dataset, and will reflect some of the characteristics of the MINFLUX sequence used for the acquisition.

Image 1: Importer window.

Through the Importer window, it is also possible to select the source for the different MINFLUX parameters in two different ways:

1. The Pick last valid iteration option, selected by default, will gather all variables from the last available iteration. In practice, this implies that for sequences without valid cfr values for the last iteration (such as the default 3D localisation sequence, Image 1, central panel), pyMINFLUX will read this metric from an earlier one (iteration 6 in this example).
2. By clicking on a specific iteration in the list, all metrics will be imported from it.

In both cases, the source iteration for the cfr and all the other metrics is highlighted with a blue background.

Only datasets imported through the Pick last valid iteration option can be saved. This ensures that .pmx files will always contain values read from the last available iteration. The export option however, is always available regardless of the Importer settings.

For certain MINFLUX sequences and Importer settings, there is a possibility that cfr values are imported from a non-relocalised iteration. In this case, only the first localisation for a given tid will have a valid cfr value.

If a minimum number of localisations per trace larger than 1 is defined in the Options panel (see Global settings section), no data will be displayed on the Data Plotter if a non-relocalized iteration is selected as data source.

In addition, the Importer window allows to specify whether the dataset is the result of a tracking experiment (Tracking dataset checkbox, see Tracking support section) and the dwell time for the selected iteration (in ms, this is used to calculate the number of dwell cycles used for a measurement).

pyMINFLUX main window

Image 2: pyMINFLUX main window.

Pipeline Toolbar

The Pipeline Toolbar, on the left part of the pyMINFLUX main window, contains links and shortcuts to all the analysis tools in the suggested workflow order (DCR unmixing, followed by fluorophore selection and filtering).

Data Plotter

Upon loading, the Data Plotter displays the (x, y) positions of the localizations read from the file (a z-projection is displayed for 3D datasets). The size of the dots used to represent each of the localizations does not scale with the zoom factor (mouse wheel) so that localizations can be precisely observed at high resolution. The canvas can be moved by LMB-clicking and dragging. A scale bar can be found on the lower-left corner of the Data Plotter, its size can be customised via RMB > Set scale bar size.

The Data Plotter view and LUT legend can be exported as images (RMB > Export...). Additionally, distances can be measured between any two points on the canvas (Ctrl+LMB and dragging on Linux and Windows; CMD+LMB and dragging on macOS); and localizations can be selected either individually (LMB on individual dots) or with a selection box (Shift+LMB).

Since version 0.5.0, it is possible to underlay a confocal image to the MINFLUX dataset in the Data Plotter. Abberior iMSPECTOR .msr files can be used as source for the images (RMB > Add confocal image). Once loaded, the images present within the file are listed, together with the relevant metadata for their identification (image and pixel size, as well as detectors used for the acquisition) (Image 3). Underlay can be replaced (RMB > Replace confocal image) or removed entirely (RMB > Remove confocal image).

Image 3: Confocal image selection window.

The toolbar under the Data Plotter includes the settings for color-coding the localizations (by trace, fluorophore ID, z coordinate and time), the option to draw only the average localization for each trace ID, and the drop-down menus to select any MINFLUX variable (tid, tim, x, y, z, efo, cfr, eco, dcr, dwell time and the fluorophore ID fluo) to be plotted instead of the default x and y. When a confocal image has been added to the Data Plotter, the two checkboxes at the bottom of the toolbar can be used to toggle the visibility of each dataset.

3D Data Viewer

Since version 0.5.0, pyMINFLUX offers a built-in viewer for 3D data visualization. Once the 3D checkbox on the toolbar has been activated, a new drop-down menu with the rendering options (orthogonal or 45 degree perspective) will appear. Zoom is controlled by the mouse wheel, dataset can be rotated by LMB-clicking and dragging and centre of rotation can be moved by Shift+LMB-clicking and dragging. As for 2D datasets, the resulting image can be exported (RMB > Export...)

Image 4: Built-in 3D Viewer.

For additional 3D data visualization options, such as the creation of movies, pyMINFLUX offers a ParaView plug-in. You can download it as a zip archive from here. Extract the zip file to your favorite location (in a multi-user environment, make sure that this location can be reached by ParaView for all users). To install it, select Manage Plugins... from ParaView's Tools menu, click on Load New... (Image 5, A) and select the pyminflux_reader.py file you just downloaded and extracted. Then expand the newly added pyminflux_reader plugin by clicking on the triangle next to it and check Auto Load (Image 5, B). From now on, the plug-in will be automatically loaded when ParaView starts.

Image 5: ParaView plugin installation.

To use the plug-in, open a .pmx file saved from pyMINFLUX.

.pmx files created by pyMINFLUX 0.4.1 need a new version of the ParaView plugin: please upgrade from the link above.

Dataframe Inspector

The Dataframe Inspector allows for manual inspection of all MINFLUX variables for the localizations selected in the Data Plotter (either by clicking or with the selection box).

Filtering tools

DCR unmixing

The Unmixer can be accessed through the corresponding button in the pipeline toolbar (Image 2, C) or from the Analysis menu. It defaults to displaying a histogram with the distribution of dcr values in the dataset (the bin size is automatically calculated according to the data range, but it can also be manually adjusted in the Histogram settings tab).

Image 6: Unmixer window.

For two-color MINFLUX datasets, localizations can be assigned to a specific fluorophore species based on its dcr value in two ways:

1. Automatic assignment: after specifying the number of fluorophores in the drop-down menu, the Detect button applies a Gaussian-mixture model fitting to separate the two populations, each one highlighted with a different color in the histogram.

Image 7: Automatic unmixing toolbar.

2. Manual assignment: the user enters a dcr threshold value to split the distribution; the Preview button highlights the resulting populations.

Image 8: Manual unmixing toolbar.

Please notice that after assignment, a post-processing step based on simple majority vote will make sure that all localization within individual traces have the same fluorophore ID. It can indeed happen that within a trace, a small number of localization with extreme dcr values are mis-labelled by either the automatic or the manual assignment, and this step can quickly take care of it.

Regardless of the method used for classification, the Assign button assigns a specific fluorophore ID to each localization in the dataframe. The Active color drop-down menu in the pipeline toolbar (Image 2, D) can then be used to select the fluorophore that will be plotted in the main Plotter and that will be affected by the filtering tools. Additionally, color-coding by fluorophore ID can be used (via the drop-down menu in the Data Plotter toolbar).

For specially challenging datasets, it is possible to use the spectral information from all relocalised iterations in the unmixing process. By activating the Pool DCR values (ECO-weighted) checkbox on the Importer window (Image 1), dcr is not directly read from the selected iteration, but calculated as the weighted average (by eco) of all relocalised iterations in the sequence. This way, fluctuations in the dcr value are averaged out, resulting in better separated peaks in the Unmixer.

Time Inspector

The Time Inspector can be accessed through the corresponding button in the pipeline toolbar (Image 2, E). By default, it shows the number of localizations per minute over the course of the MINFLUX measurement. Alternatively, the average localization precision per minute (optionally weighted by its standard error) can be selected from the drop-down menu (Image 9, A).

Image 9: Time Inspector window.

The Time Inspector allows time-based cropping of the dataset, for instance to remove the initial minutes of the acquisition or an interval with poor sample stabilization. For this purpose, the ROI on the histogram can either be resized and dragged or specified via RMB > Set range. The localizations included in it can be either kept or removed by clicking the corresponding button in the toolbar at the top (Image 9, B and C respectively).

Analyzer

The Analyzer can be accessed through the corresponding button in the pipeline toolbar (Image 2, F), it includes the efo and cfr profile for the active fluorophore (Image 10, A and B respectively), its trace length distribution (Image 10, C), as well as the localization precision distribution for all axis (Image 10, D).

Image 10: Analyzer window.

EFO filtering

The efo distribution plot in the Analyzer allows for a quick assessment of whether the MINFLUX measurement was carried out in the single-molecule regime. By analyzing the overall profile and comparing it to the results acquired with standard samples under the same conditions, the localizations originating from multiple emitters can be filtered out. This process can be approached in two ways:

1. Automatic thresholding: for this, the expected frequency of single emitters (in Hz) indicated in the corresponding field in the EFO Thresholding tab is used. The Detect button will automatically find the minimum in the histogram closest to twice the expected frequency. Please notice that the expected frequency can be set and saved in the application options.

Image 11: Efo automatic thresholding toolbar.

2. Manual thresholding: this can be done by manually indicating the values in the Pipeline Toolbar text boxes or by using the ROI in the Analyzer window (either dragging the ROI itself, or setting the ROI ranges via the RMB context menu).

CFR filtering

The cfr distribution plot in the Analyzer allows for a quick assessment of the MINFLUX iterative process accuracy. Depending on the acquisition sequence used, cfr values are already being used as stop criteria during the measurement process. The threshold values used on the last iteration, however, are usually quite permissive, resulting in some low-quality localizations being included on the final dataset. Two approaches can be used again to approach cfr filtering:

1. Automatic thresholding: for this, the cfr measurements are expected to be approximately normally distributed. The (lower and/or upper) cutoff values are defined as the user-specified number of robust standard deviations (the mean absolute deviation divided by 0.67449) away from the median.

Image 12: Cfr automatic thresholding toolbar.

2. Manual thresholding: this can be done by manually indicating the values in the Pipeline Toolbar text boxes or by using the ROI in the Analyzer window (either dragging the ROI itself, or setting the ROI ranges on the RMB context menu).

Trace length filtering

The Trace Length distribution in the Analyzer allows for quick assessment of the number of localizations achieved during an emission event (within the same tid). This metric will depend on the MINFLUX sequence used and the photon budget of the observed fluorophore. External contributions, such as autofluorescent compounds present in the sample, can generate extremely long traces, specially at the beginning of an acquisition. Two approaches can be used again to approach trace length filtering:

1. Percentile-based thresholding: for this, the top percentile cutoff value is specified by the user.

Image 13: Trace length thresholding toolbar.

2. Manual thresholding: this can be done by using the ROI in the Analyzer window (either dragging the ROI itself, or setting the ROI ranges on the RMB context menu).

The solid vertical line in the plot indicates the median value, with the dashed ones corresponding to the interquartile ranges.

Localization precision calculation

The bottom half of the Analyzer window shows the localization precision for the active fluorophore for all axes separately.

The localization precision is calculated as follows:

• for each axis x, y, and z, the standard deviation of all localizations per trace ID is calculated;
• for each axis x, y, and z, the histogram of those standard deviations is plotted;
• a vertical line corresponding to the median of all standard deviations for each axis is overlaid to each histogram;
• the line label reports the median value +/- robust standard deviation of the deviations.

This metric is updated in real time, reflecting the changes on the dataset upon subsequent filtering steps.

Please note that in case of 2D acquisition, the z axis is ignored.

The solid vertical line in the plot indicates the median value, with the dashed ones corresponding to the interquartile ranges.

Other analysis tools

Histogram Plotter

Although the Data Plotter can represent any MINFLUX variable as a scatter plot (via its toolbar), some variables are easier to interpret when displayed as a histogram (such as efo, cfr and trace length in the Analyzer). The Histogram Plotter (Analysis > Histogram Plotter) makes possible the representation of additional variables (eco, dwell and tim_tot) in histogram format outside the Analyzer.

Image 14: Histogram Plotter.

Trace stats viewer

Several statistics are reported per trace (Analysis > Trace Stats Viewer). They can be visualized in the Trace Stats Viewer and exported to .csv file from the File > Export trace stats menu. The reported/calculated values are:

tid: trace ID.

n: number of localizations in this trace.

mx, my, mz: average x, y and z localization coordinates of the trace.

sx, sy, sz: localization precision as the standard deviation of the x, y, and z coordinates (normalized by n - 1).

sxy: combined, lateral localization precision, calculated as $\sqrt{\textrm{sx}^{2} + \textrm{sy}^{2}}$.

exy: standard error of the lateral localization precision, calculated as $\frac{\textrm{sxy}}{\sqrt{n}}$.

rms_xy: lateral root-mean square of the localization precision, calculated as $\sqrt{\frac{\textrm{sx}^{2} + \textrm{sy}^{2}}{2}}$.

ez: standard error of the vertical localization precision, calculated as $\frac{\textrm{sz}}{\sqrt{n}}$.

fluo: fluorophore ID associated to the trace.

tim_tot: total duration of the trace (in ms).

avg_speed: displacement speed of the localisations averaged over the entire tid.

total_dist: total distance covered by a given tid.

Image 15: Trace Stats Viewer.

Fourier Ring Correlation analysis

pyMINFLUX implements Fourier Ring Correlation analysis (Analysis > FRC Analyzer) (as described in Ostersehlt, L.M., Jans, D.C., Wittek, A. et al. DNA-PAINT MINFLUX nanoscopy. Nat Methods 19, 1072-1075 (2022). https://doi.org/10.1038/s41592-022-01577-1) in the FRC Analyzer. You can start the FRC Analyzer from the Analysis menu.

The FCR Analyzer allows to study the evolution of the signal resolution over time, and gives an idea of when it makes sense to stop acquiring new data.

The parameters are:

• Spatial (xy) resolution (nm): the pixel size of the images to be correlated. Each localization is randomly assigned to one of two synthetic images with a 50% probability and binned into virtual pixels of the specified size (default is 4 nm). The created images are then correlated in Fourier space and the concentric frequency distribution is analyzed to extract the (average) resolution of the signal.
• Endpoint estimation: check to calculate the resolution of the entire dataset. Otherwise, a temporal analysis is performed.
• Temporal resolution (s): temporal bin size to consider. The entire acquisition is broken down into bins of the specified duration, and the resolution is estimated for the cumulative distribution of the time intervals ([0; $t_1$], [0; $t_2$], ..., [0, $t_N$]): this allows to estimate the evolution of the signal resolution over time. In many cases, the resolution is expected to reach a plateau after a while. The calculation for [0; $t_N$] corresponds to the endpoint estimation. Notice that the values will slightly change with every run because of the random assignment of localizations to the two images.
• Number of repeats: number of repetitions of the FRC calculation for each of the bins [0; $t_i$].

The plot shows the mean resolution +/- standard error for each of the bins.

Tracking support

Starting with Version 0.4.0, pyMINFLUX offers initial support for single-molecule tracking experiments. Once a tracking dataset is identified as such through the checkbox on the Importer, the following changes apply:

1. Subsequent localisations within a trace (same tid) will be connected by a line on the Data Plotter.
2. Localisation precision histograms on the Analyzer are substituted by the following tracking-specific metrics:

• Time resolution
• Average speed per trace
• Total distance covered per trace

Saving and exporting data

Data and associated settings can be saved to the native pyMINFLUX .pmx file format. Alternatively, the filtered dataset can be exported as a comma-separated value (*.csv) format with the Export button in the Pipeline Toolbar of the File > Export data menu. Please notice that localizations that were filtered out will be physically discarded in the saved and exported files.

Only datasets imported through the Pick last valid iteration option in the Importer can be saved. This ensures that .pmx files will always contain values read from the last available iteration. The export option however, is always available regardless of the Importer settings.

In addition, File > Export trace stats exports a series of additional, per-trace measurements and statistics (the same values that can be visualized in the Trace Stats Viewer).

Plot export

All plots can be exported as high-resolution .png files via the Export plot entry in the RMB context menu. The resolution (DPI) of the figure can be set in the Global settings (see below).

Global settings

The Options window allows to customize several aspects of the software:

1. Minimum number of trace localizations allows to select the minimum number of localizations within a trace to be considered for plotting and precision calculation. This is applied upon loading and after each filtering step (that it, if the length of a trace falls under the threshold after any filtering step, it will be dropped).

2. z scaling factor to compensate for the refractive index mismatch between the coverglass and the sample.

3. EFO bin size (Hz) to be used for efo distribution plotting on the Analyzer (it defaults to 1 kHz)

4. EFO expected frequency for single emitters (Hz) to be used for automated efo threshold selection.

5. EFO/CFR default plot range for efo, cfr and Localization precision default plot range for the histograms in the Analyzer.

6. Whether to use relative eco count as weighting factor during the calculation of the average localization position for each trace ID.

7. Resolution (in dots per inch) for the all plots when exported as .png images.

8. Whether to show the console at application start.

All options are accompanied by a ? button for quick help.

Settings can be set as the new default values that will be applied to each new .npy or .mat file when imported! .pmx file will use the settings that are stored in the .pmx file itself.