Mapping

Mapping means the changing of attribute values from a graph into color and size attributes for the graphic visualisation.

Mappings can be applied to two graph elements which in turn hold more specific attributes. Those are: - Nodes - node color - node size - node labels - node alpha (transparency) - Edges - edge color - edge size (thickness) - edge alpha (transparency)

There are four possibilities for a base mapping:

fixed: Takes a fixed value for color or size, meaning a float, int or str.
qualitative: Qualitative attributes are mapped onto graph elements. For example: The attribute "pet" has the values "cat", "dog" and "mouse". The values are different, but there is no natural order.
sequential: Sequential attributes are mapped onto graph elements. One example would be the degree of a node. The values are different, continuous and have a natural order.
ego_mapping: Applies a mapping which is oriented around an ego, which is a chosen node from a network. It maps different visual attributes to the ego compared to the rest of the network. The ego network includes all nodes which are directly connected to the ego and all the edges between those nodes.

There are also four mappings for more complex images, to give attributes different visualisations based on a specified condition.

filtering: A new mapping is applied to the original mapping, if a True/False condition applies to the attribute.
percentile: A new mapping is applied to the original mapping, if the percentile of the attribute is outside of a given percentile.
from_node: Takes the values of the mapping for edges from the mapping of nodes (or labels). Either the mapping of the start or end node can be applied, or the condition can be used that start and end node of an edge need to be the same.
filter_ego_network: Allows the user to filter for an ego network around an ego and to apply one mapping to the ego network and another one to the rest. Any mapping can be used, e.g. sequenatial, ego_mapping etc.

Usage

The mapping is connected with the ImageGenerator. To get started with drawing, click here.

Fixed Values

graph = nx.DiGraph() # (1)
graph.add_node("a")
graph.add_node("b")
ig = dnb.ImageGenerator(graph) # (2)

fix = fixed(12) # (3)
ig.nodes.set_sizes(fix) # (4)

Creating a simple graph.
Creating an ImageGenerator.
The object is initialised with a fixed value of 12, which is assigned to the variable fix.
The object fix is assigned to the nodes. All nodes in the network will be drawn with the circumference of 12 now.

The last two lines can also be compressed into one:

ig.nodes.set_sizes(fixed(12))

fixed is the default value. To make it easier, a fixed value can also be written like this (as long as it's a str, int or float):

ig.nodes.set_sizes(12)

Qualitative Values

graph = nx.DiGraph() # (1)
graph.add_node("a", pet="dog") # (2)
graph.add_node("b", pet="cat")
ig = dnb.ImageGenerator(graph) # (3)

qual = dnb.qualitative("pet", {"cat": "red", "dog": "green"}) # (4)
ig.nodes.set_colors(qual) # (5)

1. Creation of a simple graph. 2. Nodes with data are created: Node a has the value dog for the attribute pet. 3. Creation of an ImageGenerator. 4. An object with an attribute key ("pet") and a dict, which holds the mapping from value to color, are initialised. It is assigned to the variable qual. 5. The object qual is assigned to the nodes of the graph as colors. All nodes are now drawn with the mapping from the dict.

Here the last two lines can be shortened as well:

ig.nodes.set_colors(
    dnb.qualitative("pet", {"cat": "red", "dog": "green"}
                )

Note

Colors are passed as a String and can be a word or RGB/RGBA. For an overview of colorwords, see here. The different forms are explained here.

If you want to use a qualitative mapping for sizes, you need to initialize the dict with numerical values for sizes instead of colors. If you like cats, this might look like:

ig.nodes.set_sizes(dnb.qualitative("pet", {"cat": 50, "dog": 5})

Sequential Values

graph = nx.DiGraph() # (1)
graph.add_node("a") # (2)
graph.add_node("b")
ig = dsslab.net_bench.ImageGenerator(graph) # (3)

sequ = sequential("degree", out_range=(10, 50) ) # (4)
ig.nodes.set_sizes(sequ) # (5)

1. Creation of a simple graph. 2. Here, nodes without additional data are created, because we use the already existing attributes of the graph and its nodes. 3. Creation of an ImageGenerator. 4. Here we initialise an object with an attribute key ("degree") and an out_range, which maps the values from the network to a size. It is assigned to the variable sequ. 5. The object sequ is applied to the nodes. All nodes in the network are now drawn with the sizes from the mapping from out_range.

Note

Of course it isn't much point in using "degree" in this example, because there are no edges in the network.

Note

For the mapping of sequential values the following can be used from the internal attributes:

degree
indegree
outdegree
betweenness
closeness
Further attributes which are saved in the graph can be used, if they e.g. where put there via TextSearch. To do this, the Texttag must be used.

The shortened version should now be obvious from our previous examples. Sequential values can be used for colors in the same way. Instead of the parameter out_range, the parameter cmap has to be used in this case. For this example, we choose the colormap viridis:

ig.nodes.set_colors("degree", cmap="viridis")

Colors and sizes can be combined, so that both coincide with the nodes:

(
    ig.nodes
    .set_colors(dnb.sequential("degree", cmap="viridis"))
    .set_sizes(dnb.sequential("degree", out_range=(5,50)))
)

The following values (defined by the network) are allowed for using sequential mappings:

"indegree"
"outdegree"
"degree"
"centrality"
"betweenness"
"closeness"

You can also use manually defined values:

graph = nx.DiGraph() # (1)
graph.add_node("a", rating=3) # (2)
graph.add_node("b", rating=7)
graph.add_node("c")
ig = dnb.ImageGenerator(graph) # (3)

ig.nodes.set_sizes(
    dnb.sequential("rating", out_range=(12, 36), fallback=5) # (4)
)

ig.nodes.set_colors(
    dnb.sequential("rating", fallback="orange", colormap="viridis") # (5)
)

1. Creation of a simple graph. 2. Nodes with data are created: Node a has value 3 for the attribute rating. There also is a node without the attribute rating(c). 3. Creation of an ImageGenerator. 4. A mapping object with attribute key rating and an out_range is initialised, which maps the values from the network to sizes. The fallback is also choosen for all nodes which don't have the attribute (e.g. c). Together, the object is assigned to the node sizes with ig.nodes.set_sizes(). 5. A mapping object for color is created and applied the same way as in (4).

Extended Mappings

Extended mappings are based on existing mappings to allow for more complex mappings. There are four options for extended mappings:

filter: Creates a mapping based on a filtering condition. The condition is evaluated for every graph element. The values from a base mapping are used, if the condition is False for a specific element. The values of new_mapping are used, if the condition is True.
from_node: Takes values from the mapping for nodes (or labels) and uses them for the edge mapping. Either the mapping of start and end node are considered or the condition, that start and end node have to be the same.

Filter Values

Condition

graph = nx.DiGraph() # (1)
graph.add_node("a")
graph.add_node("b")
ig = dnb.ImageGenerator(graph) # (2)

base = dnb.fixed("blue") # (3)
new_mapping = dnb.fixed("orange") # (4)
attribute = "degree" # (5)
condition = lambda x:x > 0.5 # (6)
filtered = dnb.filtering(base, new_mapping, attribute, condition) # (7)

ig.nodes.set_colors(filtering) # (8)

1. Creation of a simple graph. 2. Creation of an ImageGenerator. 3. An object with the fixed value "blue" is initialised and assigned to the variable base. 4. An object with the fixed value "orange" is initialised and assigned to the variable new_mapping. 5. The attribute that is to be used is defined and assigned to attribute. 6. The condition is defined and assigned to condition. 7. A mapping object is created, which holds the mapping from value to color based on the condition. 8. The object filtering is assigned to the nodes of the graph as colors. All nodes with a degree higher than 0.5 ae drawn orange and all nodes with a degree lower than 0.5 have the original value blue.

base and new_mapping can be any type of mapping.

Percentile

graph = nx.DiGraph() # (1)
graph.add_node("a")
graph.add_node("b")
ig = dsslab.net_bench.ImageGenerator(graph) # (2)

base = dnb.fixed("blue") # (3)
new_mapping = dnb.fixed("orange") # (4)
attribute = "degree" # (5)

percentile = dnb.percentile(base, new_mapping, attribute, perc_range=(0,50)) # (6)


ig.nodes.set_colors(percentile) # (7)

1. Creation of a simple graph. 2. Creation of an ImageGenerator. 3. An object with the fixed value "blue" is initialised and assigned to the variable base. 4. An object with the fixed value "orange" is initialised and assigned to the variable new_mapping. 5. The attribute that is to be used is defined and assigned to attribute. 7. A mapping object is created, which holds the mapping from value to color based on the condition. Further, the perc_range is defined. 8. The object percentile is assigned to the nodes of the graph as color. All nodes with the degree whose percentile lies outside of the percentile rance are drawn orange. All attributes with the value within the percentile range get the original value: blue.

base and new_mapping can be any type of mapping.

From Node

There are three possibilities for the source Parameter in the from_node mapping, which is passed as a String:

"incoming": Uses the value of the start node of the edge.
"outgoing": Uses the value of the end node of the edge.
"matching": Uses the value of the start and end node, if they are the same. Uses the fallback value, if they are not the same. The parameter fallback is necessary for the keyword matching.

This is an example for "matching":

graph = nx.DiGraph() # (1)
graph.add_node("a")
graph.add_node("b")
graph.add_edge(a,b)
ig = dnb.ImageGenerator(graph) # (2)

ig.nodes.set_colors("degree", cmap="viridis") # (3)

from_node = dnb.from_node(ig.nodes.colors, "matching", fallback= "red") # (4)

ig.edges.set_colors(from_node) # (5)

Creation of a simple graph.
Creation of an ImageGenerator.
A mapping object for node colors is created based on "degree".
A mapping object for edge colors is initialised and assigned to the variable from_node.
The object from_node is assigned to the nodes of the graph as coloring. All edges that have the same start and end node are colored that way, the rest are colored according to the fallback.

Ego Mapping

An ego mapping can be created for nodes and edges.

A node from the graph must be chosen as an ego.

The mapping can decide sizes or colors.

The "incoming", "outgoing" and "mutual" edges or nodes and the "ego" node can be set with their own mapping via the corresponding parameters. The ego_network parameter sets the mapping for all the parts of the ego network at the same time.

Example for the usage of ego mapping:

graph = nx.DiGraph()  # (1)
graph.add_nodes_from(["A", "B", "C", "D", "E", "F", "G", "H"])  # (2)
graph.add_edges_from(
    [("B", "C"), ("C", "D"), ("D", "A"), ("A", "F"), ("A", "B"), ("B", "E"), ("G", "H"), ("G", "E"), ("B", "D")])  # (3)
ig = dnb.ImageGenerator(graph)  # (4)

ego_mapping_nodes = dnb.filter_ego_network(base ="green", ego_network = "blue", attr = 2, ego = "purple" ,incoming="grey")
ego_mapping_edges = dnb.filter_ego_network(base= 200, attr = 2, incoming = 500)

ig.nodes.set_colors(ego_mapping_nodes)  # (7)
ig.edges.set_sizes(ego_mapping_edges)  # (8)

Creation of a DiGraph (directed graph).
Adding nodes to the graph.
Adding edges to the graph.
Creating an ImageGenerator for the graph.
Creating the ego mapping for the colors of the nodes.
Creating the ego mapping for the sizes of the edges.
Applying the mapping to the colors of the nodes.
Applying the mapping to the sizes of the edges.

Filter Ego Network

filter_ego_network combines the functionality of filtering with the logic of the ego network.

It allows you to pick an ego network from a network and apply a base mapping to the part that is not in the ego network and a new mapping to the part that is in the ego network. You don't have to use ego_mapping to do this but can instead use any mapping for both parts.

The parameters you need are: a base mapping, a new mapping, an ego (a node of the network) and a boolean (undirected). The boolean has the same purpose as the ego mapping.

Example:

graph = nx.DiGraph()  # (1)
graph.add_nodes_from(["A", "B", "C", "D", "E", "F", "G", "H"])  # (2)
graph.add_edges_from(
    [("B", "C"), ("C", "D"), ("D", "A"), ("A", "F"), ("A", "B"), ("B", "E"), ("G", "H"), ("G", "E"), ("B", "D")])  # (3)
image_generator = dnb.ImageGenerator(graph)  # (4)

filter_mapping_edges = dnb.filter_ego_network(dnb.fixed("green"), ego_mapping(ego="B", mapping={"ego_edge": "blue"}),
                                              ego="B")  # (5)
filter_mapping_nodes = dnb.filter_ego_network(dnb.fixed("green"), dnb.fixed("blue"), ego="B")  # (6)

ig.edges.set_colors(filter_mapping_edges)  # (7)
ig.nodes.set_colors(filter_mapping_nodes)  # (8)

Creation of a DiGraph (directed graph).
Adding nodes to the graph.
Adding edges to the graph.
Creating an ImageGenerator for the graph.
The base here is a fixed mappping with value "green", to the ego network we apply an ego mapping. For filter_ego_network and ego_mapping we specify the ego, in this case "B".
Here we use a fixed mapping with value "green" as the base. The ego network is colored with a fixed mapping with the value "blue".
Applying the mapping to the edges.
Applying the mapping to the nodes.