pyMSDtorch.core package

Subpackages

Submodules

pyMSDtorch.core.corcoef module

pyMSDtorch.core.corcoef.cc(a, b)

Compute a correlation coefficient between two arrays

Parameters:

  • a – Array a

  • b – Array b

Returns:

A correlation coefficient

pyMSDtorch.core.custom_losses module

class pyMSDtorch.core.custom_losses.DiceBCELoss(smooth=1, alpha=0.5)

Bases: Module

Creates a criterion that outputs a combination of Dice score coefficient (DSC), a measure of overlap between two sets, and binary cross-entropy (BCE), the ubiquitous image segmentation measuring dissimilarity between two distributions. This metric’s use case includes data with lightly imbalanced class epresentation (moderate to low foreground-to-background ratio), as it leverages the BCE smoothing to enhance the already-flexible performance of DSC.

forward(inputs, targets)
Parameters:

  • inputs (List[float]) – tensor of size (N,∗), where N is the batch size and * indicates any number of additional dimensions

  • targets (List[float]) – tensor of size (N,*), the same size as the input

training: bool
class pyMSDtorch.core.custom_losses.DiceLoss(smooth=1)

Bases: Module

Creates a criterion that outputs the popular Dice score coefficient (DSC), a measure ofboverlap between image regions. It is widely used in computer vision for edge detection and is generally compared against the ubiquitous Binary Cross-Entropy in segmentation tasks.

Overall, the Dice loss is a general measure for assessing segmentation performance when a ground truth is available, though it lacks proper re-weighting when dealing with an imbalance of classes (i.e. a single class or two are disproportionately represented).

forward(inputs, targets)
Parameters:

  • inputs (List[float]) – tensor of size (N,∗), where N is the batch size and * indicates any number of additional dimensions

  • targets (List[float]) – tensor of size (N,*), the same size as the input

training: bool
class pyMSDtorch.core.custom_losses.FocalLoss(alpha=0.8, gamma=0.5)

Bases: Module

Creates a criterion that outputs the Focal loss metric, a variation of binary cross-entropy. Developed by Facebook AI Research in 2017 as a means of applying segmentation on examples with low foreground-to-background ratios, the FocalLoss criterion down-weights the easy-to-detect class decisions and instead focuses training on hard negatives.

forward(inputs, targets)
Parameters:

  • inputs (List[float]) – tensor of size (N,∗), where N is the batch size and * indicates any number of additional dimensions

  • targets (List[float]) – tensor of size (N,*), the same size as the input

training: bool
class pyMSDtorch.core.custom_losses.FocalTverskyLoss(smooth=1, alpha=0.5, beta=0.5, gamma=0.8)

Bases: Module

Creates a criterion that combines the customizable precision-to-recall penalty decisions of the Tversky loss (TL) index with the Focal loss (FL) advantages of dealing with hard examples with low foreground-to-background ratios.

The FocalTverskyLoss (FTL) is mainly comprised of TL loss, a generalization of the Dice loss coefficient, a measure of overlap between two sets that is widely popular in computer vision. The TL index aims to achieve a better precision-to-recall trade-off by adjusting how harshly false positives (fp) and false negatives (fn) are penalized. Hyperparameters alpha and beta control how harshly fps and fns are penalized, respectively, allowing the user to place higher emphasis on precision/recal with a larger alpha/beta value. For reference, setting alpha=beta=0.5 results in the DiceLoss criterion.

Once the TL index is computed, hyperparameter gamma is introduced which down-weights the easy-to-detect class decisions and instead focuses training on hard negatives.

forward(inputs, targets)
Parameters:

  • inputs (List[float]) – tensor of size (N,∗), where N is the batch size and * indicates any number of additional dimensions

  • targets (List[float]) – tensor of size (N,*), the same size as the input

training: bool
class pyMSDtorch.core.custom_losses.L1LossMasked

Bases: Module

An implementation of a masked L1Loss. Replicates the PyTorch L1Loss loss criterion, this time accepting a binary mask as third input indicating which pixels to accumulate gradients for.

forward(inputs, targets, masks)
Parameters:

  • inputs (List[float]) – tensor of size (N,∗), where N is the batch size and * indicates any number of additional dimensions

  • targets (List[float]) – tensor of size (N,*), the same size as the input

  • masks (List[bool]) – tensor of size (N,*), the same size as the input; indicates which pixels to ignore in loss evaluation

