Effects

Genetic effect specifications. Effects are sampled once at architecture creation and remain fixed for all generations.

Effect specification classes for the new architecture system.

EffectSpec ABC and concrete implementations: - AdditiveEffects: univariate additive genetic effects - MultivariateEffects: multivariate correlated effects across traits - SparseEffects: sparse causal effects (subset of variants)

class xftsim.effect.EffectSpec(effects, standardized, variant_mask)[source]

Bases: ABC

Abstract base class for genetic effect specifications.

Effects are sampled once at architecture creation and fixed for all generations. The HaplotypeOperator picks the right matvec based on the standardized flag.

effects

Effect sizes — shape (m,) for univariate, (m, k) for multivariate.

Type:

np.ndarray

standardized

If True, effects are for standardized genotypes (use standardized_matvec).

Type:

bool

variant_mask

Boolean array indicating which variants are causal.

Type:

np.ndarray

Parameters:
property m: int

Total number of variants (causal + non-causal).

property m_causal: int

Number of causal variants.

property k: int

Number of traits (1 for univariate).

class xftsim.effect.AdditiveEffects(effects, standardized, variant_mask)[source]

Bases: EffectSpec

Univariate additive genetic effects.

All variants are causal (variant_mask is all-True). Effect sizes are stored as a 1D array of shape (m,).

Examples

Generate effects targeting h2 = 0.5 across 100 variants:

>>> eff = AdditiveEffects.from_h2(h2=0.5, m=100, seed=42)
>>> eff.m
100
>>> eff.k
1

Create from a known effect array:

>>> import numpy as np
>>> eff = AdditiveEffects.from_array(np.array([0.1, -0.2, 0.05]))
>>> eff.m
3
Parameters:
classmethod from_h2(h2, m, standardized=True, seed=None)[source]

Generate additive effects to target a given heritability.

Under standardized genotypes, Var(G) = sum(beta^2). We draw beta ~ N(0, h2/m) so E[sum(beta^2)] = h2.

Parameters:

  • h2 (float) – Target heritability.

  • m (int) – Number of variants (all causal).

  • standardized (bool) – Whether effects are for standardized genotypes.

  • seed (int, optional) – Random seed for reproducibility.

Return type:

AdditiveEffects

Returns:

AdditiveEffects

Parameters:
classmethod from_array(effects, standardized=True)[source]

Create from a pre-specified effect array.

Parameters:

  • effects (np.ndarray) – (m,) array of effect sizes.

  • standardized (bool) – Whether effects are for standardized genotypes.

Return type:

AdditiveEffects

Returns:

AdditiveEffects

Parameters:
class xftsim.effect.MultivariateEffects(effects, standardized, variant_mask)[source]

Bases: EffectSpec

Multivariate correlated effects across k traits.

Effect sizes are stored as a 2D array of shape (m, k) where k is the number of traits. All variants are causal.

Parameters:
classmethod from_h2_rg(h2, rg, m, standardized=True, seed=None)[source]

Generate multivariate effects from heritabilities and genetic correlation.

Parameters:

  • h2 (list) – Per-trait heritabilities [h2_1, h2_2, …].

  • rg (float) – Genetic correlation between traits.

  • m (int) – Number of variants (all causal).

  • standardized (bool) – Whether effects are for standardized genotypes.

  • seed (int, optional) – Random seed.

Return type:

MultivariateEffects

Returns:

MultivariateEffects

Parameters:
classmethod from_covg(covg, m, standardized=True, seed=None)[source]

Generate multivariate effects from a full genetic covariance matrix.

Parameters:

  • covg (np.ndarray) – (k, k) genetic covariance matrix. sum(beta @ beta.T) approx covg.

  • m (int) – Number of variants.

  • standardized (bool) – Whether effects are for standardized genotypes.

  • seed (int, optional) – Random seed.

Return type:

MultivariateEffects

Returns:

MultivariateEffects

Parameters:
classmethod from_array(effects, standardized=True)[source]

Create from a pre-specified (m, k) effect matrix.

Parameters:

  • effects (np.ndarray) – (m, k) array of effect sizes.

  • standardized (bool) – Whether effects are for standardized genotypes.

Return type:

MultivariateEffects

Returns:

MultivariateEffects

Parameters:
class xftsim.effect.SparseEffects(effects, standardized, variant_mask)[source]

Bases: EffectSpec

Sparse causal effects – only a subset of variants are causal.

Non-causal variants have zero effect sizes. The variant_mask indicates which variants are causal.

Parameters:
classmethod from_h2(h2, m, k_causal, standardized=True, seed=None)[source]

Generate sparse additive effects.

Parameters:

  • h2 (float) – Target heritability.

  • m (int) – Total number of variants.

  • k_causal (int) – Number of causal variants.

  • standardized (bool) – Whether effects are for standardized genotypes.

  • seed (int, optional) – Random seed.

Return type:

SparseEffects

Returns:

SparseEffects

Raises:

ValueError – If k_causal > m.

Parameters: