mapping

dsstools.mapping

Module for mapping values onto colors and sizes.

Numeric = TypeVar('Numeric', int, float) module-attribute

NxElementView = TypeVar('NxElementView', NodeDataView, OutEdgeDataView, InEdgeDataView, Iterator[tuple]) module-attribute

SCALABLE_COLORMAPS = ['viridis', 'plasma', 'inferno', 'magma', 'cividis', 'Greys', 'Purples', 'Blues', 'Greens', 'Oranges', 'Reds', 'YlOrBr', 'YlOrRd', 'OrRd', 'PuRd', 'RdPu', 'BuPu', 'GnBu', 'PuBu', 'YlGnBu', 'PuBuGn', 'BuGn', 'YlGn', 'binary', 'gist_yarg', 'gist_gray', 'gray', 'bone', 'pink', 'spring', 'summer', 'autumn', 'winter', 'cool', 'Wistia', 'hot', 'afmhot', 'gist_heat', 'copper'] module-attribute

StrNumeric = TypeVar('StrNumeric', int, float, str) module-attribute

__all__ = ['filtering', 'fixed', 'percentile', 'qualitative', 'sequential', 'from_node', 'filter_ego_network'] module-attribute

logger = get_logger(__name__) module-attribute

Filter(base, supplier, new_mapping, predicate=lambda: True)

Bases: GenericMapping

Class for assigning visual attributes according to a filter condition.

Parameters:

Name	Type	Description	Default
base	GenericMapping	the original Mapping whose values will be assigned if the supplier value evaluates to False	required
supplier	Supplier	the Supplier that provides the values to be evaluated by the predicate	required
new_mapping	GenericMapping	the new Mapping whose values will be assigned if the supplier value evaluates to True	required
predicate	Callable	the expression to evaluate the Supplier, must return a boolean	lambda: True

base = base instance-attribute

fallback = None instance-attribute

new_value = new_mapping instance-attribute

predicate = predicate instance-attribute

supplier = supplier instance-attribute

__repr__()

get(graph_element, graph)

Get the visual values of the graph element based on the Supplier values filtered by the predicate. If the predicate is True the value of the new Mapping is applied, keyed by node. If the predicate is False the value of the base Mapping is applied, keyed by node. If the base mapping contains a fallback, the nodes with the fallback value will retain that value.

Parameters:

Name	Type	Description	Default
graph_element	NxElementView	NxElementView	required
graph	Graph	nx.Graph	required

Returns:

Type	Description
dict	Dict with the keys as the index of the graph element
dict	and the values as the desired visual values based on the predicate

FixedValue(value)

Bases: GenericMapping

Class for setting a singular fixed value to all items.

Parameters:

Name	Type	Description	Default
value	StrNumeric	Set a value, either a numeric type or a color string.	required

__value = parse_color(value) class-attribute instance-attribute

fallback = None instance-attribute

supplier = None instance-attribute

__repr__()

__str__()

get(graph_element, graph)

Get the fixed value for all items in the graph element.

Parameters:

Name	Type	Description	Default
graph_element	NxElementView	NxElementView	required
graph	Graph	nx.Graph	required

Returns:

Type	Description
dict	A dictionary with the key from graph as the key and value as the value

GenericMapping()

Bases: ABC

Generic Interface for mapping visual attributes to graph elements values.

fallback = None instance-attribute

supplier = None instance-attribute

__repr__()

get(graph_element, graph) abstractmethod

Parameters:

Name	Type	Description	Default
graph_element	NxElementView	NxElementView	required
graph	Graph	nx.Graph	required

Returns: A dictionary with graph_element as the keys and the value as visual mapping.

NodeDerivedValue(node_mapping, source, fallback=None)

Bases: GenericMapping

Assign a value from a node to the edges.

Parameters:

Name	Type	Description	Default
node_mapping	GenericMapping	GenericMapping the color should correspond to.	required
source	Literal['incoming', 'outgoing', 'matching']	"incoming" uses the value from the incoming node | "outgoing" uses	required
fallback		the fallback value assigned when incoming and outgoing nodes are	None

fallback = parse_color(fallback) if fallback is not None else self.node_mapping.fallback instance-attribute

node_mapping = node_mapping instance-attribute

source = source instance-attribute

supplier = None instance-attribute

__repr__()

get(graph_element, graph)

Qualitative(supplier, mapping=None, *, cmap=None)

Bases: GenericMapping

Class for assigning a value based on attributes in graph elements.

Assign a value to the items in the graph element attributes.

Parameters:

Name	Type	Description	Default
supplier	Supplier	Supplier The raw graph attributes on which to base the mapping.	required
mapping	Mapping | None	The mapping with the keys as the values of the graph element attribute and the values as the desired visual values.	None

QUALITATIVE_COLORMAPS = ['Pastel1', 'Pastel2', 'Paired', 'Accent', 'Dark2', 'Set1', 'Set2', 'Set3', 'tab10', 'tab20', 'tab20b', 'tab20c'] class-attribute instance-attribute

