Get started

The Cosmograph widget allows users to visualize complex data relationships directly in Jupyter notebooks, enhancing data analysis capabilities. Built on top of Anywidget, it integrates seamlessly within Jupyter environments, providing an interactive graphing experience.

Installation

Note: The Cosmograph widget requires Python 3.10+.

To install the Cosmograph widget, run:

pip install cosmograph

Quick Start

After installation, you can import and use the widget in any Python-based notebook environment:

import pandas as pd
from cosmograph import cosmo
 
points = pd.DataFrame({
    'id': ['node-A', 'node-B', 'node-C', 'node-D', 'node-E'],
    'label': ['Node A', 'Node B', 'Node C', 'Node D', 'Node E'],
    'value': [10, 20, 15, 25, 30],
    'category': ['A', 'B', 'A', 'B', 'A']
})
 
links = pd.DataFrame({
    'source': ['node-A', 'node-B', 'node-C', 'node-A', 'node-B'],
    'target': ['node-B', 'node-C', 'node-D', 'node-E', 'node-D'],
    'value': [1.0, 2.0, 1.5, 0.5, 1.8]
})
 
widget = cosmo(
  points=points,
  links=links,
  point_id_by='id',
  link_source_by='source',
  link_target_by='target',
  point_color_by='category',
  point_label_by='label',
  point_include_columns=['value'],
  link_include_columns=['value'],
)
widget

The widget will render an interactive graph visualization inline, allowing you to explore and manipulate your data directly.

For all available configuration options, see Configuration. To learn about programmatic interaction methods, see Methods and Values.

You can also use the widget object to interact with the rendered graph:

widget.fit_view()  # recenter the view (often useful when you've lost your graph)
widget.selected_point_ids  # get IDs of selected points

API Key Setup and Project Export

If you have a Cosmograph API key, set it globally and export your widget to the Cosmograph web application. For detailed export information, see Exporting Projects:

from cosmograph import set_api_key
 
# Set your API key (applies to all cosmograph instances)
set_api_key("your-api-key-here")
 
# Export your widget (created in Quick Start section above)
project_id = widget.export_project_by_name("My Network Visualization")
print(f"Project available at: https://run.cosmograph.app/project/{project_id}")

Examples

Configuration