Building a Graph Navigator in Python

shiny run --reload --log-level debug src/navigator/d3/app.py

from dataclasses import dataclass, asdict
from pathlib import Path
import networkx as nx
import pandas as pd

import htmltools
import shiny
import shinyswatch
from shiny import App, ui, render
from shiny.module import resolve_id
from shiny.render.renderer import Jsonifiable, Renderer
from shiny.types import SilentException
from navigator.shakespeare import CharacterNetwork, NodeId

www_dir = Path(__file__).parent.parent.parent / "www"
PLAY_DATA = CharacterNetwork(
    pd.read_csv(www_dir / "data" / "shakespeare_plays.csv", index_col=0)
)

d3_dependency = htmltools.HTMLDependency(
    "d3graph",
    "0.0.0",
    source={"subdir": str(www_dir / "gen")},
    script={"src": "d3_navigator.js", "type": "module"},
    stylesheet={"href": "d3_navigator.css"},
    all_files=True,
)

@dataclass
class SelectionState:
    zoom_nodes: list[NodeId]

@dataclass
class GraphAndState:
    graph: nx.Graph
    state: SelectionState

class render_character_graph(Renderer[GraphAndState]):
    """
    Render a dict as a D3 graph.
    """

    async def transform(self, value: GraphAndState) -> Jsonifiable:
        """Transform a networkx graph representing character interactions in
        Shakespeare's plays into a Jsonifiable object.
        """
        assert isinstance(value, GraphAndState)
        G = value.graph
        state = value.state

        def node_id_as_str(node_id) -> str:
            return ", ".join([node_id.play, node_id.name])

        nodes = [
                {
                    "id": node_id_as_str(node_id),
                    "play": node_id.play,
                    "name": node_id.name,
                    "sentences": int(node_attributes["sentences"]),
                }
                for node_id, node_attributes in G.nodes(data=True)
            ]
        links = [
                {
                    "source": node_id_as_str(source),
                    "target": node_id_as_str(target),
                    **edge_attributes,
                }
                for source, target, edge_attributes in G.edges(data=True)
            ]
        for node in nodes:
            node['is_focal'] = NodeId(play=str(node['play']), name=str(node['name'])) in set(state.zoom_nodes)

        for link in links:
            interactions = link["interactions"]
            link["interaction_strength"] = sum(
                interaction["sentences_char1"] * interaction["sentences_char2"]
                for interaction in interactions
            )

        return {
            "nodes": nodes,
            "links": links,
            "state": asdict(state),
        } #  type: ignore [reportReturnType]



app_ui = ui.page_fluid(
    ui.tags.head(
        ui.tags.title("D3.js Directed Graph in Shiny"),
        d3_dependency,
    ),
    ui.div(
        id=resolve_id("d3Graph"),
        class_="shiny-d3-graph-output",
    ),
    ui.h2("Shakespeare's plays and characters"),
    ui.layout_columns(
        ui.card(
            ui.card_header("Inputs"),
            ui.input_select(
                id="play_name",
                label="Play",
                choices=PLAY_DATA.play_names,
                selected="Henry V",
            )),
        ui.card(
            ui.card_header("Overview"),
            ui.tags.svg(
                id="d3-graph",
                style="height: 600px; border: 1px solid black;",
            )),
        ui.card(
            ui.card_header("Details"),
            ui.div(
                ui.output_ui("detail_character_output")),
            ui.output_ui("detail_interaction_output")),
        col_widths={"xl": (2, 7, 3)},
    ),
    ui.div(id="tooltip"),
    theme=shinyswatch.theme.cerulean,
)


