pysiglib.tree_to_idx

pysiglib.tree_to_idx#

tree_to_idx(tree, dimension, degree, *, tree_order='canonical', planar=False, scalar_term=False)[source]#

Given a decorated rooted tree, returns its flat index in the branched-signature coefficient vector.

Trees use the kauri tuple convention:

  • Empty tree: None – index 0 when scalar_term=True; invalid otherwise

  • Leaf: (label,) where label is in [0, dimension)

  • Internal node: (child_1, child_2, ..., root_label)

With scalar_term=True the empty tree sits at index 0. With scalar_term=False (default) there is no empty-tree entry, so all indices shift down by 1 and None is invalid.

Parameters:

  • tree – Decorated rooted tree as a tuple (or None for empty when scalar_term=True).

  • dimension (int) – Path dimension (alphabet size).

  • degree (int) – Maximum number of nodes (same as degree in branched_sig()).

  • tree_order (str) – Tree ordering convention. "canonical" (default) matches branched_sig(..., tree_order="canonical"). "recursive" matches branched_sig(..., tree_order="recursive") (the default).

  • planar (bool) – If True, use the planar (ordered) enumeration matching branched_sig(..., planar=True).

  • scalar_term (bool) – Whether the target branched signature includes the leading scalar 1 at index 0. Must match the format of the bsig you intend to index. Default False.

Returns:

Flat index in the branched signature vector.

Return type:

int

Example:#

import torch
import pysiglib

path = torch.rand(size=(100, 2))
pysiglib.prepare_branched_sig(2, 3)
bsig = pysiglib.branched_sig(path, 3, tree_order="canonical")  # scalar_term=False

tree = ((1,), 0)
idx = pysiglib.tree_to_idx(tree, dimension=2, degree=3)
print(f"Index: {idx}, Coefficient: {bsig[idx]}")

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