BioLocSim

A Python library for simulating SMLM point cloud data.

• Documentation: https://sylvanding.github.io/biolocsim
• GitHub: https://github.com/sylvanding/biolocsim
• PyPI: https://pypi.org/project/biolocsim/
• Free software: MIT

Features

• Simulate Biological Structures: Generate 3D point cloud data for:
  • Microtubules: Modeled using B-splines for smooth, realistic curves.
  • Mitochondria: Simulated with a persistent random walk model to create complex, branching shapes.
  • Nuclear Pore Complexes (NPCs): Simulated with 8-fold symmetry, realistic error models (localization uncertainty, linker error, binding site jitter), and support for multiple NPCs on a nuclear envelope.
  • Clathrin-Coated Pits (CCPs): Modeled as spheroid caps with configurable surface area, close angle, and flattening. Includes spatial exclusion for labeling, multiple emission (blinking) simulation, and support for multiple CCPs in a 3D volume with background noise.
• Point Cloud Rendering: Convert 3D point clouds into 2D microscopy-style images, complete with PSF convolution and background noise simulation.
• Mask Generation:
  • Microtubules: Create 2D and 3D centerline masks for ground truth generation.
  • Mitochondria: Produce 3D volume grids, surface masks, and 2D projection masks.
• Flexible Configuration: Easily adjust simulation parameters (volume size, point density, structure-specific attributes) through configuration files.
• Batch Processing: Automate the generation of large datasets with a command-line interface for running simulations in parallel.

Installation

There are two primary ways to install biolocsim, depending on your use case.

For Users: Install from PyPI

If you intend to use biolocsim as a library in your own projects, the easiest way is to install the latest stable release from PyPI.

# Create a new conda environment with Python 3.10
conda create -n biolocsim python=3.10 -y
conda activate biolocsim

# Install biolocsim
pip install biolocsim

For Developers: Install from Source

If you want to contribute to biolocsim, run the examples, or use the latest development version, you should install it from the source code.

1. Clone the repository:

   git clone https://github.com/sylvanding/biolocsim.git
   cd biolocsim
   

2. Create a development environment: We recommend using conda for environment management to ensure consistency.

   # Create a new conda environment with Python 3.10
   conda create -n biolocsim-dev python=3.10 -y
   conda activate biolocsim-dev
   

3. Install dependencies using Poetry: This project uses Poetry to manage dependencies. First, install Poetry itself:

   pip install poetry
   

   Then, install the project and its dependencies with poetry.lock (recommended):

   poetry install
   

   or without poetry.lock, including tools for development, testing, and documentation (not recommended):

   poetry install -E doc -E dev -E test
   

4. Verify the installation (optional): You can run the full test suite with tox to make sure everything is set up correctly.

   poetry run tox
   

   This will run tests and code style checks.

Usage Examples

This library includes examples for generating single structures and running batch simulations. You can find them in the examples/ directory.

Generating Single Structures

To generate a single structure, you can run the corresponding script from the examples/ directory.

# Generate microtubules
python examples/generate_microtubules.py

# Generate mitochondria
python examples/generate_mitochondria.py

# Generate a single Nuclear Pore Complex
python examples/generate_npc.py

# Generate multiple NPCs on a nuclear envelope
python examples/generate_npc_nucleus.py

# Generate a single Clathrin-Coated Pit
python examples/generate_ccp.py

# Generate multiple CCPs in a 3D volume
python examples/generate_ccp_roi.py

The output, including the point cloud (CSV), rendered images (PNG/TIFF), and masks, will be saved in the outputs/ directory.

Batch Generation

For generating a large dataset, the batch_generate.py script allows running multiple simulations in parallel.

# Run 4 parallel simulations for microtubules
python examples/batch_generate.py microtubule -n 4 -w 4

# Run 8 parallel simulations for mitochondria
python examples/batch_generate.py mitochondria -n 8 -w 4

# Run 10 single NPC simulations
python examples/batch_generate.py npc -n 10 -w 4

# Run 5 nucleus (multiple NPCs) simulations
python examples/batch_generate.py nucleus -n 5 -w 4

# Run 10 single CCP simulations
python examples/batch_generate.py ccp -n 10 -w 4

# Run 5 ROI CCP (multiple CCPs) simulations
python examples/batch_generate.py ccp_roi -n 5 -w 4

