2. Local epistasis¶

Conventions

• Indices are 0-based: loci are numbered $0, 1, \dots, N-1$.
• Backgrounds are ordered lexicographically (most significant bit first).
• The symbolic epistasis follows the biological “present − absent” sign convention: the first term is $+F(\dots 111 \dots)$ and signs alternate according to $(-1)^{k + |a|}$ for $a \in \{0,1\}^k$.
• You can use ep.epistasis_symbolic(N, idx) to inspect the alternating-sum formula before computing numerics; this is useful to debug indexing and missing-state issues.

Function arguments

• N : int
  Total number of loci in the landscape. It is used for context/sanity checks and to make the call explicit, but it does not change the algebraic form of the symbolic expression.

• idx : Sequence[int]
  Sequence of locus indices defining the interaction $\varepsilon_{i_1,\dots,i_k}(x)$.
  The indices:

  • must be integers in the range $0 \le i < N$,
  • define the order $k = |\text{idx}|$,
  • are internally sorted (idx = sorted(idx)),
  • must contain at least one locus; otherwise a ValueError is raised.

Purpose¶

Computes the first-order epistatic effect (focal effect)

\begin{equation} \Delta_i F(\mathbf{x}) = F(\mathbf{x}^i_{1}) - F(\mathbf{x}^i_{0}), \end{equation}

for locus $i$, across all background configurations of the remaining $N-1$ loci. It returns one value per background, optionally with uncertainty estimates and null-model statistics.

Arguments¶

Required¶

• L : Landscape
  Object containing:

  • L.states — array $(M, N)$ of genotype states (binary)
  • L.values — array $(M, R)$ of replicate measurements
    At least two replicates are needed if bootstrapping is enabled.

• i : int
  Index of the locus to toggle (0-based). Must satisfy 0 ≤ i < L.N.

Robustness options¶

• missing_policy : {"error","drop"}
  Controls how to handle missing backgrounds:

  • "error": require that every background appears for both $x_i=0$ and $x_i=1$.
  • "drop": use only the intersection of available backgrounds.

• nan_policy : {"omit","propagate"}
  Controls how to handle NaNs in replicates:

  • "omit": treat NaNs as zero before the difference (robust bootstrap).
  • "propagate": if all replicates of a term are NaN, the result for that background becomes NaN.

Bootstrap options¶

Uncertainty bootstrap (around the inferred landscape (\hat{F}))¶

• B_uncertainty : int
  Number of bootstrap replicates used to estimate the sampling distribution of
  $\Delta_i F(\mathbf{x})$.

• uncertainty_flavor : {"iid","wildcluster"}

  • "iid": independent bootstrap per state
  • "wildcluster": preserves replicates’ covariance structure (recommended if biological correlations exist)

This bootstrap produces:

• confidence intervals (ci_low, ci_high)
• sign probabilities (sign_prob_pos, sign_prob_neg)
  giving $P(\Delta_i>0)$ and $P(\Delta_i<0)$.

Null bootstrap (noise-only model)¶

• B_null : int
  Number of bootstraps to generate observed-null landscapes, i.e. landscapes with no biological signal but with realistic noise.

• consider_bio_corr : bool

  • False: i.i.d null — removes correlations between genotypes.
  • True: wild-cluster null — preserves biological covariance across states.

This bootstrap yields:

• per-background null CIs (null_ci_low, null_ci_high)
• global variance test (var_obs, var_null_median, p_value_var)
• SNR under the null (snr_null)

Output¶

Returns an Epistasis object with fields:

• values — replicate-level ΔᵢF
• mean, std_experimental, std_biological
• backgrounds — binary matrix of background genotypes
• ci_low, ci_high — uncertainty confidence intervals
• null_ci_low, null_ci_high — null-model CIs
• sign_prob_pos, sign_prob_neg — bootstrap sign probabilities
• var_obs, var_null_median, p_value_var — global null test
• snr_null — signal-to-noise ratio under null
• meta — dictionary with all settings and bootstrap metadata

When as_dataframe=True, the function returns a human-readable tidy DataFrame instead.

Purpose¶

Computes the k-th order epistatic interaction

\begin{equation} \varepsilon_{i_1,\dots,i_k}(x) = \sum_{a\in\{0,1\}^k} (-1)^{k-|a|} \,F(x^{I}_{a}) \end{equation}

across all backgrounds of the remaining $N-k$ loci.

This generalizes:

• order 1 → focal effects
• order 2 → pairwise epistasis
• order k → full alternating-sum interaction over the selected loci

