From 93e02601df956d5f4ae9852a10a6ba49956e6430 Mon Sep 17 00:00:00 2001 From: Gregor Gorjanc Date: Tue, 3 Mar 2026 21:01:06 +0000 Subject: [PATCH] Improved docs Fixes #92 #106 --- README.md | 2 +- RcppTskit/vignettes/RcppTskit_intro.qmd | 30 ++++++++++++++++--------- 2 files changed, 20 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 050cf30..8d6e91e 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ General: [![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-expe Release: [![CRAN version](https://www.r-pkg.org/badges/version/RcppTskit)](https://CRAN.R-project.org/package=RcppTskit) -[![Downloads - total](https://cranlogs.r-pkg.org/badges/grand-total/RcppTskit)](https://cranlogs.r-pkg.org/badges/grand-total/RcppTskit) +[![Downloads - total](https://cranlogs.r-pkg.org/badges/grand-total/RcppTskit)](https://cranlogs.r-pkg.org/#rpackage) [![GitHub version (main)](https://img.shields.io/github/r-package/v/HighlanderLab/RcppTskit/main?filename=RcppTskit%2FDESCRIPTION&label=Github)](https://github.com/HighlanderLab/RcppTskit) diff --git a/RcppTskit/vignettes/RcppTskit_intro.qmd b/RcppTskit/vignettes/RcppTskit_intro.qmd index 8c5765f..75ecbc2 100644 --- a/RcppTskit/vignettes/RcppTskit_intro.qmd +++ b/RcppTskit/vignettes/RcppTskit_intro.qmd @@ -23,24 +23,31 @@ If you are new to tree sequences and the broader concept of ancestral recombination graphs (ARGs), see @brandt2024promise, @lewanski2024era, @nielsen2024inference, and @wong2024general. Before showing how to use `RcppTskit`, -we summarise the now extensive tree sequence ecosystem, -because this has shaped the aim and design of `RcppTskit`. -We then highlight the aims of `RcppTskit`, +we highlight the targeted users and +summarise the now extensive tree sequence ecosystem, +as this has shaped the aim and design of `RcppTskit`. +We then describe specific aims of `RcppTskit`, describe the implemented data and class model, and show four typical use cases. +## Who is `RcppTskit` for? + As summarised below, `Python` is the most widely used environment for working with tree sequences. -Using the `R` package `reticulate` [@ushey2025reticulate] -, -most `R` users can and should leverage the large ecosystem of `Python` packages, -in particular the popular `tskit Python` API +Most `R` users who want to work with tree sequences +are advised to start with the `tskit Python` API via +the `R` package `reticulate` [@ushey2025reticulate] +. +See +for a tutorial. +This approach provides access to the most complete and mature API [@jeffrey2026population] -. -With this in mind, + +and interoperability with other `Python` packages. + `RcppTskit` is primarily geared towards providing `R` access to the `tskit C` API [@jeffrey2026population], -for cases where the `reticulate` option is not optimal; +for cases where the `reticulate` approach is not optimal; for example, high-performance or low-level work with tree sequences. As a result, `RcppTskit` currently provides a limited set of functions because the `Python` API (and `reticulate`) already covers most needs. @@ -115,7 +122,8 @@ with comprehensive packages for simulation and analysis. There is interest in working with tree sequences in `R`. Because we can call `Python` from within `R` using the `reticulate R` package, there is no pressing need for a dedicated `R` API for work with tree sequences. -See for an example of this approach. +As noted above, see +for an example of this approach. This keeps the community focused on the `Python` collection of packages. While there are differences between `Python` and `R`, many `R` users should be able to follow