qdiv.model.simulate module

qdiv.model.simulate.simulate_community(size=100, communities=1, *, sigma=1.0, mean=0.0, c_prefix='Comm', species_prefix='OTU', sort=True, random_state=None)[source]

Simulate communities with log-normal species abundance distributions.

Parameters:

  • size (int, default=100) – Number of species in each community.

  • communities (int, default=1) – Number of communities to simulate.

  • sigma (float, default=1.0) – Standard deviation of the log-normal distribution. Low values yield more even communities; high values yield more dominance.

  • mean (float, default=0.0) – Mean of the log-normal distribution.

  • c_prefix (str, default='Comm') – Prefix for community (column) names.

  • species_prefix (str, default='OTU') – Prefix for species (row) names.

  • sort (bool, default=True) – If True, sort species from most to least abundant.

  • random_state (int, np.random.Generator, or None) – Random seed or generator for reproducibility.

Returns:

Simulated abundance table (species x communities). Rows = species, columns = communities.

Return type:

pandas.DataFrame

qdiv.model.simulate.community_sample(community, n=10000, random_state=None)[source]

Draw a multinomial sample from a community abundance distribution.

Parameters:

  • community (pd.DataFrame) – DataFrame of species abundances (species x communities). Each column is a community; values are relative or absolute abundances.

  • n (int, default=10000) – Number of individuals to sample per community.

  • random_state (int, np.random.Generator, or None) – Random seed or generator for reproducibility.

Returns:

DataFrame of sampled counts (species x communities). Returns None if input is not a DataFrame.

Return type:

pandas.DataFrame or None

qdiv.model.simulate.simulate_assembly(community, immigrants, fitness, selection=1.0, dispersal=1.0, max_iter=1000, tol=0.001, noise_level=0.0, interdependence=None, random_state=None, verbose=False)[source]

Simulate community assembly from local and immigrant pools, with optional stochastic noise and species interdependence (competition/facilitation).

Parameters:

  • community (pd.DataFrame) – Initial community abundance table (species x communities).

  • immigrants (pd.DataFrame) – Immigrant pool abundance table (same shape as community).

  • fitness (pd.DataFrame) – Fitness values for each species in each community (same shape).

  • selection (float, default=1.0) – Relative weight of selection (fitness) in assembly.

  • dispersal (float, default=1.0) – Relative weight of dispersal (immigration) in assembly.

  • max_iter (int, default=1000) – Maximum number of assembly iterations.

  • tol (float, default=1e-3) – Convergence tolerance (sum of squared changes).

  • noise_level (float, default=0.0) – Standard deviation of Gaussian noise added to abundance updates (as a fraction of abundance).

  • interdependence (pd.DataFrame or None) – Square matrix (species x species) of interaction coefficients. Positive values = facilitation, negative = competition. Diagonal is typically zero or negative (self-limitation).

  • random_state (int, np.random.Generator, or None) – Random seed or generator for reproducibility.

  • verbose (bool, default=False) – If True, print progress at each iteration.

Returns:

  • final_community (pandas.DataFrame) – Assembled community abundance table (species x communities).

  • n_iter (int) – Number of iterations performed.

  • converged (bool) – True if convergence was reached within max_iter, False otherwise.

Return type:

Tuple[DataFrame, int, bool]

qdiv.model.simulate.generate_interdependence_matrix(n_species, interaction_strength=1.0, positive_fraction=0.5, symmetric=False, diagonal=0.0, species_prefix='OTU', random_state=None)[source]

Generate a random species interdependence (interaction) matrix.

Parameters:

  • n_species (int) – Number of species (matrix will be n_species x n_species).

  • interaction_strength (float, default=1.0) – Maximum absolute value for interaction coefficients.

  • positive_fraction (float, default=0.5) – Fraction of off-diagonal interactions that are positive (facilitative). The rest will be negative (competitive).

  • symmetric (bool, default=False) – If True, matrix will be symmetric (A_ij = A_ji).

  • diagonal (float, default=0.0) – Value to set on the diagonal (e.g., 0 for no self-interaction, -1 for self-limitation).

  • species_prefix (str, default='OTU') – Prefix for species (row) names.

  • random_state (int, np.random.Generator, or None) – Random seed or generator for reproducibility.

Returns:

Interaction matrix (species x species).

Return type:

pandas.DataFrame

qdiv.model.simulate.make_block_tree_df(k_per_level, *, branch_length=1.0, root_name='Root', leaf_prefix='OTU', internal_prefix='in')[source]

Generate a block tree where branching factor varies with depth. Compatible with phylo_utils (nodes, parent, branchL, leaves, dist_to_root).

Parameters:

  • k_per_level (sequence of int) – k_per_level[level] = number of children created at this depth. Length of k_per_level = total depth.

  • branch_length (float | Sequence[float] | Callable[[int, str, int], float]) – float → same length everywhere sequence[len=depth] → branch_length[level] callable(level, parent_name, child_index) → full control

  • root_name (str)

  • leaf_prefix (str)

  • internal_prefix (str)

Return type:

DataFrame

qdiv.model.simulate.make_beta_splitting_tree_df(n_leaves, beta, *, branch_length='ultrametric', root_name='Root', leaf_prefix='OTU', internal_prefix='in', random_state=None)[source]

Aldous β-splitting binary tree, returned as a DataFrame compatible with your phylo utils.

Columns:

nodes (str), leaves (set[str]), branchL (float), parent (str|None), dist_to_root (float)

Parameters:

  • n_leaves (int) – Number of tips (>= 1).

  • beta (float) – β parameter; requires beta > -1 so Beta(β+1, β+1) is defined. Larger β → more balanced; β -> -1+ → more comb-like.

  • branch_length (float | Sequence[float] | Callable[[int, str, int], float] | str) – “ultrametric” (default) or: - float: fixed length for all edges. - sequence[len = max_level+1] indexed by parent level (0=root). - callable(level, parent_name, child_index)->float for full control.

  • root_name (str)

  • leaf_prefix (str)

  • internal_prefix (str)

  • random_state (int | None)

Return type:

DataFrame