Function tskit::bindings::tsk_table_collection_union
source · pub unsafe extern "C" fn tsk_table_collection_union(
self_: *mut tsk_table_collection_t,
other: *const tsk_table_collection_t,
other_node_mapping: *const tsk_id_t,
options: tsk_flags_t
) -> c_int
Expand description
@brief Forms the node-wise union of two table collections.
@rst
Expands this table collection by adding the non-shared portions of another table
collection to itself. The other_node_mapping
encodes which nodes in other
are
equivalent to a node in self
. The positions in the other_node_mapping
array
correspond to node ids in other
, and the elements encode the equivalent
node id in self
or :c:macro:TSK_NULL
if the node is exclusive to other
. Nodes
that are exclusive other
are added to self
, along with:
- Individuals which are new to
self
. - Edges whose parent or child are new to
self
. - Sites which were not present in
self
. - Mutations whose nodes are new to
self
.
By default, populations of newly added nodes are assumed to be new populations, and added to the population table as well.
This operation will also sort the resulting tables, so the tables may change even if nothing new is added, if the original tables were not sorted.
.. note:: Migrations are currently not supported by union, and an error will be raised if we attempt call union on a table collection with migrations.
Options**:
Options can be specified by providing one or more of the following bitwise flags:
- :c:macro:
TSK_UNION_NO_CHECK_SHARED
- :c:macro:
TSK_UNION_NO_ADD_POP
@endrst
@param self A pointer to a tsk_table_collection_t object. @param other A pointer to a tsk_table_collection_t object. @param other_node_mapping An array of node IDs that relate nodes in other to nodes in self: the k-th element of other_node_mapping should be the index of the equivalent node in self, or TSK_NULL if the node is not present in self (in which case it will be added to self). @param options Union options; see above for the available bitwise flags. For the default behaviour, a value of 0 should be provided. @return Return 0 on success or a negative value on failure.