API

deepCR: Deep Learning Based Cosmic Ray Removal for Astronomical Images

Apply a learned DL model to a 2d numpy array to remove cosmic rays.

Code which accompanies the paper: Zhang & Bloom (2019)

See https://github.com/profjsb/deepCR

class deepCR.deepCR(mask='ACS-WFC-F606W-2-32', inpaint=None, device='CPU', hidden=32)[source]

Bases: object

clean(img0, threshold=0.5, inpaint=True, binary=True, segment=False, patch=256, parallel=False, n_jobs=-1)[source]
Identify cosmic rays in an input image, and (optionally) inpaint with the predicted cosmic ray mask
Parameters:img0 – (np.ndarray) 2D input image conforming to model requirements. For HST ACS/WFC, must be from

_flc.fits and in units of electrons in native resolution. :param threshold: (float; [0, 1]) applied to probabilistic mask to generate binary mask :param inpaint: (bool) return clean, inpainted image only if True :param binary: return binary CR mask if True. probabilistic mask if False :param segment: (bool) if True, segment input image into chunks of patch * patch before performing CR rejection.

Used for memory control.
Parameters:
  • patch – (int) Use 256 unless otherwise required. if segment==True, segment image into chunks of patch * patch.
  • parallel – (bool) run in parallel if True and segment==True
  • n_jobs – (int) number of jobs to run in parallel, passed to joblib. Beware of memory overflow for larger n_jobs.
Returns:

CR mask and (optionally) clean inpainted image

clean_(img0, threshold=0.5, inpaint=True, binary=True)[source]
given input image return cosmic ray mask and (optionally) clean image mask could be binary or probabilistic
Parameters:
  • img0 – (np.ndarray) 2D input image
  • threshold – for creating binary mask from probabilistic mask
  • inpaint – return clean image only if True
  • binary – return binary mask if True. probabilistic mask otherwise.
Returns:

CR mask and (optionally) clean inpainted image

clean_large(img0, threshold=0.5, inpaint=True, binary=True, patch=256)[source]
given input image return cosmic ray mask and (optionally) clean image mask could be binary or probabilistic
Parameters:
  • img0 – (np.ndarray) 2D input image
  • threshold – for creating binary mask from probabilistic mask
  • inpaint – return clean image only if True
  • binary – return binary mask if True. probabilistic mask otherwise.
Returns:

mask or binary mask; or None if internal call

clean_large_parallel(img0, threshold=0.5, inpaint=True, binary=True, patch=256, n_jobs=-1)[source]
given input image return cosmic ray mask and (optionally) clean image mask could be binary or probabilistic
Parameters:
  • img0 – (np.ndarray) 2D input image
  • threshold – for creating binary mask from probabilistic mask
  • inpaint – return clean image only if True
  • binary – return binary mask if True. probabilistic mask otherwise.
  • patch – (int) Use 256 unless otherwise required. patch size to run deepCR on.
  • n_jobs – (int) number of jobs to run in parallel, passed to joblib. Beware of memory overflow for larger n_jobs.
Returns:

CR mask and (optionally) clean inpainted image

inpaint(img0, mask)[source]
inpaint img0 under mask
Parameters:
  • img0 – (np.ndarray) input image
  • mask – (np.ndarray) inpainting mask
Returns:

inpainted clean image

class deepCR.train(image, mask, ignore=None, sky=None, aug_sky=[0, 0], name='model', hidden=32, gpu=False, epoch=50, batch_size=16, lr=0.005, auto_lr_decay=True, lr_decay_patience=4, lr_decay_factor=0.1, save_after=100000.0, plot_every=10, verbose=True, use_tqdm=False, use_tqdm_notebook=False, directory='./')[source]

Bases: object

backward_network()[source]
load(filename)[source]

Continue training from a previous model state saved to filename :param filename: (str) filename (without “.pth”) to load model state :return: None

optimize_network(dat)[source]
plot_example()[source]
plot_loss()[source]

plot validation loss vs. epoch :return: None

save()[source]

save trained network parameters to date_model_name_epoch*.pth :return: None

set_input(img0, mask, ignore)[source]
Parameters:
  • img0 – input image
  • mask – CR mask
  • ignore – loss mask
Returns:

None

set_to_eval()[source]
train()[source]

call this function to start training network :return: None

