Skip to main content

14  Overview

Data Analysis lets you explore a table of measurements with interactive plots, statistical comparisons, and machine learning. Upload a table from Data Extraction or any other source. The app guesses column roles and feature groups and opens a column editor so you can check or adjust them before plotting.

14.1 General Workflow

  1. Upload your table, check the guessed column roles, and click Use for this upload. A saved profile that matches the headers exactly skips this check.
  2. Choose an analysis type and method on the left, then select its numerical features.
  3. Use the categorical and numerical filters to select the observations to analyze. Later controls operate on this filtered dataset.
  4. Choose groups and visual encodings. In Feature Comparison and 2D Feature Distribution, Collapse by can replace individual observations with one mean per category within each analysis group.
  5. Adjust the method-specific controls, plot style, and hover over points to inspect observations.
  6. Export the analysis as a Python script to reproduce or customize it. GMM analyses also offer labeled CSV downloads.

The plots and results update as you change the controls.

14.2 Methods

Analysis type Method Numerical input
Univariate Feature Comparison One feature compared across groups
Univariate Feature Histogram One feature’s histogram or Gaussian mixture model
Bivariate 2D Feature Distribution Two features on a scatter plot
Bivariate Phasor Plot A matching pair of phasor G and S coordinates
Multivariate Dimension Reduction At least two features projected into two dimensions
Multivariate Classification One or more features used to predict categorical labels

Phasor Plot is available after upload only when the table contains a complete G/S pair with the expected phasor column names. All methods use the shared controls below, with additional controls described in their chapters.

14.3 Input

The same uploader handles extraction results and tables from other sources, in both the desktop and hosted apps. It accepts CSV, TSV/TXT with tab, semicolon, or pipe separators, Excel .xlsx/.xlsm, and OpenDocument .ods. Spreadsheet uploads use the first sheet.

A saved profile whose headers match exactly supplies the column roles and groups, and analysis opens directly. Otherwise, the column editor opens with guessed roles and groups and flags doubtful guesses; choose Use for this upload or save a reusable profile. To change them later, click ✏️ Fix Categorical & Numerical features below the upload summary. See the configuration walkthrough.

14.3.1 Requirements

Use a plain table with column headers on the first row, one observation per row, and at least one usable numerical measurement. Categorical columns, a unique row identifier, and a field-of-view column are optional for every upload.

14.3.2 Column roles

Each column has one role. The app suggests roles after upload; adjust them according to what the values mean.

  • Row ID identifies an individual observation in hover text, such as a cell or flower. This role is optional and can belong to at most one column. Its values must be nonmissing and unique after conversion to text. Without an assigned Row ID, the app creates row numbers from 1 through the number of input rows. See automatic row numbering and changing identifiers.
  • Categorical supplies labels for filters and visual grouping, such as species, treatment, day, or patient. Numeric codes can be categorical when they represent labels rather than quantities. Field-of-view labels such as image_name also use this role. Categories are stored as text. If every nonmissing value in a numeric category column is a whole number, labels use 1 rather than 1.0; missing values become N/A.
  • Numerical supplies measurements for plotting and analysis, such as length, intensity, or lifetime. At least one column with this role must contain usable numbers. Numerical columns can be organized into feature groups, each providing a dropdown in the feature pickers.
  • Ignore excludes a column from analysis while recording its header in the profile, so future uploads can still be matched to the complete table structure.

Use the column’s Role dropdown to change how it is used, then click Use for this upload or save the profile. For example, assigning Categorical to a numeric treatment code makes it available as a category filter. Changing a Numerical column to another role removes its feature-group assignment. See the column-review walkthrough.

Tip

If a numerical feature is missing from the feature pickers, including Uncategorized Features, first check that its Role is Numerical in the column review. Then inspect its values for stray text such as --. If non-numeric values account for 1% or less of the column’s non-empty values, the app converts the column to numeric, replaces those cells with NaN, and reports their count. Above that threshold, the column remains text and cannot be used as a numerical feature until those values are cleaned, even if most values are numbers.

14.3.3 Warning Messages

Warnings report cleanup such as dropping empty columns or converting a small number of stray non-numeric values to NaN (see feature recognition). Missing measurements can remain in the table. Plot methods use rows with valid values for their selected numerical features; Classification passes the selected rows to the classifier and reports an error if it cannot accept their missing measurements.

14.3.4 Error Messages

Errors block applying column choices or analysis until the input or roles are corrected. Examples include a malformed table, an assigned Row ID containing missing or duplicate values, or no usable Numerical column. Duplicate row identifiers are not silently removed. In the column review, correct the identifier, choose another column, or leave Row ID unassigned to use generated row numbers.

14.4 Shared Interactive Widgets

Feature selection is on the left; filters, grouping controls, plots, and exports are on the right. Only controls supported by the current method are shown.