colormap = cmap instance-attribute

fallback = mapping[None] instance-attribute

mapping = mapping instance-attribute

supplier = supplier instance-attribute

__repr__()

__str__()

get(graph_element, graph)

Get the values in the graph element based on the attribute mapping.

Parameters:

Name	Type	Description	Default
graph_element	NxElementView	NxElementView	required
graph		nx.Graph	required

Returns:

Type	Description
dict	Dict with the keys as the index of the graph element
dict	and the values as the desired visual values based on the attribute

Sequential(supplier, scale='lin', *, out_range, in_range=None, fallback=None, post_processor=lambda x: x, cmap=None)

Bases: GenericMapping, ABC

Abstract class for returning visual attributes on various scales.

Parameters:

Name	Type	Description	Default
*			required
in_range	tuple | None	tuple of the min and max values of the set before normalization	None
out_range	tuple[Numeric, Numeric]	tuple of the min and max values of the final scale	required
fallback	StrNumeric | None	the visual value for none	None
supplier	Supplier	Supplier The raw graph attributes on which to base the mapping, must have numeric values	required
post_processor	Callable	function applied to the values after scaling (e.g. colormapping, conversion)	lambda x: x
cmap	Colormap	optional colormap, used where raw colormap is necessary instead of postprocessor	None

colormap = cmap instance-attribute

fallback = parse_color(fallback) instance-attribute

in_range = in_range instance-attribute

out_range = out_range instance-attribute

post_processor: Callable[[float], object] = post_processor instance-attribute

scale = lambda x: x instance-attribute

supplier = supplier instance-attribute

__repr__()

__set_in_range(values)

Calculate the in range by determining the min/max of the graph element.

The value is returned after applying the appropriate scalable attribute strategy.

Parameters:

Name	Type	Description	Default
values		list of values from the graph element	required

__str__()

also(preprocessor)

Helper function for easier usage of mapping by users.

Parameters:

Name	Type	Description	Default
preprocessor	Callable[[float], float]	function that may need to be called before scaling	required

Returns:

Type	Description
	Sequential

get(graph_element, graph)

Get the values by normalizing supplier values and applying a scale.

If all values are the same, the average of the out_range will be applied to all values.

Parameters:

Name	Type	Description	Default
graph_element	NxElementView	NxElementView	required
graph	Graph	nx Graph	required

Returns:

Type	Description
dict	dict with the keys as the index of the graph element
dict	and the values as the desired visual values based on scale

comfort_fixed(attribute)

comfort_numeric_fixed(attribute)

comfort_str_fixed(attribute)

filter_ego_network(base, ego_network=None, attr=None, ego=None, incoming=None, outgoing=None, mutuals=None)

Create a mapping for a network around one selected network.

Filters an ego-network, so that the base mapping can be applied to all graphelements not in the ego-network and the new_values can be applied to all graphelements that are part of the ego-network.

Parameters:

Name	Type	Description	Default
base	GenericMapping | str | int | float	mapping that is to be applied to graphelements not in the ego-network	required
ego_network	GenericMapping | str | int | float | None	mapping that is to be applied to graphelements inside the ego-network, dictionary mapping must have "ego", and either "neighbors" for nodes or "ego_edge" as keys	None
attr	EgoNetwork | str | int | None	either the name of the node around which ego-network is constructed or an EgoNetwork Supplier	None
ego	GenericMapping | str | int | float | None	mapping only applied to the ego	None
incoming	GenericMapping | str | int | float | None	mapping only applied to incoming, overrides new_mapping	None
outgoing	GenericMapping | str | int | float | None	mapping only applied to outgoing, overrides new_mapping	None
mutuals	GenericMapping | str | int | float | None	mapping only applied both incoming and outgoing, overrides new_mapping	None

filtering(base, new_values, attr, predicate)

Filter the visual values of the graph element based on the attr values.

If the predicate is True the value of the new Mapping is applied, keyed by node. If the predicate is False the value of the base Mapping is applied, keyed by node. If the base mapping contains a fallback, the nodes with the fallback value will retain that value.

Parameters:

Name	Type	Description	Default
base	str | int | float | GenericMapping	the original Mapping whose values will be assigned if the supplier value	required
new_values	str | int | float | GenericMapping	the new Mapping whose values will be assigned if the supplier value	required
attr	str | Supplier	attribute that provides the values to be evaluated by the predicate	required
predicate		the expression to evaluate the attr values, must return a boolean	required

Returns:

Type	Description
	Filter Mapping filtered by predicate applied to attr by assigning new_values if
	predicate is True and base values if predicate is False.

Examples:

G.add_node("a", rating=3, school_type="uni")
G.add_node("b", rating=7, school_type="college")

rating = sequential("rating", out_range=(12, 36))

new_mapping = fixed(1)

image.nodes.set_sizes(filtering(rating, new_mapping, "school_type", lambda x:x is "uni"))

sizes = a: 1, b: 36
node a has been given the value 1 because the "school_type" is "uni"
node b remains unchanged

fixed(value)

