KeplerEncoding

KeplerEncoding#

Immutable container for complete Kepler.gl configuration.

class graphistry.kepler.KeplerEncoding(datasets=None, layers=None, options=None, config=None)#

Bases: object

Immutable container for complete Kepler.gl configuration.

Combines datasets, layers, options, and config into a complete Kepler visualization configuration. Follows an immutable builder pattern where methods return new instances rather than modifying in place.

Parameters:

  • datasets (Optional[List[KeplerDataset]]) – List of dataset configurations

  • layers (Optional[List[KeplerLayer]]) – List of layer configurations

  • options (Optional[KeplerOptions]) – Visualization options

  • config (Optional[KeplerConfig]) – Map configuration settings

Example: Building configuration with method chaining
from graphistry import KeplerEncoding, KeplerDataset, KeplerLayer

encoding = (
    KeplerEncoding()
    .with_dataset(KeplerDataset(id="companies", type="nodes"))
    .with_dataset(KeplerDataset(id="relationships", type="edges"))
    .with_layer(KeplerLayer({
        "id": "points",
        "type": "point",
        "config": {
            "dataId": "companies",
            "columns": {"lat": "latitude", "lng": "longitude"}
        }
    }))
    .with_options(center_map=True, read_only=False)
    .with_config(cull_unused_columns=True)
)
Example: Using with Plotter
import graphistry

g = graphistry.nodes(df, 'id')
g = g.encode_kepler(encoding)
g.plot()
to_dict()#

Serialize to dictionary format for Kepler.gl.

Returns:

Dictionary with datasets, layers, options, and config

Return type:

Dict[str, Any]

with_config(config: KeplerConfig) → KeplerEncoding#
with_config(config: None = None, *, cull_unused_columns: bool | None = None, overlay_blending: Literal['normal', 'additive', 'subtractive'] | None = None, tile_style: Dict[str, Any] | None = None, auto_graph_renderer_switching: bool | None = None) → KeplerEncoding

Return a new KeplerEncoding with updated config.

Parameters:

  • config (Optional[KeplerConfig]) – KeplerConfig object to replace current config

  • cull_unused_columns (Optional[bool]) – Remove columns not used by layers

  • overlay_blending (Optional[Literal['normal', 'additive', 'subtractive']]) – Blend mode - ‘normal’, ‘additive’, ‘subtractive’

  • tile_style (Optional[Dict[str, Any]]) – Base map tile style configuration

  • auto_graph_renderer_switching (Optional[bool]) – Enable automatic graph renderer switching

Returns:

New KeplerEncoding instance with updated config

Return type:

KeplerEncoding

with_dataset(dataset)#

Return a new KeplerEncoding with the dataset appended.

Parameters:

dataset (KeplerDataset) – KeplerDataset to append

Returns:

New KeplerEncoding instance with the dataset added

Return type:

KeplerEncoding

with_layer(layer)#

Return a new KeplerEncoding with the layer appended.

Parameters:

layer (KeplerLayer) – KeplerLayer to append

Returns:

New KeplerEncoding instance with the layer added

Return type:

KeplerEncoding

with_options(options: KeplerOptions) → KeplerEncoding#
with_options(options: None = None, *, center_map: bool | None = None, read_only: bool | None = None) → KeplerEncoding

Return a new KeplerEncoding with updated options.

Parameters:

  • options (Optional[KeplerOptions]) – KeplerOptions object to replace current options

  • center_map (Optional[bool]) – Auto-center map on data

  • read_only (Optional[bool]) – Disable map interactions

Returns:

New KeplerEncoding instance with updated options

Return type:

KeplerEncoding

Examples#

Basic Configuration#

from graphistry import KeplerEncoding, KeplerDataset, KeplerLayer

# Start with empty encoding
encoding = KeplerEncoding()

# Add dataset
encoding = encoding.with_dataset(
    KeplerDataset(id="nodes", type="nodes", label="Companies")
)

# Add layer
encoding = encoding.with_layer(
    KeplerLayer({
        "id": "point-layer",
        "type": "point",
        "config": {
            "dataId": "nodes",
            "columns": {"lat": "latitude", "lng": "longitude"}
        }
    })
)

