pyphi.matching.matching.MatchingAnalysis#

class pyphi.matching.matching.MatchingAnalysis(perceptions, world_distribution)[source]#

Bases: object

Matching between a system and a world distribution over stimuli.

Matching (Eq. 21) is the expected excess of perceptual differentiation that a complex’s environment evokes over what random noise evokes.

Variables:

  • perceptions (Mapping[tuple[int, ...], Perception]) – Maps each stimulus to the perceptual structure it triggers.

  • world_distribution (Mapping[tuple[int, ...], float]) – The probability of each stimulus in the world; must sum to 1 and every stimulus with positive probability must appear in perceptions.

Parameters:

Notes

The noise distribution is uniform over all stimuli that have a perceptual structure (the structureless world).

property noise_distribution: dict[tuple[int, ...], float]#

uniform over stimuli with a structure.

Type:

The structureless world

matching(*, seed, n_trials, k, subsequence_max=False)[source]#

Estimate matching M (Eq. 21) by seeded Monte Carlo sampling.

Each trial samples a length-k world sequence (i.i.d. from world_distribution) and a length-k noise sequence (i.i.d. from noise_distribution) and compares their perceptual differentiation. The two sequences are drawn from common random numbers (the same uniform deviates mapped through each distribution’s inverse CDF), so the comparison is paired: identical distributions yield identical sequences and a gap of exactly zero.

Parameters:

  • seed (int) – Seed for the isolated numpy RNG; recorded in the result.

  • n_trials (int) – Number of paired world/noise sequences to sample. Must be >= 1.

  • k (int) – Length of each stimulus sequence. Must be >= 1.

  • subsequence_max (bool, optional) – If False (default), the gap is computed over the full sequence (Eq. 21 with (a, b) = (1, k)), a lower bound on the maximized quantity. If True, the trial-mean gap is computed for every contiguous 1-based window (a, b) with a < b — Eq. 21’s maximization domain, so k must be at least 2 — and the maximum is returned, recording the winning window.

Returns:

MatchingResult – The estimate, its inputs, and the per-trial world and noise differentiation values.

Raises:

ValueError – If n_trials or k is less than 1, or if subsequence_max is true and k is less than 2.

Return type:

MatchingResult