Set a fixed value, that is constant across all items in the chosen graph element.

Parameters:

Name	Type	Description	Default
value		v	required

Returns:

Type	Description
	FixedValue

Examples:

image.nodes.set_sizes(fixed(75))
# the size of all nodes is now 75

image.edges.set_colors("green")
# the color of all nodes is now green

from_node(node_mapping, source, *, fallback=None)

Assign a value from a node to the edges.

Parameters:

Name	Type	Description	Default
node_mapping	GenericMapping	GenericMapping the color should correspond to.	required
source	Literal['incoming', 'outgoing', 'matching']	"incoming" uses the value from the incoming node | "outgoing"	required
fallback		the fallback value assigned when incoming and outgoing nodes	None

generate_mapping(values)

parse_color(value)

Determine whether the value is a color.

If it is a color the corresponding hex value will be returned. Otherwise, the value is returned unchanged.

Parameters:

Name	Type	Description	Default
value			required

Returns:

Type	Description
	Either returns a HEX color code or the value itself if no parsing was possible.

parse_colormap(cmap, acceptable_colormaps)

Determine whether the value is an acceptable colormap.

If it is a color the corresponding hex value will be returned. Otherwise, the value is returned unchanged.

Parameters:

Name	Type	Description	Default
cmap	str | Colormap	Colormap or string of a colormap	required

Returns:

Type	Description
	Colormap

percentile(base, new_values, attr, perc_range=None, method='linear')

Create a mapping that modifies an existing mapping by percentage.

Parameters:

Name	Type	Description	Default
base	str | int | float | GenericMapping	the Mapping, whose values are assigned to the node if the attr values are inside the perc_range	required
new_values	str | int | float | GenericMapping	the Mapping, whose values are assigned to the node if the attr values are outside the perc_range	required
attr	str | Supplier	the attribute with which the percentile is calculated, must contain numeric values	required
perc_range	tuple	tuple of min and max range for the percentile calculation, must be between 0 and 100	None
method	str	str, optional, default "linear" This parameter specifies the method to use for estimating the percentile. There are many different methods, some unique to NumPy. See the notes for explanation. The options sorted by their R type as summarized in the H&F paper [1]_ are: 'inverted_cdf' 'averaged_inverted_cdf' 'closest_observation' 'interpolated_inverted_cdf' 'hazen' 'weibull' 'linear' (default) 'median_unbiased' 'normal_unbiased' The first three methods are discontinuous. NumPy further defines the following discontinuous variations of the default 'linear' (7.) option: 'lower' 'higher', 'midpoint' 'nearest'	'linear'

Returns:

Type	Description
	Filter Mapping filtered by percentile of attr assigning values based on new_values

Examples:

G.add_node("a", rating=3)
G.add_node("b", rating=7)

base_mapping = sequential("rating", fallback="orange", cmap="viridis")
new_mapping = fixed("blue")

image.nodes.set_colors(percentile(base_mapping, new_mapping, "degree", perc_range=(0, 50))

qualitative(attr, mapping=None, *, cmap=None)

Use an attribute or colormap as value.

Parameters:

Name	Type	Description	Default
attr	str | Code	str name of the category	required
mapping	dict | None	dict of category values as the key and desired values as the values	None
cmap		str of a valid colormap or colormap object	None

Returns:

Type	Description
	Nominal

Examples:

G.add_node("a", pet="dog")
G.add_node("b", pet="cat")

image.nodes.set_colors(qualitative("rating", {"cat": "red", "dog": "green"}))
# color for node "a" is now "green" and "red" for node "b"

image.nodes.set_colors(qualitative("rating", cmap="Pastel1"))
# color for node "a" is now the first color in the Pastel1 colormap and the
# second color for node "b"

sequential(attr, scale='lin', out_range=None, in_range=None, fallback=None, cmap=None)

Scale on graph element or structural graph attributes.

Parameters:

Name	Type	Description	Default
*			required
attr	str | Supplier	str name of graph element or structural graph attribute to be scaled	required
scale	str | Callable	scale on which the values should be assigned	'lin'
out_range		tuple of the min and max values of the final scale	None
in_range		tuple of the min and max values of the set before normalization	None
fallback		a color value or numeric value for None values	None

Returns:

Type	Description
	Sequential

Examples:

G.add_node("a", rating=3)
G.add_node("b", rating=7)

image.nodes.set_sizes(sequential("degree", "log", out_range=(12, 36), fallback=5))

image.nodes.set_sizes(sequential("rating", linear(), out_range=(12, 36), fallback=5))

image.nodes.set_colors(sequential("rating", fallback="orange", cmap="viridis"))

supplier_helper(attr)

Turns attribute into a Supplier if it not one already.

First checks to see if the attribute is a StructuralAttribute to avoid obsolete values by always recalculating StructuralAttributes (e.g. degree, betweenness, etc.). If it is not a StructuralAttribute it will be processed as an ElementAttribute, which are graph attributes.

Parameters:

Name	Type	Description	Default
attr		attribute to be turned into a Supplier	required

Returns: Supplier