CNN / TCN Models

Convolutional and temporal convolutional network architectures for time series.

CNN

CNN(input_size: int, output_size: int, hl_depth: int = 1, hl_width: int = 10, act: type[Module] = Mish, bn: bool = False)

Bases: Module

Simple stacked 1D CNN with a pointwise output projection.

Parameters:

Name	Type	Description	Default
input_size	int	Number of input channels.	required
output_size	int	Number of output channels.	required
hl_depth	int	Number of hidden convolutional layers.	1
hl_width	int	Number of channels in each hidden layer.	10
act	type[Module]	Activation function class.	Mish
bn	bool	Whether to apply batch normalization.	False

Source code in tsfast/models/architectures/cnn.py

def __init__(
    self,
    input_size: int,
    output_size: int,
    hl_depth: int = 1,
    hl_width: int = 10,
    act: type[nn.Module] = Mish,
    bn: bool = False,
):
    super().__init__()

    conv_layers = [
        Conv1D(input_size if i == 0 else hl_width, hl_width, bn=bn, activation=act, padding=1)
        for i in range(hl_depth)
    ]
    self.conv_layers = nn.Sequential(*conv_layers)
    self.final = nn.Conv1d(hl_width, output_size, kernel_size=1)

CausalConv1d

CausalConv1d(in_channels: int, out_channels: int, kernel_size: int, stride: int = 1, dilation: int = 1, groups: int = 1, bias: bool = True)

Bases: Conv1d

Causal 1D convolution that pads only on the left to prevent future leakage.

Parameters:

Name	Type	Description	Default
in_channels	int	Number of input channels.	required
out_channels	int	Number of output channels.	required
kernel_size	int	Size of the convolving kernel.	required
stride	int	Stride of the convolution.	1
dilation	int	Dilation factor for the kernel.	1
groups	int	Number of blocked connections from input to output channels.	1
bias	bool	Whether to add a learnable bias.	True

Source code in tsfast/models/architectures/cnn.py

def __init__(
    self,
    in_channels: int,
    out_channels: int,
    kernel_size: int,
    stride: int = 1,
    dilation: int = 1,
    groups: int = 1,
    bias: bool = True,
):
    super().__init__(
        in_channels,
        out_channels,
        kernel_size=kernel_size,
        stride=stride,
        padding=0,
        dilation=dilation,
        groups=groups,
        bias=bias,
    )
    self.__init_size = (kernel_size - 1) * dilation

TCN_Block

TCN_Block(input_size: int, output_size: int, num_layers: int = 1, activation: type[Module] | None = Mish, wn: bool = True, bn: bool = False, dropout: float = 0.0, **kwargs: Any)

Bases: Module

Single TCN residual block with stacked causal convolutions.

Parameters:

Name	Type	Description	Default
input_size	int	Number of input channels.	required
output_size	int	Number of output channels.	required
num_layers	int	Number of causal convolution layers in the block.	1
activation	type[Module] | None	Activation function class, or None to disable.	Mish
wn	bool	Whether to apply weight normalization. Redundant when bn is set, since batch norm cancels the weight magnitude that weight norm parametrizes.	True
bn	bool	Whether to apply batch normalization after each convolution.	False
dropout	float	Dropout probability applied after each activation, or 0 to disable.	0.0
**kwargs	Any	Additional arguments passed to CausalConv1d.	{}

Source code in tsfast/models/architectures/cnn.py

def __init__(
    self,
    input_size: int,
    output_size: int,
    num_layers: int = 1,
    activation: type[nn.Module] | None = Mish,
    wn: bool = True,
    bn: bool = False,
    dropout: float = 0.0,
    **kwargs: Any,
):
    super().__init__()

    layers = []
    for i in range(num_layers):
        conv = CausalConv1d(input_size if i == 0 else output_size, output_size, 2, **kwargs)
        if wn:
            conv = weight_norm(conv)
        norm = nn.BatchNorm1d(output_size) if bn else None
        act = activation() if activation is not None else None
        drop = nn.Dropout(dropout) if dropout > 0 else None
        layers += [m for m in [conv, norm, act, drop] if m is not None]

    self.layers = nn.Sequential(*layers)

    self.residual = nn.Conv1d(input_size, output_size, kernel_size=1) if output_size != input_size else None

