These functions search the simulation data for the genotype that matches a particular known piece of information, eg a name, id, global index, or set of parents. More...

Collaboration diagram for Data Searching Functions:

Functions
char *	gsc_get_name_of_id (const gsc_AlleleMatrix *start, const gsc_PedigreeID id)
	Returns the name of the genotype with a given id. More...

int	gsc_get_parents_of_id (const gsc_AlleleMatrix *start, const gsc_PedigreeID id, gsc_PedigreeID output[static 2])
	Saves the ids of the parents of a genotype with a particular id to the output array `output`. More...

void	gsc_get_ids_of_names (const gsc_AlleleMatrix start, const size_t n_names, const char names, gsc_PedigreeID output)
	Search for genotypes with certain names in a linked list of gsc_AlleleMatrix and save the ids of those names. More...

unsigned int	gsc_get_index_of_child (const gsc_AlleleMatrix *start, const gsc_PedigreeID parent1id, const gsc_PedigreeID parent2id)
	Search for a genotype with parentage matching two given parent ids in a linked list of gsc_AlleleMatrix, and return its index. More...

unsigned int	gsc_get_index_of_name (const gsc_AlleleMatrix start, const char name)
	Search for a genotype with a particular name in a linked list of gsc_AlleleMatrix, and return its global index in the list. More...

gsc_PedigreeID	gsc_get_id_of_index (const gsc_AlleleMatrix *start, const unsigned int index)
	Get the id of a genotype by its index. More...

char *	gsc_get_genes_of_index (const gsc_AlleleMatrix *start, const unsigned int index)
	Get the alleles of a genotype by its index. More...

Detailed Description

These functions search the simulation data for the genotype that matches a particular known piece of information, eg a name, id, global index, or set of parents.

Depending on the size of the simulation, they may not be fast.

Function Documentation

◆ gsc_get_genes_of_index()

char * gsc_get_genes_of_index	(	const gsc_AlleleMatrix *	start,
		const unsigned int	index
	)

Get the alleles of a genotype by its index.

The index is assumed to be 0-based, starting at the first entry of start and continuing through the linked list to which start belongs.

Parameters

start	Pointer to the first of a linked list of gsc_AlleleMatrixes in which to locate the id at a particular index.
index	the index of the target. It is assumed to start at 0 at the start of the matrix in `start` and be incremented up until the last entry in the matrix of the last entry in the linked list.

