Matlab data structure design

MATLAB Data Structure Design for Mass Spectrometry Imaging

Summary

Design and organize MATLAB data structures to aggregate batch-processed CDF imaging files into a unified workspace format compatible with downstream mass spectrometry analysis pipelines. This skill ensures that spectral intensities, m/z values, and spatial metadata are coherently structured for linear imaging workflows.

When to use

You have multiple CDF files containing mass spectrometry imaging data (spectra, m/z arrays, and spatial coordinates) that need to be ingested into MATLAB for the DIMPLE pipeline or similar linear-axis mass spectrometry imaging analysis. Apply this skill when raw CDF files must be transformed into a single, consistently-formatted workspace that preserves spectral intensities, m/z calibration, and spatial position metadata.

When NOT to use

• CDF files have already been converted to a different format (e.g., HDF5, MAT) by another preprocessing step — use the converted format directly instead.
• Spectral data is already loaded into MATLAB as a pre-assembled array or table — design your structure based on existing format rather than re-ingesting from CDF.
• You are performing real-time streaming analysis where data cannot be held in memory as a unified structure — use file-based or incremental processing instead.

Inputs

• CDF files (NetCDF format) containing spectral intensity arrays, m/z values, and spatial coordinates
• File paths or cell array of CDF file names
• Spatial metadata (linear position, x, y coordinates, or sample identifiers)

Outputs

• MATLAB workspace struct or cell array with fields: spectra (intensity arrays), mz (m/z calibration vectors), and spatial_metadata (coordinates or positions)
• .mat file (e.g., B73-root11-workspace.mat) containing the aggregated structure for downstream pipeline use

How to apply

After reading individual CDF files using MATLAB's netCDF I/O functions, extract spectral intensity arrays, m/z values, and spatial coordinates (x, y, or linear position) from each file. Organize these extracted fields into a structured array or cell array with consistent field names and data types across all samples. Aggregate the individual structures into a single workspace object (e.g., a struct array or table) that maintains the correspondence between spectra, m/z calibration, and spatial metadata. Validate that all samples have matching m/z array lengths and that spatial coordinates are numeric and non-negative. Save the aggregated workspace as a .mat file compatible with downstream DIMPLE pipeline functions.

Related tools

• MATLAB netCDF/CDF I/O functions (Read raw spectral data, m/z arrays, and metadata from CDF files into MATLAB workspace)
• batchcdfread (Batch process multiple CDF files and iterate through each to extract and aggregate spectral data) — github.com/dickinsonlab/DIMPLE-code
• DIMPLE pipeline (Downstream consumer of the aggregated workspace structure for mass spectrometry imaging analysis along a linear axis) — github.com/dickinsonlab/DIMPLE-code

Evaluation signals

• All CDF files in the batch are successfully read and no files are skipped or cause read errors.
• The output structure has consistent field names and data types across all samples (e.g., all spectra are numeric arrays, all mz vectors are equal-length, all spatial coordinates are numeric).
• m/z array lengths match across all samples in the structure; spectral intensity array dimensions are consistent within each sample.
• Spatial metadata (position, x/y coordinates) are present, numeric, non-negative, and correspond one-to-one with each spectrum.
• The aggregated .mat file can be loaded and used by downstream DIMPLE pipeline functions without format or dimension mismatches.

Limitations

• The skill assumes all CDF files conform to a consistent schema (same m/z range, sampling resolution, and metadata fields); heterogeneous CDF formats may require per-file preprocessing.
• Memory constraints may limit batch size for very large imaging datasets; incremental processing or file-based aggregation may be necessary for datasets exceeding available RAM.
• Spatial coordinate metadata must be explicitly present in the CDF files or provided separately; if missing or inconsistent, manual alignment or augmentation is required before structure design.
• No validation is performed on m/z calibration accuracy or spectral quality; downstream pipeline is responsible for flagging or filtering poor-quality spectra.

Evidence

• [other] Extract spectral intensity arrays, m/z values, and spatial coordinates (x, y, or linear position) from each CDF file.: "Extract spectral intensity arrays, m/z values, and spatial coordinates (x, y, or linear position) from each CDF file."
• [other] Organize extracted data into a structured array or cell array with fields for spectra, m/z values, and spatial metadata.: "Organize extracted data into a structured array or cell array with fields for spectra, m/z values, and spatial metadata."
• [other] Return the aggregated workspace structure containing all batch spectra in a format compatible with downstream DIMPLE pipeline analysis.: "Return the aggregated workspace structure containing all batch spectra in a format compatible with downstream DIMPLE pipeline analysis."
• [readme] cdf files and available Matlab workspaces are provided for the roots that were analyzed in Sama et al. 2025.: "cdf files and available Matlab workspaces are provided for the roots that were analyzed in Sama et al. 2025."
• [readme] batchcdfread function developed by Yifan Meng in Dr. Richard N. Zare's lab at Stanford University: "batchcdfread function developed by Yifan Meng in Dr. Richard N. Zare's lab at Stanford University"