def server(input: shiny.Inputs, output: shiny.Outputs, _session: shiny.Session):

    zoom_nodes = shiny.reactive.Value(list[NodeId]())

    @shiny.reactive.effect
    def handle_node_on_click():
        play = input.play_name()
        click = input.node_on_click()
        shiny.req(click)
        clicked_node = NodeId(play=click['play'], name=click['name'])
        if click['ctrl']:
            # use isolate to avoid an infinite loop
            with shiny.reactive.isolate():
                old_zoom_nodes = {n for n in zoom_nodes() if n.play == play}
            new_zoom_nodes = list({clicked_node} ^ old_zoom_nodes)
        else:
            new_zoom_nodes = [clicked_node]
        zoom_nodes.set(new_zoom_nodes)


    @shiny.reactive.calc
    def detail_character() -> NodeId | None:
        play = input.play_name()
        try:
            character = input.detail_character()
        except SilentException:
            return None
        if character["play"] != play:
            return None
        return NodeId(**character)

    @render_character_graph
    def d3Graph():
        play_name = input.play_name()
        G = PLAY_DATA.graph
        if not zoom_nodes():
            print(f"jm - displaying all characters in {play_name}")
            filter_node = lambda n: n.play == play_name # noqa: E731
        else:
            neighborhood = set()
            cutoff=1
            for source in zoom_nodes():
                neighborhood |= set(nx.single_source_shortest_path_length(G, source, cutoff=cutoff))
            filter_node = lambda n: n in neighborhood # noqa: E731

        return GraphAndState(
            graph=nx.subgraph_view(G, filter_node=filter_node),
            state=SelectionState(zoom_nodes=zoom_nodes())
        )

    @staticmethod
    def character_html(character_graph: nx.Graph, *, character_id: NodeId) -> ui.Tag:
        """Return html representing a character"""
        assert isinstance(character_graph, nx.Graph)
        character_data = character_graph.nodes[character_id].copy()
        character_data.pop("play")

        return ui.div(
            *(
                ui.p(ui.strong(f"{key}:"), str(value))
                for key, value in character_data.items()
            ),
        )

    @output
    @render.ui
    def detail_character_output():
        character_id = detail_character()
        if character_id is None:
            return ui.HTML("")
        html = character_html(
            PLAY_DATA.graph, character_id=character_id
        )
        return ui.HTML(html)

    @render.table
    def detail_interaction_output():
        interaction = input.detail_interaction()

        play_name = input.play_name()

        source_name = interaction["source"]["name"]
        source_play = interaction["source"]["play"]
        target_name = interaction["target"]["name"]
        target_play = interaction["target"]["play"]
        assert source_play == target_play
        if play_name != source_play:
            print("jm - Returning empty interactions DataFrame")
            return pd.DataFrame()

        interactions = PLAY_DATA.graph.edges[
            NodeId(play=source_play, name=source_name),
            NodeId(play=target_play, name=target_name),
        ]["interactions"]

        return pd.DataFrame(interactions).rename(
            columns={
                "sentences_char1": f"Sentences by {source_name}",
                "sentences_char2": f"Sentences by {target_name}",
            }
        )


app = App(app_ui, server, static_assets=www_dir)

import * as d3 from "https://cdn.jsdelivr.net/npm/d3@7/+esm"; // Using d3 v7 ESM


function ensureG(parentSelection, className) {
    return parentSelection.data([42]).join("g").classed(className, true);
}

function getRadiusScale(nodeData, {radiusAttr, minRadius, maxRadius}) {
    const minRadiusAttr = d3.min(nodeData, d => d[radiusAttr]);
    const maxRadiusAttr = d3.max(nodeData, d => d[radiusAttr]);
    return d3.scaleSqrt()
        .domain([minRadiusAttr, maxRadiusAttr])
        .range([minRadius, maxRadius]);
}

function createZoomBehavior(zoomGroup){
    return d3.zoom()
        .scaleExtent([0.1, 10])
        .on("zoom", (event) => {
            zoomGroup.attr("transform", event.transform);
        });
}

function enterNode({width, height}, {radiusScale, radiusAttr}) {
    return function(enter) {
        const nodeEnter = enter.append("g")
              .attr("class", "node")
              .attr("transform", d => {
                  // Position new nodes randomly within the SVG
                  const x = Math.random() * width;
                  const y = Math.random() * height;
                  return `translate(${x}, ${y})`;
              });
        nodeEnter.append("circle")
            .attr("r", d => radiusScale(d[radiusAttr]));
        nodeEnter.append("text")
            .attr("dy", "0.75em")
            .attr("y", d => radiusScale(d[radiusAttr]) + 5) // Position text below the circle
            .text(d => d.name)
            .style("pointer-events", "none") // Make text not interfere with node click
        ;
        nodeEnter.classed("focal-node", d => d.is_focal);
        return nodeEnter;
    };
}

