pyphi.relations.Relations#

class pyphi.relations.Relations(*args, **kwargs)[source]#

Bases: Displayable, ToPandasMixin, Serializable

A set of relations among distinctions.

sum_phi_moment(k=2)[source]#

Return Σφ_r^k over all relations, including self-relations.

Parameters:

k (int)

Return type:

float

phi_mean_std()[source]#

Return the population mean and standard deviation of φ_r.

Derived from the count, Σφ_r, and Σφ_r², so it is exact on any backend that answers those queries without enumeration.

Raises:

ValueError – If there are no relations.

Return type:

tuple[float, float]

num_relations_of_degree(degree)[source]#

Return the number of relations with exactly degree relata.

Degree 1 counts the self-relations.

Parameters:

degree (int)

Return type:

int

sum_phi_of_degree(degree)[source]#

Return Σφ_r over relations with exactly degree relata.

Parameters:

degree (int)

Return type:

float

degree_spectrum()[source]#

Return {degree: (count, Σφ_r)} over all relations.

Degrees with no relations are omitted. The counts sum to num_relations() and the φ sums to sum_phi().

Return type:

dict[int, tuple[int, float]]

sum_phi_by_distinction(distinctions)[source]#

Return each distinction’s incident Σφ_r, aligned to distinctions.

A distinction’s incident Σφ_r is the sum of φ_r over every relation that contains it, including its self-relation. The result is a tuple parallel to distinctions; a distinction that no relation reaches contributes 0.0.

Return type:

tuple[float, …]

max_phi()[source]#

Return the maximum φ_r over all relations, or 0.0 if empty.

Return type:

float

phi_histogram()[source]#

Return {φ_r: count} over all relations.

Keys are grouped at the configured precision (pyphi.numerics.round_to_precision()), so mathematically equal values that differ by float noise share a bucket. Counts sum to num_relations().

Return type:

dict[float, int]

num_faces()[source]#

Return the total number of faces across all relations.

Return type:

int

binding_matrix()[source]#

Return the atom-pair binding matrix of the relational structure.

Entry (a, b) is the total minimum density (φ_r / |O|) of the non-self relations whose congruent overlap contains both atoms — the strength with which the two unit-states are jointly bound by relations. The diagonal decomposes the apportioned relation strength per atom. Index and columns are the atoms (state-tagged units) incident to at least one non-self relation, sorted. Self-relations are excluded: the matrix measures binding between distinctions.

Return type:

DataFrame

strongest(k=None, min_phi=None, max_degree=None)[source]#

Yield relations in descending φ_r order.

Ties in φ_r yield in an unspecified but deterministic order.

Parameters:

  • k (int, optional) – Yield at most this many relations. If None, yield all.

  • min_phi (float, optional) – Stop once φ_r falls below this threshold (compared tolerantly at the configured precision).

  • max_degree (int, optional) – Skip relations with more than this many relata.

Return type:

Iterator[Relation]

materialize(max_degree=None, min_phi=None)[source]#

Return the relations as an explicit ConcreteRelations.

Enumerates relation objects from a backend that otherwise answers queries in closed form. max_degree and min_phi (tolerant ≥) bound what is materialized.

Parameters:

  • max_degree (int | None)

  • min_phi (float | None)

Return type:

ConcreteRelations

maximal_relations()[source]#

Return the relations maximal under set inclusion of their relata.

The facets of the relation complex: every relation’s relata are a subset of some maximal relation’s. Degree ≥ 2 only; self-relations are excluded. Computed in closed form from the distinctions — on a filtered set (e.g. from materialize() with bounds) the result is the facets of the complex generated by the participating distinctions, not of the filtered subset. For φ_r-ranked relations see strongest().

Return type:

ConcreteRelations

maximal_faces()[source]#

Return the relation faces maximal under set inclusion of their relata (causes/effects), across all relations; see maximal_faces().

Return type:

frozenset

maximal_relations_by_distinction(distinctions)[source]#

Return, for each distinction, the maximal relations containing it.

Parallel to distinctions; a distinction contained in no maximal relation (an isolated distinction) gets an empty tuple. Within each tuple, facets are ordered by their sorted mechanism tuples.

Return type:

tuple

sample(n, *, seed)[source]#

Draw a coverage-weighted sample of relations.

Implemented on backends that hold the distinction set; see AnalyticalRelations.sample().

Parameters:
Return type:

RelationSample