mate

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

New mate assignment and mating regimes for the refactored simulation loop.

MateAssignment: dataclass linking offspring to parents by index. RandomMating: shuffles and pairs individuals to produce offspring. LinearAssortativeMating: rank-order pairing on a phenotypic composite. GeneralAssortativeMating: arbitrary K x K cross-mate correlation via QAP (Hexaly). BatchedMating: wraps any mating regime, splitting individuals into batches.

class xftsim.mate.MateAssignment(offspring_samples, maternal_idx, paternal_idx)[source]

Bases: object

Links offspring to parents via integer indices into the parent generation.

Parameters:

  • offspring_samples (SampleMeta) – Metadata for the offspring (unique iids, fids, sex, generation).

  • maternal_idx (np.ndarray) – (n_offspring,) indices into the parent generation for mothers.

  • paternal_idx (np.ndarray) – (n_offspring,) indices into the parent generation for fathers.

Parameters:
offspring_samples: SampleMeta
maternal_idx: ndarray
paternal_idx: ndarray
property n_offspring: int

Number of offspring in this assignment.

class xftsim.mate.RandomMating(offspring_per_pair=2)[source]

Bases: object

Random mating: shuffle individuals, pair them up, produce offspring.

Individuals are separated by sex (0=female, 1=male), each group is shuffled, and min(n_female, n_male) pairs are formed. Each pair produces offspring_per_pair offspring with sequential IIDs, pair-based FIDs, and alternating sex.

Parameters:

offspring_per_pair (int) – Number of offspring per mating pair. Default 2.

Parameters:

offspring_per_pair (int)

Examples

>>> from xftsim.struct import SampleMeta
>>> import numpy as np
>>> samples = SampleMeta(iid=np.arange(10))
>>> mating = RandomMating(offspring_per_pair=2)
>>> assignment = mating.mate(samples, rng=np.random.RandomState(0))
>>> assignment.n_offspring
10
Parameters:

offspring_per_pair (int)

mate(samples, rng=None, phenotypes=None)[source]

Produce a mate assignment from the current generation.

Algorithm: - Separate individuals by sex (0=female, 1=male). - Shuffle each group independently. - Pair up: min(n_female, n_male) pairs. - Each pair produces offspring_per_pair offspring. - Offspring get sequential iids, pair-based fids, alternating sex.

Parameters:

  • samples (SampleMeta) – Current generation’s sample metadata.

  • rng (np.random.RandomState, optional) – Random state for reproducibility.

  • phenotypes (PhenotypeArray, optional) – Ignored by RandomMating (accepted for interface compatibility).

Return type:

MateAssignment

Returns:

MateAssignment

Parameters:
class xftsim.mate.LinearAssortativeMating(component_names, r=0.0, offspring_per_pair=2)[source]

Bases: object

Assortative mating via rank-order pairing on a phenotypic composite.

Algorithm:

  1. Standardize each component in component_names to mean 0, sd 1.

  2. Compute composite = average of standardized components.

  3. Mating score = sqrt(|r|) * composite + sqrt(1-|r|) * noise. If r < 0, negate the composite for one sex (disassortative).

  4. Sort each sex by mating score, pair in rank order.

Parameters:

  • component_names (list[str]) – Phenotype component names to use for assortment.

  • r (float) – Target spousal correlation. -1 < r < 1. 0 = random mating.

  • offspring_per_pair (int) – Number of offspring per mating pair.

Parameters:
mate(samples, rng=None, phenotypes=None)[source]

Produce a mate assignment with phenotypic assortment.

Falls back to random mating if r == 0 or phenotypes is None.

Parameters:

  • samples (SampleMeta) – Current generation’s sample metadata.

  • rng (np.random.RandomState, optional) – Random state for reproducibility.

  • phenotypes (PhenotypeArray, optional) – Current phenotypes (needed for assortment scoring).

Return type:

MateAssignment

Returns:

MateAssignment

Parameters:
class xftsim.mate.GeneralAssortativeMating(component_names, cross_corr, offspring_per_pair=2, solver_params=None)[source]

Bases: object

Assortative mating with an arbitrary K x K cross-mate correlation target.

Uses the Hexaly Optimizer to solve the Quadratic Assignment Problem: find a permutation P* of one sex that minimizes ||Y'[P*] Z / n  -  Omega||_F where Omega is the target cross-mate cross-trait correlation matrix.

Parameters:

  • component_names (list[str]) – Phenotype component names (keys in PhenotypeArray) to use. Order must match the rows/columns of cross_corr.

  • cross_corr (np.ndarray) – (K, K) target cross-mate correlation matrix. cross_corr[i, j] is the desired correlation between component i in females and component j in males.

  • offspring_per_pair (int) – Number of offspring per mating pair.

  • solver_params (dict, optional) – Hexaly solver parameters. Keys: nb_threads, time_limit, tolerance, verbosity, time_between_displays, termination_interval.

Parameters:
mate(samples, rng=None, phenotypes=None)[source]

Produce a mate assignment achieving the target cross-mate correlations.

Parameters:

  • samples (SampleMeta) – Current generation’s sample metadata.

  • rng (np.random.RandomState, optional) – Random state for reproducibility (used only for offspring metadata).

  • phenotypes (PhenotypeArray) – Current phenotypes. Must contain all component_names.

Return type:

MateAssignment

Returns:

MateAssignment

Parameters:
class xftsim.mate.BatchedMating(regime, max_batch_size=1000)[source]

Bases: object

Wraps any mating regime, splitting individuals into batches.

Randomly partitions individuals into batches of at most max_batch_size individuals, runs the inner regime on each batch independently, then merges the resulting mate assignments.

This is essential for GeneralAssortativeMating at large n, where the QAP solver scales quadratically. For example, n=8000 with max_batch_size=1000 yields 8 independent QAP solves of 500 pairs each, rather than one solve of 4000 pairs.

Parameters:

  • regime – Any mating regime with a .mate(samples, rng, phenotypes) method.

  • max_batch_size (int) – Maximum number of individuals (not pairs) per batch.

Parameters:

max_batch_size (int)

mate(samples, rng=None, phenotypes=None)[source]
Parameters:
Return type:

MateAssignment