topo_metrics.clusters#

Classes#

Cluster

Functions#

smallest_ring_size(→ int)

Get the smallest ring size in the cluster.

largest_ring_size(→ int)

Get the largest ring size in the cluster.

number_of_rings(→ int)

Get the number of rings in the cluster.

get_unique_angles(→ int)

Get the number of angles in the cluster.

number_of_angles(→ int)

Get the number of angles in the cluster.

get_ring_sizes(→ list)

Get the ring sizes in the cluster.

shares_edge(→ bool)

Checks if two angles share an edge.

get_opposite_angles(→ list)

Finds the opposite angles in a cluster.

only_smallest_ring_size(→ list[int])

Retains only the smallest ring size in this list. If there are multiple

get_ring_size_by_angle(→ dict[int, list[int]])

Get the ring sizes by angle in a cluster.

ring_list_to_cluster(→ Cluster)

Convert a list of rings to a Cluster object.

get_clusters(topology, all_ring_list)

Convert a list of lists of rings to a list of Cluster objects.

get_vertex_symbol(...)

Obtain the vertex symbol(s) for one or more clusters, storing both the

get_carvs_std_dev(→ float)

Compute the standard deviation amongst the node environments.

get_carvs_vector(...)

Get the Cummulative All-Rings Vertex Symbol (CARVS) vector.

Module Contents#

class topo_metrics.clusters.Cluster[source]#

Bases: NamedTuple

central_node_id: int[source]#

The node ID of the central node in the cluster.

rings: list[topo_metrics.rings.Ring][source]#

The rings that form the cluster.

topo_metrics.clusters.smallest_ring_size(cluster: Cluster) → int[source]#

Get the smallest ring size in the cluster.

topo_metrics.clusters.largest_ring_size(cluster: Cluster) → int[source]#

Get the largest ring size in the cluster.

topo_metrics.clusters.number_of_rings(cluster: Cluster) → int[source]#

Get the number of rings in the cluster.

topo_metrics.clusters.get_unique_angles(cluster: Cluster) → int[source]#

Get the number of angles in the cluster.

topo_metrics.clusters.number_of_angles(cluster: Cluster) → int[source]#

Get the number of angles in the cluster.

topo_metrics.clusters.get_ring_sizes(cluster: Cluster) → list[source]#

Get the ring sizes in the cluster.

topo_metrics.clusters.shares_edge(angle1: tuple, angle2: tuple) → bool[source]#

Checks if two angles share an edge.

Parameters:

  • angle1 – The first angle.

  • angle2 – The second angle.

Return type:

True if the angles share an edge, False otherwise.

topo_metrics.clusters.get_opposite_angles(angles: list) → list[source]#

Finds the opposite angles in a cluster.

Parameters:

angles – A list of angles in the cluster.

Return type:

A list of opposite angle pairs.

topo_metrics.clusters.only_smallest_ring_size(ring_sizes: list[int]) → list[int][source]#

Retains only the smallest ring size in this list. If there are multiple smallest ring sizes, they are all retained.

Parameters:

ring_sizes – A list of ring sizes.

Return type:

A list of the smallest ring sizes.

topo_metrics.clusters.get_ring_size_by_angle(cluster: Cluster, all_rings: bool = False) → dict[int, list[int]][source]#

Get the ring sizes by angle in a cluster.

Parameters:

  • cluster – The cluster to get the ring sizes by angle of.

  • all_rings – Whether to consider all rings in the cluster or just the smallest ring at each angle.

Return type:

A dictionary of ring sizes by angle.

topo_metrics.clusters.ring_list_to_cluster(topology: topo_metrics.topology.Topology, ring_list: list[list[tuple[int, numpy.typing.NDArray[numpy.int_]]]], central_node_id: int) → Cluster[source]#

Convert a list of rings to a Cluster object.

Parameters:

  • topology – The topology object containing the nodes.

  • ring_list – A list of lists of node IDs and image shifts.

  • central_node_id – The node ID of the central node.

Return type:

A Cluster object with the rings in the correct positions.

topo_metrics.clusters.get_clusters(topology: topo_metrics.topology.Topology, all_ring_list: list[list[list[tuple[int, numpy.typing.NDArray[numpy.int_]]]]])[source]#

Convert a list of lists of rings to a list of Cluster objects.

Parameters:

  • topology – The topology object containing the nodes.

  • all_ring_list – A list of lists of lists of node IDs and image shifts.

Return type:

A list of Cluster objects with the rings in the correct positions.

topo_metrics.clusters.get_vertex_symbol(clusters: Cluster | list[Cluster]) → topo_metrics.symbols.VertexSymbol | list[topo_metrics.symbols.VertexSymbol][source]#

Obtain the vertex symbol(s) for one or more clusters, storing both the all_rings=False and all_rings=True vectors. If a list of clusters is provided, this function returns a list of vertex symbols in the same order.

Parameters:

clusters – Either a single cluster, or a list of cluster objects from which to obtain vertex symbols.

Returns:

  • VertexSymbol or list of VertexSymbol

  • - If a single Cluster is passed, returns a single VertexSymbol.

  • - If a list of Cluster objects is passed, returns a list of VertexSymbols.

topo_metrics.clusters.get_carvs_std_dev(carvs_vectors: numpy.typing.NDArray[numpy.int_]) → float[source]#

Compute the standard deviation amongst the node environments.

Parameters:

carvs_vectors – The CARVS vectors for each cluster in the network.

Return type:

The standard deviation of the CARVS vectors.

topo_metrics.clusters.get_carvs_vector(cluster: list[Cluster] | Cluster, max_size: int | None = None, return_per_cluster: bool = False, unique: bool = False) → topo_metrics.symbols.CARVS | numpy.typing.NDArray[numpy.floating][source]#

Get the Cummulative All-Rings Vertex Symbol (CARVS) vector.

If the input is a Cluster object, the CARVS is calculated for that specific cluster. If the input is a list of Cluster objects, the CARVS vector is calculated as an average over all clusters in the entire network, by calling the get_carvs_vector method for each cluster.

Parameters:

  • cluster – The input topology object (either a Cluster or a list of Cluster objects).

  • max_size – The maximum ring size to consider. If not specified, the maximum ring size in the network is used.

  • return_per_cluster – Whether to return the CARVS vector for each cluster in the network, or to return the average CARVS vector over all clusters.

  • unique – If returning the CARVS vector for each cluster, whether to return only unique CARVS vectors.

Return type:

The CARVS vector.