DICE

Diffusion Insight Computation Engine (DICE)

DICE logo

Download the latest release on Zenodo GitHub repository

DOI

DICE is an open-source tool for researchers in time-resolved microscopy and related fields. It evaluates the precision and accuracy of diffusion coefficient estimates derived from optical measures of excited state transport. DICE provides a robust method for assessing experimental accuracy and precision by simulating parameters that mirror your experimental setup.

DICE was developed alongside research that the tool was used to perform, published in the following paper:

Joseph J. Thiebes, Erik M. Grumstrup; Quantifying noise effects in optical measures of excited state transport. J. Chem. Phys. 28 March 2024; 160 (12): 124201. https://doi.org/10.1063/5.0190347.

Introduction

DICE’s primary advantage lies in its ability to quantify the precision and accuracy of diffusion estimates. This is accomplished by reporting the fraction of the diffusion estimates found within a user-specified proximity to the nominal diffusion parameter. For example: “50% of the diffusion coefficient estimates are within ±10% of the nominal value.”

Thus, DICE measures the likelihood that your estimated diffusion coefficient will attain the accuracy and precision required for your investigations based on your experimental parameters, such as the initial spot width, nominal diffusion length, and initial contrast-to-noise ratio.

DICE aims to support ongoing improvements in the reliability and reproducibility of diffusion coefficient estimates derived from time-resolved microscopy methods. If you enjoy this program and found it helpful, please share it.

How it works

  1. Generation of time-series profiles: DICE starts by simulating a population of excited states as a Gaussian distribution profile that undergoes decay and diffusion. The initial profile has an amplitude of unity, a width parameterized by either the full-width half-maximum or the Gaussian standard deviation, a mean position of zero, and a baseline background of zero.
  2. Noise addition: DICE incorporates white noise into the generated profiles to better resemble real-world scenarios. The magnitude of the noise is the same for every time frame and is parameterized by its standard deviation.
  3. Gaussian fit: The time-evolved noisy profiles are fitted with Gaussian functions, estimating the Mean Squared Displacement (MSD) at each time point.
  4. Linear fit and diffusion coefficient estimation: The MSD values are fitted to a linear function using a weighted least squares method. The slope of the linear fit is proportional to the estimated diffusion coefficient.
  5. Analysis: DICE compares the estimated diffusion coefficient to the nominal parameter used to generate the series of profiles. By conducting multiple simulations with the same parameters, DICE provides a statistical view of the precision and accuracy of diffusion estimates.
  6. Presentation: Several customizable plotting functions are provided to present the results.

Table of Contents

Quick Start

Online CNR Estimator

Use this link to access an online CNR estimator for your 1D noisy Gaussian profile. No Python installation necessary.

Full DICE software

Follow these steps to get started with DICE quickly:

  1. Install Python: See [Installation] below.

  2. Download the Repository: Clone or download this repository to your local machine and navigate to the project directory in your Python environment.

  3. Edit Parameters: Modify the parameters.txt file to align with your experimental parameters. This file is the primary input for the simulation.

  4. Run the Simulation: DICE can be used in several ways depending on your installation method:

    • Using the console command (if installed with pip install -e .): 
      dice parameters.txt
    • From the command line using the script: Navigate to the DICE directory and run: 
      python run_dice.py parameters.txt
    • From within a Python environment: 
      from dice.cli.main import main
import sys
     
# Set the parameters file as command line argument
sys.argv = ['dice', 'parameters.txt']
main()

      Or use the analysis functions directly:

      from dice.analysis.simulation import run_monte_carlo_simulation
from dice.io.parameters import load_parameters
     
# Load and run simulation
parameters = load_parameters("parameters.txt")
result = run_monte_carlo_simulation(parameters)

    Note: You can run the simulation immediately with the included parameters.txt file to see example results.

  5. View the Results: After the simulation completes, the results will be summarized and saved, including a histogram plot for visual analysis.

Back to table of contents

Installation

Python Requirements

DICE requires Python 3.8 or later and has been tested with Python 3.11 and 3.12. You can install Python from the official website or use package managers like conda. For online development, you can use services like Google Colab or DataLore.

Installation Methods

Method 1: Install Dependencies and Use Directly

  1. Clone or download this repository to your local machine
  2. Navigate to the DICE directory
  3. Install dependencies using pip: 
    pip install -r requirements.txt

Method 2: Install as Editable Package

  1. Clone this repository: 
    git clone https://github.com/thiebes/DICE.git
cd DICE
  2. Install in development mode: 
    pip install -e .

    This allows you to use the dice command from anywhere and imports the package.

Dependencies

DICE depends on the following Python packages (minimum versions):

