Complex Encodings: Icons

Concepts

The complex icons encodings section of a create dataset call provides fine-grained icon controls. The glyph can be set to icons, flags, text, and custom images through direct or mapped assignments.

Mappings from node/edge values to visual glyphs may be categorical, such as for mapping country names to flags, and continuous, such as for mapping wide score intervals to a few warning icons. By default, if a value is not defined by the mapping, no icon will be shown. Field other may be specified to define an alternative default mapping, such as showing a question mark. The same glyph can be applied to all elements by specifying an empty mapping with a default of choice.

Icon encodings are designed to work with other encodings. For example, icon encodings are often used alongside encodings for point colors, point sizes, and badges. Likewise, when used as a categorical mapping over a column named type, the legend will show the icon in its main area.

Default and current encodings

See primary discussion of default vs. current encodings.

Icons demo

Mapping categorical values to icon glyphs

{
    "name": "my graph",
    "metadata": {},
    "edge_encodings": { "bindings": {"source": "s", "destination": "d"} },
    "node_encodings": {
        "bindings": {"node": "n"},
        "complex": {
            "default": {
                "pointIconEncoding": {
                    "graphType": "point",
                    "encodingType": "icon",
                    "attribute": "type",
                    "variation": "categorical",
                    "mapping": {
                        "categorical": {
                            "fixed": {
                                "macbook": "laptop",
                                "mac": "server"
                            },
                            "other": "question"
                        }
                    }
                }
            }
        }
    }
}

Mapping categorical values to flags

{
    "name": "my graph",
    "metadata": {},
    "edge_encodings": { "bindings": {"source": "s", "destination": "d"} },
    "node_encodings": {
        "bindings": {"node": "n"},
        "complex": {
            "default": {
                "pointIconEncoding": {
                    "graphType": "point",
                    "encodingType": "icon",
                    "attribute": "type",
                    "variation": "categorical",
                    "mapping": {
                        "categorical": {
                            "fixed": {
                                "America": "flags-icon-us",
                                "Canada": "flags-icon-ca"
                            },
                            "other": "question"
                        }
                    }
                }
            }
        }
    }
}

Mapping categorical values to text

{
    "name": "my graph",
    "metadata": {},
    "edge_encodings": { "bindings": {"source": "s", "destination": "d"} },
    "node_encodings": {
        "bindings": {"node": "n"},
        "complex": {
            "default": {
                "pointIconEncoding": {
                    "graphType": "point",
                    "encodingType": "icon",
                    "attribute": "type",
                    "variation": "categorical",
                    "as_text": true,
                    "mapping": {
                        "categorical": {
                            "fixed": {
                                "America": "US",
                                "Canada": "CA"
                            }
                        }
                    }
                }
            }
        }
    }
}

Mapping categorical values to images that are external and embedded

