ml4gw 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

ml4gw/nn/resnet/resnet_2d.py

@@ -0,0 +1,413 @@
+"""
+In large part lifted from
+https://github.com/pytorch/vision/blob/main/torchvision/models/resnet.py
+but with arbitrary kernel sizes
+"""
+
+from typing import Callable, List, Literal, Optional
+
+import torch
+import torch.nn as nn
+from torch import Tensor
+
+from ml4gw.nn.norm import GroupNorm2DGetter, NormLayer
+
+
+def convN(
+    in_planes: int,
+    out_planes: int,
+    kernel_size: int = 3,
+    stride: int = 1,
+    groups: int = 1,
+    dilation: int = 1,
+) -> nn.Conv2d:
+    """2d convolution with padding"""
+    if not kernel_size % 2:
+        raise ValueError("Can't use even sized kernels")
+
+    return nn.Conv2d(
+        in_planes,
+        out_planes,
+        kernel_size=kernel_size,
+        stride=stride,
+        padding=dilation * int(kernel_size // 2),
+        groups=groups,
+        bias=False,
+        dilation=dilation,
+    )
+
+
+def conv1(in_planes: int, out_planes: int, stride: int = 1) -> nn.Conv2d:
+    """Kernel-size 1 convolution"""
+    return nn.Conv2d(
+        in_planes, out_planes, kernel_size=1, stride=stride, bias=False
+    )
+
+
+class BasicBlock(nn.Module):
+    """Defines the structure of the blocks used to build the ResNet"""
+
+    expansion: int = 1
+
+    def __init__(
+        self,
+        inplanes: int,
+        planes: int,
+        kernel_size: int = 3,
+        stride: int = 1,
+        downsample: Optional[nn.Module] = None,
+        groups: int = 1,
+        base_width: int = 64,
+        dilation: int = 1,
+        norm_layer: Optional[Callable[..., nn.Module]] = None,
+    ) -> None:
+
+        super().__init__()
+        if norm_layer is None:
+            norm_layer = nn.BatchNorm2d
+        if groups != 1 or base_width != 64:
+            raise ValueError(
+                "BasicBlock only supports groups=1 and base_width=64"
+            )
+        if dilation > 1:
+            raise NotImplementedError(
+                "Dilation > 1 not supported in BasicBlock"
+            )
+
+        # Both self.conv1 and self.downsample layers
+        # downsample the input when stride != 1
+        self.conv1 = convN(inplanes, planes, kernel_size, stride)
+        self.bn1 = norm_layer(planes)
+        self.relu = nn.ReLU(inplace=True)
+        self.conv2 = convN(planes, planes, kernel_size)
+        self.bn2 = norm_layer(planes)
+        self.downsample = downsample
+        self.stride = stride
+
+    def forward(self, x: Tensor) -> Tensor:
+        identity = x
+
+        out = self.conv1(x)
+        out = self.bn1(out)
+        out = self.relu(out)
+
+        out = self.conv2(out)
+        out = self.bn2(out)
+
+        if self.downsample is not None:
+            identity = self.downsample(x)
+
+        out += identity
+        out = self.relu(out)
+
+        return out
+
+
+class Bottleneck(nn.Module):
+    """
+    Bottleneck blocks implement one extra convolution
+    compared to basic blocks. In this layers, the `planes`
+    parameter is generally meant to _downsize_ the number
+    of feature maps first, which then get expanded out to
+    `planes * Bottleneck.expansion` feature maps at the
+    output of the layer.
+    """
+
+    expansion: int = 4
+
+    def __init__(
+        self,
+        inplanes: int,
+        planes: int,
+        kernel_size: int = 3,
+        stride: int = 1,
+        downsample: Optional[nn.Module] = None,
+        groups: int = 1,
+        base_width: int = 64,
+        dilation: int = 1,
+        norm_layer: Optional[Callable[..., nn.Module]] = None,
+    ) -> None:
+        super().__init__()
+        if norm_layer is None:
+            norm_layer = nn.BatchNorm2d
+
+        width = int(planes * (base_width / 64.0)) * groups
+
+        # conv1 does no downsampling, just reduces the number of
+        # feature maps from inplanes to width (where width == planes)
+        # if groups == 1 and base_width == 64
+        self.conv1 = convN(inplanes, width, kernel_size)
+        self.bn1 = norm_layer(width)
+
+        # conv2 keeps the same number of feature maps,
+        # but downsamples along the time axis if stride
+        # or dilation > 1
+        self.conv2 = convN(width, width, kernel_size, stride, groups, dilation)
+        self.bn2 = norm_layer(width)
+
+        # conv3 expands the feature maps back out to planes * expansion
+        self.conv3 = conv1(width, planes * self.expansion)
+        self.bn3 = norm_layer(planes * self.expansion)
+
+        self.relu = nn.ReLU(inplace=True)
+        self.downsample = downsample
+        self.stride = stride
+
+    def forward(self, x: Tensor) -> Tensor:
+        identity = x
+
+        out = self.conv1(x)
+        out = self.bn1(out)
+        out = self.relu(out)
+
+        out = self.conv2(out)
+        out = self.bn2(out)
+        out = self.relu(out)
+
+        out = self.conv3(out)
+        out = self.bn3(out)
+
+        if self.downsample is not None:
+            identity = self.downsample(x)
+
+        out += identity
+        out = self.relu(out)
+
+        return out
+
+
+class ResNet2D(nn.Module):
+    """2D ResNet architecture
+
+    Simple extension of ResNet with arbitrary kernel sizes
+    to support the longer timeseries used in BBH detection.
+
+    Args:
+        in_channels:
+            The number of channels in input tensor.
+        layers:
+            A list representing the number of residual
+            blocks to include in each "layer" of the
+            network. Total layers (e.g. 50 in ResNet50)
+            is `2 + sum(layers) * factor`, where factor
+            is `2` for vanilla `ResNet` and `3` for
+            `BottleneckResNet`.
+        kernel_size:
+            The size of the convolutional kernel to
+            use in all residual layers. _NOT_ the size
+            of the input kernel to the network, which
+            is determined at run-time.
+        zero_init_residual:
+            Flag indicating whether to initialize the
+            weights of the batch-norm layer in each block
+            to 0 so that residuals are initialized as
+            identities. Can improve training results.
+        groups:
+            Number of convolutional groups to use in all
+            layers. Grouped convolutions induce local
+            connections between feature maps at subsequent
+            layers rather than global. Generally won't
+            need this to be >1, and wil raise an error if
+            >1 when using vanilla `ResNet`.
+        width_per_group:
+            Base width of each of the feature map groups,
+            which is scaled up by the typical expansion
+            factor at each layer of the network. Meaningless
+            for vanilla `ResNet`.
+        stride_type:
+            Whether to achieve downsampling on the time axis
+            by strided or dilated convolutions for each layer.
+            If left as `None`, strided convolutions will be
+            used at each layer. Otherwise, `stride_type` should
+            be one element shorter than `layers` and indicate either
+            `stride` or `dilation` for each layer after the first.
+        norm_groups:
+            The number of groups to use in GroupNorm layers
+            throughout the model. If left as `-1`, the number
+            of groups will be equal to the number of channels,
+            making this equilavent to LayerNorm
+    """
+
+    block = BasicBlock
+
+    def __init__(
+        self,
+        in_channels: int,
+        layers: List[int],
+        classes: int,
+        kernel_size: int = 3,
+        zero_init_residual: bool = False,
+        groups: int = 1,
+        width_per_group: int = 64,
+        stride_type: Optional[List[Literal["stride", "dilation"]]] = None,
+        norm_layer: Optional[NormLayer] = None,
+    ) -> None:
+        super().__init__()
+        # default to using InstanceNorm if no
+        # norm layer is provided explicitly
+        self._norm_layer = norm_layer or GroupNorm2DGetter()
+
+        self.inplanes = 64
+        self.dilation = 1
+
+        # TODO: should we support passing a single string
+        # for simplicity here?
+        if stride_type is None:
+            # each element in the tuple indicates if we should replace
+            # the stride with a dilated convolution instead
+            stride_type = ["stride"] * (len(layers) - 1)
+        if len(stride_type) != (len(layers) - 1):
+            raise ValueError(
+                "'stride_type' should be None or a "
+                "{}-element tuple, got {}".format(len(layers) - 1, stride_type)
+            )
+
+        self.groups = groups
+        self.base_width = width_per_group
+
+        # start with a basic conv-bn-relu-maxpool block
+        # to reduce the dimensionality before the heavy
+        # lifting starts
+        self.conv1 = nn.Conv2d(
+            in_channels,
+            self.inplanes,
+            kernel_size=7,
+            stride=2,
+            padding=3,
+            bias=False,
+        )
+        self.bn1 = self._norm_layer(self.inplanes)
+        self.relu = nn.ReLU(inplace=True)
+        self.maxpool = nn.MaxPool2d(kernel_size=3, stride=2, padding=1)
+
+        # now create layers of residual blocks where each
+        # layer uses the same number of feature maps for
+        # all its blocks (some power of 2 times 64).
+        # Don't downsample along the time axis in the first
+        # layer, but downsample in all the rest (either by
+        # striding or dilating depending on the stride_type
+        # argument)
+        residual_layers = [self._make_layer(64, layers[0], kernel_size)]
+        it = zip(layers[1:], stride_type)
+        for i, (num_blocks, stride) in enumerate(it):
+            block_size = 64 * 2 ** (i + 1)
+            layer = self._make_layer(
+                block_size,
+                num_blocks,
+                kernel_size,
+                stride=2,
+                stride_type=stride,
+            )
+            residual_layers.append(layer)
+        self.residual_layers = nn.ModuleList(residual_layers)
+
+        # Average pool over each feature map to create a
+        # single value for each feature map that we'll use
+        # in the fully connected head
+        self.avgpool = nn.AdaptiveAvgPool2d((1, 1))
+
+        # use a fully connected layer to map from the
+        # feature maps to the binary output that we need
+        self.fc = nn.Linear(block_size * self.block.expansion, classes)
+
+        for m in self.modules():
+            if isinstance(m, nn.Conv2d):
+                nn.init.kaiming_normal_(
+                    m.weight, mode="fan_out", nonlinearity="relu"
+                )
+            elif isinstance(m, (nn.BatchNorm2d, nn.GroupNorm)):
+                nn.init.constant_(m.weight, 1)
+                nn.init.constant_(m.bias, 0)
+
+        # Zero-initialize the last BN in each residual branch,
+        # so that the residual branch starts with zeros,
+        # and each residual block behaves like an identity.
+        # This improves the model by 0.2~0.3% according to
+        # https://arxiv.org/abs/1706.02677
+        if zero_init_residual:
+            for m in self.modules():
+                if isinstance(m, Bottleneck):
+                    nn.init.constant_(m.bn3.weight, 0)
+                elif isinstance(m, BasicBlock):
+                    nn.init.constant_(m.bn2.weight, 0)
+
+    def _make_layer(
+        self,
+        planes: int,
+        blocks: int,
+        kernel_size: int = 3,
+        stride: int = 1,
+        stride_type: Literal["stride", "dilation"] = "stride",
+    ) -> nn.Sequential:
+        block = self.block
+        norm_layer = self._norm_layer
+        downsample = None
+        previous_dilation = self.dilation
+
+        if stride_type == "dilation":
+            self.dilation *= stride
+            stride = 1
+        elif stride_type != "stride":
+            raise ValueError("Unknown stride type {stride}")
+
+        if stride != 1 or self.inplanes != planes * block.expansion:
+            downsample = nn.Sequential(
+                conv1(self.inplanes, planes * block.expansion, stride),
+                norm_layer(planes * block.expansion),
+            )
+
+        layers = []
+        layers.append(
+            block(
+                self.inplanes,
+                planes,
+                kernel_size,
+                stride,
+                downsample,
+                self.groups,
+                self.base_width,
+                previous_dilation,
+                norm_layer,
+            )
+        )
+        self.inplanes = planes * block.expansion
+        for _ in range(1, blocks):
+            layers.append(
+                block(
+                    self.inplanes,
+                    planes,
+                    kernel_size,
+                    groups=self.groups,
+                    base_width=self.base_width,
+                    dilation=self.dilation,
+                    norm_layer=norm_layer,
+                )
+            )
+
+        return nn.Sequential(*layers)
+
+    def _forward_impl(self, x: Tensor) -> Tensor:
+        # See note [TorchScript super()]
+        x = self.conv1(x)
+        x = self.bn1(x)
+        x = self.relu(x)
+        x = self.maxpool(x)
+
+        for layer in self.residual_layers:
+            x = layer(x)
+
+        x = self.avgpool(x)
+        x = torch.flatten(x, 1)
+        x = self.fc(x)
+
+        return x
+
+    def forward(self, x: Tensor) -> Tensor:
+        return self._forward_impl(x)
+
+
+# TODO: implement as arg of ResNet instead?
+class BottleneckResNet2D(ResNet2D):
+    """A version of ResNet that uses bottleneck blocks"""
+
+    block = Bottleneck

ml4gw/nn/streaming/__init__.py

@@ -0,0 +1,2 @@
+from .online_average import OnlineAverager
+from .snapshotter import Snapshotter

ml4gw/nn/streaming/online_average.py

@@ -0,0 +1,121 @@
+from typing import Optional, Tuple
+
+import torch
+
+from ml4gw.utils.slicing import unfold_windows
+
+Tensor = torch.Tensor
+
+
+class OnlineAverager(torch.nn.Module):
+    """
+    Module for performing stateful online averaging of
+    batches of overlapping timeseries. At present, the
+    first `num_updates` predictions produced by this
+    model will underestimate the true average.
+
+    Args:
+        update_size:
+            The number of samples separating the timestamps
+            of subsequent inputs.
+        batch_size:
+            The number of batched inputs to expect at inference
+            time.
+        num_updates:
+            The number of steps over which to average predictions
+            before returning them.
+        num_channels:
+            The expected channel dimension of the input passed
+            to the module at inference time.
+        offset:
+            Number of samples to throw away from the front
+            edge of the kernel when averaging.
+    """
+
+    def __init__(
+        self,
+        update_size: int,
+        batch_size: int,
+        num_updates: int,
+        num_channels: int,
+        offset: Optional[int] = None,
+    ) -> None:
+        super().__init__()
+        self.update_size = update_size
+        self.num_updates = num_updates
+        self.batch_size = batch_size
+        self.num_channels = num_channels
+        self.offset = offset
+
+        # build a blank tensor into which we will embed
+        # the updated snapshot predictions at the
+        # appropriate time offset for in-batch averaging
+        self.batch_update_size = int(batch_size * update_size)
+        self.state_size = int((num_updates - 1) * update_size)
+        blank_size = self.batch_update_size + self.state_size
+        blank = torch.zeros((batch_size, num_channels, blank_size))
+        self.register_buffer("blank", blank)
+
+        # set up the indices at which the updated snapshots
+        # will be embedded into the blank tensor
+        idx = torch.arange(num_updates * update_size)
+        idx = torch.stack([idx + i * update_size for i in range(batch_size)])
+        idx = idx.view(batch_size, 1, -1).repeat(1, num_channels, 1)
+        self.register_buffer("idx", idx)
+
+        # normalization indices used to downweight the
+        # existing average at each in-batch aggregation
+        weights = torch.scatter(blank, -1, idx, 1).sum(0)
+        weight_size = int(num_updates * update_size)
+        weights = unfold_windows(weights, weight_size, update_size)
+        self.register_buffer("weights", weights)
+
+    def get_initial_state(self):
+        return torch.zeros((self.num_channels, self.state_size))
+
+    def forward(
+        self, update: torch.Tensor, state: Optional[torch.Tensor] = None
+    ) -> Tuple[torch.Tensor, torch.Tensor]:
+        if state is None:
+            state = self.get_initial_state()
+
+        # slice off the steps from this update closest
+        # to the future that we'll actually use. Divide
+        # these values by the number of updates up-front
+        # for averaging purposes.
+        start = -self.num_updates * self.update_size
+        if self.offset is not None:
+            end = -self.offset
+            start += end
+        else:
+            end = None
+        x = update[:, :, start:end] / self.num_updates
+
+        # append zeros to the state into which we
+        # can insert our updates
+        state = torch.nn.functional.pad(state, (0, self.batch_update_size))
+
+        # window the existing snapshot into overlapping
+        # segments and average them with our new updates
+        windowed = unfold_windows(state, x.size(-1), self.update_size)
+        windowed /= self.weights
+        windowed += x
+
+        # embed these windowed averages into a blank
+        # array with offsets so that we can add the
+        # overlapping bits
+        padded = torch.scatter(self.blank, -1, self.idx, windowed)
+        new_state = padded.sum(axis=0)
+
+        if self.num_updates == 1:
+            # if we don't need stateful behavior,
+            # just return the "snapshot" as-is
+            output, new_state = new_state, self.get_initial_state()
+        else:
+            # otherwise split off the values that have finished
+            # averaging and are being returned from the ones that
+            # will comprise the snapshot at the next update
+            splits = [self.batch_size, self.num_updates - 1]
+            splits = [i * self.update_size for i in splits]
+            output, new_state = torch.split(new_state, splits, dim=-1)
+        return output, new_state

ml4gw/nn/streaming/snapshotter.py

@@ -0,0 +1,121 @@
+from typing import Optional, Sequence, Tuple
+
+import torch
+
+from ml4gw.utils.slicing import unfold_windows
+
+
+class Snapshotter(torch.nn.Module):
+    """
+    Model for converting streaming state updates into
+    a batch of overlapping snaphots of a multichannel
+    timeseries. Can support multiple timeseries in a
+    single state update via the `channels_per_snapshot`
+    kwarg.
+
+    Specifically, maps tensors of shape
+    `(num_channels, batch_size * stride_size)` to a tensor
+    of shape `(batch_size, num_channels, snapshot_size)`.
+    If `channels_per_snapshot` is specified, it will return
+    `len(channels_per_snapshot)` tensors of this shape,
+    with the channel dimension replaced by the corresponding
+    value of `channels_per_snapshot`. The last tensor returned
+    at call time will be the current state that can be passed
+    to the next `forward` call.
+
+    Args:
+        num_channels:
+            Number of channels in the timeseries. If
+            `channels_per_snapshot` is not `None`,
+            this should be equal to `sum(channels_per_snapshot)`.
+        snapshot_size:
+            The size of the output snapshot windows in
+            number of samples
+        stride_size:
+            The number of samples in between each output
+            snapshot
+        batch_size:
+            The number of snapshots to produce at each
+            update. The last dimension of the input
+            tensor should have size `batch_size * stride_size`.
+        channels_per_snapshot:
+            How to split up the channels in the timeseries
+            for different tensors. If left as `None`, all
+            the channels will be returned in a single tensor.
+            Otherwise, the channels will be split up into
+            `len(channels_per_snapshot)` tensors, with each
+            tensor's channel dimension being equal to the
+            corresponding value in `channels_per_snapshot`.
+            Therefore, if specified, these values should
+            add up to `num_channels`.
+    """
+
+    def __init__(
+        self,
+        num_channels: int,
+        snapshot_size: int,
+        stride_size: int,
+        batch_size: int,
+        channels_per_snapshot: Optional[Sequence[int]] = None,
+    ) -> None:
+        super().__init__()
+        if stride_size >= snapshot_size:
+            raise ValueError(
+                "Snapshotter can't accommodate stride {} "
+                "which is greater than snapshot size {}".format(
+                    stride_size, snapshot_size
+                )
+            )
+
+        self.snapshot_size = snapshot_size
+        self.stride_size = stride_size
+        self.state_size = snapshot_size - stride_size
+        self.batch_size = batch_size
+
+        if channels_per_snapshot is not None:
+            if sum(channels_per_snapshot) != num_channels:
+                raise ValueError(
+                    "Can't break {} channels into {}".format(
+                        num_channels, channels_per_snapshot
+                    )
+                )
+        self.channels_per_snapshot = channels_per_snapshot
+        self.num_channels = num_channels
+
+    def get_initial_state(self):
+        return torch.zeros((self.num_channels, self.state_size))
+
+    # TODO: use torchtyping annotations to make
+    # clear what the expected shapes are
+    def forward(
+        self, update: torch.Tensor, snapshot: Optional[torch.Tensor] = None
+    ) -> Tuple[torch.Tensor, ...]:
+        if snapshot is None:
+            snapshot = self.get_initial_state()
+
+        # append new data to the snapshot
+        snapshot = torch.cat([snapshot, update], axis=-1)
+
+        if self.batch_size > 1:
+            snapshots = unfold_windows(
+                snapshot, self.snapshot_size, self.stride_size
+            )
+        else:
+            snapshots = snapshot[None]
+
+        if self.channels_per_snapshot is not None:
+            if snapshots.size(1) != self.num_channels:
+                raise ValueError(
+                    "Expected {} channels, found {}".format(
+                        self.num_channels, snapshots.size(1)
+                    )
+                )
+            snapshots = torch.split(
+                snapshots, self.channels_per_snapshot, dim=1
+            )
+        else:
+            snapshots = (snapshots,)
+
+        # keep only the latest snapshot as our state
+        snapshot = snapshot[:, -self.state_size :]
+        return tuple(snapshots) + (snapshot,)

ml4gw/transforms/__init__.py

@@ -1,5 +1,7 @@
+from .pearson import ShiftedPearsonCorrelation
 from .scaler import ChannelWiseScaler
 from .snr_rescaler import SnrRescaler
 from .spectral import SpectralDensity
+from .spectrogram import MultiResolutionSpectrogram
 from .waveforms import WaveformProjector, WaveformSampler
 from .whitening import FixedWhiten, Whiten