14.4.1 Numerical Selection Widgets

Numerical features use the groups guessed or applied in the column review. Recognized extraction headers are grouped by extractor and channel; other headers can form groups from shared prefixes. Ungrouped measurements appear under Uncategorized Features. Each group has its own picker.

Univariate Analysis

Choose one feature across all groups. Selecting it resets the other pickers to Select.

Bivariate Analysis

For 2D Feature Distribution, choose an X feature and a different Y feature from the same or different feature groups. Each axis uses the single-feature selection behavior above, and the X feature is excluded from the Y options. Once selected, an axis’s pickers collapse into an expander labeled with the full feature name; reopen it to change the selection. Phasor Plot instead selects a channel and a complete G/S harmonic pair.

Multivariate Analysis

Each feature group has a picker that accepts multiple selections. Choose All to include every feature in that group.

Except: selects every feature in a group except the ones you name. For example, select Except: together with intensity_sum to exclude that measurement while keeping the other features. Selecting All clears everything else, while selecting a feature clears All but keeps Except:, so you can add exclusions as you click.

Numerical feature groups with multiselect pickers. Intensity texture_nadh and Intensity texture_fad each show Except: and intensity_sum; the other categorized groups show All, and Derived Features contains redox_ratio.

Multivariate feature pickers use Except: to exclude intensity_sum from both the NADH and FAD texture groups.

14.4.2 Filter Widgets

Categorical Filters

Categorical filter row with selections for the treatment, cell line, dish, and image categories.

Categorical filters select the observations included in the analysis.

Use categorical filters to select observations by treatment, day, or other labels. Each categorical feature has a filter, up to four per row. Selecting All includes every category and clears individual selections; selecting a category clears All.

Use Except: when it is easier to name the categories to leave out. For example, select Except: and one value in an image_name filter to keep every other field of view. The exclusion is evaluated against the current data, so categories added by widening another filter are included unless you excluded them explicitly.

The filters work as a set rather than in sequence: each one offers only the categories that still have data under everything else you have selected. That means you can approach a subset from whichever direction is natural — narrowing treatment first and then day leaves you the same options as doing it the other way around — and no combination is out of reach because of the order the categorical features happen to be listed in your configuration.

One consequence is worth knowing about. Tightening one filter can deselect a choice you made elsewhere. Say you have fields of view picked out under image_name and then narrow cell_line to Panc1: every MCF7 field of view among them is left with no rows. Rather than hand you an empty plot, FLIM Playground deselects those fields of view and tells you which selection ruled them out.

Numerical Filters

Each numerical filter row specifies a condition:

  • Feature: the numerical feature to filter on
  • Operator: > or <=
  • Threshold: enter a value within the displayed range, which updates based on earlier filters.
  • Add another: show the next condition. Clear it to stop applying later rows; choose None in a feature picker to stop at that row.

Plots and analyses use the data remaining after both sets of filters.

Important

Report all numerical filters used in your analysis.

14.4.3 Visual Channels Widgets

Visual encodings map categories to color, opacity, or marker shape, making patterns easier to compare1. Grouping controls also determine which observations are compared or modeled together.

Method Grouping and layout Point encoding
Feature Comparison Color by / Group by, Separate by, Collapse by Choose one of Opacity, Subcolor, or Shape, then a column
Feature Histogram Color by, Separate by —
2D Feature Distribution Color by, Separate by, Collapse by Choose Opacity or Shape, then a column
Phasor Plot Color by, Separate by Independent Opacity by and Shape by pickers
Dimension Reduction Color by, up to two columns in Separate by Independent Opacity by and Shape by pickers
Classification Classify by forms the target classes —

Feature Comparison controls for Separate by, Color by, Collapse by, and the Opacity, Subcolor, or Shape selector with one shared column picker.

Feature Comparison controls for grouping, averaging by category, and point encoding.

Color by

Choose one or more categorical features in Color by. Each distinct combination receives a color; combined labels use :: between categories. In Feature Comparison, these groups also define the x-axis positions. When its Subcolor mode is selected, Color by becomes Group by: it still defines the comparisons, while the selected subcolor column supplies point colors.

Leave the grouping picker empty to analyze all filtered observations as one group. In Classification, Classify by defines the labels the classifier learns instead.

Note 14.1: How to order the groups

The order of selected categorical features determines the grouping hierarchy. For example, choose cell_line and then treatment to keep each cell line’s treatments together; reverse the selection order to keep treatments together.

Within each feature, groups use numeric-alphabetical sorting: labels containing a number are ordered by that number, then by their text. Thus Panc1 precedes MCF7, and Day 30 precedes Day 100. Feature Comparison also provides custom x-axis ordering.

Opacity and Shape by

