topologic.statistics package

topologic.statistics.cut_edges_by_weight(graph: networkx.classes.graph.Graph, cut_threshold: Union[int, float], cut_process: topologic.statistics.make_cuts.MakeCuts, weight_attribute: str = 'weight', prune_isolates: bool = False) → networkx.classes.graph.Graph[source]

Given a graph, a cut threshold, and a cut_process, create a new Graph that contains only the edges that are not pruned.

Note: Edges without a weight_attribute field will be excluded from these cuts. Enable logging to view any messages about edges without weights.

Parameters
  • graph (networkx.Graph) – The graph that will be copied and pruned.

  • cut_threshold (Union[int, float]) – The threshold for making cuts based on weight.

  • cut_process (MakeCuts) – Describes how we should make the cut; cut all edges larger or smaller than the cut_threshold, and whether exclusive or inclusive.

  • weight_attribute (str) – The weight attribute name in the data dictionary. Default is weight.

  • prune_isolates (bool) – If true, remove any vertex that no longer has an edge. Note that this only prunes vertices which have edges to be pruned; any isolate vertex prior to any edge cut will be retained.

Returns

Pruned copy of the graph

Return type

networkx.Graph

topologic.statistics.cut_vertices_by_betweenness_centrality(graph: networkx.classes.graph.Graph, cut_threshold: Union[int, float], cut_process: topologic.statistics.make_cuts.MakeCuts, num_random_samples: Optional[int] = None, normalized: bool = True, weight_attribute: Optional[str] = None, include_endpoints: bool = False, random_seed: Union[int, random.Random, None] = None) → networkx.classes.graph.Graph[source]

Given a graph and a cut_threshold and a cut_process, return a copy of the graph with the vertices outside of the cut_threshold.

The betweenness centrality calculation can take advantage of networkx’ implementation of randomized sampling by providing num_random_samples (or k, in networkx betweenness_centrality nomenclature).

See: https://networkx.github.io/documentation/networkx-1.10/reference/generated/networkx.algorithms.centrality.betweenness_centrality.html for more details.

Parameters
  • graph (networkx.Graph) – The graph that will be copied and pruned.

  • cut_threshold (Union[int, float]) – The threshold for making cuts based on betweenness centrality.

  • cut_process (MakeCuts) – Describes how we should make the cut; cut all edges larger or smaller than the cut_threshold, and whether exclusive or inclusive.

  • num_random_samples (Optional[int]) – Use num_random_samples for vertex samples to estimate betweenness. num_random_samples should be <= len(graph.nodes). The larger num_random_samples is, the better the approximation.

  • normalized (bool) – If True the betweenness values are normalized by 2/((n-1)(n-2)) for graphs, and 1/((n-1)(n-2)) for directed graphs where n is the number of vertices in the graph.

  • weight_attribute (Optional[str]) – If None, all edge weights are considered equal. Otherwise holds the name of the edge attribute used as weight.

  • include_endpoints (bool) – If True include the endpoints in the shortest path counts.

  • random_seed (Optional[Union[int, random.Random]]) – Random seed or preconfigured random instance to be used for randomly selecting random samples. Only used if num_random_samples is set. None will generate a new random state. Specifying a random state will provide consistent results between runs.

Returns

Pruned copy of the graph

Return type

networkx.Graph

topologic.statistics.cut_vertices_by_degree_centrality(graph: networkx.classes.graph.Graph, cut_threshold: Union[int, float], cut_process: topologic.statistics.make_cuts.MakeCuts) → networkx.classes.graph.Graph[source]

Given a graph and a cut_threshold and a cut_process, return a copy of the graph with the vertices outside of the cut_threshold.

Parameters
  • graph (networkx.Graph) – The graph that will be copied and pruned.

  • cut_threshold (Union[int, float]) – The threshold for making cuts based on degree centrality.

  • cut_process (MakeCuts) – Describes how we should make the cut; cut all edges larger or smaller than the cut_threshold, and whether exclusive or inclusive.

Returns

Pruned copy of the graph

Return type

networkx.Graph

class topologic.statistics.DefinedHistogram[source]

Bases: tuple

Contains the histogram and the edges of the bins in the histogram.

The bin_edges will have a length 1 greater than the histogram, as it defines the minimal and maximal edges as well as each edge in between.

property bin_edges

Alias for field number 1

