Logsignatures

signatory.logsignature(path: torch.Tensor, depth: int, stream: Union[bool, torch.Tensor] = False, basepoint: bool = False, inverse=False, mode: str = 'words') → torch.Tensor

Applies the logsignature transform to a stream of data.

The modes argument determines how the logsignature is represented.

Note that if performing many logsignature calculations for the same depth and size of input, then you will see a performance boost (at the cost of using a little extra memory) by using signatory.LogSignature instead of signatory.logsignature().

Parameters
Returns

A torch.Tensor, of almost the same shape as the tensor returned from signatory.signature() called with the same arguments.

If mode == "expand" then it will be exactly the same shape as the returned tensor from signatory.signature().

If mode in ("brackets", "words") then the channel dimension will instead be of size signatory.logsignature_channels(path.size(-1), depth). (Where path.size(-1) is the number of input channels.)

The different modes correspond to different mathematical representations of the logsignature.

Tip

If you haven’t studied tensor algebras and free Lie algebras, and none of the following explanation makes sense to you, then you probably want to leave mode on its default value of "words" and it will all be fine!

If mode == "expand" then the logsignature is presented as a member of the tensor algebra; the numbers returned correspond to the coefficients of all words in the tensor algebra.

If mode == "brackets" then the logsignature is presented in terms of the coefficients of the Lyndon basis of the free Lie algebra.

If mode == "words" then the logsignature is presented in terms of the coefficients of a particular computationally efficient basis of the free Lie algebra (that is not a Hall basis). Every basis element is given as a sum of Lyndon brackets. When each bracket is expanded out and the sum computed, the sum will contain precisely one Lyndon word (and some collection of non-Lyndon words). Moreover every Lyndon word is represented uniquely in this way. We identify these basis elements with each corresponding Lyndon word. This is natural as the coefficients in this basis are found just by extracting the coefficients of all Lyndon words from the tensor algebra representation of the logsignature.

In all cases, the ordering corresponds to the ordering on words given by first ordering the words by length, and then ordering each length class lexicographically.

class signatory.LogSignature(depth: int, stream: bool = False, inverse: bool = False, mode: str = 'words', **kwargs)

torch.nn.Module wrapper around the signatory.logsignature() function.

This torch.nn.Module performs certain optimisations to allow it to calculate multiple logsignatures faster than multiple calls to signatory.logsignature().

Specifically, these optimisations will apply if this torch.nn.Module is called with an input path with the same number of channels as the last input path it was called with, as is likely to be very common in machine learning set-ups. For larger depths or numbers of channels, this speedup will be substantial.

Parameters
forward(path: torch.Tensor, basepoint: Union[bool, torch.Tensor] = False) → torch.Tensor

The forward operation.

Parameters
Returns

As signatory.logsignature().

prepare(in_channels: int) → None

Prepares for computing logsignatures for paths of the specified number of channels. This will be done anyway automatically whenever this torch.nn.Module is called, if it hasn’t been called already; this method simply allows to have it done earlier, for example when benchmarking.

Parameters

in_channels (int) – The number of input channels of the path that this instance will subsequently be called with. (corresponding to path.size(-1).)

signatory.logsignature_channels(in_channels: int, depth: int) → int

Computes the number of output channels from a logsignature call with mode in ("words", "brackets").

Parameters

  • in_channels (int) – The number of channels in the input; that is, the dimension of the space that the input path resides in. If calling signatory.logsignature() with argument path then in_channels should be equal to path.size(-1).

  • depth (int) – The depth of the signature that is being computed.

Returns

An int specifying the number of channels in the logsignature of the path.

signatory.signature_to_logsignature(signature: torch.Tensor, channels: int, depth: int, stream: bool = False, mode: str = 'words', scalar_term: bool = False) → torch.Tensor

Calculates the logsignature corresponding to a signature.

Parameters

Example

import signatory
import torch
batch, stream, channels = 8, 8, 8
depth = 3
path = torch.rand(batch, stream, channels)
signature = signatory.signature(path, depth)
logsignature = signatory.signature_to_logsignature(signature, channels, depth)
Returns

A torch.Tensor representing the logsignature corresponding to the given signature. See signatory.logsignature().

class signatory.SignatureToLogSignature(channels: int, depth: int, stream: bool = False, mode: str = 'words', scalar_term: bool = False, **kwargs)

torch.nn.Module wrapper around the signatory.signature_to_logsignature() function.

Calling this torch.nn.Module on an input signature with the same number of channels as the last signature it was called with will be faster than multiple calls to the signatory.signature_to_logsignature() function, in the same way that signatory.LogSignature will be faster than signatory.logsignature().

Parameters
forward(signature: torch.Tensor) → torch.Tensor

The forward operation.

Parameters

signature (torch.Tensor) – As signatory.signature_to_logsignature().

Returns

As signatory.signature_to_logsignature().