Skip to content

Fitness distributions

These functions summarize retained fitness values, mutation effects, and changes along adaptive walks.

Fitness distribution

graphfla.analysis.fitness_distribution(
    landscape,
) -> Dict[str, float]

Return descriptive statistics of the retained fitness distribution.

Parameters

landscape : Landscape

Built fitness landscape.

Returns

statistics : dict of str to float

Keys are skewness, kurtosis (Pearson convention, normal=3), cv (sample SD divided by absolute mean), quartile_coefficient (IQR divided by absolute median), median_mean_ratio, relative_range (range divided by absolute median), and cauchy_loc (fitted location). Undefined summaries, including ratios with a zero denominator, are NaN. An empty landscape returns the same keys with NaN values.

Examples

>>> from graphfla.landscape import BooleanLandscape
>>> from graphfla.analysis import fitness_distribution
>>> landscape = BooleanLandscape().build_from_data(
...     ["00", "01", "10", "11"], [0, 1, 2, 4], verbose=False)
>>> round(fitness_distribution(landscape)["median_mean_ratio"], 3)
0.857

Summarize fitness across the configurations retained in the landscape. The fitted Cauchy location is in fitness units; the other summaries are dimensionless, but need not be invariant to shifts or nonlinear transforms.

Notes

Positive skewness indicates a longer right tail; negative skewness a longer left tail. Pearson kurtosis is 3 for a normal distribution. Cauchy location describes the fitted center and is not scale-invariant.

Raises

RuntimeError

If the graph is not initialized or the fitness attribute is missing.

Mutation effect distribution

graphfla.analysis.fitness_effect_distribution(
    landscape, mutation
) -> List[float]

Return fitness effects of one mutation across matching backgrounds.

Parameters

landscape : Landscape

Built fitness landscape.

mutation : tuple of (source, position, target)

Allele substitution to evaluate. position is a configuration-column label from landscape.data_types, not a positional column index.

Returns

effects : list of float

Target-minus-source fitness differences, one per matching background. Return an empty list if no backgrounds match. A single-position landscape has one shared empty background.

Examples

>>> from graphfla.landscape import BooleanLandscape
>>> from graphfla.analysis import fitness_effect_distribution
>>> landscape = BooleanLandscape().build_from_data(
...     ["00", "01", "10", "11"], [0, 1, 2, 4], verbose=False)
>>> fitness_effect_distribution(landscape, (0, "bit_0", 1))
[2.0, 3.0]

Use each retained background in which both source and target alleles are observed. Effects are target fitness minus source fitness, without changing sign for minimization.

Raises

ValueError

If the specified alleles don't exist at the given position.

graphfla.exceptions.NotBuiltError

If the landscape has not been built.

Fitness flattening

graphfla.analysis.fitness_flattening_index(
    landscape, min_len: int = 3, method: str = "spearman"
) -> float

Return the mean fitness-increment trend along greedy adaptive paths.

Parameters

landscape : Landscape

Built fitness landscape.

min_len : int, default=3

Minimum number of configurations, including the starting configuration, in a greedy path. Only paths ending at the selected global optimum count.

method : (spearman, pearson), default="spearman"

Correlation coefficient to calculate.

Returns

index : float

Mean correlation of step index with successive signed fitness changes. Under maximization, a negative value means gains tend to decrease along paths. Returns NaN if no eligible path has a defined correlation.

Examples

>>> from graphfla.landscape import BooleanLandscape
>>> from graphfla.analysis import fitness_flattening_index
>>> landscape = BooleanLandscape().build_from_data(
...     ["00", "01", "10", "11"], [0, 3, 2, 4], verbose=False)
>>> round(fitness_flattening_index(landscape), 3)
-1.0