Getting started with ustats

TL;DR

install.packages("ustats")
library(ustats)

H <- matrix(rnorm(100), 10, 10)
ustat(list(H, H), "ab,bc->")

That is all most users need: on the first call, reticulate (>= 1.41) automatically downloads a private Python together with the required packages (u-stats, numpy, torch) into a cached environment, and reuses it in later sessions.

How the Python environment is resolved

ustats declares its Python dependencies via reticulate::py_require() when the package is loaded. When Python is first needed, reticulate resolves these requirements as follows:

1. If you have already configured a Python environment — via reticulate::use_virtualenv(), reticulate::use_condaenv(), or the RETICULATE_PYTHON environment variable — that environment is used. It must contain u-stats, numpy, and (recommended) torch.
2. Otherwise, reticulate provisions an ephemeral, cached environment containing the declared packages automatically. Nothing is installed into your system Python.

There are therefore three ways to set things up, from least to most manual.

library(ustats)
ustat(list(matrix(rnorm(100), 10, 10)), "ab->")

library(ustats)

setup_ustats()                # virtualenv/conda + CPU-only torch
setup_ustats(gpu = TRUE)      # default PyPI torch (CUDA-enabled on Linux)
setup_ustats(
  method  = "virtualenv",     # or "conda"
  envname = "r-ustats",
  persist = TRUE              # print the RETICULATE_PYTHON line to add
)                             # to your .Rprofile (no files are written)

pip install u-stats

library(ustats)
reticulate::use_condaenv("your_env_name", required = TRUE)
# or: reticulate::use_virtualenv("~/.virtualenvs/your_env")

check_ustats_setup()
#> === ustats Environment Status ===
#>
#> [OK] Python: /path/to/python
#>   Version: 3.12
#> [OK] u_stats available
#> [OK] NumPy available
#> [OK] PyTorch available (version 2.5.1, CUDA available)
#>
#> ---------------------------------
#>  Environment fully ready (Torch backend available)

Computing U-statistics

ustat() takes a list of kernel tensors (R vectors or matrices) and an Einstein summation expression describing how their indices are contracted, with distinct letters ranging over distinct observation indices:

library(ustats)

set.seed(1)
n <- 300

H1 <- rnorm(n)
H2 <- matrix(rnorm(n * n), n, n)
H3 <- rnorm(n)

result <- ustat(
  tensors    = list(H1, H2, H2, H3),
  expression = "a,ab,bc,c->",
  backend    = "torch",  # falls back to numpy if torch is unavailable
  average    = TRUE,     # divide by the number of index tuples
  dtype      = NULL      # auto: float32 on GPU, float64 on CPU
)
print(result)

The index structure can equivalently be given as a list of numeric index vectors, which is convenient when the expression is built programmatically:

ustat(list(H1, H2, H2, H3), list(1, c(1, 2), c(2, 3), 3))

torch <- reticulate::import("torch")
torch$cuda$is_available()

Troubleshooting

• check_ustats_setup() reports a missing module. The session is bound to a Python environment that lacks the dependency. Either install it there (pip install u-stats), or restart R and select a different environment (Options 2-3 above).
• reticulate ignores use_condaenv() / RETICULATE_PYTHON. reticulate binds to a single Python per R session, at the moment Python is first initialized. Restart R and configure the environment before anything touches Python.
• The first call seems stuck. It is most likely downloading PyTorch; see Options 1-2 for how to choose the much smaller CPU-only build.
• ustat() warns “Torch backend not available”. The bound environment has no PyTorch; the computation falls back to NumPy, which is slower and can be less numerically stable. Install torch with setup_ustats() or pip install torch --index-url https://download.pytorch.org/whl/cpu.