msdial-eic-reader

Unofficial reader for MS-DIAL aligned EIC archives (AlignResult*.EIC.aef).

The goal is simple: inspect the chromatogram traces and integration boundaries that MS-DIAL already used, without recomputing EICs from raw files in a downstream QC dashboard.

This project is not affiliated with MS-DIAL, RIKEN, or the MS-DIAL maintainers. The .EIC.aef format appears to be an internal binary format and may change in future MS-DIAL releases.

Why this exists

MS-DIAL can show aligned chromatograms in the GUI, but downstream tools often only receive alignment tables and summary values. For QC, it is useful to see the per-sample traces behind an aligned feature:

• did every replicate integrate the expected peak;
• did one sample pick a smaller neighboring peak;
• are the left, apex, and right markers plausible;
• can an operator review a batch without reopening the full MS-DIAL GUI.

Recomputing EICs outside MS-DIAL is not ideal for this use case, because the external viewer may show traces or peak boundaries that differ from what MS-DIAL actually integrated.

What it reads

The reader targets MS-DIAL 5 CSS1 EIC archives named like:

AlignResult*.EIC.aef

For each aligned feature and sample trace, the JSON output includes:

• center values: RT, RI, m/z, drift, and chromatogram x-axis type;
• sample/file ID;
• peak markers: left, top, and right;
• EIC points as { "x": ..., "intensity": ... };
• original and returned point counts.

Feature indices are zero-based archive indices. In observed outputs they match the row order of the paired MS-DIAL alignment table after its header, but treat that as a practical convention rather than an official guarantee.

Install from source

git clone https://github.com/Fraximov/msdial-eic-reader.git
cd msdial-eic-reader
python -m pip install .

Python usage

from msdial_eic_reader import MsdialEicArchive

archive = MsdialEicArchive("AlignResult-test.EIC.aef")

print(archive.summary())

feature = archive.read_feature(42, max_points_per_trace=900)
for peak in feature["peaks"]:
    print(peak["file_id"], peak["left"], peak["top"], peak["right"])

Command line usage

Print archive metadata:

msdial-eic-reader summary AlignResult-test.EIC.aef

Read one aligned feature:

msdial-eic-reader feature AlignResult-test.EIC.aef 42 --max-points 900

Read a small window of features:

msdial-eic-reader window AlignResult-test.EIC.aef 40 5 --max-points 900

Set --max-points 0 to return all points. The default downsamples long traces to keep browser dashboards responsive.

Rust CLI

A dependency-free Rust CLI is included in rust/ for batch or dashboard use:

cd rust
cargo run -- --file ../AlignResult-test.EIC.aef --index 42 --max-points 900

It also supports window reads, which are useful when a UI slider moves through nearby features:

cargo run -- --file ../AlignResult-test.EIC.aef --start 40 --count 11 --max-points 900

Format notes

The inferred binary layout is documented in docs/css1-eic-aef-format.md.

Short version:

10 bytes  version string, null-padded ASCII, observed: CSS1
int32     feature count
int64[]   absolute offsets to aligned feature payloads

feature payload:
float32   center RT
float32   center RI
float32   center m/z
float32   center drift
uint8     chromatogram x-axis type
int32     sample trace count

sample trace:
int32     file ID
int32     point count
float32   top/apex x position
float32   left boundary x position
float32   right boundary x position
float32[] repeated x, intensity pairs

All numeric values are little-endian in observed files.

Limitations

• This is an unofficial reader for an internal MS-DIAL file.
• It has been tested only against observed MS-DIAL 5 CSS1 archives.
• It does not parse the paired alignment table; use the table to map feature indices to metabolite names, average RT, average m/z, annotations, and sample names.
• It is intended for QC visualization and traceability, not for replacing MS-DIAL's integration.

Contributing

Real-world fixtures are the most useful contribution, but please do not commit large raw data. Small synthetic .EIC.aef examples, version information, and edge cases are ideal.

If the MS-DIAL project later exposes an official export or API for this data, this reader should either adapt to that API or clearly point users to it.