ComprehensiveBenchmarking
==========================

Introduction
------------

The `ComprehensiveBenchmarking` class in the `distancia` package provides a robust framework for evaluating and comparing the performance of various distance metrics on a given dataset. This class allows users to measure the computational efficiency of different distance functions, helping to make informed decisions when selecting the appropriate metric for specific applications.

Idea and Utility
----------------

In data analysis, machine learning, and other computational fields, the choice of distance metric can significantly impact both the accuracy and efficiency of algorithms. The `ComprehensiveBenchmarking` class facilitates this decision-making process by providing a systematic approach to benchmarking. Users can pass in any number of custom or pre-defined distance functions, and the class will compute the average time taken to apply these functions across a dataset.

This tool is especially useful in scenarios where performance is critical, such as in real-time systems or when dealing with large-scale datasets. By understanding the trade-offs between different metrics, users can optimize their workflows, ensuring both speed and accuracy.

Example usage:
-------------

.. code-block:: python
    from distancia import ComprehensiveBenchmarking
    from distancia import Euclidean, CosineSimilarity

    # Sample data
    data_points = [((1, 2), (2, 3)), ((3, 4), (4, 5)), ((5, 6), (6, 7))]

    # Benchmarking
    benchmark = ComprehensiveBenchmarking(metrics=[Euclidean(), CosineSimilarity()], data=data_points)
    benchmark.run_benchmark()
    benchmark.print_results()

.. code-block:: python

    >>>Metric: euclidean_distance, Average Time: 0.000016 seconds
    >>>Metric: cosine_distance, Average Time: 0.000007 seconds

Academic Reference
------------------

The importance of benchmarking and selecting appropriate distance metrics has been highlighted in numerous studies and academic papers. For instance, in :footcite:t:`comprehensivebenchmarking`, the authors emphasize the critical role of distance metrics in machine learning and pattern recognition. They discuss various approaches and the necessity of efficient metric selection based on the application at hand.

.. footbibliography::

Conclusion
----------

The `ComprehensiveBenchmarking` class is a valuable addition to the `distancia` package, providing users with the tools needed to evaluate and select the most efficient distance metrics for their specific use cases. By integrating benchmarking directly into the analysis pipeline, this class enhances the usability and performance of the `distancia` package, making it an essential tool for researchers and practitioners alike.