From db7af188f1a380b75a195db2b42ccd47683e6e6f Mon Sep 17 00:00:00 2001 From: Ben Jeffery Date: Fri, 6 May 2022 17:34:15 +0100 Subject: [PATCH] Document options --- c/tests/test_trees.c | 2 +- c/tskit/core.c | 2 +- c/tskit/core.h | 101 +++++---- c/tskit/genotypes.h | 4 +- c/tskit/tables.h | 481 ++++++++++++++++++++++++------------------- c/tskit/trees.c | 2 +- c/tskit/trees.h | 83 ++++---- docs/c-api.rst | 70 ++++++- 8 files changed, 444 insertions(+), 301 deletions(-) diff --git a/c/tests/test_trees.c b/c/tests/test_trees.c index 0af2ac2efb..824f60ab62 100644 --- a/c/tests/test_trees.c +++ b/c/tests/test_trees.c @@ -7052,7 +7052,7 @@ test_init_take_ownership_no_edge_metadata(void) tsk_treeseq_free(&ts); ret = tsk_treeseq_init(&ts, tables, TSK_TAKE_OWNERSHIP); - CU_ASSERT_EQUAL_FATAL(ret, TSK_CANT_TAKE_OWNERSHIP_NO_EDGE_METADATA); + CU_ASSERT_EQUAL_FATAL(ret, TSK_ERR_CANT_TAKE_OWNERSHIP_NO_EDGE_METADATA); tsk_treeseq_free(&ts); } diff --git a/c/tskit/core.c b/c/tskit/core.c index 220cebb0a2..777ad6a15a 100644 --- a/c/tskit/core.c +++ b/c/tskit/core.c @@ -377,7 +377,7 @@ tsk_strerror_internal(int err) case TSK_ERR_VARIANT_CANT_DECODE_COPY: ret = "Can't decode a copy of a variant"; break; - case TSK_CANT_TAKE_OWNERSHIP_NO_EDGE_METADATA: + case TSK_ERR_CANT_TAKE_OWNERSHIP_NO_EDGE_METADATA: ret = "A tree sequence can't take ownership of tables with " "TSK_NO_EDGE_METADATA"; break; diff --git a/c/tskit/core.h b/c/tskit/core.h index 253cd586c7..c09ad3ceda 100644 --- a/c/tskit/core.h +++ b/c/tskit/core.h @@ -70,33 +70,13 @@ extern "C" { #define TSK_DBL_DECIMAL_DIG (DBL_DIG + 3) #endif -/* We define a specific NAN value for default mutation time which indicates - * the time is unknown. We use a specific value so that if mutation time is set to - * a NAN from a computation we can reject it. This specific value is a non-signalling - * NAN with the last six fraction bytes set to the ascii of "tskit!" - */ -#define TSK_UNKNOWN_TIME_HEX 0x7FF874736B697421ULL -static inline double -__tsk_nan_f(void) -{ - const union { - uint64_t i; - double f; - } nan_union = { .i = TSK_UNKNOWN_TIME_HEX }; - return nan_union.f; -} -#define TSK_UNKNOWN_TIME __tsk_nan_f() - -#define TSK_TIME_UNITS_UNKNOWN "unknown" -#define TSK_TIME_UNITS_UNCALIBRATED "uncalibrated" - /** @brief Tskit Object IDs. @rst All objects in tskit are referred to by integer IDs corresponding to the row they occupy in the relevant table. The ``tsk_id_t`` type should be used -when manipulating these ID values. The reserved value ``TSK_NULL`` (-1) defines +when manipulating these ID values. The reserved value :c:macro:`TSK_NULL` (-1) defines missing data. @endrst */ @@ -166,15 +146,54 @@ to the API or ABI are introduced, i.e., internal refactors of bugfixes. #define TSK_VERSION_PATCH 15 /** @} */ -/* Node flags */ +/* +We define a specific NAN value for default mutation time which indicates +the time is unknown. We use a specific value so that if mutation time is set to +a NAN from a computation we can reject it. This specific value is a non-signalling +NAN with the last six fraction bytes set to the ascii of "tskit!" +*/ +#define TSK_UNKNOWN_TIME_HEX 0x7FF874736B697421ULL +static inline double +__tsk_nan_f(void) +{ + const union { + uint64_t i; + double f; + } nan_union = { .i = TSK_UNKNOWN_TIME_HEX }; + return nan_union.f; +} + +/** +@defgroup GENERIC_CONSTANTS General options flags used in some functions. +@{ +*/ +/** +Used in node flags to indicate that a node is a sample node. +*/ #define TSK_NODE_IS_SAMPLE 1u -/* The null ID */ +/** +Null value used for cases such as absent id references. +*/ #define TSK_NULL ((tsk_id_t) -1) -/* Missing data in an array of genotypes */ +/** +Value used for missing data in genotype arrays. +*/ #define TSK_MISSING_DATA (-1) +/** +Value to indicate that a time is unknown. Note that this value is a non-signalling NAN +whose representation differs from the NAN generated by computations such as divide by zeros. +*/ +#define TSK_UNKNOWN_TIME __tsk_nan_f() + +/** @} */ + +#define TSK_TIME_UNITS_UNKNOWN "unknown" +#define TSK_TIME_UNITS_UNCALIBRATED "uncalibrated" + + #define TSK_FILE_FORMAT_NAME "tskit.trees" #define TSK_FILE_FORMAT_NAME_LENGTH 11 #define TSK_FILE_FORMAT_VERSION_MAJOR 12 @@ -186,20 +205,31 @@ to the API or ABI are introduced, i.e., internal refactors of bugfixes. */ /* Place the commmon options at the top of the space; this way we can start - * options for individual functions at the bottom without worrying about - * clashing with the common options */ +options for individual functions at the bottom without worrying about +clashing with the common options +*/ -/** @brief Turn on debugging output. Not supported by all functions. */ +/** Turn on debugging output. Not supported by all functions. */ #define TSK_DEBUG (1u << 31) -/** @brief Do not initialise the parameter object. */ +/** Do not initialise the parameter object. */ #define TSK_NO_INIT (1u << 30) -/** @brief Do not run integrity checks before performing an operation. */ +/** +Do not run integrity checks before performing an operation. +This performance optimisation should not be used unless the calling code can +guarantee reference integrity within the table collection. References +to rows not in the table or bad offsets will result in undefined +behaviour. +*/ #define TSK_NO_CHECK_INTEGRITY (1u << 29) -/** @brief Instead of taking a copy of input data, take ownership of it - * and its lifecycle */ +/** +Instead of taking a copy of input objects, the function should take ownership +of them and manage their lifecycle. The caller specifying this flag should no +longer modify or free the object or objects passed. See individual functions +using this flag for what object it applies to. +*/ #define TSK_TAKE_OWNERSHIP (1u << 28) /** @} */ @@ -346,7 +376,7 @@ An unsupported type was provided for a column in the file. #define TSK_ERR_CANNOT_EXTEND_FROM_SELF -806 #define TSK_ERR_SILENT_MUTATIONS_NOT_SUPPORTED -807 #define TSK_ERR_VARIANT_CANT_DECODE_COPY -808 -#define TSK_CANT_TAKE_OWNERSHIP_NO_EDGE_METADATA -809 +#define TSK_ERR_CANT_TAKE_OWNERSHIP_NO_EDGE_METADATA -809 /* Stats errors */ #define TSK_ERR_BAD_NUM_WINDOWS -900 @@ -510,18 +540,19 @@ tsk_size_t tsk_search_sorted(const double *array, tsk_size_t size, double value) double tsk_round(double x, unsigned int ndigits); /** -@brief Check if a number is TSK_UNKNOWN_TIME +@brief Check if a number is ``TSK_UNKNOWN_TIME`` @rst Unknown time values in tskit are represented by a particular NaN value. Since NaN values are not equal to each other by definition, a simple comparison like ``mutation.time == TSK_UNKNOWN_TIME`` will fail even if the mutation's time is TSK_UNKNOWN_TIME. This function compares the underlying bit representation of a double -value and returns true iff it is equal to the specific NaN value TSK_UNKNOWN_TIME. +value and returns true iff it is equal to the specific NaN value +:c:macro:`TSK_UNKNOWN_TIME`. @endrst @param val The number to check -@return true if the number is TSK_UNKNOWN_TIME else false +@return true if the number is ``TSK_UNKNOWN_TIME`` else false */ bool tsk_is_unknown_time(double val); diff --git a/c/tskit/genotypes.h b/c/tskit/genotypes.h index 2145001051..d769742577 100644 --- a/c/tskit/genotypes.h +++ b/c/tskit/genotypes.h @@ -112,8 +112,8 @@ have their genotypes decoded. A copy of this array will be taken by the variant. ``NULL`` sentinel value. If specified, the genotypes will be decoded to match the index in this allele array. If ``NULL`` then alleles will be automatically determined from the mutations encountered. -@param options Variant options. Either ``0`` or ``TSK_ISOLATED_NOT_MISSING`` which if -specified indicates that isolated sample nodes should not be decoded as the "missing" +@param options Variant options. Either ``0`` or ``TSK_ISOLATED_NOT_MISSING`` which +if specified indicates that isolated sample nodes should not be decoded as the "missing" state but as the ancestral state (or the state of any mutation above them). @return Return 0 on success or a negative value on failure. */ diff --git a/c/tskit/tables.h b/c/tskit/tables.h index 2fccf79440..e625f471dc 100644 --- a/c/tskit/tables.h +++ b/c/tskit/tables.h @@ -671,64 +671,212 @@ typedef struct { /* Common function options */ /****************************************************************************/ -/* Flags for simplify() */ +/** +@defgroup API_FLAGS_SIMPLIFY_GROUP :c:func:`tsk_table_collection_simplify` and +:c:func:`tsk_treeseq_simplify` specific flags. +@{ +*/ +/** Remove sites from the output if there are no mutations that reference them.*/ #define TSK_SIMPLIFY_FILTER_SITES (1 << 0) +/** Remove populations from the output if there are no nodes or migrations that +reference them. */ #define TSK_SIMPLIFY_FILTER_POPULATIONS (1 << 1) +/** Remove individuals from the output if there are no nodes that reference them.*/ #define TSK_SIMPLIFY_FILTER_INDIVIDUALS (1 << 2) +/** +Reduce the topological information in the tables to the minimum necessary to +represent the trees that contain sites. If there are zero sites this will +result in an zero output edges. When the number of sites is greater than zero, +every tree in the output tree sequence will contain at least one site. +For a given site, the topology of the tree containing that site will be +identical (up to node ID remapping) to the topology of the corresponding tree +in the input. +*/ #define TSK_SIMPLIFY_REDUCE_TO_SITE_TOPOLOGY (1 << 3) +/** +By default simplify removes unary nodes (i.e., nodes with exactly one child) +along the path from samples to root. If this option is specified such unary +nodes will be preserved in the output. +*/ #define TSK_SIMPLIFY_KEEP_UNARY (1 << 4) +/** +By default simplify removes all topology ancestral the MRCAs of the samples. +This option inserts edges from these MRCAs back to the roots of the input +trees. +*/ #define TSK_SIMPLIFY_KEEP_INPUT_ROOTS (1 << 5) +/** +@rst +This acts like :c:macro:`TSK_SIMPLIFY_KEEP_UNARY` (and is mutually exclusive with that +flag). It keeps unary nodes, but only if the unary node is referenced from an individual. +@endrst +*/ #define TSK_SIMPLIFY_KEEP_UNARY_IN_INDIVIDUALS (1 << 6) +/** @} */ -/* Flags for subset() */ +/** +@defgroup API_FLAGS_SUBSET_GROUP :c:func:`tsk_table_collection_subset` specific flags. +@{ +*/ +/**If this flag is provided, the population table will not be changed in any way.*/ #define TSK_SUBSET_NO_CHANGE_POPULATIONS (1 << 0) +/** +@rst +If this flag is provided, then unreferenced sites, individuals, and populations +will not be removed. If so, the site and individual tables will not be changed, +and (unless :c:macro:`TSK_SUBSET_NO_CHANGE_POPULATIONS` is also provided) unreferenced +populations will be placed last, in their original order. +@endrst +*/ #define TSK_SUBSET_KEEP_UNREFERENCED (1 << 1) +/** @} */ -/* Flags for check_integrity */ +/** +@defgroup API_FLAGS_CHECK_INTEGRITY_GROUP :c:func:`tsk_table_collection_check_integrity` +specific flags. +@{ +*/ +/** Check edge ordering constraints for a tree sequence. */ #define TSK_CHECK_EDGE_ORDERING (1 << 0) +/** Check that sites are in nondecreasing position order. */ #define TSK_CHECK_SITE_ORDERING (1 << 1) +/**Check for any duplicate site positions. */ #define TSK_CHECK_SITE_DUPLICATES (1 << 2) +/** +Check contraints on the ordering of mutations. Any non-null +mutation parents and known times are checked for ordering +constraints. +*/ #define TSK_CHECK_MUTATION_ORDERING (1 << 3) +/**Check individual parents are before children, where specified. */ #define TSK_CHECK_INDIVIDUAL_ORDERING (1 << 4) +/**Check migrations are ordered by time. */ #define TSK_CHECK_MIGRATION_ORDERING (1 << 5) +/**Check that the table indexes exist, and contain valid edge references. */ #define TSK_CHECK_INDEXES (1 << 6) +/** +All checks needed to define a valid tree sequence. Note that +this implies all of the above checks. +*/ #define TSK_CHECK_TREES (1 << 7) /* Leave room for more positive check flags */ +/** +Do not check integrity of references to populations. This +can be safely combined with the other checks. +*/ #define TSK_NO_CHECK_POPULATION_REFS (1 << 12) +/** @} */ +/** +@defgroup API_FLAGS_LOAD_INIT_GROUP Flags used by load and init methods. +@{ +*/ /* These flags are for table collection load or init, or used as flags on table collection or individual tables. * As flags are passed though from load to init they share a namespace */ +/** Skip reading tables, and only load top-level information. */ #define TSK_LOAD_SKIP_TABLES (1 << 0) +/** Do not load reference sequence. */ #define TSK_LOAD_SKIP_REFERENCE_SEQUENCE (1 << 1) +/** +@rst +Do not allocate space to store metadata in this table. Operations +attempting to add non-empty metadata to the table will fail +with error TSK_ERR_METADATA_DISABLED. +@endrst +*/ #define TSK_TABLE_NO_METADATA (1 << 2) +/** +@rst +Do not allocate space to store metadata in the edge table. Operations +attempting to add non-empty metadata to the edge table will fail +with error TSK_ERR_METADATA_DISABLED. +@endrst +*/ #define TSK_TC_NO_EDGE_METADATA (1 << 3) +/** @} */ /* Flags for dump tables */ /* We may not want to document this flag, but it's useful for testing * so we put it high up in the bit space, below the common options */ #define TSK_DUMP_FORCE_OFFSET_64 (1 << 27) -/* Flags for table collection copy */ +/** +@defgroup API_FLAGS_COPY_GROUP Flags used by :c:func:`tsk_table_collection_copy`. +@{ +*/ +/** Copy the file uuid, by default this is not copied. */ #define TSK_COPY_FILE_UUID (1 << 0) +/** @} */ -/* Flags for union() */ +/** +@defgroup API_FLAGS_UNION_GROUP Flags used by :c:func:`tsk_table_collection_union`. +@{ +*/ +/** +By default, union checks that the portion of shared history between +``self`` and ``other``, as implied by ``other_node_mapping``, are indeed +equivalent. It does so by subsetting both ``self`` and ``other`` on the +equivalent nodes specified in ``other_node_mapping``, and then checking for +equality of the subsets. +*/ #define TSK_UNION_NO_CHECK_SHARED (1 << 0) +/** + By default, all nodes new to ``self`` are assigned new populations. If this +option is specified, nodes that are added to ``self`` will retain the +population IDs they have in ``other``. + */ #define TSK_UNION_NO_ADD_POP (1 << 1) +/** @} */ -/* Flags for table collection equals */ +/** +@defgroup API_FLAGS_CMP_GROUP Flags used by :c:func:`tsk_table_collection_equals`. +@{ +*/ +/** +Do not include the top-level tree sequence metadata and metadata schemas +in the comparison. +*/ #define TSK_CMP_IGNORE_TS_METADATA (1 << 0) +/** Do not include the provenance table in comparison. */ #define TSK_CMP_IGNORE_PROVENANCE (1 << 1) +/** +@rst +Do not include metadata when comparing the table collections. +This includes both the top-level tree sequence metadata as well as the +metadata for each of the tables (i.e, :c:macro:`TSK_CMP_IGNORE_TS_METADATA` is implied). +All metadata schemas are also ignored. +@endrst +*/ #define TSK_CMP_IGNORE_METADATA (1 << 2) +/** +@rst +Do not include the timestamp information when comparing the provenance +tables. This has no effect if :c:macro:`TSK_CMP_IGNORE_PROVENANCE` is specified. +@endrst +*/ #define TSK_CMP_IGNORE_TIMESTAMPS (1 << 3) +/** +Do not include any tables in the comparison, thus comparing only the +top-level information of the table collections being compared. +*/ #define TSK_CMP_IGNORE_TABLES (1 << 4) +/** Do not include the reference sequence in the comparison. */ #define TSK_CMP_IGNORE_REFERENCE_SEQUENCE (1 << 5) +/** @} */ -/* Flags for table collection clear */ +/** +@defgroup API_FLAGS_CLEAR_GROUP Flags used by :c:func:`tsk_table_collection_clear`. +@{ +*/ +/** Additionally clear the table metadata schemas*/ #define TSK_CLEAR_METADATA_SCHEMAS (1 << 0) +/** Additionally clear the tree-sequence metadata and schema*/ #define TSK_CLEAR_TS_METADATA_AND_SCHEMA (1 << 1) +/** Additionally clear the provenance table*/ #define TSK_CLEAR_PROVENANCE (1 << 2) +/** @} */ /****************************************************************************/ /* Function signatures */ @@ -894,9 +1042,7 @@ more of the following bitwise flags. By default (options=0) tables are considered equal if they are byte-wise identical in all columns, and their metadata schemas are byte-wise identical. -TSK_CMP_IGNORE_METADATA - Do not include metadata or metadata schemas in the comparison. - +- :c:macro:`TSK_CMP_IGNORE_METADATA` @endrst @param self A pointer to a tsk_individual_table_t object. @@ -919,9 +1065,9 @@ Indexes that are present are also copied to the destination table. @endrst @param self A pointer to a tsk_individual_table_t object. -@param dest A pointer to a tsk_individual_table_t object. If the TSK_NO_INIT option - is specified, this must be an initialised individual table. If not, it must - be an uninitialised individual table. +@param dest A pointer to a tsk_individual_table_t object. If the TSK_NO_INIT +option is specified, this must be an initialised individual table. If not, it must be an +uninitialised individual table. @param options Bitwise option flags. @return Return 0 on success or a negative value on failure. */ @@ -1145,8 +1291,10 @@ for details of the columns in this table. @param self A pointer to a tsk_node_table_t object. @param flags The bitwise flags for the new node. @param time The time for the new node. -@param population The population for the new node. Set to TSK_NULL if not known. -@param individual The individual for the new node. Set to TSK_NULL if not known. +@param population The population for the new node. Set to TSK_NULL if not +known. +@param individual The individual for the new node. Set to TSK_NULL if not +known. @param metadata The metadata to be associated with the new node. This is a pointer to arbitrary memory. Can be ``NULL`` if ``metadata_length`` is 0. @param metadata_length The size of the metadata array in bytes. @@ -1247,9 +1395,7 @@ more of the following bitwise flags. By default (options=0) tables are considered equal if they are byte-wise identical in all columns, and their metadata schemas are byte-wise identical. -TSK_CMP_IGNORE_METADATA - Do not include metadata or metadata schemas in the comparison. - +- :c:macro:`TSK_CMP_IGNORE_METADATA` @endrst @param self A pointer to a tsk_node_table_t object. @@ -1265,7 +1411,7 @@ bool tsk_node_table_equals( @rst By default the method initialises the specified destination table. If the -destination is already initialised, the :c:macro:`TSK_NO_INIT` option should +destination is already initialised, the TSK_NO_INIT option should be supplied to avoid leaking memory. @endrst @@ -1432,11 +1578,7 @@ are initialised and freed. Options can be specified by providing one or more of the following bitwise flags: -TSK_TABLE_NO_METADATA - Do not allocate space to store metadata in this table. Operations - attempting to add non-empty metadata to the table will fail - with error TSK_ERR_METADATA_DISABLED. - +- :c:macro:`TSK_TABLE_NO_METADATA` @endrst @param self A pointer to an uninitialised tsk_edge_table_t object. @@ -1537,9 +1679,9 @@ int tsk_edge_table_truncate(tsk_edge_table_t *self, tsk_size_t num_rows); @rst Appends the rows at the specified indexes from the table ``other`` to the end of this -table. Row indexes can be repeated and in any order. If ``row_indexes`` is NULL, append -the first ``num_rows`` from ``other`` to this table. Note that metadata is copied as-is -and is not checked for compatibility with any existing schema on this table. +table. Row indexes can be repeated and in any order. If ``row_indexes`` is ``NULL``, +append the first ``num_rows`` from ``other`` to this table. Note that metadata is copied +as-is and is not checked for compatibility with any existing schema on this table. @endrst @param self A pointer to a tsk_edge_table_t object where rows are to be added. @@ -1567,9 +1709,7 @@ more of the following bitwise flags. By default (options=0) tables are considered equal if they are byte-wise identical in all columns, and their metadata schemas are byte-wise identical. -TSK_CMP_IGNORE_METADATA - Do not include metadata or metadata schemas in the comparison. - +- :c:macro:`TSK_CMP_IGNORE_METADATA` @endrst @param self A pointer to a tsk_edge_table_t object. @@ -1907,9 +2047,7 @@ more of the following bitwise flags. By default (options=0) tables are considered equal if they are byte-wise identical in all columns, and their metadata schemas are byte-wise identical. -TSK_CMP_IGNORE_METADATA - Do not include metadata or metadata schemas in the comparison. - +- :c:macro:`TSK_CMP_IGNORE_METADATA` @endrst @param self A pointer to a tsk_migration_table_t object. @@ -1930,9 +2068,9 @@ be supplied to avoid leaking memory. @endrst @param self A pointer to a tsk_migration_table_t object. -@param dest A pointer to a tsk_migration_table_t object. If the TSK_NO_INIT option - is specified, this must be an initialised migration table. If not, it must - be an uninitialised migration table. +@param dest A pointer to a tsk_migration_table_t object. If the TSK_NO_INIT +option is specified, this must be an initialised migration table. If not, it must be an +uninitialised migration table. @param options Bitwise option flags. @return Return 0 on success or a negative value on failure. */ @@ -2221,9 +2359,7 @@ more of the following bitwise flags. By default (options=0) tables are considered equal if they are byte-wise identical in all columns, and their metadata schemas are byte-wise identical. -TSK_CMP_IGNORE_METADATA - Do not include metadata or metadata schemas in the comparison. - +- :c:macro:`TSK_CMP_IGNORE_METADATA` @endrst @param self A pointer to a tsk_site_table_t object. @@ -2557,9 +2693,7 @@ more of the following bitwise flags. By default (options=0) tables are considered equal if they are byte-wise identical in all columns, and their metadata schemas are byte-wise identical. -TSK_CMP_IGNORE_METADATA - Do not include metadata or metadata schemas in the comparison. - +- :c:macro:`TSK_CMP_IGNORE_METADATA` @endrst @param self A pointer to a tsk_mutation_table_t object. @@ -2580,9 +2714,9 @@ be supplied to avoid leaking memory. @endrst @param self A pointer to a tsk_mutation_table_t object. -@param dest A pointer to a tsk_mutation_table_t object. If the TSK_NO_INIT option - is specified, this must be an initialised mutation table. If not, it must - be an uninitialised mutation table. +@param dest A pointer to a tsk_mutation_table_t object. If the TSK_NO_INIT +option is specified, this must be an initialised mutation table. If not, it must be an +uninitialised mutation table. @param options Bitwise option flags. @return Return 0 on success or a negative value on failure. */ @@ -2884,11 +3018,10 @@ more of the following bitwise flags. By default (options=0) tables are considered equal if they are byte-wise identical in all columns, and their metadata schemas are byte-wise identical. -TSK_CMP_IGNORE_METADATA +- :c:macro:`TSK_CMP_IGNORE_METADATA` Do not include metadata in the comparison. Note that as metadata is the only column in the population table, two population tables are considered equal if they have the same number of rows if this flag is specified. - @endrst @param self A pointer to a tsk_population_table_t object. @@ -2909,9 +3042,9 @@ be supplied to avoid leaking memory. @endrst @param self A pointer to a tsk_population_table_t object. -@param dest A pointer to a tsk_population_table_t object. If the TSK_NO_INIT option - is specified, this must be an initialised population table. If not, it must - be an uninitialised population table. +@param dest A pointer to a tsk_population_table_t object. If the TSK_NO_INIT +option is specified, this must be an initialised population table. If not, it must be an +uninitialised population table. @param options Bitwise option flags. @return Return 0 on success or a negative value on failure. */ @@ -3181,10 +3314,7 @@ Options to control the comparison can be specified by providing one or more of the following bitwise flags. By default (options=0) tables are considered equal if they are byte-wise identical in all columns. -TSK_CMP_IGNORE_TIMESTAMPS - Do not include the timestamp column when comparing provenance - tables. - +- :c:macro:`TSK_CMP_IGNORE_TIMESTAMPS` @endrst @param self A pointer to a tsk_provenance_table_t object. @@ -3205,9 +3335,9 @@ be supplied to avoid leaking memory. @endrst @param self A pointer to a tsk_provenance_table_t object. -@param dest A pointer to a tsk_provenance_table_t object. If the TSK_NO_INIT option - is specified, this must be an initialised provenance table. If not, it must - be an uninitialised provenance table. +@param dest A pointer to a tsk_provenance_table_t object. If the TSK_NO_INIT +option is specified, this must be an initialised provenance table. If not, it must be an +uninitialised provenance table. @param options Bitwise option flags. @return Return 0 on success or a negative value on failure. */ @@ -3370,11 +3500,7 @@ are initialised and freed. Options can be specified by providing one or more of the following bitwise flags: -TSK_TC_NO_EDGE_METADATA - Do not allocate space to store metadata in the edge table. Operations - attempting to add non-empty metadata to the edge table will fail - with error TSK_ERR_METADATA_DISABLED. - +- :c:macro:`TSK_TC_NO_EDGE_METADATA` @endrst @param self A pointer to an uninitialised tsk_table_collection_t object. @@ -3400,20 +3526,17 @@ this table collection. By default this operation clears all tables except the provenance table, retaining table metadata schemas and the tree-sequnce level metadata and schema. +No memory is freed as a result of this operation; please use +:c:func:`tsk_table_collection_free` to free internal resources. + **Options** Options can be specified by providing one or more of the following bitwise flags: -TSK_CLEAR_PROVENANCE - Additionally clear the provenance table -TSK_CLEAR_METADATA_SCHEMAS - Additionally clear the table metadata schemas -TSK_CLEAR_TS_METADATA_AND_SCHEMA - Additionally clear the tree-sequence metadata and schema - -No memory is freed as a result of this operation; please use -:c:func:`tsk_table_collection_free` to free internal resources. +- :c:macro:`TSK_CLEAR_PROVENANCE` +- :c:macro:`TSK_CLEAR_METADATA_SCHEMAS` +- :c:macro:`TSK_CLEAR_TS_METADATA_AND_SCHEMA` @endrst @param self A pointer to a tsk_table_collection_t object. @@ -3441,24 +3564,12 @@ collections are considered equal if all of the tables are byte-wise identical, and the sequence lengths, metadata and metadata schemas of the two table collections are identical. -TSK_CMP_IGNORE_PROVENANCE - Do not include the provenance table in comparison. -TSK_CMP_IGNORE_METADATA - Do not include metadata when comparing the table collections. - This includes both the top-level tree sequence metadata as well as the - metadata for each of the tables (i.e, TSK_CMP_IGNORE_TS_METADATA is implied). - All metadata schemas are also ignored. -TSK_CMP_IGNORE_TS_METADATA - Do not include the top-level tree sequence metadata and metadata schemas - in the comparison. -TSK_CMP_IGNORE_TIMESTAMPS - Do not include the timestamp information when comparing the provenance - tables. This has no effect if TSK_CMP_IGNORE_PROVENANCE is specified. -TSK_CMP_IGNORE_TABLES - Do not include any tables in the comparison, thus comparing only the - top-level information of the table collections being compared. -TSK_CMP_IGNORE_REFERENCE_SEQUENCE - Do not include the reference sequence in the comparison. +- :c:macro:`TSK_CMP_IGNORE_PROVENANCE` +- :c:macro:`TSK_CMP_IGNORE_METADATA` +- :c:macro:`TSK_CMP_IGNORE_TS_METADATA` +- :c:macro:`TSK_CMP_IGNORE_TIMESTAMPS` +- :c:macro:`TSK_CMP_IGNORE_TABLES` +- :c:macro:`TSK_CMP_IGNORE_REFERENCE_SEQUENCE` @endrst @param self A pointer to a tsk_table_collection_t object. @@ -3476,12 +3587,16 @@ bool tsk_table_collection_equals(const tsk_table_collection_t *self, By default the method initialises the specified destination table collection. If the destination is already initialised, the :c:macro:`TSK_NO_INIT` option should be supplied to avoid leaking memory. + +**Options** + +:c:macro:`TSK_COPY_FILE_UUID` @endrst @param self A pointer to a tsk_table_collection_t object. -@param dest A pointer to a tsk_table_collection_t object. If the TSK_NO_INIT option - is specified, this must be an initialised table collection. If not, it must - be an uninitialised table collection. +@param dest A pointer to a tsk_table_collection_t object. If the TSK_NO_INIT +option is specified, this must be an initialised table collection. If not, it must be an +uninitialised table collection. @param options Bitwise option flags. @return Return 0 on success or a negative value on failure. */ @@ -3517,10 +3632,10 @@ If the file contains multiple table collections, this function will load the first. Please see the :c:func:`tsk_table_collection_loadf` for details on how to sequentially load table collections from a stream. -If the TSK_LOAD_SKIP_TABLES option is set, only the non-table information from +If the :c:macro:`TSK_LOAD_SKIP_TABLES` option is set, only the non-table information from the table collection will be read, leaving all tables with zero rows and no metadata or schema. -If the TSK_LOAD_SKIP_REFERENCE_SEQUENCE option is set, the table collection is +If the :c:macro:`TSK_LOAD_SKIP_REFERENCE_SEQUENCE` option is set, the table collection is read without loading the reference sequence. **Options** @@ -3528,12 +3643,9 @@ read without loading the reference sequence. Options can be specified by providing one or more of the following bitwise flags: -TSK_NO_INIT - Do not initialise this :c:type:`tsk_table_collection_t` before loading. -TSK_LOAD_SKIP_TABLES - Skip reading tables, and only load top-level information. -TSK_LOAD_SKIP_REFERENCE_SEQUENCE - Do not load reference sequence. +- :c:macro:`TSK_NO_INIT` +- :c:macro:`TSK_LOAD_SKIP_TABLES` +- :c:macro:`TSK_LOAD_SKIP_REFERENCE_SEQUENCE` **Examples** @@ -3585,29 +3697,23 @@ different error conditions. Please see the sequentially load tree sequences from a stream. Please note that this streaming behaviour is not supported if the -TSK_LOAD_SKIP_TABLES or TSK_LOAD_SKIP_REFERENCE_SEQUENCE option is set. -If the TSK_LOAD_SKIP_TABLES option is set, only the non-table information from -the table collection will be read, leaving all tables with zero rows and no -metadata or schema. -If the TSK_LOAD_SKIP_REFERENCE_SEQUENCE option is set, the table collection is -read without loading the reference sequence. -When attempting to read from a stream with multiple table collection definitions -and either of these two options set, the requested information from the first -table collection will be read on the first call to -:c:func:`tsk_table_collection_loadf`, with subsequent calls leading to errors. +:c:macro:`TSK_LOAD_SKIP_TABLES` or :c:macro:`TSK_LOAD_SKIP_REFERENCE_SEQUENCE` option is +set. If the :c:macro:`TSK_LOAD_SKIP_TABLES` option is set, only the non-table information +from the table collection will be read, leaving all tables with zero rows and no metadata +or schema. If the :c:macro:`TSK_LOAD_SKIP_REFERENCE_SEQUENCE` option is set, the table +collection is read without loading the reference sequence. When attempting to read from a +stream with multiple table collection definitions and either of these two options set, +the requested information from the first table collection will be read on the first call +to :c:func:`tsk_table_collection_loadf`, with subsequent calls leading to errors. **Options** Options can be specified by providing one or more of the following bitwise flags: -TSK_NO_INIT - Do not initialise this :c:type:`tsk_table_collection_t` before loading. -TSK_LOAD_SKIP_TABLES - Skip reading tables, and only load top-level information. -TSK_LOAD_SKIP_REFERENCE_SEQUENCE - Do not load reference sequence. - +- :c:macro:`TSK_NO_INIT` +- :c:macro:`TSK_LOAD_SKIP_TABLES` +- :c:macro:`TSK_LOAD_SKIP_REFERENCE_SEQUENCE` @endrst @param self A pointer to an uninitialised tsk_table_collection_t object @@ -3749,7 +3855,7 @@ section. Options can be specified by providing one or more of the following bitwise flags: -TSK_NO_CHECK_INTEGRITY +:c:macro:`TSK_NO_CHECK_INTEGRITY` Do not run integrity checks using :c:func:`tsk_table_collection_check_integrity` before sorting, potentially leading to a small reduction in execution time. This @@ -3757,7 +3863,6 @@ TSK_NO_CHECK_INTEGRITY guarantee reference integrity within the table collection. References to rows not in the table or bad offsets will result in undefined behaviour. - @endrst @param self A pointer to a tsk_table_collection_t object. @@ -3801,11 +3906,7 @@ tree sequence sortedness requirements. Options can be specified by providing one or more of the following bitwise flags: -TSK_SUBSET_KEEP_UNREFERENCED - By default, this will remove any unreferenced sites, populations, and - individuals. If this flag is provided, these will be retained, with - unreferenced individuals and populations at the end of the tables, in - their original order. +- :c:macro:`TSK_SUBSET_KEEP_UNREFERENCED` @endrst @@ -3824,47 +3925,26 @@ more details. A mapping from the node IDs in the table before simplification to their equivalent values after simplification can be obtained via the ``node_map`` argument. If this is non NULL, ``node_map[u]`` will contain the new ID for node ``u`` after simplification, -or ``TSK_NULL`` if the node has been removed. Thus, ``node_map`` must be an array of -at least ``self->nodes.num_rows`` :c:type:`tsk_id_t` values. +or :c:macro:`TSK_NULL` if the node has been removed. Thus, ``node_map`` must be an array +of at least ``self->nodes.num_rows`` :c:type:`tsk_id_t` values. The table collection will +always be unindexed after simplify successfully completes. + +.. note:: Migrations are currently not supported by simplify, and an error will + be raised if we attempt call simplify on a table collection with greater + than zero migrations. See ``_ **Options**: Options can be specified by providing one or more of the following bitwise flags: -TSK_SIMPLIFY_FILTER_SITES - Remove sites from the output if there are no mutations that reference them. -TSK_SIMPLIFY_FILTER_POPULATIONS - Remove populations from the output if there are no nodes or migrations that - reference them. -TSK_SIMPLIFY_FILTER_INDIVIDUALS - Remove individuals from the output if there are no nodes that reference them. -TSK_SIMPLIFY_REDUCE_TO_SITE_TOPOLOGY - Reduce the topological information in the tables to the minimum necessary to - represent the trees that contain sites. If there are zero sites this will - result in an zero output edges. When the number of sites is greater than zero, - every tree in the output tree sequence will contain at least one site. - For a given site, the topology of the tree containing that site will be - identical (up to node ID remapping) to the topology of the corresponding tree - in the input. -TSK_SIMPLIFY_KEEP_UNARY - By default simplify removes unary nodes (i.e., nodes with exactly one child) - along the path from samples to root. If this option is specified such unary - nodes will be preserved in the output. -TSK_SIMPLIFY_KEEP_INPUT_ROOTS - By default simplify removes all topology ancestral the MRCAs of the samples. - This option inserts edges from these MRCAs back to the roots of the input - trees. -TSK_SIMPLIFY_KEEP_UNARY_IN_INDIVDUALS - This acts like TSK_SIMPLIFY_KEEP_UNARY (and is mutually exclusive with that flag). It - keeps unary nodes, but only if the unary node is referenced from an individual. - -.. note:: Migrations are currently not supported by simplify, and an error will - be raised if we attempt call simplify on a table collection with greater - than zero migrations. See ``_ - -The table collection will always be unindexed after simplify successfully -completes. +- :c:macro:`TSK_SIMPLIFY_FILTER_SITES` +- :c:macro:`TSK_SIMPLIFY_FILTER_POPULATIONS` +- :c:macro:`TSK_SIMPLIFY_FILTER_INDIVIDUALS` +- :c:macro:`TSK_SIMPLIFY_REDUCE_TO_SITE_TOPOLOGY` +- :c:macro:`TSK_SIMPLIFY_KEEP_UNARY` +- :c:macro:`TSK_SIMPLIFY_KEEP_INPUT_ROOTS` +- :c:macro:`TSK_SIMPLIFY_KEEP_UNARY_IN_INDIVIDUALS` @endrst @param self A pointer to a tsk_table_collection_t object. @@ -3910,24 +3990,17 @@ 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: -TSK_SUBSET_NO_CHANGE_POPULATIONS - If this flag is provided, the population table will not be changed - in any way. - -TSK_SUBSET_KEEP_UNREFERENCED - If this flag is provided, then unreferenced sites, individuals, and populations - will not be removed. If so, the site and individual tables will not be changed, - and (unless TSK_SUBSET_NO_CHANGE_POPULATIONS is also provided) unreferenced - populations will be placed last, in their original order. - -.. note:: Migrations are currently not supported by susbset, and an error will - be raised if we attempt call subset on a table collection with greater - than zero migrations. +- :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. @@ -3947,7 +4020,7 @@ 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 TSK_NULL if the node is exclusive to ``other``. Nodes +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``. @@ -3961,24 +4034,16 @@ 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: -TSK_UNION_NO_CHECK_SHARED - By default, union checks that the portion of shared history between - ``self`` and ``other``, as implied by ``other_node_mapping``, are indeed - equivalent. It does so by subsetting both ``self`` and ``other`` on the - equivalent nodes specified in ``other_node_mapping``, and then checking for - equality of the subsets. -TSK_UNION_NO_ADD_POP - By default, all nodes new to ``self`` are assigned new populations. If this - option is specified, nodes that are added to ``self`` will retain the - population IDs they have in ``other``. - -.. 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. +- :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. @@ -4117,10 +4182,10 @@ than their nodes or their mutation parents, etcetera. To check if a set of tables fulfills the :ref:`requirements ` needed for a valid tree sequence, use -the TSK_CHECK_TREES option. When this method is called with TSK_CHECK_TREES, -the number of trees in the tree sequence is returned. Thus, to check for errors -client code should verify that the return value is less than zero. All other -options will return zero on success and a negative value on failure. +the :c:macro:`TSK_CHECK_TREES` option. When this method is called with +:c:macro:`TSK_CHECK_TREES`, the number of trees in the tree sequence is returned. Thus, +to check for errors client code should verify that the return value is less than zero. +All other options will return zero on success and a negative value on failure. More fine-grained checks can be achieved using bitwise combinations of the other options. @@ -4130,33 +4195,15 @@ other options. Options can be specified by providing one or more of the following bitwise flags: -TSK_CHECK_EDGE_ORDERING - Check edge ordering constraints for a tree sequence. -TSK_CHECK_SITE_ORDERING - Check that sites are in nondecreasing position order. -TSK_CHECK_SITE_DUPLICATES - Check for any duplicate site positions. -TSK_CHECK_MUTATION_ORDERING - Check contraints on the ordering of mutations. Any non-null - mutation parents and known times are checked for ordering - constraints. -TSK_CHECK_INDIVIDUAL_ORDERING - Check individual parents are before children, where specified. -TSK_CHECK_MIGRATION_ORDERING - Check migrations are ordered by time. -TSK_CHECK_INDEXES - Check that the table indexes exist, and contain valid edge - references. -TSK_CHECK_TREES - All checks needed to define a valid tree sequence. Note that - this implies all of the above checks. - -It is sometimes useful to disregard some parts of the data model -when performing checks: - -TSK_NO_CHECK_POPULATION_REFS - Do not check integrity of references to populations. This - can be safely combined with the other checks. +- :c:macro:`TSK_CHECK_EDGE_ORDERING` +- :c:macro:`TSK_CHECK_SITE_ORDERING` +- :c:macro:`TSK_CHECK_SITE_DUPLICATES` +- :c:macro:`TSK_CHECK_MUTATION_ORDERING` +- :c:macro:`TSK_CHECK_INDIVIDUAL_ORDERING` +- :c:macro:`TSK_CHECK_MIGRATION_ORDERING` +- :c:macro:`TSK_CHECK_INDEXES` +- :c:macro:`TSK_CHECK_TREES` +- :c:macro:`TSK_NO_CHECK_POPULATION_REFS` @endrst @param self A pointer to a tsk_table_collection_t object. diff --git a/c/tskit/trees.c b/c/tskit/trees.c index ebccacc1c8..df94cc29c8 100644 --- a/c/tskit/trees.c +++ b/c/tskit/trees.c @@ -408,7 +408,7 @@ tsk_treeseq_init( if (options & TSK_TAKE_OWNERSHIP) { self->tables = tables; if (tables->edges.options & TSK_TABLE_NO_METADATA) { - ret = TSK_CANT_TAKE_OWNERSHIP_NO_EDGE_METADATA; + ret = TSK_ERR_CANT_TAKE_OWNERSHIP_NO_EDGE_METADATA; goto out; } } else { diff --git a/c/tskit/trees.h b/c/tskit/trees.h index ca41e5178d..0693920263 100644 --- a/c/tskit/trees.h +++ b/c/tskit/trees.h @@ -62,8 +62,17 @@ extern "C" { /* For the edge diff iterator */ #define TSK_INCLUDE_TERMINAL (1 << 0) -/* Tree sequence init flags */ +/** +@defgroup API_FLAGS_TS_INIT_GROUP :c:func:`tsk_treeseq_init` specific flags. +@{ +*/ +/** +If specified edge indexes will be built and stored in the table collection +when the tree sequence is initialised. Indexes are required for a valid +tree sequence, and are not built by default for performance reasons. +*/ #define TSK_TS_INIT_BUILD_INDEXES (1 << 0) +/** @} */ // clang-format on @@ -139,28 +148,28 @@ typedef struct { */ tsk_id_t virtual_root; /** - @brief The parent of node u is parent[u]. Equal to TSK_NULL if node u is a - root or is not a node in the current tree. + @brief The parent of node u is parent[u]. Equal to ``TSK_NULL`` if node u is + a root or is not a node in the current tree. */ tsk_id_t *parent; /** - @brief The leftmost child of node u is left_child[u]. Equal to TSK_NULL + @brief The leftmost child of node u is left_child[u]. Equal to ``TSK_NULL`` if node u is a leaf or is not a node in the current tree. */ tsk_id_t *left_child; /** - @brief The rightmost child of node u is right_child[u]. Equal to TSK_NULL + @brief The rightmost child of node u is right_child[u]. Equal to ``TSK_NULL`` if node u is a leaf or is not a node in the current tree. */ tsk_id_t *right_child; /** - @brief The sibling to the left of node u is left_sib[u]. Equal to TSK_NULL - if node u has no siblings to its left. + @brief The sibling to the left of node u is left_sib[u]. Equal to + TSK_NULL if node u has no siblings to its left. */ tsk_id_t *left_sib; /** - @brief The sibling to the right of node u is right_sib[u]. Equal to TSK_NULL - if node u has no siblings to its right. + @brief The sibling to the right of node u is right_sib[u]. Equal to + ``TSK_NULL`` if node u has no siblings to its right. */ tsk_id_t *right_sib; /** @@ -205,7 +214,6 @@ typedef struct { immediately after we call ``tsk_tree_first(&tree)``, ``tree.index`` will be zero, and after we call ``tsk_tree_last(&tree)``, ``tree.index`` will be the number of trees - 1 (see :c:func:`tsk_treeseq_get_num_trees`) - When the tree is in the null state (immediately after initialisation, or after, e.g., calling :c:func:`tsk_tree_prev` on the first tree) the value of the ``index`` is -1. @@ -217,11 +225,13 @@ typedef struct { tsk_flags_t options; tsk_size_t root_threshold; const tsk_id_t *samples; - /* These are involved in the optional sample tracking; num_samples counts - * all samples below a give node, and num_tracked_samples counts those - * from a specific subset. By default sample counts are tracked and roots - * maintained. If TSK_NO_SAMPLE_COUNTS is specified, then neither sample - * counts or roots are available. */ + /* + These are involved in the optional sample tracking; num_samples counts + all samples below a give node, and num_tracked_samples counts those + from a specific subset. By default sample counts are tracked and roots + maintained. If ``TSK_NO_SAMPLE_COUNTS`` is specified, then neither sample + counts or roots are available. + */ tsk_size_t *num_samples; tsk_size_t *num_tracked_samples; /* These are for the optional sample list tracking. */ @@ -274,9 +284,8 @@ typedef struct { @brief Initialises the tree sequence based on the specified table collection. @rst -This method will copy the supplied table collection unless TSK_TAKE_OWNERSHIP is -specified. The table collection will be checked for integrity and index maps -built. +This method will copy the supplied table collection unless :c:macro:`TSK_TAKE_OWNERSHIP` +is specified. The table collection will be checked for integrity and index maps built. This must be called before any operations are performed on the tree sequence. See the :ref:`sec_c_api_overview_structure` for details on how objects @@ -284,17 +293,8 @@ are initialised and freed. **Options** -Options can be specified by providing one or more of the following bitwise -flags: - -TSK_TAKE_OWNERSHIP - By default the table collection is copied, however if this flag is - specified the table collection will be taken and owned with a reference - held by this tree sequence. The table collection will be free'd with - this tree sequence. - -TSK_BUILD_INDEXES - If specified edge indexes will be built and stored in the table collection +- :c:macro:`TSK_TS_INIT_BUILD_INDEXES` +- :c:macro:`TSK_TAKE_OWNERSHIP` (applies to the table collection). @endrst @param self A pointer to an uninitialised tsk_table_collection_t object. @@ -410,9 +410,9 @@ be supplied to avoid leaking memory. @endrst @param self A pointer to a tsk_treeseq_t object. -@param tables A pointer to a tsk_table_collection_t object. If the TSK_NO_INIT option - is specified, this must be an initialised table collection. If not, it must - be an uninitialised table collection. +@param tables A pointer to a tsk_table_collection_t object. If the TSK_NO_INIT +option is specified, this must be an initialised table collection. If not, it must be an +uninitialised table collection. @param options Bitwise option flags. @return Return 0 on success or a negative value on failure. */ @@ -676,7 +676,7 @@ const double *tsk_treeseq_get_breakpoints(const tsk_treeseq_t *self); @rst Returns an array of ids of sample nodes in this tree sequence. -I.e. nodes that have the TSK_NODE_IS_SAMPLE flag set. +I.e. nodes that have the :c:macro:`TSK_NODE_IS_SAMPLE` flag set. The array is owned by the tree sequence and should not be modified or free'd. @endrst @@ -690,7 +690,7 @@ const tsk_id_t *tsk_treeseq_get_samples(const tsk_treeseq_t *self); @rst Returns the location of each node in the list of samples or -TSK_NULL for nodes that are not samples. +:c:macro:`TSK_NULL` for nodes that are not samples. @endrst @param self A pointer to a tsk_treeseq_t object. @@ -1043,11 +1043,10 @@ valid for the full lifetime of the destination tree. **Options** -TSK_NO_INIT - Do **not** initialise the destination tree +- :c:macro:`TSK_NO_INIT` -If TSK_NO_INIT is not specified, options supplied to :c:func:`tsk_tree_init` -can be provided. +If :c:macro:`TSK_NO_INIT` is not specified, options for :c:func:`tsk_tree_init` +can be provided and will be passed on. @endrst @@ -1417,11 +1416,11 @@ int tsk_tree_get_branch_length( /** @brief Computes the sum of the lengths of all branches reachable from - the specified node, or from all roots if u=TSK_NULL. + the specified node, or from all roots if ``u=TSK_NULL``. @rst Return the total branch length in a particular subtree or of the -entire tree. If the specified node is TSK_NULL (or the +entire tree. If the specified node is :c:macro:`TSK_NULL` (or the :ref:`virtual root`) the sum of the lengths of all branches reachable from roots is returned. Branch length is defined as difference between the time @@ -1433,7 +1432,7 @@ leaf node is zero. @endrst @param self A pointer to a tsk_tree_t object. -@param u The root of the subtree of interest, or TSK_NULL to return the +@param u The root of the subtree of interest, or ``TSK_NULL`` to return the total branch length of the tree. @param ret_tbl A double pointer to store the returned total branch length. @return 0 on success or a negative value on failure. @@ -1465,7 +1464,7 @@ int tsk_tree_get_num_samples( @rst If two nodes do not share a common ancestor in the current tree, the MRCA -node is TSK_NULL. +node is :c:macro:`TSK_NULL`. @endrst @param self A pointer to a tsk_tree_t object. diff --git a/docs/c-api.rst b/docs/c-api.rst index 236c947680..d0f2fe0e4d 100644 --- a/docs/c-api.rst +++ b/docs/c-api.rst @@ -208,8 +208,6 @@ Common options .. doxygengroup:: GENERIC_FUNCTION_OPTIONS :content-only: -.. _sec_c_api_tables_api: - ********** Tables API ********** @@ -589,6 +587,65 @@ Miscellaneous functions .. doxygenfunction:: tsk_is_unknown_time +************************* +Function Specific Options +************************* + +------------- +Load and init +------------- +.. doxygengroup:: API_FLAGS_LOAD_INIT_GROUP + :content-only: + +-------------------------- +:c:func:`tsk_treeseq_init` +-------------------------- +.. doxygengroup:: API_FLAGS_TS_INIT_GROUP + :content-only: + +----------------------------------------------------------------------- +:c:func:`tsk_treeseq_simplify`, :c:func:`tsk_table_collection_simplify` +----------------------------------------------------------------------- +.. doxygengroup:: API_FLAGS_SIMPLIFY_GROUP + :content-only: + +---------------------------------------------- +:c:func:`tsk_table_collection_check_integrity` +---------------------------------------------- +.. doxygengroup:: API_FLAGS_CHECK_INTEGRITY_GROUP + :content-only: + +------------------------------------ +:c:func:`tsk_table_collection_clear` +------------------------------------ +.. doxygengroup:: API_FLAGS_CLEAR_GROUP + :content-only: + +----------------------------------- +:c:func:`tsk_table_collection_copy` +----------------------------------- +.. doxygengroup:: API_FLAGS_COPY_GROUP + :content-only: + +---------------------- +All equality functions +---------------------- +.. doxygengroup:: API_FLAGS_CMP_GROUP + :content-only: + +------------------------------------- +:c:func:`tsk_table_collection_subset` +------------------------------------- +.. doxygengroup:: API_FLAGS_SUBSET_GROUP + :content-only: + +------------------------------------ +:c:func:`tsk_table_collection_union` +------------------------------------ +.. doxygengroup:: API_FLAGS_UNION_GROUP + :content-only: + + ********* Constants ********* @@ -602,6 +659,15 @@ API Version .. _sec_c_api_error_codes: +---------------- +Common constants +---------------- + +.. doxygengroup:: GENERIC_CONSTANTS + :content-only: + +.. _sec_c_api_tables_api: + -------------- Generic Errors --------------