HS-MOSAIC Documentation

Welcome to the documentation for HS-MOSAIC (HyperSpectral Multivariate Optical Analysis Components), a desktop GUI for fast unmixing and reconstruction of hyperspectral and multispectral imaging data. This documentation is designed to guide users through the installation, usage, and troubleshooting of the software, as well as provide detailed tutorials and reference materials.

GUI Overview

Quick Demo of the main workflow: Demo

💡 New here? Read Essentials first. Six features that are easy to miss when clicking around but change how productive HS-MOSAIC is once you know them — ROI placement options, residual-data analysis, the composite mirror, Gaussian seeds, seed pixels with two ranking metrics, and the .preset for cross-FOV reproducibility.

Start Here

Tutorials

The tutorials explain the app from the basic workflow upward. They are intentionally modality-independent first; dataset-specific examples are listed separately below.

GUI basics

Here you learn everything about the GUI and particularly the pyqtgraph plotting library, which is used for all interactive plots in the app. This is important to understand how to interact with the plots and how to interpret the visualizations.

01 Data loading

Here you learn how to load different data formats to the GUI. An important prerequisite is the tiff file format. The app can load both 3D TIFFs (x/y/spectral) and 4D TIFFs (x/y/z/spectral or x/y/time/spectral). The app also supports loading tile folders containing multiple TIFFs that together form a larger image.

02 Analysis

To understand the concepts of multivariate analysis, it is essential to understand the different analysis modes and how they work. This section explains the different modes and how to use them. The overview can help in particular to find better seed spectra for the NNMF and NNLS modes (see Seeds, spectra, and W maps), which can be crucial for getting good results.

The GPU acceleration page outlines how the optional GPU acceleration paths are set up. It is not essential to understand this for using the app, but it can be helpful for troubleshooting and for understanding the performance of the app.

03 Seeds

Seeds are how you steer NNMF and fixed-H NNLS toward physically meaningful results. They can come from ROIs drawn on the image, reference spectra loaded from files, Gaussian resonance models, or the automatic suggester — the pages below cover each source and how they combine into the H and W matrices the solver receives.

Remaining workflow

The rest of the tutorial is dedicated to handling results, exporting data, and ensuring reproducibility. This is important for getting the most out of the app and for sharing results with others.

Examples

The example section is for complete data-specific workflows. The synthetic quickstart is the canonical end-to-end check for a fresh install.

Methods

  • NNMF and NNLS modes — algorithms, math, convergence criteria, and literature references behind the analysis modes.

Reference