egttools.plotting.draw_invasion_diagram¶
- draw_invasion_diagram(graph, ax=None, style='simple', layout='circular', colors=None, node_size=None, scale_nodes_by_frequency=None, min_node_size=None, edge_width=1.5, scale_edges_by_ratio=None, min_ratio=1.0, curvature=0.2, show_ratios=True, show_frequencies=True, ratio_format='{:.2f}$\\rho_N$', frequency_format=None, ratio_label_position=0.35, name_position=None, frequency_position=None, label_offsets=None, label_padding=4.0, node_kwargs=None, edge_kwargs=None, drift_kwargs=None, label_kwargs=None, ratio_label_kwargs=None, frequency_label_kwargs=None)[source]¶
Draws an invasion diagram from a graph built with
invasion_graph().Selection edges are arrows from the resident to the strategy that invades it, labelled with \(\rho/\rho_N\); pairs that invade each other are drawn as two curved arrows with separate labels. Neutral pairs are drawn as dashed lines without arrow heads. The look is chosen with
style(seeINVASION_DIAGRAM_STYLES) and every element can be adjusted with the parameters below.- Parameters:
graph (
DiGraph) – Graph returned byinvasion_graph().ax (
Optional[Axes]) – Axes to draw on; a new 6x6 inch figure is created if omitted.Named preset from
INVASION_DIAGRAM_STYLES, or a dict with the same keys. It sets the parameters below that are left asNone(node sizes and scaling, edge scaling, label positions, frequency format and label font sizes); explicit arguments always win."simple": equal nodes, stationary frequency inside each node (0.47), name outside."proportional": node area grows with the stationary frequency and arrow width with \(\log_{10}(\rho/\rho_N)\); frequency inside as a percentage, name outside."classic": equal nodes, name and frequency outside the node."compact": equal nodes with name and percentage inside, smaller fonts; suited to diagrams with many strategies.
layout (
Union[str,Dict[int,Tuple[float,float]]]) –"circular","shell","spring"(seeded, so reproducible) or a dict mapping each node (strategy index) to an(x, y)position.colors (
Union[str,Colormap,Sequence,Dict,None]) – Node colours: a palette name (any seaborn palette or matplotlib colormap name, e.g."Set2"or"viridis"), a matplotlib colormap, a sequence of colours indexed by strategy index, or a dict keyed by strategy index or label. Palettes and sequences are indexed by strategy, so colours stay the same when strategies are filtered out. Defaults to seaborn’s"colorblind"palette.node_size (
Optional[float]) – Node area in points^2 (the largest node, ifscale_nodes_by_frequency). Set bystyle.min_node_size (
Optional[float]) – Smallest node area in points^2 whenscale_nodes_by_frequencyis set; chosen by the styles so that a percentage still fits inside the node.scale_nodes_by_frequency (
Optional[bool]) – Make node areas grow linearly with the stationary frequency, frommin_node_sizetonode_size. Ignored if the graph has no stationary distribution. Set bystyle.edge_width (
float) – Line width of the edges.scale_edges_by_ratio (
Optional[bool]) – Set bystyle. Scale the width of selection edges by \(1 + \log_{10}(\rho/\rho_N)\).min_ratio (
float) – Hide selection edges with \(\rho/\rho_N\) below this value (declutters large diagrams).curvature (
float) – Curvature of the two arrows of a pair that invade each other.show_ratios (
bool) – Whether to write \(\rho/\rho_N\) on selection edges and the stationary frequency next to each node.show_frequencies (
bool) – Whether to write \(\rho/\rho_N\) on selection edges and the stationary frequency next to each node.ratio_format (
str) – Format string for \(\rho/\rho_N\).frequency_format (
Union[str,Callable[[float],str],None]) – Format string or function for the stationary frequencies, or"percent"for whole percentages ("<1%"for frequencies that are positive but round to 0%). Set bystyle.ratio_label_position (
float) – Where to write \(\rho/\rho_N\) along each edge, as a fraction of the way from the resident to the invader. Values other than 0.5 keep the labels of edges that cross at their midpoints (e.g. diameters of a circular layout) apart.name_position (
Optional[str]) – Where to write each strategy’s name and stationary frequency (set bystyle). Outside labels go on the side of the node facing away from the centre of the diagram, the name above the frequency when both are outside. Text inside a node is black or white, whichever contrasts with the node colour; when both are inside, the name is written above the frequency.frequency_position (
Optional[str]) – Where to write each strategy’s name and stationary frequency (set bystyle). Outside labels go on the side of the node facing away from the centre of the diagram, the name above the frequency when both are outside. Text inside a node is black or white, whichever contrasts with the node colour; when both are inside, the name is written above the frequency.label_offsets (
Optional[Dict]) – Per-strategy placement of the outside labels, keyed by strategy index or label, as an(dx, dy)offset in points from the node centre. Overrides the automatic placement.label_padding (
float) – Gap, in points, between the edge of a node and its outside labels.node_kwargs (
Optional[Dict]) – Extra arguments fornetworkx.draw_networkx_nodesandnetworkx.draw_networkx_edges(selection and drift edges).edge_kwargs (
Optional[Dict]) – Extra arguments fornetworkx.draw_networkx_nodesandnetworkx.draw_networkx_edges(selection and drift edges).drift_kwargs (
Optional[Dict]) – Extra arguments fornetworkx.draw_networkx_nodesandnetworkx.draw_networkx_edges(selection and drift edges).label_kwargs (
Optional[Dict]) – Extra text properties (e.g.fontsize,color) for strategy names, edge ratios and frequencies. All text has a thin white outline so it stays readable over edges; passpath_effects=[]to remove it.ratio_label_kwargs (
Optional[Dict]) – Extra text properties (e.g.fontsize,color) for strategy names, edge ratios and frequencies. All text has a thin white outline so it stays readable over edges; passpath_effects=[]to remove it.frequency_label_kwargs (
Optional[Dict]) – Extra text properties (e.g.fontsize,color) for strategy names, edge ratios and frequencies. All text has a thin white outline so it stays readable over edges; passpath_effects=[]to remove it.
- Returns:
The axes containing the diagram.
- Return type:
Axes
Examples
>>> import egttools as egt >>> import numpy as np >>> Z = 100 >>> game = egt.games.Matrix2PlayerGameHolder(3, np.array([[1., 0, 2], [2, 1, 0], [0, 2, 1]])) >>> evolver = egt.analytical.PairwiseComparison(Z, game) >>> transitions, fixation_probabilities = evolver.calculate_transition_and_fixation_matrix_sml(1.) >>> sd = egt.utils.calculate_stationary_distribution(transitions.T) >>> graph = egt.plotting.invasion_graph(fixation_probabilities, Z, sd, labels=["R", "P", "S"]) >>> ax = egt.plotting.draw_invasion_diagram(graph)