Ionic
A streamable binary file format for mass-spectrometry profiling and imaging data, and the Rust library and CLI that read and write it.
Ionic converts losslessly to and from mzML, depends on nothing but standard byte operations, and compiles to WebAssembly, so the same reader runs in a server, a notebook or a browser tab.
Install
Why
Metabolic phenotyping has reached a scale at which the volume of data, not the sophistication of the model, limits what can be learned from it. Population-scale mass-spectrometry cohorts are the substrate for machine learning, which must iterate over the entire corpus, so the size and speed at which data can be read set the ceiling on what is feasible. At the same time, untargeted studies nominate thousands of features whose underlying peaks are almost never inspected, because with conventional formats that means retrieving gigabytes and loading a heavyweight tool per feature.
The community exchange format for mass-spectrometry data (mzML), used in proteomics, metabolic profiling and imaging, is text-based and thus too large for long-term storage, and has to be read in full before any spectrum can be reached. More compact binary alternatives such as mzMLb solve the size problem but are built on general-purpose storage libraries such as HDF5, which tie a file to a particular software stack and cannot reasonably be compiled to a lightweight target such as WebAssembly.
Ionic stores the same information as native numeric types in independently compressed Zstandard blocks, addressed through small fixed-width directories. A reader searches an index, finds where a spectrum lives, requests that byte range, and leaves the rest of the file untouched and compressed. Over HTTP, that is a range request; on disk, it is a seek.
CLI →
A command-line tool for converting mzML files to Ionic. See the CLI for installation and commands.
Usage
Convert
ionic::convert takes a path or a byte buffer. With output set it writes the file and returns None. With output empty it returns the result as Some(bytes). kind defaults to ConvertKind::Auto, which reads the direction from the .mzML or .ion extension, and from the file signature for a buffer or a file without one of those extensions.
use ;
convert?;
convert?;
let ion_bytes = convert?.unwrap;
let mzml_bytes = convert?.unwrap;
convert?;
Read an .ion file
use ;
let mut reader = open_file?;
let mz = reader.get_spectrum_array?;
let intensity = reader.get_spectrum_array?;
Reading options — ReadOptions
Write an .ion file
Memory
use ;
let mzml = from_spectra;
let mut source = new;
let mut out: = Vecnew;
let mut writer = create?;
writer.write_stream?;
File path
use ;
let mzml = from_spectra;
let mut source = new;
let mut output = open_path?; // or FileWriter::open("out.ion")
let mut writer = create?;
writer.write_stream?;
output.flush?;
WriteOptions
How the format works
A fixed 1024-byte header stores the byte offset of every section. A reader uses these offsets to go directly to the index, then decompresses only the blocks a query needs. spec/README.MD specifies the design; spec/v1.md gives the exact byte layout.
Portability
The library depends only on standard byte operations: no HDF5, no storage engine, nothing
to install alongside a file. Compression uses the pure-Rust cosmoz
on every target, so native and wasm32-unknown-unknown share the same zstd code. The wasm build
drops rayon and memmap2, and browser conversions use compression level 1. That is what
ion-beam runs on.
Related projects
- ion-beam: a browser viewer for
.ionfiles that downloads only the bytes it needs, with an inspector showing exactly which regions of the file were fetched. Try it live. - Quant·ion: the Rust processing toolkit (peak picking, baselines, noise, untargeted feature detection) with Python, R and JavaScript wrappers.
- ion-files: a small public collection of
demo
.ionfiles.
Citing
If you use Ionic, Quant·ion or ion-beam, please cite:
Reading only what you need: a dependency-free, streamable format and cross-language toolkit for scalable LC-MS feature detection. Preprint, 2026. DOI: 10.XXXXX/XXXXXX