Plotting Utilities

mesalab.plotting.mesa_plotter.handle_heatmap_generation(args, summary_df_for_plotting, plots_sub_dir, analysis_results_sub_dir, input_dir)[source]

Generate heatmaps showing how often models cross the instability strip.

This function processes the YAML or CSV summary files from a previous analysis to create Z-M (metallicity-mass) heatmaps of instability strip crossing counts. It saves the figures in a subdirectory and labels them with the model grid name.

Parameters:

  • args (argparse.Namespace) – Runtime arguments (e.g., plot options).

  • summary_df_for_plotting (pd.DataFrame) – Optional preloaded summary dataframe (can be None).

  • plots_sub_dir (str) – Output directory for saving heatmap images.

  • analysis_results_sub_dir (str) – Directory with analysis summary files (e.g., YAML/CSV).

  • input_dir (str) – Name of the input model grid (used in plot titles/filenames).

Returns:

None

Example

>>> from mesalab.plotting import mesa_plotter
>>> summary_dir = "results/summary"
>>> plot_dir = "results/plots"
>>> mesa_plotter.handle_heatmap_generation(args, None, plot_dir, summary_dir, input_dir="grid_z001")
Heatmaps saved to results/plots showing crossing frequencies by Z and M.
mesalab.plotting.mesa_plotter.handle_blue_loop_bc_plotting(args, combined_detail_data_for_plotting, blue_loop_plots_bc_sub_dir, detail_files_output_dir, plot_cfg=None)[source]

Plot blue loop tracks in the color–magnitude diagram with bolometric corrections.

Reads preprocessed detail CSV files and bolometric correction data (e.g., for Gaia bands), then plots the evolutionary tracks during the blue loop phase on CMDs. Used for visualizing where and how models populate the instability strip.

Parameters:

  • args (argparse.Namespace) – Runtime arguments (e.g., filters, flags).

  • combined_detail_data_for_plotting (pd.DataFrame) – Optional preloaded detail data.

  • blue_loop_plots_bc_sub_dir (str) – Directory to save output CMD plots.

  • detail_files_output_dir (str) – Directory where the input detail CSVs are located.

Returns:

None

Example

>>> from mesalab.plotting import mesa_plotter
>>> detail_dir = "processed/detail_data"
>>> cmd_plot_dir = "results/plots/cmd"
>>> mesa_plotter.handle_blue_loop_bc_plotting(args, None, cmd_plot_dir, detail_dir)
Plots saved for each Z showing blue loop positions in Gaia CMD.
mesalab.plotting.mesa_plotter.handle_hr_diagram_generation(args, plots_sub_dir, full_history_data_for_plotting, drop_zams, plot_cfg=None)[source]

Generate Hertzsprung–Russell diagrams from full stellar evolutionary tracks.

This function loops through available history data by metallicity, and plots the full evolutionary path (log Teff vs log L). Optionally filters out pre-ZAMS data points for clarity.

Parameters:

  • args (argparse.Namespace) – Command-line arguments including force overwrite, limits.

  • plots_sub_dir (str) – Output directory for saving HR diagrams.

  • full_history_data_for_plotting (list) – List of DataFrames, each representing a full history for a single MESA run. (Updated from dict to list to match all_hrd_plotter.py)

  • drop_zams (bool) – Whether to skip points before the zero-age main sequence.

  • plot_cfg (dict, optional) – A dictionary of plotting configurations. If None, default configurations from ‘plot_config.py’ will be used.

Returns:

None

Example

>>> from mesalab.plotting import mesa_plotter
>>> data = [df_z004_m1, df_z004_m2, df_z014_m1] # Example: list of DataFrames
>>> output_dir = "output/plots"
>>> mesa_plotter.handle_hr_diagram_generation(args, output_dir, data, drop_zams=True, plot_cfg=None)
HR diagrams saved to output/plots for each metallicity.
mesalab.plotting.heatmap_generator.generate_heatmaps_and_time_diff_csv(cross_data_df, summary_csv_path, unique_zs, unique_masses, plots_output_dir, analysis_results_output_dir, model_name='MESA Grid Analysis', blue_loop_output_type='all', analyze_blue_loop=False, plot_cfg=None)[source]

