deepCR 0.1.4

deepCR: Deep Learning Based Cosmic Ray Removal for Astronomical Images

Identify and remove cosmic rays from astronomical images using trained convolutional neural networks.

This is the installable package which implements the methods described in the paper: Zhang & Bloom (2019), submitted.

Code to reproduce benchmarking results in the paper is at: https://github.com/kmzzhang/deepCR-paper

If you use this package, please cite Zhang & Bloom (2019): url TBA

Installation

pip install deepCR

Or you can install from source:

git clone https://github.com/profjsb/deepCR.git
cd deepCR/
python setup.py install

Quick Start

With Python >=3.5:

from deepCR import deepCR
from astropy.io import fits
image = fits.getdata("example_flc.fits")

# create an instance of deepCR with specified model configuration
mdl = deepCR(mask="ACS-WFC-F606W-2-32",
	     inpaint="ACS-WFC-F606W-3-32",
             device="CPU")

# apply to input image
mask, cleaned_image = mdl.clean(image, threshold = 0.5)
# visualize those outputs to choose an adequate threshold
# note that deepCR-inpaint would be inaccurate if mask does not fully cover CR

# if you only need CR mask you may skip image inpainting for shorter runtime
mask = mdl.clean(image, threshold = 0.5, inpaint=False)

# if you want probabilistic cosmic ray mask instead of binary mask
prob_mask = mdl.clean(image, binary=False)

To reduce memory consumption (recommended for images larger 0.5 Mpix), you can tell deepCR to segment the input image into 256*256 patches, and process one patch at a time.

mask, cleaned_image = mdl.clean(image, threshold = 0.5, segment = True)
mask = mdl.clean(image, threshold = 0.5, segment = True)

Currently available models

mask:

ACS-WFC-F606W-2-4

ACS-WFC-F606W-2-32(*)

inpaint:

ACS-WFC-F606W-2-32

ACS-WFC-F606W-3-32(*)

Recommended models are marked in (*). Larger number indicate larger capacity and better performance.

Input images should come from _flc.fits files which are in units of electrons.

API Documentation

Full documentation is under development at: https://deepcr.readthedocs.io/en/latest/deepCR.html

Limitations and Caveats

In the current release, the included models have been trained and tested only on Hubble Space Telescope (HST) ACS/WFC images in the F606W filter. They may work well on nearby ACS/WFC filters, though users should exert caution.

The ACS/WFC models are not expected to work optimally on other HST detectors, though we'd be interested to know if you find additional use cases for them.

Contributing

We are very interested in getting bug fixes, new functionality, and new trained models from the community (especially for ground-based imaging and spectroscopy). Please fork this repo and issue a PR with your changes. It will be especially helpful if you add some tests for your changes.