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:

  1. Individuals which are new to self.
  2. Edges whose parent or child are new to self.
  3. Sites which were not present in self.
  4. 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.