mapping

`dsstools.mapping`

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.

`CalculatedScalableAttribute`

Bases: ScalableAttribute

Class for providing scalable attributes in need of being calculated.

`init(keyword)`

Parameters:

Name	Type	Description	Default
`keyword`	`str`	the keyword for the calculation	required

`CustomSequential`

Bases: Sequential

Class for scaling value based on custom function.

`init(scalable_attribute_strategy, *, scale='lin', **kwargs)`

Parameters:

Name	Type	Description	Default
`*`			required
`in_range`		tuple of the min and max values of the set before normalization	required
`out_range`		tuple of the min and max values of the final scale	required
`fallback`		v value set to None	required
`scalable_attribute_strategy`	`ScalableAttribute`	ScalableAttribute	required
`custom_scale`		user determined custom scale	required
`post_processor`		function applied to the values after scaling (e.g.	required

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

`FixedValue`

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 determined by the mapping strategy.

`InherentScalableAttribute`

Bases: ScalableAttribute

Class for inherent graph element values.

Inherent graph elements are graph attributes already set in the source graph.

`init(keyword)`

Parameters:

Name	Type	Description	Default
`keyword`	`str`	the key of the inherent attribute	required

`Qualitative`

Bases: GenericMapping

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

`init(attribute_key, mapping=None, *, cmap=None)`

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

Parameters:

Name	Type	Description	Default
`attribute_key`	`str \| Code`	str The keyword under which the graph element attribute is stored	required
`mapping`	`Mapping \| None`	Mapping: The mapping with the keys as the values of the graph element attribute	`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

`ScalableAttribute`

Bases: ABC

Basic interface for graph element values based on scaleable attributes.

`Sequential`

Bases: GenericMapping, ABC

Abstract class for getting visual attributes according to different scales.

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

`init(scalable_attribute_strategy, *, out_range, in_range=None, fallback=None, post_processor=lambda : x)`

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`
`scalable_attribute_strategy`	`ScalableAttribute`	strategy for handling the type of attribute (whether it is calculated	required
`post_processor`	`Callable`	function applied to the values after scaling (e.g. colormapping, conversion)	`lambda : x`

`get(graph_element, graph)`

Get the values by normalizing the values then applying the scale.

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

`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

`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

`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 inherent or calculated values.

Parameters:

Name	Type	Description	Default
`*`			required
`attr`	`str`	str name of either inherent or calculated attribute for the scale	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
	CustomSequential

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

mapping

dsstools.mapping

CalculatedScalableAttribute

__init__(keyword)

CustomSequential

__init__(scalable_attribute_strategy, *, scale='lin', **kwargs)

also(preprocessor)

FixedValue

get(graph_element, graph)

GenericMapping

get(graph_element, graph) abstractmethod

InherentScalableAttribute

__init__(keyword)

Qualitative

__init__(attribute_key, mapping=None, *, cmap=None)

get(graph_element, graph)

ScalableAttribute

Sequential

__get_in_range(values)

__init__(scalable_attribute_strategy, *, out_range, in_range=None, fallback=None, post_processor=lambda : x)

get(graph_element, graph)

fixed(value)

parse_color(value)

parse_colormap(cmap, acceptable_colormaps)

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

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

`dsstools.mapping`

`CalculatedScalableAttribute`

`init(keyword)`

`CustomSequential`

`init(scalable_attribute_strategy, *, scale='lin', **kwargs)`

`also(preprocessor)`

`FixedValue`

`get(graph_element, graph)`

`GenericMapping`

`get(graph_element, graph)` `abstractmethod`

`InherentScalableAttribute`

`init(keyword)`

`Qualitative`

`init(attribute_key, mapping=None, *, cmap=None)`

`get(graph_element, graph)`

`ScalableAttribute`

`Sequential`

`__get_in_range(values)`

`init(scalable_attribute_strategy, *, out_range, in_range=None, fallback=None, post_processor=lambda : x)`

`get(graph_element, graph)`

`fixed(value)`

`parse_color(value)`

`parse_colormap(cmap, acceptable_colormaps)`

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

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