training: bool
class pyMSDtorch.core.custom_losses.MSELossMasked

Bases: Module

An implementation of a masked mean square error Loss. Replicates the PyTorch MSELoss loss criterion, this time accepting a binary mask as third input indicating which pixels to accumulate gradients for.

forward(inputs, targets, masks)
Parameters:

  • inputs (List[float]) – tensor of size (N,∗), where N is the batch size and * indicates any number of additional dimensions

  • targets (List[float]) – tensor of size (N,*), the same size as the input

  • masks (List[bool]) – tensor of size (N,*), the same size as the input; indicates which pixels to ignore in loss evaluation

training: bool
class pyMSDtorch.core.custom_losses.TverskyLoss(smooth=1, alpha=0.75, beta=0.25)

Bases: Module

Creates a criterion that outputs the Tversky index loss, a generalization of the Dice loss coefficient, a measure of overlap between two sets that is widely popular in computer vision. The Tversky loss index aims to achieve a better precision-to-recall trade-off by adjusting how harshly false positives (fp) and false negatives (fn) are penalized.

Hyperparameters alpha and beta control how harshly fps and fns are penalized, respectively, allowing the user to place higher emphasis on precision/recal with a larger alpha/beta value. For reference, setting alpha=beta=0.5 results in the DiceLoss criterion.

forward(inputs, targets)
Parameters:

  • inputs (List[float]) – tensor of size (N,∗), where N is the batch size and * indicates any number of additional dimensions

  • targets (List[float]) – tensor of size (N,*), the same size as the input

training: bool
pyMSDtorch.core.custom_losses.tst()

Defines and test several Mixed Scale Dense Networks consisting of 2D convolutions, provides a printout of the network, and checks to make sure tensors pass through the network

pyMSDtorch.core.helpers module

class pyMSDtorch.core.helpers.RandomCrop_Dataset(images, masks, info, sample_size, get_label, samples_per_image=1, keywords=None, class_mapping=None)

Bases: Dataset

Create a dataset of samples from a set of images and masks by first filtering the set by keywords and then taking random crops

Parameters:

  • images (array-like) – A dataset containing a set of images in a similar format to that produced by torchvision.datasets.ImageFolder In particular, image[i][0] should contain a torch tensor of shape [channels_i, height_i, width_i]

  • masks (array-like) – A dataset containing a set of masks corresponding to the set of images, in the same format as images

  • info (array-like) – A 2d sequence where the entries in the ith row contain descriptions of images[i] info[i][0] should contain keywords to match for that image

  • sample_size (sequence[int, int]) – The size of samples in the dataset, in the form [height, width]

  • get_label (function(array-like)) – A one-parameter function that takes in a row of info, say info[i], and returns the associated label (the class of images[i])

  • keywords (array-like, containing strings) – A list of keywords that are matched to the descriptions of images in info [i][0]

  • samples_per_image (int) – the number of samples to generate per image

  • class_mapping (dict{ str: int } or None) – a dictionary mapping class names to indices if provided, otherwise one will be created

pyMSDtorch.core.helpers.binary_acc(y_pred, y_target)

Calculates accuracy of prediction by rounding each output pixel to zero or 1.Inputs are same as criterion evaluation function

Parameters:

  • y_pred – prediction resulting running images through model

  • y_target – target image in which the prediction is scored against

pyMSDtorch.core.helpers.count_conv2d(module: Module)

Counts the number of layers in the network

Parameters:

module – Module: the defined network, usually passed to the variable ‘net’

pyMSDtorch.core.helpers.count_conv3d(module: Module)

Counts the number of layers in the network

Parameters:

module – Module: the defined network, usually passed to the variable ‘net’

pyMSDtorch.core.helpers.count_parameters(module: Module)

Counts the number of learnable parameters in the network

Parameters:

module – Module: the defined network, usually passed to the variable ‘net’

pyMSDtorch.core.helpers.create_class_mapping(info, get_label)

Create a mapping from class names to indices Automatically creates a class called background that has index 0