function linkStringId(d, i) {
    // an identifying hash for a link, as a string
    return `${d.source.id}--${d.target.id}`;
}

function getLinkWidthScale(linkData) {
    const linkStrengthExtent = d3.extent(linkData, d => d.interaction_strength);
    return d3.scaleSqrt()
        .domain(linkStrengthExtent)
        .range([0, 10]);
}

function getLinkColorScale(linkData) {
    const linkStrengthExtent = d3.extent(linkData, d => d.interaction_strength);
    return d3.scaleSqrt()
        .domain(linkStrengthExtent)
        .range(["#fff", "#f00"]);
}

function createLink(linkGroup, linkData) {
    const linkWidthScale = getLinkWidthScale(linkData);
    const linkColorScale = getLinkColorScale(linkData);
    return linkGroup.selectAll("line")
        .data(linkData, linkStringId)
        .join("line")
        .attr("class", "link")
        .attr("stroke-width", d => linkWidthScale(d.interaction_strength))
        .attr("stroke", d => linkColorScale(d.interaction_strength))
    ;
}

function createSimulation({width, height}, nodeData, {radiusAttr, radiusScale}, linkData) {
    // warning: forceLink modifies linkData. See https://d3js.org/d3-force/link
    return d3.forceSimulation(nodeData)
        .force("link", d3.forceLink(linkData).id(node => node.id).distance(100))
        .force("charge", d3.forceManyBody().strength(-50))
        .force("center", d3.forceCenter(width / 2, height / 2))
        .force("collide", d3.forceCollide().radius(d => radiusScale(d[radiusAttr]) + 2));
}

function updatePositions(link, node, {width, height}) {
    node.attr("transform", d => {
        const x = d.x = Math.max(10, Math.min(width - 10, d.x));
        const y = d.y = Math.max(10, Math.min(height - 10, d.y));
        return `translate(${x},${y})`;
    });

    link.attr("x1", d => d.source.x)
        .attr("y1", d => d.source.y)
        .attr("x2", d => d.target.x)
        .attr("y2", d => d.target.y);
}

function isEventTargetSelected(event) {
    return d3.select(event.currentTarget).classed('selected');
}

function nodeMouseOver(link) {
    return function(event, d) {
        Shiny.setInputValue("detail_character", {"play": d.play, "name": d.name});

        d3.selectAll(".node").classed("selected", false);

        // 'this' refers to the node element that the event listener is attached to
        if (isEventTargetSelected(event)) {
            d3.select(this).classed("selected", false);
        } else {
            d3.select(this).classed("selected", true);
        }

        // Highlight links connected to the node
        link.classed("hidden", true);
        link.filter(l => (l.source === d) || (l.target === d))
            .classed("hidden", false)
            .classed("highlighted-link", true);
    };
}

function nodeMouseOut(link) {
    return function(event, d) {
        d3.select(this).classed("selected", false);
        link.classed("highlighted-link", false)
            .classed("hidden", false);
    };
}

function linkMouseOver() {
    return function(event, d) {
        Shiny.setInputValue("detail_interaction",
                            {"source": {"play": d.source.play,
                                        "name": d.source.name},
                             "target": {"play": d.target.play,
                                        "name": d.target.name}});
    };
}

function displayGraph({svgGeom, nodeData, nodeGeom, nodeGroup, linkData, linkGroup}) {
    let forceSimulation;
    function displayGraphInner(innerNodeData, innerLinkData) {
        const node = nodeGroup.selectAll("g")
              .data(innerNodeData, d => d.id)
              .join(enterNode(svgGeom, nodeGeom),
                    update => update,
                    exit => exit.remove());
        node.classed("in_focus", d => d.is_focal);
        const link = createLink(linkGroup, innerLinkData);
        node.on("mouseover", nodeMouseOver(link))
            .on("mouseout", nodeMouseOut(link))
            .on("click", (event, d) => {
                Shiny.setInputValue("node_on_click", {"play": d.play, "name": d.name, "ctrl": event.ctrlKey});
            });
        link.on("mouseover", linkMouseOver());
        if (forceSimulation) {
            forceSimulation.stop();
        }
        forceSimulation = createSimulation(svgGeom, innerNodeData, nodeGeom, innerLinkData);
        forceSimulation.on("tick", () => updatePositions(link, node, svgGeom));
    }
    displayGraphInner(nodeData, linkData);
}