Opacity by gives ordered categories different transparencies, and Shape by gives them different marker shapes. Each uses one categorical column, with categories ordered numeric-alphabetically. These encodings change the appearance of points while preserving the groups used for modeling.

Dimension Reduction encoding row showing two Separate by columns, Color by, Opacity by, and Shape by.

Dimension Reduction keeps independent opacity and shape controls beside its category-map and color selections.

Feature Comparison shares one column picker between Opacity, Subcolor, and Shape. 2D Feature Distribution shares one between Opacity and Shape. Select the mode above the picker, then choose a column; switching modes keeps that column when it is available. Clear the column to turn the encoding off. Only the active mode is applied.

Separate by

Separate by organizes the current data into category views:

The separation column cannot also be used for Color by, except in Dimension Reduction, where separation highlights parts of one shared embedding.

Collapse by

In Feature Comparison and 2D Feature Distribution, Collapse by averages observations that share a value in a selected categorical column, separately within each analysis group. The category determines what each mean represents. For example, choose dish to plot one mean per dish within each treatment and cell line, or patient to average observations from the same patient within each group.

The resulting category means become the input to the method’s summaries, statistics, and models. The method chapters explain which measurements enter each mean and how SuperPlot can show the original observations alongside them. Choose the grouping columns first: the same column cannot also be selected for collapse.

14.4.4 Unique ID Hover

Hover over a point to see its measurement values and identifier. The identifier uses the assigned Row ID column’s name, or ID when the app generated row numbers. Field-of-view columns remain ordinary categories for filtering and grouping.

With Collapse by, the hover identifies the category and the number of observations averaged into that point, such as dish1 (n=1874). SuperPlot’s smaller observation points retain their individual identifiers.

14.4.5 Plotting Configuration Widgets

Plot Styling inputs for Point Size, Axis Label Font Size, Legend Font Size, Color Map, and Show group counts in legend.

Plot Styling controls point size, text sizes, the color map, and optional legend counts.

Under Plot Styling, adjust Point Size for point plots, Axis Label Font Size, Legend Font Size, and Color Map when color groups are present. Available palettes include tab10, tab20, colorblind, Set1–Set3, Pastel1, Pastel2, Accent, viridis, plasma, inferno, magma, and cividis.

Show group counts (n) in legend adds counts where supported. Counts refer to the points used in the analysis: individual observations, or category means when Collapse by is active. When Separate by is active, Phasor counts only points from the selected separation category, while 2D Feature Distribution keeps one shared legend whose counts come from the full filtered table. Histogram panels report their own group counts; Dimension Reduction’s shared legend reports counts for the full embedding.

Classification places its font-size controls between the metric tables and the ROC/confusion-matrix plots.

14.4.6 Feature Labels

Numerical features extracted by Data Extraction are automatically rendered in proper FLIM notation on plot axes, legends, and hover text. For example, the column Lifetime fit_nadh: a1 is shown as “nadh \(\alpha_1\) (%)”, and other extracted features map to symbols such as “\(\tau_1\) (ps)”, “\(\tau_m\)”, “\(\tau_{m,i}\)”, “\(\chi_r^2\)”, and “\(\tau_{\mathrm{mod}}\)”. The mapping (channel + Greek/scientific symbol + unit) follows the feature naming convention introduced in Lifetime Features (Fit). Columns that are not recognized — identifiers, categorical features, or arbitrary user-provided columns — are displayed unchanged. The same labels are used in the exported script, so its figures match what you see in the app.

14.4.7 Export Workflow as Python Script

Click Export the entire analysis as a Python script below the results and styling controls. The script records the selected features, filters, grouping, point encodings, plot style, and method settings, including collapse, category separation, GMM export names, and any promoted category panel. It also records the upload’s column choices, including temporary edits applied with Use for this upload.

Export the entire analysis as a Python script download button.

Download a Python script that records the current analysis settings.

Keep the original uploaded table beside the downloaded .py file. The dataset is not embedded in the script. If you rename or move the table, edit DATA_PATH near the top of the script to match its filename or path.

Install uv, open a terminal in the folder containing the script and table, and run:

uv run analysis.py

Replace analysis.py with the downloaded script’s filename.

Scripts declare Python 3.11 or newer and the required packages in inline metadata. uv downloads a compatible Python if needed, installs the packages in an isolated environment, and runs the analysis.

The script reproduces the analysis with matplotlib and saves SVG figures in the working directory. You can edit these figures or use them in a publication.

For 1D and 2D GMM analyses, the app also offers labeled CSV downloads. Those downloads contain the analyzed data, including any collapse or log transformation. In the Python script, set SAVE_DERIVED_DATA = True to write the corresponding labeled CSV alongside the figures.

1.
Cleveland, W. S. & McGill, R. Graphical perception: Theory, experimentation, and application to the development of graphical methods. Journal of the American Statistical Association 79, 531–554 (1984).