Parameters:

  • info (array-like) – A sequence where the entry i contains descriptions of the ith image

  • get_label (function(Object)) – A one-parameter function that takes in an entry of info, say info[i], and returns the associated label (the class of the ith image)

pyMSDtorch.core.helpers.create_mask(tens, top, left, height, width, label)

Create a mask cropped from the given tensor with the specified label

Parameters:

  • tens (torch.FloatTensor) – tensor to extract the mask from

  • top (int) – vertical component of the top left corner of the crop

  • left (int) – horizontal coordinate of the top left corner of the crop

  • height (int) – height of the crop

  • width (int) – width of the crop

  • label (int) – label to which all nonzero pixel values are converted

pyMSDtorch.core.helpers.get_device()
Returns:

either an available GPU or the CPU

pyMSDtorch.core.helpers.get_in_channels(module: Module)

Counts the number of incoming channels in the initial 2d or 3d convolutional layer

Parameters:

module – Module: the defined network, usually passed to the variable ‘net’

pyMSDtorch.core.helpers.get_out_channels(module: Module)

Counts the number of outgoing channels in the final 2d or 3d convolutional layer

Parameters:

module – Module: the defined network, usually passed to the variable ‘net’

pyMSDtorch.core.helpers.make_dir(dir_name)

Make a directory for storing reconstructed images

Parameters:

dir_name (str) – user specified name of new directory

pyMSDtorch.core.helpers.save_decoded_image2d(img, name)

Saves torch images (clean, noisy, or reconstructed)

Parameters:

  • img – The torch image to be saved, typically extracted from a batch of test data

  • name – Name of image (with existing directory path) in which images are saved

pyMSDtorch.core.helpers.save_image_reconstructions2d(net, testloader, dir_name)

A simple module for running noisy images from the testing set through the model. A batch of original, noisy, and cleaned versions of all pics are saved.

Parameters:

  • net – the trained network

  • testloader – set of data to test, created via torch.utils.data import DataLoader

  • dir_name – directory in which all images are saved

pyMSDtorch.core.helpers.save_loss_images(train_loss, validation_loss, train_acc, validation_acc, path, log_plot=True)

Plots loss and binary accuracy functions for both the training and validation sets. Accuracy arrays computed via helpers.binary_acc

Parameters:

  • log_plot (Bool) – Toggle whether or not we want the logarithm of the loss

  • train_loss – training loss as a function of epoch

  • validation_loss – validation set loss as a function of epoch

  • train_acc – training accuracy as a function of epoch

  • validation_acc – validation set accuraccy as a function of epoch

  • path – path in which to save image

pyMSDtorch.core.helpers.save_training_images(noisy, output, mask, path, epoch, train=True)

Plots training/validation tensor images in hopes of tracking progress within the training loop

Parameters:

  • noisy (List[float]) – noisy image tensor

  • output (List[float]) – model output tensor

  • mask (List[float]) – binary mask tensor using 0 for background and 1 for peak class

  • path (str) – directory in which images are saved to

  • epoch (int) – epoch number appended to image name

  • train (bool) – True if training images, False if validation images

pyMSDtorch.core.helpers.tst_directory()

Provides a quick check for saving images from pytorch to a freshly made directory

pyMSDtorch.core.train_scripts module

pyMSDtorch.core.train_scripts.autoencode_and_classify_training(net, trainloader, validationloader, macro_epochs, mini_epochs, criteria_autoencode, minimizer_autoencode, criteria_classify, minimizer_classify, device, scheduler=None, clip_value=None, show=0)
Parameters:

  • net (input network) –

  • trainloader (training data loader) –

  • validationloader (validation data loader) –

  • macro_epochs (the total number of passes of optimization) –

  • mini_epochs (the number of passes of the data for autoencoding or classification) –

  • criteria_autoencode (loss function for autoencoding) –

  • minimizer_autoencode (minimizer for autyoencoding) –

  • criteria_classify (loss function for classification) –

  • minimizer_classify (minimizer for classification) –

  • device (where do we train?) –

  • scheduler (a scheduler, optional.) –

  • clip_value (a clip value to avoid large shifts. optional) –

  • show (when 0 show all, if set a number, every n-th pass of the data is shown.) –

Return type:

optimzed network, performance trace for autoencoding, performance trace for classification

