paroto.viz.utils
================

.. py:module:: paroto.viz.utils

.. autoapi-nested-parse::

   Utility functions for visualization module.



Functions
---------

.. autoapisummary::

   paroto.viz.utils.get_simple_label
   paroto.viz.utils.get_subsystem_name
   paroto.viz.utils.serialize_value
   paroto.viz.utils.deduplicate_nodes_by_label
   paroto.viz.utils.deduplicate_edges


Module Contents
---------------

.. py:function:: get_simple_label(full_name)

   Extract simplified label from dotted variable name.

   :param full_name: Full variable name (e.g., "vedef.breakdown.voltage")
   :type full_name: :py:class:`str`

   :returns: Simplified label (e.g., "voltage")
   :rtype: :py:class:`str`

   .. rubric:: Examples

   >>> get_simple_label("vedef.breakdown.voltage")
   'voltage'
   >>> get_simple_label("simple_var")
   'simple_var'


.. py:function:: get_subsystem_name(full_name)

   Extract subsystem name from dotted variable name.

   :param full_name: Full variable name (e.g., "vedef.breakdown.voltage")
   :type full_name: :py:class:`str`

   :returns: Subsystem name (e.g., "vedef.breakdown") or 'root' if no subsystem
   :rtype: :py:class:`str`

   .. rubric:: Examples

   >>> get_subsystem_name("vedef.breakdown.voltage")
   'vedef.breakdown'
   >>> get_subsystem_name("simple_var")
   'root'


.. py:function:: serialize_value(value)

   Convert value to string, handling arrays.

   :param value: Value to serialize
   :type value: :py:class:`Any`

   :returns: String representation of value
   :rtype: :py:class:`str`


.. py:function:: deduplicate_nodes_by_label(nodes, levels, max_level = None)

   Deduplicate nodes with same label, preferring primary params.

   When multiple nodes have the same simplified label (e.g., multiple
   "gap_distance" nodes from different subsystems), keeps only one
   canonical representative.

   :param nodes: Mapping of node_id -> node attributes
   :type nodes: :py:class:`dict`
   :param levels: Mapping of node_id -> hierarchy level
   :type levels: :py:class:`dict`
   :param max_level: Maximum level to include
   :type max_level: :py:class:`int`, *optional*

   :returns: (deduplicated_nodes, node_to_canonical, deduplicated_by_level)
             - deduplicated_nodes: dict of canonical nodes
             - node_to_canonical: mapping from any node to its canonical version
             - deduplicated_by_level: dict of level -> list of canonical node_ids
   :rtype: :py:class:`tuple`


.. py:function:: deduplicate_edges(edges, node_to_canonical, displayed_nodes)

   Deduplicate edges using canonical node mapping.

   :param edges: Original (source, target) edges
   :type edges: :py:class:`list` of :py:class:`tuple`
   :param node_to_canonical: Mapping from node_name to canonical node_name
   :type node_to_canonical: :py:class:`dict`
   :param displayed_nodes: Set of node IDs actually being displayed
   :type displayed_nodes: :py:class:`set`

   :returns: Deduplicated (canonical_source, canonical_target) edges
   :rtype: :py:class:`list` of :py:class:`tuple`