Quickstart

This guide will help you get started with Dyn-Benchmark in just a few minutes.

Basic Usage

1. Generate Your First Benchmark

The simplest way to create a benchmark with evolving communities:

from dyn.benchmark.generator.groundtruth_generator import GroundtruthGenerator

# Create a generator with default parameters
generator = GroundtruthGenerator()

# Generate a groundtruth benchmark
groundtruth = generator.generate()

To learn more about benchmark generation and customization options, check out Tutorial 1: Benchmark Generation. For reference documentation, see the GroundtruthGenerator class.

2. Exploring the Generated Benchmark

The Groundtruth object contains three main components tcommlist, graphs, and events:

from dyn.benchmark.generator.groundtruth_generator import GroundtruthGenerator
from dyn.core.communities import Membership

# Create a generator with default parameters
generator = GroundtruthGenerator()

# Generate a groundtruth benchmark
groundtruth = generator.generate()

# Access the temporal community memberships
memberships = Membership.from_tcommlist(groundtruth.tcommlist)
print(f"Number of members: {len(memberships.members)}")

# Access the generated graphs (one per snapshot)
graphs = groundtruth.graphs
print(f"Number of snapshots: {len(graphs)}")

# Access community events (births, continuations, deaths, etc.)
events = groundtruth.events
print(f"Number of events: {len(events)}")

# Example: Inspect the first snapshot's graph
first_snapshot = min(graphs.keys())
print(f"First snapshot graph has {len(graphs[first_snapshot].nodes)} nodes and {len(graphs[first_snapshot].edges)} edges")

For a deeper understanding of the benchmark structure and how to analyze community evolution, refer to Tutorial 3: Metrics Computation and Analysis. The complete API reference is available in the Groundtruth and Membership classes.

Advanced Usage

1. Customizing the Generator

You can customize the benchmark generation process:

from dyn.benchmark.generator.groundtruth_generator import GroundtruthGenerator
from dyn.benchmark.generator.communities_generator import CommunitiesGenerator
from dyn.benchmark.generator.edges_generator import SBM
from dyn.benchmark.generator.nodes_generator import RandomMemberGenerator
from dyn.core.communities import Membership

# Create custom component generators
community_generator = CommunitiesGenerator(
    community_count=15,        # Number of evolving communities
    snapshot_count=10,         # Number of snapshots
    community_size_min=5,      # Minimum community size
    core_nodes_ratio=0.7,      # Ratio of members staying in the same community
)

edge_generator = SBM(
    p_in=0.7,                  # Intra-community edge probability
    p_out=0.05,                # Inter-community edge probability
)

# Assemble the custom generator
custom_generator = GroundtruthGenerator(
    community_generator=community_generator,
    edge_generator=edge_generator,
    node_generator=RandomMemberGenerator(),
    seed=42                    # For reproducibility
)

# Generate the benchmark
groundtruth = custom_generator.generate()

For detailed customization options and examples, explore Tutorial 1: Benchmark Generation and Tutorial 2: Scalable Multi-Groundtruth Generation. The parameter reference documentation is available in the CommunitiesGenerator class and related generator classes.

2. Computing Metrics

Analyze the communities and networks with built-in metrics:

from dyn.benchmark.metrics import GroundtruthMetricsComputer

# Create a metrics computer with default metrics
metrics_computer = GroundtruthMetricsComputer()

# Compute metrics for the generated groundtruth
metrics = metrics_computer.compute(groundtruth)

# Access specific metric results
graph_metrics = metrics["graph"]
community_metrics = metrics["evolving_community"]

# Example: Print average clustering coefficient for each snapshot
for snapshot_metric in graph_metrics:
    print(f"Snapshot {snapshot_metric['snapshot']}: CCF = {snapshot_metric.get('ccf', 'N/A')}")

# Example: Print the lifetime of each evolving community
for community_metric in community_metrics:
    print(f"Evolving Community {community_metric['evolving_community']}: Begin snapshot = {community_metric['begin_snapshot']}, Lifetime = {community_metric['lifetime']}")

For a complete guide on metrics computation, analysis, and events detection, see Tutorial 3: Metrics Computation and Analysis. The full list of available metrics and their meanings can be found in the Metrics Description reference page and in the GroundtruthMetricsComputer class documentation.

3. Visualizing the communities

Create visualizations to better understand community evolution:

from dyn.drawing.sankey_drawing import plot_sankey
import matplotlib.pyplot as plt

# Create a membership object
membership = Membership.from_tcommlist(groundtruth.tcommlist)

# Create a Sankey diagram of community evolution
plot_sankey(membership.community_graph)

The Sankey diagram shows how communities evolve across snapshots, with links representing member flows between communities.

To explore the full range of visualization capabilities and examples, check out Tutorial 4: Visualizing Evolving Communities. The visualization API reference is available in the drawing module documentation.

Complete Example

from dyn.benchmark.generator.groundtruth_generator import GroundtruthGenerator
from dyn.benchmark.generator.communities_generator import CommunitiesGenerator
from dyn.benchmark.generator.edges_generator import SBM
from dyn.benchmark.generator.nodes_generator import RandomMemberGenerator
from dyn.core.communities import Membership
from dyn.benchmark.metrics import GroundtruthMetricsComputer
from dyn.drawing.sankey_drawing import plot_sankey


# Create custom component generators
community_generator = CommunitiesGenerator(
    community_count=15,        # Number of evolving communities
    snapshot_count=10,         # Number of snapshots
    community_size_min=5,      # Minimum community size
    core_nodes_ratio=0.7,      # Ratio of members staying in the same community
)

edge_generator = SBM(
    p_in=0.7,                  # Intra-community edge probability
    p_out=0.05,                # Inter-community edge probability
)

# Assemble the custom generator
custom_generator = GroundtruthGenerator(
    community_generator=community_generator,
    edge_generator=edge_generator,
    node_generator=RandomMemberGenerator(),
    seed=42                    # For reproducibility
)

# Generate the benchmark
groundtruth = custom_generator.generate()

# Create a metrics computer with default metrics
metrics_computer = GroundtruthMetricsComputer()

# Compute metrics for the generated groundtruth
metrics = metrics_computer.compute(groundtruth)

# Access specific metric results
graph_metrics = metrics["graph"]
community_metrics = metrics["evolving_community"]

# Example: Print average clustering coefficient for each snapshot
for snapshot_metric in graph_metrics:
    print(f"Snapshot {snapshot_metric['snapshot']}: CCF = {snapshot_metric.get('ccf', 'N/A')}")

# Example: Print the lifetime of each evolving community
for community_metric in community_metrics:
    print(f"Evolving Community {community_metric['evolving_community']}: Begin snapshot = {community_metric['begin_snapshot']}, Lifetime = {community_metric['lifetime']}")

# Create a membership object
membership = Membership.from_tcommlist(groundtruth.tcommlist)

# Create a Sankey diagram of community evolution
plot_sankey(membership.community_graph)