Complex Encodings: Colors and Sizes

Concepts

The complex encodings section of a create dataset call provides more control over encodings like colors and introduces new ones.

Color & size demo: Mapping categorical and continuous values

A complex mapping defines how to map either specific entity values (categorical) or how to automatically interpolate a range (continuous).

The following example maps the categorical node.payment column ("big", "normal", ...) to fixed point sizes, and it defaults to 100 for unexpected values. It also maps the continuous node.time column to a color gradient of blue-to-red (cold-to-hot). The sizes are a fixed mapping over categorical values: only 4 sizes will be displayed on screen. In contrast, the time-column-driven coloring uses a color gradient over continuous time values: it will map time values to colors anywhere between blue and yellow or between yellow and red.

{
    "name": "my graph",
    "metadata": {},
    "edge_encodings": { "bindings": {"source": "s", "destination": "d"} },
    "node_encodings": {
        "bindings": {"node": "n"},
        "complex": {
            "default": {
                "pointSizeEncoding": {
                    "graphType": "point",
                    "encodingType": "size",
                    "attribute": "payment",
                    "variation": "categorical",
                    "mapping": {
                        "fixed": {
                            "big": 500,
                            "normal": 200,
                            "tiny": 10 
                        },
                        "other": 100
                    }
                }
                "pointColorEncoding": {
                    "graphType": "point",
                    "encodingType": "color",
                    "attribute": "time",
                    "variation": "continuous",
                    "colors": ["blue", "yellow", "red"]
                }
            }
        }
    }
}

Default and current encodings

Complex encodings are nested under either a current or default section:

• current: The actively set dynamic set encoding, such as when a user manually sets a color encoding
• default: When an active encoding gets cleared, such as when a user disables an encoding, the default encoding to activate

In the below example, the default point size encoding is set to column payment. The result is that, on page load, the active risk encoding is used. In addition, the active encoding is set to column risk. If the user or an API client then clears out the active size encoding (payment), or changes the size encoding to something else and then clears out their choice, the default encoding of payment will be found and activated.

If no current encoding is set, the default will be used. The typical case is to only specify a defaultencoding. It would be used both for page load default and for what to return to upon clearing a current encoding. Specifying a current encoding is more useful for API scenarios like dashboards with switchable palette modes.

{
    "name": "my graph",
    "metadata": {},
    "edge_encodings": { "bindings": {"source": "s", "destination": "d"} },
    "node_encodings": {
        "bindings": {"node": "n"},
        "complex": {
            "default": {
                "pointSizeEncoding": {
                    "graphType": "point",
                    "encodingType": "size",
                    "attribute": "payment",
                    "variation": "categorical",
                    "mapping": {
                        "fixed": {
                            "big": 500,
                            "normal": 200,
                            "tiny": 10 
                        },
                        "other": 100
                    }
                }
            },
            "current": {
                "pointSizeEncoding": {
                    "graphType": "point",
                    "encodingType": "size",
                    "attribute": "risk",
                    "variation": "categorical",
                    "mapping": {
                        "fixed": {
                            "big": 500,
                            "normal": 200,
                            "tiny": 10 
                        },
                        "other": 100
                    }
                }
            }
        }
    }
}

Complex encodings schema

Structure

Color encoding schema

{
    ["node_encodings" | "edge_encodings"]: {
        ?"complex": {
            ?["default" | "current"]: {
                ?"(point|edge)ColorEncoding": {
                    ?"graphType": "point" | "edge",
                    ?"encodingType": "color",
                    "attribute": String,
                    ...( FixedMapping<Color> | ContinuousColorMapping )
                }
            }
        }
    }
}

Size encoding schema

{
    ["node_encodings" | "edge_encodings"]: {
        ?"complex": {
            ?["default" | "current"]: {
                ?"pointSizeEncoding": {
                    ?"graphType": "point",
                    ?"encodingType": "size",
                    "attribute": String,
                    ...( FixedMapping<Integer> )
                }
            }
        }
    }
}

Mapping: Categorical<T>

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

Mapping: ContinuousColorMapping

{
    "variation": "continuous",
    "colors": [ Color ] # ex: ["red", "rgb(0, 0, 255)", "#FF0000"]
}