API Documentation¶

Both the Keras and TFLearn modules have similarly named functions with very similar parameters. Use the _predict_ functions to perform predictions using our trained models or a model you trained from scratch. Use the _train_ functions to train a model from scratch. Use the _tl_ functions to perform transfer learning on a previously trained model – this can be our pre-trained models or a model that you trained.

Please have a look at the Tutorials for examples of how to use these functions effectively.

Keras Module¶

The three major user oriented functions happen to be gamornet_predict_keras(), gamornet_train_keras() and gamornet_tl_keras() and are documented here. For the remainder of the functions, please have a look at the source code on GitHub.

Uses a Keras model to perform predictions on supplied images.

Parameters: img_array (Numpy ndarray [nsamples,x,y,ndim]) – The array of images on which the predictions are to be performed. We insist on numpy arrays as many of the underlying deep learning frameworks work better with numpy arrays compared to other array-like elements. model_load_path (str) – Full path to the saved Keras model. Additionally, this parameter can take the following special values SDSS_sim – Downloads and uses the GaMorNet model trained on SDSS g-band simulations at z~0 from Ghosh et. al. (2020) SDSS_tl – Downloads and uses the GaMorNet model trained on SDSS g-band simulations and real data at z~0 from Ghosh et. al. (2020) CANDELS_sim – Downloads and uses the GaMorNet model trained on CANDELS H-band simulations at z~1 from Ghosh et. al. (2020) CANDELS_tl – Downloads and uses the GaMorNet model trained on CANDELS H-band simulations and real data at z~1 from Ghosh et. al. (2020) input_shape (tuple of ints (x, y, ndim) or allowed str) – The shape of the images being used in the form of a tuple. This parameter can also take the following special values:- SDSS - Sets the input shape to be (167,167,1) as was used for the SDSS g-band images in Ghosh et. al. (2020) CANDELS - Sets the input shape to be (83,83,1) as was used for the CANDELS H-band images in Ghosh et. al. (2020) batch_size (int) – This variable specifies how many images will be processed in a single batch. Set this value to lower than the default if you have limited memory availability. This doesn’t affect the predictions in any way. individual_arrays (bool) – If set to True, this will unpack the three returned arrays predicted probabilities – The returned array consists of the probability for each galaxy to be disk-dominated, indeterminate and bulge-dominated respectively [disk_prob, indet_prob, bulge_prob]. If individual_arrays is set to True, the single array is unpacked and returned as three separate arrays in the same order. The ordering of individual elements in this array corresponds to the array of images fed in. array_like
gamornet.keras_module.gamornet_train_keras(training_imgs, training_labels, validation_imgs, validation_labels, input_shape, files_save_path='./', epochs=100, checkpoint_freq=0, batch_size=64, lr=0.0001, momentum=0.9, decay=0.0, nesterov=False, loss='categorical_crossentropy', load_model=False, model_load_path='./', save_model=True, verbose=1)

Trains and returns a GaMorNet model using Keras.