Generates a heatmap showing the number of instability strip (IS) crossings as a function of initial stellar mass and metallicity, and optionally writes a CSV with blue loop and instability phase durations.

This function is typically used after the blue loop analysis step in the pipeline. The heatmap is a visual representation of the cross_data_df grid, with different colors representing the number of IS crossings for each unique Mass-Metallicity pair. Missing data points (NaNs) are explicitly handled and colored light grey.

Parameters:

  • cross_data_df (pd.DataFrame) – Grid-like DataFrame with metallicities as index and masses as columns, each value representing the number of IS crossings (0–5).

  • summary_csv_path (str) – Path to the summary CSV file containing time information.

  • unique_zs (list) – List of sorted unique metallicities (Z values).

  • unique_masses (list) – List of sorted unique initial masses.

  • plots_output_dir (str) – Directory to save the generated heatmap image.

  • analysis_results_output_dir (str) – Directory to save the output time difference CSV.

  • model_name (str) – Optional name of the model grid (used in plot title).

  • blue_loop_output_type (str) – Either ‘all’ or ‘summary’; controls detail level of summary input.

  • analyze_blue_loop (bool) – If True, the function generates a CSV with phase durations.

  • plot_cfg (dict, optional) – A dictionary of plotting configurations. If None, default configurations from ‘plot_config.py’ will be used.

Returns:

None

Example

>>> import pandas as pd
>>> import numpy as np
>>> import os
>>> from mesalab.plotting import heatmap_generator
>>>
>>> plots_dir = 'output/plots'
>>> results_dir = 'output/analysis_results'
>>> os.makedirs(plots_dir, exist_ok=True)
>>> os.makedirs(results_dir, exist_ok=True)
>>>
>>> # Create a dummy `cross_data_df`
>>> cross_df = pd.DataFrame({
...     0.8: [0, 1, 2],
...     0.9: [1, np.nan, 3],
...     1.0: [2, 3, 5]
... }, index=[0.005, 0.008, 0.012])
>>>
>>> # Create a dummy summary CSV file with time data
>>> summary_df = pd.DataFrame({
...     'initial_mass': [0.8, 0.8, 0.8, 0.9, 0.9, 0.9, 1.0, 1.0, 1.0],
...     'initial_Z': [0.005, 0.008, 0.012, 0.005, 0.008, 0.012, 0.005, 0.008, 0.012],
...     'blue_loop_crossing_count': [0, 1, 2, 1, 0, 3, 2, 3, 5],
...     'blue_loop_start_age': [np.nan, 10.0, 15.0, 12.0, np.nan, 18.0, 20.0, 25.0, 30.0],
...     'blue_loop_end_age': [np.nan, 12.0, 17.0, 15.0, np.nan, 21.0, 22.0, 28.0, 33.0],
...     'instability_start_age': [np.nan, 10.5, 15.5, 12.5, np.nan, 18.5, 20.5, 25.5, 30.5],
...     'instability_end_age': [np.nan, 11.5, 16.5, 13.5, np.nan, 19.5, 21.5, 26.5, 31.5],
...     'calculated_blue_loop_duration': [np.nan, 2.0, 2.0, 3.0, np.nan, 3.0, 2.0, 3.0, 3.0],
...     'calculated_instability_duration': [np.nan, 1.0, 1.0, 1.0, np.nan, 1.0, 1.0, 1.0, 1.0]
... })
>>> summary_csv_path = os.path.join(results_dir, 'summary.csv')
>>> summary_df.to_csv(summary_csv_path, index=False)
>>>
>>> # Call the function with the dummy data and paths
>>> print("Running example...")
>>> generate_heatmaps_and_time_diff_csv(
...     cross_df,
...     summary_csv_path,
...     unique_zs=[0.005, 0.008, 0.012],
...     unique_masses=[0.8, 0.9, 1.0],
...     plots_output_dir=plots_dir,
...     analysis_results_output_dir=results_dir,
...     analyze_blue_loop=True
... )

