Function tskit::bindings::tsk_table_collection_subset

source · 
pub unsafe extern "C" fn tsk_table_collection_subset(
    self_: *mut tsk_table_collection_t,
    nodes: *const tsk_id_t,
    num_nodes: tsk_size_t,
    options: tsk_flags_t
) -> c_int
Expand description

@brief Subsets and reorders a table collection according to an array of nodes.

@rst Reduces the table collection to contain only the entries referring to the provided list of nodes, with nodes reordered according to the order they appear in the nodes argument. Specifically, this subsets and reorders each of the tables as follows (but see options, below):

  1. Nodes: if in the list of nodes, and in the order provided.
  2. Individuals: if referred to by a retained node.
  3. Populations: if referred to by a retained node, and in the order first seen when traversing the list of retained nodes.
  4. Edges: if both parent and child are retained nodes.
  5. Mutations: if the mutation’s node is a retained node.
  6. Sites: if any mutations remain at the site after removing mutations.

Retained individuals, edges, mutations, and sites appear in the same order as in the original tables. Note that only the information directly associated with the provided nodes is retained - for instance, subsetting to nodes=[A, B] does not retain nodes ancestral to A and B, and only retains the individuals A and B are in, and not their parents.

This function does not require the tables to be sorted.

.. note:: Migrations are currently not supported by subset, and an error will be raised if we attempt call subset on a table collection with greater than zero migrations.

Options**:

Options can be specified by providing one or more of the following bitwise flags:

  • :c:macro:TSK_SUBSET_NO_CHANGE_POPULATIONS
  • :c:macro:TSK_SUBSET_KEEP_UNREFERENCED @endrst

@param self A pointer to a tsk_table_collection_t object. @param nodes An array of num_nodes valid node IDs. @param num_nodes The number of node IDs in the input nodes array. @param options Bitwise option flags. @return Return 0 on success or a negative value on failure.