For each background, it returns a replicate-level value, a mean estimate, uncertainty bands, and optional null-model statistics.

Arguments¶

Required¶

• L : Landscape
  Landscape object containing:

  • L.states — binary matrix $(M, N)$
  • L.values — replicate matrix $(M, R)$
    At least two replicates required if bootstrap is used.

• indices : tuple[int, ...]
  Locus indices involved in the interaction.
  Must satisfy:

  • integers in range $[0, N-1]$
  • at least one locus
  • order $k = \text{len(indices)}$
    The function sorts them internally.

Robustness options¶

• missing_policy : {"error","drop"}
  Controls how to handle missing genotypes:

  • "error": require that all (2^k) patterns share the same set of backgrounds
  • "drop": keep only backgrounds present for all patterns

• nan_policy : {"omit","propagate"}
  NaN behaviour in replicate-level computations:

  • "omit": NaNs are interpreted as zero before the alternating sum
  • "propagate": if any term for a background has all-NaN replicates, the epistasis value becomes NaN

Bootstrap options¶

Uncertainty bootstrap (sampling uncertainty around (\hat F))¶

• B_uncertainty : int
  Number of bootstrap replicates to estimate the distribution of
  (\varepsilon_{i_1...i_k}(x)).

• uncertainty_flavor : {"iid","wildcluster"}

  • "iid": bootstrap each state independently
  • "wildcluster": preserves replicate-level correlations (recommended)

This bootstrap provides:

• ci_low, ci_high — per-background CIs
• sign_prob_pos, sign_prob_neg —
  (\Pr(\varepsilon>0)) and (\Pr(\varepsilon<0)) under uncertainty

Null bootstrap (noise-only model)¶

Creates “observed null landscapes” — landscapes with the same measurement noise but no biological signal.

• B_null : int
  Number of null bootstrap samples.

• consider_bio_corr : bool

  • False: i.i.d. null (breaks biological correlations)
  • True: wild-cluster null (preserves cross-state covariance)

This bootstrap yields:

• null_ci_low, null_ci_high — noise-only CIs
• var_obs — observed variance across backgrounds
• var_null_median — typical variance under null
• p_value_var — probability that null variance exceeds observed
• snr_null — per-background signal-to-noise ratio under null

Other options¶

• multipliers : {"rademacher","normal"}
  Wild bootstrap multipliers.

• ci_level : float
  Confidence level for all CIs (default 0.95).

• rng : np.random.Generator
  Optional random generator for reproducibility.

• as_dataframe : bool
  If True, returns a human-readable tidy DataFrame.
  If False, returns the raw Epistasis object.

Output¶

Returns an Epistasis object with:

