Enable project sharing with Cosmograph app via new export API

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."
     }
 ]

cosmograph/widget/__init__.py

@@ -4,9 +4,13 @@
 
 import pyarrow as pa
 import anywidget
-from traitlets import Bool, Float, List, Int, Unicode, Union, Bytes, Any, observe
+from traitlets import Bool, Float, List, Int, Unicode, Union, Bytes, Any, observe, Dict
+
+from .export_project import export_project
+from cosmograph.config import register_instance, unregister_instance, get_api_key
 
 meta_path = pathlib.Path(__file__).parent / "static" / "meta.json"
+
 try:
     with open(meta_path) as f:
         meta_data = json.load(f)
@@ -107,13 +111,14 @@ class Cosmograph(anywidget.AnyWidget):
     point_color_palette = List(Unicode, default_value=None, allow_none=True).tag(
         sync=True
     )
-    point_color_by_map = List(
-        List(Union([Unicode(), List(Float())])), default_value=None, allow_none=True
+    point_color_by_map = Dict(
+        Unicode(), Union([Unicode(), List(Float())]), default_value=None, allow_none=True
     ).tag(sync=True)
     point_color_strategy = Unicode(None, allow_none=True).tag(sync=True)
 
     point_size_by = Unicode(None, allow_none=True).tag(sync=True)
     point_size_range = List(Float, default_value=None, allow_none=True).tag(sync=True)
+    point_size_strategy = Unicode(None, allow_none=True).tag(sync=True)
     point_label_by = Unicode(None, allow_none=True).tag(sync=True)
     point_label_weight_by = Unicode(None, allow_none=True).tag(sync=True)
     point_x_by = Unicode(None, allow_none=True).tag(sync=True)
@@ -142,7 +147,7 @@ class Cosmograph(anywidget.AnyWidget):
 
     show_labels = Bool(None, allow_none=True).tag(sync=True)
     show_dynamic_labels = Bool(None, allow_none=True).tag(sync=True)
-    show_labels_for = List(Unicode, allow_none=True).tag(sync=True)
+    show_labels_for = List(Unicode, default_value=None, allow_none=True).tag(sync=True)
     show_top_labels = Bool(None, allow_none=True).tag(sync=True)
     show_top_labels_limit = Int(None, allow_none=True).tag(sync=True)
     show_top_labels_by = Unicode(None, allow_none=True).tag(sync=True)
@@ -174,6 +179,9 @@ class Cosmograph(anywidget.AnyWidget):
     clicked_point_id = Unicode(None, allow_none=True).tag(sync=True)
     selected_point_indices = List(Int, allow_none=True).tag(sync=True)
     selected_point_ids = List(Unicode, allow_none=True).tag(sync=True)
+    cosmograph_config = Dict(default_value={}, allow_none=True).tag(sync=True)
+
+    api_key = Unicode(None, allow_none=True)
 
     # Convert a Pandas DataFrame into a binary format and then write it to an IPC (Inter-Process Communication) stream.
     # The `with` statement ensures that the IPC stream is properly closed after writing the data.
@@ -273,3 +281,22 @@ def step(self):
 
     def capture_screenshot(self):
         self.send({"type": "capture_screenshot"})
+
+    def export_project_by_name(self, project_name: str):
+        export_project(self.api_key, project_name, self.points, self.links, self.cosmograph_config)
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        # Register this instance to receive API key updates
+        register_instance(self)
+
+        # If no API key was provided but global one exists, use it
+        if self.api_key is None:
+            global_api_key = get_api_key()
+            if global_api_key is not None:
+                self.api_key = global_api_key
+
+    def __del__(self):
+        # Clean up by unregistering when the instance is deleted
+        unregister_instance(self)
+        super().__del__()