Neuroimage Denoiser Documentation

Table of Contents

• Overview
• Getting Started
• Building from Source
• Usage
• Training a Custom Model
  • Prepare Training Data
  • Prepare Config File
  • Train the Model
  • Gridsearch
• Utils
  • Filter h5 file
    
  • Evaluate Inference Speed
• How to Cite

Overview

The Neuroimage Denoiser is a powerful tool designed for denoising microscopic recordings, offering pre-trained model weights for the iGlu-Snfr3 sensor ready to use. This denoising is built upon the U-Net model architecture. The model can be trained on any microscopic data, without the need for manual data curation.

| raw | denoised | | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | | |

The Neuroimage Denoiser maintains the amplitude heights and therefore does not alter subsequent analysis.

Getting started

Follow these steps to set up Neuroimage Denoiser:

1. Create a new enviorment:

bash conda create -n neuroimage_denoiser python=3.10 pip conda activate neuroimage_denoiser

1. Install from pip:

bash pip install neuroimage_denoiser

1. Download pre-trained model: Download the pre-trained model from the release page and place it in the project directory.

Building from Source

To build the latest version directly from GitHub, follow these steps: 1. Create a new enviorment:

bash conda create -n neuroimage_denoiser python=3.10 pip conda activate neuroimage_denoiser

1. Clone the repository:

bash git clone https://github.com/s-weissbach/neuroimage_denoiser.git cd neuroimage_denoiser

1. Install:

bash pip install -e . 4. Download pre-trained model: Download the pre-trained model from the release page and place it in the project directory.

Usage

[!Tip] The --directory_mode will presever the folderstructure of the input folder.

Activate the conda enviorment:

bash conda activate neuroimage_denoiser

Run the following command to denoise images:

bash python -m neuroimage_denoiser denoise --path /path/to/images --modelpath /path/to/model_weights --directory_mode -o /output/path

[!IMPORTANT] Although the Neuroimage Denoiser will work without a NVIDIA graphics card, it will run significantly slower. We highly recommend to only work on a server/PC with an available graphics card.

Arguments:

| Argument | Shorthand | Description | | ------------------ | --------- | ------------------------------------------------- | | --path | -p | Path to input imagestack or directory | | --modelpath | -m | Path to pre-trained model weights | | --directory_mode | -d | Enable directory mode (preserve folder structure) | | --outputpath | -o | Path to output directory | | --batchsize | -b | Number of frames predicted at once (default: 1) | | --cpu | | Force CPU useage, even if a GPU was found | | --gpu_num | | Specify the GPU to use (default: 0) |

Supported File Formats

• tiff-based formats: .tif, .tiff, .stk

• Nikon format: .nd2

All files will be written as a .tifffile.

If you require other file formats to be supported, feel free to open an issue on GitHub.

Example

Denoise a single recording:

bash python -m neuroimage_denoiser denoise --path /path/to/imagestack.tiff --modelpath /path/to/model.pt --outputpath /output/path

Denoise all recordings in a directory:

bash python -m neuroimage_denoiser denoise --path /path/to/images_folder --modelpath /path/to/model_weights --directory_mode -o /output/path

Training a Custom Model

To train a custom model for denoising, follow these steps:

1. Prepare Training

[!WARNING] Potentially uses a lot of RAM. If you have limited RAM capicity use --memory_optimized. Beware that this will increase execution time.

[!NOTE] The recordings itself can be noisy.

Prepare the creation by storing all recordings with one sensor in a directory /path/to/traindata/. Activitymap based identification:

• does not need recordings with stimulation
• applies rolling window z-normalization and identifies regions that exceed the min_z_score and the frame in that it happens

Use the prepare_trainfiles script to generate training data from a set of images. The script takes the following arguments:

| Argument | Shorthand | Description | | -------------------- | --------- | -------------------------------------------------------------------------------------------------- | | --path | -p | Path to the folder containing images | | --fileendings | -f | List of file endings to consider | | --crop_size | -c | Crop size used during training (default: 32) | | --roi_size | | Expected ROI size; assumes detection square of (roisize x roisize) (default: 4) | | --h5 | | Path to the output H5 file that will be created | | --min_z_score | -z | Minimum Z score to be considered an active ROI (default: 2) | | --window_size | -w | Number of frames used for rolling window z-normalization (default: 50) | | --overwrite | | Overwrite existing H5 file. If false, data will be appended (default: False) | | --memory_optimized | | Execute preparation process with optimized memory usage. Increases execution time (default: False) |

Example usage:

bash python -m neuroimage_denoiser prepare_training --path /path/to/traindata --fileendings tif tiff nd2 --crop_size 32 --roi_size 6 --trainh5 training_data.h5 --min_z_score 2.0 --window_size 50 --overwrite False

2. Prepare config file

Create a trainconfig.yaml file with the following configuration settings.

yaml modelpath: 'unet.pt' train_h5: '/path/to/train.h5' batch_size: 32 learning_rate: 0.0001 num_epochs: 1 noise_center: 0.0 noise_scale: 2.0

Adjust the paths and parameters in the configuration file based on your specific setup and requirements. This configuration file will be used during the training process to specify various parameters further:

Training Configuration File Summary

