BrainSec

Automated Grey and White Matter Segmentation in Digitized Aβ Human Brain Tissue WSI. This is the implementation details for the paper: Z. Lai, L. Cerny Oliveira, R. Guo, W. Xu, Z. Hu, K. Mifflin, C. DeCarlie, S-C. Cheung, C-N. Chuah, and B. N. Dugger, "BrainSec: Automated Brain Tissue Segmentation Pipeline for Scalable Neuropathological Analysis," IEEE Access, 2022.

Authors / Contributors

• Runlin Guo
• Wenda Xu
• Zhengfeng Lai

If you have any questions/suggestions or find any bugs, please submit a GitHub issue.

Prerequisites

The list of prerequisites for building and running this repository is described below. It is guaranteed to run out-of-the-box on the configuration below. Otherwise, some trial-and-error processes might involve.

• Ubuntu 16.04/18.04 on AMD64 CPU
• System RAM >= 128 GB (less might be okay depending on usage)
• NVIDIA GPU with CUDA version >= 10.1
• Docker version >= 19.03, API >= 1.40
• nvidia-container-toolkit (previously known as nvidia-docker)

Command to test if all prerequisites are met:
sudo docker run -it --rm --gpus all ubuntu nvidia-smi

Setup Instructions

bash ./setup.sh
You should be greeted by the Docker container brainseg when this script finishes. The working directory is /BrainSeg which is where the repo is mounted at.

Port allocations

• Jupyter notebook: 9000
• TensorBoard: 6006

Repo Directory Structure

• docker/ - Dockerfiles
• install/ - Python third-party libraries requirements
• notebook/ - Jupyter notebooks including those from plaquebox-paper (original repo). Some special ones are:
  • Grad-CAM.ipynb - Grad-CAM visualization for TensorFlow2.
  • Mask_Accuracy_Benchmark_Plotting.ipynb - Mask accuracy plotting for nice-looking graphs using .csv files from compute_mask_accuracy.py.
  • PowerAnalysis.ipynb - Power analysis.
  • TensorBoard_Plotting.ipynb - Replot TensorBoard data to nice-looking graphs.
• qupath/ - QuPath tracing scripts for generating groundtruth masks. Brief tutorial can be found here.
• src/ - Source code
  • gSLICr/ - gSLICr (GPU-based SLIC implementation) repo with added support for SLICO and CUDA unified memory. Building instruction can be found in setup.sh.
  • networks/ - Network related code
    • models/ - various network model implementations
      • FCN.py - FCN Model
      • UNet.py - UNet Model
      • models.py - top-level model selection
    • dataset.py - Dataset related functions/classes.
    • losses.py - Custom losses based on tf.keras.losses.
    • metrics.py - Custom metrics based on tf.keras.metrics.
  • utils/ - Utility functions
    • color_deconv.py - Color deconvolution (color space transformation) from RGB space to stain color space.
    • compute_mask_accuracy.py - Evaluate mask accuracy using various metrics. Implemented metrics can be found via ./compute_mask_accuracy.py -h
    • numpy_pil_helper.py - Conversion functions between NumPy and PIL.
    • separate_tissue.py - Separates tissue from background using traditional image processing techniques with gSLICr.
    • svs_to_png.py - Convert .svs WSI to .png images via tiling.
  • image_helper.py - Image helper scripts including commonly used functions like grayscale_to_binary, get_thumbnails, combine_truth_binary, and resize_to_original.
  • postproc.py - Post-processing script
  • predict.py - Predicting script for trained network inferencing
  • tissue_seg.py - Tissue separation script which calls utils/separate_tissue.py iteratively over a directory of .svs WSI image. Note: manual stain estimation using QuPath is required.
  • train.py - Training script
• tests/ - Testing cases for source code using Python unittest.

Plaque quantification pipeline

• The two models are under folder /model.
• The main pipeline is in Plaque_Quantification.ipynb.

Note

In this repo, all Python scripts that are meant to be run as top-level scripts support argparse.
That is, input arguments can be specified to change the default behavior. List of input arguments and their usage instructions can be found by ./my_python_script.py -h or ./my_python_script.py <subcommand> -h.

Credit

• plaquebox-paper (original repo)
• plaquebox-paper (fork with some code dev)
• QuPath
• pyvips: Image processing for large TIFF-based image.
• gSLICr (GPU-based SLIC implementation):