BB-pBB Geometry

Geometric analysis of basal body (BB) and pro-basal body (pBB) orientation relative to the outer mitochondrial membrane (OMM) for electron tomography data.

Features

• Multiple input formats: IMOD model files (.mod), imod2point text files (.txt), and Excel tables (.xlsx)
• Automatic normal vector correction: Handles arbitrary point order with biological constraint checking
• Batch processing: Analyze multiple tomograms efficiently
• Flexible output: Text, JSON, or CSV formats
• Warning system: Flags unusual geometries for review

Installation

pip install -e .

For development:

pip install -e ".[dev]"

Quick Start

Analyze a single point file

bb-pbb-geometry analyze tomogram_001.txt

Analyze an IMOD model file

bb-pbb-geometry analyze tomogram_001.mod

Batch process multiple point files

bb-pbb-geometry batch-points tomo_*.txt -o results.csv

Batch process Excel table

bb-pbb-geometry batch tomograms.xlsx -o results.csv

Convert Excel back to IMOD for visualization

bb-pbb-geometry excel-to-imod tomograms.xlsx output_models/

Input Formats

1. imod2point Text Format

Plain text file with 7 lines, each containing space-separated x, y, z coordinates:

10.5 20.3 15.0
10.5 20.3 25.0
20.0 30.5 15.5
20.0 30.5 26.0
5.0 15.0 20.0
35.0 15.0 20.0
5.0 45.0 20.5

Point order:

• Lines 1-2: BB axis (start and end)
• Lines 3-4: pBB axis (start and end)
• Lines 5-7: OMM plane points

2. IMOD Model Format

Standard IMOD .mod file with 7 manually placed points in the same order as above.

3. Excel Table Format

Excel file with one row per tomogram and the following columns:

tomogram_id	p1_x	p1_y	p1_z	p2_x	p2_y	p2_z	...	p7_z
tomo_001	10.0	20.0	15.0	10.0	20.0	25.0	...	20.5
tomo_002	15.0	25.0	20.0	15.0	25.0	30.0	...	25.5

Output Format

Text Output (default)

Orientation Analysis Results
============================================================
File: tomogram_001.txt

Angles (degrees):
  BB to OMM plane:        85.23°
  pBB to OMM plane:       78.45°
  BB to pBB axes:         12.34°

Vectors:
  BB vector:    [0.00, 0.00, 10.00]
  pBB vector:   [0.00, 0.00, 15.50]
  OMM normal:   [0.00, 0.00, 1.00]

JSON Output

{
  "identifier": "tomogram_001.txt",
  "bb_to_omm_angle_deg": 85.23,
  "pbb_to_omm_angle_deg": 78.45,
  "bb_pbb_angle_deg": 12.34
}

CSV Output (batch mode)

identifier,bb_to_omm_angle,pbb_to_omm_angle,bb_pbb_angle,warning
tomo_001,85.23,78.45,12.34,
tomo_002,82.10,75.30,15.67,
tomo_003,-45.20,72.10,,"Unusual orientation: BB angle is negative..."

Geometric Calculations

The package implements the following calculations:

Vectors:

• BB axis: v_BB = P₂ − P₁
• pBB axis: v_pBB = P₄ − P₃
• OMM plane normal: n = (P₆ − P₅) × (P₇ − P₅)

Angles:

• BB to OMM plane: θ_BB = 90° − arccos(v_BB · n / (|v_BB| · |n|))
• pBB to OMM plane: θ_pBB = 90° − arccos(v_pBB · n / (|v_pBB| · |n|))
• BB to pBB axes: α = arccos(v_BB · v_pBB / (|v_BB| · |v_pBB|))

Angle ranges:

• BB/pBB to OMM: [-90°, +90°] (typically positive)
• BB to pBB: [0°, 180°]

Normal Vector Orientation

The 3 OMM plane points (P5, P6, P7) may be placed in arbitrary order, causing the normal vector to point in a random direction. The package automatically corrects this:

• If both BB and pBB angles are negative: Normal is flipped
• If exactly one angle is negative: Warning is issued (unusual geometry)

This ensures biologically meaningful results regardless of point placement order.

CLI Commands

analyze - Single file analysis

bb-pbb-geometry analyze INPUT_FILE [OPTIONS]

Options:
  -f, --format [auto|point|mod|excel]  Input format (default: auto-detect)
  -o, --output PATH                    Output file (default: stdout)
  --output-format [text|json]          Output format (default: text)

batch - Excel batch processing

bb-pbb-geometry batch INPUT_FILE -o OUTPUT_CSV

Processes all rows in an Excel file and outputs a CSV summary.

batch-points - Multiple point files

bb-pbb-geometry batch-points FILE1 FILE2 ... -o OUTPUT_CSV

Processes multiple point files and outputs a CSV summary.

excel-to-imod - Convert Excel to IMOD models

bb-pbb-geometry excel-to-imod EXCEL_FILE OUTPUT_DIR [OPTIONS]

Options:
  -r, --row INTEGER  Convert specific row number (1-based)

Converts Excel table rows to IMOD .mod files for visualization.
Each .mod file contains 3 objects:
  - Object 1: BB axis (red line, open contour)
  - Object 2: pBB axis (green line, open contour)
  - Object 3: OMM plane (blue triangle, closed contour)

Examples:
  # Convert all rows
  bb-pbb-geometry excel-to-imod data.xlsx output_models/

  # Convert specific row
  bb-pbb-geometry excel-to-imod data.xlsx output_models/ --row 5

Python API

from bb_pbb_geometry import analyze_points
from bb_pbb_geometry.io import read_point_file

# Read points
points = read_point_file("tomogram_001.txt")

# Analyze
results = analyze_points(points, "tomogram_001")

# Access results
print(f"BB to OMM angle: {results.bb_to_omm_angle:.2f}°")
print(f"pBB to OMM angle: {results.pbb_to_omm_angle:.2f}°")
print(f"BB to pBB angle: {results.bb_pbb_angle:.2f}°")

if results.warning:
    print(f"Warning: {results.warning}")

Development

Running tests

pytest

Code formatting

black src/ tests/
ruff check src/ tests/

License

MIT License - see LICENSE file for details.

Citation

If you use this software in your research, please cite:

[Citation information to be added]