Returns: the alleles of the genotype that has idnex index, as a copy of the pointer to the heap memory where the genotype is saved (so don't free the pointer returned from this function). It points to a sequence of characters, ordered according to the markers in the gsc_SimData to which the gsc_AlleleMatrix belongs. If there is an error in locating the genotype, it returns NULL instead.

Definition at line 2653 of file sim-operations.c.

Here is the caller graph for this function:

◆ gsc_get_id_of_index()

gsc_PedigreeID gsc_get_id_of_index	(	const gsc_AlleleMatrix *	start,
		const unsigned int	index
	)

Get the id of a genotype by its index.

The index is assumed to be 0-based, starting at the first entry of start and continuing through the linked list to which start belongs. Exits if the linked list does not contain that index.

Parameters

start	Pointer to the first of a linked list of gsc_AlleleMatrixes in which to locate the id at a particular index.
index	the index of the target. It is assumed to start at 0 at the start of the matrix in `start` and be incremented up until the last entry in the matrix of the last entry in the linked list.

Returns: the lifetime-unique id of the genotype found at that index.

Definition at line 2614 of file sim-operations.c.

Here is the caller graph for this function:

◆ gsc_get_ids_of_names()

void gsc_get_ids_of_names	(	const gsc_AlleleMatrix *	start,
		const size_t	n_names,
		const char **	names,
		gsc_PedigreeID *	output
	)

Search for genotypes with certain names in a linked list of gsc_AlleleMatrix and save the ids of those names.

Exits if any name cannot be found.

This function must check every name in the linked list for matches, so will be relatively slow.

Parameters

start	Pointer to the first of a linked list of gsc_AlleleMatrixes in which the genotype with the provided id is assumed to be found.
n_names	the length of the array of names which are being sought.
names	an array of strings/names whose ids we want to find. It must have at least [n_names] entries.
output	pointer to an array with at least enough space to store [n_names] PedigreeIDs. The ID corresponding to each name in `names` is saved at the corresponding index in `output` when it is found by the function.

Definition at line 2483 of file sim-operations.c.

Here is the caller graph for this function:

◆ gsc_get_index_of_child()

unsigned int gsc_get_index_of_child	(	const gsc_AlleleMatrix *	start,
		const gsc_PedigreeID	parent1id,
		const gsc_PedigreeID	parent2id
	)

Search for a genotype with parentage matching two given parent ids in a linked list of gsc_AlleleMatrix, and return its index.

Exits if such a child cannot be found.

This function must check every genotype in the linked list for matches, so will be relatively slow.

Parameters

start	Pointer to the first of a linked list of gsc_AlleleMatrixes in which the child is assumed to be found.
parent1id	one of the parents of the genotype must have this id.
parent2id	the other parent of the genotype must have this id.

Returns: the index (0-based, starting at the start of start) of the first sequentially located genotype whose parents match the two parent ids provided, or GSC_NA_GLOBALX if no child of those parents could be found

Definition at line 2537 of file sim-operations.c.

Here is the caller graph for this function:

◆ gsc_get_index_of_name()

unsigned int gsc_get_index_of_name	(	const gsc_AlleleMatrix *	start,
		const char *	name
	)

Search for a genotype with a particular name in a linked list of gsc_AlleleMatrix, and return its global index in the list.

This function must check every genotype in the linked list for matches, so will be relatively slow.

Parameters

start	Pointer to the first of a linked list of gsc_AlleleMatrixes in which the genotype is assumed to be found.
name	a string to match to the name of the target

Returns: the index (0-based, starting at the start of start) of the first sequentially located genotype whose name is the same as the provided name, or GSC_NA_GLOBALX if the name could not be found.

Definition at line 2577 of file sim-operations.c.

Here is the caller graph for this function:

◆ gsc_get_name_of_id()

char * gsc_get_name_of_id	(	const gsc_AlleleMatrix *	start,
		const gsc_PedigreeID	id
	)

Returns the name of the genotype with a given id.

The function uses a bisection search on the gsc_AlleleMatrix where it should be found. Searching by id is therefore fast.

See also: gsc_get_from_ordered_pedigree_list()

This function assumes that ids are never reshuffled in the gsc_SimData. This is true as long as gsc_condense_allele_matrix's process of moving genotypes while retaining their order is the only genotype-rearranging function in use. This function's algorithm will need to be revisited if different genotype-rearranging processes are implemented.

Parameters

start	Pointer to the first of a linked list of gsc_AlleleMatrixes in which the genotype with the provided id is assumed to be found.
id	the id of the genotype whose name is sought

Returns: the name of the genotype that has id id, as a copy of the pointer to the heap memory where the name is saved (so don't free the pointer returned from this function). Returns NULL if the ID does not exist. Note the return value might also be NULL if the genotype of this ID has no name.

Definition at line 2356 of file sim-operations.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ gsc_get_parents_of_id()

int gsc_get_parents_of_id	(	const gsc_AlleleMatrix *	start,
		const gsc_PedigreeID	id,
		gsc_PedigreeID	output[static 2]
	)

Saves the ids of the parents of a genotype with a particular id to the output array output.

The function uses a bisection search on the gsc_AlleleMatrix where it should be found. Searching by id is therefore fast.

See also: gsc_get_from_ordered_pedigree_list()

This function assumes that ids are never reshuffled in the gsc_SimData. This is true as long as gsc_condense_allele_matrix's process of moving genotypes while retaining their order is the only genotype-rearranging function in use. This function's algorithm will need to be revisited if different genotype-rearranging processes are implemented.

Parameters

start	Pointer to the first of a linked list of gsc_AlleleMatrixes in which the genotype with the provided id is assumed to be found.
id	the id of the genotype whose parents are sought
output	An array which the calling function can access where this function will put its results.

Returns: 0 when the id is successfully identified and at least one parent's id is known, 1 if neither parent is known, and 2 if the ID passed in does not exist. The ids of both parents if at least one parent is known/nonzero are saved to the array output.

Definition at line 2422 of file sim-operations.c.

Here is the call graph for this function:

Here is the caller graph for this function: