hiveplotlib 0.26.2__py3-none-any.whl → 0.27.0__py3-none-any.whl

hiveplotlib/__init__.py

@@ -12,5 +12,9 @@ from hiveplotlib.hiveplot import (  # noqa: F401
     HivePlot,
     hive_plot_n_axes,
 )
+from hiveplotlib.hiveplot_matrix import (  # noqa: F401
+    HPM_SUPPORTED_VIZ_BACKENDS,
+    HivePlotMatrix,
+)
 from hiveplotlib.node import Node, NodeCollection  # noqa: F401
 from hiveplotlib.p2cp import P2CP, p2cp_n_axes  # noqa: F401

hiveplotlib/axis.py

@@ -6,6 +6,7 @@ Definition of ``Axis`` instance and helper static methods for generating and wor
 
 from typing import Hashable, Optional
 
+import numpy as np
 import pandas as pd
 
 from hiveplotlib.utils import polar2cartesian
@@ -93,7 +94,9 @@ class Axis:
         self.sorting_variable = None
 
         # hold all the cartesian coordinates, polar rho, corresponding labels, and node metadata in a pandas dataframe
-        self.node_placements = pd.DataFrame(columns=["x", "y", "unique_id", "rho"])
+        self.node_placements = pd.DataFrame(
+            columns=np.array(["x", "y", "unique_id", "rho"])
+        )
 
         # hold the current vmin and vmax used to place nodes on an axis in a ``HivePlot`` instance.
         self.vmin = None

hiveplotlib/converters.py

@@ -4,22 +4,22 @@
 Converters from various data structures to ``hiveplotlib``-ready structures.
 """
 
-from typing import Tuple
-
 import pandas as pd
 
-from hiveplotlib import Edges, Node, NodeCollection
-from hiveplotlib.node import node_collection_from_node_list
+from hiveplotlib import Edges, NodeCollection
 
-# say the graph type instead of calling `nx.Graph` to keep networkx dep out of this file.
-NetworkXGraph = "networkx.classes.graph.Graph instance"
+try:
+    import networkx as nx
+except ImportError as ie:  # pragma: no cover
+    msg = "`networkx` dependencies not installed, but can be installed by running `pip install hiveplotlib[networkx]`"
+    raise ImportError(msg) from ie
 
 
 def networkx_to_nodes_edges(
-    graph: NetworkXGraph,
+    graph: nx.Graph,
     unique_id_name: str = "unique_id",
     check_uniqueness: bool = True,
-) -> Tuple[NodeCollection, Edges]:  # type: ignore
+) -> tuple[NodeCollection, Edges]:
     """
     Take a ``networkx`` graph and return ``hiveplotlib``-friendly data structures.
 
