Interactive visualization components for mass spectrometry data in Streamlit, backed by Vue.js.
- Cross-component selection linking via shared identifiers
- Memory-efficient preprocessing via subprocess isolation
- Automatic disk caching with config-based invalidation
- Cache reconstruction - components can be restored from cache without re-specifying configuration
- Table component (Tabulator.js) with server-side pagination, filtering, sorting, go-to, CSV and Excel export
- Line plot component (Plotly.js) with highlighting, annotations, zoom
- Mirror plot component for paired-spectrum comparison with independent per-side filtering and shared click selection
- Heatmap component (Plotly scattergl) with multi-resolution downsampling for millions of points
- Clustered heatmap component (Plotly) for feature-by-sample matrices, with row/column dendrograms and a group annotation bar
- Volcano plot component for differential expression visualization with significance thresholds
- PCA component for sample-level dimensionality reduction with per-group coloring and confidence ellipses
- Sequence view component for peptide visualization with fragment ion matching and auto-zoom
- Deconvolved spectrum component for charge-state deconvolution results: deconvolved masses, their annotated raw peaks per charge state, and sequence tag ladders
- Series plot component for continuous curves (score densities, calibration curves, chromatogram overlays)
- 3D plot component drawing points as stems (e.g. isotope peaks across charge states) or as traces (e.g. the mass traces of a feature)
- Protein sequence view component with matched fragment ions, tag coverage, truncations, modifications and internal fragments, linked to a fragment table
- Protein structure view component (3Dmol.js) colouring a PDB or mmCIF structure by the fragment evidence of a sequence entry, with in-view upload and removal of structure files
- Batched reruns (
defer_reruns()) so a click across many linked components costs one script rerun - Differential expression analysis (
openms_insight.analysis) - filtering, imputation, normalization, statistical testing and GO enrichment over Polars LazyFrames
pip install openms-insightGO enrichment (openms_insight.analysis.enrichment) needs two
additional packages:
pip install "openms-insight[analysis]"Everything else - every component, and the rest of openms_insight.analysis -
works with the base install.
import streamlit as st
from openms_insight import Table, LinePlot, Heatmap, VolcanoPlot, StateManager
# Create state manager for cross-component linking
state_manager = StateManager()
# Create a table - clicking a row sets the 'item' selection
table = Table(
cache_id="items_table",
data_path="items.parquet",
interactivity={"item": "item_id"},
column_definitions=[
{"field": "item_id", "title": "ID", "sorter": "number"},
{"field": "name", "title": "Name"},
],
)
table(state_manager=state_manager)
# Create a linked plot - filters by the selected 'item'
plot = LinePlot(
cache_id="values_plot",
data_path="values.parquet",
filters={"item": "item_id"},
x_column="x",
y_column="y",
)
plot(state_manager=state_manager)Components communicate through identifiers using three mechanisms:
filters: INPUT - filter this component's data by the selectionfilter_defaults: INPUT - default value when selection is Noneinteractivity: OUTPUT - set a selection when user clicks
# Master table: no filters, sets 'spectrum' on click
master = Table(
cache_id="spectra",
data_path="spectra.parquet",
interactivity={"spectrum": "scan_id"}, # Click -> sets spectrum=scan_id
)
# Detail table: filters by 'spectrum', sets 'peak' on click
detail = Table(
cache_id="peaks",
data_path="peaks.parquet",
filters={"spectrum": "scan_id"}, # Filters where scan_id = selected spectrum
interactivity={"peak": "peak_id"}, # Click -> sets peak=peak_id
)
# Plot: filters by 'spectrum', highlights selected 'peak'
plot = LinePlot(
cache_id="plot",
data_path="peaks.parquet",
filters={"spectrum": "scan_id"},
interactivity={"peak": "peak_id"},
x_column="mass",
y_column="intensity",
)
# Table with filter defaults - shows unannotated data when no identification selected
annotations = Table(
cache_id="annotations",
data_path="annotations.parquet",
filters={"identification": "id_idx"},
filter_defaults={"identification": -1}, # Use -1 when identification is None
)
# Two filters on one table. ALL shows every row while nothing is selected, so
# unselecting a mass shift lifts that filter and keeps the protein one. A list
# column ("shift_ids": [1, 3]) matches when one of its values is selected.
from openms_insight import ALL
proteoforms = Table(
cache_id="proteoforms",
data_path="proteoforms.parquet",
filters={"protein": "protein_id", "mass_shift": "shift_ids"},
filter_defaults={"mass_shift": ALL},
)Interactive table using Tabulator.js with filtering dialogs, sorting, pagination, and CSV export.
Table(
cache_id="spectra_table",
data_path="spectra.parquet",
interactivity={"spectrum": "scan_id"},
column_definitions=[
{"field": "scan_id", "title": "Scan", "sorter": "number"},
{
"field": "rt",
"title": "RT (min)",
"sorter": "number",
"hozAlign": "right",
"formatter": "money",
"formatterParams": {"precision": 2, "symbol": ""},
},
{"field": "precursor_mz", "title": "m/z", "sorter": "number"},
],
index_field="scan_id",
go_to_fields=["scan_id"],
initial_sort=[{"column": "scan_id", "dir": "asc"}],
default_row=0,
pagination=True,
page_size=100,
)Key parameters:
column_definitions: List of Tabulator column configs (field, title, sorter, formatter, etc.)index_field: Column used as unique row identifier (default: 'id')go_to_fields: Columns available in "Go to" navigationinitial_sort: Default sort configurationpagination: Enable server-side pagination (default: True). Only the current page of data is sent to the browser, dramatically reducing memory usage for large datasets.page_size: Rows per page (default: 100)hidden_columns: Columns that start hidden. The viewer can show them, or hide any other column, from the column menu in the table toolbar. Their choice is kept in their browser, per table.search: A search box in the toolbar.Truesearches the text columns, a list of column names searches those (they need not be shown). Rows must contain every word, in any of the columns; case is ignored and words are matched literally.search_placeholdersets its placeholder.numeric_filters: Numeric columns offered in the filter dialog as a one-sided threshold, with one-click suggested values and an optional default.filter_presets: Ready-made filters at the top of the filter dialog, each a check box with a label, optional help and a default state. The same card lists the filters the viewer set (column filters, search), each removed by unticking it. A preset that is on keeps only the rows matching all of its conditions ({"column", "op", "value"}, op one of==,!=,<=,>=,<,>,in,not in) and counts in the filter badge and chips. The sequence view's fragment table uses the same presets.collapse_columns: Columns that do not fit the table's width fold into a row overview (default).Falsekeeps every column and scrolls the table sideways instead, for a narrow table whose columns all matter. It does not affect the cache.keyboard_navigation: Step through the rows with the keyboard once a row is clicked or the table is tabbed to (default: True). Up and Down select the previous and next row, Page Up and Page Down move by the rows in view, Home and End go to the first and last row, across pages. The row reached is highlighted at once and selected, as if clicked, once no key has been pressed for 200 ms, so holding a key down reruns the app once rather than for every row. Keys typed in the search box or a dialog are left alone.Falseturns it off; it does not affect the cache.
Filters. The filter button opens a dialog with a filter per column: values to keep, a text pattern, or for numbers "at least", "at most" or a range. Every filter, and the search, runs in Python over the whole table. The filters in force show as chips under the toolbar, each removable, with "Clear all"; they are kept when the table is drawn again.
Table(
cache_id="proteins",
data=proteins,
search=True, # or ["accession", "gene", "description"]
search_placeholder="Accession, gene or protein name",
numeric_filters={
"q_value": {
"op": "<=",
"suggestions": [{"value": 0.01, "label": "1 % (run)"}, 0.001],
},
"peptides": {"op": ">=", "suggestions": [2, 3], "default": 2},
},
filter_presets=[
{
"label": "Hide contaminants",
"column": "is_contaminant",
"op": "!=",
"value": True,
"default": True,
},
{
"label": "Well supported",
"filters": [
{"column": "peptides", "op": ">=", "value": 2},
{"column": "q_value", "op": "<=", "value": 0.01},
],
},
],
)Custom formatters: In addition to Tabulator's built-in formatters, these custom formatters are available:
scientific: Exponential notation (e.g., "1.23e-05") - useformatterParams: {precision: 3}signed: Explicit +/- prefix (e.g., "+1.234") - useformatterParams: {precision: 3, showPositive: true}badge: Colored pill/badge for categorical values - useformatterParams: {colorMap: {"Up": "#FF0000"}, defaultColor: "#888"}
column_definitions = [
{
"field": "pvalue",
"title": "P-value",
"formatter": "scientific",
"formatterParams": {"precision": 2},
},
{
"field": "log2fc",
"title": "Log2 FC",
"formatter": "signed",
"formatterParams": {"precision": 3},
},
{
"field": "regulation",
"title": "Status",
"formatter": "badge",
"formatterParams": {
"colorMap": {"Up": "#d62728", "Down": "#1f77b4", "NS": "#888888"}
},
},
]CSV export. The table's download button exports every row that passes the
current filters, in the current sort order, with every column of the data, not
only the page on screen and the columns in column_definitions. Displayed
columns come first. The same export is available in Python:
table.export_data() # whole table, initial sort
table.export_data(state) # as rendered for this selection stateExcel export. With xlsxwriter installed (pip install openms-insight[excel]),
the download button of a paginated table opens a menu with CSV and Excel (.xlsx).
The workbook holds the same rows, with the column titles as its header and list
columns joined with ; , and an "About" sheet: the table, when it was exported,
the number of rows, the sort, the filters and the search. export_info adds rows
of your own to that sheet, such as the run and its settings; it is not part of the
cache configuration:
Table(..., export_info={"Run": "Run 3", "Database": "yeast.fasta, 6,115 proteins"})Text is written as text, so a value starting with = is not run as a formula. A
sheet holds at most 1,048,575 rows; beyond that the About sheet says how many were
left out.
Stick-style line plot using Plotly.js for mass spectra visualization.
LinePlot(
cache_id="spectrum_plot",
data_path="peaks.parquet",
filters={"spectrum": "scan_id"},
interactivity={"peak": "peak_id"},
x_column="mass",
y_column="intensity",
highlight_column="is_annotated",
annotation_column="ion_label",
title="MS/MS Spectrum",
x_label="m/z",
y_label="Intensity",
styling={
"highlightColor": "#E4572E",
"selectedColor": "#F3A712",
"unhighlightedColor": "lightblue",
},
)Key parameters:
x_column,y_column: Column names for x/y valueshighlight_column: Boolean/int column indicating which points to highlightannotation_column: Text column for labels on highlighted pointsstyling: Color configuration dictkeep_zoom: Start with the zoom pinned (defaultFalse). The pin button in the plot toolbar toggles it: pinned, the zoomed x range stays when another spectrum is selected; unpinned, each new spectrum is shown in full. Double-click resets the zoom either way.MirrorPlotandDeconvolvedSpectrumhave the same button and argumenttop_peak_labels,show_top_peak_labels: The Label top peaks button (a number sign) in the plot toolbar shows the m/z of the most intense peaks in view, 10 by default (top_peak_labels=0removes the button). The labels are placed again on every zoom or pan, most intense first, leaving out any that would overlap, so zooming in labels more peaks.show_top_peak_labels=Truestarts with them shown. Peaks carrying one of your own labels keep only that label. Render-time only, likekeep_zoomwindow_identifier,window_tolerance: Shade an x window kept in the shared state, e.g. the m/z window of an XIC shown elsewhere on the page. The value underwindow_identifieris a centre (widened bywindow_toleranceon each side: a number of Da, default 0.01, or a string such as"10 ppm","0.02 Da"or"0.5 m/z"),[low, high], orNonefor no band. The band is labelled (1950.7319 ± 10 ppm) and stays at least 3 px wide, so it is visible at full range.MirrorPlottakes the same two arguments and shades the window over both spectra. While a window is set, a Window button in the plot toolbar hides the band and shows it again. Render-time onlyx_markers,x_marker_tolerance: Labelled positions on the x axis, as{label: x}or a list of{"x", "label", "color"}dicts (labelandcoloroptional). Each marker gets a dotted guide over the plot's height in its own colour (or the one given) and its label at the top. Withx_marker_tolerance(x units) the most intense peak within that distance of a marker is its peak: it gets a dot in the marker's colour, the label moves above it, and the hover read-out names it; a marker without a peak keeps a fainter guide. Labels that would overlap are left out, left to right, so zooming in shows more of them. A Markers button in the plot toolbar, shown only when the plot has markers, hides them and shows them again. Expected positions such as reporter ions or diagnostic fragments:x_markers={"126": 126.1277, "127N": 127.1248, ...}, x_marker_tolerance=0.003. Render-time onlyusi: The Universal Spectrum Identifier of the shown spectrum (mzspec:<collection>:<run>:<index type>:<index>[:<interpretation>]), for a USI button in the plot toolbar that copies it, e.g. to look the spectrum up in a repository or cite it. Any part may be a placeholder{identifier}, which takes the value the shared state holds under that identifier:usi="mzspec:PXD000561:run1:scan:{spectrum}"follows the spectrum picked elsewhere on the page. The button shows once every placeholder has a value, and its tooltip shows the USI it copies.MirrorPlottakes the same argument. Render-time only
Hovering shows the peak nearest the mouse along x, anywhere in the plot's height: a dot on the peak top and a box with its x and y (and its annotation, if any). Within two pixels of the mouse the most intense peak wins, so a dense profile spectrum reports the peak that is drawn.
The mouse wheel zooms x around the mouse while y follows the peaks in view; zooming out past the full extent shows the full view. Shift + wheel or a sideways (trackpad) wheel pans x, and so does dragging with the middle button; panning stops at the ends of the data. A double-click shows the full view. Outside the plot area the wheel scrolls the page.
Two stick-style spectra rendered against a shared x-axis with the bottom half flipped, used for comparing paired spectra (experimental vs. theoretical, sample vs. reference, MS1 vs. MS2 fragments). Each half is filtered independently, while clicks on either half feed into one shared selection.
from openms_insight import MirrorPlot
mirror = MirrorPlot(
cache_id="mirror",
data_path="peaks.parquet",
filters_top={"spectrum_a": "scan_id"}, # top half follows spectrum_a
filters_bottom={"spectrum_b": "scan_id"}, # bottom half follows spectrum_b
interactivity={"selected_peak": "peak_id"}, # click in either half -> shared
x_column="mass",
y_column="intensity", # positive for both halves
highlight_column="is_annotated",
annotation_column="ion_label",
title_top="Experimental",
title_bottom="Reference",
x_label="m/z",
y_label="Intensity",
)
mirror(state_manager=state_manager, height=600)Key parameters:
filters_top/filters_bottom: Per-side filter mappings (independent selections drive each half)filter_defaults_top/filter_defaults_bottom: Per-side default values when the corresponding selection isNoneinteractivity: Shared across both halves — a click in either half writes the same identifierx_column,y_column: Shared schema. Provide y values as positive numbers; the bottom half is flipped at render timehighlight_column,annotation_column: Shared schema for highlights and label texttitle_top,title_bottom: In-figure labels for each half (rendered inside the plot, not above it)styling: Color dict withhighlightColor,selectedColor,unhighlightedColor(same defaults as LinePlot)svg_filename: File name (without extension) of the image download (default:title, thenmirror_plot); the format is set as in Image downloadsmeasure,measure_tolerance,measure_residues: The measure tool, on by default (see Measuring)peak_labels: Your own labels on peaks, on by default (see Peak labels)
Behavior:
- The y-axis auto-rescales to the maximum visible peak when zooming, and overlapping annotation labels are re-evaluated at the new pixel/data ratio so previously hidden labels reappear when there is room (matches LinePlot's zoom behavior)
- Tick labels show absolute intensity on both sides — the bottom half is flipped only for layout, not for the displayed values
- Marker traces are kept in addition to stick shapes so Plotly fires
plotly_clickevents; the click handler picks the side viacurveNumberand routes the row's interactivity column value to the shared selection - In measure mode the two peaks of a measurement must be in the same half; a click in the other half starts a new measurement there
set_top_dynamic_annotations(...)/set_bottom_dynamic_annotations(...)allow another component (e.g. aSequenceView) to push fragment-ion annotations into one half without invalidating the cache
2D scatter heatmap using Plotly scattergl with multi-resolution downsampling for large datasets (millions of points).
Heatmap(
cache_id="peaks_heatmap",
data_path="all_peaks.parquet",
x_column="retention_time",
y_column="mass",
intensity_column="intensity",
interactivity={"spectrum": "scan_id", "peak": "peak_id"},
min_points=30000,
x_bins=400,
y_bins=50,
title="Peak Map",
x_label="Retention Time (min)",
y_label="m/z",
colorscale="Portland",
)Key parameters:
x_column,y_column,intensity_column: Column names for axes and colormin_points: Target size for downsampling (default: 20000)x_bins,y_bins: Grid resolution for spatial binningcolorscale: Plotly colorscale name (default: 'Portland')reversescale: Invert colorscale direction (default: False)log_scale: Use log10 color mapping (default: True). Set to False for linear.low_values_on_top: Prioritize low values during downsampling and display them on top (default: False). Use for scores where lower = better (e.g., e-values, PEP, q-values).intensity_label: Custom colorbar label (default: 'Intensity')hover_column: Column whose text is shown when hovering a point, above its intensityon_select: Selections a click sets besidesinteractivity, as Table'son_select(None clears one)highlight: Mapping of identifier names to column names. The points whose column value is the identifier's selected value are ringed, whichever component selected it (looked up in the full data, so a point the current level dropped is still marked)color_columns: Your own further numeric columns the points can be colored by, as label to column. The toolbar's Color button lists the intensity and these, with a slider that shows only the points from a value up (see Plot toolbar)layer_column: Your own column whose values are layers the toolbar's Layers button shows or hides. In categorical mode the categories are the layers unless this names another columncolorbar_editor: The colorbar below the plot opens an editor on click (default True; False keepscolorscale)
Coloring by your own columns, and layers: Nothing in these options is specific to mass spectrometry: they take any columns of your data. A map of weather stations, colored by rainfall, temperature or sunny days, with the station networks as layers:
Heatmap(
cache_id="stations",
data=stations,
x_column="longitude",
y_column="latitude",
intensity_column="rainfall",
log_scale=False,
intensity_label="Rainfall (mm)",
color_columns={"Temperature (°C)": "temperature", "Sunny days": "sunny_days"},
layer_column="network", # e.g. "Airport", "Volunteer"
)The columns are checked when the component is built from data: a name that is
not in the data raises a ValueError. They are render-time options, so adding or
changing them reuses the cache. Downsampling keeps the points of highest
intensity; coloring by another column colors those points.
Marking a selection made elsewhere:
Heatmap(
cache_id="identifications",
data=hits, # one row per identified spectrum
x_column="rt",
y_column="mass",
intensity_column="score",
log_scale=False,
intensity_label="Score",
hover_column="name",
interactivity={"hit": "hit_id"}, # a click selects the hit ...
highlight={"hit": "hit_id"}, # ... and the selected hit is ringed,
) # also when a table selected itLinear scale example:
Heatmap(
cache_id="psm_scores",
data_path="psm_data.parquet",
x_column="rt",
y_column="mz",
intensity_column="score",
log_scale=False, # Linear color mapping
intensity_label="Score", # Custom colorbar label
colorscale="Blues",
)Low values on top (PSM scores):
For identification results where lower scores indicate better matches (e.g., e-values, PEP, q-values), use low_values_on_top=True to preserve low-scoring points during downsampling and display them on top of high-scoring points:
Heatmap(
cache_id="psm_evalue",
data_path="psm_data.parquet",
x_column="rt",
y_column="mz",
intensity_column="e_value",
log_scale=True, # Log scale for e-values
low_values_on_top=True, # Keep/show low e-values (best hits)
reversescale=True, # Bright color = low value = best
intensity_label="E-value",
colorscale="Portland",
)Categorical mode:
Use category_column for discrete coloring by category instead of continuous intensity colorscale:
Heatmap(
cache_id="samples_heatmap",
data_path="samples.parquet",
x_column="retention_time",
y_column="mass",
intensity_column="intensity",
category_column="sample_group", # Color by category instead of intensity
category_colors={ # Optional custom colors
"Control": "#1f77b4",
"Treatment_A": "#ff7f0e",
"Treatment_B": "#2ca02c",
},
)Boxes (e.g. LC-MS features):
set_boxes() draws rectangles over the points. Boxes are given per render, so
call it before each render; only boxes in the visible range are sent. With
selection=, clicking a point inside a box sets that identifier to the box's
id, and the selected box is drawn with a thicker outline.
heatmap.set_boxes(
features_df,
x_range=("rt_start", "rt_end"),
y_range=("mz_start", "mz_end"),
id_column="feature_id",
selection="feature",
label="Features",
)
heatmap(key="peak_map", state_manager=state_manager)Grid heatmap for categorical axes (e.g. proteins against samples), with optional hierarchical clustering and dendrograms on either axis.
Use this rather than Heatmap when both axes are labels rather than numbers.
Heatmap is a scattergl point cloud built for continuous axes (RT vs m/z) and
millions of points; ClusteredHeatmap renders an actual grid and ships the whole
matrix in one payload, so it expects tens to low-thousands of cells and has no
pagination, filtering or zoom machinery.
from openms_insight import ClusteredHeatmap
ClusteredHeatmap(
cache_id="protein_heatmap",
data_path="quantification.parquet", # wide: id_col + one column per sample
id_col="ProteinName",
metadata=metadata_df, # columns: sample_id, group
row_cluster=True,
col_cluster=True,
linkage_method="average",
linkage_metric="euclidean",
title="Protein Abundance",
intensity_label="Z-score",
group_colors={"Control": "#1f77b4", "Treatment": "#d62728"},
)(state_manager=state_manager, height=600)Key parameters:
id_col: Column naming each row (e.g. protein name). Every other column is treated as a sample columnmetadata: Optionalsample_id->grouptable. When given, a group color bar is drawn above the heatmaprow_cluster/col_cluster: Cluster that axis and draw its dendrogram (left for rows, top for columns). Skipped automatically when the axis has fewer than 2 entrieslinkage_method/linkage_metric: Passed through toscipy.cluster.hierarchy.linkagecolorscale,reversescale,intensity_label: Cell color mapping and colorbar label. Without acolorscale, cells use a diverging scale centred on 0 (blue, the page colour, orange) that follows the app's light or dark theme, which suits z-scorescolorbar_editor: The colorbar below the plot opens an editor on click (one, two or three colors, presets, reverse, reset); default True, False keepscolorscale- Layout: the heatmap fills the component's width. Row labels sit right of the heatmap; when the rows are too close to label them all, every n-th one is labelled (the heading of the label column says which) and long labels are cut. Hovering a cell shows its full row label, sample, group and value
group_colors: Map group value -> color for the annotation bar. Groups without an explicit color get one from a default palette
No filters or interactivity. Unlike the other components, ClusteredHeatmap
does not participate in cross-component linking: the clustered layout depends on the
full matrix, so there is nothing sensible to filter. Both arguments are accepted (they are
part of the shared signature) but have no effect on what is rendered.
The matrix must be complete when clustering. Hierarchical clustering cannot
compute distances across missing values, so the component raises a ValueError
naming the number of affected rows. Impute first (see
Differential Expression Analysis), or pass
row_cluster=False, col_cluster=False to render an incomplete matrix as-is.
Mouse-wheel zoom is disabled here. The layout anchors the heatmap, both
dendrograms and the group bar to manually positioned axes, which scrollZoom
re-ranges inconsistently. Use the toolbar's box zoom instead.
Interactive volcano plot for differential expression analysis with significance thresholds.
from openms_insight import VolcanoPlot
VolcanoPlot(
cache_id="de_volcano",
data_path="differential_expression.parquet",
log2fc_column="log2FC",
pvalue_column="pvalue",
label_column="protein_name", # Optional: labels for significant points
filters={"comparison": "comparison_id"},
interactivity={"protein": "protein_id"},
title="Differential Expression",
x_label="Log2 Fold Change",
y_label="-log10(p-value)",
up_color="#d62728", # Color for up-regulated
down_color="#1f77b4", # Color for down-regulated
ns_color="#888888", # Color for not significant
)(
state_manager=state_manager,
fc_threshold=1.0, # Fold change threshold (render-time)
p_threshold=0.05, # P-value threshold (render-time)
max_labels=20, # Max labels to show
)Key parameters:
log2fc_column: Column with log2 fold change valuespvalue_column: Column with p-values (automatically converted to -log10)label_column: Optional column for point labelsup_color,down_color,ns_color: Colors for significance categoriesfc_threshold,p_threshold: Significance thresholds (passed at render time, not cached)max_labels: Maximum number of labels to display on significant points
Render-time thresholds: The fc_threshold and p_threshold are passed via __call__(), not __init__(). This allows instant threshold adjustment without cache invalidation.
Sample-level PCA scatter plot, computed directly from a wide quantification matrix.
from openms_insight import PCAPlot
PCAPlot(
cache_id="protein_pca",
data_path="quantification.parquet", # wide: id_col + one column per sample
metadata=metadata_df, # columns: sample_id, group
n_components=4, # compute 4 PCs, display any pair of them
standardize=True, # z-score each feature before fitting
interactivity={"sample": "sample_id"},
title="Sample PCA",
group_colors={"Control": "#1f77b4", "Treatment": "#d62728"},
show_ellipses=True,
)(
state_manager=state_manager,
pc_x=1, # x-axis component, 1-indexed (render-time)
pc_y=2, # y-axis component, 1-indexed (render-time)
)Key parameters:
metadata:sample_id->grouptable. Required wheneverdataordata_pathis givenn_components: How many principal components to compute. Set above 2 to browse further component pairs without recomputingstandardize: Z-score each feature across samples before fitting (defaultTrue; recommended when features are on different scales)show_ellipses: Draw a 95% confidence ellipse per group. Only drawn for groups with at least 3 samplesgroup_colors: Map group value -> color. Each group is its own trace, so the legend is clickablepc_x,pc_y: Which components to plot (passed at render time, not cached)
filters and interactivity map to columns of the computed score table -
sample_id, group, and PC1..PCn - not to columns of the input matrix.
Render-time component selection: like VolcanoPlot's thresholds, pc_x and
pc_y are passed via __call__(). Switching from PC1/PC2 to PC1/PC3 re-renders
immediately; PCA itself is only recomputed when the data, metadata or
n_components change.
Axis labels default to PC{n} (xx.x%) from each component's explained variance
ratio.
Peptide sequence visualization with fragment ion matching. Supports both dynamic (filtered by selection) and static sequences.
# Dynamic: sequence from DataFrame filtered by selection
SequenceView(
cache_id="peptide_view",
sequence_data_path="sequences.parquet", # columns: scan_id, sequence, precursor_charge
peaks_data_path="peaks.parquet", # columns: scan_id, peak_id, mass, intensity
filters={"spectrum": "scan_id"},
interactivity={"peak": "peak_id"},
deconvolved=False, # peaks are m/z values, consider charge states
title="Fragment Coverage",
)
# Static: single sequence with optional peaks
SequenceView(
cache_id="static_peptide",
sequence_data=("PEPTIDEK", 2), # (sequence, charge) tuple
peaks_data=peaks_df, # Optional: LazyFrame with mass, intensity columns
deconvolved=True, # peaks are neutral masses
)
# Simplest: just a sequence string
SequenceView(
cache_id="simple_seq",
sequence_data="PEPTIDEK", # charge defaults to 1
)Key parameters:
sequence_data: LazyFrame, (sequence, charge) tuple, or sequence stringsequence_data_path: Path to parquet with sequence datapeaks_data/peaks_data_path: Optional peak data for fragment matchingdeconvolved: If False (default), peaks are m/z and matching considers charge statesannotation_config: Dict with ion_types, tolerance, neutral_losses settings
Features:
- Automatic fragment ion matching (a/b/c/x/y/z ions)
- Configurable mass tolerance (ppm or Da)
- Neutral loss support (-H2O, -NH3)
- Auto-zoom for short sequences (≤20 amino acids)
- Fragment coverage statistics
- Click-to-select peaks with cross-component linking
- Fragment ion export for every sequence, not just the selected one
Fragment ion export. export_fragment_ions() runs the view's matching (its
annotation_config and deconvolved setting) over every cached sequence,
against the peaks that share its filter columns, and returns one row per matched
ion: the sequence's filter columns, sequence, precursor_charge, ion,
ion_type, ion_number, charge, theoretical_mz, observed_mz,
intensity, mass_error_da, mass_error_ppm and peak_id.
fragments = sequence_view.export_fragment_ions() # matched ions only
fragments = sequence_view.export_fragment_ions(include_unmatched=True)
fragments.write_csv("fragment_ions.tsv", separator="\t")Spectrum plot for charge-state deconvolution results. Each row of data is one spectrum, with list columns: the deconvolved masses and their intensities, the raw peaks, and for each mass the raw peaks assigned to it.
from openms_insight import DeconvolvedSpectrum
spectrum = DeconvolvedSpectrum(
cache_id="deconv_spectrum",
data=spectra, # one row per scan, list columns
filters={"spectrum": "scan_idx"},
mass_identifier="mass", # index into the selected spectrum's mass list
view="deconvolved", # or "annotated", "ladder"
)
spectrum(key="spectrum", state_manager=state_manager)Views:
deconvolved: the masses as sticks. Clicking one selects it.annotated: the raw peaks, with the signal peaks of the selected mass highlighted and each charge state labelledz=N.ladder: the masses with a sequence tag drawn as a ladder, set per render withset_ladder(masses, sequence). Clicking a ladder mass shows its raw peaks.
Fragment ions of a sequence view. With fragment_matches_identifier= (or set_fragment_matches_identifier() per render) set to the identifier a ProteinSequenceView publishes its matched fragments to, the spectrum colours the masses and raw peaks those ions explain by kind (N-terminal, C-terminal, internal) and labels them. Raw peaks are the signal peaks of a matched mass and, for annotated fragments with a charge, the isotope envelope at that charge. The marks follow the sequence view: changing the ion types, the sequence or its modifications updates them. They apply only to the spectrum the matches were made on, compared through the spectrum's first filter column. The Fragments button in the toolbar's Show group hides or shows them.
Line, marker, bar or box plot with one trace per series, for continuous curves where the x values are sampled points rather than peaks (for stick spectra use LinePlot), and for counts or distributions per sample.
mode is "lines" (default), "markers", "lines+markers", "bars" (one bar per x value and series, the series side by side) or "box" (one box per x value and series, drawn from all y values at that x). orientation="h" turns bars and boxes sideways, the x values listed top to bottom, which suits long labels such as GO terms or file names.
from openms_insight import SeriesPlot
SeriesPlot(
cache_id="score_density",
data=densities, # columns: x, y, kind
x_column="x",
y_column="y",
series_column="kind",
series_names={"target": "Target scores", "decoy": "Decoy scores"},
series_colors={"target": "green", "decoy": "red"},
x_label="Score",
y_label="Density",
)(key="density", state_manager=state_manager)
# Identified proteins per sample, as bars
SeriesPlot(
cache_id="proteins_per_sample",
data=counts, # columns: sample, proteins, kind
x_column="sample",
y_column="proteins",
series_column="kind",
mode="bars",
)(key="per_sample", state_manager=state_manager)
# Abundances per sample, as boxes
SeriesPlot(
cache_id="abundances",
data=abundances, # columns: sample, log2_abundance, step
x_column="sample",
y_column="log2_abundance",
series_column="step",
mode="box",
y_range_mode="normal",
)(key="abundances", state_manager=state_manager)Interactive 3D plot. mode="stems" draws every point as a vertical line from the floor (e.g. x = mass, y = charge, z = intensity); mode="lines" joins the points sharing a trace_column value (e.g. x = m/z, y = retention time, z = intensity). Data is tidy, or holds equal-length list columns with all points of one entity per row, which are spread into points after filtering.
from openms_insight import Plot3D
Plot3D(
cache_id="mass_signals",
data=peaks, # columns: scan, mass_idx, kind, mass, charge, intensity
filters={"spectrum": "scan", "mass": "mass_idx"},
x_column="mass",
y_column="charge",
z_column="intensity",
series_column="kind",
series_colors={"Signal": "#3366CC", "Noise": "#DC3912"},
)(key="signals", state_manager=state_manager)Sequence view of a protein or peptide with its fragment and tag evidence: matched fragment ions (a/b/c/x/y/z), tag coverage, the selected tag, truncations, localized and ambiguous modifications and, with externally annotated fragments, internal fragments. A table below the grid lists the matched fragments. Residues, fragment rows and the masses of the spectrum are linked.
from openms_insight import ProteinSequenceView
ProteinSequenceView(
cache_id="sequence_view",
data=identifications, # one row per sequence entry with its spectrum
filters={"protein": "hit_index"},
mass_column="masses",
mass_identifier="mass",
aa_identifier="aa",
fragment_identifier="fragment", # selected fragment row, shared with other views
)(key="sequence", state_manager=state_manager)The expected columns are listed in ProteinSequenceView.SEQUENCE_COLUMNS and the class docstring. Pass sequence= (a dict with those columns) for one fixed sequence. entry_title and observed_mass_label name the entry in the header.
Every modification the view applies (one set in a residue menu, or one of an edited identification) is localized from the matched fragments: a fragment that matches only with the mass shift places it inside the fragment, one that matches only without it places it outside. When several residues remain, or the shift fits several library modifications at those residues, the view marks the residues with a dashed line and the modification with a ?, and says why in its tooltip and in the list of modifications.
edit_identifier= (or set_edit_identifier() per render) lets the user edit an identification: a pencil button starts from the search result, the residue menus and the "change sequence" dialog then change the sequence and its modifications, and a reset button goes back. Each change is written to that identifier as a dict with action (edit, update or reset) and a fresh nonce; the app keeps the edit and renders the view again with the edited entry (edited=True, fragment masses of the unmodified sequence, its modifications localized on single residues).
fragment_matches_identifier= (or set_fragment_matches_identifier()) publishes the matched fragments (name, ion type, kind, mass, index of the matched mass and, for annotated fragments, charge and m/z) with the tolerance, for a DeconvolvedSpectrum to mark. Give spectrum_key_column= (the spectrum's id column, e.g. scan_idx) so a spectrum showing another scan ignores them.
3D structure of a protein (PDB or mmCIF, drawn with 3Dmol.js), coloured by the fragment evidence of a sequence entry. It takes the same data as ProteinSequenceView, aligns the sequence to the structure's chains, and shares residue and fragment selection with a sequence view. Residues outside the entry's start..end positions are not shown.
from openms_insight import ProteinStructureView
view = ProteinStructureView(
cache_id="structure_view",
data=identifications,
filters={"protein": "hit_index"},
aa_identifier="aa",
fragment_identifier="fragment",
)
view.set_structure(
{
"status": "ok",
"format": "pdb",
"data": pdb_text,
"accession": "P60844",
"label": "AlphaFold DB model",
}
)
view.on_structure_action(handle_upload_or_remove) # optional: upload/remove buttons
view(key="structure", state_manager=state_manager)The structure is given per render with set_structure(), since where it comes from is up to the app. With on_structure_action(handler), the view offers buttons to upload a structure file and to remove an uploaded one. The handler receives {"op": "upload", "accession", "name", "data"} or {"op": "remove", "accession"} and returns True to rerun.
The script button in the view's toolbar saves the colouring as shown (fragment evidence, modifications, hidden termini; not the current selection) as a script for a desktop viewer: a ChimeraX Python script (.py, File > Open) or a PyMOL script (.pml, File > Run Script). Each script carries the structure itself and lists what the colours mean in its header, so the one file is all that is needed.
All components accept these common arguments:
| Argument | Type | Default | Description |
|---|---|---|---|
cache_id |
str |
Required | Unique identifier for disk cache |
data_path |
str |
None |
Path to parquet file (preferred for memory efficiency) |
data |
pl.LazyFrame |
None |
Polars LazyFrame (alternative to data_path) |
filters |
Dict[str, str] |
None |
Map identifier -> column for filtering |
filter_defaults |
Dict[str, Any] |
None |
Default values when selection is None (ALL: every row) |
interactivity |
Dict[str, str] |
None |
Map identifier -> column for click actions |
cache_path |
str |
"." |
Base directory for cache storage |
regenerate_cache |
bool |
False |
Force cache regeneration |
height |
int |
400 |
Component height in pixels (render-time parameter) |
Table, VolcanoPlot, Heatmap and ClusteredHeatmap take
multi_select={identifier: column}. The user then picks several rows or points at
once, and the identifier holds the sorted distinct values of column over them
(None when nothing is picked). Components with the same identifier show and change
the same set, so any page can read it with state_manager.get_selection(identifier).
A multi-selection is a selection level like any other. In filters it keeps the rows
whose column is in the set, so Table(..., filters={"proteins": "accession"}) lists the
picked proteins, and the same works for masses, scans or any other column.
| Component | How the user selects |
|---|---|
Table |
A check mark button in the toolbar shows a check box per row (hidden until then); Shift-click ticks a range; the header box ticks every row passing the filters (on a paginated table, in Python over all pages). Selected rows are marked by a bar on the left whether or not the boxes are shown |
VolcanoPlot |
Box or lasso select in the plot toolbar (Shift adds). With selection_presets=True, buttons above the plot select All changed, Up or Down at the plot's cut-offs; preset_labels={"up": ..., "down": ..., "changed": ..., "clear": ...} renames them |
Heatmap |
Box or lasso select in the plot toolbar (Shift adds); the region is resolved in Python on the full data, not the downsampled level shown; every point of the picked entries is marked |
ClusteredHeatmap |
Box or lasso select over rows (the column must be id_col); selected rows are outlined |
Each plot's toolbar gets a Clear selection button, with the number of selected points on it.
volcano = VolcanoPlot(
...,
label_column="name",
multi_select={"proteins": "accession"},
selection_presets=True,
preset_labels={"up": "Higher in treated", "down": "Lower in treated"},
)
table = Table(..., multi_select={"proteins": "accession"})
picked_only = Table(..., filters={"proteins": "accession"}) # the picked rows
picked = state_manager.get_selection("proteins") # e.g. ["P0A6Y8", "P0A7V0"] or NoneEvery Plotly component draws its tools in a row above the plot, in labelled
groups: View (box zoom, pan, select, zoom in and out, autoscale, reset, pin
zoom, clear selection), Annotate (measure, peak labels, top peak labels),
Show (switches such as the colorbar or the fragment ions) and Download.
A tool that is on is highlighted, and a tool that made something (measurements,
labels, a selection) shows how many, with an × that removes them. The row is
always visible, not only on hover. Its 36 px are taken from the plot, so a
component keeps the height it is given.
When the groups do not fit the panel's width, the row keeps only the tools that are on or hold something, plus Reset, and offers every tool in a menu behind ⋯, sorted into the same groups. The toolbar follows the Streamlit theme.
Some tools open a menu below the toolbar (inside ⋯ on a narrow toolbar):
- Layers shows or hides parts of a plot, one entry per layer with its color;
one layer always stays shown. The layers are what your data defines: the
values of
Heatmap(layer_column=...)or of itscategory_column, the groups ofPCAPlot, the series ofSeriesPlotandPlot3D, and up-, down-regulated and not significant inVolcanoPlot. - Color (
Heatmap) picks what the points are colored by: the intensity or a column ofcolor_columns, and the lowest value shown.
Heatmap and ClusteredHeatmap draw their colorbar small below the plot. A
click opens an editor: one, two or three colors, the position of the middle
color, presets, Reverse and Reset. colorbar_editor=False keeps colorscale.
These choices last while the component is on the page; they are not kept in the state.
In a component of your own. The pieces are not tied to these components. In
js-component/src:
utils/plotTools.ts: aPlotToolwithmenu(sections of kindchoice,togglesorrange) opens that menu instead of running.composables/useLayers.ts:useLayers()keeps which layers are hidden;layers.tool(list)is the Layers button andlayers.visible(key)tells the component what to draw.components/plotly/ColorbarLegend.vuewithutils/colorscale.ts: the colorbar row and its editor for any Plotly colorscale (a name or a stop list); it emits the chosen colors, whichspecToStops()turns into a stop list for Plotly.
Every 2D plot has a Measure button (a ruler) in its plot toolbar: LinePlot,
MirrorPlot, SeriesPlot, DeconvolvedSpectrum, Heatmap, VolcanoPlot and
PCAPlot. It is on by default; measure=False removes it. Pressing it switches
clicks from selecting to measuring: click a point, then a second one. While measuring
the ruler is highlighted and a short note sits over the plot's top-left corner; the
plot keeps its height.
| Component | What a measurement shows |
|---|---|
LinePlot |
A bracket above the two peaks labelled with the x difference: Δm/z 128.059 when the x-axis label is m/z, otherwise Δ<x label>. On an m/z axis the difference is matched to residue masses at 1+ and 2+ (≈ Q/K, ≈ G (2+)) |
MirrorPlot |
As LinePlot on an m/z axis; both peaks must be in the same half |
DeconvolvedSpectrum |
Between masses: Δmass 128.095 ≈ K, matched as a neutral mass (1+ only). Between raw peaks ('annotated', a ladder drill-down): Δm/z, matched at 1+ and 2+ |
SeriesPlot |
A bracket labelled with the x difference only (ΔRT 12.400) |
Heatmap, VolcanoPlot, PCAPlot |
A line between the two points labelled with the x and y differences, from the first point to the second (Δlog2 Fold Change +2.150, Δ-log10(p-value) −1.300), using the axis labels |
Residues are the 20 standard amino acids, monoisotopic, I and L shown as I/L,
closest first. measure_tolerance (default 0.02 Da per point; a difference
matches within twice that, since both points carry the error) and
measure_residues (extra named masses, e.g. {"M(Oxidation)": 147.0354}) tune
the matching on LinePlot, MirrorPlot and DeconvolvedSpectrum.
Several measurements can stay on a plot. Esc cancels a half-finished one,
clicking a label removes that measurement and the Clear measurements button (×)
next to the ruler removes all. They are
plain Plotly shapes and annotations, so the image download includes them. They are
cleared when other data is plotted (a Heatmap keeps them while zooming). With
measure mode off, clicks select as they always did.
The measure options are render-time settings: they are not part of the cache
configuration, so switching the tool on or off never rebuilds a cache.
ClusteredHeatmap (a categorical matrix: there is no distance between two
samples' columns) and Plot3D (a click in 3D does not pick comparable points)
have no measure tool.
LinePlot and MirrorPlot have a Label peaks button (a tag) in their plot
toolbar, next to the ruler. It is on by default; peak_labels=False removes it.
In label mode a click on a peak opens a small text box at the peak: type a label,
Enter keeps it and Esc closes the box. Clicking one of your labels opens it again
to change the text, and an empty text removes it. The Remove peak labels
button next to the tag removes every label of the spectrum shown. Label mode and
measure mode take turns: switching one on switches the other off.
Labels are kept per spectrum while the plot is on the page: plotting another
spectrum shows that spectrum's labels, and going back shows the earlier ones again.
They are plain Plotly annotations with an arrow to their peak, so the image
download includes them. Like the measure options, peak_labels is a render-time
setting and never part of the cache configuration.
A click on a LinePlot peak writes the interactivity columns of that peak to the state. Map an identifier to the x column to hand the m/z to the rest of the page, next to any id the click already selects:
LinePlot(
cache_id="ms2",
data=peaks,
x_column="mz",
y_column="intensity",
interactivity={"peak": "peak_id", "xic_mz": "mz"},
)(state_manager=state)
mz = state.get_selection("xic_mz") # None until a peak is clicked
if mz is not None:
show_xic(mz) # the page's own codeThe peak is the one the hover read-out shows. Columns reach the browser as 32-bit floats, so a float is written as the shortest decimal that is the same 32-bit float (341.3387, not 341.33868408203125); the plot still marks that peak as selected.
Every plot with a toolbar (LinePlot, MirrorPlot, DeconvolvedSpectrum, SeriesPlot, VolcanoPlot, PCAPlot, Plot3D, Heatmap) takes a stepper: one of its filter identifiers. The plot toolbar then shows ‹ frame 12 ›; the arrows set that identifier to the previous or next value of its column, in sorted order, and the tooltip says where the value is (12 of 340). While the filter has no value (and no filter_defaults entry) the plot starts at the first one. A peak map of one ion-mobility frame steps through the frames, a spectrum plot through its spectra:
Heatmap(
cache_id="frames",
data=peaks,
x_column="mz",
y_column="inv_k0",
intensity_column="intensity",
filters={"frame": "frame"},
categorical_filters=["frame"], # optional: resolution levels per frame
stepper="frame",
)(state_manager=state)A Table has no toolbar and refuses a stepper; a table that writes the same identifier through interactivity follows the steps and moves the plot when a row is clicked. The sorted values are read once from the cache; only the current value and its neighbours are sent with each render. Render-time only, not part of the cache.
LinePlot, MirrorPlot, DeconvolvedSpectrum, SeriesPlot, VolcanoPlot, PCAPlot and Heatmap take a zoom_identifier. The plot then reports its axis ranges to the StateManager under that identifier after a zoom or pan, and zooms to a value set there from Python. The value is plain JSON, so a page can store it (in a saved view, say) and set it before the plot is ever drawn:
state = StateManager("viewer")
state.set_selection("zoom@spectrum", {"x": [400.0, 900.0]}) # m/z 400 to 900
state.set_selection("zoom@peak_map", {"x": [10.0, 20.0], "y": [450.0, 800.0]})
LinePlot(cache_id="spectrum", ..., zoom_identifier="zoom@spectrum")(state_manager=state)xandyare[low, high]. A missing axis shows its full extent, andNoneis the full view.- The spectrum plots keep only the x range; their y axis follows the visible peaks.
- Without
zoom_identifier(the default) the zoom stays in the browser, as before. OnlyHeatmapalways reports its zoom (default identifierheatmap_zoom), because the zoom picks the resolution of its data; it reads{"x", "y"}as well as its own{"xRange", "yRange"}. - Each report reruns the script once, debounced to 0.4 s after the last zoom or pan, like any change of the state. Give an identifier only to plots whose zoom should be kept.
- Render-time only: it is not part of the cache.
Every component that offers an image download saves in one format: SVG by default, or PNG, JPEG or WebP. Pick it once for all components, for example from a settings widget on every page run:
import openms_insight
openms_insight.set_image_format(st.session_state.get("image-format", "svg"))
openms_insight.get_image_format() # 'svg', 'png', 'jpeg' or 'webp'A component's image_format argument (default None: follow
set_image_format()) overrides it for that component:
LinePlot(
cache_id="spectrum",
data=peaks,
x_column="mz",
y_column="intensity",
image_format="png",
)| Component | Download button | Notes |
|---|---|---|
LinePlot, MirrorPlot, SeriesPlot, DeconvolvedSpectrum |
plot toolbar | |
Heatmap, VolcanoPlot, PCAPlot, ClusteredHeatmap |
plot toolbar | |
Plot3D |
plot toolbar | WebGL scene: Plotly embeds it as a picture, also in SVG. export_format="png" (older API) still means PNG unless image_format is given |
SequenceView, ProteinSequenceView |
Download button above the sequence | Saved from the page (dom-to-image) |
ProteinStructureView |
Camera button | WebGL scene with no vector form: "svg" saves a PNG |
The toolbar button's tooltip reads "Download as SVG" (or PNG, JPEG, WebP). SVG keeps the
size the plots always had; PNG, JPEG and WebP are drawn at twice the size the
view has on screen. A browser that cannot write WebP from a page (Safari) saves
PNG instead. The file name comes from svg_filename where a component has it
(otherwise its title); the extension follows the format.
Inside a Streamlit session set_image_format() is kept per session, so users
of one app can pick different formats; outside a session it is process wide.
The format is a render-time setting, not part of the cache configuration:
changing it never rebuilds a cache.
When working with large datasets (especially heatmaps with millions of points), use data_path instead of data to enable subprocess preprocessing:
# Subprocess preprocessing (recommended for large datasets)
# Memory is fully released after cache creation
heatmap = Heatmap(
data_path="large_peaks.parquet", # triggers subprocess
cache_id="peaks_heatmap",
...
)
# In-process preprocessing (for smaller datasets or debugging)
# Memory may be retained by allocator after preprocessing
heatmap = Heatmap(
data=pl.scan_parquet("large_peaks.parquet"), # runs in main process
cache_id="peaks_heatmap",
...
)Why this matters: Memory allocators like mimalloc (used by Polars) retain freed memory for performance. For large datasets, this can cause memory usage to stay high even after preprocessing completes. Running preprocessing in a subprocess guarantees all memory is returned to the OS when the subprocess exits.
A cache_id identifies one (data, config) pair. Constructing a component whose cache already exists with the same configuration reuses it and skips preprocessing entirely — which is what makes it safe to build components at the top of a Streamlit script, where the whole script reruns on every interaction:
# Runs preprocessing once. Every rerun after that loads the cache.
table = Table(
cache_id="spectra",
data=pl.scan_parquet("spectra.parquet"),
cache_path="./cache",
index_field="scan_id",
)Changing the data does not invalidate the cache. The configuration is hashed, but the data behind a LazyFrame cannot be without collecting it — which is the expense the cache exists to avoid. Give new data a new cache_id, or force a rebuild:
table = Table(
cache_id="spectra",
data=pl.scan_parquet("todays_spectra.parquet"),
cache_path="./cache",
index_field="scan_id",
regenerate_cache=True, # rebuild even though the config is unchanged
)Render-only settings such as title and colorscale currently take part in the cache key, so changing one rebuilds the cache rather than being ignored. That is wasteful but safe.
When the app's workspaces live on an S3 bucket mounted as a file system (the OpenMS streamlit-template's optional S3 storage), components write their caches to the mounted path and, by default, read them from it too. Setting OPENMS_INSIGHT_S3=1 reads the cached parquet files through the S3 API instead, so polars fetches only the row groups and columns a render needs; it applies when WORKSPACES_S3_ENDPOINT, WORKSPACES_S3_BUCKET, WORKSPACES_S3_ACCESS_KEY and WORKSPACES_S3_SECRET_KEY are all set and the cache lies under WORKSPACES_DIR (the bucket's root). It is off by default because a view reads its cache again on every rerun: through the gateway each read is a few ranged requests, where the mount answers from its local cache, and on the live apps that made selecting a table row about three times slower. The helper is openms_insight.core.storage.scan_parquet.
Components can be reconstructed from cache using only cache_id and cache_path. All configuration is restored from the cached manifest:
# First run: create component with data and config
table = Table(
cache_id="my_table",
data_path="data.parquet",
filters={"spectrum": "scan_id"},
column_definitions=[...],
cache_path="./cache",
)
# Subsequent runs: reconstruct from cache only
table = Table(
cache_id="my_table",
cache_path="./cache",
)
# All config (filters, column_definitions, etc.) restored from cacheAll components are callable. Pass a StateManager to enable cross-component linking:
from openms_insight import StateManager
state_manager = StateManager()
table(state_manager=state_manager, height=300)
plot(state_manager=state_manager, height=400)Components follow the app's Streamlit theme. The light and dark colours are
used as before. The theme's fonts (font, codeFont, headingFont) are
loaded inside the components when the app declares them with
[[theme.fontFaces]]. The primary colour is used for the selected table row,
check boxes and the buttons in the table dialogs.
openms_insight.analysis is the pipeline that feeds VolcanoPlot, PCAPlot and
ClusteredHeatmap: filtering, imputation, normalization, statistical testing and
GO enrichment.
It sits outside the component architecture and is deliberately not re-exported from
the package root, so import the modules directly. Note that analysis.filter
shadows the builtin filter if you import it under its bare name - the example
below aliases it:
import polars as pl
from openms_insight.analysis import filter as feature_filter
from openms_insight.analysis import imputation, normalization, statisticsEvery function takes a wide-format pl.LazyFrame (one row per feature, one
column per sample) plus a sample metadata pl.DataFrame with sample_id and
group columns, and returns a LazyFrame. Nothing is collected until you ask for
it.
data = pl.scan_parquet("quantification.parquet") # ProteinName, S1 .. S6
metadata = pl.DataFrame(
{
"sample_id": ["S1", "S2", "S3", "S4", "S5", "S6"],
"group": ["Control"] * 3 + ["Treatment"] * 3,
}
)
data = feature_filter.filter_low_abundance(data, metadata, threshold_percentile=10.0)
data = feature_filter.filter_low_repeatability(data, metadata, max_missing_ratio=0.5)
data = imputation.impute_mar(data, metadata, strategy="median")
data = normalization.transform_data(data, metadata, "log2")
data = normalization.normalize_samples(data, metadata, "median", id_col="ProteinName")
data = normalization.scale_data(data, metadata, "auto_scaling")
results = statistics.calculate_statistical_tests(data, metadata, method="limma_like")
results = statistics.adjust_fdr_lazy(results, strategy="BH")
report = results.collect() # adds log2FC, stat, p-value, p-adj| Function | Keeps a row when |
|---|---|
filter_low_abundance |
at least one group's median clears that group's threshold_percentile cutoff |
filter_low_repeatability |
at least one group has no more than max_missing_ratio of its samples missing |
filter_low_variance |
at least one group's variance clears that group's threshold_percentile cutoff |
All three apply their cutoff per group and keep the row if any single group passes, so a feature that varies only within one condition is not discarded for having low variance overall. Zeros count as missing. A metadata table with no usable groups leaves the data unchanged rather than filtering everything away.
impute_mar(data, metadata, strategy="median")- missing at random: fill from the feature's own mean or median within the same groupimpute_smallest_value(data, metadata, scope="row")- missing not at random: fill with the smallest observed value, per feature ("row") or across the whole matrix ("global"), on the assumption that missing MS values fall below the detection limit
Both treat explicit nulls and zeros as missing.
| Function | Operates on | Strategies |
|---|---|---|
transform_data |
each value | "log2", "log10" (both add 1 first, so zeros do not become -inf), "square_root", "cube_root" |
normalize_samples |
whole samples (columns) | "sum", "median", "pqn", "reference_feature", "quantile" |
scale_data |
each feature (row) | "mean_centering", "auto_scaling" (Z-score), "pareto_scaling", "range_scaling" |
All three accept "None" and return the input unchanged, which makes them easy to
wire straight to a Streamlit selectbox. "reference_feature" additionally needs
reference_feature= naming a row in id_col.
calculate_statistical_tests(data, metadata, method=...) adds log2FC, stat and
p-value:
| Method | Test | Groups |
|---|---|---|
"limma_like" (default) |
Empirical Bayes variance-moderated t-test / F-test | 2 / 3+ |
"welch" |
Welch's t-test (unequal variances) | exactly 2 |
"paired" |
Paired t-test | exactly 2, equal size |
"anova" |
One-way ANOVA F-test | 3+ |
limma_like shrinks each feature's variance towards a common prior, which is what
makes small-n experiments usable. Everything is expressed as lazy Polars operations
and only drops into SciPy for the final p-value.
adjust_fdr_lazy(results, strategy=...) then adds p-adj, using "BH"
(Benjamini-Hochberg, the default), "Bonferroni", or "None" to copy p-value
through unchanged.
The result feeds VolcanoPlot directly:
VolcanoPlot(
cache_id="de_volcano",
data=results,
log2fc_column="log2FC",
pvalue_column="p-adj",
label_column="ProteinName",
)(state_manager=state_manager, fc_threshold=1.0, p_threshold=0.05)calculate_go_enrichment annotates UniProt accessions via
MyGene.info and runs Fisher's exact test per GO term, for
each of the BP, CC and MF categories.
It is the odd one out in this module: it makes a live network call, takes an
eager pl.DataFrame, and returns a (status, payload) tuple instead of raising,
so callers can tell "not enough significant proteins" apart from a hard failure.
from openms_insight.analysis.enrichment import calculate_go_enrichment
status, payload = calculate_go_enrichment(
report, # eager DataFrame with an ID column, log2FC, and a p-value column
id_col="ProteinName",
target_p_col="p-adj",
p_cutoff=0.05,
fc_cutoff=1.0,
)
if status == "success":
for category, result in payload["categories"].items():
st.plotly_chart(result["fig"]) # "BP" | "CC" | "MF"status is "success", "insufficient_proteins" (fewer than 3 proteins pass the
cutoffs) or "empty_data".
For a set the user picked (see multi_select), go_enrichment takes the
foreground and background directly, and the annotations from
fetch_go_annotations, so an app can cache them per protein:
from openms_insight.analysis.enrichment import fetch_go_annotations, go_enrichment
annotations = fetch_go_annotations(background) # query, BP_terms, CC_terms, MF_terms
result = go_enrichment(annotations, foreground=picked, background=background)
result["categories"]["BP"] # GO_Term, Count, Background, GeneRatio, BgRatio,
# FoldEnrichment, p_value, -log10(p), p_adj, ProteinsWhen the user tests many selections of the same proteins (a lasso on a plot, check boxes in a table), build the term index once and test each selection from it. The index is a Polars frame (accession, category, term) that an app can store, for example as parquet next to its results, so a selection only counts its proteins and runs the tests:
from openms_insight.analysis.enrichment import go_enrichment_from_index, go_term_index
index = go_term_index(annotations, background) # once, e.g. after the workflow
result = go_enrichment_from_index(index, foreground=picked, background=background)go_enrichment returns the same result; it builds the index itself.
These functions need the analysis extra:
pip install "openms-insight[analysis]"For a comprehensive guide to the internal architecture, conventions, and pitfalls, see CONTRIBUTING.md.
cd js-component
npm install
npm run build# Terminal 1: Vue dev server
cd js-component
npm run dev
# Terminal 2: Streamlit with dev mode
SVC_DEV_MODE=true SVC_DEV_URL=http://localhost:5173 streamlit run app.pyEnable hash tracking logs to debug data synchronization issues:
SVC_DEBUG_HASH=true streamlit run app.py# Python tests
pip install -e ".[dev]"
pytest tests/ -v
# TypeScript type checking
cd js-component
npm run type-check# Python
ruff check .
ruff format .
# JavaScript/TypeScript
cd js-component
npm run lint
npm run format