Methods and Values

The Cosmograph widget provides methods and attributes to control and interact with your visualizations. For basic usage examples, see Get started. For configuration options, see Configuration.

Selection Methods

Control which points are selected in the visualization.

Selecting Points

# Select a single point by ID or index
widget.select_point_by_id('node-A')
widget.select_point_by_index(0)
 
# Select multiple points
widget.select_points_by_ids(['node-A', 'node-B', 'node-C'])
widget.select_points_by_indices([0, 1, 2])
 
# Unselect specific points
widget.unselect_points_by_indices([0, 1])

Selection Modes

# Enable rectangular selection (users can drag to select)
widget.activate_rect_selection()
widget.deactivate_rect_selection()
 
# Enable polygonal/lasso selection
widget.activate_polygonal_selection()
widget.deactivate_polygonal_selection()
 
# Select points within a polygon (uses screen/pixel coordinates: 0 to canvas width/height)
polygon = [[0, 0], [100, 0], [100, 100], [0, 100]]
widget.select_points_in_polygon(polygon)

View Control Methods

Adjust the camera viewport and zoom position.

# Fit view to show all points (with optional duration and padding)
widget.fit_view()
widget.fit_view(duration=500, padding=0.1)
 
# Fit view to specific points (with optional duration and padding)
widget.fit_view_by_ids(['node-A', 'node-B'], duration=500, padding=0.1)
widget.fit_view_by_indices([0, 1, 2], duration=500, padding=0.1)
 
# Fit view to a coordinate region (flat array: [x0, y0, x1, y1, ...])
widget.fit_view_by_coordinates([-10, -10, 10, 10], duration=1000, padding=0.1)

Parameters (for all fit_view methods):

duration: Animation duration in milliseconds (optional, default: 250ms)
padding: Padding around fitted area as a fraction (optional, default: 0.1 = 10% padding)

Note on coordinate systems:

fit_view_by_coordinates() uses the space coordinate system - the same coordinate system where points are positioned (from simulation, or from point_x_by and point_y_by columns if specified).
select_points_in_polygon() uses screen/pixel coordinates (0 to canvas width/height), matching the viewport dimensions.

Focus Methods

Highlight a specific point by drawing a ring around it.

# Focus on a point by ID or index
widget.focus_point('node-A')
widget.focus_point_by_index(5)
 
# Clear focus
widget.focus_point(None)
widget.focus_point_by_index(None)

Simulation Control Methods

Control the force-directed simulation that positions points.

widget.start(alpha=1.0)  # Start simulation (alpha controls energy level)
widget.pause()           # Pause the simulation
widget.restart()         # Unpause/resume the simulation (continues from current state)
widget.step()            # Execute one simulation step

Other Methods

# Export visualization to Cosmograph web application (see Exporting Projects for details)
project_id = widget.export_project_by_name("My Project")  # Returns project_id (string)
print(f"Project URL: https://run.cosmograph.app/project/{project_id}")
 
# Capture a screenshot
widget.capture_screenshot()

Read the current state of the visualization and user interactions.

Selection State

# Get selected point IDs and indices
widget.selected_point_ids      # List of selected point IDs
widget.selected_point_indices  # List of selected point indices
widget.selected_link_indices   # List of selected link indices

Click State

# Get information about clicked point
widget.clicked_point_id    # ID of clicked point (or None)
widget.clicked_point_index # Index of clicked point (or None)
widget.clicked_cluster     # Information about clicked cluster (or None)

For exporting your visualizations to the Cosmograph web application, see Exporting Projects.

Configuration Advanced Features