napari-lattice 0.1.7

Napari plugin to process and analyze lattice lightsheet data especially from the Zeiss lattice lightsheet. It can also be used for lattice lightsheet data acquired at different angles. The plugin can be used in batchmode without napari.

napari-lattice

This napari plugin allows deskewing, cropping, visualisation and analysis of lattice lightsheet data skewed in the Y plane (Zeiss Lattice Lightsheet). Support will eventually be for other types of data.

---

This napari plugin was generated with Cookiecutter using @napari's cookiecutter-napari-plugin template.

Installation

1. Use a conda environment for installation. You will need Anaconda Navigator or a lighter version Miniconda installed. Click on the Anaconda prompt or terminal and create an environment first:

    conda create -n napari-lattice python=3.9
   

2. You can use any name instead of "llsz". Once an environment is created, activate it by typing with the name you used:

    conda activate napari-lattice
   

3. Start with installing pyopencl

    conda install -c conda-forge pyopencl
   

   If you have trouble installing pyopencl on Windows, use a precompiled wheel from here. As we use python 3.9, you have to download and try the wheels which have cp39 in their name. For example, if we download pyopencl‑2022.1‑cp39‑cp39‑win_amd64.whl, then we navigate to the download folder and run:

    pip install pyopencl‑2022.1‑cp39‑cp39‑win_amd64.whl
   

   If this version doesn't work, try pyopencl‑2021.2.9+cl12‑cp39‑cp39‑win_amd64.whl

4. You need to install napari first. Once napari is installed, to install latest version of the napari_lattice plugin, by typing the following command in the terminal :

    pip install git+https://github.com/BioimageAnalysisCoreWEHI/napari_lattice.git
   

The plugin will be made available by napari-> Install/Uninstall Plugins soon.

5. If you have an NVIDIA graphics card, you can make deconvolution fast by installing Talley Lamberts' library pycudadecon.

    conda install -c conda-forge pycudadecon
   

Check the pycudadecon github page if you're having trouble with installation.

---

Features

All transformations are now powered by clesperanto.

Functions:

• Deskewing and deconvolution of Zeiss lattice lightsheet images
  • Ability to preview deskewed image at channel or timepoint of interest
• Crop and deskew only a small portion of the image
• You can import ROIs created in ImageJ into the plugin for cropping
• Create image processing workflows using napari-workflows and apply them to lattice lightsheet data
• Run napari_lattice from the terminal

---

Usage

Once installed, just start napari and the plugin should be under "Plugins" tab

Note that channels and timepoints start from 0.

**File compatibility

• You can directly open a Zeiss lattice file by dragging the file into napari.
• You will get a prompt to Choose Reader. Select aicsimageio-out-of-memory for large datasets that don't fit in memory.
• If the channels are split into different layers, press Shift and select all the channels. Right click on the highlighted layers and then click Merge to stack.
• Once image has loaded, click Initialize Plugin. If its a czi file, it will load voxel size from the metadata. Once the button turns green, it means the plugin is initialized

Deskewing

To preview the deskewed output of a single timepoint and channel, choose the layer under the box img data, enter the timepoint and channel of interest and click Preview. You can see the status of the processing in the terminal. Once finished, you will see a deskewed image and the corresponding maximum intensity projection as two layers.

To deskew and save a range of timepoints and channels, select the Deskew tab. Choose the channel and time ranges, save directory and click Save. You can also select to save as tif or h5. Tif will save as individual timepoints, h5 will be a single file using default chunk size and gzip compression.

Deconvolution

To perform deconvolution (Richardson Lucy), you will need the PSFs. We have provided simulated PSFs for the Zeiss lattice lightsheet generated by Zen software here. Tick Deconvolution and then click the box Click to Select PSFs for deconvolution. You can choose a multichannel psf image in the first box or choose psfs for each channel. The order of the PSFs must follow the order of the image channels. To run deconvolution really fast, under Choose processing device, select cuda_gpu, which will use pycudadecon library for deconvolution. The cpu options uses Richardson-Lucy algorithm from scikit-image library.

Cropping

• Click on the Crop & Deskew tab.
• Clicking on Click to activate Cropping Preview will activate the Import ImageJ ROI and Crop Preview buttons. This will also add a shapes layer for the ROIs or shapes.

Crop & Deskew (initial)	Crop & Deskew (Activated)

• For cropping regions of interest on the deskewed image, you can either:
  • draw the regions using shapes layer in napari AND/OR
  • import ImageJ ROIs an ImageJ ROI file (.zip).
• You can use a combination of shapes and ImageJ ROIs if needed.
• To preview the cropped image, select the ROI and then click Crop Preview.

Note: The cropping functionality works by finding the inverse transform of the ROI from the deskewed image and extracting the corresponding data from the skewed or raw image. Only the extracted portion will be deskewed. This saves time and is low on memory compared to deskewing the entire image and then cropping. You can select the range of channels and time poitns you'd like to crop and save under Crop and Save Data section.

Workflow

This section uses napari-workflows to implement custom image processing routines on lattice lightsheet datasets. You can create a custom workflow using napari-assistant and save it. This can then be loaded into the napari_lattice plugin under the Workflow tab which can then be applied to the deskewed output.

