Add golden toy examples test suite for comprehensive py3plex validation

[Copilot]

Adds deterministic test suite with hand-computable expected outputs covering all main py3plex components: core network construction, multiplex coupling semantics, supra-adjacency matrices, statistics, centrality measures, community detection, DSL queries, I/O, and visualization.

Test Coverage

10 tests across key domains:

• Core: layer density (2/3 for 3-node 2-edge layers), node activity (1.0 for multi-layer, 0.5 for single-layer nodes)
• Multiplex: automatic coupling edge creation, edge aggregation with count metric
• Centrality: overlapping degree (hand-verified: A=2, B=4, C=1, D=1)
• Community: Louvain with structural invariants (node instances across layers in same community)
• DSL: both legacy string queries and builder API (Q.nodes().from_layers(L["layer1"]).where(degree__gt=1))
• I/O: multiedgelist format roundtrip preserving node/edge counts
• Visualization: smoke test with Agg backend to tmp_path

Example Usage

@pytest.fixture
def toy_multilayer_network():
    """2-layer network: layer1 A-B-C path, layer2 A-B-D star"""
    network = multinet.multi_layer_network(directed=False)
    network.add_edges([
        ['A', 'layer1', 'B', 'layer1', 1],
        ['B', 'layer1', 'C', 'layer1', 1],
        ['A', 'layer2', 'B', 'layer2', 1],
        ['B', 'layer2', 'D', 'layer2', 1],
    ], input_type='list')
    return network

def test_golden_multilayer_statistics(toy_multilayer_network):
    assert mls.layer_density(net, "layer1") == pytest.approx(2/3)
    assert mls.node_activity(net, node="B") == pytest.approx(1.0)

Implementation Notes

• Multiplex fixture creates 2-layer network with same nodes (A,B,C,D), auto-generates coupling edges
• Community detection checks structural properties (coupling keeps node instances together) rather than exact labels
• All file I/O to tmp_path, matplotlib uses Agg backend
• Runtime: ~0.2s for 10 tests (deterministic with random_state=42)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>golden toy tests</issue_title>
<issue_description>You are working in the py3plex repository.

Goal:
Create a new pytest module named: tests/test_golden_toy_examples.py
This module should provide “golden toy examples” (tiny graphs with hand-computable expected outputs) that exercise ALL main parts of py3plex:

• core network construction + layer management
• multiplex coupling edge semantics
• supra-adjacency matrix generation
• statistics (layer_density, node_activity)
• multilayer centrality (at least overlapping_degree_centrality)
• community detection (Louvain multilayer) with robust assertions
• DSL (string query + builder query)
• parsers/I/O roundtrip (tmp_path)
• visualization smoke test using non-interactive backend

Constraints:

• Tests must be deterministic and fast (< ~1s total locally).
• Must not require internet.
• Must not require external binaries (node2vec/infomap). If any wrappers would require binaries, do NOT call them; only import them or skip gracefully.
• Use matplotlib Agg backend for any visualization-related smoke tests and always close figures.
• Use tmp_path for any file I/O and do not write to repo directories.

Implementation steps:

1. Imports & safety:

• import pytest
• import numpy as np
• import matplotlib; matplotlib.use("Agg")
• import matplotlib.pyplot as plt
• from py3plex.core import multinet
• from py3plex.algorithms.statistics import multilayer_statistics as mls
• from py3plex.dsl import execute_query, Q, L
• For community detection, use the function shown in docs:
  from py3plex.algorithms.community_detection.multilayer_modularity import louvain_multilayer
  If this import path differs in the repo, search for the multilayer Louvain entrypoint used in the 10-minute tutorial and use that.

2. Fixtures: build two tiny networks.

Fixture A: toy_multilayer_network()

• network = multinet.multi_layer_network()
• network.add_edges([...], input_type="list") with undirected unit weights:
  ['A','layer1','B','layer1',1],
  ['B','layer1','C','layer1',1],
  ['A','layer2','B','layer2',1],
  ['B','layer2','D','layer2',1]
• Return network.

Fixture B: toy_multiplex_network(tmp_path)

• Create a small multiplex_edges file in tmp_path.
• Use a 2-layer multiplex with SAME nodes in all layers (A,B,C,D) and two disconnected edges per layer:
  layer 1: A-B, C-D
  layer 2: A-B, C-D
• Save as whitespace-delimited: layer node1 node2 weight (e.g., “1 A B 1”).
• Load with:
  net = multinet.multi_layer_network(network_type="multiplex")
  net.load_network(str(path), directed=False, input_type="multiplex_edges")
• Return net.
• IMPORTANT: this should auto-create coupling edges between node counterparts across layers; coupling edges should have attribute type == "coupling" if available.

3. Core golden tests (multilayer):

• test_golden_multilayer_statistics(toy_multilayer_network):
  assert mls.layer_density(net,"layer1") == pytest.approx(2/3, rel=1e-6)
  assert mls.layer_density(net,"layer2") == pytest.approx(2/3, rel=1e-6)
  assert mls.node_activity(net, node="B") == pytest.approx(1.0)
  assert mls.node_activity(net, node="C") == pytest.approx(0.5)

• test_golden_supra_adjacency_shape(toy_multilayer_network):
  mtx = net.get_supra_adjacency_matrix()
  n = len(list(net.get_nodes()))
  assert mtx.shape == (n,n)
  (Optional robust check) if network is undirected, verify matrix is symmetric (mtx - mtx.T has zero nnz / near-zero norm).
  Avoid brittle ordering-dependent checks.

4. Multiplex coupling golden tests:

• test_golden_multiplex_coupling_edges(toy_multiplex_network):
  explicit_edges = list(net.get_edges(data=True, multiplex_edges=False))
  all_edges = list(net.get_edges(data=True, multiplex_edges=True))
  assert len(all_edges) > len(explicit_edges)
  coupling_edges = [e for e in all_edges if isinstance(e, tuple) and len(e) >= 3 and e[2].get("type") == "coupling"]
  If coupling_edges is non-empty, assert len(coupling_edges) == 4 for 4 physical nodes in 2 layers.
  Also assert that explicit_edges contains exactly the 4 within-layer edges (2 per layer).
  If the exact API differs, adapt: the key invariant is that coupling edges exist and are filtered out by multiplex_edges=False.

5. Multiplex aggregation golden test:

• test_golden_multiplex_aggregate_counts(toy_multiplex_network):
  agg = net.aggregate_edges(metric="count", normalize_by="raw")
  Ensure you can read weights for edges A-B and C-D.
  Assert weight(A,B) == 2 and weight(C,D) == 2.
  If agg returns a py3plex network, inspect agg.core_network; if it returns a NetworkX graph, use that directly.

6. DSL golden tests:

• test_golden_dsl_string_query(toy_multilayer_network):
  res = execute_query(net, "SELECT nodes WHERE degree > 1")
  Assert it returns count == 2 (only ('B','layer1') and ('B','layer2') have degree 2 in the combined core graph).
  If the DSL returns a Result object, check re...

• Fixes golden toy tests #898

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.