Add a vignette

Fixes #10 #28 #27

Author: gregorgorjanc

.gitignore

@@ -1,15 +1,19 @@
-*.Rproj
+.DS_Store
 .Rproj.user
 .Rhistory
 .RData
 .Ruserdata
 .vscode
+*.Rproj
+RcppTskit/**/.quarto/
+RcppTskit/inst/doc
 RcppTskit/src/*.o
 RcppTskit/src/tskit/*.o
 RcppTskit/src/*.so
 RcppTskit/src/*.dll*
 RcppTskit/src/Makevars
 RcppTskit/src/Makevars.win
+RcppTskit/vignettes/*.html
+RcppTskit/vignettes/*.R
+RcppTskit/vignettes/*_files
 test.trees
-.DS_Store
-*.html

README.md

@@ -9,18 +9,15 @@ Tskit provides Python, C, and Rust APIs. The Python API can be called from R
 via the `reticulate` R package to seamlessly load and analyse a tree sequence,
 as described at https://tskit.dev/tutorials/RcppTskit.html.
 `RcppTskit` provides R access to the `tskit` C API for use cases where the
-`reticulate` approach is not optimal. For example, for high-performance and
-low-level work with tree sequences. Currently, `RcppTskit` provides a very limited
+`reticulate` option is not optimal. For example, for high-performance and
+low-level work with tree sequences. Currently, `RcppTskit` provides a limited
 number of R functions due to the availability of extensive Python API and
-the `reticulate` approach.
+the `reticulate` option.
 
-See more details on the state of the tree sequence ecosystem and aims for
-`RcppTskit` in [RcppTskit/inst/STATE_and_AIMS.md](RcppTskit/inst/STATE_and_AIMS.md),
+See more details on the state of the tree sequence ecosystem and aims of
+`RcppTskit` in [RcppTskit/vignettes/RcppTskit_intro.qmd](RcppTskit/vignettes/RcppTskit_intro.qmd),
 including examples on how to use it on its own or to develop new R packages.
 
-TODO: Think how to best point to use cases. Probably best to point to vignette and pkgdown!?
-      https://github.com/HighlanderLab/RcppTskit/issues/10
-
 ## Status
 
 <!-- badges: start -->
@@ -31,7 +28,7 @@ TODO: Think how to best point to use cases. Probably best to point to vignette a
 [![CRAN version](https://www.r-pkg.org/badges/version/RcppTskit)](https://CRAN.R-project.org/package=RcppTskit) <!-- Row 2, Col 1 --> ![GitHub version (main)](https://img.shields.io/github/r-package/v/HighlanderLab/RcppTskit/main?filename=RcppTskit%2FDESCRIPTION&label=Github) <!-- Row 2, Col 2 --> [![Downloads - total](https://cranlogs.r-pkg.org/badges/grand-total/RcppTskit)](https://cranlogs.r-pkg.org/badges/grand-total/RcppTskit) <!-- Row 2, Col 3 -->
 
 <!-- line break 2 -->
-[![CRAN R CMD check](https://cranchecks.info/badges/summary/RcppTskit)](https://cran.r-project.org/web/checks/check_results_RcppTskit.html) <!-- Row 3, Col 1 --> ![GitHub R CMD check](https://img.shields.io/github/actions/workflow/status/HighlanderLab/RcppTskit/R-CMD-check.yaml?label=GitHub%20R%20CMD%20check) <!-- Row 3, Col 2 --> [![Codecov test coverage](https://codecov.io/gh/HighlanderLab/RcppTskit/graph/badge.svg)](https://app.codecov.io/gh/HighlanderLab/RcppTskit) <!-- Row 3, Col 3 -->
+[![CRAN R CMD check](https://cranchecks.info/badges/summary/RcppTskit)](https://cran.r-project.org/web/checks/check_results_RcppTskit.html) <!-- Row 3, Col 1 --> [![GitHub R CMD check](https://img.shields.io/github/actions/workflow/status/HighlanderLab/RcppTskit/R-CMD-check.yaml?label=GitHub%20R%20CMD%20check)](https://github.com/HighlanderLab/RcppTskit/actions/workflows/R-CMD-check.yaml) <!-- Row 3, Col 2 --> [![Codecov test coverage](https://codecov.io/gh/HighlanderLab/RcppTskit/graph/badge.svg)](https://app.codecov.io/gh/HighlanderLab/RcppTskit) <!-- Row 3, Col 3 -->
 
 <!-- badges: end -->
 

RcppTskit/.Rbuildignore

@@ -9,8 +9,11 @@
 ^\.clang-format$
 ^\.covrignore$
 ^\.github$
-^pkg_dev_notes\.md$
 ^codecov\.yaml$
-^notes_pkg_dev\.Rmd$
 ^inst/examples/create_test\.trees\.R$
 ^inst/examples/create_test\.trees\.py$
+^notes_pkg_dev\.Rmd$
+^pkg_dev_notes\.md$
+^tests/testthat/_snaps$
+^vignettes/\.quarto$
+^vignettes/*_files$

RcppTskit/DESCRIPTION

@@ -15,16 +15,22 @@ Description: Tskit enables performant storage, manipulation, and analysis
   via the `reticulate` R package to seamlessly load and analyse
   a tree sequence as described at https://tskit.dev/tutorials/RcppTskit.html.
   `RcppTskit` provides R access to the `tskit` C API for use cases where the
-  `reticulate` approach is not optimal. For example, for high-performance and
-  low-level work with tree sequences. Currently, `RcppTskit` provides a very
-  limited number of R functions due to the availability of extensive Python API
-  and the `reticulate` approach.
+  `reticulate` option is not optimal. For example, for high-performance and
+  low-level work with tree sequences. Currently, `RcppTskit` provides a limited
+  number of R functions due to the availability of extensive Python API and
+  the `reticulate` option.
 URL: https://github.com/highlanderlab/RcppTskit
 License: MIT + file LICENSE
 Depends: R (>= 4.0.0)
 Imports: methods, R6, Rcpp (>= 1.1.0), reticulate
 LinkingTo: Rcpp
-Suggests: covr, spelling, testthat
+Suggests:
+    covr,
+    knitr,
+    quarto,
+    spelling,
+    testthat
 RoxygenNote: 7.3.3
 Encoding: UTF-8
 Language: en-GB
+VignetteBuilder: quarto

RcppTskit/NEWS.md

@@ -13,8 +13,11 @@ This is the first release.
 - Initial version of RcppTskit using the tskit C API (version 1.3.0).
 - TreeSequence R6 class so R code looks Pythonic.
 - `ts_load()` or `TreeSequence$new()` to load a tree sequence from file into R.
-- Methods to summarise a tree sequence and its contents `ts$print()`, `ts$num_nodes()`, etc.
+- Methods to summarise a tree sequence and its contents `ts$print()`,
+  `ts$num_nodes()`, etc.
 - Method to save a tree sequence to a file `ts$dump()`.
-- Method to push tree sequence between R and reticulate Python (TODO).
-- Most methods have underlying C++ function that work with a pointer to tree sequence object,
-  for example, `RcppTskit:::ts_load_ptr()`.
+- Method to push tree sequence between R and reticulate Python
+  `ts$r_to_py()` and `ts_py_to_r()`.
+- Most methods have an underlying (unexported) C++ function that works with
+  a pointer to tree sequence object,for example, `RcppTskit:::ts_load_ptr()`.
+- All implemented functionality is documented and demonstrated with a vignette.

RcppTskit/R/RcppTskit-package.R

@@ -8,10 +8,10 @@
 #' via the `reticulate` R package to seamlessly load and analyse a tree sequence
 #' as described at https://tskit.dev/tutorials/tskitr.html.
 #' `RcppTskit` provides R access to the `tskit` C API for use cases where the
-#' `reticulate` approach is not optimal. For example, for high-performance
-#' and low-level work with tree sequences. Currently, `RcppTskit` provides a very
+#' `reticulate` option is not optimal. For example, for high-performance
+#' and low-level work with tree sequences. Currently, `RcppTskit` provides a
 #' limited number of R functions due to the availability of extensive Python API
-#' and the `reticulate` approach.
+#' and the `reticulate` option.
 #' @keywords internal
 #'
 #' @useDynLib RcppTskit, .registration = TRUE
@@ -21,76 +21,7 @@
 #' @importFrom reticulate is_py_object import py_module_available py_require
 #'
 #' @examples
-#' \dontshow{# Providing the examples here so we test them via R CMD check}
-#' # Here are examples showcasing what you can do with RcppTskit
-#'
-#' # 1) Load a tree sequence into R and summarise it
-#' # Load a tree sequence
-#' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
-#' ts <- ts_load(ts_file)
-#'
-#' # Print summary of the tree sequence
-#' ts$num_individuals()
-#' ts
-#'
-#' # 2) Pass tree sequence between R and reticulate or standard Python
-#'
-#' # Tree sequence in R
-#' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
-#' ts <- ts_load(ts_file)
-#'
-#' # If you have a tree sequence in R and want to use tskit Python API, use
-#' ts_py <- ts$r_to_py()
-#' # ... continue in reticulate Python ...
-#' ts_py$num_individuals # 80
-#' ts2_py = ts_py$simplify(samples = c(0L, 1L, 2L, 3L))
-#' ts2_py$num_individuals # 2
-#' # ... and to bring it back to R use ...
-#' ts2 <- ts_py_to_r(ts2_py)
-#' ts2$num_individuals() # 2
-#'
-#' # If you prefer standard (non-reticulate) Python, use
-#' ts_file <- tempfile()
-#' print(ts_file)
-#' ts$dump(file = ts_file)
-#' # ... continue in standard Python ...
-#' # import tskit
-#' # ts = tskit.load("insert_ts_file_path_here")
-#' # ts.num_individuals # 80
-#' # ts2 = ts.simplify(samples = [0, 1, 2, 3])
-#' # ts2.num_individuals # 2
-#' # ts2.dump("insert_ts_file_path_here")
-#' # ... and to bring it back to R use ...
-#' ts2 <- ts_load(ts_file)
-#' ts$num_individuals() # 2 (if you have ran the above Python code)
-#'
-#' # 3) Call tskit C API in C++ code in R session or script
-#' library(Rcpp)
-#' # Write and compile a C++ function
-#' codeString <- '
-#'   #include <tskit.h>
-#'   int ts_num_individuals(SEXP ts) {
-#'     Rcpp::XPtr<tsk_treeseq_t> ts_xptr(ts);
-#'     return (int) tsk_treeseq_get_num_individuals(ts_xptr);
-#'   }'
-#' ts_num_individuals2 <- Rcpp::cppFunction(code=codeString,
-#'                                          depends="RcppTskit",
-#'                                          plugins="RcppTskit")
-#' # We must specify both the `depends` and `plugins` arguments!
-#'
-#' # Load a tree sequence
-#' ts_file <- system.file("examples/test.trees", package="RcppTskit")
-#' ts <- ts_load(ts_file)
-#'
-#' # Apply the compiled function
-#' ts_num_individuals2(ts$pointer)
-#'
-#' # An identical RcppTskit implementation
-#' ts$num_individuals()
-#'
-#' # 4) Call `tskit` C API in C++ code in another R package
-#' # TODO: Show vignette here
-#' #       https://github.com/HighlanderLab/RcppTskit/issues/10
+#' vignette(package="RcppTskit")
 "_PACKAGE"
 
 #' Providing an inline plugin so we can call tskit C API with functions like