Introduction
Welcome to the documentation of the OPAL Masterclass with machine learning. This is mainly an overview of all classes and functions used in the masterclass. The code and further documentation can be found on GitHub.
Class Event
- class Event(filename, image, category, probabilities=None)
An event consists of a filename, an image and a category. Additionally, probabilities from predictions can be stored.
- filename
Filename of the event.
- Type
text
- image
Image of the event as numpy array.
- Type
numpy array
- category
Category as 1, 2, 3, 4 or q, e, m, t.
- Type
text or number
- probabilities
Prediction probabilities for the classes “q”, “e”, “m” and “t”. Defaults to None.
- Type
list of numbers, optional
- show_image(show_category=False, show_probability=False)
Displays the image of the event.
- Parameters
show_category (bool, optional) – Sets if the category will be shown below the image. Defaults to False.
show_probability (bool, optional) – Shows the probabilites of classification in case there are any. Defaults to False.
Class MLModel
- class MLModel
This class is a wrapper for the machine learning model. It simplifies the use of Tensorflow. Resets Tensorflow random seed with value of global variable random_seed.
- model
Underlying tensorflow model.
- Type
tf.keras.models
- historylist
List of all training outputs.
- Type
list of tf.keras.callbacks
- training
List containing the training data as Event objects.
- Type
list of Events
- validation
List containing the validation data as Event objects.
- Type
list of Events
- train_time
Stores the summed duration of the training operation.
- Type
datetime.timedelta
- delete_structure()
Deletes current model structure.
- load_structure_default()
Loads the default model structure. These are three convolution-pooling-layers and two fully connected layers.
- load_training_eventlist(training_eventlist)
Loads the eventlist for training.
- Parameters
training_eventlist (list) – Eventlist with training events.
- load_validation_eventlist(validation_eventlist)
Loads the eventlist for validation.
- Parameters
validation_eventlist (list) – Eventlist with validation events.
- new_layer_convolution(count_filter=32, size_filter=(3, 3), activation='relu')
Adds a convolutional layer.
- Parameters
count_filter (number, optional) – Defines the number of individual filters. Defaults to 32.
size_filter (tuple with two numbers, optional) – Defines the size of the filter kernels. Defaults to (3, 3).
activation (string, optional) – Sets the activation function. Defaults to ‘relu’.
- new_layer_dense(count_neurons=64, activation='relu')
Adds a fully connected (dense) layer.
- Parameters
counts_neurons (number, optional) – Defines the count of neurons in this layer. Defaults to 64.
activation (string, optional) – Sets the activation function. Defaults to ‘relu’.
- new_layer_final()
Adds the last layer of a network. This is a fully connected layer with four outputs.
- new_layer_flatten()
Serializes all neurons. This is used for switching from convolutional layers to fully connected layers.
- new_layer_pooling(size_filter=(3, 3))
Adds a pooling layer.
- Parameters
size_filter (tuple with two numbers, optional) – Defines the size of the neighboorhood to be pooled. Defaults to (3, 3).
- predict(test_eventlist)
Predict categories of given events using the learned model. Categories of input data will be ignored and overwritten with the prediction.
- Parameters
test_eventlist (list) – List of events for testing.
- Raises
RuntimeError – Model not trained.
- Returns
Eventlist with predictions.
- Return type
List
- show_learning_curve(**args)
Shows the learning curve.
- Parameters
historylist (List of TF objects) – List of learning histories of the model.
show_accuracy (bool, optional) – Shows the accuracy. Defaults to True.
show_loss (bool, optional) – Shows the loss. Defaults to False.
- Raises
RuntimeError – Model not trained.
- show_structure()
Shows an overview of all model layers.
- Raises
RuntimeError – No model has been loaded or created.
- train(show_time=True, count_epochs=3)
Starts the training of the model.
- Parameters
show_time (bool, optional) – Defines if the total time is shown after training. Defaults to True.
counts_epochs (number, optional) – Defines how many iterations over all training and validation data should be performed.
- Raises
RuntimeError – No model or no data.
Class Overview
- class Overview
An object of this class can create an overview of visible branching ratios. The method show always prints the current state of the given eventlists and not the state at the time, the list was added.
- add_entry(name, eventlist, overwrite=False)
Adds a new entry to the overview. There can not be two columns with the same name. In this case nothing will be added. An entry with a certain name can be overwritten.
- Parameters
name (string) – Column heading of the entry.
eventlist (list) – Eventlist of the entry.
overwrite (boolean) – If True, a possible entry with the same name will be overwritten with a new eventlist.
- delete_entry(index)
Deletes an entry from the overview.
- Parameters
index (number) – Index of item to be deleted.
- Raises
IndexError – The given index is too low or too high.
- show(show_theory=True)
Prints the overview.
- Parameters
show_theory (bool, optional) – Sets if the theoretical branching ratio is shown. Defaults to True.
Further Functions
- check_files()
Checks if category file in images are at the specified path. If not, they will be downloaded.
- set_random_seeds(seed)
Sets random seeds for Numpy and Tensorflow. The same seed is used for both modules. With given seed, the whole process is not random anymore, but will always produce the same results. The functions split_events_random, augment_events and MLModel.init use this seed. Within these functions, the global seed of Numpy or Tensorflow may be reset.
- Parameters
seed (number) – Seed to be passed.
- show_image(event, show_category=False, show_probability=False)
Displays the image of the event.
- Parameters
show_category (bool, optional) – Sets if the category will be shown below the image. Defaults to False.
show_probability (bool, optional) – Shows the probabilites of classification in case there are any. Defaults to False.
- filenames_from_eventlist(eventlist)
Generates a list of filenames from a list of events.
- Parameters
eventlist (list of events) – Input list.
- Returns
List of filenames.
- Return type
List
- images_from_eventlist(eventlist)
Generates a list of images from a list of events.
- Parameters
eventlist (list of events) – Input list.
- Returns
List of images.
- Return type
List
Warning: This is a list of 3D numpy arrays and not a 4D numpy array yet!
- categories_from_eventlist(eventlist, numbers=False)
Generates a list of categories from a list of events.
- Parameters
eventlist (list of events) – Input list.
numbers (bool, optional) – Sets if the categories are given as numbers (True) or letters (False). Defaults to False.
- Returns
List of categories
- Return type
List
- show_overview(names, *arrays, show_theory=True)
Shows an overview of all visible branching ratios.
- Parameters
names (liste of strings) – List with column headings.
*arrays (list of events) – One or multiple list of events. Separate by comma when using multiple lists.
show_theory (bool, optional) – Sets if the theoretical branching ratio is shown. Defaults to True.
- sign_to_number(sign)
Converts decay categories signs to numbers.
- Parameters
sign (letter) – Input category.
- Raises
RuntimeError – Letter does not match any category.
- Returns
Output category.
- Return type
Number
- number_to_sign(number)
Converts decay categories numbers to signs.
- Parameters
number (number) – Input category.
- Raises
RuntimeError – Number does not match any category.
- Returns
Output category.
- Return type
Letter
- show_confusion_matrix(true_eventlist, predicted_eventlist)
Shows confusion matrix.
- Parameters
true_eventlist (list) – List of events with true categories.
predicted_eventlist (list) – List of events with predicted categories.
- calculate_prediction_accuracy(true_eventlist, predicted_eventlist)
Calculates the prediction accuracy for given eventlists of true and predicted events.
- Parameters
true_eventlist (list) – List of events with true categories.
predicted_eventlist (list) – List of events with predicted categories.
- Returns
Prediction accuracy.
- Return type
number
- plot_metrics(historylist, show_accuracy=True, show_loss=False)
Shows the learning curve with respect to accuracy or loss. By default, only the accuracy learning curve is shown.
- Parameters
historylist (list of TF history objects) – List of learning histories of the model.
show_accuracy (bool, optional) – Shows the accuracy. Defaults to True.
show_loss (bool, optional) – Shows the loss. Defaults to False.
- load_events()
Loads all images from the folder and combines them with category information from .csv file.
- Returns
List of events.
- Return type
List
- augment_events(eventlist, factor)
The dataset is augmented by copying the images and rotating and/or flipping the randomly. The output is shuffled. Resets Numpy random seed with current value of global variable random_seed.
- Parameters
eventlist (list) – List of events
factor (number or list) – If factor is a number, all decay channels are augmented by this factor. If factor is a list of four entries, the decay channels are augmented according to the order “q, e, m, t”.
- Raises
ValueError – Factor has unexpected structure.
- Returns
List of events.
- Return type
List
- split_events_random(eventlist, fraction_first_block)
Splits a list into two lists randomly. Uses global random seed.
- Parameters
eventlist (list) – List of events.
fraction_first_block (number) – Fraction of items in the first new list.
- Returns
- tuple containing:
List: List of events (first block), List: List of events (second block)
- Return type
tuple
- show_false_predictions(true_eventlist, predicted_eventlist, count=5, show_probability=True)
Generates an overview with all false predicted events.
- Parameters
true_eventlist (list) – True events.
predicted_eventlist (list) – Predicted events.
count (number, optional) – Number of events to be shown. Defaults to 5.
show_probability (boolean, optional) – Sets if classification probabilities are shown. Defaults to True.
- filter_by_category(eventlist, category)
This function creates a new eventlist, where only events of one category appear.
- Parameters
eventlist (list) – Input eventlist.
category ([type]) – Category to be filtered for, given as “q”, “e”, “m” or “t”.
- Returns
Filtered eventlist.
- Return type
list
- show_only_one_category(eventlist, category, count=5)
Show all (or a few) events of one category in an eventlist.
- Parameters
eventlist (list) – Input eventlist.
category (string) – Category given as letter (“q”, “e”, “m” or “t”).
count (int, optional) – Number of events to be shown. Defaults to 5.