{
    "name": "my graph",
    "metadata": {},
    "edge_encodings": { "bindings": {"source": "s", "destination": "d"} },
    "node_encodings": {
        "bindings": {"node": "n"},
        "complex": {
            "default": {
                "pointIconEncoding": {
                    "graphType": "point",
                    "encodingType": "icon",
                    "attribute": "type",
                    "variation": "categorical",
                    "mapping": {
                        "categorical": {
                            "fixed": {
                                "mac": "https://cdn.mos.cms.futurecdn.net/a89992626a0bf98e5f9030af8584b26e-970-80.jpg.webp",
                                "macbook": "data:image/svg+xml;base64,PHN2ZyBoZWlnaHQ9JzMwMHB4JyB3aWR0aD0nMzAwcHgnICBmaWxsPSIjMDAwMDAwIiB4bWxuczp4PSJodHRwOi8vbnMuYWRvYmUuY29tL0V4dGVuc2liaWxpdHkvMS4wLyIgeG1sbnM6aT0iaHR0cDovL25zLmFkb2JlLmNvbS9BZG9iZUlsbHVzdHJhdG9yLzEwLjAvIiB4bWxuczpncmFwaD0iaHR0cDovL25zLmFkb2JlLmNvbS9HcmFwaHMvMS4wLyIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWxuczp4bGluaz0iaHR0cDovL3d3dy53My5vcmcvMTk5OS94bGluayIgdmVyc2lvbj0iMS4xIiB4PSIwcHgiIHk9IjBweCIgdmlld0JveD0iMCAwIDEwMCAxMDAiIGVuYWJsZS1iYWNrZ3JvdW5kPSJuZXcgMCAwIDEwMCAxMDAiIHhtbDpzcGFjZT0icHJlc2VydmUiPjxzd2l0Y2g+PGZvcmVpZ25PYmplY3QgcmVxdWlyZWRFeHRlbnNpb25zPSJodHRwOi8vbnMuYWRvYmUuY29tL0Fkb2JlSWxsdXN0cmF0b3IvMTAuMC8iIHg9IjAiIHk9IjAiIHdpZHRoPSIxIiBoZWlnaHQ9IjEiPjwvZm9yZWlnbk9iamVjdD48ZyBpOmV4dHJhbmVvdXM9InNlbGYiPjxnPjxwb2x5Z29uIGZpbGw9IiMwMDAwMDAiIHN0cm9rZT0iIzAwMDAwMCIgc3Ryb2tlLW1pdGVybGltaXQ9IjEwIiBwb2ludHM9IjIwMy44NzUsOC4xNDEgMTcxLjAwNCw3MS40MjIgMTQxLjM4MywxMC44MjYgICAgICAxMzMuNzEzLDcuMjEzIDEzMy43MTMsLTIuMDA1IDIwMy4wNTksLTQuNSAgICAiPjwvcG9seWdvbj48Zz48cGF0aCBmaWxsPSIjMDAwMDAwIiBzdHJva2U9IiMwMDAwMDAiIHN0cm9rZS13aWR0aD0iNi41OTcxIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiIHN0cm9rZS1taXRlcmxpbWl0PSIxMCIgZD0iICAgICAgTTIwNi4yODMsNy4yMTNjMCwxLjM3OS0xLjQ0MywyLjQ5Ni0zLjIyNSwyLjQ5NmgtNjYuMTIxYy0xLjc4MSwwLTMuMjI1LTEuMTE3LTMuMjI1LTIuNDk2di05LjIxOCAgICAgIGMwLTEuMzc4LDEuNDQzLTIuNDk1LDMuMjI1LTIuNDk1aDY2LjEyMWMxLjc4MSwwLDMuMjI1LDEuMTE3LDMuMjI1LDIuNDk1VjcuMjEzeiI+PC9wYXRoPjxwb2x5Z29uIGZpbGw9IiMwMDAwMDAiIHN0cm9rZT0iIzAwMDAwMCIgc3Ryb2tlLXdpZHRoPSI2LjU5NzEiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCIgc3Ryb2tlLW1pdGVybGltaXQ9IjEwIiBwb2ludHM9IiAgICAgIDE3MS4wMDQsMTAuMzM5IDIwMC44NTIsMTAuMzM5IDE4NS45MjgsNDEuODkyIDE3MS4wMDQsNzMuNDQ0IDE1Ni4wNzgsNDEuODkyIDE0MS4xNTIsMTAuMzM5ICAgICAiPjwvcG9seWdvbj48Zz48ZGVmcz48cG9seWdvbiBpZD0iYiIgcG9pbnRzPSIxNzEuMDA0LDguMzE3IDIwMC44NTIsOC4zMTYgMTg1LjkyOCwzOS44NjkgMTcxLjAwNCw3MS40MjIgMTU2LjA3OCwzOS44NjkgMTQxLjE1Miw4LjMxNiAgICAgICAgICAgICAgICI+PC9wb2x5Z29uPjwvZGVmcz48Y2xpcFBhdGggaWQ9ImEiPjx1c2UgeGxpbms6aHJlZj0iI2IiIG92ZXJmbG93PSJ2aXNpYmxlIj48L3VzZT48L2NsaXBQYXRoPjxjaXJjbGUgY2xpcC1wYXRoPSJ1cmwoI2EpIiBmaWxsPSIjMDAwMDAwIiBzdHJva2U9IiMwMDAwMDAiIHN0cm9rZS13aWR0aD0iNi41OTcxIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiIHN0cm9rZS1taXRlcmxpbWl0PSIxMCIgY3g9IjE1Ni43NDciIGN5PSIyOS45NTgiIHI9IjcuODg4Ij48L2NpcmNsZT48Y2lyY2xlIGNsaXAtcGF0aD0idXJsKCNhKSIgZmlsbD0iIzAwMDAwMCIgc3Ryb2tlPSIjMDAwMDAwIiBzdHJva2Utd2lkdGg9IjYuNTk3MSIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIiBzdHJva2UtbWl0ZXJsaW1pdD0iMTAiIGN4PSIxODUuNjgxIiBjeT0iMjUuMjI2IiByPSI3Ljg4OCI+PC9jaXJjbGU+PGNpcmNsZSBjbGlwLXBhdGg9InVybCgjYSkiIGZpbGw9IiMwMDAwMDAiIHN0cm9rZT0iIzAwMDAwMCIgc3Ryb2tlLXdpZHRoPSI2LjU5NzEiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCIgc3Ryb2tlLW1pdGVybGltaXQ9IjEwIiBjeD0iMTcxLjAwMiIgY3k9IjU0Ljg4OCIgcj0iNy44ODkiPjwvY2lyY2xlPjx1c2UgeGxpbms6aHJlZj0iI2IiIG92ZXJmbG93PSJ2aXNpYmxlIiBmaWxsPSIjMDAwMDAwIiBzdHJva2U9IiMwMDAwMDAiIHN0cm9rZS1taXRlcmxpbWl0PSIxMCI+PC91c2U+PC9nPjwvZz48L2c+PGc+PHBhdGggZD0iTTk2Ljk1MSw1Mi4xNzNjLTAuMjc1LTAuNjc4LTAuOTE5LTEuMTE1LTEuNjY5LTEuMTE0bC0yMi4yNjgtMC4wNzNjMC4xMTksMS4yMywwLjE1NywyLjQ0OSwwLjExNywzLjU3bDE3LjY3MSwwLjEwNyAgICAgbC0xNy44MywxNy4wMTVoLTIuMTc4Yy0wLjI3NSwwLjM5LTAuNjA1LDAuNjE4LTEsMC42MThIMTQuMzgyYy0xLjY4MywwLjQyNC0zLjQyNiwwLjY0My01LjI3LDAuNTMgICAgIGMtMC4xODQtMC4wMTItMC4zNTktMC4wNTQtMC41MzEtMC4xMTJjLTAuMTc2LDAuMzc3LTAuMjMyLDAuODA4LTAuMTE0LDEuMjNjMC4yMTUsMC43NzEsMC45MTgsMS4zMDUsMS43MTksMS4zMDVoNjMuNTAzICAgICBjMC40NTgsMCwwLjktMC4xNzcsMS4yMzItMC40OTNsMjEuNjA3LTIwLjYyQzk3LjA1OCw1My42Myw5Ny4yMjUsNTIuODUyLDk2Ljk1MSw1Mi4xNzN6Ij48L3BhdGg+PC9nPjxnPjxwYXRoIGQ9Ik03Mi43ODEsNzYuMDIxSDQuNzA1Yy0wLjk4NiwwLTEuNzg2LTAuNzk5LTEuNzg2LTEuNzg1VjI1Ljc2NWMwLTAuOTg2LDAuOC0xLjc4NiwxLjc4Ni0xLjc4Nmg2OC4wNzcgICAgIGMwLjk4NywwLDEuNzg2LDAuOCwxLjc4NiwxLjc4NnY0OC40NzJDNzQuNTY3LDc1LjIyMyw3My43NjksNzYuMDIxLDcyLjc4MSw3Ni4wMjF6IE02LjQ5LDcyLjQ1aDY0LjUwNnYtNDQuOUg2LjQ5VjcyLjQ1eiI+PC9wYXRoPjwvZz48Zz48Zz48cGF0aCBkPSJNMzkuNDY2LDYzLjg3MWMtNS43MzQtMC4wMDEtMTAuNDA4LTQuNjY2LTEwLjQyMS0xMC40Yy0wLjAwNi0yLjc4NSwxLjA3My01LjQwNCwzLjAzNy03LjM3OCAgICAgIGMxLjk2NS0xLjk3Myw0LjU4LTMuMDYyLDcuMzY0LTMuMDY4YzIuODk1LDAsNS42NjcsMS4yMDMsNy42MzIsMy4zMDFjMC4zOTQsMC40MjEsMC41NjEsMS4wMDYsMC40NDcsMS41NzEgICAgICBjLTAuMTEzLDAuNTY1LTAuNDkyLDEuMDQxLTEuMDE4LDEuMjc3Yy0xLjQwOCwwLjYzMy0yLjMxNSwyLjAzNi0yLjMxMiwzLjU3NGMwLjAwNCwxLjc2OCwxLjIwMiwzLjMxNywyLjkxNCwzLjc2OCAgICAgIGMwLjU1OCwwLjE0NiwxLjAxLDAuNTU1LDEuMjE1LDEuMDk0YzAuMjA1LDAuNTQsMC4xMzUsMS4xNDYtMC4xODUsMS42MjRjLTEuOTM3LDIuODk3LTUuMTY5LDQuNjMyLTguNjQ5LDQuNjM4ICAgICAgQzM5LjQ4OSw2My44NzEsMzkuNDY3LDYzLjg3MSwzOS40NjYsNjMuODcxeiBNMzkuNDcsNDYuNTk1Yy0xLjg0NywwLjAwNC0zLjU2NiwwLjcyMS00Ljg1OCwyLjAxOCAgICAgIGMtMS4yOTEsMS4yOTgtMiwzLjAyLTEuOTk2LDQuODUyYzAuMDA4LDMuNzcsMy4wODEsNi44MzYsNi44NTEsNi44MzZsMCwxLjc4NmwwLjAxNy0xLjc4NmMxLjU2OC0wLjAwMiwzLjA2MS0wLjUzOSw0LjI1NS0xLjQ5MSAgICAgIGMtMS45MDYtMS4zNzMtMy4xMDktMy42MDMtMy4xMTQtNi4wNTNjLTAuMDA1LTIuMDE4LDAuODA4LTMuOTEzLDIuMTg3LTUuMjk2QzQxLjgwNCw0Ni44OTUsNDAuNjY0LDQ2LjU5NSwzOS40Nyw0Ni41OTV6Ij48L3BhdGg+PC9nPjxnPjxnPjxsaW5lIHgxPSI0MC45MjciIHkxPSIzNC43MDMiIHgyPSIzOC4zMyIgeTI9IjQxLjA3MyI+PC9saW5lPjwvZz48Zz48cGF0aCBkPSJNNDAuOTI3LDM0LjcwM2MwLDAsMC4xMDMsMC4xNTcsMC4yMTUsMC40MDdjMC4xMTcsMC4yNSwwLjI0MiwwLjU5MiwwLjMzMiwwLjk3N2MwLjE3OSwwLjc3LDAuMTI5LDEuNjc4LTAuMTkzLDIuNDc1ICAgICAgIGMtMC4zMjIsMC43OTgtMC45MiwxLjQ4Mi0xLjU4NywxLjkwN2MtMC4zMzQsMC4yMTItMC42NjQsMC4zNjgtMC45MjMsMC40NjVjLTAuMjU2LDAuMDk5LTAuNDQxLDAuMTQtMC40NDEsMC4xNCAgICAgICBzLTAuMTA0LTAuMTU4LTAuMjE3LTAuNDA4Yy0wLjExOC0wLjI1MS0wLjI0NS0wLjU5My0wLjMzNS0wLjk3OGMtMC4xOC0wLjc3MS0wLjEyOC0xLjY3OCwwLjE5OS0yLjQ3MyAgICAgICBjMC4zMjYtMC43OTcsMC45MjYtMS40OCwxLjU5Mi0xLjkwNWMwLjMzMy0wLjIxMywwLjY2Mi0wLjM2OSwwLjkyLTAuNDY3QzQwLjc0MywzNC43NDMsNDAuOTI3LDM0LjcwMyw0MC45MjcsMzQuNzAzeiI+PC9wYXRoPjwvZz48L2c+PC9nPjwvZz48L3N3aXRjaD48L3N2Zz4="
                            },
                            "other": "question"
                        }
                    }
                }
            }
        }
    }
}