• Core quantities

  • values — replicate-level k-th order values ((M',R))
  • mean — mean across replicates
  • std_experimental, std_biological
  • backgrounds — binary backgrounds ((M',N-k))

• Uncertainty bootstrap outputs

  • ci_low, ci_high
  • sign_prob_pos, sign_prob_neg

• Null-model outputs

  • null_ci_low, null_ci_high
  • var_obs, var_null_median, p_value_var, effect_size_var
  • snr_null

• Metadata

  • indices, indices_names
  • background_indices, background_names
  • bootstrap settings, seeds, and robustness flags

When as_dataframe=True, returns a full table of epistasis results, suitable for downstream filtering, plotting, and network reconstruction.

Purpose¶

Compute all k-th order epistatic interactions $\varepsilon_{i_1,\dots,i_k}(x)$
for all subsets of loci and all backgrounds, in a single call.

Internally, this function:

1. Loops over interaction orders $k = \text{min\_order}, \dots, \text{max\_order}$.
2. For each order $k$, loops over all combinations of loci $I \subset \{0,\dots,N-1\}$ with $|I| = k$.
3. Calls epistasis_k(L, indices=I, ...) for each combination.
4. Either:
   • returns a nested dict of Epistasis objects, or
   • merges everything into a single tidy DataFrame for downstream analysis.

This is the high-level “orchestrator” for computing the entire epistasis structure of a landscape.

Arguments¶

Required¶

• L : Landscape
  Landscape object with:
  • L.states — binary genotypes of shape $(M, N)$
  • L.values — replicate measurements of shape $(M, R)$

Order range¶

• min_order : int (default = 1)
  Minimum interaction order to compute. Must satisfy $1 \le \text{min\_order} \le N$.

• max_order : Optional[int] (default = None)
  Maximum interaction order.

  • If None, it is set to L.N.
  • Must satisfy $1 \le \text{max\_order} \le N$ and min_order ≤ max_order.

For example:

• min_order=1, max_order=1 → only focal effects.
• min_order=2, max_order=2 → only pairwise epistasis.
• min_order=1, max_order=N → full hierarchy of all orders.

Robustness options¶

Passed directly to each internal call to epistasis_k:

• missing_policy : {"error","drop"}
  Controls how to handle missing genotypes for each interaction:

  • "error": require a complete set of backgrounds for all patterns.
  • "drop": keep only backgrounds common to all patterns (intersection).

• nan_policy : {"omit","propagate"}
  Controls NaN handling in replicates:

  • "omit": NaNs are replaced by 0 before the alternating sum.
  • "propagate": if a term is all-NaN in a background, that epistasis value becomes NaN.

Bootstrap options¶

Applied identically to all interactions via epistasis_k:

• B_uncertainty : int (default = 0)
  Number of bootstrap samples for the uncertainty bootstrap
  (sampling variation around the inferred landscape (\hat F)).
  If 0, no uncertainty bootstrap is performed.

• uncertainty_flavor : {"iid","wildcluster"}

  • "iid": bootstrap each state independently.
  • "wildcluster": preserve replicate-level correlations.

• B_null : int (default = 0)
  Number of bootstrap samples for the null bootstrap
  (observed-null landscapes with noise but no biological signal).
  If 0, no null bootstrap is computed.

• consider_bio_corr : bool (default = False)

  • False: i.i.d. null — cross-state correlations are broken.
  • True: wild-cluster null — cross-state covariance structure is preserved.

• multipliers : {"rademacher","normal"}
  Distribution for wild bootstrap multipliers.

• ci_level : float (default = 0.95)
  Confidence level used for both uncertainty and null confidence intervals.

• rng : np.random.Generator | None
  Optional random number generator for reproducibility.

Output format¶

• as_dataframe : bool (default = True)

  • If True:
    Returns a single tidy pd.DataFrame combining all orders and all locus sets.
    Typical columns include:

    • "Background" (binary string)
    • "Order"
    • "Loci involved"
    • "Epistasis (mean)"
    • "Experimental SD", "Biological SD"
    • "Uncertainty CI (low/high)"
    • "Null CI (low/high)"
    • "Signal-to-Null-Noise (SNR)"
    • "P-value (variance excess)", etc.

  • If False:
    Returns a nested dictionary of Epistasis objects:

    {
        k : {
            indices_tuple : Epistasis(...)
        }
    }
    

    where:

    • k is the interaction order,
    • indices_tuple is a tuple of loci (e.g. (0, 2, 5)).

This makes compute_full_epistasis suitable both for high-level exploratory work (as_dataframe=True) and low-level programmatic analysis (as_dataframe=False).

Purpose¶

Selects epistatic interactions that show strong, statistically supported biological signal,
using a combination of:

1. Signal-to-noise ratio under the null (SNR)
2. Global p-value for excess variance across backgrounds
3. Bootstrap sign probability (confidence that the effect is positive or negative)

This function acts as a biological significance filter on the output of
compute_full_epistasis(as_dataframe=True).

Inputs¶

full_df : pd.DataFrame¶

The full epistasis table, already in “pretty” format.
Should include, when available:

• "Signal-to-Null-Noise (SNR)"
• "P-value (variance excess)"
• "Prob(Effect > 0)", "Prob(Effect < 0)"

If any of these columns are missing, they are automatically added as NaN so
the corresponding criterion safely fails (the row is excluded).

Filtering criteria¶

Each interaction must satisfy all of the following:

1. Minimum SNR under the null¶

• min_snr_null : float = 2.0

Keeps interactions whose signal is at least twice the expected noise amplitude:

\begin{equation} \text{SNR} = \frac{|\varepsilon(x)|}{\sigma_{\text{null}}} \end{equation}

A threshold of 2.0 means “signal ≥ 2 standard deviations of noise”.

2. Maximum p-value for excess variance¶

• max_p_value : float = 0.05

Testing whether epistasis varies across backgrounds more than expected under the null:

\begin{equation} p = \Pr\left( \mathrm{Var}_{\text{null}} \ge \mathrm{Var}_{\text{obs}} \right) \end{equation}

Only interactions with p ≤ 0.05 are retained.
Rows with missing or NaN p-values are excluded automatically.

3. Minimum sign-confidence probability¶

• min_prob_sign : float = 0.95

We compute:

\begin{equation} \max\big( \Pr(\varepsilon>0),\ \Pr(\varepsilon<0) \big) \end{equation}

using bootstrap samples of the epistatic effect.

An interaction passes if there is at least 95% probability the effect has a consistent sign.

Output¶

Returns a DataFrame containing only the rows where:

\begin{equation} \text{SNR} \ge \text{min\_snr\_null} \quad\text{and}\quad p \le \text{max\_p\_value} \quad\text{and}\quad \max(\Pr{>} , \Pr{<}) \ge \text{min\_prob\_sign}. \end{equation}

This is ideal for:

• identifying robust biological interactions,
• reducing noise before network construction,
• visualizing only the strongest epistasis signals,
• downstream clustering or enrichment analysis.

Purpose¶

Construct a pairwise epistatic network from the output of
compute_full_epistasis.

For each pair of loci $(i, j)$ with a computed order-2 epistasis $\varepsilon_{i,j}(x)$, the function aggregates epistatic values across all backgrounds and outputs a single edge weight. This produces a graph representation of the epistatic structure of the landscape.

Inputs¶

full_df : pd.DataFrame¶

The “pretty” DataFrame returned by compute_full_epistasis(as_dataframe=True).
It must contain at least:

• "Interaction type" — strings like "order-2"
• "Loci involved" — tuples like (i, j)
• "Epistasis (mean)" — mean epistasis per background

Optionally:

• "Signal-to-Null-Noise (SNR)" — per-background SNR

Only the rows where "Interaction type" == "order-2" are used.

Interaction order¶

• order : int, default = 2

Currently only pairwise networks (order = 2) are supported.
This argument keeps the API consistent with future extensions.

Aggregation method¶

• agg : {"mean_abs", "max_abs", "mean_snr", "max_snr"}

Controls how per-background epistasis is summarized into a single edge weight:

| Aggregation | Meaning | |------------|---------| | "mean_abs" | Mean of $|\varepsilon_{i,j}(x)|$ across backgrounds | | "max_abs" | Maximum of $|\varepsilon_{i,j}(x)|$ | | "mean_snr" | Mean SNR across backgrounds | | "max_snr" | Maximum SNR |

These metrics let you visualize either:

• average strength of epistasis (mean_abs),
• strongest interaction across contexts (max_abs),
• or biological signal relative to noise (mean_snr, max_snr).

Node names¶

• feature_names : list[str] or None

If provided, must be of length N (number of loci).
The output will include two extra columns:

• "Locus i name"
• "Locus j name"

This is convenient when loci correspond to gene names or biological features.

Output¶

Returns a tidy DataFrame with one row per epistatic edge:

Columns:

• "i", "j" — locus indices
• "weight" — aggregated epistasis between loci
• "metric" — which aggregation rule was used
• "Locus i name", "Locus j name" — optional

This output can be directly passed into network libraries such as:

• networkx.from_pandas_edgelist
• igraph
• cytoscape / graph-tool formatters

Use cases¶

• Visualizing the global epistatic architecture of a genotype–phenotype map.

• Comparing interaction networks across environments or replicates.

• Filtering strong edges using SNR or null-based metrics.

• Downstream structural analysis (centrality, clustering, modularity).

Purpose¶

Visualize a pairwise epistasis network using the edge list produced by
epistasis_to_network.

Each node is a locus (index or biological name).
Each edge represents the aggregated strength of epistasis between two loci, with edge thickness proportional to the epistatic weight.

This function is meant for quick exploratory visualization and uses
networkx + matplotlib.

Inputs¶

edges_df : pd.DataFrame¶

A DataFrame containing at least:

• "i" — locus index of node $1$
• "j" — locus index of node $2$
• "weight" — aggregated epistatic value for the pair

If use_names=True, the DataFrame must also contain:

• "Locus i name"
• "Locus j name"

These are generated automatically in epistasis_to_network when feature_names is provided.

Node labels¶

use_names : bool, default = False¶

Controls whether nodes are displayed using:

• locus indices (0,1,2,...)
  or
• biological names (gene names, or other identifiers)

Useful when loci correspond to biological entities rather than numerical indices.

Plot aesthetics¶

node_size : int, default = 800¶

Pixel size of the nodes.

font_size : int, default = 10¶

Font size for node labels.

Edges are drawn with widths proportional to their normalized weight:

\begin{equation} \text{width}_{ij} = 2 + 4 \cdot \frac{\text{weight}_{ij}}{\max\_w} \end{equation}

This makes strong epistasis visually prominent.