alnfile

A Python package for reading AreTomo alignment files into pandas DataFrames, with utilities for converting to IMOD transformation matrices.

Installation

pip install alnfile

Quick start

Basic usage

The main function is alnfile.read() which accepts a file path and an optional alignment type:

import alnfile

# Read either global or local alignments (default global)
global_df = alnfile.read("path/to/your/file.aln")
print(global_df.head())
# Columns: sec, rot, gmag, tx, ty, smean, sfit, scale, base, tilt

# Local alignments   
local_df = alnfile.read("file.aln", alignment_type="local")
print(local_df.head())
# Columns: sec_idx, patch_idx, center_x, center_y, shift_x, shift_y, is_reliable

IMOD Transformation Matrices

Convert alignment data to IMOD-compatible transformation matrices:

import alnfile

# Read alignment data
df = alnfile.read("path/to/your/file.aln")

# Convert DataFrame to transformation matrices (IMOD .xf format)
xf_matrices = alnfile.df_to_xf(df)  # Returns (n_tilts, 2, 3) array
# Each matrix is [[A11, A12, DX], [A21, A22, DY]]

# Use yx convention (swap rows) if needed for specific applications
xf_matrices_yx = alnfile.df_to_xf(df, yx=True)  # Returns (n_tilts, 2, 3) array
# Each matrix is [[A22, A21, DY], [A12, A11, DX]]

Data Structure

Global Alignment DataFrame

Local Alignment DataFrame

Rows will have None values for columns not applicable to their type.

Attribution

This implementation has been adapted from a similar reader in cryoet-alignment repository by Utz H. Ermel (@uermel).