property histogram

Alias for field number 0

topologic.statistics.filter_function_for_make_cuts(cut_threshold: Union[int, float], cut_process: topologic.statistics.make_cuts.MakeCuts) → Callable[[Tuple[Any, Union[int, float]]], bool][source]
topologic.statistics.histogram_betweenness_centrality(graph: networkx.classes.graph.Graph, bin_directive: Union[int, List[Union[float, int]], numpy.ndarray, str] = 10, num_random_samples: Optional[int] = None, normalized: bool = True, weight_attribute: Optional[str] = None, include_endpoints: bool = False, random_seed: Union[int, random.Random, None] = None) → topologic.statistics.defined_histogram.DefinedHistogram[source]

Generates a histogram of the vertex betweenness centrality of the provided graph. Histogram function is fundamentally proxied through to numpy’s histogram function, and bin selection follows numpy.histogram processes.

The betweenness centrality calculation can take advantage of networkx’ implementation of randomized sampling by providing num_random_samples (or k, in networkx betweenness_centrality nomenclature).

See: https://networkx.github.io/documentation/networkx-1.10/reference/generated/networkx.algorithms.centrality.betweenness_centrality.html for more details.

Parameters
  • graph (networkx.Graph) – the graph. No changes will be made to it.

  • bin_directive (Union[int, List[Union[float, int]], numpy.ndarray, str]) – Is passed directly through to numpy’s “histogram” (and thus, “histogram_bin_edges”) functions. See: https://docs.scipy.org/doc/numpy-1.15.1/reference/generated/numpy.histogram_bin_edges.html#numpy.histogram_bin_edges In short description: if an int is provided, we use bin_directive number of equal range bins. If a sequence is provided, these bin edges will be used and can be sized to whatever size you prefer. Note that the np.ndarray should be ndim=1 and the values should be float or int.

  • num_random_samples (Optional[int]) – Use num_random_samples for vertex samples to estimate betweeness. num_random_samples should be <= len(graph.nodes). The larger num_random_samples is, the better the approximation.

  • normalized (bool) – If True the betweenness values are normalized by 2/((n-1)(n-2)) for graphs, and 1/((n-1)(n-2)) for directed graphs where n is the number of vertices in the graph.

  • weight_attribute (Optional[str]) – If None, all edge weights are considered equal. Otherwise holds the name of the edge attribute used as weight.

  • include_endpoints (bool) – If True include the endpoints in the shortest path counts.

  • random_seed (Optional[Union[int, random.Random]]) – Random seed or preconfigured random instance to be used for randomly selecting random samples. Only used if num_random_samples is set. None will generate a new random state. Specifying a random state will provide consistent results between runs.

Returns

A named tuple that contains the histogram and the bin_edges used in the histogram

Return type

DefinedHistogram

topologic.statistics.histogram_degree_centrality(graph: networkx.classes.graph.Graph, bin_directive: Union[int, List[Union[float, int]], numpy.ndarray, str] = 10) → topologic.statistics.defined_histogram.DefinedHistogram[source]

Generates a histogram of the vertex degree centrality of the provided graph. Histogram function is fundamentally proxied through to numpy’s histogram function, and bin selection follows numpy.histogram processes.

Parameters
Returns

A named tuple that contains the histogram and the bin_edges used in the histogram

Return type

DefinedHistogram

topologic.statistics.histogram_edge_weight(graph: networkx.classes.graph.Graph, bin_directive: Union[int, List[Union[float, int]], numpy.ndarray, str] = 10, weight_attribute: str = 'weight') → topologic.statistics.defined_histogram.DefinedHistogram[source]

Generates a histogram of the edge weights of the provided graph. Histogram function is fundamentally proxied through to numpy’s histogram function, and bin selection follows numpy.histogram processes.

Note: Edges without a weight_attribute field will be excluded from this histogram. Enable logging to view any messages about edges without weights.

Parameters
Returns

A named tuple that contains the histogram and the bin_edges used in the histogram

Return type

DefinedHistogram

class topologic.statistics.MakeCuts[source]

Bases: enum.Enum

An enumeration.

LARGER_THAN_EXCLUSIVE = 2
LARGER_THAN_INCLUSIVE = 1
SMALLER_THAN_EXCLUSIVE = 4
SMALLER_THAN_INCLUSIVE = 3