mapping

`dsstools.mapping`

Module for mapping values onto colors and sizes.

`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`

`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

`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.

`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`

`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`

`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)`

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`

`__get_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

Returns:

Type	Description
	Tuple for the min/max range for normalization

`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

`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)

ig.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:

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

ig.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`

`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')`

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")

ig.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")

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

ig.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)

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

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

ig.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

mapping

dsstools.mapping

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

get(graph_element, graph)

FixedValue(value)

get(graph_element, graph)

GenericMapping()

get(graph_element, graph) abstractmethod

NodeDerivedValue(node_mapping, source, fallback=None)

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

get(graph_element, graph)

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

__get_in_range(values)

also(preprocessor)

get(graph_element, graph)

filtering(base, new_values, attr, predicate)

fixed(value)

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

parse_color(value)

parse_colormap(cmap, acceptable_colormaps)

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

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

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

supplier_helper(attr)

`dsstools.mapping`

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

`get(graph_element, graph)`

`FixedValue(value)`

`get(graph_element, graph)`

`GenericMapping()`

`get(graph_element, graph)` `abstractmethod`

`NodeDerivedValue(node_mapping, source, fallback=None)`

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

`get(graph_element, graph)`

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

`__get_in_range(values)`

`also(preprocessor)`

`get(graph_element, graph)`

`filtering(base, new_values, attr, predicate)`

`fixed(value)`

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

`parse_color(value)`

`parse_colormap(cmap, acceptable_colormaps)`

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

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

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

`supplier_helper(attr)`