TensorNet Documentation¶
TensorNet is a high-level deep learning library built on top of PyTorch.
Installation¶
To install and use TensorNet all you have to do is:
pip install torch-tensornet
If you want to get the latest version of the code before it is released on PyPI you can install the library from GitHub
pip install git+https://github.com/shan18/TensorNet.git#egg=torch-tensornet
Data¶
Classes and methods which can be used to create and modify datasets.
Datasets¶
-
class
tensornet.data.
BaseDataset
(train_batch_size=1, val_batch_size=1, cuda=False, num_workers=1, path=None, train_split=0.7, resize=0, 0, padding=0, 0, crop=0, 0, horizontal_flip_prob=0.0, vertical_flip_prob=0.0, gaussian_blur_prob=0.0, rotate_degree=0.0, cutout_prob=0.0, cutout_dim=8, 8, hue_saturation_prob=0.0, contrast_prob=0.0)[source]¶ Loads a dataset.
- Parameters
train_batch_size (
int
, optional) – Number of images to consider in each batch in train set. (default: 0)val_batch_size (
int
, optional) – Number of images to consider in each batch in validation set. (default: 0)cuda (
bool
, optional) – True is GPU is available. (default: False)num_workers (
int
, optional) – How many subprocesses to use for data loading. (default: 0)path (
str
, optional) – Path where dataset will be downloaded. If no path provided, data will be downloaded in a pre-defined directory.train_split (
float
, optional) – Fraction of dataset to assign for training. This parameter will not work for MNIST and CIFAR-10 datasets. (default: 0.7)resize (
tuple
, optional) – Resize the input to the given height and width. (default: (0, 0))padding (
tuple
, optional) – Pad the image if the image size is less than the specified dimensions (height, width). (default: (0, 0))crop (
tuple
, optional) – Randomly crop the image with the specified dimensions (height, width). (default: (0, 0))horizontal_flip_prob (
float
, optional) – Probability of an image being horizontally flipped. (default: 0)vertical_flip_prob (
float
, optional) – Probability of an image being vertically flipped. (default: 0)rotate_degree (
float
, optional) – Angle of rotation for image augmentation. (default: 0)cutout_prob (
float
, optional) – Probability that cutout will be performed. (default: 0)cutout_dim (
tuple
, optional) – Dimensions of the cutout box (height, width). (default: (8, 8))hue_saturation_prob (
float
, optional) – Probability of randomly changing hue, saturation and value of the input image. (default: 0)contrast_prob (
float
, optional) – Randomly changing contrast of the input image. (default: 0)
-
data
(train=True)[source]¶ Return data based on train mode.
- Parameters
train (
bool
, optional) – True for training data. (default: True)- Returns
Training or validation data and targets.
-
unnormalize
(image, transpose=False, data_type=None)[source]¶ Un-normalize a given image.
- Parameters
image (
numpy.ndarray
ortorch.Tensor
) – A ndarray or tensor. If tensor, it should be in CPU.transpose (
bool
, optional) – If True, transposed output will be returned. This param is effective only when image is a tensor. If tensor, the output will have channel number as the last dim. (default: False)data_type (
str
, optional) – Type of image. Required only when dataset has multiple types of images. (default: None)
- Returns
Unnormalized image
- Return type
(numpy.ndarray or torch.Tensor)
-
normalize
(image, transpose=False, data_type=None)[source]¶ Normalize a given image.
- Parameters
image (
numpy.ndarray
ortorch.Tensor
) – A ndarray or tensor. If tensor, it should be in CPU.transpose (
bool
, optional) – If True, transposed output will be returned. This param is effective only when image is a tensor. If tensor, the output will have channel number as the last dim. (default: False)data_type (
str
, optional) – Type of image. Required only when dataset has multiple types of images. (default: None)
- Returns
Normalized image
- Return type
(numpy.ndarray or torch.Tensor)
-
class
tensornet.data.
MNIST
(train_batch_size=1, val_batch_size=1, cuda=False, num_workers=1, path=None, train_split=0.7, resize=0, 0, padding=0, 0, crop=0, 0, horizontal_flip_prob=0.0, vertical_flip_prob=0.0, gaussian_blur_prob=0.0, rotate_degree=0.0, cutout_prob=0.0, cutout_dim=8, 8, hue_saturation_prob=0.0, contrast_prob=0.0)[source]¶ MNIST Dataset.
Note: This dataset inherits the
BaseDataset
class.
-
class
tensornet.data.
CIFAR10
(train_batch_size=1, val_batch_size=1, cuda=False, num_workers=1, path=None, train_split=0.7, resize=0, 0, padding=0, 0, crop=0, 0, horizontal_flip_prob=0.0, vertical_flip_prob=0.0, gaussian_blur_prob=0.0, rotate_degree=0.0, cutout_prob=0.0, cutout_dim=8, 8, hue_saturation_prob=0.0, contrast_prob=0.0)[source]¶ CIFAR-10 Dataset.
Note: This dataset inherits the
BaseDataset
class.
-
class
tensornet.data.
CIFAR100
(train_batch_size=1, val_batch_size=1, cuda=False, num_workers=1, path=None, train_split=0.7, resize=0, 0, padding=0, 0, crop=0, 0, horizontal_flip_prob=0.0, vertical_flip_prob=0.0, gaussian_blur_prob=0.0, rotate_degree=0.0, cutout_prob=0.0, cutout_dim=8, 8, hue_saturation_prob=0.0, contrast_prob=0.0)[source]¶ CIFAR-100 Dataset.
Note: This dataset inherits the
BaseDataset
class.
-
class
tensornet.data.
TinyImageNet
(train_batch_size=1, val_batch_size=1, cuda=False, num_workers=1, path=None, train_split=0.7, resize=0, 0, padding=0, 0, crop=0, 0, horizontal_flip_prob=0.0, vertical_flip_prob=0.0, gaussian_blur_prob=0.0, rotate_degree=0.0, cutout_prob=0.0, cutout_dim=8, 8, hue_saturation_prob=0.0, contrast_prob=0.0)[source]¶ Tiny ImageNet Dataset.
Note: This dataset inherits the
BaseDataset
class.
-
class
tensornet.data.
MODESTMuseum
(train_batch_size=1, val_batch_size=1, cuda=False, num_workers=1, path=None, train_split=0.7, resize=0, 0, padding=0, 0, crop=0, 0, horizontal_flip_prob=0.0, vertical_flip_prob=0.0, gaussian_blur_prob=0.0, rotate_degree=0.0, cutout_prob=0.0, cutout_dim=8, 8, hue_saturation_prob=0.0, contrast_prob=0.0)[source]¶ MODEST Museum Dataset.
Note: This dataset inherits the
BaseDataset
class.
Processing¶
-
class
tensornet.data.processing.
Transformations
(resize=0, 0, padding=0, 0, crop=0, 0, horizontal_flip_prob=0.0, vertical_flip_prob=0.0, gaussian_blur_prob=0.0, rotate_degree=0.0, cutout_prob=0.0, cutout_dim=8, 8, hue_saturation_prob=0.0, contrast_prob=0.0, mean=0.5, 0.5, 0.5, std=0.5, 0.5, 0.5, normalize=True, train=True)[source]¶ Wrapper class to pass on albumentaions transforms into PyTorch.
-
tensornet.data.processing.
data_loader
(data, shuffle=True, batch_size=1, num_workers=1, cuda=False)[source]¶ Create data loader
- Parameters
data (torchvision.datasets) – Downloaded dataset.
shuffle (
bool
, optional) – If True, shuffle the dataset. (default: True)batch_size (
int
, optional) – Number of images to considered in each batch. (default: 1)num_workers (
int
, optional) – How many subprocesses to use for data loading. (default: 1)cuda (
bool
, optional) – True is GPU is available. (default: False)
- Returns
DataLoader instance.
- Return type
(torch.utils.data.DataLoader)
Models¶
Classes and methods which can be used to create and configure model architectures.
Base Model¶
-
class
tensornet.models.
BaseModel
[source]¶ This is the parent class for all the models that are to be created using
TensorNet
.-
forward
(x: torch.Tensor) → torch.Tensor[source]¶ This function defines the forward pass of the model.
- Parameters
x (torch.Tensor) – Input.
- Returns
Model output.
- Return type
(torch.Tensor)
-
summary
(input_size: Tuple[int])[source]¶ Generates model summary.
- Parameters
input_size (tuple) – Size of input to the model.
-
create_learner
(train_loader, optimizer, criterion, device='cpu', epochs=1, l1_factor=0.0, val_loader=None, callbacks=None, metrics=None, activate_loss_logits=False, record_train=True)[source]¶ Create Learner object.
- Parameters
train_loader (torch.utils.data.DataLoader) – Training data loader.
optimizer (torch.optim) – Optimizer for the model.
criterion (torch.nn) – Loss Function.
device (
str
ortorch.device
) – Device where the data will be loaded.epochs (
int
, optional) – Numbers of epochs to train the model. (default: 1)l1_factor (
float
, optional) – L1 regularization factor. (default: 0)val_loader (
torch.utils.data.DataLoader
, optional) – Validation data loader.callbacks (
list
, optional) – List of callbacks to be used during training.track (
str
, optional) – Can be set to either ‘epoch’ or ‘batch’ and will store the changes in loss and accuracy for each batch or the entire epoch respectively. (default: ‘epoch’)metrics (
list
, optional) – List of names of the metrics for model evaluation.
-
set_learner
(learner: tensornet.engine.learner.Learner)[source]¶ Assign a learner object to the model.
- Parameters
learner (
Learner
) – Learner object.
-
fit
(train_loader, optimizer, criterion, device='cpu', epochs=1, l1_factor=0.0, val_loader=None, callbacks=None, metrics=None, activate_loss_logits=False, record_train=True, start_epoch=1, verbose=True)[source]¶ Train the model.
- Parameters
train_loader (torch.utils.data.DataLoader) – Training data loader.
optimizer (torch.optim) – Optimizer for the model.
criterion (torch.nn) – Loss Function.
device (
str
ortorch.device
) – Device where the data will be loaded.epochs (
int
, optional) – Numbers of epochs to train the model. (default: 1)l1_factor (
float
, optional) – L1 regularization factor. (default: 0)val_loader (
torch.utils.data.DataLoader
, optional) – Validation data loader.callbacks (
list
, optional) – List of callbacks to be used during training.track (
str
, optional) – Can be set to either ‘epoch’ or ‘batch’ and will store the changes in loss and accuracy for each batch or the entire epoch respectively. (default: ‘epoch’)metrics (
list
, optional) – List of names of the metrics for model evaluation.record_train (
bool
, optional) – If False, metrics will be calculated only during validation. (default: True)activate_loss_logits (
bool
, optional) – If True, the logits will first pass through the activate_logits function before going to the criterion. (default: False)start_epoch (
int
, optional) – Starting epoch number to display during training. (default: 1)verbose (
bool
, optional) – Print loss and metrics. (default: True)
-
evaluate
(loader, verbose=True, log_message='Evaluation')[source]¶ Evaluate the model on a custom data loader.
- Parameters
loader (torch.utils.data.DataLoader) – Data loader.
verbose (
bool
, optional) – Print loss and metrics. (default: True)log_message (str) – Prefix for the logs which are printed at the end.
- Returns
loss and metric values
-
save
(filepath: str, **kwargs)[source]¶ Save the model.
- Parameters
filepath (str) – File in which the model will be saved.
**kwargs – Additional parameters to save with the model.
-
load
(filepath: str) → dict[source]¶ Load the model and return the additional parameters saved in in the checkpoint file.
- Parameters
filepath (str) – File in which the model is be saved.
- Returns
Parameters saved inside the checkpoint file.
- Return type
(dict)
-
training
: bool¶
-
ResNet¶
-
class
tensornet.models.
ResNet
(block: Type[Union[tensornet.models.resnet.BasicBlock, tensornet.models.resnet.Bottleneck]], layers: List[int], num_classes: int = 1000, zero_init_residual: bool = False, groups: int = 1, width_per_group: int = 64, replace_stride_with_dilation: Optional[List[bool]] = None, norm_layer: Optional[Callable[[…], torch.nn.modules.module.Module]] = None)[source]¶ Residual-Net (ResNet)
Note: This model inherits the
BaseModel
class.- Parameters
block (
BasicBlock
orBottleneck
) – Type of block to use for the model.layers (list) – Number of blocks for each layer.
num_classes (
int
, optional) – Number of classes. (default: 1000)zero_init_residual (
bool
, optional) – Make residual branch behave like an identity. (default: False)groups (
int
, optional) – Number of groups per block. (default: 1)width_per_group (
int
, optional) – Width for each group. (default: 64)replace_stride_with_dilation (
list
, optional) – Replace stride with dilation for each layer.norm_layer (
nn.Module
, optional) – Normalization Layer.
-
forward
(x: torch.Tensor) → torch.Tensor[source]¶ This function defines the forward pass of the model.
- Parameters
x (torch.Tensor) – Input.
- Returns
Model output.
- Return type
(torch.Tensor)
-
training
: bool¶
-
tensornet.models.
resnet18
(pretrained: bool = False, progress: bool = True, **kwargs: Any) → tensornet.models.resnet.ResNet[source]¶ ResNet-18 model from “Deep Residual Learning for Image Recognition”.
- Parameters
pretrained (bool) – If True, returns a model pre-trained on ImageNet
progress (bool) – If True, displays a progress bar of the download to stderr
-
tensornet.models.
resnet34
(pretrained: bool = False, progress: bool = True, **kwargs: Any) → tensornet.models.resnet.ResNet[source]¶ ResNet-34 model from “Deep Residual Learning for Image Recognition”.
- Parameters
pretrained (bool) – If True, returns a model pre-trained on ImageNet
progress (bool) – If True, displays a progress bar of the download to stderr
-
tensornet.models.
resnet50
(pretrained: bool = False, progress: bool = True, **kwargs: Any) → tensornet.models.resnet.ResNet[source]¶ ResNet-50 model from “Deep Residual Learning for Image Recognition”.
- Parameters
pretrained (bool) – If True, returns a model pre-trained on ImageNet
progress (bool) – If True, displays a progress bar of the download to stderr
-
tensornet.models.
resnet101
(pretrained: bool = False, progress: bool = True, **kwargs: Any) → tensornet.models.resnet.ResNet[source]¶ ResNet-101 model from “Deep Residual Learning for Image Recognition”.
- Parameters
pretrained (bool) – If True, returns a model pre-trained on ImageNet
progress (bool) – If True, displays a progress bar of the download to stderr
-
tensornet.models.
resnet152
(pretrained: bool = False, progress: bool = True, **kwargs: Any) → tensornet.models.resnet.ResNet[source]¶ ResNet-152 model from “Deep Residual Learning for Image Recognition”.
- Parameters
pretrained (bool) – If True, returns a model pre-trained on ImageNet
progress (bool) – If True, displays a progress bar of the download to stderr
-
tensornet.models.
resnext50_32x4d
(pretrained: bool = False, progress: bool = True, **kwargs: Any) → tensornet.models.resnet.ResNet[source]¶ ResNeXt-50 32x4d model from “Aggregated Residual Transformation for Deep Neural Networks”.
- Parameters
pretrained (bool) – If True, returns a model pre-trained on ImageNet
progress (bool) – If True, displays a progress bar of the download to stderr
-
tensornet.models.
resnext101_32x8d
(pretrained: bool = False, progress: bool = True, **kwargs: Any) → tensornet.models.resnet.ResNet[source]¶ ResNeXt-101 32x8d model from “Aggregated Residual Transformation for Deep Neural Networks”.
- Parameters
pretrained (bool) – If True, returns a model pre-trained on ImageNet
progress (bool) – If True, displays a progress bar of the download to stderr
-
tensornet.models.
wide_resnet50_2
(pretrained: bool = False, progress: bool = True, **kwargs: Any) → tensornet.models.resnet.ResNet[source]¶ Wide ResNet-50-2 model from “Wide Residual Networks”. The model is the same as ResNet except for the bottleneck number of channels which is twice larger in every block. The number of channels in outer 1x1 convolutions is the same, e.g. last block in ResNet-50 has 2048-512-2048 channels, and in Wide ResNet-50-2 has 2048-1024-2048.
- Parameters
pretrained (bool) – If True, returns a model pre-trained on ImageNet
progress (bool) – If True, displays a progress bar of the download to stderr
-
tensornet.models.
wide_resnet101_2
(pretrained: bool = False, progress: bool = True, **kwargs: Any) → tensornet.models.resnet.ResNet[source]¶ Wide ResNet-101-2 model from “Wide Residual Networks”. The model is the same as ResNet except for the bottleneck number of channels which is twice larger in every block. The number of channels in outer 1x1 convolutions is the same, e.g. last block in ResNet-50 has 2048-512-2048 channels, and in Wide ResNet-50-2 has 2048-1024-2048.
- Parameters
pretrained (bool) – If True, returns a model pre-trained on ImageNet
progress (bool) – If True, displays a progress bar of the download to stderr
MobilenetV2¶
-
class
tensornet.models.
MobileNetV2
(num_classes=1000, width_mult=1.0, inverted_residual_setting=None, round_nearest=8, block=None, norm_layer=None)[source]¶ MobileNet V2
Note: This model inherits the
BaseModel
class.- Parameters
num_classes (
int
, optional) – Number of classes. (default: 1000)width_mult (
float
, optional) – Width multiplier - adjusts number of channels in each layer by this amount. (default: 1.0)inverted_residual_setting (optional) – Network structure.
round_nearest (
int
, optional) – Round the number of channels in each layer to be a multiple of this number. Set to 1 to turn off rounding. (default: 8)block (optional) – Module specifying inverted residual building block for mobilenet.
norm_layer (optional) – Module specifying the normalization layer to use.
-
forward
(x)[source]¶ This function defines the forward pass of the model.
- Parameters
x (torch.Tensor) – Input.
- Returns
Model output.
- Return type
(torch.Tensor)
-
training
: bool¶
-
tensornet.models.
mobilenet_v2
(pretrained=False, progress=True, **kwargs)[source]¶ Constructs a MobileNetV2 architecture from “MobileNetV2: Inverted Residuals and Linear Bottlenecks”.
- Parameters
pretrained (bool, optional) – If True, returns a model pre-trained on ImageNet. (default=False)
progress (bool, optional) – If True, displays a progress bar of the download to stderr. (default=True)
Depth Estimation and Segmentation ResNet¶
-
class
tensornet.models.
DSResNet
[source]¶ A U-Net Inspired model for Monocular Depth Estimation and Image Segmentation.
For information check the Depth-Estimation-Segmentation repository.
Note: This model inherits the
BaseModel
class.-
forward
(x: torch.Tensor) → torch.Tensor[source]¶ This function defines the forward pass of the model.
- Parameters
x (torch.Tensor) – Input.
- Returns
Model output.
- Return type
(torch.Tensor)
-
training
: bool¶
-
Criterion¶
This module contains loss functions.
-
tensornet.models.loss.
cross_entropy_loss
()[source]¶ Cross Entropy Loss. The loss automatically applies the softmax activation function on the prediction input.
- Returns
Cross entroy loss function
-
tensornet.models.loss.
bce_loss
()[source]¶ Binary Cross Entropy Loss. The loss automatically applies the sigmoid activation function on the prediction input.
- Returns
Binary cross entropy loss function
-
tensornet.models.loss.
mse_loss
()[source]¶ Mean Squared Error Loss.
- Returns
Mean squared error loss function
-
tensornet.models.loss.
rmse_loss
(smooth=1e-06)[source]¶ Root Mean Squared Error Loss.
- Returns
Root mean squared error loss function
-
tensornet.models.loss.
dice_loss
(smooth=1)[source]¶ Dice Loss.
- Parameters
smooth (
float
, optional) – Smoothing value. A larger smooth value (also known as Laplace smooth, or Additive smooth) can be used to avoid overfitting. (default: 1)- Returns
Dice loss function
-
tensornet.models.loss.
bce_dice_loss
(smooth=1e-06)[source]¶ BCE Dice Loss.
- Parameters
smooth (
float
, optional) – Smoothing value.- Returns
BCE Dice loss function
-
tensornet.models.loss.
ssim_loss
(data_range=1.0, size_average=True, channel=1)[source]¶ SSIM Loss.
- Parameters
data_range (
float
orint
, optional) – Value range of input images (usually 1.0 or 255). (default: 255)size_average (
bool
, optional) – If size_average=True, ssim of all images will be averaged as a scalar. (default: True)channel (
int
, optional) – input channels (default: 1)
- Returns
SSIM loss function
-
tensornet.models.loss.
ms_ssim_loss
(data_range=1.0, size_average=True, channel=1)[source]¶ MS-SSIM Loss.
- Parameters
data_range (
float
orint
, optional) – Value range of input images (usually 1.0 or 255). (default: 1.0)size_average (
bool
, optional) – If size_average=True, ssim of all images will be averaged as a scalar. (default: True)channel (
int
, optional) – input channels (default: 1)
- Returns
MS-SSIM loss function
Optimizers¶
This module contains optimizers.
-
tensornet.models.optimizer.
sgd
(model: torch.nn.modules.module.Module, learning_rate: float = 0.01, momentum: int = 0, dampening: int = 0, l2_factor: float = 0.0, nesterov: bool = False)[source]¶ SGD optimizer.
- Parameters
model (torch.nn.Module) – Model Instance.
learning_rate (
float
, optional) – Learning rate for the optimizer. (default: 0.01)momentum (
float
, optional) – Momentum factor. (default: 0)dampening (
float
, optional) – Dampening for momentum. (default: 0)l2_factor (
float
, optional) – Factor for L2 regularization. (default: 0)nesterov (
bool
, optional) – Enables nesterov momentum. (default: False)
- Returns
SGD optimizer.
-
tensornet.models.optimizer.
adam
(model: torch.nn.modules.module.Module, learning_rate: float = 0.001, betas: Tuple[float] = 0.9, 0.999, eps: float = 1e-08, l2_factor: float = 0.0, amsgrad: bool = False)[source]¶ Adam optimizer.
- Parameters
model (torch.nn.Module) – Model Instance.
learning_rate (
float
, optional) – Learning rate for the optimizer. (default: 0.001)betas (
tuple
, optional) – Coefficients used for computing running averages of gradient and its square. (default: (0.9, 0.999))eps (
float
, optional) – Term added to the denominator to improve numerical stability. (default: 1e-8)l2_factor (
float
, optional) – Factor for L2 regularization. (default: 0)amsgrad (
bool
, optional) – Whether to use the AMSGrad variant of this algorithm from the paper On the Convergence of Adam and Beyond. (default: False)
- Returns
Adam optimizer.
Engine¶
Classes and methods used to train and test models.
-
class
tensornet.engine.
Learner
(train_loader, optimizer, criterion, device='cpu', epochs=1, l1_factor=0.0, val_loader=None, callbacks=None, metrics=None, activate_loss_logits=False, record_train=True)[source]¶ Model Trainer and Validator.
- Parameters
train_loader (torch.utils.data.DataLoader) – Training data loader.
optimizer (torch.optim) – Optimizer for the model.
criterion (torch.nn) – Loss Function.
device (
str
ortorch.device
, optional) – Device where the data will be loaded. (default=’cpu’)epochs (
int
, optional) – Numbers of epochs/iterations to train the model for. (default: 1)l1_factor (
float
, optional) – L1 regularization factor. (default: 0)val_loader (
torch.utils.data.DataLoader
, optional) – Validation data loader.callbacks (
list
, optional) – List of callbacks to be used during training.metrics (
list
, optional) –List of names of the metrics for model evaluation.
Note: If the model has multiple outputs, then this will be a nested list where each individual sub-list will specify the metrics which are to be used for evaluating each output respectively. In such cases, the model checkpoint will consider only the metric of the first output for saving checkpoints.
activate_loss_logits (
bool
, optional) – If True, the logits will first pass through the activate_logits function before going to the criterion. (default: False)record_train (
bool
, optional) – If False, metrics will be calculated only during validation. (default: True)
-
set_model
(model)[source]¶ Assign model to learner.
- Parameters
model (torch.nn.Module) – Model Instance.
-
update_training_history
(loss)[source]¶ Update the training history.
- Parameters
loss (float) – Loss value.
-
activate_logits
(logits)[source]¶ Apply activation function to the logits if needed. After this the logits will be sent for calculation of loss or evaluation metrics.
- Parameters
logits (torch.Tensor) – Model output
- Returns
activated logits
- Return type
(torch.Tensor)
-
calculate_criterion
(logits, targets, train=True)[source]¶ Calculate loss.
- Parameters
logits (torch.Tensor) – Prediction.
targets (torch.Tensor) – Ground truth.
train (
bool
, optional) – If True, loss is sent to the L1 regularization function. (default: True)
- Returns
loss value
- Return type
(torch.Tensor)
-
fetch_data
(data)[source]¶ Fetch data from loader and load it to GPU.
- Parameters
data (
tuple
orlist
) – List containing inputs and targets.- Returns
inputs and targets loaded to GPU.
-
train_batch
(data)[source]¶ Train the model on a batch of data.
- Parameters
data (
tuple
orlist
) – Input and target data for the model.- Returns
Batch loss.
- Return type
(float)
-
train_epoch
(verbose=True)[source]¶ Run an epoch of model training.
- Parameters
verbose (
bool
, optional) – Print logs. (default: True)
-
evaluate
(loader, verbose=True, log_message='Evaluation')[source]¶ Evaluate the model on a custom data loader.
- Parameters
loader (torch.utils.data.DataLoader) – Data loader.
verbose (
bool
, optional) – Print loss and metrics. (default: True)log_message (str) – Prefix for the logs which are printed at the end.
- Returns
loss and metric values
-
validate
(verbose=True)[source]¶ Validate an epoch of model training.
- Parameters
verbose (
bool
, optional) – Print validation loss and metrics. (default: True)
-
save_checkpoint
(epoch=None)[source]¶ Save model checkpoint.
- Parameters
epoch (
int
, optional) – Current epoch number.
-
write_summary
(epoch, train)[source]¶ Write training summary in tensorboard.
- Parameters
epoch (int) – Current epoch number.
train (bool) – If True, summary will be written for model training else it will be writtern for model validation.
-
fit
(start_epoch=1, epochs=None, reset=True, verbose=True)[source]¶ Perform model training.
- Parameters
start_epoch (
int
, optional) – Start epoch for training. (default: 1)epochs (
int
, optional) – Numbers of epochs/iterations to train the model for. If no value is given, the original value given during initialization of learner will be used.reset (
bool
, optional) – Flag to indicate that training is starting from scratch. (default: True)verbose (
bool
, optional) – Print logs. (default: True)
-
class
tensornet.engine.
LRFinder
(model, optimizer, criterion, metric='loss', device=None, memory_cache=True, cache_dir=None)[source]¶ Learning rate range test. The learning rate range test increases the learning rate in a pre-training run between two boundaries in a linear or exponential manner. It provides valuable information on how well the network can be trained over a range of learning rates and what is the optimal learning rate.
- Parameters
model (torch.nn.Module) – Model Instance.
optimizer (torch.optim) – Optimizer where the defined learning is assumed to be the lower boundary of the range test.
criterion (torch.nn) – Loss function.
metric (
str
, optional) – Metric to use for finding the best learning rate. Can be either ‘loss’ or ‘accuracy’. (default: ‘loss’)device (
str
ortorch.device
, optional) – Device where the computation will take place. If None, uses the same device as model. (default: none)memory_cache (
bool
, optional) – If this flag is set to True, state_dict of model and optimizer will be cached in memory. Otherwise, they will be saved to files under the cache_dir. (default: True)cache_dir (
str
, optional) – Path for storing temporary files. If no path is specified, system-wide temporary directory is used. Notice that this parameter will be ignored if memory_cache is True. (default: None)
-
range_test
(train_loader, iterations, mode='iteration', learner=None, val_loader=None, start_lr=None, end_lr=10, step_mode='exp', smooth_f=0.0, diverge_th=5)[source]¶ Performs the learning rate range test.
- Parameters
train_loader (torch.utils.data.DataLoader) – The training set data loader.
iterations (int) – The number of iterations/epochs over which the test occurs. If ‘mode’ is set to ‘iteration’ then it will correspond to the number of iterations else if mode is set to ‘epoch’ then it will correspond to the number of epochs.
mode (
str
, optional) – After which mode to update the learning rate. Can be either ‘iteration’ or ‘epoch’. (default: ‘iteration’)learner (
Learner
, optional) – Learner object for the model. (default: None)val_loader (
torch.utils.data.DataLoader
, optional) – If None, the range test will only use the training metric. When given a data loader, the model is evaluated after each iteration on that dataset and the evaluation metric is used. Note that in this mode the test takes significantly longer but generally produces more precise results. (default: None)start_lr (
float
, optional) – The starting learning rate for the range test. If None, uses the learning rate from the optimizer. (default: None)end_lr (
float
, optional) – The maximum learning rate to test. (default: 10)step_mode (
str
, optional) – One of the available learning rate policies, linear or exponential (‘linear’, ‘exp’). (default: ‘exp’)smooth_f (
float
, optional) – The metric smoothing factor within the [0, 1] interval. Disabled if set to 0, otherwise the metric is smoothed using exponential smoothing. (default: 0.0)diverge_th (
int
, optional) – The test is stopped when the metric surpasses the threshold: diverge_th * best_metric. To disable, set it to 0. (default: 5)
-
plot
(log_lr=True, show_lr=None)[source]¶ Plots the learning rate range test.
- Parameters
skip_start (
int
, optional) – Number of batches to trim from the start. (default: 10)skip_end (
int
, optional) – Number of batches to trim from the end. (default: 5)log_lr (
bool
, optional) – True to plot the learning rate in a logarithmic scale; otherwise, plotted in a linear scale. (default: True)show_lr (
float
, optional) – Is set, will add vertical line to visualize specified learning rate. (default: None)
Callbacks¶
Model Checkpoint¶
-
class
tensornet.engine.ops.
ModelCheckpoint
(path, monitor='val_loss', mode='auto', verbose=0, save_best_only=True, best_value=None)[source]¶ Store model checkpoint while training.
- Parameters
path (str) – Path to the directory where the checkpoints will be stored.
monitor (
str
, optional) – Metric to monitor. (default: ‘val_loss’)mode (
str
, optional) – Comparison mode for monitored quantity. One of {auto, min, max}. (default: ‘auto’)verbose (
int
, optional) – verbosity mode, 0 or 1. (default: 0)save_best_only (
bool
, optional) – If True, only the model with the best value of monitoring quantity will be saved. (default: True)best_value (
float
, optional) – Best value of the monitored metric, this is useful when resuming training. This param will work only when save_best_only is True.
-
__call__
(model, current_value, epoch=None, **kwargs)[source]¶ Compare the current value with the best value and save the model accordingly.
- Parameters
model (torch.nn.Module) – Model Instance.
optimizer (torch.optim) – Optimizer for the model.
current_value (float) – Current value of the monitored quantity.
epoch (int) – Epoch count.
**kwargs – Other keyword arguments.
TensorBoard¶
-
class
tensornet.engine.ops.
TensorBoard
(logdir=None, images=None, device='cpu')[source]¶ Setup Tensorboard.
- Parameters
logdir (
str
, optional) – Save directory location. Default is runs/CURRENT_DATETIME_HOSTNAME, which changes after each run.images (
torch.Tensor
, optional) – Batch of images for which predictions will be done.device (
str
ortorch.device
, optional) – Device where the data will be loaded. (default=’cpu’)
-
write_model
(model)[source]¶ Write graph to tensorboard.
- Parameters
model (torch.nn.Module) – Model Instance.
-
write_image
(image, image_name)[source]¶ Write image to tensorboard.
- Parameters
image (torch.Tensor) – Image tensor.
image_name (str, optional) – Name of the image to be written.
LR Schedulers¶
-
tensornet.engine.ops.lr_scheduler.
step_lr
(optimizer, step_size, gamma=0.1, last_epoch=- 1)[source]¶ Create LR step scheduler.
- Parameters
optimizer (torch.optim) – Model optimizer.
step_size (int) – Frequency for changing learning rate.
gamma (
float
, optional) – Factor for changing learning rate. (default: 0.1)last_epoch (
int
, optional) – The index of last epoch. (default: -1)
- Returns
Learning rate scheduler.
- Return type
StepLR
-
tensornet.engine.ops.lr_scheduler.
reduce_lr_on_plateau
(optimizer, factor=0.1, patience=10, verbose=False, min_lr=0)[source]¶ Create LR plateau reduction scheduler.
- Parameters
optimizer (torch.optim) – Model optimizer.
factor (
float
, optional) – Factor by which the learning rate will be reduced. (default: 0.1)patience (
int
, optional) – Number of epoch with no improvement after which learning rate will be will be reduced. (default: 10)verbose (
bool
, optional) – If True, prints a message to stdout for each update. (default: False)min_lr (
float
, optional) – A scalar or a list of scalars. A lower bound on the learning rate of all param groups or each group respectively. (default: 0)
- Returns
ReduceLROnPlateau instance.
-
tensornet.engine.ops.lr_scheduler.
one_cycle_lr
(optimizer, max_lr, epochs, steps_per_epoch, pct_start=0.5, div_factor=10.0, final_div_factor=10000)[source]¶ Create One Cycle Policy for Learning Rate.
- Parameters
optimizer (torch.optim) – Model optimizer.
max_lr (float) – Upper learning rate boundary in the cycle.
epochs (int) – The number of epochs to train for. This is used along with steps_per_epoch in order to infer the total number of steps in the cycle.
steps_per_epoch (int) – The number of steps per epoch to train for. This is used along with epochs in order to infer the total number of steps in the cycle.
pct_start (
float
, optional) – The percentage of the cycle (in number of steps) spent increasing the learning rate. (default: 0.5)div_factor (
float
, optional) – Determines the initial learning rate via initial_lr = max_lr / div_factor. (default: 10.0)final_div_factor (
float
, optional) – Determines the minimum learning rate via min_lr = initial_lr / final_div_factor. (default: 1e4)
- Returns
OneCycleLR instance.
-
tensornet.engine.ops.lr_scheduler.
cyclic_lr
(optimizer, base_lr, max_lr, step_size_up=2000, step_size_down=None, mode='triangular', gamma=1.0, scale_fn=None, scale_mode='cycle', cycle_momentum=True, base_momentum=0.8, max_momentum=0.9, last_epoch=- 1, verbose=False)[source]¶ Create Cyclic LR Policy.
- Parameters
optimizer (torch.optim) – Model optimizer.
base_lr (float) – Lower learning rate boundary in the cycle.
max_lr (float) – Upper learning rate boundary in the cycle.
step_size_up (int) – Number of training iterations in the increasing half of a cycle. (default: 2000)
step_size_down (int) – Number of training iterations in the decreasing half of a cycle. If step_size_down is None, it is set to step_size_up. (default: None)
mode (str) – One of triangular, triangular2, exp_range. If scale_fn is not None, this argument is ignored. (default: ‘triangular’)
gamma (float) – Constant in ‘exp_range’ scaling function: gamma**(cycle iterations). (default: 1.0)
scale_fn – Custom scaling policy defined by a single argument lambda function, where 0 <= scale_fn(x) <= 1 for all x >= 0. If specified, then ‘mode’ is ignored. (default: None)
scale_mode (str) – ‘cycle’, ‘iterations’. Defines whether scale_fn is evaluated on cycle number or cycle iterations (training iterations since start of cycle). (default: ‘cycle’)
cycle_momentum (bool) – If True, momentum is cycled inversely to learning rate between ‘base_momentum’ and ‘max_momentum’. (default: True)
base_momentum (float) – Lower momentum boundaries in the cycle. (default: 0.8)
max_momentum (float) – Upper momentum boundaries in the cycle. Functionally, it defines the cycle amplitude (max_momentum - base_momentum). (default: 0.9)
last_epoch (int) – The index of the last batch. This parameter is used when resuming a training job.(default: -1)
verbose (bool) – If True, prints a message to stdout for each update. (default: False)
- Returns
CyclicLR instance.
Regularizers¶
GradCAM¶
-
class
tensornet.gradcam.
GradCAM
(model: torch.nn.modules.module.Module, layer_name: str)[source]¶ Calculate GradCAM salinecy map.
Note: The current implemenation supports only ResNet models. The class can be extended to add support for other models.
- Parameters
model (torch.nn.Module) – A model instance.
layer_name (str) – Name of the layer in model for which the map will be calculated.
-
__call__
(input: tuple, class_idx: Optional[int] = None, retain_graph: bool = False) → Tuple[torch.Tensor][source]¶ - Parameters
input (tuple) – Input image with shape of (1, 3, H, W)
class_idx (
int
, optional) – Class index for calculating GradCAM. If not specified, the class index that makes the highest model prediction score will be used.
- Returns
2-element tuple containing
(torch.tensor): saliency map of the same spatial dimension with input.
(torch.tensor): model output.
-
class
tensornet.gradcam.
GradCAMPP
(model: torch.nn.modules.module.Module, layer_name: str)[source]¶ Calculate GradCAM++ salinecy map.
It inherits the GradCAM class so the definition for all the methods is exactly the same as its parent class.
Note: The current implemenation supports only ResNet models. The class can be extended to add support for other models.
-
class
tensornet.gradcam.
GradCAMView
(model: torch.nn.modules.module.Module, layers: List[str], device: Union[str, torch.device], mean: Union[float, tuple], std: Union[float, tuple])[source]¶ Create GradCAM and GradCAM++.
Note: The current implemenation of GradCAM and GradCAM++ supports only ResNet models. The class can be extended to add support for other models.
- Parameters
model (torch.nn.Module) – Trained model.
layers (list) – List of layers to show GradCAM on.
device (
str
ortorch.device
) – GPU or CPU.mean (
float
ortuple
) – Mean of the dataset.std (
float
ortuple
) – Standard Deviation of the dataset.
-
cam
(norm_img_class_list: List[Union[Dict[str, Union[torch.Tensor, int]], torch.Tensor]])[source]¶ Get CAM for a list of images.
- Parameters
norm_img_class_list (list) – List of dictionaries or list of images. If dict, each dict contains keys ‘image’ and ‘class’ having values ‘normalized_image’ and ‘class_idx’ respectively. class_idx is optional. If class_idx is not given then the model prediction will be used and the parameter should just be a list of images. Each image should be of type torch.Tensor
-
__call__
(norm_img_class_list: List[Union[Dict[str, Union[torch.Tensor, int]], torch.Tensor]]) → List[Dict[str, Union[numpy.ndarray, Dict[str, numpy.ndarray]]]][source]¶ Get GradCAM for a list of images.
- Parameters
norm_img_class_list (list) – List of dictionaries or list of images. If dict, each dict contains keys ‘image’ and ‘class’ having values ‘normalized_image’ and ‘class_idx’ respectively. class_idx is optional. If class_idx is not given then the model prediction will be used and the parameter should just be a list of images. Each image should be of type torch.Tensor
-
tensornet.gradcam.
visualize_cam
(mask: torch.Tensor, img: torch.Tensor, alpha: float = 1.0) → Tuple[torch.Tensor][source]¶ Make heatmap from mask and synthesize GradCAM result image using heatmap and img.
- Parameters
mask (torch.tensor) – mask shape of (1, 1, H, W) and each element has value in range [0, 1]
img (torch.tensor) – img shape of (1, 3, H, W) and each pixel value is in range [0, 1]
- Returns
2-element tuple containing
(torch.tensor): heatmap img shape of (3, H, W)
(torch.tensor): synthesized GradCAM result of same shape with heatmap.
Utilities¶
This section lists out all the utility functions present througout TensorNet
.
Common Utilities¶
-
tensornet.utils.
set_seed
(seed: int, cuda: bool)[source]¶ Set seed to make the results reproducible.
- Parameters
seed (int) – Random seed value.
cuda (bool) – Whether CUDA is available.
-
tensornet.utils.
initialize_cuda
(seed: int) → Tuple[bool, torch.device][source]¶ Check if GPU is availabe and set seed.
- Parameters
seed (int) – Random seed value.
- Returns
2-element tuple containing
(bool): if cuda is available
(torch.device): device name
-
tensornet.utils.
get_predictions
(model: torch.nn.modules.module.Module, loader: torch.utils.data.dataloader.DataLoader, device: Union[str, torch.device], sample_count: int = 25)[source]¶ Get correct and incorrect model predictions.
- Parameters
model (torch.nn.Module) – Model Instance.
loader (torch.utils.data.DataLoader) – Data Loader.
device (
str
ortorch.device
) – Device where data will be loaded.(obj (sample_count) – int, optional): Total number of predictions to store from each correct and incorrect samples. (default: 25)
-
tensornet.utils.
class_level_accuracy
(model: torch.nn.modules.module.Module, loader: torch.utils.data.dataloader.DataLoader, device: Union[str, torch.device], classes: Union[List[str], Tuple[str]])[source]¶ Print test accuracy for each class in dataset.
- Parameters
model (torch.nn.Module) – Model Instance.
loader (torch.utils.data.DataLoader) – Data Loader.
device (
str
ortorch.device
) – Device where data will be loaded.classes (
list
ortuple
) – List of classes in the dataset.
-
tensornet.utils.
plot_metric
(data: Union[List[float], Dict[str, List[float]]], metric: str, title: str = None, size: Tuple[int] = 7, 5, legend_font: int = 15, legend_loc: str = 'lower right')[source]¶ Plot accuracy graph or loss graph.
- Parameters
data (
list
ordict
) – If only single plot then this is a list, else for multiple plots this is a dict with keys containing the plot name and values being a list of points to plot.metric (str) – Metric name which is to be plotted. Can be either loss or accuracy.
title (
str
, optional) – Title of the plot, if no title given then it is determined from the x and y label.size (
tuple
, optional) – Size of the plot. (default: ‘(7, 5)’)legend_loc (
str
, optional) – Location of the legend box in the plot. No legend will be plotted if there is only a single plot. (default: ‘lower right’)legend_font (
int
, optional) – Font size of the legend (default: ‘15’)
-
tensornet.utils.
plot_predictions
(data: List[dict], classes: Union[List[str], Tuple[str]], plot_title: str, plot_path: str)[source]¶ Display data.
- Parameters
data (list) – List of images, model predictions and ground truths. Images should be numpy arrays.
classes (
list
ortuple
) – List of classes in the dataset.plot_title (str) – Title for the plot.
plot_path (str) – Complete path for saving the plot.
-
tensornet.utils.
save_and_show_result
(classes: Union[List[str], Tuple[str]], correct_pred: Optional[List[dict]] = None, incorrect_pred: Optional[List[dict]] = None, path: Optional[str] = None)[source]¶ Display network predictions.
- Parameters
classes (
list
ortuple
) – List of classes in the dataset.correct_pred (
list
, optional) – Contains correct model predictions and labels.incorrect_pred (
list
, optional) – Contains incorrect model predictions and labels.path (
str
, optional) – Path where the results will be saved.
Model Utilities¶
Utility methods used by classes and methods present in the Models
section.
-
tensornet.models.utils.
summary
(model: torch.nn.modules.module.Module, input_size: Union[Tuple[int], List[int], Dict[str, Union[tuple, list]]], batch_size: int = - 1, dtypes: Optional = None)[source]¶ Display model summary.
- Parameters
model (torch.nn.Module) – Model instance.
input_size (
tuple
,list
ordict
) – Input size for the model.batch_size (
int
, optional) – Batch size. (default: -1)dtypes (optional) – Model input data types.
Data Utilities¶
Utility methods used by classes and methods present in the Data
section.
-
tensornet.data.utils.
unnormalize
(image, mean, std, transpose=False)[source]¶ Un-normalize a given image.
- Parameters
image (
numpy.ndarray
ortorch.Tensor
) – A ndarray or tensor. If tensor, it should be in CPU.mean (
float
ortuple
) – Mean. It can be a single value or a tuple with 3 values (one for each channel).std (
float
ortuple
) – Standard deviation. It can be a single value or a tuple with 3 values (one for each channel).transpose (
bool
, optional) – If True, transposed output will be returned. This param is effective only when image is a tensor. If tensor, the output will have channel number as the last dim. (default: False)
- Returns
Unnormalized image
- Return type
(numpy.ndarray or torch.Tensor)
-
tensornet.data.utils.
normalize
(image, mean, std, transpose=False)[source]¶ Normalize a given image.
- Parameters
image (
numpy.ndarray
ortorch.Tensor
) – A ndarray or tensor. If tensor, it should be in CPU.mean (
float
ortuple
) – Mean. It can be a single value or a tuple with 3 values (one for each channel).std (
float
ortuple
) – Standard deviation. It can be a single value or a tuple with 3 values (one for each channel).transpose (
bool
, optional) – If True, transposed output will be returned. This param is effective only when image is a tensor. If tensor, the output will have channel number as the last dim. (default: False)
- Returns
Normalized image
- Return type
(numpy.ndarray or torch.Tensor)
Contact/Getting Help¶
If you need any help or want to report a bug, raise an issue in the repo.