ClaRAN: A deep learning classifier for radio morphologies
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
data/RGZdevkit2017/RGZ2017/ImageSets/Main
experiments
lib
tools
.gitignore
LICENSE
README.md
requirements.txt

README.md

ClaRAN

Radio Galaxy Zoo: ClaRAN - A Deep Learning Classifier for Radio Morphologies

ClaRAN - Classifying Radio sources Automatically with Neural networks - is a proof-of-concept radio source morphology classifier based upon the Faster Region-based Convolutional Neutral Network (Faster R-CNN). ClaRAN is the first publicly available radio source morphology classifier that is capable of associating discrete and extended components of radio sources in an automated fashion. ClaRAN demonstrates the feasibility of applying deep learning methods for cross-matching complex radio sources of multiple components with infrared maps. The promising results from ClaRAN have implications for the further development of efficient cross-wavelength source identification, matching, and morphology classifications for future radio surveys.

ClaRAN replaces the original RoI cropping layer with the Spatial Transformer Network (STN) pooling to support a fully end-to-end training pipeline. An unexpected benefit of this is that the code also runs on laptops that may not have GPUs (with a much longer latency of course --- e.g. 6 seconds compared to 100s of milliseconds per image).

Requirements

The code requires Tensorflow 1.0 or above, python 2.7 as well as the following python libraries:

  • matplotlib
  • numpy
  • opencv-python
  • scipy
  • cython
  • easydict
  • astropy
  • Pillow
  • pyyaml

Those modules can be installed using: pip install -U pip followed by pip install -r requirements.txt. It is highly recommended to setup a standalone python virtual environment to install these modules and run the code.

The code requires at least 3 GB of disk space (to store images and pre-trained models) and 3GB of RAM during training. For GPU training, this means the size of the device RAM is at least 3 GB.

Setup

  1. Clone this repository: git clone https://github.com/chenwuperth/rgz_rcnn.git
  2. Compile: cd lib and make. This should compile a bunch of Cython/C code (for bounding box calculation), and will produce the dynamic libraries under both CPUs and GPUs (if available).
  3. Download RGZ Data: cd tools and run python download_data.py. This will download data and RGZ model for training, testing, and demo.

Tutorial

Getting started

Run: cd tools and python demo.py --radio ../data/rgzdemo/FIRSTJ011349.0+065025.fits --ir ../data/rgzdemo/FIRSTJ011349.0+065025_infrared.png to detect a multi-component radio galaxy! Some examples of demo output are shown below:

Each detected box denotes an identified radio source, and its morphology is succinctly labelled as X C_Y P, where X and Y denotes the number of radio components and the number of radio peaks respectively. Each morphology label is also associated with a score between 0 and 1, indicating the probability of a morphology class being present.

Run: cd experiments/scripts and bash example_test_cpu.sh to evaluate the RGZ model on 4603 images on your laptop using CPUs only. Please change the RGZ_RCNN environment variable in the script accordingly. The output records the Average Precision for each class and the overall mean AP for the D4 method.

Morphology Classes AP
1C_1P 0.8784
1C_2P 0.7074
1C_3P 0.8941
2C_2P 0.8200
2C_3P 0.7916
3C_3P 0.9269
mAP 83.6%

Run: cd experiments/scripts and sbatch example_train_slurm.sh to train your own RGZ model on GPU node managed by the SLURM job scheduler. You will need to change resources, paths, and module names based on the configuration of your own cluster.

Questions?

Feel free to open an issue to discuss any questions not covered so far.

Citation

If you benefit from this code, please cite our paper:

@article{doi:10.1093/mnras/sty2646,
author = {Wu, Chen and Wong, Oiwei Ivy and Rudnick, Lawrence and Shabala, Stanislav S and Alger, Matthew J and Banfield, Julie K and Ong, Cheng Soon and White, Sarah V and Garon, Avery F and Norris, Ray P and Andernach, Heinz and Tate, Jean and Lukic, Vesna and Tang, Hongming and Schawinski, Kevin and Diakogiannis, Foivos I},
title = {Radio Galaxy Zoo: ClaRAN – a deep learning classifier for radio morphologies},
journal = {Monthly Notices of the Royal Astronomical Society},
volume = {482},
number = {1},
pages = {1211-1230},
year = {2019},
doi = {10.1093/mnras/sty2646},
URL = {http://dx.doi.org/10.1093/mnras/sty2646}
}

Acknowledgement

The initial codebase was built on the awesome Faster-RCNN_TF project.