.. _plotting_workflow:

Plotting Workflow
=================

The Plotting workflow in `mesalab` is dedicated to generating various visualizations from your processed MESA simulation grid. Currently, this workflow does not include specific plotting functionalities for GYRE outputs.

----

Purpose
-------

This workflow automatically generates:

* **Hertzsprung-Russell (HR) Diagrams:** Visualize the individual stellar evolutionary tracks.
* **Blue Loop Crossing Heatmap:** Display the distribution of instability strip crossings across your grid of models. This can be particularly powerful for analyzing large parameter spaces.
* **Blue Loop Visualizations:** `mesalab` generates HR Diagrams (HRD), Color-Magnitude Diagrams (CMD) for Gaia bands, and ``log_g`` `vs.` ``log_Teff`` plots. These visualizations are color-coded by metallicity (Z) and highlight every model that undergoes a `blue loop` and crosses the Instability Strip from the red side.

----

Input
-----

The primary input for the Plotting workflow is the summarized data generated by the :doc:`mesa_analysis_workflow` (``summary_results.csv`` file).

* **Implicit Input Path:** `mesalab` will automatically look for the necessary input data in the ``analysis_results`` directory (which is located inside your main ``output_dir`` of the previous `mesalab` run). If ``summary_results.csv`` is missing, `mesalab` makes the reanalysis of the grid.

----

Image Files
-----------

`mesalab` generates a variety of plots to visualize your MESA simulation results:

* **Blue Loop & Instability Strip Diagrams:**
    * ``CMD_Gaia_all_blue_loop_data.png``: A Color-Magnitude Diagram (CMD) using Gaia bands, displaying all model points that undergo a blue loop and cross the Instability Strip.
    * ``HRD_all_blue_loop_data.png``: An HR Diagram (HRD) showcasing all model points identified as undergoing a blue loop.
    * ``LogL_LogG_all_blue_loop_data.png``: A ``$\log L$`` vs. ``$\log g$`` diagram for blue looping models.
    * ``mesa_grid_blue_loop_heatmap.png``: A heatmap visualizing the blue loop crossing count across your MESA grid (generated from the ``crossing_count_grid.csv`` data).

* **Full Grid HR Diagrams:**
    * ``HR_diagram_[dir]_z[Z_VALUE].png``: An HR Diagram for the entire MESA grid, generated for each metallicity (Z) present in your simulations. The `[dir]` portion of the filename indicates the plot represents data from your main MESA grid input directory. These plots are color-coded by metallicity (Z).
        
        * **Example**: ``HR_diagram_MESA_grid_z0.0090.png`` or ``HR_diagram_MESA_grid_z0.0100.png``.

----

Configuration Parameters
------------------------

Plotting execution and layout are controlled by two distinct sections within your :ref:`YAML configuration <understanding_yaml_config>` file:

1. ``plotting_settings`` section (Workflow Toggles)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These parameters determine *which* plots are generated by the pipeline:

* ``generate_heatmaps``: (Boolean) Set to `true` to generate heatmaps from cross-grid data, typically visualizing properties like instability strip crossing counts. Default: `false`.

* ``generate_hr_diagrams``: (String) Controls the generation of HR diagrams. Options are:
    * `"none"`: No HR diagrams are generated.
    * `"all"`: Generates HR diagrams for all models in the grid.
    * `"drop_zams"`: Generates HR diagrams but excludes the Zero-Age Main Sequence (ZAMS) phase.
    * Default: `"none"`.

* ``generate_blue_loop_plots_with_bc``: (Boolean) If `true`, `mesalab` will generate blue loop-specific plots, including bolometric corrections if applicable. Default: `false`.

2. ``plot_config`` section (Visual Style Overrides)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This optional, global section allows you to customize the visual aesthetics (sizes, resolutions, and margins) of the figures directly from the YAML file. If specified, these values dynamically overwrite the internal defaults defined in ``mesalab/plotting/plot_config.py``.

Supported fields include:

* ``figure``: Customize ``figsize`` (as an ``[width, height]`` array) and ``dpi``.
* ``axes``: Set ``title_size`` and ``label_size``.
* ``scatter``: Adjust ``dot_size`` and plot properties.
* ``all_hrd``: Custom grid plotting rules (e.g., ``max_cols``).

For a complete list of parameters and their detailed descriptions, please refer to the :ref:`Understanding the YAML Configuration <understanding_yaml_config>` section.

----

Controlling Plot Generation
---------------------------

The Plotting workflow in `mesalab` is integrated with the data processing performed by the :doc:`mesa_analysis_workflow` It processes the generated CSVs (``summary_results.csv``, ``crossing_count_grid.csv``).

.. note::
    In the current version, the Plotting workflow is not designed to run as a completely independent module that solely loads and plots pre-existing data via the CLI. Instead, it operates within the context of `mesalab`'s overall data processing workflow.

**Example Configuration for Plot Generation and Style Customization:**

Here's an example of how you can configure your YAML file to enable specific plot types and customize their appearance simultaneously:

.. code-block:: yaml

    general_settings:
      input_dir: path/to/your/grid
      output_dir: ./mesalab_output  
      force_reanalysis: false 

    blue_loop_analysis:
      analyze_blue_loop: true

    plotting_settings:
      generate_heatmaps: true                # Enable heatmap generation
      generate_hr_diagrams: "all"            # Generate HR diagrams for all models
      generate_blue_loop_plots_with_bc: true # Generate blue loop plots with bolometric corrections

    # Global Style Overrides passed to Matplotlib
    plot_config:
      figure:
        figsize: [10, 6]
        dpi: 150
      axes:
        title_size: 16
      scatter:
        dot_size: 32
      colorbar:
        pad: 0.02
      all_hrd:
        figsize: [12, 4]
        max_cols: 7

    gyre_workflow:
      run_gyre_workflow: false # Ensure GYRE workflow is disabled