@@ -31,11 +31,14 @@ def networkx_to_nodes_edges(
     :param check_uniqueness: whether or not to check that provided ``Node`` instances have unique IDs.
     :return: ``list`` of ``Node`` instances, ``(n, 2)`` ``np.ndarray`` of edges.
     """
-    nodes = [Node(unique_id=i, data=data) for i, data in list(graph.nodes.data())]
-    edge_keys = pd.DataFrame(list(graph.edges.keys()), columns=["from", "to"])
-    edge_values = pd.DataFrame(list(graph.edges.values()))
-    return node_collection_from_node_list(
-        node_list=nodes,
-        unique_id_name=unique_id_name,
+    node_data = []
+    for node, attributes in graph.nodes(data=True):
+        node_data.append({unique_id_name: node, **attributes})
+
+    node_df = pd.DataFrame(node_data)
+    edge_df = nx.to_pandas_edgelist(graph, source="from", target="to")
+    return NodeCollection(
+        data=node_df,
+        unique_id_column=unique_id_name,
         check_uniqueness=check_uniqueness,
-    ), Edges(data=edge_keys.join(edge_values))
+    ), Edges(data=edge_df)

hiveplotlib/datasets/international_trade.py

@@ -52,7 +52,7 @@ def international_trade_data(
     csv_years = [i.split("_")[2] for i in csv_files]
     csv_hs92 = [i.split("_")[-1] for i in csv_files]
     hiveplotlib_supported_values = pd.DataFrame(
-        np.c_[csv_years, csv_hs92], columns=["Year", "Trade Code"]
+        np.c_[csv_years, csv_hs92], columns=np.array(["Year", "Trade Code"])
     )
 
     # check that our implied data and metadata files exist

hiveplotlib/datasets/toy_hive_plots.py

@@ -13,6 +13,7 @@ from hiveplotlib import (
     NodeCollection,
     hive_plot_n_axes,
 )
+from hiveplotlib.datasets.international_trade import international_trade_data
 from hiveplotlib.edges import Edges
 from hiveplotlib.hiveplot import HivePlot
 from hiveplotlib.node import dataframe_to_node_list
@@ -52,7 +53,7 @@ def example_base_hive_plot(
             rng.uniform(low=10, high=20, size=num_nodes),
             rng.uniform(low=20, high=30, size=num_nodes),
         ],
-        columns=["low", "med", "high"],
+        columns=np.array(["low", "med", "high"]),
     )
 
     # make indices a column
@@ -106,7 +107,7 @@ def example_node_data(num_nodes: int = 100, seed: int = 0) -> pd.DataFrame:
             rng.uniform(low=10, high=19.99, size=num_nodes),
             rng.uniform(low=20, high=29.99, size=num_nodes),
         ],
-        columns=["low", "med", "high"],
+        columns=np.array(["low", "med", "high"]),
     )
     # make indices a column
     return data.reset_index(names="unique_id")
@@ -162,7 +163,9 @@ def example_edge_data(
     node_ids = nodes.data[nodes.unique_id_column].to_numpy()
     rng = np.random.default_rng(seed)
     edge_array = rng.choice(node_ids, size=num_edges * 2).reshape(-1, 2)
-    return pd.DataFrame(edge_array, columns=[from_column_name, to_column_name])
+    return pd.DataFrame(
+        edge_array, columns=np.array([from_column_name, to_column_name])
+    )
 
 
 def example_edges(
@@ -199,6 +202,85 @@ def example_edges(
     )
 
 
+def example_trade_nodes_and_edges() -> Tuple[NodeCollection, Edges]:
+    """
+    Load the international trade nodes and edges.
+
+    Used in the
+    :doc:`Hive Plots with More Than 3 Groups </notebooks/hive_plots_more_than_three_groups>`
+    notebook.
+
+    Uses :py:func:`hiveplotlib.datasets.international_trade.international_trade_data` to load 2019 trade data for HS92
+    trade group 8112 ("beryllium, chromium, germanium, vanadium, gallium, hafnium, indium, niobium
+    (columbium), rhenium and thallium, articles thereof, and waste or scrap") from the
+    `Harvard Growth Lab <https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi%3A10.7910%2FDVN%2FT4CHWJ>`_.
+
+    **Node columns** (152 nodes):
+
+    - ``"country"``: ISO 3166-1 alpha-3 country code (unique ID).
+    - ``"continent"``: continent of the country (Africa, Asia, Europe, North America, Oceania, or South America).
+    - ``"export_value"``: total USD exported by that country within trade group 8112 in 2019.
+      Countries with no exports are assigned 0.
+
+    **Edge columns** (1158 edges):
+
+    Each edge represents non-zero trade from an origin country to a destination country.
+
+    - ``"origin_country"``: ISO 3166-1 alpha-3 code of the exporting country (from column).
+    - ``"destination_country"``: ISO 3166-1 alpha-3 code of the importing country (to column).
+    - ``"export_value"``: USD exported from the origin to the destination.
+    - ``"origin_continent"``: continent of the origin country.
+    - ``"destination_continent"``: continent of the destination country.
+
+    :return: tuple of ``(NodeCollection, Edges)`` representing the trade network.
+    """
+    data, _ = international_trade_data(year=2019, hs92_code=8112)
+
+    export_totals_per_country = (
+        data.loc[:, ["origin_country", "export_value"]]
+        .groupby("origin_country")
+        .sum()
+        .reset_index()
+    )
+
+    node_data = pd.concat(
+        [
+            data.loc[:, ["origin_country", "origin_continent"]].rename(
+                columns={
+                    "origin_country": "country",
+                    "origin_continent": "continent",
+                }
+            ),
+            data.loc[:, ["destination_country", "destination_continent"]].rename(
+                columns={
+                    "destination_country": "country",
+                    "destination_continent": "continent",
+                }
+            ),
+        ]
+    ).drop_duplicates()
+
+    node_data = node_data.merge(
+        export_totals_per_country,
+        how="left",
+        left_on="country",
+        right_on="origin_country",
+    ).drop(columns=["origin_country"])
+
+    # fill in countries with no exports as 0, not NaN
+    node_data.export_value = node_data.export_value.fillna(0)
+
+    nodes = NodeCollection(node_data, unique_id_column="country")
+
+    edges = Edges(
+        data,
+        from_column_name="origin_country",
+        to_column_name="destination_country",
+    )
+
+    return nodes, edges
+
+
 def example_nodes_and_edges(
     num_nodes: int = 100,
     num_edges: int = 200,
@@ -238,8 +320,8 @@ def example_hive_plot(
     num_nodes: int = 100,
     num_edges: int = 100,
     partition_data_column: Literal["low", "med", "high"] = "low",
-    labels: Optional[List[Hashable]] = ("A", "B", "C"),
-    cutoffs: Optional[Union[List[float], int]] = 3,
+    labels: Optional[List[Hashable]] = ["A", "B", "C"],  # noqa: B006
+    cutoffs: Union[List[Union[int, float]], int] = 3,
     partition_variable_name: Optional[Hashable] = None,
     sorting_variables: Union[Hashable, Dict[Hashable, Hashable]] = "low",
     seed: int = 0,
@@ -310,7 +392,7 @@ def example_hive_plot(
             node_collection.data,
             left_on="to",
             right_on=node_unique_id_column,
-            suffixes=[None, "_to"],
+            suffixes=(None, "_to"),
         )
     )
     for col in ["low", "med", "high"]:
@@ -329,3 +411,219 @@ def example_hive_plot(
         sorting_variables=sorting_variables,
         **hive_plot_kwargs,
     )
+
+
+def example_hpm_nodes_and_edges(
+    num_groups: int = 3,
+    nodes_per_group: int = 10,
+    edge_tag_counts: Optional[Dict[str, int]] = None,
+    edge_structure: Optional[Dict[str, str]] = None,
+    seed: int = 42,
+) -> Tuple["NodeCollection", "Edges"]:
+    """
+    Generate a shared toy dataset that works well with ``HivePlotMatrix`` examples.
+
+    Returns a ``NodeCollection`` of ``num_groups * nodes_per_group`` nodes across
+    ``num_groups`` groups (A, B, C, ...) with structured numeric columns, and a
+    multi-tag ``Edges`` object.
+
+    **Node columns**:
+
+    - ``"unique_id"``: integers 0 to (num_groups * nodes_per_group - 1).
+    - ``"group"``: group label, assigned in consecutive blocks. With ``num_groups=3``,
+      nodes 0-9 are ``"A"``, 10-19 are ``"B"``, 20-29 are ``"C"``.
+    - ``"value1"``: *correlated with group* - each group draws from a distinct sub-interval
+      of [0, 10] in ascending order. Sorting by ``value1`` places groups at distinct,
+      separated positions along each axis if setting axes ``vmin`` and ``vmax`` values to the same fixed range.
+    - ``"value2"``: *uncorrelated noise* - all nodes draw from Uniform(0, 10). Sorting
+      by ``value2`` produces little visible group separation.
+    - ``"value3"``: *inversely correlated with group* - the mirror image of ``value1``.
+      The first group draws from the highest sub-interval, the last from the lowest.
+
+    **Default edge tags** (decreasing density):
+
+    - ``"official"``: 40 edges.
+    - ``"social"``: 30 edges.
+    - ``"informal"``: 20 edges.
+
+    :param num_groups: number of groups to generate (A, B, C, ...). Default 3.
+    :param nodes_per_group: number of nodes in each group. Default 10.
+    :param edge_tag_counts: dictionary mapping edge tag names to edge counts. Defaults to
+        ``{"official": 40, "social": 30, "informal": 20}``.
+    :param edge_structure: dictionary mapping edge tag names to structure types.
+        Supported types:
+
+        - ``"random"``: edges connect any two nodes uniformly at random (default).
+        - ``"intragroup"``: edges connect nodes within the same group only.
+        - ``"intergroup"``: edges connect nodes in different groups only.
+
+        Tags not listed in this dictionary default to ``"random"``.
+    :param seed: base random seed. Seeds ``seed``, ``seed+1``, ... are used for
+        successive edge tags respectively.
+    :return: tuple of ``(NodeCollection, Edges)``.
+    """
+    _valid_structures = {"random", "intragroup", "intergroup"}
+    if edge_tag_counts is None:
+        edge_tag_counts = {"official": 40, "social": 30, "informal": 20}
+    if edge_structure is None:
+        edge_structure = {}
+    for tag, structure in edge_structure.items():
+        if structure not in _valid_structures:
+            msg = (
+                f"edge_structure[{tag!r}] = {structure!r} is not valid. "
+                f"Must be one of {_valid_structures}."
+            )
+            raise ValueError(msg)
+    num_nodes = num_groups * nodes_per_group
+    rng = np.random.default_rng(seed)
+
+    # Deterministic block group assignment
+    group_labels = [chr(ord("A") + i) for i in range(num_groups)]
+    groups: list = []
+    for label in group_labels:
+        groups.extend([label] * nodes_per_group)
+
+    # Divide [0, 10] into num_groups equal sub-intervals
+    breakpoints = np.linspace(0, 10, num_groups + 1)
+
+    # value1: correlated - group i draws from [breakpoints[i], breakpoints[i+1]]
+    value1_parts = []
+    for i in range(num_groups):
+        lo, hi = breakpoints[i], breakpoints[i + 1]
+        value1_parts.append(rng.uniform(lo, hi, size=nodes_per_group))
+    value1 = np.concatenate(value1_parts)
+
+    value2 = rng.uniform(0, 10, size=num_nodes)
+
+    # value3: inversely correlated - group i draws from the reversed sub-interval
+    value3_parts = []
+    for i in range(num_groups):
+        j = num_groups - 1 - i
+        lo, hi = breakpoints[j], breakpoints[j + 1]
+        value3_parts.append(rng.uniform(lo, hi, size=nodes_per_group))
+    value3 = np.concatenate(value3_parts)
+
+    data = pd.DataFrame(
+        {
+            "unique_id": np.arange(num_nodes),
+            "group": groups,
+            "value1": value1,
+            "value2": value2,
+            "value3": value3,
+        }
+    )
+    nodes = NodeCollection(data=data, unique_id_column="unique_id")
+    node_ids = data["unique_id"].to_numpy()
+    groups_array = np.array(groups)
+
+    def _make_edges(n_edges: int, edge_seed: int, structure: str) -> pd.DataFrame:
+        edge_rng = np.random.default_rng(edge_seed)
+        if structure == "random":
+            return pd.DataFrame(
+                edge_rng.choice(node_ids, size=n_edges * 2).reshape(-1, 2),
+                columns=np.array(["from", "to"]),
+            )
+
+        from_nodes = edge_rng.choice(node_ids, size=n_edges)
+        to_nodes = np.empty(n_edges, dtype=node_ids.dtype)
+        for j in range(n_edges):
+            src_group = groups_array[from_nodes[j]]
+            if structure == "intragroup":
+                candidates = node_ids[groups_array == src_group]
+            else:  # intergroup
+                candidates = node_ids[groups_array != src_group]
+            to_nodes[j] = edge_rng.choice(candidates)
+        return pd.DataFrame(
+            {"from": from_nodes, "to": to_nodes},
+        )
+
+    edges = Edges(
+        data={
+            tag: _make_edges(count, seed + i, edge_structure.get(tag, "random"))
+            for i, (tag, count) in enumerate(edge_tag_counts.items())
+        }
+    )
+    return nodes, edges
+
+
+def example_minimal_hive_plot() -> HivePlot:
+    """
+    Generate a minimal ``HivePlot`` instance with edge color styling.
+
+    Uses :py:func:`example_hive_plot` with 6 nodes and 6 edges (seed 42) and adds
+    a uniform edge color of ``"#006BA4"`` to all axis pairs that have edges.
+
+    :return: ``HivePlot`` instance.
+    """
+    return example_hive_plot(
+        num_nodes=6,
+        num_edges=6,
+        seed=42,
+        all_edge_kwargs={"color": "#006BA4"},
+    )
+
+
+def example_multi_tag_hive_plot() -> HivePlot:
+    """
+    Generate a ``HivePlot`` instance with two edge tags and ``repeat_axes=True``.
+
+    Creates 12 nodes (seed 10) with two independent sets of 15 edges (seeds 10 and 20)
+    stored under tags ``"tag_red"`` and ``"tag_blue"``. Edge colors are ``"#FF0000"``
+    and ``"#0000FF"`` respectively.
+
+    :return: ``HivePlot`` instance with two edge tags.
+    """
+    nodes = example_node_collection(num_nodes=12, seed=10)
+    edge_data_1 = example_edge_data(nodes=nodes, num_edges=15, seed=10)
+    edge_data_2 = example_edge_data(nodes=nodes, num_edges=15, seed=20)
+    multi_tag_edges = Edges(data={"tag_red": edge_data_1, "tag_blue": edge_data_2})
+    partition_variable = nodes.create_partition_variable(
+        data_column="low", labels=["A", "B", "C"]
+    )
+    hp = HivePlot(
+        nodes=nodes,
+        edges=multi_tag_edges,
+        partition_variable=partition_variable,
+        sorting_variables="low",
+        repeat_axes=True,
+    )
+    hp.edges.update_edge_viz_kwargs(tag="tag_red", color="#FF0000")
+    hp.edges.update_edge_viz_kwargs(tag="tag_blue", color="#0000FF")
+    return hp
+
+
+def example_full_kwargs_hive_plot() -> HivePlot:
+    """
+    Generate a ``HivePlot`` instance with data-dependent edge kwargs, colormaps, and node styling.
+
+    Uses :py:func:`example_hive_plot` with 9 nodes, 10 edges (seed 99), and
+    ``repeat_axes=True``. Scaled edge data columns are created for alpha and linewidth,
+    and all edge visualization kwargs are set via
+    :py:meth:`~hiveplotlib.HivePlot.update_edge_plotting_keyword_arguments` using column
+    name references:
+
+    - **color**: the ``"low"`` edge data column mapped through a ``"cividis"`` colormap.
+    - **alpha**: the ``"alpha_scaled"`` column (``low / 10``, yielding values in ~0.3-1.0).
+    - **linewidth**: the ``"lw_scaled"`` column (``low / 3``, yielding values in ~1.0-3.3).
+
+    Node styling is applied via ``update_node_viz_kwargs`` with a ``"viridis"`` colormap mapped to the ``"low"``
+    data column.
+
+    :return: ``HivePlot`` instance with node and edge kwargs.
+    """
+    hp = example_hive_plot(num_nodes=9, num_edges=10, seed=99, repeat_axes=True)
+    # create scaled edge data columns for alpha (0-1 range) and linewidth
+    hp.edges.data["alpha_scaled"] = hp.edges.data["low"] / 10
+    hp.edges.data["lw_scaled"] = hp.edges.data["low"] / 3
+    # data-dependent edge kwargs: color, alpha, and linewidth all from edge data columns
+    hp.update_edge_plotting_keyword_arguments(
+        array="low",
+        cmap="cividis",
+        clim=(0, 10),
+        alpha="alpha_scaled",
+        linewidth="lw_scaled",
+    )
+    hp.update_node_viz_kwargs(
+        c="low", s=30, alpha=0.8, edgecolor="black", cmap="viridis"
+    )
+    return hp

hiveplotlib/datasets/toy_p2cps.py

@@ -34,7 +34,7 @@ def four_gaussian_blobs_3d(
     corners_to_keep = [0, 1, 2, 4]
 
     # name of the features we will create for each set of data generated below
-    feature_names = ["X", "Y", "Z", "Label"]
+    feature_names = np.array(["X", "Y", "Z", "Label"])
 
     # set seed for consistent data
     rng = np.random.default_rng(random_seed)
@@ -63,7 +63,7 @@ def four_gaussian_blobs_3d(
     # make the labels ints
     df.Label = df.Label.astype(int)
     # replace the 4s with 3s so our labels are just range(4)
-    df.Label.to_numpy()[df.Label.to_numpy() == 4] = 3
+    df.loc[df["Label"] == 4, "Label"] = 3
 
     return df
 

hiveplotlib/edges.py

@@ -4,7 +4,7 @@
 """
 
 from copy import deepcopy
-from typing import Hashable, Literal, Optional, Union
+from typing import Hashable, Literal, Optional, Union, cast
 
 import numpy as np
 import pandas as pd
@@ -99,7 +99,9 @@ class Edges:
     def __init__(
         self,
         data: Union[
-            pd.DataFrame, np.ndarray, dict[Hashable, Union[np.ndarray, pd.DataFrame]]
+            pd.DataFrame,
+            np.ndarray,
+            dict[Hashable, Union[np.ndarray, pd.DataFrame]],
         ],
         from_column_name: Hashable = "from",
         to_column_name: Hashable = "to",
@@ -114,7 +116,7 @@ class Edges:
 
         self.edge_viz_kwargs = {} if edge_viz_kwargs is None else edge_viz_kwargs.copy()
 
-        self._data = self._validate_edge_data(data)
+        self._data: dict[Hashable, pd.DataFrame] = self._validate_edge_data(data)
 
         # nested dictionary that stores boolean 1d arrays of which edges are relevant to which set of edges plotted
         #  edges are plotted in chunks of "from axis", "to axis", and "tag", so this stores 1 boolean array nested in
@@ -124,7 +126,10 @@ class Edges:
     def _validate_edge_data(
         self,
         data: Union[
-            pd.DataFrame, np.ndarray, dict[Hashable, Union[np.ndarray, pd.DataFrame]]
+            pd.DataFrame,
+            np.ndarray,
+            dict[Hashable, Union[np.ndarray, pd.DataFrame]],
+            dict[Hashable, pd.DataFrame],
         ],
     ) -> dict[Hashable, pd.DataFrame]:
         """
@@ -134,40 +139,52 @@ class Edges:
             of either.
         :return: dictionary of ``pandas.DataFrame`` objects with validated edge data.
         """
-        if not isinstance(data, dict):
+        # Normalize input to a dictionary without mutating the input parameter to avoid type ambiguity.
+        if isinstance(data, dict):
+            data_dict = data
+        else:
             if isinstance(data, np.ndarray):
                 assert data.shape[1] == 2, (
                     "Any `numpy.ndarray` input in `data` must be shape (n, 2) "
                     f"but found input with {data.shape[1]} columns."
                 )
-                data = pd.DataFrame(
-                    data, columns=[self.from_column_name, self.to_column_name]
+                df_single = pd.DataFrame(
+                    data, columns=np.array([self.from_column_name, self.to_column_name])
                 )
-            data = {0: data}  # default to tag 0 for single dataframe provided
+            else:
+                df_single = cast("pd.DataFrame", data)
+            # default to tag 0 for single dataframe provided
+            data_dict: dict[Hashable, pd.DataFrame] = {0: df_single}
             if 0 not in self.edge_viz_kwargs:
                 self.edge_viz_kwargs[0] = {}
-        for kw in data:
-            assert isinstance(data[kw], (pd.DataFrame, np.ndarray)), (
+
+        # Build the validated output dictionary of DataFrames.
+        out: dict[Hashable, pd.DataFrame] = {}
+        for kw, val in data_dict.items():
+            assert isinstance(val, (pd.DataFrame, np.ndarray)), (
                 f"Provided data for tag {kw} must be a `pandas.DataFrame` or `numpy.ndarray`."
             )
-            if isinstance(data[kw], pd.DataFrame):
-                assert self.from_column_name in data[kw].columns, (
+            if isinstance(val, pd.DataFrame):
+                df_kw = val
+                assert self.from_column_name in df_kw.columns, (
                     f"Provided data for tag {kw} must have a column named '{self.from_column_name}'"
                 )
-                assert self.to_column_name in data[kw].columns, (
+                assert self.to_column_name in df_kw.columns, (
                     f"Provided data for tag {kw} must have a column named '{self.to_column_name}'"
                 )
-            elif isinstance(data[kw], np.ndarray):
-                assert data[kw].shape[1] == 2, (
+                out[kw] = df_kw
+            else:
+                assert val.shape[1] == 2, (
                     "Any `numpy.ndarray` input in `data` must be shape (n, 2) "
-                    f"but found input with {data[kw].shape[1]} columns."
+                    f"but found input with {val.shape[1]} columns."
                 )
-                data[kw] = pd.DataFrame(
-                    data[kw], columns=[self.from_column_name, self.to_column_name]
+                out[kw] = pd.DataFrame(
+                    val,
+                    columns=np.array([self.from_column_name, self.to_column_name]),
                 )
             if kw not in self.edge_viz_kwargs:
                 self.edge_viz_kwargs[kw] = {}
-        return data
+        return out
 
     @property
     def data(self) -> Union[pd.DataFrame, dict[Hashable, pd.DataFrame]]:
@@ -182,9 +199,19 @@ class Edges:
             return next(iter(self._data.values()))
         return self._data
 
+    @property
+    def tags(self) -> list[Hashable]:
+        """
+        Return the list of all edge tags.
+
+        :return: list of tag keys for this ``Edges`` instance.
+        """
+        return list(self._data.keys())
+
     def add_edges(
         self,
-        data: dict[Hashable, Union[np.ndarray, pd.DataFrame]],
+        data: dict[Hashable, Union[np.ndarray, pd.DataFrame]]
+        | dict[Hashable, pd.DataFrame],
     ) -> None:
         """
         Add edges to the ``Edges`` instance.
@@ -217,7 +244,7 @@ class Edges:
         :return: copy of the ``Edges`` instance.
         """
         return Edges(
-            data=self._data.copy(),
+            data=deepcopy(self._data),  # ty:ignore[invalid-argument-type]
             from_column_name=self.from_column_name,
             to_column_name=self.to_column_name,
             edge_viz_kwargs=deepcopy(self.edge_viz_kwargs),