TCN

TCN(input_size: int, output_size: int, hl_depth: int = 1, hl_width: int = 10, act: type[Module] = Mish, bn: bool = False, layers_per_block: int = 1, dropout: float = 0.0)

Bases: Module

Temporal Convolutional Network with exponentially increasing dilation.

Parameters:

Name	Type	Description	Default
input_size	int	Number of input channels.	required
output_size	int	Number of output channels.	required
hl_depth	int	Number of TCN blocks (each with doubled dilation).	1
hl_width	int	Number of channels in each hidden TCN block.	10
act	type[Module]	Activation function class.	Mish
bn	bool	Whether to apply batch normalization.	False
layers_per_block	int	Number of causal convolution layers within each TCN block.	1
dropout	float	Dropout probability applied after each activation, or 0 to disable.	0.0

Source code in tsfast/models/architectures/cnn.py

def __init__(
    self,
    input_size: int,
    output_size: int,
    hl_depth: int = 1,
    hl_width: int = 10,
    act: type[nn.Module] = Mish,
    bn: bool = False,
    layers_per_block: int = 1,
    dropout: float = 0.0,
):
    super().__init__()

    conv_layers = [
        TCN_Block(
            input_size if i == 0 else hl_width,
            hl_width,
            num_layers=layers_per_block,
            dilation=2 ** (i),
            bn=bn,
            activation=act,
            dropout=dropout,
        )
        for i in range(hl_depth)
    ]
    self.conv_layers = nn.Sequential(*conv_layers)
    self.final = nn.Conv1d(hl_width, output_size, kernel_size=1)

SeperateTCN

SeperateTCN(input_list: list[int], output_size: int, hl_depth: int = 1, hl_width: int = 10, act: type[Module] = Mish, bn: bool = False, final_layer: int = 3, layers_per_block: int = 1, dropout: float = 0.0)

Bases: Module

TCN with separate convolutional branches per input group, merged by a linear head.

Parameters:

Name	Type	Description	Default
input_list	list[int]	List of channel counts, one per input group.	required
output_size	int	Number of output channels.	required
hl_depth	int	Number of TCN blocks per branch.	1
hl_width	int	Total hidden width split evenly across branches.	10
act	type[Module]	Activation function class.	Mish
bn	bool	Whether to apply batch normalization.	False
final_layer	int	Number of hidden layers in the final linear head.	3
layers_per_block	int	Number of causal convolution layers within each TCN block.	1
dropout	float	Dropout probability applied after each activation, or 0 to disable.	0.0

Source code in tsfast/models/architectures/cnn.py

def __init__(
    self,
    input_list: list[int],
    output_size: int,
    hl_depth: int = 1,
    hl_width: int = 10,
    act: type[nn.Module] = Mish,
    bn: bool = False,
    final_layer: int = 3,
    layers_per_block: int = 1,
    dropout: float = 0.0,
):
    super().__init__()
    self.input_list = np.cumsum([0] + input_list)

    tcn_width = hl_width // len(input_list)
    layers = [
        [
            TCN_Block(
                n if i == 0 else tcn_width,
                tcn_width,
                num_layers=layers_per_block,
                dilation=2 ** (i),
                bn=bn,
                activation=act,
                dropout=dropout,
            )
            for i in range(hl_depth)
        ]
        for n in input_list
    ]
    self.layers = nn.ModuleList([nn.Sequential(*layer) for layer in layers])

    self.final = SeqLinear(tcn_width * len(input_list), output_size, hidden_size=hl_width, hidden_layer=final_layer)

CRNN

