Enable project sharing with Cosmograph app via new export API

.gitignore

@@ -121,3 +121,4 @@ node_modules
 meta.json
 
 cosmograph/widget/static
+.cosmograph_cache

README.md

@@ -153,6 +153,64 @@ Zooming in a bit:
 
 ![image](https://github.com/user-attachments/assets/e988950d-9f53-40c2-8b77-18cfb92efb50)
 
+## 🔑 API Key Setup and Project Export
+
+### Setting up API Key
+
+If you have a Cosmograph API key, you can set it globally to authenticate with Cosmograph services:
+
+```python
+from cosmograph import set_api_key
+
+# Set your API key globally (this will apply to all cosmograph instances)
+set_api_key("your-api-key-here")
+```
+
+Once set, all cosmograph widgets will automatically use this API key for authentication.
+
+### Exporting Projects to Cosmograph Platform
+
+You can export your cosmograph visualization as a project to the [Cosmograph platform](https://run.cosmograph.app), making it accessible via a web interface for sharing and further collaboration.
+
+```python
+import pandas as pd
+from cosmograph import cosmo, set_api_key
+
+# Set your API key first
+set_api_key("your-api-key-here")
+
+# Create your visualization
+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]
+})
+
+graph = 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'
+)
+
+# Export to Cosmograph platform
+graph.export_project_by_name("My Network Visualization")
+```
+
+The exported project will be available on the [Cosmograph platform](https://run.cosmograph.app).
+
+
 ## 🎉 More Examples
 
 Try out the Cosmograph widget in Google Colab with these example notebooks:

cosmograph/__init__.py

@@ -25,6 +25,7 @@
 
 from cosmograph.base import cosmo, base_cosmo
 from cosmograph.widget import Cosmograph
+from cosmograph.config import set_api_key, get_api_key
 
 from importlib.metadata import version, PackageNotFoundError
 

cosmograph/_dev_utils/data/config_prep/parsed_types.json

@@ -228,7 +228,7 @@
                         "optional": true
                     },
                     {
-                        "name": "simulationCluster",
+                        "name": "simulationClusterStrength",
                         "type": "number",
                         "description": "Cluster coefficient. Default `0.1`.",
                         "optional": true
@@ -728,13 +728,6 @@
                         "optional": true,
                         "default": "100"
                     },
-                    {
-                        "name": "showTopLabelsBy",
-                        "type": "string",
-                        "description": "Specify the numeric column that is used to determine the top points that will be sorted by. Works only when `pointLabelBy` is provided.",
-                        "optional": true,
-                        "default": "undefined"
-                    },
                     {
                         "name": "pointLabelFn",
                         "type": "AccessorFn<string>",

cosmograph/base.py

@@ -13,6 +13,8 @@
     cosmograph_base_signature,
 )
 
+from cosmograph.config import get_api_key
+
 cosmo_base_sig = cosmograph_base_signature()
 cosmo_base_params_doc_str = cosmograph_base_docs()
 
@@ -133,7 +135,7 @@ def cosmo(
     point_size_by: str = None,
     point_color_by: str = None,
     point_color_palette: list[str] = None,
-    point_color_by_map: list[list[Union[str, list[float]]]] = None,
+    point_color_by_map: Dict[str, Union[str, list[float]]] = None,
     point_color_strategy: str = None,
     point_label_by: str = None,
     point_color: Union[str, list[float]] = None,
@@ -144,6 +146,7 @@ def cosmo(
     point_id_by: str = None,
     point_index_by: str = None,
     point_size_range: list[float] = None,
+    point_size_strategy: str = None,
     point_label_weight_by: str = None,
     point_cluster_by: str = None,
     point_cluster_strength_by: str = None,
@@ -210,7 +213,6 @@ def cosmo(
     show_labels_for: list[str] = None,
     show_top_labels: bool = None,
     show_top_labels_limit: int = None,
-    show_top_labels_by: str = None,
     static_label_weight: float = None,
     dynamic_label_weight: float = None,
     label_margin: float = None,
@@ -219,6 +221,7 @@ def cosmo(
     disable_link_width_legend: bool = None,
     disable_point_color_legend: bool = None,
     disable_link_color_legend: bool = None,
+    api_key: str = None,
     clicked_point_index: int = None,
     clicked_point_id: str = None,
     selected_point_indices: list[int] = None,
@@ -296,6 +299,12 @@ def cosmo(
     # validate the kwargs
     kwargs = validate_kwargs(kwargs)
 
+    # If api_key is None, use the global one if available
+    if kwargs.get('api_key') is None:
+        global_api_key = get_api_key()
+        if global_api_key is not None:
+            kwargs['api_key'] = global_api_key
+
     # Make a Cosmograph widget instance with these kwargs
     return Cosmograph(**kwargs)
 

cosmograph/config.py

@@ -0,0 +1,51 @@
+"""Configuration settings for cosmograph."""
+
+# Global API key variable
+_GLOBAL_API_KEY = None
+_COSMOGRAPH_INSTANCES = set()
+
+
+def set_api_key(api_key: str) -> None:
+    """
+    Set a global API key to be used by all cosmograph instances.
+
+    Args:
+        api_key: The API key to use
+    """
+    global _GLOBAL_API_KEY
+    _GLOBAL_API_KEY = api_key
+
+    # Update API key for all existing instances
+    for instance in _COSMOGRAPH_INSTANCES:
+        instance.api_key = api_key
+
+
+def get_api_key() -> str:
+    """
+    Get the current global API key.
+
+    Returns:
+        The current global API key, or None if not set
+    """
+    return _GLOBAL_API_KEY
+
+
+def register_instance(instance) -> None:
+    """
+    Register a cosmograph instance to receive API key updates.
+
+    Args:
+        instance: A Cosmograph instance
+    """
+    _COSMOGRAPH_INSTANCES.add(instance)
+
+
+def unregister_instance(instance) -> None:
+    """
+    Unregister a cosmograph instance.
+
+    Args:
+        instance: A Cosmograph instance
+    """
+    if instance in _COSMOGRAPH_INSTANCES:
+        _COSMOGRAPH_INSTANCES.remove(instance)

cosmograph/data/params_ssot.json

@@ -5,6 +5,40 @@
         "annotation":"bool",
         "description":"Prevents the simulation from running, merely rendering the graph."
     },
+    {
+        "name":"select_point_on_click",
+        "default": null,
+        "annotation":"bool",
+        "description":"Controls whether to select a clicked point with the connected points."
+    },
+    {
+        "name":"select_point_on_label_click",
+        "default": null,
+        "annotation":"bool",
+        "description":"Controls whether to select a point with the connected points when the point's label is clicked."
+    },
+    {
+        "name":"focus_point_on_click",
+        "default": null,
+        "annotation":"bool",
+        "description":"Controls whether to focus on a point when the point itself is clicked."
+    },
+    {
+        "name":"focus_point_on_label_click",
+        "default": null,
+        "annotation":"bool",
+        "description":"Controls whether to focus on a point when the point's label is clicked."
+    },
+    {
+        "name":"components_display_state_mode",
+        "default": null,
+        "annotation":"bool",
+        "description":"Controls display state messages behavior for all Cosmograph components."
+    },
+
+
+
+
     {
         "name":"simulation_decay",
         "default":1000,
@@ -75,10 +109,10 @@
         "description":"Sets simulation friction."
     },
     {
-        "name":"simulation_cluster",
+        "name":"simulation_cluster_strength",
         "default":null,
         "annotation":"float",
-        "description":""
+        "description":"Coefficient of simulation cluster strength from 0 to 1. If `undefined`, the graph will not apply any clustering force to the simulation."
     },
     {
         "name":"background_color",
@@ -234,7 +268,7 @@
         "description":"Activates quadtree algorithm for Many-Body force when set to True."
     },
     {
-        "name":"show_FPS_monitor",
+        "name":"show_fps_monitor",
         "default":false,
         "annotation":"bool",
         "description":"Display an FPS counter in the upper right corner of the canvas."
@@ -338,7 +372,7 @@
     {
         "name":"point_color_by_map",
         "default":null,
-        "annotation":"list[list[typing.Union[str, list[float]]]]",
+        "annotation":"typing.Dict[str, typing.Union[str, list[float]]]",
         "description":"An optional mapping of values to colors for the points in the visualization. The keys in the map should be string and the values can be either color strings or arrays of RGBA values. Used when point_color_strategy is set to `'map'`."
     },
     {
@@ -359,6 +393,12 @@
         "annotation":"list[float]",
         "description":""
     },
+    {
+        "name":"point_size_strategy",
+        "default":null,
+        "annotation":"str",
+        "description":"Specifies the strategy for sizing points based on data from the point_size_by column."
+    },
     {
         "name":"point_label_by",
         "default":null,
@@ -498,34 +538,70 @@
         "description":"Maximum number of top points to show labels for."
     },
     {
-        "name":"show_top_labels_by",
+        "name":"show_cluster_labels",
+        "default":false,
+        "annotation":"bool",
+        "description":"Show labels for the clusters based on the `pointClusterBy` column. When any point is selected, cluster labels will be hidden until the selection is cleared."
+    },
+    {
+        "name":"show_focused_point_label",
+        "default":null,
+        "annotation":"bool",
+        "description":"Controls whether to show the label for the focused point."
+    },
+    {
+        "name":"point_label_color",
         "default":null,
         "annotation":"str",
-        "description":"Column to determine which points are considered as a top."
+        "description":"Specifies the CSS color to use for the point labels."
+    },
+    {
+        "name":"point_label_font_size",
+        "default":13,
+        "annotation":"float",
+        "description":"Specifies the font size to use for the point labels."
+    },
+    {
+        "name":"cluster_label_font_size",
+        "default":16,
+        "annotation":"float",
+        "description":"Specifies the font size to use for the cluster labels."
+    },
+    {
+        "name":"scale_cluster_labels",
+        "default":true,
+        "annotation":"bool",
+        "description":"Whether to scale the cluster labels based on the number of points in the cluster."
     },
     {
         "name":"static_label_weight",
-        "default":null,
+        "default":0.8,
         "annotation":"float",
-        "description":"Weight of static labels."
+        "description":"Specifies the weight of the static labels."
     },
     {
         "name":"dynamic_label_weight",
-        "default":null,
+        "default":0.7,
         "annotation":"float",
-        "description":"Weight of dynamic labels."
+        "description":"Specifies the weight of the dynamic labels."
     },
     {
         "name":"label_margin",
-        "default":null,
+        "default":5,
         "annotation":"float",
-        "description":""
+        "description":"Specifies the margin between the label and the point."
+    },
+    {
+        "name":"label_padding",
+        "default":[6.5, 4.5, 6.5, 4.5],
+        "annotation":"list[float]",
+        "description":"Specifies the [left, top, right, bottom] padding of the label element."
     },
     {
         "name":"show_hovered_point_label",
-        "default":null,
+        "default":false,
         "annotation":"bool",
-        "description":"Flag to display the label for the currently hovered point."
+        "description":"Whether to show a hovered point label."
     },
     {
         "name":"disable_point_size_legend",
@@ -598,5 +674,11 @@
         "default":null,
         "annotation":"typing.Callable[[typing.Dict[str, typing.Any]], typing.Any]",
         "description":""
+    },
+    {
+        "name":"api_key",
+        "default":null,
+        "annotation":"str",
+        "description":"API key for authenticating with Cosmograph services. Can be set globally using set_api_key() function."
     }
 ]