Mapping continuous values to icons

{
    "name": "my graph",
    "metadata": {},
    "edge_encodings": { "bindings": {"source": "s", "destination": "d"} },
    "node_encodings": {
        "bindings": {"node": "n"},
        "complex": {
            "default": {
                "pointIconEncoding": {
                    "graphType": "point",
                    "encodingType": "icon",
                    "attribute": "score",
                    "variation": "continuous",
                    "mapping": {
                        "continuous": {
                            "bins": [
                                [20, 'info'],
                                [80, 'exclamation-circle'],
                                [null, 'exclamation-triangle']
                            ],
                            "other": "question"
                        }
                    }
                }
            }
        }
    }
}

Complex icons encodings schema

Structure

Note the syntax switch from node to point:

{
    ["node_encodings" | "edge_encodings"]: {
        "complex": {
            ["default" | "current"]: {
                "(point|edge)IconEncoding": {
                    "graphType": "point" | "edge",
                    "encodingType": "icon",
                    "attribute": String,
                    ?"asText": Boolean,
                    ...( FixedMapping<Glyph> | ContinuousMapping<Glyph> )
                }
            }
        }
    }
}

Mapping: Categorical<T>

Map specific values, with an optional default:

{
    ?"attribute": String
    "variation": "categorical",
    "mapping": {
        "categorical": {
            "fixed": {
                [String]: T
            },
            ?"other": T
        }
    }
}

Mapping: Continuous<T>

Map value ranges, with optional comparator and default. If the last value range bin specifics null for the comparator, values above the previous sentinels will map to the last bin. This enables mapping unexpectedly high values to the last bin, while null values may be handled separately via an other mapping.

{
    ?"attribute": String,
    "variation": "continuous",
    "mapping": {
        "continuous": {
            "bins": [
                [Comparable | null, T]
            ],
            ?"other": T
        }
    }
}

Glyphs

Glyphs are automatically inferred based on their string value:

• Flag: flag-icon-(a-z){2} (ISO3611-Alpha-2 country code)
• Icon: fa-(a-z0-9-)+ (Font Awesome 4 icon values)
• Image URL (link): http[s]://.*
• Data URI (embedding): data:.* (learn more about data URIs)
• If none of the above match, Graphistry will prepend fa- and treat the value as an icon

To use uninterpreted text values, disable glyph inference by setting "asText": true