resnet

Module containing ResNets adapted for use in minerva.

class ResNet(block: Type[BasicBlock | Bottleneck], layers: list[int] | tuple[int, int, int, int], in_channels: int = 3, n_classes: int = 8, zero_init_residual: bool = False, groups: int = 1, width_per_group: int = 64, replace_stride_with_dilation: tuple[bool, bool, bool] | None = None, norm_layer: Callable[[...], Module] | None = None, encoder: bool = False)

Modified version of the ResNet network to handle multi-spectral inputs and cross-entropy.

encoder_on

Whether to initialise the ResNet as an encoder or end-to-end classifier. If True, forward method returns the output of each layer block. avgpool and fc are not initialised. If False, adds a global average pooling layer after the last block, flattens the output and passes through a fully connected layer for classification output.

Type:: bool

inplanes

Number of input feature maps. Initially set to 64.

Type:: int

dilation

Dilation factor of convolutions. Initially set to 1.

Type:: int

groups

Number of convolutions in grouped convolutions of Bottleneck Blocks.

Type:: int

base_width

Modifies the number of feature maps in convolutional layers of Bottleneck Blocks.

Type:: int

conv1

Input convolutional layer of Conv1 input block to the network.

Type:: Conv2d

bn1

Batch normalisation layer of the Conv1 input block to the network.

Type:: Module

relu

Rectified Linear Unit (ReLU) activation layer to be used throughout ResNet.

Type:: ReLU

maxpool

3x3 Max-pooling layer with stride 2 of the Conv1 input block to the network.

Type:: MaxPool2d

layer1

Layer 1 of the ResNet comprising number and type of blocks defined by layers.

Type:: Sequential

layer2

Layer 2 of the ResNet comprising number and type of blocks defined by layers.

Type:: Sequential

layer3

Layer 3 of the ResNet comprising number and type of blocks defined by layers.

Type:: Sequential

layer4

Layer 4 of the ResNet comprising number and type of blocks defined by layers.

Type:: Sequential

avgpool

Global average pooling layer taking the output from the last block. Only initialised if encoder_on=False.

Type:: AdaptiveAvgPool2d

fc

Fully connected layer that takes the flattened output from average pooling to a classification output. Only initialised if encoder_on=False.

Type:: Linear

Warning

Layers using BasicBlock are not compatible with anything other than the default values for groups and width_per_group.

Parameters:

block (BasicBlock | Bottleneck) – Type of block operations to use throughout network.
layers (list[int] | tuple[int, int, int, int]) – Number of blocks in each of the 4 layers.
in_channels (int) – Optional; Number of channels (or bands) in the input imagery.
n_classes (int) – Optional; Number of classes in data to be classified.
zero_init_residual (bool) – Optional; If True, zero-initialise the last BN in each residual branch, so that the residual branch starts with zeros, and each residual block behaves like an identity.
groups (int) – Optional; Number of convolutions in grouped convolutions of Bottleneck Blocks. Not compatible with Basic Block!
width_per_group (int) – Optional; Modifies the number of feature maps in convolutional layers of Bottleneck Blocks. Not compatible with Basic Block!
replace_stride_with_dilation (tuple[bool, bool, bool]) – Optional; Each element in the tuple indicates whether to replace the 2x2 stride with a dilated convolution instead. Must be a three element tuple of bools.
norm_layer (Callable[..., Module]) – Optional; Normalisation layer to use in each block. Typically, BatchNorm2d.
encoder (bool) – Optional; Whether to initialise the ResNet as an encoder or end-to-end classifier. If True, forward method returns the output of each layer block. avgpool and fc are not initialised. If False, adds a global average pooling layer after the last block, flattens the output and passes through a fully connected layer for classification output.

Raises:

ValueError – If replace_stride_with_dilation is not None or a 3-element tuple.

forward(x: Tensor) → Tensor | tuple[Tensor, Tensor, Tensor, Tensor, Tensor]

Performs a forward pass of the ResNet.

Can be called directly as a method (e.g. model.forward) or when data is parsed to model (e.g. model()).

Parameters:: x (Tensor) – Input data to network.
Returns:: If initialised as an encoder, returns a tuple of outputs from each layer 1-4. Else, returns Tensor of the likelihoods the network places on the input x being of each class.
Return type:: Tensor | tuple[Tensor, Tensor, Tensor, Tensor, Tensor]

class ResNet101(criterion: Any | None = None, input_size: tuple[int, int, int] = (4, 256, 256), n_classes: int = 8, zero_init_residual: bool = False, groups: int = 1, width_per_group: int = 64, replace_stride_with_dilation: tuple[bool, bool, bool] | None = None, norm_layer: Callable[[...], Module] | None = None, encoder: bool = False, torch_weights: bool = False)

ResNet101 modified from source to have customisable number of input channels and to be used as a backbone by stripping classification layers away.

block_type: alias of Bottleneck

class ResNet152(criterion: Any | None = None, input_size: tuple[int, int, int] = (4, 256, 256), n_classes: int = 8, zero_init_residual: bool = False, groups: int = 1, width_per_group: int = 64, replace_stride_with_dilation: tuple[bool, bool, bool] | None = None, norm_layer: Callable[[...], Module] | None = None, encoder: bool = False, torch_weights: bool = False)