Parameters: training_imgs (Numpy ndarray [nsamples,x,y,ndim]) – The array of images which are to be used for the training process. We insist on numpy arrays as many of the underlying deep learning frameworks work better with numpy arrays compared to other array-like elements. training_labels (Numpy ndarray [nsamples,label_arrays]) – The truth labels for each of the training images. The supplied labels must be in the one-hot encoding format. We reproduce below what each individual label array should look like:- Disk-dominated - [1,0,0] Indeterminate - [0,1,0] Bulge-dominated - [0,0,1] validation_imgs (Numpy ndarray [nsamples,x,y,ndim]) – The array of images which are to be used for the validation process. We insist on numpy arrays as many of the underlying deep learning frameworks work better with numpy arrays compared to other array-like elements. validation_labels (Numpy ndarray [nsamples,label_arrays]) – The truth labels for each of the validation images. The supplied labels must be in the one-hot encoding format. We reproduce below what each individual label array should look like:- Disk-dominated - [1,0,0] Indeterminate - [0,1,0] Bulge-dominated - [0,0,1] input_shape (tuple of ints (x, y, ndim) or allowed str) – The shape of the images being used in the form of a tuple. This parameter can also take the following special values:- SDSS - Sets the input shape to be (167,167,1) as was used for the SDSS g-band images in Ghosh et. al. (2020) CANDELS - Sets the input shape to be (83,83,1) as was used for the CANDELS H-band images in Ghosh et. al. (2020) files_save_path (str) – The full path to the location where files generated during the training process are to be saved. This includes the metrics.csv file as well as the trained model. Set this to /dev/null on a unix system if you don’t want to save the output. epochs (int) – The number of epochs for which you want to train the model. checkpoint_freq (int) – The frequency (in terms of epochs) at which you want to save models. For eg. setting this to 25, would save the model at its present state every 25 epochs. batch_size (int) – This variable specifies how many images will be processed in a single batch. This is a hyperparameter. The default value is a good starting point lr (float or schedule) – This is the learning rate to be used during the training process. This is a hyperparameter that should be tuned during the training process. The default value is a good starting point. Instead of setting it at a single value, you can also set a schedule using keras.optimizers.schedules.LearningRateSchedule momentum (float) – The value of the momentum to be used in the gradient descent optimizer that is used to train GaMorNet. This must always be $$\geq 0$$. This accelerates the gradient descent process. This is a hyperparameter. The default value is a good starting point. decay (float) – The amount of learning rate decay to be applied over each update. nesterov (bool) – Whether to apply Nesterov momentum or not. loss (allowed str or function) – The loss function to be used. If using the string option, you need to specify the name of the loss function. This can be set to be any loss available in keras.losses load_model (bool) – Whether you want to start the training from a previously saved model. We strongly recommend using the gamornet_tl_keras function for more control over the process when starting the training from a previously saved model. model_load_path (str) – Required iff load_model == True. The path to the saved model. save_model (bool) – Whether you want to save the model in its final trained state. Note that this parameter does not affect the models saved by the checkpoint_freq parameter verbose ({0, 1, 2}) – The level of verbosity you want from Keras during the training process. 0 = silent, 1 = progress bar, 2 = one line per epoch. Trained Keras Model Keras Model class
gamornet.keras_module.gamornet_tl_keras(training_imgs, training_labels, validation_imgs, validation_labels, input_shape, load_layers_bools=[True, True, True, True, True, True, True, True], trainable_bools=[True, True, True, True, True, True, True, True], model_load_path='./', files_save_path='./', epochs=100, checkpoint_freq=0, batch_size=64, lr=1e-05, momentum=0.9, decay=0.0, nesterov=False, loss='categorical_crossentropy', save_model=True, verbose=1)

Performs Transfer Learning (TL) using a previously trained GaMorNet model.

