Configuration

The Cosmograph widget builds upon the native Cosmograph library, inheriting most of its configuration parameters, which are mostly optional and can be modified in real-time. For basic usage examples, see Get started. For detailed insights about configuration parameters, refer to the documentation.

The `data` Parameter

The data parameter is a convenience feature that automatically assigns your DataFrame to either points or links, reducing boilerplate code. The default resolution behavior uses prioritize_points, but you can customize this with the data_resolution parameter (see Advanced Features).

Resolution rules (default: “prioritize points”):

If data is provided and points is None:
- data → points
If data is provided and points already exists:
- data → links (only if links is None)
If both points and links are provided with data:
- Raises ValueError

Examples:

# Simple: data → points
widget = cosmo(data=df, point_id_by='id')
 
# With links: data → links
widget = cosmo(points=nodes_df, data=edges_df, point_id_by='id', link_source_by='source', link_target_by='target')
 
# Error: both points and links specified
widget = cosmo(points=df1, links=df2, data=df3)  # ❌ Raises ValueError

Minimal Configuration for Points

To render a graph, the following minimal configuration is required:

Parameter	Description
`points`	Data in a pandas DataFrame format
`point_id_by`	Unique identifier column for each point

Additional Points Configuration

Parameter	Description
`point_index_by`	Ordinal index of each point (0 to n)
`point_color_by`	Column name for point colors
`point_color_strategy`	Strategy for applying colors: `None` (auto), `'palette'`, `'interpolatePalette'`, `'map'`, `'degree'`, `'linkDirection'`, `'direct'`
`point_color_palette`	Array of color strings for palette strategies
`point_color_by_map`	Dictionary mapping values to colors (keys: string, values: `str` or `[r, g, b, a]`)
`point_color`	Default point color (when `point_color_by` not specified). Can be color string or `[r, g, b, a]` array
`point_size_by`	Column name for point sizes
`point_size_strategy`	Strategy for sizing points: `None` (auto), `'direct'`, `'degree'`
`point_size_range`	Range for automatic point size scaling `[min, max]`
`point_label_by`	Column name for point labels
`point_label_weight_by`	Column name for point label weights
`point_x_by`	Column name for x-coordinate
`point_y_by`	Column name for y-coordinate
`point_cluster_by`	Column name for point clusters
`point_cluster_strength_by`	Column defining cluster attraction strength
`cluster_positions_map`	Dictionary mapping cluster keys to `[x, y]` positions
`point_include_columns`	Additional column names to include in point data
`point_timeline_by`	Column name for timeline/date data

Minimal Configuration for Links

To define links, the following fields are necessary:

Parameter	Description
`links`	Data in a pandas DataFrame format
`link_source_by`	Column with unique identifier for source points
`link_target_by`	Column with unique identifier for target points (string or array for multi-target)

Additional Links Configuration

Parameter	Description
`link_source_index_by`	Index column of source point
`link_target_index_by`	Index column of target point
`link_color_by`	Column name for link colors
`link_width_by`	Column name for link widths
`link_arrow_by`	Column indicating links with arrows
`link_strength_by`	Column name for link strengths
`link_strength_range`	Range for automatic link strength scaling `[min, max]`
`link_include_columns`	Additional column names to include in link data
`link_timeline_by`	Column name for timeline/date data

Simulation Settings

Parameter	Description
`disable_simulation`	Prevents simulation from running, renders graph only
`simulation_decay`	How quickly the simulation cools down
`simulation_gravity`	Coefficient for gravity force
`simulation_center`	Centers the mass force coefficient
`simulation_repulsion`	Point repulsion between points
`simulation_repulsion_theta`	Granularity of Many-Body force (Barnes–Hut criterion when `use_quadtree: True`)
`simulation_link_spring`	Spring constant for links
`simulation_link_distance`	Default distance for links
`simulation_link_dist_random_variation_range`	Random link distance range `[min, max]`
`simulation_repulsion_from_mouse`	Mouse position repulsion coefficient (right-click)
`simulation_friction`	Simulation friction
`simulation_impulse`	Coefficient of simulation impulse (0 to 1)
`simulation_cluster`	Cluster coefficient

Graph Appearance

