Analyzer API
============

The Analyzer API provides classes and functions for processing, visualizing, and extracting insights from simulation results generated by the Executor module.

Module Overview
---------------

The Analyzer module is responsible for:

- Loading simulation results from the Executor
- Processing and aggregating data
- Generating visualizations and plots
- Analyzing the complexity of simulations
- Comparing results across different scenarios

Key Classes
-----------

Analyzer
~~~~~~~~~~~~~~~

.. code-block:: python

    from hamlet.analyzer import Analyzer

    # Initialize with a dictionary of paths to result directories
    analyzer = Analyzer(path={"scenario1": "./results/example_scenario"})
    analyzer.plot_all()

The ``Analyzer`` class is the main entry point for analyzing simulation results. It loads result data and provides methods for visualization and analysis.

**Key Methods**:

- ``plot_all(save_path=None, **kwargs)``: Generates all available plots for agents, grids, and markets
- ``agents``: Access to agent-specific plotting functionality
- ``grids``: Access to grid-specific plotting functionality
- ``markets``: Access to market-specific plotting functionality

Data Processing
~~~~~~~~~~~~~~~

The Analyzer module includes data processing classes:

- ``DataProcessorBase``: Base class for data processors that handles loading and processing simulation data
- ``AgentDataProcessor``: Processes agent-specific data from simulation results
- ``MarketDataProcessor``: Processes market-specific data from simulation results
- ``GridDataProcessor``: Processes grid-specific data from simulation results

Each data processor is initialized with a path to the results directory and configuration data, and provides methods to process specific types of data.

Visualization
~~~~~~~~~~~~~

Visualization components include:

- ``PlotterBase``: Base class for plotting functionality with a ``plot_all()`` method
- ``AgentPlotter``: Creates agent-specific visualizations
- ``MarketPlotter``: Creates market-specific visualizations
- ``GridPlotter``: Creates grid-specific visualizations

Each plotter is initialized with a path to the results directory, configuration data, and a corresponding data processor. The ``decorator_plot_function`` decorator is used to mark methods as plotting functions.

Example Usage
-------------

Basic Analysis
~~~~~~~~~~~~~~

.. code-block:: python

    from hamlet.analyzer import Analyzer

    # Initialize the Analyzer with a dictionary of paths to result directories
    analyzer = Analyzer(path={
        "scenario1": "./results/example_scenario"
    })
    
    # Generate all plots
    analyzer.plot_all()
    
    # Or access specific plotters for more control
    # Agent-specific plots
    analyzer.agents.plot_all()
    
    # Market-specific plots
    analyzer.markets.plot_all()
    
    # Grid-specific plots
    analyzer.grids.plot_all()

Saving Plots to Disk
~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    from hamlet.analyzer import Analyzer

    # Initialize the Analyzer
    analyzer = Analyzer(path={
        "scenario1": "./results/example_scenario"
    })
    
    # Generate and save all plots to a specific directory
    analyzer.plot_all(save_path="./analysis_results/plots")

Analyzing Multiple Scenarios
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    from hamlet.analyzer import Analyzer

    # Initialize the Analyzer with multiple scenarios
    analyzer = Analyzer(path={
        "scenario_1": "./results/scenario_1",
        "scenario_2": "./results/scenario_2",
        "scenario_3": "./results/scenario_3"
    })
    
    # Generate plots for all scenarios
    analyzer.plot_all()
    
    # The plots will automatically include data from all scenarios for comparison

Extending the Analyzer
----------------------

Users can extend the Analyzer functionality by:

1. Creating custom data processors for specialized analysis
2. Implementing new visualization methods
3. Defining additional KPIs for specific research questions
4. Developing custom export formats for integration with other tools

For more detailed information on specific classes and methods, refer to the API reference documentation.