📦 emdoc

emdoc — A fast, high-performance serialEM MDOC parser and writer for cryo-EM ⚡

• serialem + mdoc = emdoc
• for rust & python users

✨ Features

📥 Installation

Cargo.toml

[dependencies]
mdoc = { version = "0.1.0", features = ["serde"] }

# Optional features
# mdoc = { version = "0.1.0", features = ["serde", "python", "polars"] }

Python

# Coming soon! For now, build with maturin
maturin develop --features python

🚀 Quick Start

1️⃣ Parse a File

use emdoc::Mdoc;

// Load entire MDOC into memory
let mdoc = Mdoc::from_file("data.mdoc")?;
println!("📊 Found {} tilt images", mdoc.tilt_series().len());

// Access header
for entry in mdoc.header() {
    println!("🏷️  {:?}", entry);
}

2️⃣ Read Typed Fields

let z0 = mdoc.tilt_image(0).unwrap();
println!("🔬 Tilt Angle: {:?}", z0.tilt_angle());
println!("🎯 Defocus: {:?}", z0.defocus());
println!("📐 Magnification: {:?}", z0.magnification());

// Type-safe access with error handling
let angle: f32 = z0.get_checked("TiltAngle")?;

3️⃣ Modify & Save

let mut mdoc = Mdoc::from_file("input.mdoc")?;

// Update a field
mdoc.update_field(0, "Defocus", "-3.5");

// Add new tilt image
let new_image = mdoc.add_tilt_image(42);
new_image.set("TiltAngle", "45.0");
new_image.set("Magnification", "50000");

// Lossless write (preserves original formatting)
mdoc.write_lossless(std::fs::File::create("output.mdoc")?)?;

📚 API Reference

🏗️ Core Types

🔧 Mdoc Methods

📂 Constructors

✏️ Writers

🔍 Accessors

🛠️ Mutators

✅ Validation & Normalization

🔌 Serialization

📊 Data Science

🔍 ZBlock Methods

📖 Readers

Convenience Fields

✏️ Writers

🔄 Round-trip

🌊 Streaming APIs

Visitor Pattern

pub trait MdocVisitor {
    fn header(&mut self, entry: &str);      // 🏷️ Header line
    fn begin_tilt(&mut self, z: usize);     // 🎬 Start Z block
    fn field(&mut self, key: &str, value: &str); // 📄 Field
    fn end_tilt(&mut self);                 // 🏁 End Z block
}

pub fn parse_stream<R: BufRead>(
    reader: R,
    visitor: &mut dyn MdocVisitor,
) -> Result<(), ParseError>

Transform API

pub fn transform<R: BufRead, W: Write>(
    reader: R,
    writer: W,
    f: impl FnMut(&mut FieldEdit),
) -> Result<(), ParseError>

// FieldEdit has: key, value, new_value (set via .set())

🎯 Performance Tips

🔬 Cryo-EM Specific Examples

📊 Plot Defocus vs Tilt Angle (Python)

import emdoc
import matplotlib.pyplot as plt

# Load MDOC
mdoc_data = emdoc.Mdoc.from_file("tilt_series.mdoc")
tilt_angles, defocus_values = mdoc_data.to_numpy_arrays()

# 📈 Quick plot
plt.figure(figsize=(10, 6))
plt.scatter(tilt_angles, defocus_values, alpha=0.7, s=50)
plt.xlabel("Tilt Angle (°)")
plt.ylabel("Defocus (μm)")
plt.title("Defocus vs Tilt Angle")
plt.grid(True, alpha=0.3)
plt.show()

🔄 Streaming Filter (Rust)

use std::fs::File;
use emdoc::{parse_stream, MdocVisitor};

struct TiltAngleFilter {
    min_angle: f32,
    max_angle: f32,
}

impl MdocVisitor for TiltAngleFilter {
    fn begin_tilt(&mut self, z: usize) {
        println!("🎬 Processing Z = {}", z);
    }
    
    fn field(&mut self, key: &str, value: &str) {
        if key == "TiltAngle" {
            let angle: f32 = value.parse().unwrap();
            if angle < self.min_angle || angle > self.max_angle {
                println!("⚠️  Tilt angle {} out of range!", angle);
            }
        }
    }
}

🧪 Testing

# Run tests
cargo test

# Test Python integration
cargo test --features python

# Benchmark parsing
cargo bench --features bench

📜 License

MIT License - see LICENSE file for details.

🤝 Contributing

We love contributions! Please submit a pull request or open an issue on GitHub.