pysiglib.sig_score

pysiglib.sig_score#

Added in version v0.2.1.

sig_score(sample, y, dyadic_order, *, lam=1.0, static_kernel=None, time_aug=False, lead_lag=False, end_time=1.0, n_jobs=1, max_batch=-1)[source]#

Computes the (generalised) signature kernel score

\[\phi_{\text{sig}}(\mu, y) := \lambda \mathbb{E}_{x,x' \sim \mu}[k(x,x')] - 2\mathbb{E}_{x\sim \mu}[k(x,y)].\]

Given a batch of sample paths \(\{x_i\}_{i=1}^m \sim \mu\) and a path \(y\), the score is computed using the consistent and unbiased estimator

\[\widehat{\phi}_{\text{sig}}(\mu, y) := \frac{\lambda }{m(m-1)} \sum_{j \neq i} k(x_i, x_j) - \frac{2}{m} \sum_i k(x_i, y).\]

Optionally, a static kernel can be specified. For details, see the documentation on static kernels.

Parameters:

  • sample (numpy.ndarray | torch.tensor) – The batch of sample paths drawn from \(\mu\), of shape (*batch_shape, length_1, dimension).

  • y (numpy.ndarray | torch.tensor) – The path(s) \(y\), of shape (*batch_shape_y, length_2, dimension). batch_shape_y may be empty (single y) or arbitrary; the score is computed independently for each y. Independent of sample’s batch shape.

  • dyadic_order (int | tuple) – If set to a positive integer \(\lambda\), will refine the paths by a factor of \(2^\lambda\). If set to a tuple of positive integers \((\lambda_1, \lambda_2)\), will refine the first path by \(2^{\lambda_1}\) and the second path by \(2^{\lambda_2}\).

  • lam (float) – The parameter \(\lambda\) of the generalised signature kernel score (default = 1.0).

  • static_kernel (None | pysiglib.StaticKernel) – Static kernel passed to the signature kernel computation. If None (default), the linear kernel will be used. For details, see the documentation on static kernels.

  • time_aug (bool) – If set to True, will compute the signature of the time-augmented path, \(\hat{x}_t := (t, x_t)\), defined as the original path with an extra channel set to time, \(t\). This channel spans \([0, t_L]\), where \(t_L\) is given by the parameter end_time.

  • lead_lag (bool) – If set to True, will compute the signature of the path after applying the lead-lag transformation.

  • end_time (float) – End time for time-augmentation, \(t_L\).

  • n_jobs (int) – (Only applicable to CPU computation) Number of threads to run in parallel. If n_jobs = 1, the computation is run serially. If set to -1, all available threads are used. For n_jobs below -1, (max_threads + 1 + n_jobs) threads are used. For example if n_jobs = -2, all threads but one are used.

  • max_batch (int) – Maximum batch size to run in parallel. If the computation is failing due to insufficient memory, this parameter should be decreased. If set to -1, the entire batch is computed in parallel.

Returns:

Signature kernel score, of shape batch_shape_y (or (1,) if y is a single 2D path).

Return type:

numpy.ndarray | torch.tensor

Example:#

import torch
import pysiglib

sample = torch.rand((20, 100, 5))
y = torch.rand((100, 5))
score = pysiglib.sig_score(sample, y, dyadic_order=2)
print(score.shape)  # (1,)

# Using a static kernel with regularisation and time augmentation
import torch
import pysiglib

sample = torch.rand((20, 100, 5))
y = torch.rand((100, 5))
rbf = pysiglib.RBFKernel(sigma=1.0)
score = pysiglib.sig_score(
    sample, y,
    dyadic_order=2,
    lam=0.1,
    static_kernel=rbf,
    time_aug=True,
    max_batch=8,
)
print(score)

# Multi-dim sample batch and a batch of y paths
# one score is returned per y
import torch
import pysiglib

sample = torch.rand((4, 5, 100, 5))  # 4 * 5 = 20 sample paths total
y = torch.rand((3, 100, 5))          # batch of 3 target paths
score = pysiglib.sig_score(sample, y, dyadic_order=2)
print(score.shape)  # (3,)

Citation#

If you found this library useful in your research, please consider citing the paper:

@article{shmelev2025pysiglib,
  title={pySigLib-Fast Signature-Based Computations on CPU and GPU},
  author={Shmelev, Daniil and Salvi, Cristopher},
  journal={arXiv preprint arXiv:2509.10613},
  year={2025}
}
Contents