plot

name	plot
description	Skill for scientific plotting using matplotlib. Generates, executes, and verifies publication-quality plots directly via run_python and run_bash.
metadata	{"tools":["run_bash","run_python","show_plot"],"tags":["PLOT","MATPLOTLIB","UTILITY"]}

Workflow

1. Determine output directory Use run_python to build a unique timestamped output directory. First try plots/ relative to the current working directory; fall back to $MATCLAW_WORKSPACE/plots/ if cwd is not writable:

   import os, datetime, random
   tag = datetime.datetime.now().strftime("%Y%m%d%H%M%S") + f"_{random.randint(100000,999999)}"
   # Prefer a plots/ subdir next to the data (cwd)
   cwd_plots = os.path.join(os.getcwd(), "plots", tag)
   try:
       os.makedirs(cwd_plots, exist_ok=True)
       output_dir = cwd_plots
   except OSError:
       ws_root = os.environ.get("MATCLAW_WORKSPACE") or os.path.expanduser("~/.workspace")
       output_dir = os.path.join(ws_root, "plots", tag)
       os.makedirs(output_dir, exist_ok=True)
   print(output_dir)
   

   Capture the printed path — use it as OUTPUT_DIR in all subsequent steps.

2. Write the plotting script Use run_python to write a complete Python script to OUTPUT_DIR/plot.py. The script must:

   • Import only allowed modules: matplotlib, numpy, pandas, scipy, seaborn, ase, json, csv, pathlib, os, datetime
   • Set OUTPUT_DIR = "<absolute_path>" at the top (hardcoded to the resolved path from step 1)
   • Load data from the absolute path provided by the user
   • Create the figure with plt.subplots(figsize=..., dpi=300)
   • Apply publication-quality formatting (axis labels with units, legend, tight_layout())
   • Save with plt.savefig(os.path.join(OUTPUT_DIR, filename), dpi=300, bbox_inches="tight")
   • No plt.show()
   • Print the final output path at the end: print("PLOT_PATH:", save_path)

   Scientific context shortcuts:

   • Band structure: k-path x-axis with symmetry labels (Γ X L …), E − E_F on y-axis, Fermi level at y=0
   • DOS: energy x-axis, vertical Fermi level line, fill_between for partial DOS
   • Convergence: parameter on x-axis, horizontal reference line, legend per dataset
   • MD / time-series: time [fs/ps] x-axis, moving average if noisy
   • Scatter / heatmap: equal aspect if coordinates; colorbar with units

3. Execute the script

   exec(open("<OUTPUT_DIR>/plot.py").read())
   

   Or equivalently pass the script content to run_python.

4. Verify output Use run_bash to confirm the file exists and is non-empty:

   ls -lh <OUTPUT_DIR>/*.png
   

5. Register the plot Call show_plot(plot_path="<absolute_path_to_png>"). This emits the structured {"plot_path": "..."} response that the UI needs to display the image. Only call it after run_bash confirms the file exists.

Rules

• Always use absolute paths for data loading and saving.
• Use timestamps in filenames to prevent overwrites.
• If execution fails, read the error, fix the code, and retry (max 3 attempts).
• Never fabricate a plot_path — only report the path after run_bash confirms the file exists.
• Data files passed as relative paths should be resolved relative to MATCLAW_WORKSPACE (same logic as step 1).