HRD Plotter

mesalab.plotting.all_hrd_plotter.generate_all_hr_diagrams(all_history_data_flat: list, model_name: str, output_dir: str, logT_blue_edge: list, logL_blue_edge: list, logT_red_edge: list, logL_red_edge: list, drop_zams: bool = False, plot_cfg: dict = None)[source]

Generates Hertzsprung-Russell (HR) diagrams for pre-loaded MESA run data, grouping plots by metallicity and saving each metallicity’s plots as a single image.

The pre-main sequence (pre-MS) phase can be excluded from the plots if ‘drop_zams’ is True.

Plots are sorted by initial mass within each metallicity group; the subplot layout is fixed to 4 columns.

If data is insufficient after trimming (and ‘drop_zams’ is True), the specific subplot for that run is skipped, and a warning is logged.

Parameters:

  • all_history_data_flat (list) – A flat list of full, untrimmed history DataFrames for all MESA runs. Each DataFrame is expected to have ‘initial_Z’ and ‘initial_mass’ columns. (This is the ‘flattened_full_history_data_for_plotting’ from mesa_analyzer).

  • model_name (str) – The name of the MESA model, used for constructing file paths and plot titles (e.g., ‘nad_convos’).

  • output_dir (str) – The directory where the generated HR diagram images will be saved.

  • logT_blue_edge (list) – Logarithm of effective temperatures for the blue edge of the instability strip.

  • logL_blue_edge (list) – Logarithm of luminosities for the blue edge of the instability strip.

  • logT_red_edge (list) – Logarithm of effective temperatures for the red edge of the instability strip.

  • logL_red_edge (list) – Logarithm of luminosities for the red edge of the instability strip.

  • drop_zams (bool, optional) – If True, the pre-main sequence (pre-MS) phase is trimmed from the beginning of the track using the ‘center_h1’ drop criterion (or ‘log_L’ minimum as fallback). Defaults to False (i.e., full track is plotted).

  • plot_cfg (dict, optional) – A dictionary of plotting configurations. If None, default configurations from ‘plot_config.py’ will be used.

Returns:

None

Example

>>> import pandas as pd
>>> import os
>>> from mesalab.plotting import all_hrd_plotter
>>> import numpy as np
>>> # Define the output directory
>>> output_dir = 'output/plots'
>>> os.makedirs(output_dir, exist_ok=True)
>>>
>>> # Define dummy data for two different runs (M=1.0, Z=0.012 and M=1.5, Z=0.012)
>>> df1 = pd.DataFrame({
...     'initial_mass': [1.0] * 20,
...     'initial_Z': [0.012] * 20,
...     'log_Teff': np.linspace(3.7, 3.8, 20),
...     'log_L': np.linspace(1.0, 1.5, 20),
...     'model_number': np.arange(20),
...     'center_h1': np.linspace(0.7, 0.6, 20)
... })
>>> df2 = pd.DataFrame({
...     'initial_mass': [1.5] * 20,
...     'initial_Z': [0.012] * 20,
...     'log_Teff': np.linspace(3.8, 3.9, 20),
...     'log_L': np.linspace(1.5, 2.0, 20),
...     'model_number': np.arange(20),
...     'center_h1': np.linspace(0.7, 0.6, 20)
... })
>>> # The function expects a flat list of DataFrames
>>> all_data = [df1, df2]
>>>
>>> # Create dummy instability strip data
>>> logT_blue = [3.8, 3.75, 3.7]
>>> logL_blue = [1.5, 1.0, 0.5]
>>> logT_red = [3.7, 3.65, 3.6]
>>> logL_red = [1.5, 1.0, 0.5]
>>>
>>> # Call the function
>>> all_hrd_plotter.generate_all_hr_diagrams(
...     all_history_data_flat=all_data,
...     model_name='dummy_model',
...     output_dir=output_dir,
...     logT_blue_edge=logT_blue,
...     logL_blue_edge=logL_blue,
...     logT_red_edge=logT_red,
...     logL_red_edge=logL_red,
...     drop_zams=True
... )