CRNN(input_size: int, output_size: int, num_ft: int = 10, num_cnn_layers: int = 4, num_rnn_layers: int = 2, hs_cnn: int = 10, hs_rnn: int = 10, hidden_p: float = 0, input_p: float = 0, weight_p: float = 0, rnn_type: str = 'gru')

Bases: Module

Convolutional-Recurrent Neural Network combining a TCN front-end with an RNN back-end.

Parameters:

Name	Type	Description	Default
input_size	int	Number of input channels.	required
output_size	int	Number of output channels.	required
num_ft	int	Number of intermediate features between the CNN and RNN stages.	10
num_cnn_layers	int	Number of TCN blocks in the convolutional stage.	4
num_rnn_layers	int	Number of stacked RNN layers.	2
hs_cnn	int	Hidden channel width of the TCN stage.	10
hs_rnn	int	Hidden size of the RNN stage.	10
hidden_p	float	Dropout probability on RNN hidden-to-hidden connections.	0
input_p	float	Dropout probability on RNN inputs.	0
weight_p	float	Weight dropout probability for RNN parameters.	0
rnn_type	str	RNN cell type ("gru" or "lstm").	'gru'

Source code in tsfast/models/architectures/cnn.py

def __init__(
    self,
    input_size: int,
    output_size: int,
    num_ft: int = 10,
    num_cnn_layers: int = 4,
    num_rnn_layers: int = 2,
    hs_cnn: int = 10,
    hs_rnn: int = 10,
    hidden_p: float = 0,
    input_p: float = 0,
    weight_p: float = 0,
    rnn_type: str = "gru",
):
    super().__init__()
    self.cnn = TCN(input_size, num_ft, num_cnn_layers, hs_cnn, act=nn.ReLU)
    self.rnn = SimpleRNN(
        num_ft,
        output_size,
        num_layers=num_rnn_layers,
        hidden_size=hs_rnn,
        hidden_p=hidden_p,
        input_p=input_p,
        weight_p=weight_p,
        rnn_type=rnn_type,
    )

SeperateCRNN

SeperateCRNN(input_list: list[int], output_size: int, num_ft: int = 10, num_cnn_layers: int = 4, num_rnn_layers: int = 2, hs_cnn: int = 10, hs_rnn: int = 10, hidden_p: float = 0, input_p: float = 0, weight_p: float = 0, rnn_type: str = 'gru')

Bases: Module

CRNN with separate TCN branches per input group, merged before the RNN stage.

Parameters:

Name	Type	Description	Default
input_list	list[int]	List of channel counts, one per input group.	required
output_size	int	Number of output channels.	required
num_ft	int	Number of intermediate features between the CNN and RNN stages.	10
num_cnn_layers	int	Number of TCN blocks per branch in the convolutional stage.	4
num_rnn_layers	int	Number of stacked RNN layers.	2
hs_cnn	int	Hidden channel width of the TCN branches.	10
hs_rnn	int	Hidden size of the RNN stage.	10
hidden_p	float	Dropout probability on RNN hidden-to-hidden connections.	0
input_p	float	Dropout probability on RNN inputs.	0
weight_p	float	Weight dropout probability for RNN parameters.	0
rnn_type	str	RNN cell type ("gru" or "lstm").	'gru'

Source code in tsfast/models/architectures/cnn.py

def __init__(
    self,
    input_list: list[int],
    output_size: int,
    num_ft: int = 10,
    num_cnn_layers: int = 4,
    num_rnn_layers: int = 2,
    hs_cnn: int = 10,
    hs_rnn: int = 10,
    hidden_p: float = 0,
    input_p: float = 0,
    weight_p: float = 0,
    rnn_type: str = "gru",
):
    super().__init__()
    self.cnn = SeperateTCN(input_list, num_ft, num_cnn_layers, hs_cnn, act=nn.ReLU, final_layer=0)
    self.rnn = SimpleRNN(
        num_ft,
        output_size,
        num_layers=num_rnn_layers,
        hidden_size=hs_rnn,
        hidden_p=hidden_p,
        input_p=input_p,
        weight_p=weight_p,
        rnn_type=rnn_type,
    )