if (Shiny) {
    class NavigatorGraphOutputBinding extends Shiny.OutputBinding {
        find(scope) {
            return scope.find(".shiny-d3-graph-output");
        }
        renderValue(el, payload) {
            const {
                nodes: nodeData,
                links: linkData,
                state: state
            } = payload;

            const svg = d3.select("#d3-graph");

            const zoomGroup = ensureG(svg.selectAll(".zoom-container"), "zoom-container");
            const linkGroup = ensureG(zoomGroup.selectAll(".links"), "links");
            const nodeGroup = ensureG(zoomGroup.selectAll(".nodes"), "nodes");

            const width = svg.node().getBoundingClientRect().width;
            const height = svg.node().getBoundingClientRect().height;
            const radiusAttr = "sentences";
            const radiusScale = getRadiusScale(nodeData, {radiusAttr: radiusAttr, minRadius: 5, maxRadius: 25});
            svg.call(createZoomBehavior(zoomGroup));

            const svgGeom = {
                width: width,
                height: height,
            };
            const nodeGeom = {
                radiusScale: radiusScale,
                radiusAttr: radiusAttr
            };

            displayGraph({svgGeom: svgGeom, nodeGroup: nodeGroup, nodeData: nodeData, nodeGeom: nodeGeom,
                          linkGroup: linkGroup, linkData: linkData,
            });
        }
    }
    Shiny.outputBindings.register(new NavigatorGraphOutputBinding(), "shiny-d3-graph-output");
}

body { font-family: 'Inter', sans-serif; }

.hidden {
  display: none;
}

.node circle {
    fill: #69b3a2;
    stroke: #000000;
    stroke-width: 1.5px;
    transition: all 0.2s ease-in-out; /* Smooth transition for highlight */
}

.node.selected circle {
    fill: #ff0000;
}

.node.in_focus circle {
    stroke-width: 3px;
}

.node text {
    font-size: 10px;
    pointer-events: none; /* Prevent text from interfering with drag */
    text-anchor: middle;
    fill: #333;
    transition: all 0.2s ease-in-out; /* Smooth transition for highlight */
}

.node.selected text {
    font-weight: bold;
    fill: #ff0000;
}

.link {
    /* stroke: #909090; */
    stroke-opacity: 0.6;
    stroke-width: 2px;
    fill: none; /* Ensure links are lines, not filled shapes */
}

.highlighted-link {
  stroke: #f00; /* Red color for highlighted links */
}

.tooltip {
    position: absolute;
    text-align: center;
    width: auto;
    height: auto;
    padding: 8px;
    background: lightsteelblue;
    border: 0px;
    border-radius: 8px;
    pointer-events: none;
    opacity: 0;
    transition: opacity 0.2s;
}

table {
    width: 100%;
    border-collapse: collapse;
    margin-top: 10px;
}

th, td {
    border: 1px solid #ddd;
    padding: 8px;
    text-align: left;
}

th {
    background-color: #f2f2f2;
}

import functools
import sys
from pathlib import Path


def trace(func):
    @functools.wraps(func)
    def traced(*args, **kwargs):
        func_name = func.__name__

        arg_str = ", ".join(repr(arg) for arg in args)
        kwarg_str = ", ".join(f"{key}={repr(value)}" for key, value in kwargs.items())
        all_args = ", ".join(filter(None, [arg_str, kwarg_str]))

        print(f"TRACE: Entering {func_name}({all_args})")

        try:
            result = func(*args, **kwargs)
            print(f"TRACE: Exiting {func_name} with result: {repr(result)}")
            return result
        except Exception as e:
            print(f"TRACE: Exiting {func_name} with exception: {e=}")
            raise

    return traced