| Argument | Description | | --------------- | ------------------------------------------------------------------------- | | modelpath | Path to save the model after training | | train_h5 | Path to the h5 file containing the training data | | batch_size | Number of training examples utilized in one iteration | | learning_rate | Rate at which the model's weights are updated during training | | num_epochs | Number of times the entire training dataset is passed through the network | | noise_center | Center of the noise added to the input data during training | | noise_scale | Scale of the noise added to the input data during training |

3. Train the model

Run the training script by executing the following command:

bash python -m neuroimage_denoiser train -p /path/to/trainconfig.yaml`

--trainconfigpath (-p): Path to the train config YAML file containing training parameters. ----gpu_num: Specify the GPU to use (default: 0)

When a CUDA capable GPU is found GPU ready will be printed; otherwise Warning: only CPU found. It is not recommended to train with a CPU only.

Gridsearch

Perform a grid search over training parameters. First define the parameters that should be tested in grid_trainconfig.yaml

```yaml

training parameters

modelfolder: '/path/to/savetrainedmodels' trainh5: '/path/to/trainingdata.h5' batchsize: 64 learningrate: 0.0001 lossfunctions: ['L1','Smooth-L1','MSE','Huber'] noisescales: [0.5,1.0,1.5,2.0,3.0] noisecenters: [0,0.5,1.0] gaussianfilter: [True, False] gaussiansigma: [0.5,1.0] numepochs: 1

evaluation parameters

batchsizeinference: 1 evaluationimgpath: '/path/to/testrecording.tif' evaluationroifolder: '/path/to/testroiset' stimulationframes: [100,200] response_patience: 5 ```

Here's a table explaining the grid search configuration parameters:

| Parameter | Description | Example Value | | ----------------------- | ------------------------------------------------------------------------- | ------------------------------------- | | modelfolder | Directory where the trained models will be saved | /path/to/save_trained_models | | train_h5 | Path to the H5 file containing the training data | /path/to/training_data.h5 | | batch_size | Number of training examples used in one iteration | 64 | | learning_rate | Rate at which the model's weights are updated during training | 0.0001 | | loss_functions | List of loss functions to be used during training | ['L1', 'Smooth-L1', 'MSE', 'Huber'] | | noise_scales | List of noise scales to be applied to the input data during training | [0.5, 1.0, 1.5, 2.0, 3.0] | | noise_centers | List of noise centers to be applied to the input data during training | [0, 0.5, 1.0] | | gaussian_filter | List indicating whether to apply a Gaussian filter to the ytrain data | [True, False] | | `gaussiansigma| List of sigma values for the Gaussian filter |[0.5, 1.0]| |numepochs| Number of times the entire training dataset is passed through the network |1| |batchsizeinference| Batch size used during inference |1| |evaluationimgpath| Path to the image used for evaluation |/path/to/testrecording.tif| |evaluationroifolder| Path to the folder containing regions of interest (ROI) for evaluation |/path/to/testroiset| |stimulationframes| List of frame numbers where stimulation occurs |[100, 200]| |responsepatience| Number of frames to wait for a response after a stimulation frame |5` |

Once the config file for the gridsearch is set, it can be started by using the command:

bash python -m neuroimage_denoiser gridsearch_train --trainconfigpath <path>

The gridsearch will save its results to a JSON file.

Utils

Filter h5-file

We've included a convinience function to filter the h5-file with a new z-score, in case you've selected a lot of frames that do not have responses due to a insufficient z-score.

| Flag | Shorthand | Description | | ----------- | --------- | ------------------------------------ | | --h5 | | Path to the input H5 file | | --outputh5 | -o | Path to the output H5 file | | --minz | -z | Minimum Z value for filtering | | --roi_size | -r | Size of the Region of Interest (ROI) |

Example

bash python -m neuroimage_denoiser filter_h5 -i /path/to/input.h5 -o /path/to/output.h5 --min_z 3.0 --roi_size 6

Evaluate Inference Speed

The script evaluates the inference speed of Neuroimage Denoiser for image denoising across different crop sizes. It begins by cropping image sequences to specified sizes and then performs model inference, measuring the time taken for each operation. Results are saved in a JSON file, providing a performance benchmark for varying image dimensions.

bash python -m neuroimage_denoiser eval_inference_speed --path <path> --modelpath <model_path> --cropsizes <sizes> --num_frames <num> --outpath <output_path>

| Argument | Shorthand | Description | Required | Example Value | | -------------- | --------- | ------------------------------------------------------ | -------- | ------------------------ | | --path | -p | Path to folder containing images | Yes | /path/to/images | | --modelpath | -m | Path to model weights | Yes | /path/to/model_weights | | --cropsizes | -c | List of crop sizes to test | Yes | 32 64 128 | | --num_frames | -n | Number of frames to test | Yes | 100 | | --outpath | -o | Path to save result | Yes | /path/to/save/results | | --cpu | | Force CPU usage, even if a GPU is available (optional) | No | |

How to Cite

Neuroimage Denoiser for removing noise from transient fluorescent signals in functional imaging. Stephan Weissbach, Jonas Milkovits, Michela Borghi, Carolina Amaral, Abderazzaq El Khallouqi, Susanne Gerber, Martin Heine bioRxiv 2024.06.08.598061; doi: https://doi.org/10.1101/2024.06.08.598061