mate

Below is an auto-generated summary of the xftsim.mate submodule API.

This module contains functions and classes for implementing different mating regimes in the context of forward time genetics simulations.

Functions:

_solve_qap_ls: Private function that solves the Quadratic Assignment Problem using LocalSolver.

Classes:

MatingRegime: Base class for defining mating regimes. RandomMatingRegime: A class for implementing random mating. LinearAssortativeMatingRegime: A class for implementing linear assortative mating. KAssortativeMatingRegime: A class for implementing k-assortative mating. BatchedMatingRegime: A class for batching individuals to improve mating regime performance.

class xftsim.mate.BatchedMatingRegime(regime, max_batch_size)

Bases: MatingRegime

BatchedMatingRegime class that batches mating assignments, either for the sake of efficiency or to simulate stratification.

Parameters:

• regime (MatingRegime) – The mating regime object.

• max_batch_size (int) – Maximum size of each batch.

regime

The mating regime object.

Type:

MatingRegime

max_batch_size

Maximum size of each batch.

Type:

int

batch(haplotypes, phenotypes, control)

Split samples into batches.

mate(haplotypes, phenotypes, control)

Generate mating assignments in batches.

batch(haplotypes=None, phenotypes=None, control=None)

Split samples into batches.

Parameters:

• haplotypes (xarray.DataArray, optional) – Haplotypes array.

• phenotypes (xarray.DataArray, optional) – Phenotypes array.

• control (dict, optional) – Control parameters.

Returns:

• batches (list) – List of batches of samples.

• num_batches (int) – Number of batches.

mate(haplotypes=None, phenotypes=None, control=None)

Generate mating assignments in batches and merge into single assignment object.

Parameters:

• haplotypes (xarray.DataArray, optional) – Haplotypes array.

• phenotypes (xarray.DataArray, optional) – Phenotypes array.

• control (dict, optional) – Control parameters.

Returns:

mate_assignments (MateAssignment) – Mating assignments.

class xftsim.mate.GeneralAssortativeMatingRegime(component_index, cross_corr, offspring_per_pair=<xftsim.utils.ConstantCount object>, mates_per_female=<xftsim.utils.ConstantCount object>, female_offspring_per_pair='balanced', sex_aware=False, exhaustive=True, control={})

Bases: MatingRegime

A class that implements the general assortative mating regimes. I.e., matches two sets of individuals with K phenotypes to achieve an arbitrary K x K cross-mate cross-correlation structure.

Parameters:

• component_index (xft.index.ComponentIndex) – An object containing information about the components.

• cross_corr (ndarray) – The cross-correlation matrix of size K x K.

• offspring_per_pair (Union[int, xft.utils.VariableCount], optional) – The number of offspring per mating pair. Default is 1.

• mates_per_female (Union[int, xft.utils.VariableCount], optional) – The number of mates for each female. Default is 2.

• female_offspring_per_pair (Union[str, int, xft.utils.VariableCount], optional) – The number of offspring per mating pair for females. Default is ‘balanced’.

• sex_aware (bool, optional) – Whether to consider sex in mating pairs. Default is False.

• exhaustive (bool, optional) – Whether to enumerate all possible pairs. Default is True.

• control (dict, optional) – A dictionary of control parameters passed to LocalSolver. Defaults are as follows: nb_threads=4, time_limit=120, tolerance=1e-5, verbosity=1, time_between_displays=15

cross_corr

The cross-correlation matrix of size K x K.

Type:

ndarray

component_index

An object containing information about the components.

Type:

xft.index.ComponentIndex

K

The total number of components.

Type:

int

mate(haplotypes: xr.DataArray = None, phenotypes: xr.DataArray = None, control: dict = None) → xft.mate.MateAssignment:

Mate haplotypes and phenotypes based on the K-assortative mating regime.

mate(haplotypes=None, phenotypes=None, control={})

Mate haplotypes and phenotypes based on the K-assortative mating regime.

Parameters:

• haplotypes (xr.DataArray, optional) – The haplotype data to be mated. Default is None.

• phenotypes (xr.DataArray, optional) – The phenotype data to be mated. Default is None.

Returns:

assignment (xft.mate.MateAssignment) – The assignment of haplotypes to parents.

