diff --git a/RcppTskit/DESCRIPTION b/RcppTskit/DESCRIPTION index 05270d5..539dd26 100644 --- a/RcppTskit/DESCRIPTION +++ b/RcppTskit/DESCRIPTION @@ -23,9 +23,11 @@ Description: 'Tskit' enables efficient storage, manipulation, and analysis 'reticulate' option is not optimal; for example, high-performance or low-level work with tree sequences. Currently, 'RcppTskit' provides a limited set of functions because the 'Python' API and 'reticulate' - already cover most needs. The provided `RcppTskit R` API mirrors the - `tskit Python` API, while the `RcppTskit C++` API mirrors the `tskit - C` API. + already cover most needs. The provided 'RcppTskit R' API mirrors the + 'tskit Python' API, while the 'RcppTskit C++' API mirrors the 'tskit + C' API. Users should explore the 'RcppTskit' help pages of 'R' + functions, while developers should explore the 'RcppTskit:::rtsk_*' + low-level 'R' and 'C++'' functions. License: MIT + file LICENSE URL: https://github.com/HighlanderLab/RcppTskit BugReports: https://github.com/HighlanderLab/RcppTskit/issues diff --git a/RcppTskit/R/RcppTskit-package.R b/RcppTskit/R/RcppTskit-package.R index e6eb768..60736bc 100644 --- a/RcppTskit/R/RcppTskit-package.R +++ b/RcppTskit/R/RcppTskit-package.R @@ -6,17 +6,20 @@ #' The tree sequence encoding of an ARG is described in Wong et al. (2024) #' , while \code{tskit} project is #' described in Jeffrey et al. (2026) . -#' See also https://tskit.dev for project news, documentation, and tutorials. -#' \code{Tskit} provides Python, C, and Rust application programming interfaces (APIs). -#' The Python API can be called from R via the \code{reticulate} package to -#' load and analyse tree sequences as described at -#' https://tskit.dev/tutorials/tskitr.html. -#' \code{RcppTskit} provides R access to the \code{tskit} C API for cases where the -#' \code{reticulate} option is not optimal; for example; high-performance or low-level -#' work with tree sequences. Currently, \code{RcppTskit} provides a limited set of -#' R functions because the Python API and \code{reticulate} already covers most needs. -#' The provided \code{RcppTskit R} API mirrors the \code{tskit Python} API, -#' while the \code{RcppTskit C++} API mirrors the \code{tskit C} API. +#' See also \url{https://tskit.dev} for project news, documentation, and tutorials. +#' \code{Tskit} provides \code{Python}, \code{C}, and \code{Rust} application +#' programming interfaces (APIs). The \code{Python} API can be called from +#' \code{R} via the \code{reticulate} package to load and analyse tree sequences +#' as described at \url{https://tskit.dev/tutorials/tskitr.html}. +#' \code{RcppTskit} provides \code{R} access to the \code{tskit C} API for cases +#' where the \code{reticulate} option is not optimal; for example; high-performance +#' or low-level work with tree sequences. Currently, \code{RcppTskit} provides a +#' limited set of \code{R} functions because the \code{Python} API and +#' \code{reticulate} already covers most needs. The provided \code{RcppTskit R} +#' API mirrors the \code{tskit Python} API, while the \code{RcppTskit C++} API +#' mirrors the \code{tskit C} API. Users should explore the \code{RcppTskit} +#' help pages of \code{R} functions, while developers should explore the provided +#' \code{RcppTskit:::rtsk_*} low-level \code{R} and \code{C++} functions. #' @keywords internal #' #' @useDynLib RcppTskit, .registration = TRUE diff --git a/RcppTskit/inst/WORDLIST b/RcppTskit/inst/WORDLIST index bc2dadc..fa1e83d 100644 --- a/RcppTskit/inst/WORDLIST +++ b/RcppTskit/inst/WORDLIST @@ -13,6 +13,8 @@ finaliser iyae kastore msprime +num +rtsk tc ts tskit diff --git a/RcppTskit/man/RcppTskit-package.Rd b/RcppTskit/man/RcppTskit-package.Rd index 6ab8ef6..04ddd16 100644 --- a/RcppTskit/man/RcppTskit-package.Rd +++ b/RcppTskit/man/RcppTskit-package.Rd @@ -11,17 +11,20 @@ ancestral recombination graphs (ARGs) using succinct tree sequence encoding. The tree sequence encoding of an ARG is described in Wong et al. (2024) , while \code{tskit} project is described in Jeffrey et al. (2026) . -See also https://tskit.dev for project news, documentation, and tutorials. -\code{Tskit} provides Python, C, and Rust application programming interfaces (APIs). -The Python API can be called from R via the \code{reticulate} package to -load and analyse tree sequences as described at -https://tskit.dev/tutorials/tskitr.html. -\code{RcppTskit} provides R access to the \code{tskit} C API for cases where the -\code{reticulate} option is not optimal; for example; high-performance or low-level -work with tree sequences. Currently, \code{RcppTskit} provides a limited set of -R functions because the Python API and \code{reticulate} already covers most needs. -The provided \code{RcppTskit R} API mirrors the \code{tskit Python} API, -while the \code{RcppTskit C++} API mirrors the \code{tskit C} API. +See also \url{https://tskit.dev} for project news, documentation, and tutorials. +\code{Tskit} provides \code{Python}, \code{C}, and \code{Rust} application +programming interfaces (APIs). The \code{Python} API can be called from +\code{R} via the \code{reticulate} package to load and analyse tree sequences +as described at \url{https://tskit.dev/tutorials/tskitr.html}. +\code{RcppTskit} provides \code{R} access to the \code{tskit C} API for cases +where the \code{reticulate} option is not optimal; for example; high-performance +or low-level work with tree sequences. Currently, \code{RcppTskit} provides a +limited set of \code{R} functions because the \code{Python} API and +\code{reticulate} already covers most needs. The provided \code{RcppTskit R} +API mirrors the \code{tskit Python} API, while the \code{RcppTskit C++} API +mirrors the \code{tskit C} API. Users should explore the \code{RcppTskit} +help pages of \code{R} functions, while developers should explore the provided +\code{RcppTskit:::rtsk_*} low-level \code{R} and \code{C++} functions. } \examples{ vignette("RcppTskit_intro") diff --git a/RcppTskit/vignettes/RcppTskit_intro.qmd b/RcppTskit/vignettes/RcppTskit_intro.qmd index 75ecbc2..fa2f318 100644 --- a/RcppTskit/vignettes/RcppTskit_intro.qmd +++ b/RcppTskit/vignettes/RcppTskit_intro.qmd @@ -56,6 +56,10 @@ As the name suggests, `RcppTskit` leverages the `R` package `Rcpp` which significantly lowers the barrier to using `C++` with `R`. However, we still need to write `C++` wrappers and expose them to `R`, so we recommend using `reticulate` first. +To understand which functions are implemented, +users should explore the `RcppTskit` help pages of `R` functions, +while developers should explore the underlying +`RcppTskit:::rtsk_*` low-level `R` and `C++` functions. ## State of the tree sequence ecosystem @@ -201,18 +205,15 @@ so all editing should happen in `C/C++` or `Python`. ## API mirroring across the languages -The provided `RcppTskit R` API mirrors the `tskit Python` API, -while . - `RcppTskit` aims to keep naming, arguments, defaults, and behaviour aligned with upstream `tskit` APIs whenever practical. Specifically, -the provided `RcppTskit R` API mirrors the `tskit Python` API, -that is the functions and `R6` classes (with their methods) aim to mirror +the `RcppTskit R` API mirrors the `tskit Python` API; +the `R` functions and `R6` classes (with their methods) aim to mirror `tskit Python` functions and classes (with their methods). Note that the `RcppTskit R` API is far more limited than the `tskit Python` API. The `RcppTskit C++` API aims to mirror the `tskit C` API functions and semantics, -but is deliberately `R` oriented +but is deliberately `R` oriented. When we intentionally deviate (for example, to support `R` idioms or safety), we document the rationale and test the chosen behaviour. @@ -223,7 +224,8 @@ First install `RcppTskit` from CRAN and load it. ```{r} #| label: pre-setup #| include: false -# Had issues on Windows (R reported that RcppTskit is not installed, which is odd). +# Had issues on GitHub Windows +# (R reported that RcppTskit is not installed, which is odd). # This tries to "restore" the library path. lib_env <- Sys.getenv("R_LIBS") if (nzchar(lib_env)) { @@ -264,10 +266,30 @@ tc$print() # Convert the table collection to tree sequence ts2 <- tc$tree_sequence() -# Explore the help pages +# Users should explore the help pages help(package = "RcppTskit") ``` +Developers should also explore the low-level `R` and `C++` functions. +Their names all start with `rtsk_` and are accessible via `RcppTskit:::`. +For example, the above `R` function `ts_load()` effectively calls: + +```{r} +#| label: use_case_1_dev_funcs +# Low-level R function, which further calls the C++ function +RcppTskit:::rtsk_treeseq_load + +# C++ function (see also the C++ source code) +RcppTskit:::`_RcppTskit_rtsk_treeseq_load` + +# The same as the ts_load() example, but exposing the external pointer +xptr <- RcppTskit:::rtsk_treeseq_load(ts_file) +methods::is(xptr) + +# We pass the external pointer to other low-level functions +RcppTskit:::rtsk_treeseq_get_num_individuals(xptr) +``` + ### 2) Pass a tree sequence between `R` and reticulate or standard `Python` ```{r}