Parameters: training_imgs (Numpy ndarray [nsamples,x,y,ndim]) – The array of images which are to be used for the TL process. We insist on numpy arrays as many of the underlying deep learning frameworks work better with numpy arrays compared to other array-like elements. training_labels (Numpy ndarray [nsamples,label_arrays]) – The truth labels for each of the TL images. The supplied labels must be in the one-hot encoding format. We reproduce below what each individual label array should look like:- Disk-dominated - [1,0,0] Indeterminate - [0,1,0] Bulge-dominated - [0,0,1] validation_imgs (Numpy ndarray [nsamples,x,y,ndim]) – The array of images which are to be used for the validation process. We insist on numpy arrays as many of the underlying deep learning frameworks work better with numpy arrays compared to other array-like elements. validation_labels (Numpy ndarray [nsamples,label_arrays]) – The truth labels for each of the validation images. The supplied labels must be in the one-hot encoding format. We reproduce below what each individual label array should look like:- Disk-dominated - [1,0,0] Indeterminate - [0,1,0] Bulge-dominated - [0,0,1] input_shape (tuple of ints (x, y, ndim) or allowed str) – The shape of the images being used in the form of a tuple. This parameter can also take the following special values:- SDSS - Sets the input shape to be (167,167,1) as was used for the SDSS g-band images in Ghosh et. al. (2020) CANDELS - Sets the input shape to be (83,83,1) as was used for the CANDELS H-band images in Ghosh et. al. (2020) load_layers_bools (array of bools) – This variable is used to identify which of the 5 convolutional and 3 fully-connected layers of GaMorNet will be loaded during the transfer learning process from the supplied starting model. The rest of the layers will be initialized from scratch. The order of the bools correspond to the following layer numbers [2, 5, 8, 9, 10, 13, 15, 17] in GaMorNet. Please see Figure 4 and Table 2 of Ghosh et. al. (2020) to get more details. The first five layers are the convolutional layers and the last three are the fully connected layers. This parameter can also take the following special values which are handy when you are using our models to perform predictions:- load_bools_SDSS - Sets the bools according to what was done for the SDSS data in Ghosh et. al. (2020) load_bools_CANDELS- Sets the bools according to what was done for the CANDELS data in Ghosh et. al. (2020) trainable_bools (array of bools) – This variable is used to identify which of the 5 convolutional and 3 fully-connected layers of GaMorNet will be trainable during the transfer learning process. The rest are frozen at the values loaded from the previous model. The order of the bools correspond to the following layer numbers [2, 5, 8, 9, 10, 13, 15, 17] in GaMorNet. Please see Figure 4 and Table 2 of Ghosh et. al. (2020) to get more details. The first five layers are the convolutional layers and the last three are the fully connected layers. This parameter can also take the following special values which are handy when you are using our models to perform predictions:- train_bools_SDSS - Sets the bools according to what was done for the SDSS data in Ghosh et. al. (2020) train_bools_CANDELS- Sets the bools according to what was done for the CANDELS data in Ghosh et. al. (2020) model_load_path (str) – Full path to the saved Keras model, which will serve as the starting point for transfer learning. Additionally, this parameter can take the following special values SDSS_sim – Downloads and uses the GaMorNet model trained on SDSS g-band simulations at z~0 from Ghosh et. al. (2020) SDSS_tl – Downloads and uses the GaMorNet model trained on SDSS g-band simulations and real data at z~0 from Ghosh et. al. (2020) CANDELS_sim – Downloads and uses the GaMorNet model trained on CANDELS H-band simulations at z~1 from Ghosh et. al. (2020) CANDELS_tl – Downloads and uses the GaMorNet model trained on CANDELS H-band simulations and real data at z~1 from Ghosh et. al. (2020) files_save_path (str) – The full path to the location where files generated during the training process are to be saved. This includes the metrics.csv file as well as the trained model. Set this to /dev/null on a unix system if you don’t want to save the output. epochs (int) – The number of epochs for which you want to train the model. checkpoint_freq (int) – The frequency (in terms of epochs) at which you want to save models. For eg. setting this to 25, would save the model at its present state every 25 epochs. batch_size (int) – This variable specifies how many images will be processed in a single batch. This is a hyperparameter. The default value is a good starting point lr (float or schedule) – This is the learning rate to be used during the training process. This is a hyperparameter that should be tuned during the training process. The default value is a good starting point. Instead of setting it at a single value, you can also set a schedule using keras.optimizers.schedules.LearningRateSchedule momentum (float) – The value of the momentum to be used in the gradient descent optimizer that is used to train GaMorNet. This must always be $$\geq 0$$. This accelerates the gradient descent process. This is a hyperparameter. The default value is a good starting point. decay (float) – The amount of learning rate decay to be applied over each update. nesterov (bool) – Whether to apply Nesterov momentum or not. loss (allowed str) – The loss function to be used. If using the string option, you need to specify the name of the loss function. This can be set to be any loss available in keras.losses save_model (bool) – Whether you want to save the model in its final trained state. Note that this parameter does not affect the models saved by the checkpoint_freq parameter verbose ({0, 1, 2}) – The level of verbosity you want from Keras during the training process. 0 = silent, 1 = progress bar, 2 = one line per epoch. Trained Keras Model Keras Model class

TFLearn Module¶

The three major user oriented functions happen to be gamornet_predict_tflearn(), gamornet_train_tflearn() and gamornet_tl_tflearn() and are documented here. For the remainder of the functions, please have a look at the source code on GitHub.

gamornet.tflearn_module.gamornet_predict_tflearn(img_array, model_load_path, input_shape, batch_size=64, individual_arrays=False, trainable_bools=[True, True, True, True, True, True, True, True], clear_session=False)

Uses a TFLearn model to perform predictions on supplied images.

