Skip to content

Landscape profile

profile runs a selection of the metrics documented in this section in one call and returns them together: a Series for one landscape, or a DataFrame with one row per landscape for several. Use it for a first overview of a landscape or to compare landscapes; call the individual functions when you need their full results.

Profile

graphfla.analysis.profile(
    landscape,
    *,
    metrics=None,
    params=None,
    seed=None,
    n_jobs=-1,
    progress=None,
) -> Union[pd.Series, pd.DataFrame]

Return selected analysis metrics for one or more landscapes.

See Also

Parameters

landscape : Landscape, list of Landscape or tuple of Landscape

One built landscape returns a Series. A list or tuple returns a DataFrame with one row per landscape, in input order.

metrics : str, sequence of str or None, default=None

Metrics to compute. Pass a group name, a function name, or a list mixing both; for example, "ruggedness", ["fdc", "gamma"], or ["ruggedness", "gamma"]. None computes all 21 metrics. Available groups and their function names are:

  • "fitness": fitness_distribution.

  • "ruggedness": local_optima_ratio, gradient_intensity, autocorrelation, r_s_ratio.

  • "robustness": neutrality, evolvability_enhancing_fraction.

  • "correlation": fdc, basin_fitness_correlation, neighbor_fitness_correlation, fitness_flattening_index.

  • "navigability": global_optima_accessibility, mean_path_length_to_global_optimum, mean_distance_to_global_optimum.

  • "epistasis": gamma, gamma_star, global_idiosyncratic_index, diminishing_returns_index, increasing_costs_index, classify_epistasis, extradimensional_bypass.

Groups expand in the order listed above; repeated metrics are computed once, at their first position. An empty list selects no metrics. Use function names here, not output fields such as "epistasis.magnitude". Functions returning variable-length tables or requiring a mutation, position or target must be called directly.

params : dict or None, default=None

Optional settings for individual metrics, keyed by function name. For example, {"autocorrelation": {"walk_length": 50}, "neutrality": {"threshold": 0.05}}. These settings override shared seed and n_jobs values. Use {"classify_epistasis": {"sample_cut_prob": 0}} for exact motif enumeration, or set that function's time_budget here to control automatic sampling. None uses each function's defaults. Settings for unselected metrics are not used; unknown function or parameter names raise ValueError.

seed : int or None, default=None

Shared random seed for metrics that sample. An integer makes sampling reproducible; None leaves each function's default randomness in place.

n_jobs : int or None, default=-1

Worker count for metrics that support parallel computation. Use -1 for all available CPUs or 1 for serial execution. Landscapes themselves are processed sequentially.

progress : bool or None, default=None

Show a progress bar on stderr. None shows it in interactive sessions and notebooks, and hides it in scripts. True or False forces the choice.

Returns

values : pandas.Series or pandas.DataFrame

Float results, with function names as labels for scalar metrics. Dictionary results expand into columns: fitness.<statistic>, epistasis.<type>, bypass.proportion and bypass.avg_length. A DataFrame uses a default integer index; assign its index after the call if labels are needed. Undefined results are NaN. A metric that fails produces NaN and a warning, while the remaining metrics continue.

Examples

>>> from graphfla.landscape import BooleanLandscape
>>> from graphfla.analysis import profile
>>> landscape = BooleanLandscape().build_from_data(
...     ["00", "01", "10", "11"], [0, 1, 2, 4], verbose=False)
>>> profile(landscape, metrics="local_optima_ratio", progress=False).to_dict()
{'local_optima_ratio': 0.25}
>>> selected = profile(landscape, metrics=["fdc", "gamma"],
...                    n_jobs=1, progress=False)
>>> selected.index.tolist()
['fdc', 'gamma']
>>> profile(landscape, metrics="neutrality",
...         params={"neutrality": {"threshold": 1.0}}, progress=False).to_dict()
{'neutrality': 0.25}

Raises

ValueError

If a metric, group or parameter name is unknown.

TypeError

If params or one of its values is not a dictionary.