# Configure options
encoding = encoding.with_options(center_map=True, read_only=False)

# Apply to graph
g = g.encode_kepler(encoding)

Chained Builder Pattern#

from graphistry import KeplerEncoding, KeplerDataset, KeplerLayer

# Chain multiple operations
encoding = (
    KeplerEncoding()
    .with_dataset(KeplerDataset(id="companies", type="nodes"))
    .with_dataset(KeplerDataset(id="relationships", type="edges"))
    .with_layer(KeplerLayer({
        "id": "nodes",
        "type": "point",
        "config": {"dataId": "companies", "columns": {"lat": "latitude", "lng": "longitude"}}
    }))
    .with_layer(KeplerLayer({
        "id": "edges",
        "type": "arc",
        "config": {
            "dataId": "relationships",
            "columns": {
                "lat0": "edgeSourceLatitude",
                "lng0": "edgeSourceLongitude",
                "lat1": "edgeTargetLatitude",
                "lng1": "edgeTargetLongitude"
            }
        }
    }))
    .with_options(center_map=True)
    .with_config(cull_unused_columns=False)
)

g = g.encode_kepler(encoding)

Constructor Pattern#

from graphistry import KeplerEncoding, KeplerDataset, KeplerLayer

# Pass all components to constructor
encoding = KeplerEncoding(
    datasets=[
        KeplerDataset(id="nodes", type="nodes", label="Companies"),
        KeplerDataset(id="edges", type="edges", label="Relationships")
    ],
    layers=[
        KeplerLayer({"id": "point-layer", "type": "point", "config": {...}}),
        KeplerLayer({"id": "arc-layer", "type": "arc", "config": {...}})
    ],
    options=KeplerOptions(center_map=True, read_only=False),
    config=KeplerConfig(cull_unused_columns=False)
)

g = g.encode_kepler(encoding)

Multi-Layer Visualization#

# Create complex visualization with multiple layers
encoding = (
    KeplerEncoding()

    # Datasets
    .with_dataset(KeplerDataset(id="companies", type="nodes"))
    .with_dataset(KeplerDataset(id="relationships", type="edges", map_node_coords=True))
    .with_dataset(KeplerDataset(
        id="countries",
        type="countries",
        resolution=50,
        computed_columns={
            "avg_revenue": {
                "type": "aggregate",
                "computeFromDataset": "companies",
                "sourceKey": "country",
                "targetKey": "name",
                "aggregate": "mean",
                "aggregateCol": "revenue"
            }
        }
    ))

    # Layers
    .with_layer(KeplerLayer({
        "id": "companies-points",
        "type": "point",
        "config": {
            "dataId": "companies",
            "label": "Company Locations",
            "columns": {"lat": "latitude", "lng": "longitude"},
            "isVisible": True,
            "color": [255, 140, 0]
        }
    }))
    .with_layer(KeplerLayer({
        "id": "relationships-arcs",
        "type": "arc",
        "config": {
            "dataId": "relationships",
            "label": "Business Relationships",
            "columns": {
                "lat0": "edgeSourceLatitude",
                "lng0": "edgeSourceLongitude",
                "lat1": "edgeTargetLatitude",
                "lng1": "edgeTargetLongitude"
            },
            "isVisible": False,
            "color": [100, 200, 200],
            "visConfig": {"opacity": 0.2}
        }
    }))
    .with_layer(KeplerLayer({
        "id": "countries-geojson",
        "type": "geojson",
        "config": {
            "dataId": "countries",
            "label": "Countries by Avg Revenue",
            "columns": {"geojson": "_geometry"},
            "isVisible": True
        },
        "visualChannels": {
            "colorField": {"name": "avg_revenue", "type": "real"},
            "colorScale": "quantile"
        }
    }))

    # Options and config
    .with_options(center_map=True, read_only=False)
    .with_config(cull_unused_columns=False, overlay_blending="additive")
)

g = g.encode_kepler(encoding)

Serialization#

# Convert to dictionary for inspection or manual editing
encoding_dict = encoding.to_dict()

# Result structure:
# {
#     'datasets': [...],
#     'layers': [...],
#     'options': {...},
#     'config': {...}
# }

See Also#