Standard Python Libraries: The following are part of the Python Standard Library and do not need to be installed separately:

Remember to regularly update your packages to their latest versions using pip to ensure the smooth functioning of DICE. If you encounter issues during installation, please contact the author or raise an issue on GitHub.

Back to table of contents

Parameter inputs

Edit the parameters.txt file to set up your simulation. Each simulation models one experimental diffusion measurement, comprising a series of time-evolved Gaussian profiles with noise. Each simulation uses one set of parameters.

Filename slug

A prefix for your output files to help identify them later. The output file names will also automatically include the parameters below, so your slug could be a textual identifier connected to a set of experiments. Avoid special characters in the slug.

Example:

If the Filename slug is set to 'example', simulation results are saved in the output/example/ directory:

All simulation parameters and settings are included in the summary text file for reference.

Number of simulation iterations

Specify the number of simulations to run.

Units

Specify the singular units for length and time, like 'micrometer' and 'nanosecond'. These units apply to all parameters representing physical quantities of length and time. Ensure that all parameter magnitudes are appropriately scaled.

Nominal diffusion and lifetime parameters

Provide either:

Note: Scale these parameters for the units parameterized above (or, in the case of the diffusion coefficient, the square of your length unit over your time unit) Examples:

Initial profile parameters

Configure the amplitude, mean, and width of the initial Gaussian profile. Note: Amplitudes other than unity have not been tested.

Noise value

Set the standard deviation of noise added to each profile pixel. You can provide:

Spatial axis parameters

Set the spatial width and pixel number for the scan. The spatial width should align with the length unit specified.

Temporal axis parameters

Provide time-axis information using one of the following forms:

Proximity level

This parameter determines the accuracy threshold to analyze. For instance, a 0.1 proximity level means the program will evaluate how many estimates are within $\pm 10$% of the nominal value.

In other words:

For example, if you enter 0.1 for your precision level, the program will tell you what portion of all the estimates were within $\pm 10$% of the nominal value.

Note: Conventional statistical methods of characterizing precision and accuracy are to report the standard deviation and the mean, median, and mode, respectively. The portion of estimates that are within proximity to the nominal value, reported by this script, offers a single evaluation of the impact of both precision and accuracy on the results. In some ways, this figure may be more intuitive and practical in experimental settings.

Plotting (image) parameters

Data retention

Decide whether to retain all profile data. Note that keeping profile data may impact performance, depending on the number of profiles generated.

Parallel processing

Enable parallel processing by setting this parameter to True.

Back to table of contents

Functions

The source code contains extensive documentation describing the functions and how they work.

Back to table of contents

Outputs

DICE generates three main output files, organized in the output/<filename_slug>/ directory:

All outputs are saved in output/<filename_slug>/ to keep your workspace organized.

Back to table of contents

Interpreting Results

The result of simulations based on a given set of parameters is a distribution of diffusion coefficient estimates. By analyzing this distribution, users can assess whether a given experimental measurement with the same parameters is representative of the range of possible measurements that might be taken if the experiment were performed repeatedly.

When the parameters are input, the user chooses a diffusion coefficient and lifetime or a diffusion length. The “true” diffusion coefficient is inexorably unknown, so the input parameter is a best guess or an initial measurement.

Importantly, the results of the simulation are not to be interpreted as a comment on whether the diffusion coefficient and other input parameters are correct. Rather, the results indicate a range of possible estimates that would arise in experiment if the input parameters are correct.

Back to table of contents

Glossary

Jargon terms and acronyms used in this documentation include:

Back to table of contents

Known issues and limitations

Back to table of contents

Contributions and feedback

We welcome contributions and feedback from the community to improve DICE. If you’re interested in contributing, here’s how you can help:

Reporting Bugs or Issues

Feature Requests

Contributing Code

Documentation Improvements

Questions and General Feedback

Your contributions, feedback, and questions are invaluable to us. They help us make DICE a better tool for everyone in the research community. Thank you for your support and collaboration!

Back to table of contents

Acknowledgements

Thanks to Professor Erik M. Grumstrup, Skyler Hollinbeck, Sajia Afrin, and my spouse, Julia K. Thiebes, for their invaluable support and feedback.

This material is based upon work supported by the National Science Foundation under Grant No. 2154448. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.

Back to table of contents

How to cite

Joseph J. Thiebes. 2023. thiebes/DICE. Zenodo. https://doi.org/10.5281/zenodo.10258191

Back to table of contents

License

Diffusion Insight Computation Engine (DICE) by Joseph J. Thiebes is licensed under the MIT License.

Copyright (c) 2023-2025 Joseph J. Thiebes

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.

Back to table of contents

This site is open source. Improve this page.