# Image Visualization Formatting

> Use when you have loaded a normalized or raw pixel array (NumPy format) with associated metadata from MSI line-scan data, and need to generate publication-quality ion images with controlled intensity scaling, smoothing, and optional ratio or fractional abundance comparisons across multiple m/z.

- Skill: `holobiomicslab/image-visualization-formatting` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/image-visualization-formatting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/image-visualization-formatting/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/image-visualization-formatting

---


# image-visualization-formatting

## Summary

Apply normalization, scaling, and interpolation transformations to mass spectrometry imaging pixel arrays to produce publication-ready ion images and comparative visualizations (ratio, fractional abundance). This skill bridges processed pixel data to interpretable visual formats suitable for scientific communication.

## When to use

You have loaded a normalized or raw pixel array (NumPy format) with associated metadata from MSI line-scan data, and need to generate publication-quality ion images with controlled intensity scaling, smoothing, and optional ratio or fractional abundance comparisons across multiple m/z layers.

## When NOT to use

- Input pixel array is not in NumPy format or lacks associated metadata JSON—preprocessing to array form is required first.
- Data are already formatted as publication figures or raster images; this skill is for converting numerical arrays to images, not post-processing graphics.
- No clear reference or internal standard compound is available for internal standard normalization and TIC alone does not adequately correct for spatial variations in ionization efficiency.

## Inputs

- NumPy array (pixel array in float64 or uint format)
- JSON metadata file (associated with pixel array, containing m/z list, acquisition parameters)
- Mass list (integer list of m/z indices to visualize)
- Internal standard parameters (optional: std_idx, std_precursor m/z, std_fragment m/z, std_mobility, std_charge)

## Outputs

- Publication-style ion images (PNG, PDF, or matplotlib figure objects)
- Raw pixel intensity arrays (NumPy .npy or CSV format)
- Ratio images (element-wise division of two m/z layers with NaN/inf handling)
- Fractional abundance images (normalized by sum across all m/z layers per pixel)

## How to apply

Load the pixel array and metadata JSON using MSIGen's load_pixels function, then invoke get_and_display_images with your chosen normalization mode (TIC, internal standard, or none), intensity scaling via quantile-based scaling (e.g., scale=0.999 caps intensity at the 99.9th percentile) or manual threshold, and interpolation option (linear or none) to control smoothing. For comparative visualizations, call fractional_abundance_images or ratio_images with the target m/z indices and handle_infinity parameter set appropriately to manage divide-by-zero errors. Specify image_savetype to write outputs as publication-style figures (PNG/PDF), raw arrays (NumPy .npy), or CSV tables. The normalization step is critical: TIC normalization accounts for pixel-to-pixel variation in total signal, while internal standard normalization corrects for ionization efficiency by dividing each pixel's signal by a known reference compound identified by mass, mobility, charge, or list index.

## Related tools

- **MSIGen** (Core package providing get_and_display_images, fractional_abundance_images, ratio_images functions and load_pixels for reading serialized pixel arrays and metadata.) — https://github.com/LabLaskin/MSIGen
- **Jupyter Notebook** (Interactive development environment for executing visualization workflows step-by-step and iterating on normalization and scaling parameters.)
- **Python** (Runtime language for MSIGen; requires version >=3.9 and <=3.11 to ensure compatibility with dependencies.)

## Examples

```
pixels, metadata = msigen.load_pixels('path/to/saved_pixels.npy'); vis.get_and_display_images(pixels, metadata, normalize='TIC', scale=0.999, interpolation='linear', image_savetype='png')
```

## Evaluation signals

- Output images show spatially coherent ion signal distribution without salt-and-pepper noise or clipping artifacts.
- Intensity histograms or quantile metrics confirm that scaling has been applied correctly (e.g., max pixel intensity is at or below the specified quantile threshold).
- Ratio images do not contain unexpected infinity or NaN regions, or such regions are handled according to handle_infinity parameter.
- Metadata embedded in saved figures (e.g., PNG exif or figure title) or accompanying CSV files match the m/z values, normalization mode, and acquisition metadata.
- Visual comparison across multiple normalization modes (TIC vs. internal standard) shows expected differences in relative intensity patterns (internal standard correction should suppress spatially uniform background).

## Limitations

- Quantile-based intensity scaling is data-dependent; the same quantile value may produce over- or under-scaled images across datasets with different noise profiles or dynamic ranges.
- Internal standard normalization requires accurate identification of the standard compound; errors in mass tolerance (mass_tolerance_MS1, mass_tolerance_prec, mass_tolerance_frag) or mobility tolerance can lead to incorrect standard assignment and flawed normalization.
- Interpolation smoothing (linear mode) can blur sharp chemical boundaries or inflate apparent spatial resolution; 'none' option may preserve artifacts.
- MSIGen is designed specifically for nano-DESI MSI data; applicability to other MSI modalities (MALDI, DESI) or non-line-scan acquisition geometries is not documented.

## Evidence

- [other] MSIGen supports image normalization to total ion current (TIC) via normalize='TIC' parameter and to an internal standard via normalize='intl_std' parameter when processing pixel arrays.: "MSIGen supports image normalization to total ion current (TIC) via normalize='TIC' parameter and to an internal standard via normalize='intl_std' parameter when processing pixel arrays."
- [other] Call MSIGen's get_and_display_images function with the chosen normalization parameters (normalize, std_idx, std_precursor, std_mass, std_fragment, std_mobility, std_charge) to apply normalization across all image layers. Optionally apply pixel intensity scaling via scale parameter (quantile-based; e.g., 0.999 sets max to 99.9th percentile) or manual threshold.: "call MSIGen's get_and_display_images function with the chosen normalization parameters (normalize, std_idx, std_precursor, std_mass, std_fragment, std_mobility, std_charge) to apply normalization"
- [other] Save the normalized image output as publication-style figures, raw images, or CSV arrays according to the image_savetype parameter.: "Save the normalized image output as publication-style figures, raw images, or CSV arrays according to the image_savetype parameter."
- [methods] Load previously saved NumPy array and metadata files and Visualize and display ion images with normalization options.: "Load previously saved NumPy array and metadata files; pixels, metadata = msigen.load_pixels(load_path). Visualize and display ion images with normalization options via"
- [methods] Generate fractional abundance images and Generate ratio images with optional handle_infinity parameter to replace infinity values from divide by zero errors.: "Generate fractional abundance images via vis.fractional_abundance_images(pixels, metadata, ...) and ratio images via vis.ratio_images(pixels, metadata, ...); handle_infinity parameter to replace"
- [readme] MSIGen is designed for converting mass spectrometry imaging (MSI) data from the raw line-scan data to a visualizable format and is designed with nano-DESI MSI in mind.: "MSIGen is designed for converting mass spectrometry imaging (MSI) data from the raw line-scan data to a visualizable format and is designed with nano-DESI MSI in mind."