class xftsim.mate.LinearAssortativeMatingRegime(component_index, r=0, offspring_per_pair=<xftsim.utils.ConstantCount object>, mates_per_female=<xftsim.utils.ConstantCount object>, female_offspring_per_pair='balanced', sex_aware=False, exhaustive=True)

Bases: MatingRegime

A linear assortative mating regime that performs mate selection based on a specified component index. Speifically, individuals are mated such that the cross-mate correlations across all specified components are equal to r. This reflects mating on a linear combination of phenotypes and does not generalize to many cross-mate correlation stuctures observed in practice, but is more efficient.

Parameters:

• component_index (xft.index.ComponentIndex) – The component index used to select mating pairs based on the correlation between the phenotype values.

• r (float, optional) – The correlation coefficient, a value between -1 and 1. Defaults to 0.

• offspring_per_pair (Union[int, xft.utils.VariableCount], optional) – The number of offspring per pair. If int, it will be converted to a ConstantCount object. Defaults to 1.

• mates_per_female (Union[int, xft.utils.VariableCount], optional) – The number of mates per female. If int, it will be converted to a ConstantCount object. Defaults to 1.

• female_offspring_per_pair (Union[str, int, xft.utils.VariableCount], optional) – The number of female offspring per mating pair. If ‘balanced’, the number of females is randomly selected for each pair to balance the sex ratio. If int, it will be converted to a ConstantCount object. Defaults to ‘balanced’.

• sex_aware (bool, optional) – If True, only mating pairs with different sex are allowed. Defaults to False.

• exhaustive (bool, optional) – If True, all possible mating pairs will be enumerated. If False, pairs will be randomly selected. Defaults to True.

Raises:

AssertionError – If r is not between -1 and 1. If the correlation r is not feasible for the number of phenotypes in the component index.

TODO: see also

mate(haplotypes=None, phenotypes=None, control=None)

Mate individuals.

Parameters:

• haplotypes (xarray.DataArray, optional) – The haplotypes of the individuals, by default None.

• phenotypes (xarray.DataArray, optional) – The phenotypes of the individuals, by default None.

• control (dict, optional) – The mating control parameters, by default None.

Returns:

MateAssignment – The mate assignment result.

class xftsim.mate.MateAssignment(generation, maternal_sample_index, paternal_sample_index, previous_generation_sample_index, n_offspring_per_pair, n_females_per_pair, sex_aware=False)

Bases: object

Represents a mate assignment for a given generation of individuals.

Parameters:

• generation (int) – The generation number.

• maternal_sample_index (xft.index.SampleIndex) – The sample index for the maternal individuals.

• paternal_sample_index (xft.index.SampleIndex) – The sample index for the paternal individuals.

• previous_generation_sample_index (xft.index.SampleIndex) – The sample index for the previous generation.

• n_offspring_per_pair (NDArray[Shape[``”*”``], Int64]) – An array containing the number of offspring per mating pair.

• n_females_per_pair (NDArray[Shape[``”*”``], Int64]) – An array containing the number of female offspring per mating pair.

• sex_aware (bool, optional (default=False)) – Whether the mate assignment is sex-aware.

get_mate_phenotypes(phenotypes, component_index=None, full=True)

Retrieves mate phenotypes based on the given phenotypes data.

Parameters:

• phenotypes (xr.DataArray) – The phenotypes data array.

• component_index (xft.index.ComponentIndex, optional) – The component index for the phenotypes data array.

• full (bool) – Ignore component_index and get all components.

Returns:

pd.DataFrame – A DataFrame containing the mate phenotypes.

get_mating_frame()

Constructs a DataFrame containing mate phenotypes regardless of reproductive success.

Returns:

pd.DataFrame – A DataFrame containing mating information.

get_reproduction_frame()

Constructs a DataFrame containing information relating to mates and offspring.

Returns:

pd.DataFrame – A DataFrame containing reproduction information.

property is_constant_population

TODO property to determine if the population is constant or not.

Returns:

bool – True if the population is constant, False otherwise.

property maternal_integer_index

The integer index for the maternal individuals.

Returns:

np.ndarray – An array containing the integer index for the maternal individuals.

property n_females

The total number of female offspring.

Returns:

int – The total number of female offspring.

property n_males

The total number of male offspring.

Returns:

int – The total number of male offspring.

property n_reproducing_pairs

The total number of reproducing pairs.

Returns:

int – The total number of reproducing pairs.

property n_total_offspring

The total number of offspring.

Returns:

int – The total number of offspring.