Parameters: training_imgs (Numpy ndarray [nsamples,x,y,ndim]) – The array of images which are to be used for the training process. We insist on numpy arrays as many of the underlying deep learning frameworks work better with numpy arrays compared to other array-like elements. training_labels (Numpy ndarray [nsamples,label_arrays]) – The truth labels for each of the training images. The supplied labels must be in the one-hot encoding format. We reproduce below what each individual label array should look like:- Disk-dominated - [1,0,0] Indeterminate - [0,1,0] Bulge-dominated - [0,0,1] validation_imgs (Numpy ndarray [nsamples,x,y,ndim]) – The array of images which are to be used for the validation process. We insist on numpy arrays as many of the underlying deep learning frameworks work better with numpy arrays compared to other array-like elements. validation_labels (Numpy ndarray [nsamples,label_arrays]) – The truth labels for each of the validation images. The supplied labels must be in the one-hot encoding format. We reproduce below what each individual label array should look like:- Disk-dominated - [1,0,0] Indeterminate - [0,1,0] Bulge-dominated - [0,0,1] input_shape (tuple of ints (x, y, ndim) or allowed str) – The shape of the images being used in the form of a tuple. This parameter can also take the following special values:- SDSS - Sets the input shape to be (167,167,1) as was used for the SDSS g-band images in Ghosh et. al. (2020) CANDELS - Sets the input shape to be (83,83,1) as was used for the CANDELS H-band images in Ghosh et. al. (2020) files_save_path (str) – The full path to the location where the models generated during the training process are to be saved. The path should end with the name of the file. For eg. /path/checkpoint. This will result in model files of the form checkpoint.meta, checkpoint.data and checkpoint.index being saved. Set this to /dev/null on a unix system if you don’t want to save the file(s) epochs (int) – The number of epochs for which you want to train the model. max_checkpoints (int) – TFLearn saves the model at the end of each epoch. This parameter controls how many of the most recent models are saved. For eg. setting this to 2, will save the model state during the most recent two epochs. batch_size (int) – This variable specifies how many images will be processed in a single batch. This is a hyperparameter. The default value is a good starting point lr (float) – This is the learning rate to be used during the training process. This is a hyperparameter that should be tuned during the training process. The default value is a good starting point. momentum (float) – The value of the momentum to be used in the gradient descent optimizer that is used to train GaMorNet. This must always be $$\geq 0$$. This accelerates the gradient descent process. This is a hyperparameter. The default value is a good starting point. decay (float) – The amount of learning rate decay to be applied over each update. nesterov (bool) – Whether to apply Nesterov momentum or not. loss (allowed str or function) – The loss function to be used. If using the string option, you need to specify the name of the loss function. This can be set to be any loss available in tflearn load_model (bool) – Whether you want to start the training from a previously saved model. We strongly recommend using the gamornet_tl_tflearn function for more control over the process when starting the training from a previously saved model. model_load_path (str) – Required iff load_model == True. The path to the saved model. Note that tflearn models usually consist of three files in the format file_name.data, file_name.index, file_name.meta. For this parameter, simply specify file_path/file_name. save_model (bool) – Whether you want to save the model files at each epoch during training. This parameter should be used in conjunction with max_checkpoints to configure how many of the saved model files are preserved till the end. show_metric (bool) – Whether to display the training/testing metrics during training. clear_session (bool) – If set to True, this will clear the TensorFlow session currently running. This is handy while running GaMorNet in a notebook to avoid variable name confusions. (Sometimes, under the hood, TFLearn & Tensorflow reuse the same layer names leading to conflicts) Note that if set to True, you will lose access to any other graphs you may have run before. Trained TFLearn Model TFLearn models.dnn.DNN class
Parameters: training_imgs (Numpy ndarray [nsamples,x,y,ndim]) – The array of images which are to be used for the TL process. We insist on numpy arrays as many of the underlying deep learning frameworks work better with numpy arrays compared to other array-like elements. training_labels (Numpy ndarray [nsamples,label_arrays]) – The truth labels for each of the TL images. The supplied labels must be in the one-hot encoding format. We reproduce below what each individual label array should look like:- Disk-dominated - [1,0,0] Indeterminate - [0,1,0] Bulge-dominated - [0,0,1] validation_imgs (Numpy ndarray [nsamples,x,y,ndim]) – The array of images which are to be used for the validation process. We insist on numpy arrays as many of the underlying deep learning frameworks work better with numpy arrays compared to other array-like elements. validation_labels (Numpy ndarray [nsamples,label_arrays]) – The truth labels for each of the validation images. The supplied labels must be in the one-hot encoding format. We reproduce below what each individual label array should look like:- Disk-dominated - [1,0,0] Indeterminate - [0,1,0] Bulge-dominated - [0,0,1] input_shape (tuple of ints (x, y, ndim) or allowed str) – The shape of the images being used in the form of a tuple. This parameter can also take the following special values:- SDSS - Sets the input shape to be (167,167,1) as was used for the SDSS g-band images in Ghosh et. al. (2020) CANDELS - Sets the input shape to be (83,83,1) as was used for the CANDELS H-band images in Ghosh et. al. (2020) load_layers_bools (array of bools) – This variable is used to identify which of the 5 convolutional and 3 fully-connected layers of GaMorNet will be loaded during the transfer learning process from the supplied starting model. The rest of the layers will be initialized from scratch. The order of the bools correspond to the following layer numbers [2, 5, 8, 9, 10, 13, 15, 17] in GaMorNet. Please see Figure 4 and Table 2 of Ghosh et. al. (2020) to get more details. The first five layers are the convolutional layers and the last three are the fully connected layers. This parameter can also take the following special values which are handy when you are using our models to perform predictions:- load_bools_SDSS - Sets the bools according to what was done for the SDSS data in Ghosh et. al. (2020) load_bools_CANDELS- Sets the bools according to what was done for the CANDELS data in Ghosh et. al. (2020) trainable_bools (array of bools) – This variable is used to identify which of the 5 convolutional and 3 fully-connected layers of GaMorNet will be trainable during the transfer learning process. The rest are frozen at the values loaded from the previous model. The order of the bools correspond to the following layer numbers [2, 5, 8, 9, 10, 13, 15, 17] in GaMorNet. Please see Figure 4 and Table 2 of Ghosh et. al. (2020) to get more details. The first five layers are the convolutional layers and the last three are the fully connected layers. This parameter can also take the following special values which are handy when you are using our models to perform predictions:- train_bools_SDSS - Sets the bools according to what was done for the SDSS data in Ghosh et. al. (2020) train_bools_CANDELS- Sets the bools according to what was done for the CANDELS data in Ghosh et. al. (2020) model_load_path (str) – Path to the saved model, which will serve as the starting point for transfer learning. Note that tflearn models usually consist of three files in the format file_name.data, file_name.index, file_name.meta. For this parameter, simply specify file_path/file_name. This parameter can also take the following special values SDSS_sim – Downloads and uses GaMorNet models trained on SDSS g-band simulations at z~0 from Ghosh et. al. (2020) SDSS_tl – Downloads and uses GaMorNet models trained on SDSS g-band simulations and real data at z~0 from Ghosh et. al. (2020) CANDELS_sim – Downloads and uses GaMorNet models trained on CANDELS H-band simulations at z~1 from Ghosh et. al. (2020) CANDELS_tl – Downloads and uses GaMorNet models trained on CANDELS H-band simulations and real data at z~1 from Ghosh et. al. (2020) files_save_path (str) – The full path to the location where the models generated during the training process are to be saved. The path should end with the name of the file. For eg. /path/checkpoint. This will result in model files of the form checkpoint.meta, checkpoint.data and checkpoint.index being saved. Set this to /dev/null on a unix system if you don’t want to save the output. epochs (int) – The number of epochs for which you want to train the model. max_checkpoints (int) – TFLearn saves the model at the end of each epoch. This parameter controls how many of the most recent models are saved. For eg. setting this to 2, will save the model state during the most recent two epochs. batch_size (int) – This variable specifies how many images will be processed in a single batch. This is a hyperparameter. The default value is a good starting point lr (float) – This is the learning rate to be used during the training process. This is a hyperparameter that should be tuned during the training process. The default value is a good starting point. momentum (float) – The value of the momentum to be used in the gradient descent optimizer that is used to train GaMorNet. This must always be $$\geq 0$$. This accelerates the gradient descent process. This is a hyperparameter. The default value is a good starting point. decay (float) – The amount of learning rate decay to be applied over each update. nesterov (bool) – Whether to apply Nesterov momentum or not. loss (allowed str or function) – The loss function to be used. If using the string option, you need to specify the name of the loss function. This can be set to be any loss available in tflearn save_model (bool) – Whether you want to save the model files at each epoch during training. This parameter should be used in conjunction with max_checkpoints to configure how many of the saved model files are preserved till the end. show_metric (bool) – Whether to display the training/testing metrics during training. clear_session (bool) – If set to True, this will clear the TensorFlow session currently running. This is handy while running GaMorNet in a notebook to avoid variable name confusions. (Sometimes, under the hood, TFLearn & Tensorflow reuse the same layer names leading to conflicts) Note that if set to True, you will lose access to any other graphs you may have run before. Trained TFLearn Model TFLearn models.dnn.DNN class