diff --git a/RcppTskit/R/Class-TableCollection.R b/RcppTskit/R/Class-TableCollection.R index 7a911ee..cf830a6 100644 --- a/RcppTskit/R/Class-TableCollection.R +++ b/RcppTskit/R/Class-TableCollection.R @@ -1,8 +1,9 @@ #' @title Table collection R6 class (TableCollection) -#' @description An R6 class holding an external pointer to a table collection -#' object. As an R6 class, its methods look Pythonic and therefore resemble the -#' tskit Python API. Since the class only holds the pointer, it is lightweight. -#' Currently there is a limited set of R methods for working the tree sequence. +#' @description An \code{R6} class holding an external pointer to +#' a table collection object. As an \code{R6} class, method-calling looks Pythonic +#' and hence resembles the \code{tskit Python} API. Since the class only +#' holds the pointer, it is lightweight. Currently there is a limited set of +#' \code{R} methods for working with the table collection object. #' @export TableCollection <- R6Class( classname = "TableCollection", @@ -16,7 +17,7 @@ TableCollection <- R6Class( #' @param skip_reference_sequence logical; if \code{TRUE}, skip loading #' reference genome sequence information. #' @param xptr an external pointer (\code{externalptr}) to a table collection. - #' @details See the corresponding Python function at + #' @details See the \code{tskit Python} equivalent at #' \url{https://github.com/tskit-dev/tskit/blob/dc394d72d121c99c6dcad88f7a4873880924dd72/python/tskit/tables.py#L3463}. #' TODO: Update URL to TableCollection.load() method #104 #' https://github.com/HighlanderLab/RcppTskit/issues/104 @@ -65,7 +66,7 @@ TableCollection <- R6Class( #' @description Write a table collection to a file. #' @param file a string specifying the full path of the tree sequence file. - #' @details See the corresponding Python function at + #' @details See the \code{tskit Python} equivalent at #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TableCollection.dump}. #' @return No return value; called for side effects. #' @examples @@ -86,7 +87,7 @@ TableCollection <- R6Class( }, #' @description Create a \code{\link{TreeSequence}} from this table collection. - #' @details See the corresponding Python function at + #' @details See the \code{tskit Python} equivalent at #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TableCollection.tree_sequence}. #' @return A \code{\link{TreeSequence}} object. #' @examples @@ -102,7 +103,88 @@ TableCollection <- R6Class( TreeSequence$new(xptr = ts_xptr) }, + #' @description Get the number of provenances in a table collection. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @examples + #' tc_file <- system.file("examples/test.trees", package = "RcppTskit") + #' tc <- tc_load(tc_file) + #' tc$num_provenances() + num_provenances = function() { + rtsk_table_collection_get_num_provenances(self$xptr) + }, + + #' @description Get the number of populations in a table collection. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @examples + #' tc_file <- system.file("examples/test.trees", package = "RcppTskit") + #' tc <- tc_load(tc_file) + #' tc$num_populations() + num_populations = function() { + rtsk_table_collection_get_num_populations(self$xptr) + }, + + #' @description Get the number of migrations in a table collection. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @examples + #' tc_file <- system.file("examples/test.trees", package = "RcppTskit") + #' tc <- tc_load(tc_file) + #' tc$num_migrations() + num_migrations = function() { + rtsk_table_collection_get_num_migrations(self$xptr) + }, + + #' @description Get the number of individuals in a table collection. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @examples + #' tc_file <- system.file("examples/test.trees", package = "RcppTskit") + #' tc <- tc_load(tc_file) + #' tc$num_individuals() + num_individuals = function() { + rtsk_table_collection_get_num_individuals(self$xptr) + }, + + #' @description Get the number of nodes in a table collection. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @examples + #' tc_file <- system.file("examples/test.trees", package = "RcppTskit") + #' tc <- tc_load(tc_file) + #' tc$num_nodes() + num_nodes = function() { + rtsk_table_collection_get_num_nodes(self$xptr) + }, + + #' @description Get the number of edges in a table collection. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @examples + #' tc_file <- system.file("examples/test.trees", package = "RcppTskit") + #' tc <- tc_load(tc_file) + #' tc$num_edges() + num_edges = function() { + rtsk_table_collection_get_num_edges(self$xptr) + }, + + #' @description Get the number of sites in a table collection. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @examples + #' tc_file <- system.file("examples/test.trees", package = "RcppTskit") + #' tc <- tc_load(tc_file) + #' tc$num_sites() + num_sites = function() { + rtsk_table_collection_get_num_sites(self$xptr) + }, + + #' @description Get the number of mutations in a table collection. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @examples + #' tc_file <- system.file("examples/test.trees", package = "RcppTskit") + #' tc <- tc_load(tc_file) + #' tc$num_mutations() + num_mutations = function() { + rtsk_table_collection_get_num_mutations(self$xptr) + }, + #' @description Get the sequence length. + #' @return A numeric. #' @examples #' tc_file <- system.file("examples/test.trees", package = "RcppTskit") #' tc <- tc_load(tc_file) @@ -112,6 +194,7 @@ TableCollection <- R6Class( }, #' @description Get the time units string. + #' @return A character. #' @examples #' tc_file <- system.file("examples/test.trees", package = "RcppTskit") #' tc <- tc_load(tc_file) @@ -121,6 +204,7 @@ TableCollection <- R6Class( }, #' @description Get whether the table collection has edge indexes. + #' @return A logical. #' @examples #' tc_file <- system.file("examples/test.trees", package = "RcppTskit") #' tc <- tc_load(tc_file) @@ -130,7 +214,7 @@ TableCollection <- R6Class( }, #' @description Build edge indexes for this table collection. - #' @details See the corresponding Python function at + #' @details See the \code{tskit Python} equivalent at #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TableCollection.build_index}. #' @return No return value; called for side effects. #' @examples @@ -146,7 +230,7 @@ TableCollection <- R6Class( }, #' @description Drop edge indexes for this table collection. - #' @details See the corresponding Python function at + #' @details See the \code{tskit Python} equivalent at #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TableCollection.drop_index}. #' @return No return value; called for side effects. #' @examples @@ -160,6 +244,7 @@ TableCollection <- R6Class( }, #' @description Get whether the table collection has a reference genome sequence. + #' @return A logical. #' @examples #' tc_file1 <- system.file("examples/test.trees", package = "RcppTskit") #' tc_file2 <- system.file("examples/test_with_ref_seq.trees", package = "RcppTskit") @@ -171,9 +256,10 @@ TableCollection <- R6Class( rtsk_table_collection_has_reference_sequence(self$xptr) }, - #' @description Get the file UUID string. - #' @details Returns the UUID of the file the table collection was loaded from. - #' If unavailable, returns \code{NA_character_}. + #' @description Get the UUID string of the file the table collection was + #' loaded from. + #' @return A character; \code{NA_character_} when file is information is + #' unavailable. #' @examples #' tc_file <- system.file("examples/test.trees", package = "RcppTskit") #' tc <- tc_load(tc_file) @@ -182,14 +268,15 @@ TableCollection <- R6Class( rtsk_table_collection_get_file_uuid(self$xptr) }, - #' @description This function saves a table collection from R to disk and - #' loads it into reticulate Python for use with the \code{tskit} Python API. - #' @param tskit_module reticulate Python module of \code{tskit}. By default, - #' it calls \code{\link{get_tskit_py}} to obtain the module. + #' @description This function saves a table collection from \code{R} to disk + #' and loads it into reticulate \code{Python} for use with the + #' \code{tskit Python} API. + #' @param tskit_module reticulate \code{Python} module of \code{tskit}. + #' By default, it calls \code{\link{get_tskit_py}} to obtain the module. #' @param cleanup logical; delete the temporary file at the end of the function? #' @details See \url{https://tskit.dev/tutorials/tables_and_editing.html#tables-and-editing} #' on what you can do with the tables. - #' @return Table collection in reticulate Python. + #' @return \code{TableCollection} object in reticulate \code{Python}. #' @seealso \code{\link{tc_py_to_r}}, \code{\link{tc_load}}, and #' \code{\link[=TableCollection]{TableCollection$dump}}. #' @examples @@ -222,7 +309,9 @@ TableCollection <- R6Class( #' @description Print a summary of a table collection and its contents. #' @return A list with two data.frames; the first contains table collection #' properties and their values; the second contains the number of rows in - #' each table and the length of their metadata. + #' each table and the length of their metadata. All columns are characters + #' since output types differ across the entries. Use individual getters + #' to obtain raw values before they are converted to character. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' tc <- tc_load(file = ts_file) diff --git a/RcppTskit/R/Class-TreeSequence.R b/RcppTskit/R/Class-TreeSequence.R index e61d3a0..957619d 100644 --- a/RcppTskit/R/Class-TreeSequence.R +++ b/RcppTskit/R/Class-TreeSequence.R @@ -1,8 +1,9 @@ #' @title Succinct tree sequence R6 class (TreeSequence) -#' @description An R6 class holding an external pointer to a tree sequence -#' object. As an R6 class, its methods look Pythonic and therefore resemble the -#' tskit Python API. Since the class only holds the pointer, it is lightweight. -#' Currently there is a limited set of R methods for working with the tree sequence. +#' @description An \code{R6} class holding an external pointer to +#' a tree sequence object. As an \code{R6} class, method-calling looks Pythonic +#' and hence resembles the \code{tskit Python} API. Since the class only +#' holds the pointer, it is lightweight. Currently there is a limited set of +#' \code{R} methods for working with the tree sequence. #' @export TreeSequence <- R6Class( classname = "TreeSequence", @@ -17,7 +18,7 @@ TreeSequence <- R6Class( #' @param skip_reference_sequence logical; if \code{TRUE}, skip loading #' reference genome sequence information. #' @param xptr an external pointer (\code{externalptr}) to a tree sequence. - #' @details See the corresponding Python function at + #' @details See the \code{tskit Python} equivalent at #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.load}. #' @return A \code{\link{TreeSequence}} object. #' @seealso \code{\link{ts_load}} @@ -66,7 +67,7 @@ TreeSequence <- R6Class( #' @description Write a tree sequence to a file. #' @param file a string specifying the full path of the tree sequence file. - #' @details See the corresponding Python function at + #' @details See the \code{tskit Python} equivalent at #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.dump}. #' @return No return value; called for side effects. #' @examples @@ -87,7 +88,7 @@ TreeSequence <- R6Class( }, #' @description Copy the tables into a \code{\link{TableCollection}}. - #' @details See the corresponding Python function at + #' @details See the \code{tskit Python} equivalent at #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.dump_tables}. #' @return A \code{\link{TableCollection}} object. #' @examples @@ -103,7 +104,9 @@ TreeSequence <- R6Class( #' @description Print a summary of a tree sequence and its contents. #' @return A list with two data.frames; the first contains tree sequence #' properties and their values; the second contains the number of rows in - #' each table and the length of their metadata. + #' each table and the length of their metadata. All columns are characters + #' since output types differ across the entries. Use individual getters + #' to obtain raw values before they are converted to character. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' ts <- ts_load(ts_file) @@ -121,12 +124,13 @@ TreeSequence <- R6Class( invisible(ret) }, - #' @description This function saves a tree sequence from R to disk and - #' loads it into reticulate Python for use with the \code{tskit} Python API. - #' @param tskit_module reticulate Python module of \code{tskit}. By default, - #' it calls \code{\link{get_tskit_py}} to obtain the module. + #' @description This function saves a tree sequence from \code{R} to disk + #' and loads it into reticulate \code{Python} for use with the + #' \code{tskit Python} API. + #' @param tskit_module reticulate \code{Python} module of \code{tskit}. + #' By default, it calls \code{\link{get_tskit_py}} to obtain the module. #' @param cleanup logical; delete the temporary file at the end of the function? - #' @return Tree sequence in reticulate Python. + #' @return \code{TreeSequence} object in reticulate \code{Python}. #' @seealso \code{\link{ts_py_to_r}}, \code{\link{ts_load}}, and #' \code{\link[=TreeSequence]{TreeSequence$dump}}. #' @examples @@ -158,6 +162,9 @@ TreeSequence <- R6Class( }, #' @description Get the number of provenances in a tree sequence. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @details See the \code{tskit Python} equivalent at + #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_provenances}. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' ts <- ts_load(ts_file) @@ -167,6 +174,9 @@ TreeSequence <- R6Class( }, #' @description Get the number of populations in a tree sequence. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @details See the \code{tskit Python} equivalent at + #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_populations}. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' ts <- ts_load(ts_file) @@ -176,6 +186,9 @@ TreeSequence <- R6Class( }, #' @description Get the number of migrations in a tree sequence. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @details See the \code{tskit Python} equivalent at + #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_migrations}. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' ts <- ts_load(ts_file) @@ -185,6 +198,9 @@ TreeSequence <- R6Class( }, #' @description Get the number of individuals in a tree sequence. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @details See the \code{tskit Python} equivalent at + #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_individuals}. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' ts <- ts_load(ts_file) @@ -194,6 +210,9 @@ TreeSequence <- R6Class( }, #' @description Get the number of samples (of nodes) in a tree sequence. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @details See the \code{tskit Python} equivalent at + #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_samples}. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' ts <- ts_load(ts_file) @@ -203,6 +222,9 @@ TreeSequence <- R6Class( }, #' @description Get the number of nodes in a tree sequence. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @details See the \code{tskit Python} equivalent at + #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_nodes}. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' ts <- ts_load(ts_file) @@ -212,6 +234,9 @@ TreeSequence <- R6Class( }, #' @description Get the number of edges in a tree sequence. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @details See the \code{tskit Python} equivalent at + #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_nodes}. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' ts <- ts_load(ts_file) @@ -221,6 +246,9 @@ TreeSequence <- R6Class( }, #' @description Get the number of trees in a tree sequence. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @details See the \code{tskit Python} equivalent at + #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_trees}. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' ts <- ts_load(ts_file) @@ -230,6 +258,9 @@ TreeSequence <- R6Class( }, #' @description Get the number of sites in a tree sequence. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @details See the \code{tskit Python} equivalent at + #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_sites}. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' ts <- ts_load(ts_file) @@ -239,6 +270,9 @@ TreeSequence <- R6Class( }, #' @description Get the number of mutations in a tree sequence. + #' @return A signed 64 bit integer \code{bit64::integer64}. + #' @details See the \code{tskit Python} equivalent at + #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_mutations}. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' ts <- ts_load(ts_file) @@ -248,6 +282,9 @@ TreeSequence <- R6Class( }, #' @description Get the sequence length. + #' @return A numeric. + #' @details See the \code{tskit Python} equivalent at + #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.sequence_length}. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' ts <- ts_load(ts_file) @@ -259,6 +296,9 @@ TreeSequence <- R6Class( #' @description Get the discrete genome status. #' @details Returns \code{TRUE} if all genomic coordinates in the tree #' sequence are discrete integer values. + #' @details See the \code{tskit Python} equivalent at + #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.discrete_genome}. + #' @return A logical. #' @examples #' ts_file1 <- system.file("examples/test.trees", package = "RcppTskit") #' ts_file2 <- system.file("examples/test_non_discrete_genome.trees", package = "RcppTskit") @@ -271,6 +311,9 @@ TreeSequence <- R6Class( }, #' @description Get whether the tree sequence has a reference genome sequence. + #' @return A logical. + #' @details See the \code{tskit Python} equivalent at + #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.has_reference_sequence}. #' @examples #' ts_file1 <- system.file("examples/test.trees", package = "RcppTskit") #' ts_file2 <- system.file("examples/test_with_ref_seq.trees", package = "RcppTskit") @@ -283,6 +326,9 @@ TreeSequence <- R6Class( }, #' @description Get the time units string. + #' @return A character. + #' @details See the \code{tskit Python} equivalent at + #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.time_units}. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' ts <- ts_load(ts_file) @@ -294,6 +340,9 @@ TreeSequence <- R6Class( #' @description Get the discrete time status. #' @details Returns \code{TRUE} if all time values in the tree sequence are #' discrete integer values. + #' @details See the \code{tskit Python} equivalent at + #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.discrete_time}. + #' @return A logical. #' @examples #' ts_file1 <- system.file("examples/test.trees", package = "RcppTskit") #' ts_file2 <- system.file("examples/test_discrete_time.trees", package = "RcppTskit") @@ -306,6 +355,9 @@ TreeSequence <- R6Class( }, #' @description Get the min time in node table and mutation table. + #' @details See the \code{tskit Python} equivalent at + #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.min_time}. + #' @return A numeric. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' ts <- ts_load(ts_file) @@ -315,6 +367,9 @@ TreeSequence <- R6Class( }, #' @description Get the max time in node table and mutation table. + #' @details See the \code{tskit Python} equivalent at + #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.max_time}. + #' @return A numeric. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' ts <- ts_load(ts_file) @@ -323,8 +378,10 @@ TreeSequence <- R6Class( rtsk_treeseq_get_max_time(self$xptr) }, + # No Python equivalent in the docs as of 2026-03-03 #' @description Get the length of metadata in a tree sequence and its tables. - #' @return A named list with the length of metadata. + #' @return A named list with the length of metadata, each as a signed 64 bit + #' integer \code{bit64::integer64}. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' ts <- ts_load(ts_file) @@ -333,9 +390,11 @@ TreeSequence <- R6Class( rtsk_treeseq_metadata_length(self$xptr) }, - #' @description Get the file UUID string. - #' @details Returns the UUID of the file the tree sequence was loaded from. - #' If unavailable, returns \code{NA_character_}. + # No Python equivalent in the docs as of 2026-03-03 + #' @description Get the UUID string of the file the tree sequence was + #' loaded from. + #' @return A character; \code{NA_character_} when file is information is + #' unavailable. #' @examples #' ts_file <- system.file("examples/test.trees", package = "RcppTskit") #' ts <- ts_load(ts_file) diff --git a/RcppTskit/R/RcppExports.R b/RcppTskit/R/RcppExports.R index 915b68a..e2e2676 100644 --- a/RcppTskit/R/RcppExports.R +++ b/RcppTskit/R/RcppExports.R @@ -135,6 +135,38 @@ rtsk_treeseq_metadata_length <- function(ts) { .Call(`_RcppTskit_rtsk_treeseq_metadata_length`, ts) } +rtsk_table_collection_get_num_provenances <- function(tc) { + .Call(`_RcppTskit_rtsk_table_collection_get_num_provenances`, tc) +} + +rtsk_table_collection_get_num_populations <- function(tc) { + .Call(`_RcppTskit_rtsk_table_collection_get_num_populations`, tc) +} + +rtsk_table_collection_get_num_migrations <- function(tc) { + .Call(`_RcppTskit_rtsk_table_collection_get_num_migrations`, tc) +} + +rtsk_table_collection_get_num_individuals <- function(tc) { + .Call(`_RcppTskit_rtsk_table_collection_get_num_individuals`, tc) +} + +rtsk_table_collection_get_num_nodes <- function(tc) { + .Call(`_RcppTskit_rtsk_table_collection_get_num_nodes`, tc) +} + +rtsk_table_collection_get_num_edges <- function(tc) { + .Call(`_RcppTskit_rtsk_table_collection_get_num_edges`, tc) +} + +rtsk_table_collection_get_num_sites <- function(tc) { + .Call(`_RcppTskit_rtsk_table_collection_get_num_sites`, tc) +} + +rtsk_table_collection_get_num_mutations <- function(tc) { + .Call(`_RcppTskit_rtsk_table_collection_get_num_mutations`, tc) +} + rtsk_table_collection_get_sequence_length <- function(tc) { .Call(`_RcppTskit_rtsk_table_collection_get_sequence_length`, tc) } diff --git a/RcppTskit/R/RcppTskit.R b/RcppTskit/R/RcppTskit.R index 9ade202..d99a468 100644 --- a/RcppTskit/R/RcppTskit.R +++ b/RcppTskit/R/RcppTskit.R @@ -140,7 +140,7 @@ load_args_to_options <- function( #' @param skip_tables logical; if \code{TRUE}, load only non-table information. #' @param skip_reference_sequence logical; if \code{TRUE}, skip loading #' reference genome sequence information. -#' @details See the corresponding Python function at +#' @details See the \code{tskit Python} equivalent at #' \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.load}. #' @return A \code{\link{TreeSequence}} object. #' @seealso \code{\link[=TreeSequence]{TreeSequence$new}} @@ -177,7 +177,7 @@ ts_read <- ts_load #' @param skip_reference_sequence logical; if \code{TRUE}, skip loading #' reference genome sequence information. #' @return A \code{\link{TableCollection}} object. -#' @details See the corresponding Python function at +#' @details See the \code{tskit Python} equivalent at #' \url{https://github.com/tskit-dev/tskit/blob/dc394d72d121c99c6dcad88f7a4873880924dd72/python/tskit/tables.py#L3463}. #' TODO: Update URL to TableCollection.load() method #104 #' https://github.com/HighlanderLab/RcppTskit/issues/104 diff --git a/RcppTskit/inst/include/RcppTskit_public.hpp b/RcppTskit/inst/include/RcppTskit_public.hpp index 696d0d0..eb4b7fc 100644 --- a/RcppTskit/inst/include/RcppTskit_public.hpp +++ b/RcppTskit/inst/include/RcppTskit_public.hpp @@ -40,6 +40,14 @@ Rcpp::String rtsk_treeseq_get_file_uuid(SEXP ts); Rcpp::List rtsk_treeseq_summary(SEXP ts); Rcpp::List rtsk_treeseq_metadata_length(SEXP ts); +SEXP rtsk_table_collection_get_num_provenances(SEXP tc); +SEXP rtsk_table_collection_get_num_populations(SEXP tc); +SEXP rtsk_table_collection_get_num_migrations(SEXP tc); +SEXP rtsk_table_collection_get_num_individuals(SEXP tc); +SEXP rtsk_table_collection_get_num_nodes(SEXP tc); +SEXP rtsk_table_collection_get_num_edges(SEXP tc); +SEXP rtsk_table_collection_get_num_sites(SEXP tc); +SEXP rtsk_table_collection_get_num_mutations(SEXP tc); double rtsk_table_collection_get_sequence_length(SEXP tc); bool rtsk_table_collection_has_reference_sequence(SEXP tc); Rcpp::String rtsk_table_collection_get_time_units(SEXP tc); diff --git a/RcppTskit/man/TableCollection.Rd b/RcppTskit/man/TableCollection.Rd index a780ac0..cbce99d 100644 --- a/RcppTskit/man/TableCollection.Rd +++ b/RcppTskit/man/TableCollection.Rd @@ -4,10 +4,11 @@ \alias{TableCollection} \title{Table collection R6 class (TableCollection)} \description{ -An R6 class holding an external pointer to a table collection -object. As an R6 class, its methods look Pythonic and therefore resemble the -tskit Python API. Since the class only holds the pointer, it is lightweight. -Currently there is a limited set of R methods for working the tree sequence. +An \code{R6} class holding an external pointer to +a table collection object. As an \code{R6} class, method-calling looks Pythonic +and hence resembles the \code{tskit Python} API. Since the class only +holds the pointer, it is lightweight. Currently there is a limited set of +\code{R} methods for working with the table collection object. } \examples{ @@ -40,6 +41,70 @@ tc <- TableCollection$new(file = ts_file) ts <- tc$tree_sequence() is(ts) +## ------------------------------------------------ +## Method `TableCollection$num_provenances` +## ------------------------------------------------ + +tc_file <- system.file("examples/test.trees", package = "RcppTskit") +tc <- tc_load(tc_file) +tc$num_provenances() + +## ------------------------------------------------ +## Method `TableCollection$num_populations` +## ------------------------------------------------ + +tc_file <- system.file("examples/test.trees", package = "RcppTskit") +tc <- tc_load(tc_file) +tc$num_populations() + +## ------------------------------------------------ +## Method `TableCollection$num_migrations` +## ------------------------------------------------ + +tc_file <- system.file("examples/test.trees", package = "RcppTskit") +tc <- tc_load(tc_file) +tc$num_migrations() + +## ------------------------------------------------ +## Method `TableCollection$num_individuals` +## ------------------------------------------------ + +tc_file <- system.file("examples/test.trees", package = "RcppTskit") +tc <- tc_load(tc_file) +tc$num_individuals() + +## ------------------------------------------------ +## Method `TableCollection$num_nodes` +## ------------------------------------------------ + +tc_file <- system.file("examples/test.trees", package = "RcppTskit") +tc <- tc_load(tc_file) +tc$num_nodes() + +## ------------------------------------------------ +## Method `TableCollection$num_edges` +## ------------------------------------------------ + +tc_file <- system.file("examples/test.trees", package = "RcppTskit") +tc <- tc_load(tc_file) +tc$num_edges() + +## ------------------------------------------------ +## Method `TableCollection$num_sites` +## ------------------------------------------------ + +tc_file <- system.file("examples/test.trees", package = "RcppTskit") +tc <- tc_load(tc_file) +tc$num_sites() + +## ------------------------------------------------ +## Method `TableCollection$num_mutations` +## ------------------------------------------------ + +tc_file <- system.file("examples/test.trees", package = "RcppTskit") +tc <- tc_load(tc_file) +tc$num_mutations() + ## ------------------------------------------------ ## Method `TableCollection$sequence_length` ## ------------------------------------------------ @@ -155,6 +220,14 @@ tc \item \href{#method-TableCollection-dump}{\code{TableCollection$dump()}} \item \href{#method-TableCollection-write}{\code{TableCollection$write()}} \item \href{#method-TableCollection-tree_sequence}{\code{TableCollection$tree_sequence()}} +\item \href{#method-TableCollection-num_provenances}{\code{TableCollection$num_provenances()}} +\item \href{#method-TableCollection-num_populations}{\code{TableCollection$num_populations()}} +\item \href{#method-TableCollection-num_migrations}{\code{TableCollection$num_migrations()}} +\item \href{#method-TableCollection-num_individuals}{\code{TableCollection$num_individuals()}} +\item \href{#method-TableCollection-num_nodes}{\code{TableCollection$num_nodes()}} +\item \href{#method-TableCollection-num_edges}{\code{TableCollection$num_edges()}} +\item \href{#method-TableCollection-num_sites}{\code{TableCollection$num_sites()}} +\item \href{#method-TableCollection-num_mutations}{\code{TableCollection$num_mutations()}} \item \href{#method-TableCollection-sequence_length}{\code{TableCollection$sequence_length()}} \item \href{#method-TableCollection-time_units}{\code{TableCollection$time_units()}} \item \href{#method-TableCollection-has_index}{\code{TableCollection$has_index()}} @@ -196,8 +269,10 @@ reference genome sequence information.} \if{html}{\out{}} } \subsection{Details}{ -See the corresponding Python function at +See the \code{tskit Python} equivalent at \url{https://github.com/tskit-dev/tskit/blob/dc394d72d121c99c6dcad88f7a4873880924dd72/python/tskit/tables.py#L3463}. + TODO: Update URL to TableCollection.load() method #104 + https://github.com/HighlanderLab/RcppTskit/issues/104 } \subsection{Returns}{ @@ -232,7 +307,7 @@ Write a table collection to a file. \if{html}{\out{}} } \subsection{Details}{ -See the corresponding Python function at +See the \code{tskit Python} equivalent at \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TableCollection.dump}. } @@ -280,7 +355,7 @@ Create a \code{\link{TreeSequence}} from this table collection. } \subsection{Details}{ -See the corresponding Python function at +See the \code{tskit Python} equivalent at \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TableCollection.tree_sequence}. } @@ -298,6 +373,190 @@ is(ts) } +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-TableCollection-num_provenances}{}}} +\subsection{Method \code{num_provenances()}}{ +Get the number of provenances in a table collection. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{TableCollection$num_provenances()}\if{html}{\out{
}} +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} +\subsection{Examples}{ +\if{html}{\out{
}} +\preformatted{tc_file <- system.file("examples/test.trees", package = "RcppTskit") +tc <- tc_load(tc_file) +tc$num_provenances() +} +\if{html}{\out{
}} + +} + +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-TableCollection-num_populations}{}}} +\subsection{Method \code{num_populations()}}{ +Get the number of populations in a table collection. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{TableCollection$num_populations()}\if{html}{\out{
}} +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} +\subsection{Examples}{ +\if{html}{\out{
}} +\preformatted{tc_file <- system.file("examples/test.trees", package = "RcppTskit") +tc <- tc_load(tc_file) +tc$num_populations() +} +\if{html}{\out{
}} + +} + +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-TableCollection-num_migrations}{}}} +\subsection{Method \code{num_migrations()}}{ +Get the number of migrations in a table collection. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{TableCollection$num_migrations()}\if{html}{\out{
}} +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} +\subsection{Examples}{ +\if{html}{\out{
}} +\preformatted{tc_file <- system.file("examples/test.trees", package = "RcppTskit") +tc <- tc_load(tc_file) +tc$num_migrations() +} +\if{html}{\out{
}} + +} + +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-TableCollection-num_individuals}{}}} +\subsection{Method \code{num_individuals()}}{ +Get the number of individuals in a table collection. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{TableCollection$num_individuals()}\if{html}{\out{
}} +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} +\subsection{Examples}{ +\if{html}{\out{
}} +\preformatted{tc_file <- system.file("examples/test.trees", package = "RcppTskit") +tc <- tc_load(tc_file) +tc$num_individuals() +} +\if{html}{\out{
}} + +} + +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-TableCollection-num_nodes}{}}} +\subsection{Method \code{num_nodes()}}{ +Get the number of nodes in a table collection. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{TableCollection$num_nodes()}\if{html}{\out{
}} +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} +\subsection{Examples}{ +\if{html}{\out{
}} +\preformatted{tc_file <- system.file("examples/test.trees", package = "RcppTskit") +tc <- tc_load(tc_file) +tc$num_nodes() +} +\if{html}{\out{
}} + +} + +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-TableCollection-num_edges}{}}} +\subsection{Method \code{num_edges()}}{ +Get the number of edges in a table collection. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{TableCollection$num_edges()}\if{html}{\out{
}} +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} +\subsection{Examples}{ +\if{html}{\out{
}} +\preformatted{tc_file <- system.file("examples/test.trees", package = "RcppTskit") +tc <- tc_load(tc_file) +tc$num_edges() +} +\if{html}{\out{
}} + +} + +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-TableCollection-num_sites}{}}} +\subsection{Method \code{num_sites()}}{ +Get the number of sites in a table collection. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{TableCollection$num_sites()}\if{html}{\out{
}} +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} +\subsection{Examples}{ +\if{html}{\out{
}} +\preformatted{tc_file <- system.file("examples/test.trees", package = "RcppTskit") +tc <- tc_load(tc_file) +tc$num_sites() +} +\if{html}{\out{
}} + +} + +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-TableCollection-num_mutations}{}}} +\subsection{Method \code{num_mutations()}}{ +Get the number of mutations in a table collection. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{TableCollection$num_mutations()}\if{html}{\out{
}} +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} +\subsection{Examples}{ +\if{html}{\out{
}} +\preformatted{tc_file <- system.file("examples/test.trees", package = "RcppTskit") +tc <- tc_load(tc_file) +tc$num_mutations() +} +\if{html}{\out{
}} + +} + } \if{html}{\out{
}} \if{html}{\out{}} @@ -308,6 +567,9 @@ Get the sequence length. \if{html}{\out{
}}\preformatted{TableCollection$sequence_length()}\if{html}{\out{
}} } +\subsection{Returns}{ +A numeric. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{tc_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -328,6 +590,9 @@ Get the time units string. \if{html}{\out{
}}\preformatted{TableCollection$time_units()}\if{html}{\out{
}} } +\subsection{Returns}{ +A character. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{tc_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -348,6 +613,9 @@ Get whether the table collection has edge indexes. \if{html}{\out{
}}\preformatted{TableCollection$has_index()}\if{html}{\out{
}} } +\subsection{Returns}{ +A logical. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{tc_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -369,7 +637,7 @@ Build edge indexes for this table collection. } \subsection{Details}{ -See the corresponding Python function at +See the \code{tskit Python} equivalent at \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TableCollection.build_index}. } @@ -401,7 +669,7 @@ Drop edge indexes for this table collection. } \subsection{Details}{ -See the corresponding Python function at +See the \code{tskit Python} equivalent at \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TableCollection.drop_index}. } @@ -430,6 +698,9 @@ Get whether the table collection has a reference genome sequence. \if{html}{\out{
}}\preformatted{TableCollection$has_reference_sequence()}\if{html}{\out{
}} } +\subsection{Returns}{ +A logical. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{tc_file1 <- system.file("examples/test.trees", package = "RcppTskit") @@ -448,16 +719,16 @@ tc2$has_reference_sequence() \if{html}{\out{}} \if{latex}{\out{\hypertarget{method-TableCollection-file_uuid}{}}} \subsection{Method \code{file_uuid()}}{ -Get the file UUID string. +Get the UUID string of the file the table collection was + loaded from. \subsection{Usage}{ \if{html}{\out{
}}\preformatted{TableCollection$file_uuid()}\if{html}{\out{
}} } -\subsection{Details}{ -Returns the UUID of the file the table collection was loaded from. - If unavailable, returns \code{NA_character_}. +\subsection{Returns}{ +A character; \code{NA_character_} when file is information is + unavailable. } - \subsection{Examples}{ \if{html}{\out{
}} \preformatted{tc_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -473,8 +744,9 @@ tc$file_uuid() \if{html}{\out{}} \if{latex}{\out{\hypertarget{method-TableCollection-r_to_py}{}}} \subsection{Method \code{r_to_py()}}{ -This function saves a table collection from R to disk and - loads it into reticulate Python for use with the \code{tskit} Python API. +This function saves a table collection from \code{R} to disk + and loads it into reticulate \code{Python} for use with the + \code{tskit Python} API. \subsection{Usage}{ \if{html}{\out{
}}\preformatted{TableCollection$r_to_py(tskit_module = get_tskit_py(), cleanup = TRUE)}\if{html}{\out{
}} } @@ -482,8 +754,8 @@ This function saves a table collection from R to disk and \subsection{Arguments}{ \if{html}{\out{
}} \describe{ -\item{\code{tskit_module}}{reticulate Python module of \code{tskit}. By default, -it calls \code{\link{get_tskit_py}} to obtain the module.} +\item{\code{tskit_module}}{reticulate \code{Python} module of \code{tskit}. +By default, it calls \code{\link{get_tskit_py}} to obtain the module.} \item{\code{cleanup}}{logical; delete the temporary file at the end of the function?} } @@ -495,7 +767,7 @@ See \url{https://tskit.dev/tutorials/tables_and_editing.html#tables-and-editing} } \subsection{Returns}{ -Table collection in reticulate Python. +\code{TableCollection} object in reticulate \code{Python}. } \subsection{Examples}{ \if{html}{\out{
}} @@ -535,7 +807,9 @@ Print a summary of a table collection and its contents. \subsection{Returns}{ A list with two data.frames; the first contains table collection properties and their values; the second contains the number of rows in - each table and the length of their metadata. + each table and the length of their metadata. All columns are characters + since output types differ across the entries. Use individual getters + to obtain raw values before they are converted to character. } \subsection{Examples}{ \if{html}{\out{
}} diff --git a/RcppTskit/man/TreeSequence.Rd b/RcppTskit/man/TreeSequence.Rd index d439baa..2ab1eba 100644 --- a/RcppTskit/man/TreeSequence.Rd +++ b/RcppTskit/man/TreeSequence.Rd @@ -4,10 +4,11 @@ \alias{TreeSequence} \title{Succinct tree sequence R6 class (TreeSequence)} \description{ -An R6 class holding an external pointer to a tree sequence -object. As an R6 class, its methods look Pythonic and therefore resemble the -tskit Python API. Since the class only holds the pointer, it is lightweight. -Currently there is a limited set of R methods for working with the tree sequence. +An \code{R6} class holding an external pointer to +a tree sequence object. As an \code{R6} class, method-calling looks Pythonic +and hence resembles the \code{tskit Python} API. Since the class only +holds the pointer, it is lightweight. Currently there is a limited set of +\code{R} methods for working with the tree sequence. } \examples{ @@ -312,7 +313,7 @@ reference genome sequence information.} \if{html}{\out{
}} } \subsection{Details}{ -See the corresponding Python function at +See the \code{tskit Python} equivalent at \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.load}. } @@ -352,7 +353,7 @@ Write a tree sequence to a file. \if{html}{\out{
}} } \subsection{Details}{ -See the corresponding Python function at +See the \code{tskit Python} equivalent at \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.dump}. } @@ -400,7 +401,7 @@ Copy the tables into a \code{\link{TableCollection}}. } \subsection{Details}{ -See the corresponding Python function at +See the \code{tskit Python} equivalent at \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.dump_tables}. } @@ -431,7 +432,9 @@ Print a summary of a tree sequence and its contents. \subsection{Returns}{ A list with two data.frames; the first contains tree sequence properties and their values; the second contains the number of rows in - each table and the length of their metadata. + each table and the length of their metadata. All columns are characters + since output types differ across the entries. Use individual getters + to obtain raw values before they are converted to character. } \subsection{Examples}{ \if{html}{\out{
}} @@ -449,8 +452,9 @@ ts \if{html}{\out{}} \if{latex}{\out{\hypertarget{method-TreeSequence-r_to_py}{}}} \subsection{Method \code{r_to_py()}}{ -This function saves a tree sequence from R to disk and - loads it into reticulate Python for use with the \code{tskit} Python API. +This function saves a tree sequence from \code{R} to disk + and loads it into reticulate \code{Python} for use with the + \code{tskit Python} API. \subsection{Usage}{ \if{html}{\out{
}}\preformatted{TreeSequence$r_to_py(tskit_module = get_tskit_py(), cleanup = TRUE)}\if{html}{\out{
}} } @@ -458,15 +462,15 @@ This function saves a tree sequence from R to disk and \subsection{Arguments}{ \if{html}{\out{
}} \describe{ -\item{\code{tskit_module}}{reticulate Python module of \code{tskit}. By default, -it calls \code{\link{get_tskit_py}} to obtain the module.} +\item{\code{tskit_module}}{reticulate \code{Python} module of \code{tskit}. +By default, it calls \code{\link{get_tskit_py}} to obtain the module.} \item{\code{cleanup}}{logical; delete the temporary file at the end of the function?} } \if{html}{\out{
}} } \subsection{Returns}{ -Tree sequence in reticulate Python. +\code{TreeSequence} object in reticulate \code{Python}. } \subsection{Examples}{ \if{html}{\out{
}} @@ -504,6 +508,14 @@ Get the number of provenances in a tree sequence. \if{html}{\out{
}}\preformatted{TreeSequence$num_provenances()}\if{html}{\out{
}} } +\subsection{Details}{ +See the \code{tskit Python} equivalent at + \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_provenances}. +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -524,6 +536,14 @@ Get the number of populations in a tree sequence. \if{html}{\out{
}}\preformatted{TreeSequence$num_populations()}\if{html}{\out{
}} } +\subsection{Details}{ +See the \code{tskit Python} equivalent at + \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_populations}. +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -544,6 +564,14 @@ Get the number of migrations in a tree sequence. \if{html}{\out{
}}\preformatted{TreeSequence$num_migrations()}\if{html}{\out{
}} } +\subsection{Details}{ +See the \code{tskit Python} equivalent at + \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_migrations}. +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -564,6 +592,14 @@ Get the number of individuals in a tree sequence. \if{html}{\out{
}}\preformatted{TreeSequence$num_individuals()}\if{html}{\out{
}} } +\subsection{Details}{ +See the \code{tskit Python} equivalent at + \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_individuals}. +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -584,6 +620,14 @@ Get the number of samples (of nodes) in a tree sequence. \if{html}{\out{
}}\preformatted{TreeSequence$num_samples()}\if{html}{\out{
}} } +\subsection{Details}{ +See the \code{tskit Python} equivalent at + \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_samples}. +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -604,6 +648,14 @@ Get the number of nodes in a tree sequence. \if{html}{\out{
}}\preformatted{TreeSequence$num_nodes()}\if{html}{\out{
}} } +\subsection{Details}{ +See the \code{tskit Python} equivalent at + \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_nodes}. +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -624,6 +676,14 @@ Get the number of edges in a tree sequence. \if{html}{\out{
}}\preformatted{TreeSequence$num_edges()}\if{html}{\out{
}} } +\subsection{Details}{ +See the \code{tskit Python} equivalent at + \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_nodes}. +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -644,6 +704,14 @@ Get the number of trees in a tree sequence. \if{html}{\out{
}}\preformatted{TreeSequence$num_trees()}\if{html}{\out{
}} } +\subsection{Details}{ +See the \code{tskit Python} equivalent at + \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_trees}. +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -664,6 +732,14 @@ Get the number of sites in a tree sequence. \if{html}{\out{
}}\preformatted{TreeSequence$num_sites()}\if{html}{\out{
}} } +\subsection{Details}{ +See the \code{tskit Python} equivalent at + \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_sites}. +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -684,6 +760,14 @@ Get the number of mutations in a tree sequence. \if{html}{\out{
}}\preformatted{TreeSequence$num_mutations()}\if{html}{\out{
}} } +\subsection{Details}{ +See the \code{tskit Python} equivalent at + \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.num_mutations}. +} + +\subsection{Returns}{ +A signed 64 bit integer \code{bit64::integer64}. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -704,6 +788,14 @@ Get the sequence length. \if{html}{\out{
}}\preformatted{TreeSequence$sequence_length()}\if{html}{\out{
}} } +\subsection{Details}{ +See the \code{tskit Python} equivalent at + \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.sequence_length}. +} + +\subsection{Returns}{ +A numeric. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -727,8 +819,15 @@ Get the discrete genome status. \subsection{Details}{ Returns \code{TRUE} if all genomic coordinates in the tree sequence are discrete integer values. + + +See the \code{tskit Python} equivalent at + \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.discrete_genome}. } +\subsection{Returns}{ +A logical. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file1 <- system.file("examples/test.trees", package = "RcppTskit") @@ -752,6 +851,14 @@ Get whether the tree sequence has a reference genome sequence. \if{html}{\out{
}}\preformatted{TreeSequence$has_reference_sequence()}\if{html}{\out{
}} } +\subsection{Details}{ +See the \code{tskit Python} equivalent at + \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.has_reference_sequence}. +} + +\subsection{Returns}{ +A logical. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file1 <- system.file("examples/test.trees", package = "RcppTskit") @@ -775,6 +882,14 @@ Get the time units string. \if{html}{\out{
}}\preformatted{TreeSequence$time_units()}\if{html}{\out{
}} } +\subsection{Details}{ +See the \code{tskit Python} equivalent at + \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.time_units}. +} + +\subsection{Returns}{ +A character. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -798,8 +913,15 @@ Get the discrete time status. \subsection{Details}{ Returns \code{TRUE} if all time values in the tree sequence are discrete integer values. + + +See the \code{tskit Python} equivalent at + \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.discrete_time}. } +\subsection{Returns}{ +A logical. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file1 <- system.file("examples/test.trees", package = "RcppTskit") @@ -823,6 +945,14 @@ Get the min time in node table and mutation table. \if{html}{\out{
}}\preformatted{TreeSequence$min_time()}\if{html}{\out{
}} } +\subsection{Details}{ +See the \code{tskit Python} equivalent at + \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.min_time}. +} + +\subsection{Returns}{ +A numeric. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -843,6 +973,14 @@ Get the max time in node table and mutation table. \if{html}{\out{
}}\preformatted{TreeSequence$max_time()}\if{html}{\out{
}} } +\subsection{Details}{ +See the \code{tskit Python} equivalent at + \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.TreeSequence.max_time}. +} + +\subsection{Returns}{ +A numeric. +} \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file <- system.file("examples/test.trees", package = "RcppTskit") @@ -864,7 +1002,8 @@ Get the length of metadata in a tree sequence and its tables. } \subsection{Returns}{ -A named list with the length of metadata. +A named list with the length of metadata, each as a signed 64 bit + integer \code{bit64::integer64}. } \subsection{Examples}{ \if{html}{\out{
}} @@ -881,16 +1020,16 @@ ts$metadata_length() \if{html}{\out{}} \if{latex}{\out{\hypertarget{method-TreeSequence-file_uuid}{}}} \subsection{Method \code{file_uuid()}}{ -Get the file UUID string. +Get the UUID string of the file the tree sequence was + loaded from. \subsection{Usage}{ \if{html}{\out{
}}\preformatted{TreeSequence$file_uuid()}\if{html}{\out{
}} } -\subsection{Details}{ -Returns the UUID of the file the tree sequence was loaded from. - If unavailable, returns \code{NA_character_}. +\subsection{Returns}{ +A character; \code{NA_character_} when file is information is + unavailable. } - \subsection{Examples}{ \if{html}{\out{
}} \preformatted{ts_file <- system.file("examples/test.trees", package = "RcppTskit") diff --git a/RcppTskit/man/tc_load.Rd b/RcppTskit/man/tc_load.Rd index 5e14aa2..b149869 100644 --- a/RcppTskit/man/tc_load.Rd +++ b/RcppTskit/man/tc_load.Rd @@ -24,8 +24,10 @@ A \code{\link{TableCollection}} object. Load a table collection from a file } \details{ -See the corresponding Python function at +See the \code{tskit Python} equivalent at \url{https://github.com/tskit-dev/tskit/blob/dc394d72d121c99c6dcad88f7a4873880924dd72/python/tskit/tables.py#L3463}. + TODO: Update URL to TableCollection.load() method #104 + https://github.com/HighlanderLab/RcppTskit/issues/104 } \section{Functions}{ \itemize{ diff --git a/RcppTskit/man/ts_load.Rd b/RcppTskit/man/ts_load.Rd index 45c9b2b..618abc8 100644 --- a/RcppTskit/man/ts_load.Rd +++ b/RcppTskit/man/ts_load.Rd @@ -24,7 +24,7 @@ A \code{\link{TreeSequence}} object. Load a tree sequence from a file } \details{ -See the corresponding Python function at +See the \code{tskit Python} equivalent at \url{https://tskit.dev/tskit/docs/latest/python-api.html#tskit.load}. } \section{Functions}{ diff --git a/RcppTskit/src/RcppExports.cpp b/RcppTskit/src/RcppExports.cpp index a8be147..f3ae137 100644 --- a/RcppTskit/src/RcppExports.cpp +++ b/RcppTskit/src/RcppExports.cpp @@ -346,6 +346,94 @@ BEGIN_RCPP return rcpp_result_gen; END_RCPP } +// rtsk_table_collection_get_num_provenances +SEXP rtsk_table_collection_get_num_provenances(const SEXP tc); +RcppExport SEXP _RcppTskit_rtsk_table_collection_get_num_provenances(SEXP tcSEXP) { +BEGIN_RCPP + Rcpp::RObject rcpp_result_gen; + Rcpp::RNGScope rcpp_rngScope_gen; + Rcpp::traits::input_parameter< const SEXP >::type tc(tcSEXP); + rcpp_result_gen = Rcpp::wrap(rtsk_table_collection_get_num_provenances(tc)); + return rcpp_result_gen; +END_RCPP +} +// rtsk_table_collection_get_num_populations +SEXP rtsk_table_collection_get_num_populations(const SEXP tc); +RcppExport SEXP _RcppTskit_rtsk_table_collection_get_num_populations(SEXP tcSEXP) { +BEGIN_RCPP + Rcpp::RObject rcpp_result_gen; + Rcpp::RNGScope rcpp_rngScope_gen; + Rcpp::traits::input_parameter< const SEXP >::type tc(tcSEXP); + rcpp_result_gen = Rcpp::wrap(rtsk_table_collection_get_num_populations(tc)); + return rcpp_result_gen; +END_RCPP +} +// rtsk_table_collection_get_num_migrations +SEXP rtsk_table_collection_get_num_migrations(const SEXP tc); +RcppExport SEXP _RcppTskit_rtsk_table_collection_get_num_migrations(SEXP tcSEXP) { +BEGIN_RCPP + Rcpp::RObject rcpp_result_gen; + Rcpp::RNGScope rcpp_rngScope_gen; + Rcpp::traits::input_parameter< const SEXP >::type tc(tcSEXP); + rcpp_result_gen = Rcpp::wrap(rtsk_table_collection_get_num_migrations(tc)); + return rcpp_result_gen; +END_RCPP +} +// rtsk_table_collection_get_num_individuals +SEXP rtsk_table_collection_get_num_individuals(const SEXP tc); +RcppExport SEXP _RcppTskit_rtsk_table_collection_get_num_individuals(SEXP tcSEXP) { +BEGIN_RCPP + Rcpp::RObject rcpp_result_gen; + Rcpp::RNGScope rcpp_rngScope_gen; + Rcpp::traits::input_parameter< const SEXP >::type tc(tcSEXP); + rcpp_result_gen = Rcpp::wrap(rtsk_table_collection_get_num_individuals(tc)); + return rcpp_result_gen; +END_RCPP +} +// rtsk_table_collection_get_num_nodes +SEXP rtsk_table_collection_get_num_nodes(const SEXP tc); +RcppExport SEXP _RcppTskit_rtsk_table_collection_get_num_nodes(SEXP tcSEXP) { +BEGIN_RCPP + Rcpp::RObject rcpp_result_gen; + Rcpp::RNGScope rcpp_rngScope_gen; + Rcpp::traits::input_parameter< const SEXP >::type tc(tcSEXP); + rcpp_result_gen = Rcpp::wrap(rtsk_table_collection_get_num_nodes(tc)); + return rcpp_result_gen; +END_RCPP +} +// rtsk_table_collection_get_num_edges +SEXP rtsk_table_collection_get_num_edges(const SEXP tc); +RcppExport SEXP _RcppTskit_rtsk_table_collection_get_num_edges(SEXP tcSEXP) { +BEGIN_RCPP + Rcpp::RObject rcpp_result_gen; + Rcpp::RNGScope rcpp_rngScope_gen; + Rcpp::traits::input_parameter< const SEXP >::type tc(tcSEXP); + rcpp_result_gen = Rcpp::wrap(rtsk_table_collection_get_num_edges(tc)); + return rcpp_result_gen; +END_RCPP +} +// rtsk_table_collection_get_num_sites +SEXP rtsk_table_collection_get_num_sites(const SEXP tc); +RcppExport SEXP _RcppTskit_rtsk_table_collection_get_num_sites(SEXP tcSEXP) { +BEGIN_RCPP + Rcpp::RObject rcpp_result_gen; + Rcpp::RNGScope rcpp_rngScope_gen; + Rcpp::traits::input_parameter< const SEXP >::type tc(tcSEXP); + rcpp_result_gen = Rcpp::wrap(rtsk_table_collection_get_num_sites(tc)); + return rcpp_result_gen; +END_RCPP +} +// rtsk_table_collection_get_num_mutations +SEXP rtsk_table_collection_get_num_mutations(const SEXP tc); +RcppExport SEXP _RcppTskit_rtsk_table_collection_get_num_mutations(SEXP tcSEXP) { +BEGIN_RCPP + Rcpp::RObject rcpp_result_gen; + Rcpp::RNGScope rcpp_rngScope_gen; + Rcpp::traits::input_parameter< const SEXP >::type tc(tcSEXP); + rcpp_result_gen = Rcpp::wrap(rtsk_table_collection_get_num_mutations(tc)); + return rcpp_result_gen; +END_RCPP +} // rtsk_table_collection_get_sequence_length double rtsk_table_collection_get_sequence_length(const SEXP tc); RcppExport SEXP _RcppTskit_rtsk_table_collection_get_sequence_length(SEXP tcSEXP) { @@ -556,6 +644,14 @@ static const R_CallMethodDef CallEntries[] = { {"_RcppTskit_rtsk_treeseq_get_file_uuid", (DL_FUNC) &_RcppTskit_rtsk_treeseq_get_file_uuid, 1}, {"_RcppTskit_rtsk_treeseq_summary", (DL_FUNC) &_RcppTskit_rtsk_treeseq_summary, 1}, {"_RcppTskit_rtsk_treeseq_metadata_length", (DL_FUNC) &_RcppTskit_rtsk_treeseq_metadata_length, 1}, + {"_RcppTskit_rtsk_table_collection_get_num_provenances", (DL_FUNC) &_RcppTskit_rtsk_table_collection_get_num_provenances, 1}, + {"_RcppTskit_rtsk_table_collection_get_num_populations", (DL_FUNC) &_RcppTskit_rtsk_table_collection_get_num_populations, 1}, + {"_RcppTskit_rtsk_table_collection_get_num_migrations", (DL_FUNC) &_RcppTskit_rtsk_table_collection_get_num_migrations, 1}, + {"_RcppTskit_rtsk_table_collection_get_num_individuals", (DL_FUNC) &_RcppTskit_rtsk_table_collection_get_num_individuals, 1}, + {"_RcppTskit_rtsk_table_collection_get_num_nodes", (DL_FUNC) &_RcppTskit_rtsk_table_collection_get_num_nodes, 1}, + {"_RcppTskit_rtsk_table_collection_get_num_edges", (DL_FUNC) &_RcppTskit_rtsk_table_collection_get_num_edges, 1}, + {"_RcppTskit_rtsk_table_collection_get_num_sites", (DL_FUNC) &_RcppTskit_rtsk_table_collection_get_num_sites, 1}, + {"_RcppTskit_rtsk_table_collection_get_num_mutations", (DL_FUNC) &_RcppTskit_rtsk_table_collection_get_num_mutations, 1}, {"_RcppTskit_rtsk_table_collection_get_sequence_length", (DL_FUNC) &_RcppTskit_rtsk_table_collection_get_sequence_length, 1}, {"_RcppTskit_rtsk_table_collection_has_reference_sequence", (DL_FUNC) &_RcppTskit_rtsk_table_collection_has_reference_sequence, 1}, {"_RcppTskit_rtsk_table_collection_get_time_units", (DL_FUNC) &_RcppTskit_rtsk_table_collection_get_time_units, 1}, diff --git a/RcppTskit/src/RcppTskit.cpp b/RcppTskit/src/RcppTskit.cpp index eb6feb4..0d35b0c 100644 --- a/RcppTskit/src/RcppTskit.cpp +++ b/RcppTskit/src/RcppTskit.cpp @@ -734,44 +734,23 @@ Rcpp::String rtsk_treeseq_get_file_uuid(const SEXP ts) { // EXTENSION: composite summary helper (no single tsk_* equivalent). // [[Rcpp::export]] Rcpp::List rtsk_treeseq_summary(const SEXP ts) { - rtsk_treeseq_t ts_xptr(ts); return Rcpp::List::create( - Rcpp::_["num_provenances"] = rtsk_wrap_tsk_size_t_as_integer64( - tsk_treeseq_get_num_provenances(ts_xptr), - "rtsk_treeseq_summary/tsk_treeseq_get_num_provenances"), - Rcpp::_["num_populations"] = rtsk_wrap_tsk_size_t_as_integer64( - tsk_treeseq_get_num_populations(ts_xptr), - "rtsk_treeseq_summary/tsk_treeseq_get_num_populations"), - Rcpp::_["num_migrations"] = rtsk_wrap_tsk_size_t_as_integer64( - tsk_treeseq_get_num_migrations(ts_xptr), - "rtsk_treeseq_summary/tsk_treeseq_get_num_migrations"), - Rcpp::_["num_individuals"] = rtsk_wrap_tsk_size_t_as_integer64( - tsk_treeseq_get_num_individuals(ts_xptr), - "rtsk_treeseq_summary/tsk_treeseq_get_num_individuals"), - Rcpp::_["num_samples"] = rtsk_wrap_tsk_size_t_as_integer64( - tsk_treeseq_get_num_samples(ts_xptr), - "rtsk_treeseq_summary/tsk_treeseq_get_num_samples"), - Rcpp::_["num_nodes"] = rtsk_wrap_tsk_size_t_as_integer64( - tsk_treeseq_get_num_nodes(ts_xptr), - "rtsk_treeseq_summary/tsk_treeseq_get_num_nodes"), - Rcpp::_["num_edges"] = rtsk_wrap_tsk_size_t_as_integer64( - tsk_treeseq_get_num_edges(ts_xptr), - "rtsk_treeseq_summary/tsk_treeseq_get_num_edges"), - Rcpp::_["num_trees"] = rtsk_wrap_tsk_size_t_as_integer64( - tsk_treeseq_get_num_trees(ts_xptr), - "rtsk_treeseq_summary/tsk_treeseq_get_num_trees"), - Rcpp::_["num_sites"] = rtsk_wrap_tsk_size_t_as_integer64( - tsk_treeseq_get_num_sites(ts_xptr), - "rtsk_treeseq_summary/tsk_treeseq_get_num_sites"), - Rcpp::_["num_mutations"] = rtsk_wrap_tsk_size_t_as_integer64( - tsk_treeseq_get_num_mutations(ts_xptr), - "rtsk_treeseq_summary/tsk_treeseq_get_num_mutations"), - Rcpp::_["sequence_length"] = tsk_treeseq_get_sequence_length(ts_xptr), - Rcpp::_["discrete_genome"] = tsk_treeseq_get_discrete_genome(ts_xptr), + Rcpp::_["num_provenances"] = rtsk_treeseq_get_num_provenances(ts), + Rcpp::_["num_populations"] = rtsk_treeseq_get_num_populations(ts), + Rcpp::_["num_migrations"] = rtsk_treeseq_get_num_migrations(ts), + Rcpp::_["num_individuals"] = rtsk_treeseq_get_num_individuals(ts), + Rcpp::_["num_samples"] = rtsk_treeseq_get_num_samples(ts), + Rcpp::_["num_nodes"] = rtsk_treeseq_get_num_nodes(ts), + Rcpp::_["num_edges"] = rtsk_treeseq_get_num_edges(ts), + Rcpp::_["num_trees"] = rtsk_treeseq_get_num_trees(ts), + Rcpp::_["num_sites"] = rtsk_treeseq_get_num_sites(ts), + Rcpp::_["num_mutations"] = rtsk_treeseq_get_num_mutations(ts), + Rcpp::_["sequence_length"] = rtsk_treeseq_get_sequence_length(ts), + Rcpp::_["discrete_genome"] = rtsk_treeseq_get_discrete_genome(ts), Rcpp::_["has_reference_sequence"] = - tsk_treeseq_has_reference_sequence(ts_xptr), + rtsk_treeseq_has_reference_sequence(ts), Rcpp::_["time_units"] = rtsk_treeseq_get_time_units(ts), - Rcpp::_["discrete_time"] = tsk_treeseq_get_discrete_time(ts_xptr), + Rcpp::_["discrete_time"] = rtsk_treeseq_get_discrete_time(ts), Rcpp::_["min_time"] = rtsk_treeseq_get_min_time(ts), Rcpp::_["max_time"] = rtsk_treeseq_get_max_time(ts), Rcpp::_["file_uuid"] = rtsk_treeseq_get_file_uuid(ts)); @@ -899,6 +878,89 @@ Rcpp::String rtsk_treeseq_get_metadata(const SEXP ts) { // https://tskit.dev/tskit/docs/stable/python-api.html#sec-tables-api-table-collection // https://tskit.dev/tskit/docs/stable/python-api.html#tskit.TableCollection +// PUBLIC, RcppTskit extension +// @describeIn rtsk_table_collection_summary Get the number of provenances +// in a table collection +// [[Rcpp::export]] +SEXP rtsk_table_collection_get_num_provenances(const SEXP tc) { + rtsk_table_collection_t tc_xptr(tc); + return rtsk_wrap_tsk_size_t_as_integer64( + tc_xptr->provenances.num_rows, + "rtsk_table_collection_get_num_provenances"); +} + +// PUBLIC, RcppTskit extension +// @describeIn rtsk_table_collection_summary Get the number of populations +// in a table collection +// [[Rcpp::export]] +SEXP rtsk_table_collection_get_num_populations(const SEXP tc) { + rtsk_table_collection_t tc_xptr(tc); + return rtsk_wrap_tsk_size_t_as_integer64( + tc_xptr->populations.num_rows, + "rtsk_table_collection_get_num_populations"); +} + +// PUBLIC, RcppTskit extension +// @describeIn rtsk_table_collection_summary Get the number of migrations +// in a table collection +// [[Rcpp::export]] +SEXP rtsk_table_collection_get_num_migrations(const SEXP tc) { + rtsk_table_collection_t tc_xptr(tc); + return rtsk_wrap_tsk_size_t_as_integer64( + tc_xptr->migrations.num_rows, "rtsk_table_collection_get_num_migrations"); +} + +// PUBLIC, RcppTskit extension +// @describeIn rtsk_table_collection_summary Get the number of individuals +// in a table collection +// [[Rcpp::export]] +SEXP rtsk_table_collection_get_num_individuals(const SEXP tc) { + rtsk_table_collection_t tc_xptr(tc); + return rtsk_wrap_tsk_size_t_as_integer64( + tc_xptr->individuals.num_rows, + "rtsk_table_collection_get_num_individuals"); +} + +// PUBLIC, RcppTskit extension +// @describeIn rtsk_table_collection_summary Get the number of nodes +// in a table collection +// [[Rcpp::export]] +SEXP rtsk_table_collection_get_num_nodes(const SEXP tc) { + rtsk_table_collection_t tc_xptr(tc); + return rtsk_wrap_tsk_size_t_as_integer64( + tc_xptr->nodes.num_rows, "rtsk_table_collection_get_num_nodes"); +} + +// PUBLIC, RcppTskit extension +// @describeIn rtsk_table_collection_summary Get the number of edges +// in a table collection +// [[Rcpp::export]] +SEXP rtsk_table_collection_get_num_edges(const SEXP tc) { + rtsk_table_collection_t tc_xptr(tc); + return rtsk_wrap_tsk_size_t_as_integer64( + tc_xptr->edges.num_rows, "rtsk_table_collection_get_num_edges"); +} + +// PUBLIC, RcppTskit extension +// @describeIn rtsk_table_collection_summary Get the number of sites +// in a table collection +// [[Rcpp::export]] +SEXP rtsk_table_collection_get_num_sites(const SEXP tc) { + rtsk_table_collection_t tc_xptr(tc); + return rtsk_wrap_tsk_size_t_as_integer64( + tc_xptr->sites.num_rows, "rtsk_table_collection_get_num_sites"); +} + +// PUBLIC, RcppTskit extension +// @describeIn rtsk_table_collection_summary Get the number of mutations +// in a table collection +// [[Rcpp::export]] +SEXP rtsk_table_collection_get_num_mutations(const SEXP tc) { + rtsk_table_collection_t tc_xptr(tc); + return rtsk_wrap_tsk_size_t_as_integer64( + tc_xptr->mutations.num_rows, "rtsk_table_collection_get_num_mutations"); +} + // PUBLIC, RcppTskit extension // @describeIn rtsk_table_collection_summary Get the sequence length // [[Rcpp::export]] @@ -959,7 +1021,8 @@ bool rtsk_table_collection_has_index(const SEXP tc, const int options = 0) { // @title Build indexes for a table collection // @param tc an external pointer to table collection as a // \code{tsk_table_collection_t} object. -// @param options \code{tskit} bitwise flags, currently unused and should be set +// @param options \code{tskit} bitwise flags, currently unused and should be +// set // to 0 // @details This function calls // \url{https://tskit.dev/tskit/docs/stable/c-api.html#c.tsk_table_collection_build_index}. @@ -987,7 +1050,8 @@ void rtsk_table_collection_build_index(const SEXP tc, const int options = 0) { // @title Drop indexes for a table collection // @param tc an external pointer to table collection as a // \code{tsk_table_collection_t} object. -// @param options \code{tskit} bitwise flags, currently unused and should be set +// @param options \code{tskit} bitwise flags, currently unused and should be +// set // to 0 // @details This function calls // \url{https://tskit.dev/tskit/docs/stable/c-api.html#c.tsk_table_collection_drop_index}. @@ -1005,8 +1069,8 @@ void rtsk_table_collection_drop_index(const SEXP tc, const int options = 0) { rtsk_table_collection_t tc_xptr(tc); int ret = tsk_table_collection_drop_index(tc_xptr, flags); // tsk_table_collection_drop_index() currently documents always returning 0; - // so we test for possible future failures, but we cannot unit-test this path. - // # nocov start + // so we test for possible future failures, but we cannot unit-test this + // path. # nocov start if (ret != 0) { Rcpp::stop(tsk_strerror(ret)); } @@ -1016,15 +1080,16 @@ void rtsk_table_collection_drop_index(const SEXP tc, const int options = 0) { // TODO: Do we have to add TableCollection$sort() method? #99 // https://github.com/HighlanderLab/RcppTskit/issues/99 -// TODO: Do we need any other method on table collection to produce a valid ts? -// #100 +// TODO: Do we need any other method on table collection to produce a valid +// ts? #100 // https://github.com/HighlanderLab/RcppTskit/issues/100 // PUBLIC, RcppTskit extension // @title Summary of properties and number of records in a table collection // @param tc an external pointer to table collection as a // \code{tsk_table_collection_t} object. -// @param options \code{tskit} bitwise flags, currently unused and should be set +// @param options \code{tskit} bitwise flags, currently unused and should be +// set // to 0 // @details These functions return the summary of properties and number of // records in a table collection, by accessing its elements and/or calling @@ -1033,11 +1098,22 @@ void rtsk_table_collection_drop_index(const SEXP tc, const int options = 0) { // numbers and values, while functions \code{rtsk_table_collection_*} return // the number or value for each item. Count-like values are returned as // \code{R bit64::integer64} to approach range in \code{C tsk_size_t / -// uint64_t} (see \code{rtsk_wrap_tsk_size_t_as_integer64} for more details). +// uint64_t} (see \code{rtsk_wrap_tsk_size_t_as_integer64} for more +// details). // @examples // ts_file <- system.file("examples/test.trees", package = "RcppTskit") // tc_xptr <- RcppTskit:::rtsk_table_collection_load(ts_file) // RcppTskit:::rtsk_table_collection_summary(tc_xptr) +// RcppTskit:::rtsk_table_collection_get_num_provenances(ts_xptr) +// RcppTskit:::rtsk_table_collection_get_num_populations(ts_xptr) +// RcppTskit:::rtsk_table_collection_get_num_migrations(ts_xptr) +// RcppTskit:::rtsk_table_collection_get_num_individuals(ts_xptr) +// RcppTskit:::rtsk_table_collection_get_num_samples(ts_xptr) +// RcppTskit:::rtsk_table_collection_get_num_nodes(ts_xptr) +// RcppTskit:::rtsk_table_collection_get_num_edges(ts_xptr) +// RcppTskit:::rtsk_table_collection_get_num_trees(ts_xptr) +// RcppTskit:::rtsk_table_collection_get_num_sites(ts_xptr) +// RcppTskit:::rtsk_table_collection_get_num_mutations(ts_xptr) // RcppTskit:::rtsk_table_collection_get_sequence_length(tc_xptr) // RcppTskit:::rtsk_table_collection_has_reference_sequence(tc_xptr) // RcppTskit:::rtsk_table_collection_get_time_units(tc_xptr) @@ -1045,34 +1121,20 @@ void rtsk_table_collection_drop_index(const SEXP tc, const int options = 0) { // RcppTskit:::rtsk_table_collection_has_index(tc_xptr) // [[Rcpp::export]] Rcpp::List rtsk_table_collection_summary(const SEXP tc) { - rtsk_table_collection_t tc_xptr(tc); - const tsk_table_collection_t *tables = tc_xptr; return Rcpp::List::create( - Rcpp::_["num_provenances"] = rtsk_wrap_tsk_size_t_as_integer64( - tables->provenances.num_rows, - "rtsk_table_collection_summary/tables->provenances.num_rows"), - Rcpp::_["num_populations"] = rtsk_wrap_tsk_size_t_as_integer64( - tables->populations.num_rows, - "rtsk_table_collection_summary/tables->populations.num_rows"), - Rcpp::_["num_migrations"] = rtsk_wrap_tsk_size_t_as_integer64( - tables->migrations.num_rows, - "rtsk_table_collection_summary/tables->migrations.num_rows"), - Rcpp::_["num_individuals"] = rtsk_wrap_tsk_size_t_as_integer64( - tables->individuals.num_rows, - "rtsk_table_collection_summary/tables->individuals.num_rows"), - Rcpp::_["num_nodes"] = rtsk_wrap_tsk_size_t_as_integer64( - tables->nodes.num_rows, - "rtsk_table_collection_summary/tables->nodes.num_rows"), - Rcpp::_["num_edges"] = rtsk_wrap_tsk_size_t_as_integer64( - tables->edges.num_rows, - "rtsk_table_collection_summary/tables->edges.num_rows"), - Rcpp::_["num_sites"] = rtsk_wrap_tsk_size_t_as_integer64( - tables->sites.num_rows, - "rtsk_table_collection_summary/tables->sites.num_rows"), - Rcpp::_["num_mutations"] = rtsk_wrap_tsk_size_t_as_integer64( - tables->mutations.num_rows, - "rtsk_table_collection_summary/tables->mutations.num_rows"), - Rcpp::_["sequence_length"] = tables->sequence_length, + Rcpp::_["num_provenances"] = + rtsk_table_collection_get_num_provenances(tc), + Rcpp::_["num_populations"] = + rtsk_table_collection_get_num_populations(tc), + Rcpp::_["num_migrations"] = rtsk_table_collection_get_num_migrations(tc), + Rcpp::_["num_individuals"] = + rtsk_table_collection_get_num_individuals(tc), + Rcpp::_["num_nodes"] = rtsk_table_collection_get_num_nodes(tc), + Rcpp::_["num_edges"] = rtsk_table_collection_get_num_edges(tc), + Rcpp::_["num_sites"] = rtsk_table_collection_get_num_sites(tc), + Rcpp::_["num_mutations"] = rtsk_table_collection_get_num_mutations(tc), + Rcpp::_["sequence_length"] = + rtsk_table_collection_get_sequence_length(tc), Rcpp::_["has_reference_sequence"] = rtsk_table_collection_has_reference_sequence(tc), Rcpp::_["time_units"] = rtsk_table_collection_get_time_units(tc), @@ -1084,7 +1146,8 @@ Rcpp::List rtsk_table_collection_summary(const SEXP tc) { // @title Get the length of metadata in a table collection and its tables // @param tc an external pointer to table collection as a // \code{tsk_table_collection_t} object. -// @return A named list with the length of metadata as \code{R bit64::integer64} +// @return A named list with the length of metadata as \code{R +// bit64::integer64} // values to approach range in \code{C tsk_size_t / uint64_t} // (see \code{rtsk_wrap_tsk_size_t_as_integer64} for more details). // @examples diff --git a/RcppTskit/tests/testthat/test_load_summary_and_dump.R b/RcppTskit/tests/testthat/test_load_summary_and_dump.R index ee75415..e914fb8 100644 --- a/RcppTskit/tests/testthat/test_load_summary_and_dump.R +++ b/RcppTskit/tests/testthat/test_load_summary_and_dump.R @@ -358,6 +358,70 @@ test_that("ts/tc_load(), ts/tc_summary*(), and ts/tc_dump(x) work", { ) expect_equal(n_xptr_tc[shared_items], n_xptr_ts[shared_items]) + expect_error(rtsk_table_collection_get_num_provenances()) + expect_error(rtsk_table_collection_get_num_provenances(ts)) + n_xptr <- rtsk_table_collection_get_num_provenances(tc_xptr) + expect_true(bit64::is.integer64(n_xptr)) + expect_equal(n_xptr, 2L) + expect_equal(n_xptr, n_xptr_tc[["num_provenances"]]) + expect_equal(tc$num_provenances(), 2L) + + expect_error(rtsk_table_collection_get_num_populations()) + expect_error(rtsk_table_collection_get_num_populations(ts)) + n_xptr <- rtsk_table_collection_get_num_populations(tc_xptr) + expect_true(bit64::is.integer64(n_xptr)) + expect_equal(n_xptr, 1L) + expect_equal(n_xptr, n_xptr_tc[["num_populations"]]) + expect_equal(tc$num_populations(), 1L) + + expect_error(rtsk_table_collection_get_num_migrations()) + expect_error(rtsk_table_collection_get_num_migrations(ts)) + n_xptr <- rtsk_table_collection_get_num_migrations(tc_xptr) + expect_true(bit64::is.integer64(n_xptr)) + expect_equal(n_xptr, 0L) + expect_equal(n_xptr, n_xptr_tc[["num_migrations"]]) + expect_equal(tc$num_migrations(), 0L) + + expect_error(rtsk_table_collection_get_num_individuals()) + expect_error(rtsk_table_collection_get_num_individuals(ts)) + n_xptr <- rtsk_table_collection_get_num_individuals(tc_xptr) + expect_true(bit64::is.integer64(n_xptr)) + expect_equal(n_xptr, 8L) + expect_equal(n_xptr, n_xptr_tc[["num_individuals"]]) + expect_equal(tc$num_individuals(), 8L) + + expect_error(rtsk_table_collection_get_num_nodes()) + expect_error(rtsk_table_collection_get_num_nodes(ts)) + n_xptr <- rtsk_table_collection_get_num_nodes(tc_xptr) + expect_true(bit64::is.integer64(n_xptr)) + expect_equal(n_xptr, 39L) + expect_equal(n_xptr, n_xptr_tc[["num_nodes"]]) + expect_equal(tc$num_nodes(), 39L) + + expect_error(rtsk_table_collection_get_num_edges()) + expect_error(rtsk_table_collection_get_num_edges(ts)) + n_xptr <- rtsk_table_collection_get_num_edges(tc_xptr) + expect_true(bit64::is.integer64(n_xptr)) + expect_equal(n_xptr, 59L) + expect_equal(n_xptr, n_xptr_tc[["num_edges"]]) + expect_equal(tc$num_edges(), 59L) + + expect_error(rtsk_table_collection_get_num_sites()) + expect_error(rtsk_table_collection_get_num_sites(ts)) + n_xptr <- rtsk_table_collection_get_num_sites(tc_xptr) + expect_true(bit64::is.integer64(n_xptr)) + expect_equal(n_xptr, 25L) + expect_equal(n_xptr, n_xptr_tc[["num_sites"]]) + expect_equal(tc$num_sites(), 25L) + + expect_error(rtsk_table_collection_get_num_mutations()) + expect_error(rtsk_table_collection_get_num_mutations(ts)) + n_xptr <- rtsk_table_collection_get_num_mutations(tc_xptr) + expect_true(bit64::is.integer64(n_xptr)) + expect_equal(n_xptr, 30L) + expect_equal(n_xptr, n_xptr_tc[["num_mutations"]]) + expect_equal(tc$num_mutations(), 30L) + expect_error(rtsk_table_collection_get_sequence_length()) expect_error(rtsk_table_collection_get_sequence_length(ts)) n_xptr <- rtsk_table_collection_get_sequence_length(tc_xptr)