train_continue(epochs)[source]
train_initial(epochs)[source]
validate_mask()[source]
Returns:validation loss. print TPR and FPR at threshold = 0.5.
deepCR.roc(model, image, mask, ignore=None, thresholds=array([0.001, 0.003, 0.005, 0.007, 0.009, 0.011, 0.013, 0.015, 0.017, 0.019, 0.021, 0.023, 0.025, 0.027, 0.029, 0.031, 0.033, 0.035, 0.037, 0.039, 0.041, 0.043, 0.045, 0.047, 0.049, 0.051, 0.053, 0.055, 0.057, 0.059, 0.061, 0.063, 0.065, 0.067, 0.069, 0.071, 0.073, 0.075, 0.077, 0.079, 0.081, 0.083, 0.085, 0.087, 0.089, 0.091, 0.093, 0.095, 0.097, 0.099, 0.101, 0.103, 0.105, 0.107, 0.109, 0.111, 0.113, 0.115, 0.117, 0.119, 0.121, 0.123, 0.125, 0.127, 0.129, 0.131, 0.133, 0.135, 0.137, 0.139, 0.141, 0.143, 0.145, 0.147, 0.149, 0.151, 0.153, 0.155, 0.157, 0.159, 0.161, 0.163, 0.165, 0.167, 0.169, 0.171, 0.173, 0.175, 0.177, 0.179, 0.181, 0.183, 0.185, 0.187, 0.189, 0.191, 0.193, 0.195, 0.197, 0.199, 0.201, 0.203, 0.205, 0.207, 0.209, 0.211, 0.213, 0.215, 0.217, 0.219, 0.221, 0.223, 0.225, 0.227, 0.229, 0.231, 0.233, 0.235, 0.237, 0.239, 0.241, 0.243, 0.245, 0.247, 0.249, 0.251, 0.253, 0.255, 0.257, 0.259, 0.261, 0.263, 0.265, 0.267, 0.269, 0.271, 0.273, 0.275, 0.277, 0.279, 0.281, 0.283, 0.285, 0.287, 0.289, 0.291, 0.293, 0.295, 0.297, 0.299, 0.301, 0.303, 0.305, 0.307, 0.309, 0.311, 0.313, 0.315, 0.317, 0.319, 0.321, 0.323, 0.325, 0.327, 0.329, 0.331, 0.333, 0.335, 0.337, 0.339, 0.341, 0.343, 0.345, 0.347, 0.349, 0.351, 0.353, 0.355, 0.357, 0.359, 0.361, 0.363, 0.365, 0.367, 0.369, 0.371, 0.373, 0.375, 0.377, 0.379, 0.381, 0.383, 0.385, 0.387, 0.389, 0.391, 0.393, 0.395, 0.397, 0.399, 0.401, 0.403, 0.405, 0.407, 0.409, 0.411, 0.413, 0.415, 0.417, 0.419, 0.421, 0.423, 0.425, 0.427, 0.429, 0.431, 0.433, 0.435, 0.437, 0.439, 0.441, 0.443, 0.445, 0.447, 0.449, 0.451, 0.453, 0.455, 0.457, 0.459, 0.461, 0.463, 0.465, 0.467, 0.469, 0.471, 0.473, 0.475, 0.477, 0.479, 0.481, 0.483, 0.485, 0.487, 0.489, 0.491, 0.493, 0.495, 0.497, 0.499, 0.501, 0.503, 0.505, 0.507, 0.509, 0.511, 0.513, 0.515, 0.517, 0.519, 0.521, 0.523, 0.525, 0.527, 0.529, 0.531, 0.533, 0.535, 0.537, 0.539, 0.541, 0.543, 0.545, 0.547, 0.549, 0.551, 0.553, 0.555, 0.557, 0.559, 0.561, 0.563, 0.565, 0.567, 0.569, 0.571, 0.573, 0.575, 0.577, 0.579, 0.581, 0.583, 0.585, 0.587, 0.589, 0.591, 0.593, 0.595, 0.597, 0.599, 0.601, 0.603, 0.605, 0.607, 0.609, 0.611, 0.613, 0.615, 0.617, 0.619, 0.621, 0.623, 0.625, 0.627, 0.629, 0.631, 0.633, 0.635, 0.637, 0.639, 0.641, 0.643, 0.645, 0.647, 0.649, 0.651, 0.653, 0.655, 0.657, 0.659, 0.661, 0.663, 0.665, 0.667, 0.669, 0.671, 0.673, 0.675, 0.677, 0.679, 0.681, 0.683, 0.685, 0.687, 0.689, 0.691, 0.693, 0.695, 0.697, 0.699, 0.701, 0.703, 0.705, 0.707, 0.709, 0.711, 0.713, 0.715, 0.717, 0.719, 0.721, 0.723, 0.725, 0.727, 0.729, 0.731, 0.733, 0.735, 0.737, 0.739, 0.741, 0.743, 0.745, 0.747, 0.749, 0.751, 0.753, 0.755, 0.757, 0.759, 0.761, 0.763, 0.765, 0.767, 0.769, 0.771, 0.773, 0.775, 0.777, 0.779, 0.781, 0.783, 0.785, 0.787, 0.789, 0.791, 0.793, 0.795, 0.797, 0.799, 0.801, 0.803, 0.805, 0.807, 0.809, 0.811, 0.813, 0.815, 0.817, 0.819, 0.821, 0.823, 0.825, 0.827, 0.829, 0.831, 0.833, 0.835, 0.837, 0.839, 0.841, 0.843, 0.845, 0.847, 0.849, 0.851, 0.853, 0.855, 0.857, 0.859, 0.861, 0.863, 0.865, 0.867, 0.869, 0.871, 0.873, 0.875, 0.877, 0.879, 0.881, 0.883, 0.885, 0.887, 0.889, 0.891, 0.893, 0.895, 0.897, 0.899, 0.901, 0.903, 0.905, 0.907, 0.909, 0.911, 0.913, 0.915, 0.917, 0.919, 0.921, 0.923, 0.925, 0.927, 0.929, 0.931, 0.933, 0.935, 0.937, 0.939, 0.941, 0.943, 0.945, 0.947, 0.949, 0.951, 0.953, 0.955, 0.957, 0.959, 0.961, 0.963, 0.965, 0.967, 0.969, 0.971, 0.973, 0.975, 0.977, 0.979, 0.981, 0.983, 0.985, 0.987, 0.989, 0.991, 0.993, 0.995, 0.997, 0.999]))[source]

evaluate model on test set with the ROC curve

Parameters:
  • model – deepCR object
  • image – np.ndarray((N, W, H)) image array
  • mask – np.ndarray((N, W, H)) CR mask array
  • ignore – np.ndarray((N, W, H)) bad pixel array incl. saturation, etc.
  • thresholds – np.ndarray(N) FPR grid on which to evaluate ROC curves
Returns:

np.ndarray(N), np.ndarray(N): TPR and FPR