def log_mouseovers(node):
    print(f"mouseover: {node}")


def log_clicks(node):
    print(f"click: {node}")

def print_traits(widget):
    """Print the traits for an ipython widget
    """
    print([t for t in widget.traits()
           if not str(t).startswith('_')])

def bind_to_name(name: str):
    """
    A decorator that binds the decorated function to a specified string name
    at the module/global level.

    The function will be accessible via its original name and the new bound name.

    Args:
        name: The name to bind the function to at global scope.
    """
    if not isinstance(name, str):
        raise TypeError("The name argument must be a string.")

    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            return func(*args, **kwargs)
        globals()[name] = func
        return wrapper

    return decorator

from typing import Any
import networkx as nx

def create_cycle_graph(n)-> nx.Graph:
    """
    Creates a circular graph with nodes valued from 0 to n-1,
    where each node is connected to its successor and predecessor mod n.

    Args:
      n: The number of nodes in the graph.

    Returns:
      A NetworkX graph object representing the circular graph.
    """
    G = nx.cycle_graph(n)

    return G

def node_and_neighbors(graph: nx.Graph, node: Any) -> nx.Graph:
  """
  Returns a subgraph consisting of the given node and all its immediate neighbors.

  Args:
    graph: The input NetworkX undirected graph.
    node: The node within the graph for which to get the subgraph.

  Returns:
    A NetworkX graph object representing the subgraph containing the
    specified node and its neighbors.

  Raises:
    nx.NetworkXError: If the specified node is not in the graph.
  """
  if node not in graph:
    raise nx.NetworkXError(f"Node {node} is not in the graph.")

  subgraph_nodes = list(graph.neighbors(node)) + [node]

  return graph.subgraph(subgraph_nodes)

import re
import warnings
from dataclasses import dataclass
from itertools import combinations
from typing import Any, Iterable

import pandas as pd
import networkx as nx
from thefuzz import process as thefuzz_process


def calculate_candidate_character_replacements(
    character_names: pd.Series, min_similarity_score: int
) -> dict[str, str]:
    """Calculate candidate replacements to clean a Series of character names by
    standardizing strings using fuzzy matching.

    Args:

        series: The input Series.

        min_similarity_score: The minimum fuzzy matching score (0-100) to consider a
            string a potential match.

    Returns:
        A mapping from current character names to cleaned ones, where these are different
    """

    def strip_name(name: str) -> str:
        name = name.strip()
        name = re.sub(r"  +", " ", name)
        name = re.sub(r"[^a-zA-Z]+$", "", name)
        return name

    def best_match(
        name: str, stripped_names: Iterable[str], min_similarity_score: int
    ) -> str:
        stripped_name = strip_name(name)
        extracted = thefuzz_process.extractOne(stripped_name, stripped_names)
        if extracted is None:
            return stripped_name
        best_match, score = extracted
        if score < min_similarity_score:
            return stripped_name
        else:
            return best_match

    replacements = {}
    replacement_values = set()
    for name in character_names.value_counts().index:  # most frequent values first
        replacements[name] = best_match(name, replacement_values, min_similarity_score)
        replacement_values.add(replacements[name])

    return {
        name: mapped_name
        for name, mapped_name in replacements.items()
        if name != mapped_name
    }


@dataclass(frozen=True)
class NodeId:
    play: str
    name: str


