# 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
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_include_columns=['value'],
point_label_by='label',
link_include_columns=['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=0.01, # often have to play with this number to get the size right
)
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.01, # often have to play with this number to get the size right
)
h
```
Zooming in a bit:
## 🎉 More Examples
Try out the Cosmograph widget in Google Colab with these example notebooks:
- [Cosmograph Widget (Colab notebook) ✌️](https://colab.research.google.com/drive/1d0Gsn6KlCNCjPp8n8fpm82ctBpARasVX)
- [Mobius in Cosmograph Widget (Colab notebook)🎗️](https://colab.research.google.com/drive/1-FlUSyRAgdhXT6rNyi3uYrIIlGX8gRuk)
- [Clusters in Cosmograph (Colab notebook) 🫧](https://colab.research.google.com/drive/1Rt8rmmeMuWyFjEqae2DdJ3NYymtjC9cT)
- [English Words 🔤](https://colab.research.google.com/drive/1jZ2tPJw4gHpTCJVwCggRPWLmasfJIjPc?usp=sharing)
## 🛸 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/12/25/1a98dfb00d3dd4fc685482049c4a6fc5863a1548a0b8fd9f3319a1cb4b7b/cosmograph-0.0.27.tar.gz",
"platform": "any",
"description": "\n# 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## \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\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_include_columns=['value'],\n point_label_by='label',\n link_include_columns=['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=0.01, # often have to play with this number to get the size right\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.01, # often have to play with this number to get the size right\n)\nh\n```\n\n\n\nZooming in a bit:\n\n\n\n\n## \ud83c\udf89 More Examples\n\nTry out the Cosmograph widget in Google Colab with these example notebooks:\n\n- [Cosmograph Widget (Colab notebook) \u270c\ufe0f](https://colab.research.google.com/drive/1d0Gsn6KlCNCjPp8n8fpm82ctBpARasVX)\n- [Mobius in Cosmograph Widget (Colab notebook)\ud83c\udf97\ufe0f](https://colab.research.google.com/drive/1-FlUSyRAgdhXT6rNyi3uYrIIlGX8gRuk)\n- [Clusters in Cosmograph (Colab notebook) \ud83e\udee7](https://colab.research.google.com/drive/1Rt8rmmeMuWyFjEqae2DdJ3NYymtjC9cT)\n- [English Words \ud83d\udd24](https://colab.research.google.com/drive/1jZ2tPJw4gHpTCJVwCggRPWLmasfJIjPc?usp=sharing)\n\n\n## \ud83d\udef8 Issues and Feedback\n\nSubmit issues to https://github.com/cosmograph-org/py_cosmograph/issues.\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",
"bugtrack_url": null,
"license": "GPL",
"summary": "Visualize large-scale network graphs and machine learning embeddings",
"version": "0.0.27",
"project_urls": {
"Homepage": "https://github.com/cosmograph-org/py_cosmograph"
},
"split_keywords": [
"graph",
" embedding",
" network",
" visualization",
" machine learning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0e23f0436d7d7b55e8199673cc0a6bd4b5bea70849848734d0ece34f2ac060af",
"md5": "d35b0bb0cd4be2c9405197cc06d291f7",
"sha256": "56052c4f265d332a6dee0f31db654a19c146e2892ea4002bd719bf71b974002c"
},
"downloads": -1,
"filename": "cosmograph-0.0.27-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d35b0bb0cd4be2c9405197cc06d291f7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 82854,
"upload_time": "2024-12-20T00:09:29",
"upload_time_iso_8601": "2024-12-20T00:09:29.627782Z",
"url": "https://files.pythonhosted.org/packages/0e/23/f0436d7d7b55e8199673cc0a6bd4b5bea70849848734d0ece34f2ac060af/cosmograph-0.0.27-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "12251a98dfb00d3dd4fc685482049c4a6fc5863a1548a0b8fd9f3319a1cb4b7b",
"md5": "84865d8ec43607a458c1aebc28070426",
"sha256": "6df0feb31bd503f41664b5270d14d98d9be23220bf0faebd5ea41151407f47fb"
},
"downloads": -1,
"filename": "cosmograph-0.0.27.tar.gz",
"has_sig": false,
"md5_digest": "84865d8ec43607a458c1aebc28070426",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 78419,
"upload_time": "2024-12-20T00:09:31",
"upload_time_iso_8601": "2024-12-20T00:09:31.028082Z",
"url": "https://files.pythonhosted.org/packages/12/25/1a98dfb00d3dd4fc685482049c4a6fc5863a1548a0b8fd9f3319a1cb4b7b/cosmograph-0.0.27.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-20 00:09:31",
"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
