lattice-sub 1.0.10__py3-none-any.whl

lattice_sub-1.0.10.dist-info/METADATA

@@ -0,0 +1,324 @@
+Metadata-Version: 2.4
+Name: lattice-sub
+Version: 1.0.10
+Summary: Lattice subtraction for cryo-EM micrographs - removes periodic crystal signals to reveal non-periodic features
+Author-email: George Stephenson <george.stephenson@colorado.edu>, Vignesh Kasinath <vignesh.kasinath@colorado.edu>
+License: MIT
+Project-URL: Homepage, https://github.com/gsstephenson/cryoem-lattice-subtraction
+Project-URL: Documentation, https://github.com/gsstephenson/cryoem-lattice-subtraction#readme
+Project-URL: Repository, https://github.com/gsstephenson/cryoem-lattice-subtraction
+Keywords: cryo-em,electron-microscopy,lattice-subtraction,image-processing,fft
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.11
+Requires-Dist: mrcfile>=1.4
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tqdm>=4.65
+Requires-Dist: click>=8.1
+Requires-Dist: scikit-image>=0.21
+Requires-Dist: torch>=2.0
+Requires-Dist: matplotlib>=3.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.7; extra == "viz"
+Dynamic: license-file
+
+# Lattice Subtraction for Cryo-EM
+
+```
+.__          __    __  .__                                   ___.    
+|  | _____ _/  |__/  |_|__| ____  ____             ________ _\_ |__  
+|  | \__  \\   __\   __\  |/ ___\/ __ \   ______  /  ___/  |  \ __ \ 
+|  |__/ __ \|  |  |  | |  \  \__\  ___/  /_____/  \___ \|  |  / \_\ \
+|____(____  /__|  |__| |__|\___  >___  >         /____  >____/|___  /
+          \/                   \/    \/               \/          \/ 
+```
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.5+-ee4c2c.svg)](https://pytorch.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Remove periodic lattice patterns from cryo-EM micrographs to reveal non-periodic features.**
+
+![Example Result](docs/images/example_comparison.png)
+
+---
+
+## Installation
+
+```bash
+pip install lattice-sub
+```
+
+That's it! GPU acceleration works automatically if you have an NVIDIA GPU.
+
+---
+
+## Quick Start
+
+### Process a Single Image
+
+```bash
+lattice-sub process your_image.mrc -o output.mrc --pixel-size 0.56
+```
+
+### Process a Folder of Images
+
+```bash
+lattice-sub batch input_folder/ output_folder/ --pixel-size 0.56
+```
+
+### Generate Comparison Images
+
+```bash
+lattice-sub batch input_folder/ output_folder/ --pixel-size 0.56 --vis comparisons/
+```
+
+This creates side-by-side PNG images showing before/after/difference for each micrograph.
+
+---
+
+## Common Options
+
+| Option | Description |
+|--------|-------------|
+| `-p, --pixel-size` | **Required.** Pixel size in Ångstroms |
+| `-o, --output` | Output file path (default: `sub_<input>`) |
+| `-t, --threshold` | Peak detection sensitivity (default: 1.42) |
+| `--cpu` | Force CPU processing (GPU is used by default) |
+| `-q, --quiet` | Hide the banner and progress messages |
+| `-v, --verbose` | Show detailed processing information |
+
+### Example with Options
+
+```bash
+# Process with custom threshold, verbose output
+lattice-sub process image.mrc -o cleaned.mrc -p 0.56 -t 1.5 -v
+
+# Batch process, force CPU with 8 parallel workers
+lattice-sub batch raw/ processed/ -p 0.56 --cpu -j 8
+```
+
+---
+
+## Using a Config File
+
+For reproducible processing, save your parameters in a YAML file:
+
+```yaml
+# params.yaml
+pixel_ang: 0.56
+threshold: 1.42
+inside_radius_ang: 90
+unit_cell_ang: 116
+```
+
+Then use it:
+
+```bash
+lattice-sub process image.mrc -o output.mrc --config params.yaml
+```
+
+Create a starter config file:
+
+```bash
+lattice-sub init-config params.yaml --pixel-size 0.56
+```
+
+---
+
+## GPU Troubleshooting
+
+GPU should work automatically. If it doesn't:
+
+```bash
+# Check GPU status
+lattice-sub setup-gpu
+
+# Or verify manually
+python -c "import torch; print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'No GPU')"
+```
+
+**Requirements:** NVIDIA GPU with driver 525+ (RTX 20/30/40 series, A100, etc.)
+
+---
+
+## Python API
+
+```python
+from lattice_subtraction import LatticeSubtractor, Config
+
+# Configure and process
+config = Config(pixel_ang=0.56)
+subtractor = LatticeSubtractor(config)
+
+result = subtractor.process("input.mrc")
+result.save("output.mrc")
+```
+
+### Batch Processing
+
+```python
+from lattice_subtraction import BatchProcessor, Config
+
+config = Config(pixel_ang=0.56)
+processor = BatchProcessor(config)
+
+stats = processor.process_directory("raw/", "processed/")
+print(f"Processed {stats.successful}/{stats.total} files")
+```
+
+---
+
+## What It Does
+
+This tool removes the periodic "lattice" pattern from 2D crystal cryo-EM images:
+
+1. **Finds lattice peaks** in the Fourier transform (the repeating pattern)
+2. **Replaces them** with averaged local values (inpainting)
+3. **Preserves phase** so the image stays accurate
+4. **Returns** the cleaned image with non-periodic features visible
+
+### Key Parameters Explained
+
+| Parameter | What it controls |
+|-----------|------------------|
+| `pixel_ang` | Your detector's pixel size (check your microscope settings) |
+| `threshold` | How aggressively to detect peaks. Higher = fewer peaks removed |
+| `inside_radius_ang` | Protect low-resolution features (default 90Å is good for nucleosomes) |
+| `unit_cell_ang` | Crystal repeat distance (116Å for nucleosome arrays) |
+
+---
+
+## Need Help?
+
+```bash
+# See all commands
+lattice-sub --help
+
+# See options for a specific command
+lattice-sub process --help
+lattice-sub batch --help
+```
+
+---
+
+## Citation
+
+```bibtex
+@software{lattice_sub,
+  title = {Lattice Subtraction for Cryo-EM Micrographs},
+  author = {Stephenson, George and Kasinath, Vignesh},
+  year = {2026},
+  url = {https://github.com/gsstephenson/cryoem-lattice-subtraction}
+}
+```
+
+**Original MATLAB algorithm**: Vignesh Kasinath  
+**Python package**: George Stephenson  
+Kasinath Lab, BioFrontiers Institute, University of Colorado Boulder
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+---
+
+<details>
+<summary><strong>📚 Advanced Topics</strong> (click to expand)</summary>
+
+### Algorithm Details
+
+```
+Image → Pad → FFT → Detect Peaks → Create Mask → Inpaint → iFFT → Crop → Output
+```
+
+The algorithm:
+1. Pads the image to reduce edge artifacts
+2. Applies 2D FFT to get frequency domain
+3. Detects lattice peaks via thresholding on log-power spectrum
+4. Creates a mask protecting inner (low-freq) and outer (high-freq) regions
+5. Inpaints peaks with local average amplitude from 4 shifted neighbors
+6. Preserves original phase information
+7. Inverse FFT returns to real space
+
+### Full Parameter Reference
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `pixel_ang` | *required* | Pixel size in Ångstroms |
+| `threshold` | 1.42 | Peak detection threshold on log-amplitude |
+| `inside_radius_ang` | 90 | Inner resolution limit (Å) - protects structural info |
+| `outside_radius_ang` | auto | Outer resolution limit (Å) - protects near Nyquist |
+| `expand_pixel` | 10 | Morphological expansion of peak mask (pixels) |
+| `unit_cell_ang` | 116 | Crystal unit cell for inpaint shift calculation (Å) |
+| `backend` | auto | `"auto"`, `"numpy"` (CPU), or `"pytorch"` (GPU) |
+
+### Supported Hardware
+
+- **NVIDIA GPUs**: RTX 20/30/40 series, A100, H100
+- **CUDA versions**: 11.8, 12.1, 12.4, 12.6, 12.8
+- **CPU fallback**: Works on any system (just slower)
+
+### Development Setup
+
+```bash
+git clone https://github.com/gsstephenson/cryoem-lattice-subtraction.git
+cd cryoem-lattice-subtraction
+
+conda create -n lattice_sub python=3.11 -y
+conda activate lattice_sub
+
+pip install -e ".[dev]"
+pytest tests/ -v  # Run tests
+```
+
+### Code Structure
+
+```
+src/lattice_subtraction/
+├── __init__.py        # Package exports
+├── cli.py             # Command-line interface
+├── core.py            # LatticeSubtractor main class
+├── batch.py           # Parallel batch processing
+├── config.py          # Configuration dataclass
+├── io.py              # MRC file I/O
+├── masks.py           # FFT mask generation
+├── processing.py      # FFT helpers
+├── ui.py              # Terminal UI
+└── visualization.py   # Comparison figures
+```
+
+### Migration from MATLAB
+
+This is a modernized rewrite of legacy MATLAB code (`LAsub.m`, `bg_push_by_rot.m`, etc.) with:
+- 10-100× faster processing via GPU
+- Pip-installable package
+- YAML config files instead of hardcoded values
+- Command-line interface
+- Automated testing
+
+Convert a legacy PARAMETER file:
+
+```bash
+lattice-sub convert-config PARAMETER params.yaml
+```
+
+</details>

lattice_sub-1.0.10.dist-info/RECORD

@@ -0,0 +1,16 @@
+lattice_sub-1.0.10.dist-info/licenses/LICENSE,sha256=2kPoH0cbEp0cVEGqMpyF2IQX1npxdtQmWJB__HIRSb0,1101
+lattice_subtraction/__init__.py,sha256=FkGThd0LyCu5WWJsyTNT1cjecysjHbXkEEL_3u_DabU,1464
+lattice_subtraction/batch.py,sha256=sTDWEL5FlEx2HFaJsTZRXyzLQoNCgUqRo900eZ6kq68,12005
+lattice_subtraction/cli.py,sha256=VVLMvtSbo3iEWRiUPBZJxvquSty7QHXmE8dxUy3jYm0,23200
+lattice_subtraction/config.py,sha256=gziw2drMbuefTf7L5zGEnJljmjdMD_daGQE85NyOWHw,7427
+lattice_subtraction/core.py,sha256=9ExoPVifc5OVBSh-wL_tp6z-CwuMYWfmg6PRWTL2mW0,14551
+lattice_subtraction/io.py,sha256=uHku6rJ0jeCph7w-gOIDJx-xpNoF6PZcLfb5TBTOiw0,4594
+lattice_subtraction/masks.py,sha256=HIamrACmbQDkaCV4kXhnjMDSwIig4OtQFLig9A8PMO8,11741
+lattice_subtraction/processing.py,sha256=UnwEuuRLpffXVgDz8D56VlusXSCZ5NAABGZRvBe3VTs,6210
+lattice_subtraction/ui.py,sha256=Sp_a-yNmBRZJxll8h9T_H5-_KsI13zGYmHcbcpVpbR8,9176
+lattice_subtraction/visualization.py,sha256=7hAT19BWuw4l3JUTHFf29qwD1b2_fR9LS7p6x3BwEyA,5761
+lattice_sub-1.0.10.dist-info/METADATA,sha256=09AlzyPDqh0vCjW2QNiTn_Elmld0wvAVoQb1mIm3pho,9251
+lattice_sub-1.0.10.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+lattice_sub-1.0.10.dist-info/entry_points.txt,sha256=o8PzJR8kFnXlKZufoYGBIHpiosM-P4PZeKZXJjtPS6Y,61
+lattice_sub-1.0.10.dist-info/top_level.txt,sha256=BOuW-sm4G-fQtsWPRdeLzWn0WS8sDYVNKIMj5I3JXew,20
+lattice_sub-1.0.10.dist-info/RECORD,,

lattice_sub-1.0.10.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

lattice_sub-1.0.10.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lattice-sub = lattice_subtraction.cli:main

lattice_sub-1.0.10.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kasinath Lab, University of Colorado Boulder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lattice_sub-1.0.10.dist-info/top_level.txt

@@ -0,0 +1 @@
+lattice_subtraction

lattice_subtraction/__init__.py

@@ -0,0 +1,49 @@
+"""
+Lattice Subtraction for Cryo-EM Micrographs
+
+This package provides tools for computationally removing periodic crystal lattice
+signals (Bragg spots) from cryo-EM micrographs to reveal non-periodic features
+such as defects, individual particles, or molecular tags.
+
+Main components:
+    - LatticeSubtractor: Core class for processing single images
+    - BatchProcessor: Parallel processing of multiple micrographs
+    - Config: Configuration management via YAML files
+    - generate_visualizations: Create comparison PNG images
+
+Example:
+    >>> from lattice_subtraction import LatticeSubtractor, Config
+    >>> config = Config.from_yaml("params.yaml")
+    >>> subtractor = LatticeSubtractor(config)
+    >>> result = subtractor.process("micrograph.mrc")
+    >>> result.save("output.mrc")
+"""
+
+__version__ = "1.0.10"
+__author__ = "George Stephenson & Vignesh Kasinath"
+
+from .config import Config
+from .core import LatticeSubtractor
+from .batch import BatchProcessor
+from .io import read_mrc, write_mrc
+from .visualization import (
+    generate_visualizations,
+    save_comparison_visualization,
+    create_comparison_figure,
+)
+from .ui import TerminalUI, get_ui, is_interactive
+
+__all__ = [
+    "LatticeSubtractor",
+    "BatchProcessor", 
+    "Config",
+    "read_mrc",
+    "write_mrc",
+    "generate_visualizations",
+    "save_comparison_visualization",
+    "create_comparison_figure",
+    "TerminalUI",
+    "get_ui",
+    "is_interactive",
+    "__version__",
+]