| Title: | Native Access to Succinct Tree Sequences |
|---|---|
| Description: | Provides a native R interface to the 'tskit' C API for loading, inspecting, traversing, and writing succinct tree sequences. Tree sequences remain owned by native external pointers while typed R functions expose selected tables, opaque metadata, tree intervals, and declared source-population ancestry without a Python runtime. |
| Authors: | Sounkou Mahamane Toure [aut, cre], Tskit Developers [cph] (Bundled tskit C library) |
| Maintainer: | Sounkou Mahamane Toure <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 0.0.0.9000 |
| Built: | 2026-09-20 11:23:30 UTC |
| Source: | https://github.com/RGenomicsETL/Rtskit |
TreeSequence owns one tsk_treeseq_t value through a native external
pointer. IDs returned by table accessors retain tskit's zero-based indexing.
TreeSequence(ptr = NULL, source = character(0))TreeSequence(ptr = NULL, source = character(0))
ptr |
Internal live native pointer. |
source |
Source path or |
For every focal sample and marginal tree, this function walks toward the
root and records the first node whose population is one of
source_populations. Adjacent tree intervals with the same source are
merged. This is exact ancestry truth only when the simulation's population
and node-retention semantics make those source populations authoritative.
tskit_ancestry_intervals( x, source_populations, samples = NULL, require_resolved = TRUE )tskit_ancestry_intervals( x, source_populations, samples = NULL, require_resolved = TRUE )
x |
A |
source_populations |
A non-empty vector of zero-based source-population IDs. Names, when supplied, become the returned source labels and should be dataset-qualified. |
samples |
Zero-based focal sample-node IDs. |
require_resolved |
Whether to fail if a focal lineage reaches a root without encountering a declared source population. |
A data frame of sample IDs, half-open intervals, source labels, and source-population IDs, grouped by sample and ordered by coordinate.
Haller et al. (2019), Tree-sequence recording in SLiM opens new
horizons for forward-time simulation of whole genomes,
doi:10.1111/1755-0998.12968. The published local-ancestry example is
pinned at SLiMTreeSeqPub commit
6715c28b02942bc4757c9f8bcab133ad4a0bfcfb.
Write a succinct tree sequence
tskit_dump(x, path, overwrite = FALSE)tskit_dump(x, path, overwrite = FALSE)
x |
A |
path |
Destination |
overwrite |
Whether to replace an existing file. |
The normalized destination path, invisibly.
Metadata remains native and is not decoded by this initial accessor.
tskit_edges(x)tskit_edges(x)
x |
A |
A data frame with zero-based IDs and edge coordinates and nodes.
The example contains two sample nodes from one individual and two source ancestors spanning adjacent trees over a sequence of length 10. Population and individual metadata, one site, and one mutation exercise the native constructor without external software.
tskit_example()tskit_example()
An in-memory TreeSequence.
Ragged locations and parent IDs are returned as list columns. Individual
metadata remains opaque and is available through tskit_metadata().
tskit_individuals(x)tskit_individuals(x)
x |
A |
A data frame with zero-based individual IDs, flags, location and parent list columns, and metadata lengths.
Load a succinct tree sequence
tskit_load(path)tskit_load(path)
path |
Existing |
A TreeSequence owning the loaded native value.
Rtskit deliberately returns raw bytes and does not infer a codec from a
schema. Row tables return a list of raw vectors in the requested ID order.
Top-level tree-sequence and reference-sequence metadata return one raw
vector and do not accept id.
tskit_metadata(x, table, id = NULL)tskit_metadata(x, table, id = NULL)
x |
A |
table |
One of |
id |
Optional zero-based row IDs. |
A raw vector for top-level metadata or a list of raw vectors for a row table.
The schema is returned exactly as stored. Convert or decode it explicitly only when the declared codec is understood by the caller.
tskit_metadata_schema(x, table)tskit_metadata_schema(x, table)
x |
A |
table |
One of |
A raw vector containing the table metadata schema.
Metadata remains native and is not decoded by this initial accessor.
tskit_nodes(x)tskit_nodes(x)
x |
A |
A data frame with zero-based IDs, flags, time, population, and individual columns.
Population metadata remains opaque. Use tskit_metadata() to request its
bytes explicitly.
tskit_populations(x)tskit_populations(x)
x |
A |
A data frame with zero-based population IDs and metadata lengths.
Return sample node IDs
tskit_samples(x)tskit_samples(x)
x |
A |
An integer vector of zero-based node IDs.
Summarize a succinct tree sequence
tskit_summary(x)tskit_summary(x)
x |
A |
A named list of sequence length and table/tree counts. Counts are doubles because tskit sizes can exceed R's integer range.
Traverse tree intervals
tskit_trees(x)tskit_trees(x)
x |
A |
A data frame containing each tree index, half-open interval, root count, and active edge count.