1  Get Started

1.1 Installation

sconjoint runs on the torch deep-learning backend, which bundles its own copy of libtorch (downloaded on first use). Install torch first and confirm its native library loads:

install.packages("torch")
torch::install_torch()        # downloads libtorch the first time
torch::torch_is_installed()   # should return TRUE

Then install sconjoint from CRAN. It has been submitted; until it is accepted this line stays commented out — install a development version instead (see Section 1.2):

# install.packages("sconjoint")

On CPU-only machines this is all you need. On a CUDA-enabled GPU, follow https://torch.mlverse.org to install the CUDA build of libtorch; scfit(device = "cuda") then uses it automatically. (The bit-exact determinism guarantee — identical sc_fit output regardless of n_cores — holds only on CPU.)

1.2 Versions

Until the CRAN release, install from GitHub. The development branches carry features ahead of CRAN:

Source Version What it adds
CRAN 0.2.1 The released version (default), pending acceptance
GitHub @dev 0.2.1 Development version; currently matches the CRAN submission
GitHub @feat/torch-threads 0.2.1.9000 Newest in-progress work: the torch_threads Windows-stability control and the attribute-interaction extension, pending merge to dev after the release

Install a specific source with the @branch suffix:

# install.packages("remotes")
remotes::install_github("xuyiqing/sconjoint@dev")                 # development version
remotes::install_github("xuyiqing/sconjoint@feat/torch-threads")  # newest features

Check which version is installed on this computer:

packageVersion("sconjoint")
[1] '0.2.1.9000'

Once sconjoint is on CRAN, install.packages("sconjoint") gives the latest release and remotes::install_version("sconjoint", "0.2.1") pins a specific one. Installing sconjoint pulls in ggplot2, ggridges, and related plotting packages automatically; no extra setup is needed for the visualization methods in the Plot Options chapter.

WarningTroubleshooting: the R session aborts when calling scfit()

A session abort (the R process exits, rather than throwing an R error) almost always comes from the native libtorch backend, not from sconjoint itself. It has been reported on some Windows systems while the same code runs fine on macOS. Things to try, in order:

  1. Confirm torch works in isolation. In a fresh session, run library(torch); x <- torch_randn(3, 3); x %*% x. If that aborts, the problem is the torch / libtorch installation or your environment, not sconjoint: reinstall with torch::install_torch(), and check whether security or endpoint-protection software is blocking the libtorch DLLs (a common cause on managed corporate Windows machines).

  2. Cap torch’s threads with torch_threads = 1. torch’s default multi-threaded CPU backend aborts the session on some Windows configurations, and running it single-threaded often avoids it. The torch_threads argument to scfit() is the targeted fix for this (issue #7). It currently lives on the feat/torch-threads branch, pending merge to dev after the next release, so install that branch first:

    remotes::install_github("xuyiqing/sconjoint@feat/torch-threads")
library(sconjoint)
fit <- scfit(formula, data, ..., torch_threads = 1)

    torch_threads = 1 changes only the threading, not the results, and torch honors the thread count only on the first such call of a session — so set it before running any other torch work.

  3. Try plain R (Rterm or the console) rather than an IDE, to rule out an IDE-specific interaction.