pyMSDtorch.core.train_scripts.regression_metrics(preds, target)

Compute a pearson correlation coefficient. Useful for validating / understanding regression performance

Parameters:

  • preds (Predicted values) –

  • target (Target values) –

Return type:

A correlation coefficient

pyMSDtorch.core.train_scripts.segmentation_metrics(preds, target, missing_label=-1)

Computes a variety of F1 scores. See : https://towardsdatascience.com/micro-macro-weighted-averages-of-f1-score-clearly-explained-b603420b292f

Parameters:

  • preds (Predicted labels) –

  • target (Target labels) –

  • missing_label (missing label) –

Return type:

micro and macro F1 scores

pyMSDtorch.core.train_scripts.train_autoencoder(net, trainloader, validationloader, NUM_EPOCHS, criterion, optimizer, device, savepath=None, saveevery=None, scheduler=None, use_amp=False, show=0, clip_value=None)

Loop through epochs passing dirty images to net.

Parameters:

  • net – input network

  • trainloader – data loader with training data

  • validationloader – data loader with validation data

  • NUM_EPOCHS – number of epochs

  • criterion – target function

  • optimizer – optimization engine

  • device – the device where we calculate things

  • savepath – filepath in which we save networks intermittently

  • saveevery – integer n for saving network every n epochs

  • scheduler – an optional schedular. can be None

  • show – print stats every n-th epoch

  • use_amp – use pytorch automatic mixed precision

  • clip_value – value for gradient clipping. Can be None.

Returns:

A network and run summary stats.

pyMSDtorch.core.train_scripts.train_labeling(net, trainloader, validationloader, NUM_EPOCHS, criterion, optimizer, device, savepath=None, saveevery=None, scheduler=None, show=0, use_amp=False, clip_value=None)

Loop through epochs passing images to be segmented on a pixel-by-pixel basis.

Parameters:

  • net – input network

  • trainloader – data loader with training data

  • validationloader – data loader with validation data

  • NUM_EPOCHS – number of epochs

  • criterion – target function

  • optimizer – optimization engine

  • device – the device where we calculate things

  • savepath – filepath in which we save networks intermittently

  • saveevery – integer n for saving network every n epochs

  • scheduler – an optional schedular. can be None

  • show – print stats every n-th epoch

  • use_amp – use pytorch automatic mixed precision

  • clip_value – value for gradient clipping. Can be None.

Returns:

A network and run summary stats

pyMSDtorch.core.train_scripts.train_regression(net, trainloader, validationloader, NUM_EPOCHS, criterion, optimizer, device, savepath=None, saveevery=None, scheduler=None, use_amp=False, show=0, clip_value=None)

Loop through epochs passing dirty images to net.

Parameters:

  • net – input network

  • trainloader – data loader with training data

  • validationloader – data loader with validation data

  • NUM_EPOCHS – number of epochs

  • criterion – target function

  • optimizer – optimization engine

  • device – the device where we calculate things

  • savepath – filepath in which we save networks intermittently

  • saveevery – integer n for saving network every n epochs

  • scheduler – an optional schedular. can be None

  • show – print stats every n-th epoch

  • use_amp – use pytorch automatic mixed precision

  • clip_value – value for gradient clipping. Can be None.

Returns:

A network and run summary stats.

pyMSDtorch.core.train_scripts.train_segmentation(net, trainloader, validationloader, NUM_EPOCHS, criterion, optimizer, device, savepath=None, saveevery=None, scheduler=None, show=0, use_amp=False, clip_value=None)

Loop through epochs passing images to be segmented on a pixel-by-pixel basis.

Parameters:

  • net – input network

  • trainloader – data loader with training data

  • validationloader – data loader with validation data

  • NUM_EPOCHS – number of epochs

  • criterion – target function

  • optimizer – optimization engine

  • device – the device where we calculate things

  • savepath – filepath in which we save networks intermittently

  • saveevery – integer n for saving network every n epochs

  • scheduler – an optional schedular. can be None

  • show – print stats every n-th epoch

  • use_amp – use pytorch automatic mixed precision

  • clip_value – value for gradient clipping. Can be None.

Returns:

A network and run summary stats

pyMSDtorch.core.train_scripts.tst()

Module contents