ResNet152 modified from source to have customisable number of input channels and to be used as a backbone by stripping classification layers away.

block_type: alias of Bottleneck

class ResNet18(criterion: Any | None = None, input_size: tuple[int, int, int] = (4, 256, 256), n_classes: int = 8, zero_init_residual: bool = False, groups: int = 1, width_per_group: int = 64, replace_stride_with_dilation: tuple[bool, bool, bool] | None = None, norm_layer: Callable[[...], Module] | None = None, encoder: bool = False, torch_weights: bool = False): ResNet18 modified from source to have customisable number of input channels and to be used as a backbone by stripping classification layers away.

class ResNet34(criterion: Any | None = None, input_size: tuple[int, int, int] = (4, 256, 256), n_classes: int = 8, zero_init_residual: bool = False, groups: int = 1, width_per_group: int = 64, replace_stride_with_dilation: tuple[bool, bool, bool] | None = None, norm_layer: Callable[[...], Module] | None = None, encoder: bool = False, torch_weights: bool = False): ResNet34 modified from source to have customisable number of input channels and to be used as a backbone by stripping classification layers away.

class ResNet50(criterion: Any | None = None, input_size: tuple[int, int, int] = (4, 256, 256), n_classes: int = 8, zero_init_residual: bool = False, groups: int = 1, width_per_group: int = 64, replace_stride_with_dilation: tuple[bool, bool, bool] | None = None, norm_layer: Callable[[...], Module] | None = None, encoder: bool = False, torch_weights: bool = False)

ResNet50 modified from source to have customisable number of input channels and to be used as a backbone by stripping classification layers away.

block_type: alias of Bottleneck

class ResNetX(criterion: Any | None = None, input_size: tuple[int, int, int] = (4, 256, 256), n_classes: int = 8, zero_init_residual: bool = False, groups: int = 1, width_per_group: int = 64, replace_stride_with_dilation: tuple[bool, bool, bool] | None = None, norm_layer: Callable[[...], Module] | None = None, encoder: bool = False, torch_weights: bool = False)

Helper class to allow for easy creation of ResNet variant classes of the base ResNet class.

Example

To build a ResNet variant class, just simply set the appropiate attributes in the definition of your new variant class that inherits from ResNetX.

>>> from minerva.models import ResNetX
>>> from torchvision.models.resnet import Bottleneck
>>>
>>> class MyResNet101(ResNetX):
>>>     layer_struct = [3, 4, 23, 3]
>>>     block_type = BottleNeck
>>>     weights_name = "ResNet101_Weights.IMAGENET1K_V1"

You can then construct an instance of your new class like any other ResNet with the added bonus of being able to use pre-trained torch weights:

>>> model = ResNet101(*args, **kwargs, torch_weights=True)

block_type

Type of the block used to construct the ResNet layers.

Type:: BasicBlock | Bottleneck

layer_struct

Number of layers per block in the ResNet.

Type:: list[int]

weights_name

Name of the torch pre-trained weights to use if torch_weights==True.

Type:: str

network

ResNet network.

Type:: ResNet

Parameters:

criterion – torch loss function model will use.
input_size (tuple[int, int, int]) – Optional; Defines the shape of the input data in order of number of channels, image width, image height.
n_classes (int) – Optional; Number of classes in data to be classified.
zero_init_residual (bool) – Optional; If True, zero-initialise the last BN in each residual branch, so that the residual branch starts with zeros, and each residual block behaves like an identity.
replace_stride_with_dilation (tuple[bool, bool, bool]) – Optional; Each element in the tuple indicates whether to replace the 2x2 stride with a dilated convolution instead. Must be a three element tuple of bools.
norm_layer (Callable[..., Module]) – Optional; Normalisation layer to use in each block. Typically BatchNorm2d.
encoder (bool) – Optional; Whether to initialise the ResNet as an encoder or end-to-end classifier. If True, forward method returns the output of each layer block. avgpool and fc are not initialised. If False, adds a global average pooling layer after the last block, flattens the output and passes through a fully connected layer for classification output.
torch_weights (bool) – Optional; Whether to use the pre-trained weights from torchvision. See note.

Note

If using torch_weights, the weight state_dict is modified to remove incompatible layers (such as the conv1 layer) if input_size is non-RGB (i.e not 3-channel) and/or images smaller than 224x224 with the randomly initialised conv1 that is appropiate for input_size.

block_type: alias of BasicBlock

forward(x: Tensor) → Tensor | tuple[Tensor, Tensor, Tensor, Tensor, Tensor]

Performs a forward pass of the ResNet.

Can be called directly as a method (e.g. model.forward()) or when data is parsed to model (e.g. model()).

Parameters:: x (Tensor) – Input data to network.
Returns:: If initialised as an encoder, returns a tuple of outputs from each layer 1-4. Else, returns Tensor of the likelihoods the network places on the input x being of each class.
Return type:: Tensor | tuple[Tensor, Tensor, Tensor, Tensor, Tensor]