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:

.. code:: python

    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 :doc:`Tutorial 1: Benchmark Generation <tutorials/1_comprehensive_benchmark_generation>`. For reference documentation, see the :class:`GroundtruthGenerator <dyn.benchmark.generator.groundtruth_generator>` class.

2. Exploring the Generated Benchmark
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. code:: python

    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 :doc:`Tutorial 3: Metrics Computation and Analysis <tutorials/3_metrics_computation_analysis>`. The complete API reference is available in the :class:`Groundtruth <dyn.benchmark.generator.groundtruth_generator.Groundtruth>` and :class:`Membership <dyn.core.communities.Membership>` classes.

Advanced Usage
--------------

1. Customizing the Generator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can customize the benchmark generation process:

.. code:: python

    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 :doc:`Tutorial 1: Benchmark Generation <tutorials/1_comprehensive_benchmark_generation>` and :doc:`Tutorial 2: Scalable Multi-Groundtruth Generation <tutorials/2_scalable_multiple_groundtruth_generation>`. The parameter reference documentation is available in the :class:`CommunitiesGenerator <dyn.benchmark.generator.communities_generator>` class and related generator classes.

2. Computing Metrics
~~~~~~~~~~~~~~~~~~~~

Analyze the communities and networks with built-in metrics:

.. code:: python

    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 :doc:`Tutorial 3: Metrics Computation and Analysis <tutorials/3_metrics_computation_analysis>`. The full list of available metrics and their meanings can be found in the :doc:`Metrics Description <references/metrics_description>` reference page and in the :class:`GroundtruthMetricsComputer <dyn.benchmark.metrics.GroundtruthMetricsComputer>` class documentation.

3. Visualizing the communities
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create visualizations to better understand community evolution:

.. code:: python

    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 :doc:`Tutorial 4: Visualizing Evolving Communities <tutorials/4_visualizing_evolving_communities>`. The visualization API reference is available in the drawing module documentation.


Complete Example
----------------

.. code:: python

    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)