Skip to content

Home

AMS-BP#

AMS-BP Logo

Advanced Fluorescence Microscopy Simulation Tool#

AMS-BP is a powerful simulation tool for advanced fluorescence microscopy experiments. This guide covers both command-line usage and library integration.

Overview of Simulation Workflow#

A ground truth is created, a, with (f_{n}\) fluorophore types of (N_{f_{n}}\) molecules each. If applicable, the motion of these molecules is modelled using a 3D bounded FBM with fluctuating generalized diffusion coefficients and Hurst parameters. Variations are modelled as a Markov Chain and require rate constants as parameters. Different fluorophores can have different motion models. The resolution of the motion models is (\Delta t\) and cannot be smaller than 1 ms (for computational efficiency). Given the microscope parameters specific to the experimental procedure to simulate, at every time (t_{j}\), the excitation intensity for each channel (b) is calculated at each fluorophore's location, c. For (t_{j} \rightarrow t_{j+\Delta t}\), the photophysical state trajectory of the fluorophore is simulated using the light intensity at the molecule's location as input for any light-dependent transition rates, d. For the duration that the shutter is open and light is emitted from the sample, emission filters for each channel are applied before the convolution with PSF models, e. The incident photons on the detector are then converted to photoelectrons and finally to digital units using the detector models provided, f.

API Reference and Docs#

Find detailed API references for the library at: joemans3/github.io/AMS_BP

A more detailed example is provided in the jupyter notebook in the examples. For starters refer to the VisualizingIndividualModules. Then head over to the laser modulation module which will show how to change the laser power over time in the simulations. Then view an example of a complex experiment setup for FRAP which is possible by the use of compositions of modules in this simulation library.

Examples (Click on the image buttons to be taken to the Jupyter notebooks):#

!!ATTENTION!! - Please note that you NEED to install the developmental dependencies to run the examples in full. This is mainly for installing the Jupyter notebook extensions, matplotlib and other visualization packages.

Table of Contents#

Installation#

Installing the CLI tool using UV#

  1. Install UV.
  2. Run the command:
uv tool install AMS_BP
  1. You will have access to three CLI commands (using the uv interface):
    • run_AMS_BP runsim : This is the main entry point for the simulation. (see run_AMS_BP runsim --help for more details)
    • run_AMS_BP config : This is a helper tool to generate a template config file for the simulation. (see run_AMS_BP config --help for more details)
    • run_AMS_BP gui : to start the GUI. See GUI Documentation
    • Note: using run_AMS_BP --help will show you all the available commands.
  2. You can now use these tools (they are isolated in their own env created by uv, which is cool).

PyPi#

  1. If using pip, make sure the environment is python >= 3.12
  2. Run:
pip install AMS_BP

Command Line Interface#

AMS-BP provides a command-line interface with three main commands:

# Generate a default configuration file
run_AMS_BP config [OPTIONS]

# Run a simulation using a configuration file
run_AMS_BP runsim CONFIG_FILE

#start the GUI
run_AMS_BP gui

Config Command Options#

  • -o, --output_path PATH: Specify the output directory for the configuration file
  • -r, --recursive_o: Create output directory if it doesn't exist

GUI#

In addition to the CLI and programmatic API, AMS-BP comes with a graphical interface to guide users through the configuration, simulation, and analysis pipeline.

Main GUI Features#

The GUI provides the following tools from a single interface:

  • Create Configuration File — Launches the visual configuration builder
  • Run Simulation from Config — Select a .toml file and run the simulation with logging and progress tracking
  • Visualize Microscopy Data (Napari) — Open TIFF, PNG, ND2, or Zarr image files and view with the Napari viewer
  • Package Logs for Sharing — Package run directories (e.g., run_2024_04_20_001) into a .zip file for archival or collaboration

Launch the GUI#

To start the GUI, run:


run_AMS_BP gui

For detailed walkthrough see the GUI Documentation.

Configuration File#

The configuration file (sim_config.toml) is divided into several key sections:

For a detailed description of the configuration file, refer to the Configuration File Reference.#

Basic Units#

version = "0.1"
length_unit = "um"        # micrometers
time_unit = "ms"          # milliseconds
diffusion_unit = "um^2/s" # diffusion coefficient units

Key Configuration Sections#

  1. Cell Parameters

  2. Define cell space dimensions

  3. Molecule Parameters

  4. Number of molecules per type
  5. Tracking types (constant/fbm)
  6. Diffusion coefficients

  7. State transition probabilities

  8. Global Parameters

  9. Sample plane dimensions
  10. Cycle count -> Exposure time + Interval time

  11. Exposure and interval times

  12. Fluorophore Configuration

  13. Any number of fluorophores
  14. Any number of States per fluorophore
  15. Fluorophore StateType: (bright, dark, bleached) -> All States must be one of these.
  16. Transition parameters

  17. Spectral properties

  18. Optical Configuration

  19. PSF parameters
  20. Laser settings
  21. Channel configuration
  22. Camera settings

Running Experiments#

AMS-BP's CLI currently supports two types of experiments:

(however this can be extended when used as a library)

1. Time Series#

[experiment]
experiment_type = "time-series"
z_position = 0.0
laser_names_active = ["red", "blue"]
laser_powers_active = [0.5, 0.05]
laser_positions_active = [[5, 5, 0], [5, 5, 0]]

2. Z-Stack#

[experiment]
experiment_type = "z-stack"
z_position = [-0.5, -0.4, -0.3, -0.2, -0.1, 0, 0.1, 0.2, 0.3, 0.4, 0.5]
laser_names_active = ["red", "blue"]
laser_powers_active = [0.5, 0.05]
laser_positions_active = [[5, 5, 0], [5, 5, 0]]

To run the default configuration: 1. Make sure you followed the uv tool installation. 2. Make a copy of the default configuration file using the command:

run_AMS_BP config
  1. Run the sim:
run_AMS_BP runsim sim_config.toml
  1. View the results in the newly created folder, whose name is defined in the config file.

High Priority Features#

~~1. Irregular cell shapes with motion models~~ (supported with release of v0.2.0) 2. Stimulated Emission models 3. STORM workflow examples 4. CTRW motion models 5. Simpler configurations

NOTE: Please note that this application DOES NOT currently model the process of stimulated emission, and as such is not suitable for simulating stimulated emission microscopy (STED)-type experiments. Work in this area is ongoing.

Custom Experiment Types#

When using AMS-BP as a library, you can create custom experiment types by:

  1. Extending the base experiment class
  2. Implementing custom scanning patterns
  3. Defining new molecule behaviors
  4. Creating specialized analysis routines

Tips and Best Practices#

  1. Configuration Management
  2. Keep separate config files for different experiment types
  3. Version control your configurations

  4. Document any custom modifications

  5. Resource Usage

  6. Monitor memory usage for large simulations

  7. Use appropriate sampling rates

  8. Data Output

  9. Set appropriate output paths
  10. Use meaningful naming conventions
  11. Consider data format requirements for analysis

Troubleshooting#

Common issues and their solutions: TODO