Nondefaced-Detector

A framework to detect if a 3D MRI volume has been defaced.

Table of contents

• Installation
  • Container
    • GPU
    • CPU
  • Pip
• Using pre-trained networks
• Reproducibility
• Usage
• Paper
• Roadmap
• Questions or Issues
• Contributing
• License
• Contact
• Acknowledgements
  • Training Dataset
  • Built With

Installation

Container

We recommend using the latest Nondefaced-detector docker container, which includes all the dependencies required for the framework.

GPU

The Nondefaced-detector GPU supported container uses the tensorflow-gpu as its base image. Please see the official tensorflow docker install page for all of the CUDA and NVIDIA driver requirements.

$ docker pull shashankbansal56/nondefaced-detector:latest-gpu

CPU

This container can be used on most systems that have Docker/Singularity installed.

$ docker pull shashankbansal56/nondefaced-detector:latest-cpu

NOTE: The CPU container will be very slow for training. We highly recommend that you use a GPU system.

Pip

$ pip install --no-cache-dir "nondefaced-detector[cpu/gpu]"

Using pre-trained networks

Pre-trained networks are avalaible in the Nondefaced-detector models repository. Prediction can be done using the nondefaced-detector CLI or in python.

From docker container installation

$ docker run --rm -v $PWD:/data nondefaced-detector:latest-cpu \
    predict \
    --model-path="/opt/nondefaced-detector-reproducibility/pretrained_weights" \
    "/opt/nondefaced-detector-reproducibility/examples/faced/example1.nii.gz"

$ docker run --rm --gpus all -v $PWD:/data nondefaced-detector:latest-gpu \
    predict \
    --model-path="/opt/nondefaced-detector-reproducibility/pretrained_weights" \
    "/opt/nondefaced-detector-reproducibility/examples/faced/example1.nii.gz"

From pip installation

$ nondefaced-detector
Usage: nondefaced-detector [OPTIONS] COMMAND [ARGS]...

  A framework to detect if a 3D MRI Volume has been defaced.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  convert   Preprocess MRI volumes and convert to Tfrecords.
  evaluate  Evaluate a model's predictions against known labels.
  info      Return information about this system.
  predict   Predict labels from features using a trained model.

Reproducibility

Steps to reproduce inference results from the paper.

Step 1: Get the preprocessed dataset. You need to have datalad installed.

$ datalad clone https://gin.g-node.org/shashankbansal56/nondefaced-detector-reproducibility /opt/nondefaced-detector-reproducibility
$ cd /opt/nondefaced-detector-reproducibility
$ datalad get pretrained_weights/*
$ datalad get test_ixi/tfrecords/*

NOTE: To reproduce inference results from the paper, you only need to download the tfrecords.

Step 2: Depending on your system create a tensorflow-cpu/gpu virtual environment. We recommend using conda.

$ conda create -n tf-cpu tensorflow
$ conda activate tf-cpu

Step 3: Get the nondefaced-detector repo.

$ git clone https://github.com/poldracklab/nondefaced-detector.git

Step 4: Run the standalone inference script.

$ cd nondefaced-detector
$ pip install -e .
$ cd nondefaced_detector
$ python inference.py -h
usage: inference.py [-h] tfrecords_path model_path

positional arguments:
  tfrecords_path  Path to tfrecords.
  model_path      Path to pretrained model weights.

optional arguments:
  -h, --help      show this help message and exit

Usage

Get started by checking out the documentation!

Paper

You can find the pre-print on bioRxiv.

Roadmap

See the projects dashboard for a list of ongoing work and proposed features.

Questions or Issues

See the open issues for a list of known issues. If you have any questions or encounter any issues, please submit a github issue.

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

Contact

Shashank Bansal - shashankbansal56@gmail.com

Acknowledgements

Training Dataset

The original model was trained on 980 defaced MRI scans from 36 different studies that are publicly available at OpenNeuro.org

Built With

• nobrainer
• IXI Dataset