property offspring_fids

The family identifiers for the offspring.

Returns:

np.ndarray – An array containing the family identifiers for the offspring.

property offspring_iids

The unique identifiers for the offspring.

Returns:

np.ndarray – An array containing the unique identifiers for the offspring.

property offspring_sample_index

The sample index for the offspring.

Returns:

xft.index.SampleIndex – The sample index for the offspring.

property offspring_sex

The sex of the offspring.

Returns:

np.ndarray – An array containing the sex of the offspring.

property paternal_integer_index

The integer index for the paternal individuals.

Returns:

np.ndarray – An array containing the integer index for the paternal individuals.

static reduce_merge(assignments)

Merges a list of MateAssignment objects into a single MateAssignment object.

Parameters:

assignments (Iterable) – An iterable of MateAssignment objects to be merged.

Returns:

MateAssignment – A new MateAssignment object resulting from the merge of the input assignments.

property reproducing_maternal_index

The maternal index for reproducing individuals.

Returns:

xft.index.SampleIndex – The maternal index for reproducing individuals.

property reproducing_paternal_index

The paternal index for reproducing individuals.

Returns:

xft.index.SampleIndex – The paternal index for reproducing individuals.

trio_view(pheno_parental, pheno_offspring)

Returns an array with the phenotypes of offspring, followed by the phenotypes of their parents in the same order as the order of offspring in this MateAssignment.

Parameters:

• pheno_parental (xr.DataArray) – An xarray DataArray containing the phenotypes of the parents.

• pheno_offspring (xr.DataArray) – An xarray DataArray containing the phenotypes of the offspring.

Returns:

np.ndarray – An array with the phenotypes of offspring, followed by the phenotypes of their parents.

update_pedigree(pedigree)

class xftsim.mate.MatingRegime(mateFunction=None, offspring_per_pair=<xftsim.utils.ConstantCount object>, mates_per_female=<xftsim.utils.ConstantCount object>, female_offspring_per_pair='balanced', sex_aware=False, exhaustive=True, component_index=None, haplotypes=False)

Bases: object

A class for defining a mating regime to simulate the reproductive behavior of a population.

Parameters:

• mateFunction (Callable, optional) – A function that specifies how the mating process is carried out. Default is None.

• offspring_per_pair (Union[Callable, int, xft.utils.VariableCount], optional) – The number of offspring per mating pair. This can be a callable function, an integer, or a VariableCount object. Default is xft.utils.ConstantCount(1).

• mates_per_female (Union[Callable, int, xft.utils.VariableCount], optional) – The number of mating partners each female has. This can be a callable function, an integer, or a VariableCount object. Default is xft.utils.ConstantCount(1).

• female_offspring_per_pair (Union[Callable, str, int, xft.utils.VariableCount], optional) – The number of female offspring per mating pair. This can be a callable function, a string, an integer, or a VariableCount object. If set to ‘balanced’, the number of female offspring will be randomly assigned from a balanced range (0, …, total_offspring). Default is ‘balanced’.

• sex_aware (bool, optional) – Whether the mating process should take sex into account. If True, females and males will be paired up based on their sex. If False, the pairs will be randomly assigned. Default is False.

• exhaustive (bool, optional) – Whether the mating pairs should be enumerated exhaustively or randomly. If True, all possible pairings will be enumerated before repeating. If False, the pairings will be randomly assigned with replacement. Default is True.

• component_index (xft.index.ComponentIndex, optional) – Which phenotype components (if any) are used in assigning mates

• haplotypes (bool, optional) – Flag indeicating if haplotype data is used to assign mates (defaults to False)

sex_aware

Whether the mating process should take sex into account.

Type:

bool

offspring_per_pair

The number of offspring per mating pair.

Type:

Union[Callable, int, xft.utils.VariableCount]

mates_per_female

The number of mating partners each female has.

Type:

Union[Callable, int, xft.utils.VariableCount]

female_offspring_per_pair

The number of female offspring per mating pair.

Type:

Union[Callable, str, int, xft.utils.VariableCount]

exhaustive

Whether the mating pairs should be enumerated exhaustively or randomly.

Type:

bool

mateFunction

A function that specifies how the mating process is carried out.

Type:

Callable

expected_offspring_per_pair

The expected number of offspring per mating pair.

Type:

float

expected_mates_per_female

The expected number of mating partners each female has.

