updated doc and readme

README.md

@@ -3,13 +3,14 @@
 
 ## deepCR: Deep Learning Based Cosmic Ray Removal for Astronomical Images
 
-Apply a learned convolutional neural net (CNN) model to a 2d `numpy` array to identify and remove cosmic rays, on multi-core CPUs or GPUs.
+Identify and remove cosmic rays from astronomical images using trained convolutional neural networks. Fast on both CPU and GPU.
+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): www.arxiv.org/XXX
+This repo is under active development.
 
 <img src="https://raw.githubusercontent.com/profjsb/deepCR/master/imgs/postage-sm.jpg" wdith="90%">
 
-
-This is the installable package which implements the methods described in the paper: Zhang & Bloom (2019), submitted. Code to benchmark the model and to generate figures and tables in the paper can be found in the deepCR-paper Github repo: https://github.com/kmzzhang/deepCR-paper
-
 ### Installation
 
 ```bash
@@ -31,21 +32,28 @@ With Python >=3.5:
 ```python
 from deepCR import deepCR
 from astropy.io import fits
-
-image = fits.getdata("*********_flc.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-2-32",
-             device="GPU")
+	         inpaint="ACS-WFC-F606W-3-32",
+             device="CPU")
+# apply to input image
+# you should examine cleaned_image to verify that proper threshold is used
 mask, cleaned_image = mdl.clean(image, threshold = 0.5)
+
+# for quicker mask prediction, skip image inpainting
+mask = mdl.clean(image, threshold = 0.5, inpaint=False)
+
+# for probabilistic cosmic ray mask (instead of binary mask)
+prob_mask = mdl.clean(image, binary=False)
 ```
-Note:
-Input image must be in units of electrons
 
-To reduce memory consumption (recommended for image larger than 1k x 1k):
+To reduce memory consumption (recommended for image larger than 1k x 1k), deepCR could segment input image to smaller patches of seg*seg, perform CR rejection one by one, and stitch the outputs back to original size. Runtime does not increase by much.
 ```python
 mask, cleaned_image = mdl.clean(image, threshold = 0.5, seg = 256)
+mask = mdl.clean(image, threshold = 0.5,  seg = 256)
 ```
-which segments the input image into patches of 256*256, seperately perform CR rejection on the patches, before stitching back to original image size.
+We recommend using patch size (seg) no smaller than 64.
 
 ### Currently available models
 
@@ -57,17 +65,18 @@ inpaint:
     ACS-WFC-F606W-2-32
     ACS-WFC-F606W-3-32(*)
 
-The two numbers following instrument configuration specifies model size, with larger number indicating better performing model at the expense of runtime. Recommanded models are marked in (*). For benchmarking of these models, please refer to the original paper.
+Recommended models are marked in (*).
+Input images should come from _flc.fits files which are in units of electrons.
+The two numbers, e.g., 2-32, specifies model hyperparameter. Larger number indicate larger capacity and better performance.
 
 ### API Documentation
 
 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 built and tested only on Hubble Space Telescope (HST) ACS/WFC images in the F606W filter. Application to native-spatial resolution (ie. not drizzled), calibrated images from ACS/F606W (`*_flc.fits`) is expected to work well. Use of these prepackaged models in other observing modes with HST or spectroscopy is not encouraged. We are planning hosting a "model zoo" that would allow deepCR to be adapted to a wide range of instrument configurations.
+In the current release, the included models have been built and tested only on Hubble Space Telescope (HST) ACS/WFC images in the F606W filter. Applying them to other HST detectors is discouraged. Users should exert caution when applying the models to other filters of ACS/WFC.
 
 ### 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.
-

docs/deepCR.rst

@@ -1,13 +1,6 @@
 deepCR package
 ==============
 
-Subpackages
------------
-
-.. toctree::
-
-   deepCR.test
-
 Submodules
 ----------
 
@@ -19,39 +12,6 @@ deepCR.model module
    :undoc-members:
    :show-inheritance:
 
-deepCR.parts module
--------------------
-
-.. automodule:: deepCR.parts
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-deepCR.test\_par module
------------------------
-
-.. automodule:: deepCR.test_par
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-deepCR.unet module
-------------------
-
-.. automodule:: deepCR.unet
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-deepCR.util module
-------------------
-
-.. automodule:: deepCR.util
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-
 Module contents
 ---------------