If you'd like to use the shapes layer for cropping and applying a workflow, tick Crop Data checkbox. This will crop the data and then apply the workflow.

You can also use custom python functions with workflows. The function needs to be called within the workflow yml file and the custom function should be a .py file in the same directory as the workflow file. An example will be added soon.

More details will be added soon.

---

Batch processing (No GUI)

The software can also be used to batch process data in a folder. To run the program, you will have to open a terminal and make sure your environment is activated using conda activate. To see a list of options, you type napari_lattice -h . The -h means help and will print out a list of options on how to run the program. Currently, the available options are:

    usage: napari_lattice [-h] --input INPUT --output OUTPUT [--skew_direction SKEW_DIRECTION] [--deskew_angle DESKEW_ANGLE] --processing PROCESSING [--deconvolution DECONVOLUTION][--deconvolution_num_iter DECONVOLUTION_NUM_ITER] [--deconvolution_psf DECONVOLUTION_PSF [DECONVOLUTION_PSF ...]] [--roi_file ROI_FILE] [--channel CHANNEL] [--voxel_sizes VOXEL_SIZES] [--file_extension FILE_EXTENSION] [--time_range TIME_RANGE TIME_RANGE] [--channel_range CHANNEL_RANGE CHANNEL_RANGE] [--workflow_path WORKFLOW_PATH] [--output_file_type OUTPUT_FILE_TYPE]

    Lattice Data processing
    arguments:

    required:
    --input INPUT         Enter input file
    --output OUTPUT       Enter save folder
    --processing PROCESSING
                          Enter the processing option: deskew, crop, workflow or workflow_crop
    
    optional arguments:
    -h, --help            show this help message and exit

    --skew_direction SKEW_DIRECTION
                            Enter the direction of skew (default is Y)
    --deskew_angle DESKEW_ANGLE
                            Enter the deskew angle (default is 30)
    --deconvolution DECONVOLUTION
                            Specify the device to use for deconvolution. Options are cpu or cuda_gpu (Requires an NVIDIA graphics card and pycudadecon to be installed)
    --deconvolution_num_iter DECONVOLUTION_NUM_ITER
                            Enter the number of iterations to run Richardson-Lucy deconvolution (default is 10)
    --deconvolution_psf DECONVOLUTION_PSF [DECONVOLUTION_PSF ...]
                            Enter paths to psf file/s separated by commas or you can enter each path with double quotes
    --roi_file ROI_FILE   Enter the path to the ROI file for performing cropping (only valid for -processing where crop or workflow_crop is specified
    --voxel_sizes VOXEL_SIZES
                            Enter the voxel sizes as (dz,dy,dx). Make sure they are in brackets
    --file_extension FILE_EXTENSION
                            If choosing a folder, enter the extension of the files (make sure you enter it with the dot at the start, i.e., .czi or .tif), else .czi and .tif files will be used
    --time_range TIME_RANGE TIME_RANGE
                            Enter time range to extract, default will be entire timeseries if no range is specified. For example, 0 9 will extract first 10 timepoints
    --channel_range CHANNEL_RANGE CHANNEL_RANGE
                            Enter channel range to extract, default will be all channels if no range is specified. For example, 0 1 will extract first two channels.
    --workflow_path WORKFLOW_PATH
                            Enter path to the workflow file '.yml
    --output_file_type OUTPUT_FILE_TYPE
                            Save as either tif or h5, defaults to tif
    --channel CHANNEL     If input is a tiff file and there are channel dimensions but no time dimensions, choose as True

As an example, if you would like to deskew a bunch of files in a folder, you would need to define the input folder, save location and processing option (deskew). The skew direction by default is Y and deskew angle is 30.

If the input folder is:

C:\source

and output or save location is:

C:\deskewed

then you run the command,

napari_lattice --input "C:\source" --output "C:\deskewed" --processing deskew

Note that the folder locations are in quotes. This is useful especially if you have spaces in the folder names.

If you'd like to run cropping and deskew and have a list of ImageJ ROI files (.zip) files which are located at, say D:\rois and the folder locations are the same as above, then we can use the command:

napari_lattice --input "C:\source" --output "C:\deskewed" --roi_file "D:\rois" --processing crop

Note: The ROI files need to have the same name as the image files.

You can also replace the input, output, and roi_file arguments with file locations instead of folders.

Please find sample data for testing in the sample_data folder above

Data Credit: Cindy Evelyn & Niall Geoghegan, Walter and Eliza Hall Institute of Medical Research, Melbourne, Australia

Contributing

Contributions are very welcome. Tests can be run with tox, please ensure the coverage at least stays the same before you submit a pull request.

License

======= Distributed under the terms of the [GPL-3.0 License] license, "napari_lattice" is free and open source software

Acknowledgment

This project was supported by funding from the Rogers Lab at the Centre for Dynamic Imaging at the Walter and Eliza Hall Institute of Medical Research. This project has been made possible in part by Napari plugin accelerator grant from the Chan Zuckerberg Initiative DAF, an advised fund of the Silicon Valley Community Foundation.

Issues

If you encounter any problems, please [file an issue] along with a detailed description.