Type:

float

expected_female_offspring_per_pair

The expected number of female offspring per mating pair.

Type:

float

population_growth_factor

The population growth factor.

Type:

float

get_potential_mates(haplotypes: xr.DataArray = None, phenotypes: xr.DataArray = None)

Returns the potential female and male mating partners based on the sex awareness parameter.

enumerate_assignment(female_indices: NDArray, male_indices: NDArray, haplotypes: xr.DataArray = None, phenotypes: xr.DataArray = None) → MateAssignment

Enumerates the mating assignments.

mate(haplotypes: xr.DataArray = None, phenotypes: xr.DataArray = None, control: dict = None) → MateAssignment

Calls the mateFunction to perform the mating process.

property dependency_graph

property dependency_graph_edges

draw_dependency_graph(node_color='none', node_size=1500, arrowsize=7, font_size=6, margins=0.1, **kwargs)

enumerate_assignment(female_indices, male_indices, haplotypes=None, phenotypes=None)

Enumerate the mate assignments.

Parameters:

• female_indices (NDArray) – The indices of the females to mate.

• male_indices (NDArray) – The indices of the males to mate.

• haplotypes (xr.DataArray) – The haplotypes to use for mating.

• phenotypes (xr.DataArray) – The phenotypes to use for mating.

Returns:

MateAssignment – The mate assignments.

property expected_female_offspring_per_pair

Get the expected female offspring per pair.

Returns:

float – The expected female offspring per pair.

Raises:

NotImplementedError – If the female offspring count is not an integer or a VariableCount.

property expected_mates_per_female

Get the expected mates per female.

Returns:

float – The expected mates per female.

Raises:

NotImplementedError – If the mates count is not an integer or a VariableCount.

property expected_offspring_per_pair

Get the expected offspring per pair.

Returns:

float – The expected offspring per pair.

Raises:

NotImplementedError – If the offspring count is not an integer or a VariableCount.

get_potential_mates(haplotypes=None, phenotypes=None)

Return potential mating pairs.

Parameters:

• haplotypes (xr.DataArray) – The haplotypes to use for mating.

• phenotypes (xr.DataArray) – The phenotypes to use for mating.

Returns:

(NDArray, NDArray) – The potential female and male mating indices.

mate(haplotypes=None, phenotypes=None, control=None)

Mate individuals.

Parameters:

• haplotypes (xarray.DataArray, optional) – The haplotypes of the individuals, by default None.

• phenotypes (xarray.DataArray, optional) – The phenotypes of the individuals, by default None.

• control (dict, optional) – The mating control parameters, by default None.

Returns:

MateAssignment – The mate assignment result.

property mateFunction

property population_growth_factor

Get the population growth factor.

Returns:

float – The population growth factor.

class xftsim.mate.RandomMatingRegime(offspring_per_pair=<xftsim.utils.ConstantCount object>, mates_per_female=<xftsim.utils.ConstantCount object>, female_offspring_per_pair='balanced', sex_aware=False, exhaustive=True)

Bases: MatingRegime

A mating regime that randomly pairs individuals and produces offspring with balanced numbers of males and females.

Parameters:

• offspring_per_pair (xft.utils.VariableCount, optional) – Number of offspring produced per mating pair, by default xft.utils.ConstantCount(1)

• mates_per_female (xft.utils.VariableCount, optional) – Number of males that mate with each female, by default xft.utils.ConstantCount(1)

• female_offspring_per_pair (Union[str, xft.utils.VariableCount], optional) – The number of female offspring per mating pair. If “balanced”, the number is balanced with the number of male offspring. By default, “balanced”.

• sex_aware (bool, optional) – If True, randomly paired individuals are selected so that there is an equal number of males and females. Otherwise, random pairing is performed. By default, False.

• exhaustive (bool, optional) – If True, perform exhaustive enumeration of potential mates. If False, perform random sampling. By default, True.

mate(haplotypes=None, phenotypes=None, control=None)

Mate individuals randomly with balanced numbers of males and females.

Parameters:

• haplotypes (xr.DataArray, optional) – Array containing haplotypes, by default None

• phenotypes (xr.DataArray, optional) – Array containing phenotypes, by default None

• control (dict, optional) – Control dictionary, by default None

Returns:

MateAssignment – An object containing the maternal and paternal sample indices, the number of offspring per pair, and the number of female offspring per pair.