Conv1D

Conv1D(input_size: int, output_size: int, kernel_size: int = 3, activation: type[Module] | None = Mish, wn: bool = True, bn: bool = False, **kwargs: Any) -> nn.Sequential

Create a 1D convolutional block with optional activation and batch norm.

Parameters:

Name	Type	Description	Default
input_size	int	Number of input channels.	required
output_size	int	Number of output channels.	required
kernel_size	int	Size of the convolving kernel.	3
activation	type[Module] | None	Activation function class, or None to disable.	Mish
wn	bool	Accepted for signature parity with CConv1D; weight norm is not applied.	True
bn	bool	Whether to apply batch normalization after the convolution.	False
**kwargs	Any	Additional arguments passed to nn.Conv1d.	{}

Source code in tsfast/models/architectures/cnn.py

def Conv1D(
    input_size: int,
    output_size: int,
    kernel_size: int = 3,
    activation: type[nn.Module] | None = Mish,
    wn: bool = True,
    bn: bool = False,
    **kwargs: Any,
) -> nn.Sequential:
    """Create a 1D convolutional block with optional activation and batch norm.

    Args:
        input_size: Number of input channels.
        output_size: Number of output channels.
        kernel_size: Size of the convolving kernel.
        activation: Activation function class, or None to disable.
        wn: Accepted for signature parity with ``CConv1D``; weight norm is not applied.
        bn: Whether to apply batch normalization after the convolution.
        **kwargs: Additional arguments passed to ``nn.Conv1d``.
    """
    conv = nn.Conv1d(input_size, output_size, kernel_size, **kwargs)
    norm = nn.BatchNorm1d(output_size) if bn else None
    act = activation() if activation is not None else None
    m = [m for m in [conv, norm, act] if m is not None]
    return nn.Sequential(*m)

CConv1D

CConv1D(input_size: int, output_size: int, kernel_size: int = 2, activation: type[Module] | None = Mish, wn: bool = True, bn: bool = False, **kwargs: Any) -> nn.Sequential

Create a causal 1D convolutional block with optional weight norm and batch norm.

Parameters:

Name	Type	Description	Default
input_size	int	Number of input channels.	required
output_size	int	Number of output channels.	required
kernel_size	int	Size of the convolving kernel.	2
activation	type[Module] | None	Activation function class, or None to disable.	Mish
wn	bool	Whether to apply weight normalization. Redundant when bn is set, since batch norm cancels the weight magnitude that weight norm parametrizes.	True
bn	bool	Whether to apply batch normalization after the convolution.	False
**kwargs	Any	Additional arguments passed to CausalConv1d.	{}

Source code in tsfast/models/architectures/cnn.py

def CConv1D(
    input_size: int,
    output_size: int,
    kernel_size: int = 2,
    activation: type[nn.Module] | None = Mish,
    wn: bool = True,
    bn: bool = False,
    **kwargs: Any,
) -> nn.Sequential:
    """Create a causal 1D convolutional block with optional weight norm and batch norm.

    Args:
        input_size: Number of input channels.
        output_size: Number of output channels.
        kernel_size: Size of the convolving kernel.
        activation: Activation function class, or None to disable.
        wn: Whether to apply weight normalization. Redundant when ``bn`` is set, since
            batch norm cancels the weight magnitude that weight norm parametrizes.
        bn: Whether to apply batch normalization after the convolution.
        **kwargs: Additional arguments passed to ``CausalConv1d``.
    """
    conv = CausalConv1d(input_size, output_size, kernel_size, **kwargs)
    if wn:
        conv = weight_norm(conv)
    norm = nn.BatchNorm1d(output_size) if bn else None
    act = activation() if activation is not None else None
    m = [m for m in [conv, norm, act] if m is not None]
    return nn.Sequential(*m)