# Path

class `signatory.``Path`(path: torch.Tensor, depth: int, basepoint: Union[bool, torch.Tensor] = False, remember_path: bool = True, scalar_term: bool = False, **kwargs)

  Calculates signatures and logsignatures on intervals of an input path.

  By doing some precomputation, it can rapidly calculate the signature or logsignature over any slice of the input path. This is particularly useful if you need the signature or logsignature of a path over many different intervals: using this class will be much faster than computing the signature or logsignature of each sub-path each time.

  May be efficiently sliced and indexed along its batch dimension via [] syntax. This will return a new Path without copying the underlying data.

  Parameters

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

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

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

    - remember_path (bool, optional) – Defaults to True. Whether to record the `path` argument that this was called with. If True, then it will be accessible as the `.path` attribute. This argument may be set to False if it is known that the underlying path is no longer of interest and should not kept in memory just because it was passed as an argument here.

    - scalar_term (bool, optional) – Defaults to False. Whether to include the scalar ‘1’ when calling the `signatory.Path.signature()` method; see also the equivalent argument for `signatory.signature()`.

  `signature`(start: Optional[int] = None, end: Optional[int] = None) → torch.Tensor

    Returns the signature on a particular interval.

    Parameters

      - start (int or None, optional) – Defaults to the start of the path. The start point of the interval to calculate the signature on.

      - end (int or None, optional) – Defaults to the end of the path. The end point of the interval to calculate the signature on.

    Returns

      The signature on the interval `[start, end]`.

      In the simplest case, when `path` and `depth` are the arguments that this class was initialised with (and `basepoint` was not passed), then this function returns a value equal to `signatory.signature(path[start:end], depth)`.

      In general, let `p = torch.cat(self.path, dim=1)`, so that it is all given paths (including those `path` from both initialistion and `signatory.Path.update()`, and any `basepoint`) concatenated together. Then this function will return a value equal to `signatory.signature(p[start:end], depth)`.

  `logsignature`(start: Optional[int] = None, end: Optional[int] = None, mode: str = 'words') → torch.Tensor

    Returns the logsignature on a particular interval.

    Parameters

      - start (int or None, optional) – As `signatory.Path.signature()`.

      - end (int or None, optional) – As `signatory.Path.signature()`.

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

    Returns

      The logsignature on the interval `[start, end]`. See the documentation for `signatory.Path.signature()`.

  `update`(path: torch.Tensor) → None

    Concatenates the given path onto the path already stored.

    This means that the signature of the new overall path can now be asked for via `signatory.Path.signature()`. Furthermore this will be dramatically faster than concatenating the two paths together and then creating a new Path object: the ‘concatenation’ occurs implicitly, without actually involving any recomputation or reallocation of memory.

    Parameters

      path (torch.Tensor) – The path to concatenate on. As `signatory.signature()`.

  property `remember_path`

    Whether this Path remembers the `path` argument it was called with.

  property `path`

    The path(s) that this Path was created with.

  property `depth`

    The depth that Path has calculated the signature to.

  `size`(index: Optional[int] = None) → Union[int, torch.Size]

    The size of the input path. As `torch.Tensor.size()`.

    Parameters

      index (int or None, optional) – As `torch.Tensor.size()`.

    Returns

      As `torch.Tensor.size()`.

  property `shape`

    The shape of the input path. As `torch.Tensor.shape`.

  `channels`() → int

    The number of channels of the input stream.

  `signature_size`(index: Optional[int] = None) → Union[int, torch.Size]

    The size of the signature of the path. As `torch.Tensor.size()`.

    Parameters

      index (int or None, optional) – As `torch.Tensor.size()`.

    Returns

      As `torch.Tensor.size()`.

  property `signature_shape`

    The shape of the signature of the path. As `torch.Tensor.shape`.

  `signature_channels`() → int

    The number of signature channels; as `signatory.signature_channels()`.

  `logsignature_size`(index: Optional[int] = None) → Union[int, torch.Size]

    The size of the logsignature of the path. As `torch.Tensor.size()`.

    Parameters

      index (int or None, optional) – As `torch.Tensor.size()`.

    Returns

      As `torch.Tensor.size()`.

  property `logsignature_shape`

    The shape of the logsignature of the path. As `torch.Tensor.shape`.

  `logsignature_channels`() → int

    The number of logsignature channels; as `signatory.logsignature_channels()`.

  `shuffle`()

    Randomly permutes the Path along its batch dimension, and returns as a new Path. Returns a tuple of the new Path object, and the random permutation that produced it.

  `shuffle_`()

    In place version of `signatory.Path.shuffle()`.

Warning

If repeatedly making forward and backward passes (for example when training a neural network) and you have a learnt layer before the `signatory.Path`, then make sure to construct a new `signatory.Path` object for each forward pass.

Reusing the same object between forward passes will mean that signatures aren’t computed using the latest information, as the internal buffers will still correspond to the data passed in when the `signatory.Path` object was first constructed.