Parameter	Description
`background_color`	Canvas background color. Can be color string or `[r, g, b, a]` array
`space_size`	Size of the simulation space
`point_color`	Default point color (when `point_color_by` not specified). Can be color string or `[r, g, b, a]` array
`point_greyout_opacity`	Opacity of unselected nodes during selection
`point_size`	Default size value for points (when `point_size_by` not provided)
`point_size_scale`	Scale factor for point sizes
`point_sampling_distance`	Distance threshold for sampling points
`hovered_point_cursor`	Cursor type when hovering over a point
`render_hovered_point_ring`	Enable ring around hovered points
`hovered_point_ring_color`	Color of hovered point ring. Can be color string or `[r, g, b, a]` array
`focused_point_ring_color`	Color of focused point ring. Can be color string or `[r, g, b, a]` array
`focused_point_index`	Index of focused point (prioritized over `focus_point` method)
`render_links`	Enable or disable link rendering
`link_color`	Default link color (when `link_color_by` not specified). Can be color string or `[r, g, b, a]` array
`link_greyout_opacity`	Opacity of unselected links during selection
`link_width`	Default link width (when `link_width_by` not specified)
`link_width_scale`	Scale factor for link widths
`curved_links`	Enable or disable curved links
`curved_link_segments`	Segments defining curved links
`curved_link_weight`	Weight factor for link curvature
`curved_link_control_point_distance`	Control point positioning (1 = distance equal to line length)
`link_arrows`	Enable or disable arrows on links (when `link_arrow_by` not specified)
`link_arrows_size_scale`	Scale factor for link arrow size
`link_visibility_distance_range`	Pixel distance range for link transparency `[min, max]`
`link_visibility_min_transparency`	Minimum transparency of links
`scale_points_on_zoom`	Scale point sizes when zooming (default: `True`)
`scale_links_on_zoom`	Scale link widths when zooming
`initial_zoom_level`	Starting zoom level
`disable_zoom`	Enable or disable zooming
`enable_drag`	Allow graph dragging
`fit_view_on_init`	Automatically fit view to all points on init
`fit_view_delay`	Delay for fitting view after initialization (ms)
`fit_view_padding`	Padding around fit view area
`fit_view_duration`	Animation duration for view fitting (ms)
`fit_view_by_points_in_rect`	Fit view to specified rectangle of points `[[left, bottom], [right, top]]`

Labels

Parameter	Description
`show_labels`	Show labels (except hovered) on canvas
`show_dynamic_labels`	Show dynamic labels for visible points
`show_top_labels`	Display labels for top points
`show_top_labels_limit`	Maximum number of top points to show labels for
`show_labels_for`	Array of point IDs to show labels for
`static_label_weight`	Weight of static labels
`dynamic_label_weight`	Weight of dynamic labels
`label_margin`	Margin between label and point
`show_hovered_point_label`	Display label for hovered point (default: `True`)
`show_cluster_labels`	Display cluster labels
`point_label_color`	Color for point labels
`point_label_font_size`	Font size for point labels
`cluster_label_font_size`	Font size for cluster labels
`scale_cluster_labels`	Scale cluster labels
`label_padding`	Padding around labels as `[left, top, right, bottom]`
`use_point_color_strategy_for_cluster_labels`	Use point color strategy for cluster labels
`select_cluster_on_label_click`	Select cluster when its label is clicked

Additional Parameters

Parameter	Description
`show_fps_monitor`	Display FPS counter in upper right corner
`pixel_ratio`	Canvas pixel ratio
`random_seed`	Seed value for random number generation (can be `int` or `str`)
`polygonal_selector_stroke_color`	Color for polygonal selector stroke
`polygonal_selector_line_width`	Line width for polygonal selector
`select_point_on_click`	Behavior when clicking a point (`True`, `False`, or `'single'`)
`select_point_on_label_click`	Behavior when clicking a point label (`True`, `False`, or `'single'`)
`reset_selection_on_empty_canvas_click`	Reset selection when clicking empty canvas
`focus_point_on_click`	Focus point when clicked
`focus_point_on_label_click`	Focus point when its label is clicked
`components_display_state_mode`	Control display state of components (`'loading'`, `False`, or `None`)
`status_indicator_mode`	Control status indicator mode (`'spinner'`, `'text'`, `False`, or `None`)
`preserve_point_positions_on_data_update`	Preserve point positions when data is updated

Legends

Parameter	Description
`disable_point_color_legend`	Disable point color legend
`disable_point_size_legend`	Disable point size legend
`disable_link_color_legend`	Disable link color legend
`disable_link_width_legend`	Disable link width legend

These parameters are specific to the Python widget and control widget behavior or provide access to widget state.

Parameter	Description
`api_key`	API key for exporting projects to Cosmograph platform (can also be set globally with `set_api_key()`)
`clicked_point_index`	Index of clicked point (read-only attribute, see Methods and Values)
`clicked_point_id`	ID of clicked point (read-only attribute, see Methods and Values)
`selected_point_indices`	List of selected point indices (read-only attribute, see Methods and Values)
`selected_point_ids`	List of selected point IDs (read-only attribute, see Methods and Values)

Quadtree Algorithm Settings (Experimental)

Parameter	Description
`use_quadtree`	Activate quadtree algorithm for Many-Body force
`simulation_repulsion_quadtree_levels`	Barnes–Hut approximation depth (when `use_quadtree: True`)

To learn about programmatic control methods and attributes, see Methods and Values. For advanced features like partial functions, ingress system, and custom data resolution, see Advanced Features.

Get started Methods and Values