.. Dyn-Benchmark documentation master file

############
DynBenchmark
############

Customizable Ground Truths to Benchmark Community Detection and Tracking in Temporal Networks
=============================================================================================

.. image:: _static/sankey_example.png
   :width: 600px
   :align: center
   :alt: Sankey diagram showing community evolution

DynBenchmark is a comprehensive toolkit for generating customizable ground truths to benchmark community detection and tracking algorithms in temporal networks.

Key Features
============

.. raw:: html
   :file: templates/key_features.html

For detailed information on each feature, see our :doc:`tutorials <tutorials/1_comprehensive_benchmark_generation>`.

Quick Start
===========

.. code-block:: python

   # Install the package
   pip install dyn-benchmark[pretty]
   
   # Generate a customized benchmark
   from dyn.benchmark.generator.groundtruth_generator import GroundtruthGenerator
   
   # Create a generator with specific parameters
   generator = GroundtruthGenerator(seed=42)
   
   # Generate the benchmark with evolving communities
   groundtruth = generator.generate()
   
   # Visualize community evolution with Sankey diagram
   from dyn.drawing.sankey_drawing import plot_sankey
   from dyn.core.communities import Membership
   
   membership = Membership.from_tcommlist(groundtruth.tcommlist)
   plot_sankey(membership.community_graph)


Citation
========

If you use DynBenchmark in your research, please cite:

.. code-block:: text

   Brisson, L., Bothorel, C., & Duminy, N. (2025). DynBenchmark: Customizable Ground 
   Truths to Benchmark Community Detection and Tracking in Temporal Networks, France's International Conference on Complex Systems (FRCCS 2025), Bordeaux, France

BibTeX:

.. code-block:: bibtex

    @inproceedings{Brisson2025DynBenchmark,
       title={DynBenchmark: Customizable Ground Truths to Benchmark Community Detection and Tracking in Temporal Networks},
       author={Brisson, Laurent and Bothorel, C{\'e}cile and Duminy, Nicolas},
       booktitle={France's International Conference on Complex Systems (FRCCS 2025)},
       year={2025}
    }

.. toctree::
   :maxdepth: 1
   :hidden:

   Homepage <self>

.. toctree::
   :maxdepth: 1
   :caption: GETTING STARTED
   :hidden:

   install
   quickstart

.. toctree::
   :caption: TUTORIALS
   :hidden:
   :maxdepth: 2
   :glob:

   tutorials/*

.. toctree::
   :caption: REFERENCE MANUAL
   :hidden:

   references/ground_truth_generation_parameters
   references/metrics_description
   
   api

Contributing
============

This package is growing continuously and contributions are welcomed.
Contributions can come in the form of new features, bug fixes, documentation improvements
or any combination thereof.

If you want to contribute to this package, please read the :doc:`Contributing guidelines <contributing>`.
If you have any new ideas or have found bugs, feel free to `create an issue <https://gitlab.com/decide.imt-atlantique/dyn/benchmark/-/issues/new>`_.
Finally, any contribution must be proposed for integration as a `Merge Request <https://gitlab.com/decide.imt-atlantique/dyn/benchmark/-/merge_requests/new>`_.

Please visit our `Gitlab <https://gitlab.com/decide.imt-atlantique/dyn/benchmark>`_ for more details.

License
=======

This software is licensed under the `European Union Public Licence (EUPL) v1.2 <https://joinup.ec.europa.eu/page/eupl-text-11-12>`_.
For more information see `this <https://gitlab.com/decide.imt-atlantique/dyn/benchmark/-/blob/main/LICENSE>`_.

.. toctree::
   :caption: SUPPORT AND CONTRIBUTION
   :hidden:

   contributing
   troubleshoots
   Issues <https://gitlab.com/decide.imt-atlantique/dyn/benchmark/-/issues>
   Gitlab <https://gitlab.com/decide.imt-atlantique/dyn/benchmark>