1- # ' @title Succinct Tree Sequence R6 Class
2- # ' @description An R6 class to hold an external pointer to a tskit tree sequence.
3- # ' As an R6 class, it's functions will look Pythonic and hence resemble the
1+ # ' @title Succinct tree sequence R6 Class (TreeSequence)
2+ # ' @description An R6 class holding an external pointer to a tree sequence
3+ # ' object. As an R6 class, it's methods look Pythonic and hence resemble the
44# ' tskit Python API. Since the class only holds the pointer, it is lightweight.
5- # ' The pointer does not provide direct view for users and currently there is
6- # ' only a limited number of methods available to summarise the tree sequence.
5+ # ' Currently there is only a limited number of methods available to summarise
6+ # ' the tree sequence.
77# ' @export
88TreeSequence <- R6Class(
99 classname = " TreeSequence"
@@ -12,10 +12,22 @@ TreeSequence <- R6Class(
1212 pointer = " externalptr"
1313
1414 # ' @description Create a \code{\link{TreeSequence}} from a file or a pointer.
15- # ' See \code{\link{ts_load}()} for details and examples.
16- # ' @param file see \code{\link{ts_load}()}
17- # ' @param options see \code{\link{ts_load}()}
18- # ' @param pointer an external pointer to a tree sequence
15+ # ' See \code{\link{ts_load}} for details and examples.
16+ # ' @param file a string specifying the full path of the tree sequence file.
17+ # ' @param options integer bitwise options (see details at
18+ # ' \url{https://tskit.dev/tskit/docs/stable/c-api.html#c.tsk_treeseq_load}).
19+ # ' @param pointer an external pointer to a tree sequence ()
20+ # ' @return A \code{\link{TreeSequence}} object.
21+ # ' @seealso \code{\link{ts_load}}
22+ # ' @examples
23+ # ' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
24+ # ' ts <- TreeSequence$new(file = ts_file)
25+ # ' is(ts)
26+ # ' ts
27+ # ' ts$num_nodes()
28+ # ' # Also
29+ # ' ts <- ts_load(ts_file)
30+ # ' is(ts)
1931 initialize = function (file , options = 0L , pointer = NULL ) {
2032 if (missing(file ) && is.null(pointer )) {
2133 stop(" Provide a file name or a pointer!"
@@ -43,148 +55,174 @@ TreeSequence <- R6Class(
4355 invisible (self )
4456 },
4557
46- # ' @description Write a tree sequence to a file.
47- # ' See \code{\link{ts_dump}()} for details and examples.
48- # ' @param file see \code{\link{ts_dump}()}
49- # ' @param options see \code{\link{ts_dump}()}
58+ # ' @description Write a tree sequence to a file
59+ # ' @param file a string specifying the full path of the tree sequence file.
60+ # ' @param options integer bitwise options (see details at
61+ # ' \url{https://tskit.dev/tskit/docs/stable/c-api.html#c.tsk_treeseq_dump}).
62+ # ' @return No return value; called for side effects.
63+ # ' @examples
64+ # ' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
65+ # ' ts <- ts_load(ts_file)
66+ # ' dump_file <- tempfile()
67+ # ' ts$dump(dump_file)
68+ # ' ts$write(dump_file) # alias
5069 dump = function (file , options = 0L ) {
5170 ts_dump_ptr(self $ pointer , file = file , options = options )
5271 },
5372
54- # ' @description Write a tree sequence to a file.
55- # ' Alias for \code{TreeSequence$dump(file, options)}.
56- # ' See \code{\link{ts_dump}()} for details and examples.
57- # ' @param file see \code{\link{ts_dump}()}
58- # ' @param options see \code{\link{ts_dump}()}
73+ # ' @description Alias for \code{\link[=TreeSequence]{TreeSequence$dump}}.
74+ # ' @param file see
75+ # ' @param options see
5976 write = function (file , options = 0L ) {
6077 self $ dump(file = file , options = options )
6178 },
6279
6380 # ' @description Print a summary of a tree sequence and its contents.
64- # ' See \code{\link{ts_print}()} for details and examples.
81+ # ' @return list with two data.frames; the first contains tree sequence
82+ # ' properties and their value; the second contains the numbers of rows in
83+ # ' tables and the length of their metadata.
84+ # ' @examples
85+ # ' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
86+ # ' ts <- ts_load(ts_file)
87+ # ' ts$print()
88+ # ' ts
6589 print = function () {
6690 cat(" Object of class 'TreeSequence'\n "
6791 print(ts_print_ptr(self $ pointer ))
6892 },
6993
70- # ' @description Summary of properties and number of records in a tree sequence.
71- # ' See \code{\link{ts_summary}()} for details and examples.
72- summary = function () {
73- ts_summary_ptr(self $ pointer )
94+ # ' @description This function saves a tree sequence from R to disk and
95+ # ' reads it into reticulate Python for use with \code{tskit} Python API.
96+ # ' @param tskit_module reticulate Python module of \code{tskit}. By default,
97+ # ' it calls \code{\link{get_tskit_py}} to obtain the module.
98+ # ' @param cleanup logical delete the temporary file at the end of the function?
99+ # ' @return Tree sequence in reticulate Python.
100+ # ' @seealso \code{\link{ts_py_to_r}}, \code{\link{ts_load}}, and
101+ # ' \code{\link[=TreeSequence]{TreeSequence$dump}}.
102+ # ' @examples
103+ # ' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
104+ # ' ts_r <- ts_load(ts_file)
105+ # ' is(ts_r)
106+ # ' ts_r$num_samples() # 160
107+ # '
108+ # ' # Transfer the tree sequence to reticulate Python and use tskit Python API
109+ # ' ts_py <- ts_r$r_to_py()
110+ # ' is(ts_py)
111+ # ' ts_py$num_samples # 160
112+ # ' ts2_py <- ts_py$simplify(samples = c(0L, 1L, 2L, 3L))
113+ # ' ts2_py$num_samples # 4
114+ r_to_py = function (tskit_module = get_tskit_py(), cleanup = TRUE ) {
115+ ts_r_to_py_ptr(
116+ self $ pointer ,
117+ tskit_module = tskit_module ,
118+ cleanup = cleanup
119+ )
74120 },
75121
76122 # ' @description Get the number of provenances in a tree sequence.
77- # ' See \code{\link{ts_summary}()} for details and examples.
123+ # ' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
124+ # ' ts <- ts_load(ts_file)
125+ # ' ts_num_provenances(ts)
78126 num_provenances = function () {
79127 ts_num_provenances_ptr(self $ pointer )
80128 },
81129
82130 # ' @description Get the number of populations in a tree sequence.
83- # ' See \code{\link{ts_summary}()} for details and examples.
131+ # ' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
132+ # ' ts <- ts_load(ts_file)
133+ # ' ts_num_populations(ts)
84134 num_populations = function () {
85135 ts_num_populations_ptr(self $ pointer )
86136 },
87137
88138 # ' @description Get the number of migrations in a tree sequence.
89- # ' See \code{\link{ts_summary}()} for details and examples.
139+ # ' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
140+ # ' ts <- ts_load(ts_file)
141+ # ' ts_num_migrations(ts)
90142 num_migrations = function () {
91143 ts_num_migrations_ptr(self $ pointer )
92144 },
93145
94146 # ' @description Get the number of individuals in a tree sequence.
95- # ' See \code{\link{ts_summary}()} for details and examples.
147+ # ' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
148+ # ' ts <- ts_load(ts_file)
149+ # ' ts_num_individuals(ts)
96150 num_individuals = function () {
97151 ts_num_individuals_ptr(self $ pointer )
98152 },
99153
100154 # ' @description Get the number of samples (of nodes) in a tree sequence.
101- # ' See \code{\link{ts_summary}()} for details and examples.
155+ # ' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
156+ # ' ts <- ts_load(ts_file)
157+ # ' ts_num_samples(ts)
102158 num_samples = function () {
103159 ts_num_samples_ptr(self $ pointer )
104160 },
105161
106162 # ' @description Get the number of nodes in a tree sequence.
107- # ' See \code{\link{ts_summary}()} for details and examples.
163+ # ' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
164+ # ' ts <- ts_load(ts_file)
165+ # ' ts_num_nodes(ts)
108166 num_nodes = function () {
109167 ts_num_nodes_ptr(self $ pointer )
110168 },
111169
112170 # ' @description Get the number of edges in a tree sequence.
113- # ' See \code{\link{ts_summary}()} for details and examples.
171+ # ' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
172+ # ' ts <- ts_load(ts_file)
173+ # ' ts_num_edges(ts)
114174 num_edges = function () {
115175 ts_num_edges_ptr(self $ pointer )
116176 },
117177
118178 # ' @description Get the number of trees in a tree sequence.
119- # ' See \code{\link{ts_summary}()} for details and examples.
179+ # ' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
180+ # ' ts <- ts_load(ts_file)
181+ # ' ts_num_trees(ts)
120182 num_trees = function () {
121183 ts_num_trees_ptr(self $ pointer )
122184 },
123185
124186 # ' @description Get the number of sites in a tree sequence.
125- # ' See \code{\link{ts_summary}()} for details and examples.
187+ # ' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
188+ # ' ts <- ts_load(ts_file)
189+ # ' ts_num_sites(ts)
126190 num_sites = function () {
127191 ts_num_sites_ptr(self $ pointer )
128192 },
129193
130194 # ' @description Get the number of mutations in a tree sequence.
131- # ' See \code{\link{ts_summary}()} for details and examples.
195+ # ' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
196+ # ' ts <- ts_load(ts_file)
197+ # ' ts_num_mutations(ts)
132198 num_mutations = function () {
133199 ts_num_mutations_ptr(self $ pointer )
134200 },
135201
136202 # ' @description Get the sequence length.
137- # ' See \code{\link{ts_summary}()} for details and examples.
203+ # ' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
204+ # ' ts <- ts_load(ts_file)
205+ # ' ts_sequence_length(ts)
138206 sequence_length = function () {
139207 ts_sequence_length_ptr(self $ pointer )
140208 },
141209
142210 # ' @description Get the time units string.
143- # ' See \code{\link{ts_summary}()} for details and examples.
211+ # ' ts_file <- system.file("examples/test.trees", package = "RcppTskit")
212+ # ' ts <- ts_load(ts_file)
213+ # ' ts_time_units(ts)
144214 time_units = function () {
145215 ts_time_units_ptr(self $ pointer )
146216 },
147217
148218 # ' @description Get the length of metadata in a tree sequence and its tables.
149- # ' See \code{\link{ts_metadata_length}()} for details and examples.
219+ # ' @return A named list with the length of metadata.
220+ # ' @examples
221+ # 'ts_file <- system.file("examples/test.trees", package = "RcppTskit")
222+ # ' ts <- ts_load(ts_file)
223+ # 'ts$metadata_length()
150224 metadata_length = function () {
151225 ts_metadata_length_ptr(self $ pointer )
152- },
153-
154- # ' @description Transfer a tree sequence from R to reticulate Python.
155- # ' See \code{\link{ts_r_to_py}()} for details and examples.
156- # ' @param tskit_module see \code{\link{ts_r_to_py}()}
157- # ' @param cleanup see \code{\link{ts_r_to_py}()}
158- r_to_py = function (tskit_module = get_tskit_py(), cleanup = TRUE ) {
159- ts_r_to_py_ptr(
160- self $ pointer ,
161- tskit_module = tskit_module ,
162- cleanup = cleanup
163- )
164226 }
165227 )
166228)
167-
168- # ' @name TreeSequence-load-alias
169- # ' @title Create a \code{\link{TreeSequence}} from a file
170- # ' @description
171- # ' Alias for \code{TreeSequence$new(file, options)}
172- # ' See \code{\link{ts_load}()} for details and examples.
173- # ' @param file see \code{\link{ts_load}()}
174- # ' @param options see \code{\link{ts_load}()}
175- TreeSequence $ load <- function (file , options = 0L ) {
176- TreeSequence $ new(file = file , options = options )
177- }
178- # This one has to be outside of the R6 class definition to work as a generator
179-
180- # ' @name TreeSequence-read-alias
181- # ' @title Create a \code{\link{TreeSequence}} from a file.
182- # ' @description
183- # ' Alias for \code{TreeSequence$new(file, options)}
184- # ' See \code{\link{ts_load}()} for details and examples.
185- # ' @param file see \code{\link{ts_load}()}
186- # ' @param options see \code{\link{ts_load}()}
187- TreeSequence $ read <- function (file , options = 0L ) {
188- TreeSequence $ new(file = file , options = options )
189- }
190- # This one has to be outside of the R6 class definition to work as a generator
0 commit comments