Merge pull request #43 from HighlanderLab:gregorgorjanc/issue10

Add a vignette

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

CODE_OF_CONDUCT.md

@@ -0,0 +1,126 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at gregor.gorjanc@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][https://github.com/mozilla/inclusion].
+
+For answers to common questions about this code of conduct, see the FAQ at
+<https://www.contributor-covenant.org/faq>. Translations are available at <https://www.contributor-covenant.org/translations>.
+
+[homepage]: https://www.contributor-covenant.org

README.md

@@ -9,17 +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),
-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
+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).
+The vignette also shows examples on how to use `RcppTskit` on its own or
+to develop new R packages.
 
 ## Status
 
@@ -31,13 +29,17 @@ 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 -->
 
 ## Contents
 
-  * `extern` - Git submodule for `tskit` and instructions on obtaining the latest version and copying the `tskit` C code into `RcppTskit` directory. `extern` is saved outside of the `RcppTskit` directory because `R CMD CHECK` complains otherwise.
+  * `extern` - Git submodule for `tskit` and instructions on
+    obtaining the latest version and copying the `tskit` C code into
+    `RcppTskit` directory.
+    `extern` is saved outside of the `RcppTskit` directory
+    because `R CMD CHECK` complains otherwise.
 
   * `RcppTskit` - R package `RcppTskit`.
 
@@ -67,22 +69,26 @@ https://mac.r-project.org/tools for macOS tools.
 ```
 # install.packages("remotes") # If you don't have it already
 
-# Release (TODO)
+# Release
 # TODO: Tag a release #15
 #       https://github.com/HighlanderLab/RcppTskit/issues/15
 # remotes::install_github("HighlanderLab/RcppTskit/RcppTskit")
 
 # Main branch
-remotes::install_github("HighlanderLab/RcppTskit/RcppTskit")
+remotes::install_github("HighlanderLab/RcppTskit/RcppTskit@main")
 
 # Development branch
-# TODO: Create a devel branch #16
-#       https://github.com/HighlanderLab/RcppTskit/issues/16
-# remotes::install_github("HighlanderLab/RcppTskit/RcppTskit@devel")
+remotes::install_github("HighlanderLab/RcppTskit/RcppTskit@devel")
 ```
 
 ## Development
 
+### Code of Conduct
+
+Please note that the `RcppTskit` project is released with a
+[Contributor Code of Conduct](https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html).
+By contributing to this project, you agree to abide by its terms.
+
 ### Clone
 
 First clone the repository:
@@ -93,7 +99,8 @@ git clone https://github.com/HighlanderLab/RcppTskit.git
 
 ### Pre-commit install
 
-We use [pre-commit](https://pre-commit.com) hooks to ensure code quality. Specifically, we use:
+We use [pre-commit](https://pre-commit.com) hooks to ensure code quality.
+Specifically, we use:
 * [air](https://github.com/posit-dev/air) to format R code,
 * [jarl](https://github.com/etiennebacher/jarl) to lint R code,
 * [clang-format](https://clang.llvm.org/docs/ClangFormat.html) to format C/C++ code, and
@@ -111,7 +118,8 @@ If you plan to update `tskit`, follow instructions in `extern/README.md`.
 
 ### RcppTskit
 
-Then open `RcppTskit` package directory in your favourite R IDE (Positron, RStudio, text-editor-of-your-choice, etc.) and implement your changes.
+Then open `RcppTskit` package directory in your favourite R IDE
+(Positron, RStudio, text-editor-of-your-choice, etc.) and implement your changes.
 
 You should routinely check your changes (in R):
 
@@ -161,6 +169,8 @@ pre-commit run --all-files
 
 ### Continuous integration
 
-We use Github Actions to run continuous integration (CI) checks on each push and pull request. Specifically, we run:
+We use Github Actions to run continuous integration (CI) checks
+on each push and pull request.
+Specifically, we run:
 * [R CMD check](.github/workflows/R-CMD-check.yaml) on multiple platforms and
 * [covr test coverage](.github/workflows/covr.yaml).

RcppTskit/.Rbuildignore

@@ -9,8 +9,12 @@
 ^\.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

@@ -1,30 +1,44 @@
-Package: RcppTskit
 Type: Package
+Package: RcppTskit
 Title: R access to the tskit C API
 Version: 0.1.0
 Date: 2026-01-2607
 Authors@R:
-  person(given = "Gregor", family = "Gorjanc",
-         email = "gregor.gorjanc@gmail.com",
-         role = c("aut", "cre"),
-         comment = c(ORCID = "0000-0001-8008-2787"))
+    person("Gregor", "Gorjanc", , "gregor.gorjanc@gmail.com", role = c("aut", "cre"),
+           comment = c(ORCID = "0000-0001-8008-2787"))
 Description: Tskit enables performant storage, manipulation, and analysis
-  of ancestral recombination graphs (ARGs) using succinct tree sequence encoding.
-  See https://tskit.dev for project news, documentation, and tutorials.
-  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 number of R functions due to the availability of extensive Python API
-  and the `reticulate` approach.
-URL: https://github.com/highlanderlab/RcppTskit
+    of ancestral recombination graphs (ARGs) using succinct tree sequence
+    encoding.  See https://tskit.dev for project news, documentation, and
+    tutorials.  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`
+    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.
 License: MIT + file LICENSE
-Depends: R (>= 4.0.0)
-Imports: methods, R6, Rcpp (>= 1.1.0), reticulate
-LinkingTo: Rcpp
-Suggests: covr, spelling, testthat
-RoxygenNote: 7.3.3
+URL: https://github.com/HighlanderLab/RcppTskit
+BugReports: https://github.com/HighlanderLab/RcppTskit/issues
+Depends:
+    R (>= 4.0.0)
+Imports:
+    methods,
+    R6,
+    Rcpp (>= 1.1.0),
+    reticulate
+Suggests:
+    covr,
+    knitr,
+    quarto,
+    spelling,
+    testthat (>= 3.0.0)
+LinkingTo:
+    Rcpp
+VignetteBuilder:
+    quarto
+Config/testthat/edition: 3
 Encoding: UTF-8
 Language: en-GB
+RoxygenNote: 7.3.3

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.