class CharacterNetwork:
    REQUIRED_COLUMNS = "play_name,genre,character,act,scene,sentence,text,sex".split(
        ","
    )

    KNOWN_CHARACTER_FIXES: dict[str, dict[str, str]] = {
        "Richard III": {
            "Of Buckingham": "Ghost of Buckingham",
            "Of Prince Edward": "Ghost of Prince Edward",
        },
        "Henry VI, part 1": {"Su Ffolk": "Suffolk"},
        "Othello": {"Second Gentlemen": "Second Gentleman"},
        "Romeo and Juliet": {"Lady  Capulet": "Lady Capulet"},
        "Hamlet": {
            "Guildenstern:": "Guildenstern",
            "Rosencrantz:": "Rosencrantz",
        },
        "Taming of the Shrew": {"Katarina": "Katharina"},
        "Henry VI, part 2": {"First Murder": "First Murderer"},
        "Measure for Measure": {"Pomphey": "Pompey"},
    }

    KNOWN_CHARACTER_NON_FIXES: set[tuple[str, str]] = {
        ("Antony and Cleopatra", "Attendants"),
        ("Coriolanus", "Citizen"),
        ("Henry IV, part 2", "King Henry V"),
        ("Henry VI, part 2", "Servant"),
        ("Timon of Athens", "Servants"),
    }

    # Names not referring to definite characters.  These are not so interesting to look at
    # and may represent different people.
    INDEFINITE_NAMES = [
        "& C",
        "A Lord",
        "A Patrician",
        "A Player",
        "All",
        "All Citizens",
        "All Conspirators",
        "All Ladies",
        "All Lords",
        "All Servants",
        "All The Goths",
        "All The Lords",
        "All The People",
        "Another",
        "As Long As You Or I",
        "Attendant",
        "Attendants",
        "Both Citizens",
        "Both Murderers",
        "Both Tribunes",
        "Boy",
        "Captain",
        "Children",
        "Chorus",
        "Citizen",
        "Citizens",
        "Clown",
        "Commons",
        "Court",
        "Courtezan",
        "Crier",
        "Gentleman",
        "Gentlemen",
        "Gentlewoman",
        "Girl",
        "Guard",
        "Knight",
        "Knights",
        "Lady",
        "Lieutenant",
        "Lord",
        "Lords",
        "Man",
        "Merchant",
        "Messenger",
        "Mother",
        "Musician",
        "Nobleman",
        "Nurse",
        "Officer",
        "Old Athenian",
        "Old Lady",
        "Old Man",
        "Outlaws",
        "Page",
        "Players",
        "Prince",
        "Princes",
        "Princess",
        "Prologue",
        "Sailor",
        "Scout",
        "Senator",
        "Senators",
        "Sergeant",
        "Servant",
        "Servants",
        "Shepard",
        "Shepherd",
        "Sheriff",
        "Soldier",
        "Soldiers",
        "Some Others",
        "Some Speak",
        "Soothsayer",
        "Steward",
        "Townsman",
        "Travellers",
        "Watch",
        "Watchman",
        "Wife",
    ]

    def __init__(self, df: pd.DataFrame, min_similarity_score: int = 92):
        """Initializes the CharacterNetwork with a dataframe containing character
        interactions in Shakespeare's plays.

        Nodes represent a unique character within a specific play (e.g., 'play-name-character').
        Edges connect characters who speak in the same scene.

        Args:
            df: The dataframe, with columns:
            - play_name
            - genre
            - act
            - scene
            - character
            - sex
            - sentence
            - text

            min_similarity_score: minimum Levenshtein-based similarity score to warn if
               character name matches are found for
        """
        self.df = CharacterNetwork.clean_playdata(df, min_similarity_score)
        self.graph = CharacterNetwork._build_shakespeare_network(self.df)
        self.play_names = sorted(set(df["play_name"]))

    @staticmethod
    def clean_playdata(df: pd.DataFrame, min_similarity_score: int) -> pd.DataFrame:
        """Return a cleaned version of df.

        Character names are replaced based on previously checked replacements.

        Warnings are issued if there are any candidate replacements not among those
        previously known or ruled out, based on a fuzzy-matching analysis of the character
        names.

        Args:

          min_similarity_score: the threshold above which character names are
            candidates for consolidation. Corresponds to the score returned from
            `thefuzz.process.extractOne`.
        """
        assert set(df.columns) == set(CharacterNetwork.REQUIRED_COLUMNS)

        # 1. Apply previously known fixes
        dfr = df.copy()
        dfr["character"] = dfr.groupby("play_name")["character"].transform(
            lambda s: s.replace(
                CharacterNetwork.KNOWN_CHARACTER_FIXES.get(s.name) or {}
            )
        )

        # 2. Warn if there are any candidate fixes not previously known
        play_mappings = dfr.groupby("play_name").apply(
            lambda group_df: calculate_candidate_character_replacements(
                group_df["character"], min_similarity_score=min_similarity_score
            )
        )

        assert isinstance(play_mappings, pd.Series)

        play_mappings = {
            play: {
                original: replacement
                for original, replacement in replacements.items()
                if (play, original) not in CharacterNetwork.KNOWN_CHARACTER_NON_FIXES
            }
            for play, replacements in play_mappings.items()
        }
        for play, replacements in play_mappings.items():
            if replacements:
                warnings.warn(
                    f"Candidate character replacements found in play {play}: {replacements}"
                )

        assert set(dfr.columns) == set(CharacterNetwork.REQUIRED_COLUMNS)

        # Remove entries with names not referring to definite characters
        dfr = dfr[~dfr["character"].isin(CharacterNetwork.INDEFINITE_NAMES)]

        return dfr

    @staticmethod
    def _build_shakespeare_network(df: pd.DataFrame) -> nx.Graph:
        assert set(df.columns) == set(CharacterNetwork.REQUIRED_COLUMNS)

        # Add the number of unique scenes.
        scenes_per_character = (
            df.groupby(["play_name", "character", "act", "scene"])
            .size()
            .reset_index(name="_count")
            .groupby(["play_name", "character"])
            .size()
            .reset_index(name="num_scenes")
        )

        # Group by play, character, and sex to get a summary for each character node.
        character_data = (
            df.groupby(["play_name", "character", "sex"])
            .agg(num_sentences=("sentence", "count"), num_acts=("act", "nunique"))
            .reset_index()
        ).merge(scenes_per_character, on=["play_name", "character"])

        # Prepare a dictionary for node attributes, keyed by the unique node ID.
        node_attributes: dict[NodeId, dict[str, Any]] = {}
        for _, row in character_data.iterrows():
            node_id = NodeId(play=row["play_name"], name=row["character"])
            node_attributes[node_id] = {
                "play": row["play_name"],
                "character": row["character"],
                "sex": row["sex"],
                "acts": row["num_acts"],
                "scenes": row["num_scenes"],
                "sentences": row["num_sentences"],
            }
        # Process Edge Data
        interactions = (
            df.groupby(["play_name", "act", "scene"])["character"]
            .apply(set)
            .reset_index(name="characters_in_scene")
        )

        edge_attributes: dict[tuple[str, str, str], dict[str, Any]] = {}

        sentences_by_scene_and_character = df.groupby(
            ["play_name", "act", "scene", "character"]
        ).size()
        for _, row in interactions.iterrows():
            play_name = row["play_name"]
            act = row["act"]
            scene = row["scene"]
            characters_in_scene = row["characters_in_scene"]

            # Get all unique pairs of characters in this scene.
            for char1, char2 in combinations(set(characters_in_scene), 2):
                edge_key = (play_name, char1, char2)
                sentences_char1 = sentences_by_scene_and_character.loc[
                    play_name, act, scene, char1
                ]
                sentences_char2 = sentences_by_scene_and_character.loc[
                    play_name, act, scene, char2
                ]
                if edge_key not in edge_attributes:
                    edge_attributes[edge_key] = {
                        "play_name": play_name,
                        "interactions": [],
                    }
                edge_attributes[edge_key]["interactions"].append(
                    {
                        "act": act,
                        "scene": scene,
                        "sentences_char1": int(sentences_char1),
                        "sentences_char2": int(sentences_char2),
                    }
                )

        # Build the NetworkX Graph
        G = nx.Graph()

        for node_id, attributes in node_attributes.items():
            G.add_node(node_id, **attributes)

        for edge_key, attributes in edge_attributes.items():
            play, char1, char2 = edge_key
            G.add_edge(
                NodeId(play=play, name=char1),
                NodeId(play=play, name=char2),
                **attributes,
            )

        return G


# Example usage:
# character_network = CharacterNetwork(pd.read_csv(data_dir / 'shakespeare_plays.csv'))
# play_names = character_network.play_names
# sdg = character_network.graph
# print(f"jm - {sdg=}")