WARNING: This repo have moved to
Please refer to the new location for issues and updates.
PyBroMo is an open-source simulator for Brownian-motion diffusion and photon emission of fluorescent particles excited by a diffraction limited laser spot. PyBroMo allows to simulate timestamps of photons emitted during smFRET experiments, including sample background and detectors dark counts and to save the results in in Photon-HDF5 format. The smFRET data files can be analyzed with any smFRET burst analysis software.
For an opensource smFRET burst analysis software supporting Photon-HDF5 see FRETBursts.
PyBromo simulates 3-D Brownian motion trajectories and emission of an arbitrary number of particles freely diffusing in a simulation volume (a box). Inside the simulation box a laser excitation volume (the PSF of the objective lens) is defined numerically or analytically (Gaussian shape). Particles diffusing through the excitation volume emit photons at a rate proportional to the local excitation intensity.
A precomputed numerical PSF is included and used by default. The included numerical PSF is computed through rigorous vectorial electromagnetic computations ([Nasse, Woehl 2010] (http://dx.doi.org/10.1364/JOSAA.27.000295)) using the PSFLab software. The user can provide a different numerical PSF or, alternatively, use an analytical Gaussian-shaped PSF.
An overview of the architecture of the simulator can be found below.
The user documentation is provided in a series of Jupyter notebooks (see Usage examples).
If you have a question or find a bug in PyBroMo please open a GitHub Issue. Bug fixes and/or enhancements are welcome, just send a pull request (PR).
For more info contact me at tritemio@gmail.com.
PyBroMo is written in the python programming language using the standard scientific stack of libraries (numpy, scipy, pytables, matplotlib).
Usage examples are given as Jupyter/IPython notebooks. Jupyter Notebook is an interactive web-based environment that allows to mix rich text, math and graphics with (live) code. You can find a static HTML version of the notebooks below in section Usage examples.
Moreover the IPython environment allows to easily setup a cluster for parallel computing. Therefore simulation time can be greatly reduced using a single multi-core PC, multiple PC or a cloud-computing service.
If you are new to Jupyter Notebook, refer to this guide for installation and first steps:
The simulation domain is defined as 3-D box, centered around the origin. As boundary conditions particles can be either reflected at the interface ("mirror" condition) or reinjected from the opposite face ("periodic" condition).
A particle is described by its initial position. A list of particles with random initial position is generated before running the diffusion simulation.
The excitation PSF is a function of the position and is centered with maximum on the origin. A realistic PSF obtained by vectorial electromagnetic simulation is precomputed using PSFLab. The PSF is computed for a water immersion objective (NA = 1.2) at 532 nm and includes effects such as refractive index mismatch and mismatch between the objective lens correction and the cover-glass thickness. The user can generate a different PSF using PSFLab or equivalent software. The PSF is generated using circular polarized light so it has cylindrical symmetry and it is precomputed only on the x-z plane. Alternatively, a simple Gaussian PSF can also be used.
The Brownian motion parameters are: the diffusion coefficient, the simulation box, the list of particles, the simulation time step and the simulation duration.
The Brownian motion simulation uses constant time-steps (typically 0.5 μs).
This allows a straightforward and efficient implementation.
The total simulation time is divided in chunks so that trajectories for a single chunk
can easily fit in RAM. For each chunk, trajectories are computed by
cumulative sum (cumsum)
of the array of Gaussian displacement.
The instantaneous emission rate of each particle is computed during the Brownian motion simulation by evaluating the PSF intensity at each position. After the diffusion simulation, for each particle, photons are generated from a Poisson process using the previously computed emission rates. An additional constant Poisson process models sample background and detectors' dark counts. The time bin in which a "count" (photon or background) is extracted becomes the timestamp.
PyBroMo provides functions to simulate one or multiple FRET populations,
saving the results in regular smFRET data files in Photon-HDF5 format. For each timestamp,
the particle ID is also saved, allowing to separate the contribution of each particle.
Photo-physics effects, such as blinking and bleaching, are not explicily
modeled but they can be easily included "modulating" the emission
rates before generating the photons.
Two-states systems (each state with a different FRET efficiency) can be also
simulated. In this case, the user needs to generate a static smFRET data file for each state
(from the same diffusion trajectories). Next, transition times (switch-points) can be
computed (e.g. drawing exponetial random variables) for each particle until the simulation
duration is covered. Finally, the user can create a new
smFRET data file by selecting timestamps from each static-state file
according to the generated transitions.
As a final note, PyBroMo computations can be performed on a single core or distributed on the nodes of a cluster (IPython cluster). Thanks to the IPython infrastructure the simulation can be seamless run on a single machine, on a cluster of machines or on a cloud computing server.
PyBroMo includes a collection of notebooks which serves both as usage examples and user guide. The notebooks can be read online at:
You may be also interested in a few notebooks on the theory of Brownian motion simulation (they don't require PyBroMo):
- Theory - Introduction to Brownian Motion simulation
- Theory - On Browniam motion and Diffusion coefficient
- python 3.3 (or higher)
- numpy 1.8 (or higher)
- matplotlib 1.4.3 (or higher) (with QT backend for the trajectory explorer GUI)
- pytables 3.1 (or later)
- Jupyter notebook 3 (or later)
- phconvert (0.6.6 or later) to save smFRET Photon-HDF5 files
I wish to thank Xavier Michalet for useful discussions.
This work was supported by NIH grants R01 GM069709 and R01 GM095904.
PyBroMo - A single molecule FRET diffusion simulator in confocal geometry.
Copyright (C) 2013-2017 Antonino Ingargiola - tritemio@gmail.com
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
version 2, as published by the Free Software Foundation.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You can find a full copy of the license in the file LICENSE.txt