# Cosmograph
The **Cosmograph Widget** brings the power of Cosmograph's GPU-accelerated force layout graph visualization right into your Jupyter notebooks. Built on top of [Anywidget](https://anywidget.dev/), this widget provides a seamless, interactive graph exploration experience directly within your data science workflow, making it easier than ever to visualize complex data relationships and embeddings.
## ✨ Key Features
- **Interactive Visualization**: Pan, zoom, select, and hover to explore large, complex network graphs right in your notebook.
- **GPU-Acceleration**: Powered by [@cosmograph/cosmos](http://github.com/cosmograph-org/cosmos), it delivers smooth interactions and rapid rendering of large-scale graphs.
- **Seamless Integration**: Embeds naturally into Jupyter notebooks, JupyterLab, and other notebook-based environments.
- **Rich Configuration API**: Fine-tune graph appearance, behavior, and layout parameters through easy-to-use Python APIs.
## 🚀 Installation
Note: You'll need python 3.10 or greater.
To install the Cosmograph widget, simply run:
```sh
pip install cosmograph
```
Once installed, you can start using it in your notebooks immediately.
[](https://pypi.org/project/cosmograph/)
## 🛠️ Quick Start
After installation, you can import and use the widget in any Python-based notebook environment:
### Tiny example
```python
import pandas as pd
from cosmograph import cosmo
points = pd.DataFrame({
'id': [1, 2, 3, 4, 5],
'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': [1, 2, 3, 1, 2],
'target': [2, 3, 4, 5, 4],
'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_size_by='value'
)
widget
```
The widget will render an interactive graph visualization inline, allowing you to
explore and manipulate your data directly.
You also use the widget object to interact with the rendered graph.
```python
widget.fit_view() # recenter the view (often useful when you've lost your graph (or within your graph)
widget.selected_point_ids # if you've selected some points and want to get info about the selection...
# etc.
```
### Nicer example
Let's download a big dataset of English words, plus some hyponym-hypernym relationships.
(A hyponym-hypernym relationship is a “type-of” relationship where a hyponym is a more
specific term (e.g., “dog”) and a hypernym is a broader term (e.g., “animal”).)
```python
import pandas as pd
from cosmograph import cosmo
df = pd.read_parquet('https://www.dropbox.com/scl/fi/4mnk1e2wx31j9mdsjzecy/wordnet_feature_meta.parquet?rlkey=ixjiiso80s1uk4yhx1v38ekhm&dl=1')
hyponyms = pd.read_parquet('https://www.dropbox.com/scl/fi/pl72ixv34soo1o8zanfrz/hyponyms.parquet?rlkey=t4d606fmq1uinn29qmli7bx6r&dl=1')
```
Peep at the data:
```python
print(f"{df.shape=}")
df.iloc[0]
```
```python
print(f"{hyponyms.shape=}")
hyponyms.iloc[0]
```
Let's plot the data using the [UMAP projection](https://umap-learn.readthedocs.io/en/latest/)
of the (OpenAI) [embeddings](https://www.deepset.ai/blog/the-beginners-guide-to-text-embeddings)
of the words, coloring by "part-of-speech" and sizing by the usage frequency of the word.
```python
g = cosmo(
df,
point_id_by='lemma',
point_label_by='word',
point_x_by='umap_x',
point_y_by='umap_y',
point_color_by='pos',
point_size_by='frequency',
point_size_scale=6, # often have to play with this number to get the size right
disable_point_size_legend=True
)
g
```
Zooming in a bit:
And now, let's put some hypernym-hyponym links, and let the network converge to a stable
layout using a force-directed simulation (try it yourself, the convergence is pretty!)
```python
h = cosmo(
points=df,
links=hyponyms,
link_source_by='source',
link_target_by='target',
point_id_by='lemma',
point_label_by='word',
# point_x_by='umap_x',
# point_y_by='umap_y',
point_color_by='pos',
point_size_by='frequency',
point_size_scale=0.2, # often have to play with this number to get the size right
disable_point_size_legend=True
)
h
```
Zooming in a bit:
## 🎉 More Examples
Try out the Cosmograph widget in Google Colab with these example notebooks:
- [Timeline in Cosmograph Widget ⏳](https://colab.research.google.com/drive/1fK7SLsoMFiDt9_42z9W7jo0z43yCL-CR)
- [Real-Time Data Exploration with Cosmograph Widget 🪄](https://colab.research.google.com/drive/1bL3hcPbP2xPuxrtgmYaTU_hChCrdCp2Q)
- [Mobius in Cosmograph Widget 🎗️](https://colab.research.google.com/drive/1-FlUSyRAgdhXT6rNyi3uYrIIlGX8gRuk)
- [Clusters in Cosmograph 🫧](https://colab.research.google.com/drive/1Rt8rmmeMuWyFjEqae2DdJ3NYymtjC9cT)
- [English Words 🔤](https://colab.research.google.com/drive/1TocOW1ZkwwDapNTY0F-lBGmhrs7BtIPK)
## 🛸 Issues and Feedback
Submit issues to https://github.com/cosmograph-org/py_cosmograph/issues.
## 👩🏻🚀 Contact and More Info
🌎 [Website](https://cosmograph.app)
📩 [Email](mailto:hi@cosmograph.app)
👾 [Join the Cosmograph Discord Community](https://discord.gg/Rv8RUQuzsx)
Raw data
{
"_id": null,
"home_page": "https://github.com/cosmograph-org/py_cosmograph",
"name": "cosmograph",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Graph, Embedding, Network, Visualization, Machine Learning",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ce/c3/c657e50b6a4da97918c6a10b9d1fc4b9560c33bb0b1f8efe6edcc9476aeb/cosmograph-0.0.45.tar.gz",
"platform": "any",
"description": "# Cosmograph\n\nThe **Cosmograph Widget** brings the power of Cosmograph's GPU-accelerated force layout graph visualization right into your Jupyter notebooks. Built on top of [Anywidget](https://anywidget.dev/), this widget provides a seamless, interactive graph exploration experience directly within your data science workflow, making it easier than ever to visualize complex data relationships and embeddings.\n\n\n## \u2728 Key Features\n\n- **Interactive Visualization**: Pan, zoom, select, and hover to explore large, complex network graphs right in your notebook.\n- **GPU-Acceleration**: Powered by [@cosmograph/cosmos](http://github.com/cosmograph-org/cosmos), it delivers smooth interactions and rapid rendering of large-scale graphs.\n- **Seamless Integration**: Embeds naturally into Jupyter notebooks, JupyterLab, and other notebook-based environments.\n- **Rich Configuration API**: Fine-tune graph appearance, behavior, and layout parameters through easy-to-use Python APIs.\n\n## \ud83d\ude80 Installation\n\nNote: You'll need python 3.10 or greater. \n\nTo install the Cosmograph widget, simply run:\n\n```sh\npip install cosmograph\n```\n\nOnce installed, you can start using it in your notebooks immediately.\n\n[](https://pypi.org/project/cosmograph/)\n\n\n## \ud83d\udee0\ufe0f Quick Start\n\nAfter installation, you can import and use the widget in any Python-based notebook environment:\n\n### Tiny example\n\n```python\nimport pandas as pd\nfrom cosmograph import cosmo\n\npoints = pd.DataFrame({\n 'id': [1, 2, 3, 4, 5],\n 'label': ['Node A', 'Node B', 'Node C', 'Node D', 'Node E'],\n 'value': [10, 20, 15, 25, 30],\n 'category': ['A', 'B', 'A', 'B', 'A']\n})\n\nlinks = pd.DataFrame({\n 'source': [1, 2, 3, 1, 2],\n 'target': [2, 3, 4, 5, 4],\n 'value': [1.0, 2.0, 1.5, 0.5, 1.8]\n})\n\nwidget = cosmo(\n points=points,\n links=links,\n point_id_by='id',\n link_source_by='source',\n link_target_by='target',\n point_color_by='category',\n point_label_by='label',\n point_size_by='value'\n)\nwidget\n```\n\nThe widget will render an interactive graph visualization inline, allowing you to \nexplore and manipulate your data directly. \n\n\n\nYou also use the widget object to interact with the rendered graph.\n\n```python\nwidget.fit_view() # recenter the view (often useful when you've lost your graph (or within your graph)\nwidget.selected_point_ids # if you've selected some points and want to get info about the selection...\n# etc.\n```\n\n### Nicer example\n\nLet's download a big dataset of English words, plus some hyponym-hypernym relationships. \n(A hyponym-hypernym relationship is a \u201ctype-of\u201d relationship where a hyponym is a more \nspecific term (e.g., \u201cdog\u201d) and a hypernym is a broader term (e.g., \u201canimal\u201d).)\n\n```python\nimport pandas as pd\nfrom cosmograph import cosmo\n\ndf = pd.read_parquet('https://www.dropbox.com/scl/fi/4mnk1e2wx31j9mdsjzecy/wordnet_feature_meta.parquet?rlkey=ixjiiso80s1uk4yhx1v38ekhm&dl=1')\nhyponyms = pd.read_parquet('https://www.dropbox.com/scl/fi/pl72ixv34soo1o8zanfrz/hyponyms.parquet?rlkey=t4d606fmq1uinn29qmli7bx6r&dl=1')\n```\n\nPeep at the data:\n\n```python\nprint(f\"{df.shape=}\")\ndf.iloc[0]\n```\n\n```python\nprint(f\"{hyponyms.shape=}\")\nhyponyms.iloc[0]\n```\n\nLet's plot the data using the [UMAP projection](https://umap-learn.readthedocs.io/en/latest/) \nof the (OpenAI) [embeddings](https://www.deepset.ai/blog/the-beginners-guide-to-text-embeddings)\nof the words, coloring by \"part-of-speech\" and sizing by the usage frequency of the word.\n\n```python\ng = cosmo(\n df,\n point_id_by='lemma',\n point_label_by='word',\n point_x_by='umap_x',\n point_y_by='umap_y',\n point_color_by='pos',\n point_size_by='frequency',\n point_size_scale=6, # often have to play with this number to get the size right\n disable_point_size_legend=True\n)\ng\n```\n\n\n\nZooming in a bit:\n\n\n\n\nAnd now, let's put some hypernym-hyponym links, and let the network converge to a stable \nlayout using a force-directed simulation (try it yourself, the convergence is pretty!)\n\n```python\nh = cosmo(\n points=df,\n links=hyponyms,\n link_source_by='source',\n link_target_by='target',\n point_id_by='lemma',\n point_label_by='word',\n # point_x_by='umap_x',\n # point_y_by='umap_y',\n point_color_by='pos',\n point_size_by='frequency',\n point_size_scale=0.2, # often have to play with this number to get the size right\n disable_point_size_legend=True\n)\nh\n```\n\n\n\nZooming in a bit:\n\n\n\n## \ud83c\udf89 More Examples\n\nTry out the Cosmograph widget in Google Colab with these example notebooks:\n\n- [Timeline in Cosmograph Widget \u23f3](https://colab.research.google.com/drive/1fK7SLsoMFiDt9_42z9W7jo0z43yCL-CR)\n- [Real-Time Data Exploration with Cosmograph Widget \ud83e\ude84](https://colab.research.google.com/drive/1bL3hcPbP2xPuxrtgmYaTU_hChCrdCp2Q)\n- [Mobius in Cosmograph Widget \ud83c\udf97\ufe0f](https://colab.research.google.com/drive/1-FlUSyRAgdhXT6rNyi3uYrIIlGX8gRuk)\n- [Clusters in Cosmograph \ud83e\udee7](https://colab.research.google.com/drive/1Rt8rmmeMuWyFjEqae2DdJ3NYymtjC9cT)\n- [English Words \ud83d\udd24](https://colab.research.google.com/drive/1TocOW1ZkwwDapNTY0F-lBGmhrs7BtIPK)\n\n\n## \ud83d\udef8 Issues and Feedback\n\nSubmit issues to https://github.com/cosmograph-org/py_cosmograph/issues.\n\n\n## \ud83d\udc69\ud83c\udffb\u200d\ud83d\ude80 Contact and More Info\n\n\ud83c\udf0e\u00a0[Website](https://cosmograph.app)\n\n\ud83d\udce9\u00a0[Email](mailto:hi@cosmograph.app)\n\n\ud83d\udc7e\u00a0[Join the Cosmograph Discord Community](https://discord.gg/Rv8RUQuzsx)\n\n",
"bugtrack_url": null,
"license": "GPL",
"summary": "Visualize large-scale network graphs and machine learning embeddings",
"version": "0.0.45",
"project_urls": {
"Homepage": "https://github.com/cosmograph-org/py_cosmograph"
},
"split_keywords": [
"graph",
" embedding",
" network",
" visualization",
" machine learning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "902a8a517eda65aaa5965559f0334b2ff3554c7f7d6bf63acd5f24bbd07f00ef",
"md5": "2bff669a83677e24db4f134641d62792",
"sha256": "1dc222a476ba0809a95b89c746e626aa824938d13168bbaa6f81ccdcbed300f9"
},
"downloads": -1,
"filename": "cosmograph-0.0.45-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2bff669a83677e24db4f134641d62792",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 32204,
"upload_time": "2025-02-14T12:53:21",
"upload_time_iso_8601": "2025-02-14T12:53:21.861012Z",
"url": "https://files.pythonhosted.org/packages/90/2a/8a517eda65aaa5965559f0334b2ff3554c7f7d6bf63acd5f24bbd07f00ef/cosmograph-0.0.45-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cec3c657e50b6a4da97918c6a10b9d1fc4b9560c33bb0b1f8efe6edcc9476aeb",
"md5": "c908767e3f10d0ea6098babb6b55250f",
"sha256": "80f97bd4def47cb331c28045c4e83098c6512ec4d438bc3c0e7a8a59a4ce6b12"
},
"downloads": -1,
"filename": "cosmograph-0.0.45.tar.gz",
"has_sig": false,
"md5_digest": "c908767e3f10d0ea6098babb6b55250f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 33010,
"upload_time": "2025-02-14T12:53:23",
"upload_time_iso_8601": "2025-02-14T12:53:23.584415Z",
"url": "https://files.pythonhosted.org/packages/ce/c3/c657e50b6a4da97918c6a10b9d1fc4b9560c33bb0b1f8efe6edcc9476aeb/cosmograph-0.0.45.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-14 12:53:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cosmograph-org",
"github_project": "py_cosmograph",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cosmograph"
}
JSON