You can specify the structure type (microtubule, mitochondria, npc, nucleus, ccp, or ccp_roi), the total number of simulations (-n), and the number of parallel workers (-w). The results will be saved in subdirectories within outputs/batch_simulation/.

Acknowledgements

The core simulation methodologies for generating SMLM biological structures point clouds in this library are heavily inspired by and based upon the principles described in the following seminal papers:

@article{ouyang2018deep,
  title={Deep learning massively accelerates super-resolution localization microscopy},
  author={Ouyang, Wei and Aristov, Andrey and Lelek, Micka{\"e}l and Hao, Xian and Zimmer, Christophe},
  journal={Nature biotechnology},
  volume={36},
  number={5},
  pages={460--468},
  year={2018},
  publisher={Nature Publishing Group US New York}
}

% ---- Microtubule related papers ----

@article{sage2019super,
  title={Super-resolution fight club: assessment of 2D and 3D single-molecule localization microscopy software},
  author={Sage, Daniel and Pham, Thanh-An and Babcock, Hazen and Lukes, Tomas and Pengo, Thomas and Chao, Jerry and Velmurugan, Ramraj and Herbert, Alex and Agrawal, Anurag and Colabrese, Silvia and others},
  journal={Nature methods},
  volume={16},
  number={5},
  pages={387--395},
  year={2019},
  publisher={Nature Publishing Group US New York}
}

% ---- Mitochondria related papers ----

@article{brenner2024quantifying,
  title={Quantifying nanoscopic alterations associated with mitochondrial dysfunction using three-dimensional single-molecule localization microscopy},
  author={Brenner, Benjamin and Xu, Fengyuanshan and Zhang, Yang and Kweon, Junghun and Fang, Raymond and Sheibani, Nader and Zhang, Sarah X and Sun, Cheng and Zhang, Hao F},
  journal={Biomedical Optics Express},
  volume={15},
  number={3},
  pages={1571--1584},
  year={2024},
  publisher={Optica Publishing Group}
}

% ---- NPC related papers ----

@article{kim2018integrative,
  title={Integrative structure and functional anatomy of a nuclear pore complex},
  author={Kim, Seung Joong and Fernandez-Martinez, Javier and Nudelman, Ilona and Shi, Yi and Zhang, Wenzhu and Raveh, Barak and Herricks, Thurston and Slaughter, Brian D and Hogan, Joanna A and Upla, Paula and others},
  journal={Nature},
  volume={555},
  number={7697},
  pages={475--482},
  year={2018},
  publisher={Nature Publishing Group UK London}
}

@article{loschberger2012super,
  title={Super-resolution imaging visualizes the eightfold symmetry of gp210 proteins around the nuclear pore complex and resolves the central channel with nanometer resolution},
  author={L{\"o}schberger, Anna and Van de Linde, Sebastian and Dabauvalle, Marie-Christine and Rieger, Bernd and Heilemann, Mike and Krohne, Georg and Sauer, Markus},
  journal={Journal of cell science},
  volume={125},
  number={3},
  pages={570--575},
  year={2012},
  publisher={Company of Biologists}
}

% ---- CCP related papers ----

@article{ries2020smap,
  title={SMAP: a modular super-resolution microscopy analysis platform for SMLM data},
  author={Ries, Jonas},
  journal={Nature methods},
  volume={17},
  number={9},
  pages={870--872},
  year={2020},
  publisher={Nature Publishing Group US New York}
}

@article{wu2023maximum,
  title={Maximum-likelihood model fitting for quantitative analysis of SMLM data},
  author={Wu, Yu-Le and Hoess, Philipp and Tschanz, Aline and Matti, Ulf and Mund, Markus and Ries, Jonas},
  journal={Nature Methods},
  volume={20},
  number={1},
  pages={139--148},
  year={2023},
  publisher={Nature Publishing Group US New York}
}

@article{mund2021superresolution,
  title={Superresolution microscopy reveals partial preassembly and subsequent bending of the clathrin coat during endocytosis},
  author={Mund, Markus and Tschanz, Aline and Wu, Yu-Le and Frey, Felix and Mehl, Johanna L and Kaksonen, Marko and Avinoam, Ori and Schwarz, Ulrich S and Ries, Jonas},
  journal={BioRxiv},
  pages={2021--10},
  year={2021},
  publisher={Cold Spring Harbor Laboratory}
}

Credits

This package was created with Cookiecutter and the waynerv/cookiecutter-pypackage project template.