# Logsignatures

`signatory.``logsignature`(path: torch.Tensor, depth: int, stream: bool = False, basepoint: Union[bool, torch.Tensor] = False, inverse: bool = 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

    - path (`torch.Tensor`) – as `signatory.signature()`.

    - depth (int) – as `signatory.signature()`.

    - stream (bool, optional) – as `signatory.signature()`.

    - basepoint (bool or `torch.Tensor`, optional) – as `signatory.signature()`.

    - inverse (bool, optional) – as `signatory.signature()`.

    - mode (str, optional) – Defaults to `"words"`. How the output should be presented. Valid values are `"words"`, `"brackets"`, or `"expand"`. Precisely what each of these options mean is described in the “Returns” section below. For machine learning applications, `"words"` is the appropriate choice. The other two options are mostly only interesting for mathematicians.

  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

    - depth (int) – as `signatory.logsignature()`.

    - stream (bool, optional) – as `signatory.logsignature()`.

    - inverse (bool, optional) – as `signatory.logsignature()`.

    - mode (str, optional) – as `signatory.logsignature()`.

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

    The forward operation.

    Parameters

      - path (`torch.Tensor`) – As `signatory.logsignature()`.

      - basepoint (bool or torch.Tensor, optional) – As `signatory.logsignature()`.

    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

    - signature (`torch.Tensor`) – The result of a call to `signatory.signature()`.

    - channels (int) – The number of input channels of the `path` that `signatory.signature()` was called with.

    - depth (int) – The value of `depth` that `signatory.signature()` was called with.

    - stream (bool, optional) – Defaults to False. The value of `stream` that `signatory.signature()` was called with.

    - mode (str, optional) – Defaults to `"words"`. As `signatory.logsignature()`.

    - scalar_term (bool, optional) – Defaults to False. The value of `scalar_term` that `signatory.signature()` was called with.

  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

    - channels (int) – as `signatory.signature_to_logsignature()`.

    - depth (int) – as `signatory.signature_to_logsignature()`.

    - stream (bool, optional) – as `signatory.signature_to_logsignature()`.

    - mode (str, optional) – as `signatory.signature_to_logsignature()`.

    - scalar_term (bool, optional) – as `signatory.signature_to_logsignature()`.

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

    The forward operation.

    Parameters

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

    Returns

      As `signatory.signature_to_logsignature()`.