@brainpilot/skills 0.0.6 → 0.0.7

package/skills/16_Animal_Behavior/ethoclaw-multiparameter-clustermap-generate/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: ethoclaw-multiparameter-clustermap-generate
+description: "Generate journal-style hierarchical clustering clustermaps (heatmap+dendrogram) from a folder of .h5/.hdf5 files (KinematicParameter/ParameterName + ParameterData). Summarize frames per sample (mean/median/max), optionally normalize (column z-score), cluster samples/parameters, and export PNG/PDF + CSV + linkage arrays. Use when user asks for multi-parameter clustering heatmap/clustering tree/full parameter full sample clustering figure generation."
+---
+
+# H5 Multi-parameter Clustermap
+
+Create a Prism-like clustermap (heatmap + dendrogram) for **all parameters × all samples** from `.h5` files.
+
+## Assumptions about H5 structure
+Each `.h5` must contain:
+- `KinematicParameter/ParameterName` (parameter name list)
+- `KinematicParameter/ParameterData` (2D array: frames/timepoints × parameters)
+
+## How it works
+- For each sample (one `.h5`): summarize every parameter’s time-series into a single value (`mean`/`median`/`max`).
+- Stack into a feature matrix: **rows = samples**, **cols = parameters**.
+- Optional normalization: parameter-wise z-score across samples (column z-score).
+- Hierarchical cluster rows and columns and draw clustermap.
+
+## Quick start (no config editing)
+
+### Option 1: Run in the project folder (recommended)
+
+```bash
+cd /d C:\\path\\to\\your_project
+python <skill>/scripts/cluster_all_params.py
+```
+
+It will:
+- auto-read all `*.h5` under the current folder
+- write outputs to `results/cluster_all_kinematic_params/`
+
+### Option 2: Pass project path explicitly
+
+```bash
+python scripts/cluster_all_params.py --root "C:\\path\\to\\your_project"
+```
+
+### Option 3: Use TOML config (only if you want a saved preset)
+
+```bash
+python scripts/cluster_all_params_from_config.py --config references/config.example.toml
+```
+
+## Outputs
+In your configured output folder:
+- `clustermap_all_params.png`
+- `clustermap_all_params.pdf`
+- `feature_matrix.csv`
+- `row_linkage.npy`, `col_linkage.npy`
+- `clustering_meta.json`
+
+## Config knobs you’ll likely change
+
+CLI flags (no file edits):
+- `--summary mean|median|max`
+- `--style nature|cell|minimal`
+- `--cmap RdBu_r|coolwarm|vlag|icefire|...` (used when `style` doesn’t override)
+- `--linewidths` / `--linecolor` (grid lines)
+- `--metric euclidean|correlation`
+
+TOML (optional saved preset):
+- `features.summary = mean|median|max`
+- `plot.style = nature|cell|minimal`
+- `plot.cmap = RdBu_r|coolwarm|vlag|icefire|...`
+- `plot.linewidths` / `plot.linecolor`
+- `clustering.metric = euclidean|correlation`
+
+## Notes
+- If `ParameterName` ordering differs between files, the script will stop (to avoid mixing mismatched features).
+- If you have many parameters, set smaller `plot.xtick_fontsize` and rotate ticks.

package/skills/16_Animal_Behavior/ethoclaw-multiparameter-clustermap-generate/references/config.example.toml

@@ -0,0 +1,56 @@
+# h5-multiparameter-clustermap config
+
+[io]
+# Folder containing .h5 files
+root = "C:/Users/ASUS/Desktop/2Dxy_test_project/random_project"
+
+# Output directory (relative to root unless absolute)
+outdir = "results/cluster_all_kinematic_params"
+
+[h5]
+# Datasets inside the .h5
+param_name_dataset = "KinematicParameter/ParameterName"
+param_data_dataset = "KinematicParameter/ParameterData"
+
+[features]
+# How to summarize each parameter's time-series per sample
+# Options: mean | median | max
+summary = "mean"
+
+# Normalize feature matrix columns (parameter-wise) across samples
+# Options: col_zscore | none
+normalize = "col_zscore"
+
+[clustering]
+# Options: average | complete | ward | single
+linkage = "average"
+
+# Options: euclidean | correlation  (correlation corresponds to 1-Pearson distance)
+metric = "euclidean"
+
+[plot]
+# Journal-style presets (recommended): nature | cell | minimal
+# If set, will provide defaults for cmap/fonts/grid.
+style = "nature"
+
+# Colormap for heatmap. Works with matplotlib colormaps (e.g., RdBu_r, coolwarm)
+# and seaborn palettes (vlag, icefire). Ignored if style enforces a cmap.
+cmap = "RdBu_r"
+
+# Add grid lines (makes parameter boundaries clearer)
+linewidths = 0.4
+linecolor = "white"
+
+# Figure size (inches)
+figwidth = 18
+figheight = 10
+
+# Tick label styling (useful when many parameters)
+xtick_rotation = 90
+xtick_fontsize = 7
+ytick_fontsize = 8
+
+# Save both formats
+save_png = true
+save_pdf = true
+png_dpi = 300

package/skills/16_Animal_Behavior/ethoclaw-multiparameter-clustermap-generate/scripts/cluster_all_params.py

@@ -0,0 +1,232 @@
+# -*- coding: utf-8 -*-
+"""All-params all-samples kinematic clustermap (no config editing required).
+
+Run it from ANY project folder that contains .h5 files:
+
+  cd /d C:/path/to/your_project
+  python <skill>/scripts/cluster_all_params.py
+
+Or pass an explicit root:
+
+  python scripts/cluster_all_params.py --root "C:/path/to/your_project"
+
+Outputs default to:
+  <root>/results/cluster_all_kinematic_params/
+
+You can optionally tweak behavior via CLI flags (no file edits):
+  --summary mean|median|max
+  --style nature|cell|minimal
+  --cmap RdBu_r|coolwarm|vlag|icefire|...
+"""
+
+import argparse, os, re, glob, json
+import numpy as np
+
+import h5py
+import pandas as pd
+import seaborn as sns
+import matplotlib
+matplotlib.use('Agg')
+
+from scipy.cluster.hierarchy import linkage
+
+PARAM_NAME_DS_DEFAULT = 'KinematicParameter/ParameterName'
+PARAM_DATA_DS_DEFAULT = 'KinematicParameter/ParameterData'
+
+
+def natural_key(s: str):
+    return [int(t) if t.isdigit() else t.lower() for t in re.split(r'(\d+)', s)]
+
+
+def _decode(x):
+    if isinstance(x, bytes):
+        return x.decode('utf-8', errors='ignore')
+    return str(x)
+
+
+def summarize_ts(x: np.ndarray, method: str) -> float:
+    x = np.asarray(x, dtype=float)
+    x[~np.isfinite(x)] = np.nan
+    if method == 'median':
+        return float(np.nanmedian(x))
+    if method == 'max':
+        return float(np.nanmax(x))
+    return float(np.nanmean(x))
+
+
+def col_zscore(M: np.ndarray) -> np.ndarray:
+    mu = np.nanmean(M, axis=0, keepdims=True)
+    sd = np.nanstd(M, axis=0, keepdims=True)
+    sd[sd == 0] = 1.0
+    return (M - mu) / sd
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--root', default='.', help='Project folder containing .h5 files (default: current directory)')
+    ap.add_argument('--outdir', default='', help='Output folder (default: results/cluster_all_kinematic_params under root)')
+
+    ap.add_argument('--param-name-ds', default=PARAM_NAME_DS_DEFAULT)
+    ap.add_argument('--param-data-ds', default=PARAM_DATA_DS_DEFAULT)
+
+    ap.add_argument('--summary', default='mean', choices=['mean','median','max'])
+    ap.add_argument('--normalize', default='col_zscore', choices=['col_zscore','none'])
+
+    ap.add_argument('--linkage', dest='linkage_method', default='average', choices=['average','complete','ward','single'])
+    ap.add_argument('--metric', default='euclidean', choices=['euclidean','correlation'])
+
+    ap.add_argument('--style', default='nature', choices=['nature','cell','minimal'])
+    ap.add_argument('--cmap', default='RdBu_r', help='Matplotlib cmap name (used when style does not override)')
+
+    ap.add_argument('--linewidths', type=float, default=0.4)
+    ap.add_argument('--linecolor', default='white')
+    ap.add_argument('--figwidth', type=float, default=18)
+    ap.add_argument('--figheight', type=float, default=10)
+    ap.add_argument('--xtick-rotation', type=float, default=90)
+    ap.add_argument('--xtick-fontsize', type=float, default=7)
+    ap.add_argument('--ytick-fontsize', type=float, default=8)
+
+    ap.add_argument('--save-png', action='store_true', default=True)
+    ap.add_argument('--no-save-png', action='store_false', dest='save_png')
+    ap.add_argument('--save-pdf', action='store_true', default=True)
+    ap.add_argument('--no-save-pdf', action='store_false', dest='save_pdf')
+    ap.add_argument('--png-dpi', type=int, default=300)
+
+    args = ap.parse_args()
+
+    root = os.path.abspath(args.root)
+    outdir = args.outdir.strip()
+    if not outdir:
+        outdir = os.path.join(root, 'results', 'cluster_all_kinematic_params')
+    elif not os.path.isabs(outdir):
+        outdir = os.path.join(root, outdir)
+    os.makedirs(outdir, exist_ok=True)
+
+    h5_files = sorted(glob.glob(os.path.join(root, '*.h5')), key=natural_key)
+    if not h5_files:
+        raise SystemExit(f'No .h5 files found under: {root}')
+
+    sample_names = []
+    feats_list = []
+    per_sample = {}
+    param_names_ref = None
+
+    for hp in h5_files:
+        sample = os.path.splitext(os.path.basename(hp))[0]
+        with h5py.File(hp, 'r') as h5:
+            if args.param_name_ds not in h5 or args.param_data_ds not in h5:
+                continue
+            names_raw = h5[args.param_name_ds][()]
+            param_names = [_decode(n).strip() for n in names_raw]
+            data = np.asarray(h5[args.param_data_ds][()])
+            if data.ndim != 2:
+                continue
+
+            if param_names_ref is None:
+                param_names_ref = param_names
+            else:
+                if len(param_names) != len(param_names_ref) or any(a != b for a, b in zip(param_names, param_names_ref)):
+                    raise SystemExit(f"ParameterName mismatch in {os.path.basename(hp)}; cannot combine reliably.")
+
+            feats = [summarize_ts(data[:, j], args.summary) for j in range(data.shape[1])]
+
+            sample_names.append(sample)
+            feats_list.append(np.array(feats, dtype=float))
+            per_sample[sample] = {
+                'h5': os.path.basename(hp),
+                'n_frames': int(data.shape[0]),
+                'n_params': int(data.shape[1]),
+            }
+
+    if not feats_list:
+        raise SystemExit('No valid kinematic parameter data found in any .h5')
+
+    M = np.vstack(feats_list)
+    if args.normalize == 'col_zscore':
+        M = col_zscore(M)
+
+    df = pd.DataFrame(M, index=sample_names, columns=param_names_ref)
+    df.to_csv(os.path.join(outdir, 'feature_matrix.csv'))
+
+    row_link = linkage(df.values, method=args.linkage_method, metric=args.metric)
+    col_link = linkage(df.values.T, method=args.linkage_method, metric=args.metric)
+
+    np.save(os.path.join(outdir, 'row_linkage.npy'), row_link)
+    np.save(os.path.join(outdir, 'col_linkage.npy'), col_link)
+
+    # style presets
+    style_l = str(args.style).lower()
+    if style_l == 'cell':
+        sns.set_theme(style='white', context='paper', font_scale=0.9)
+        cmap_use = 'RdBu_r'
+    elif style_l == 'nature':
+        sns.set_theme(style='white', context='paper', font_scale=0.95)
+        cmap_use = 'vlag'
+    elif style_l == 'minimal':
+        sns.set_theme(style='white', context='paper', font_scale=0.9)
+        cmap_use = args.cmap
+        args.linewidths = 0.0
+    else:
+        sns.set_theme(style='white', context='paper', font_scale=0.9)
+        cmap_use = args.cmap
+
+    g = sns.clustermap(
+        df,
+        row_linkage=row_link,
+        col_linkage=col_link,
+        cmap=cmap_use,
+        center=0.0 if args.normalize == 'col_zscore' else None,
+        linewidths=args.linewidths,
+        linecolor=args.linecolor,
+        xticklabels=True,
+        yticklabels=True,
+        figsize=(args.figwidth, args.figheight),
+    )
+
+    try:
+        g.ax_heatmap.set_xticklabels(g.ax_heatmap.get_xticklabels(), rotation=args.xtick_rotation, ha='right', fontsize=args.xtick_fontsize)
+        g.ax_heatmap.set_yticklabels(g.ax_heatmap.get_yticklabels(), fontsize=args.ytick_fontsize)
+    except Exception:
+        pass
+
+    g.fig.suptitle(
+        f"All kinematic params ({args.summary}) | norm={args.normalize} | linkage={args.linkage_method}, metric={args.metric}",
+        y=1.02,
+    )
+
+    if args.save_png:
+        g.savefig(os.path.join(outdir, 'clustermap_all_params.png'), dpi=args.png_dpi, bbox_inches='tight')
+    if args.save_pdf:
+        g.savefig(os.path.join(outdir, 'clustermap_all_params.pdf'), bbox_inches='tight')
+
+    meta = {
+        'root': root,
+        'outdir': outdir,
+        'source': {'param_name_dataset': args.param_name_ds, 'param_data_dataset': args.param_data_ds},
+        'summary': args.summary,
+        'normalize': args.normalize,
+        'linkage_method': args.linkage_method,
+        'distance_metric': args.metric,
+        'plot': {
+            'style': args.style,
+            'cmap': cmap_use,
+            'linewidths': args.linewidths,
+            'linecolor': args.linecolor,
+            'xtick_rotation': args.xtick_rotation,
+            'xtick_fontsize': args.xtick_fontsize,
+            'ytick_fontsize': args.ytick_fontsize,
+            'png_dpi': args.png_dpi,
+        },
+        'n_samples': int(df.shape[0]),
+        'n_params': int(df.shape[1]),
+        'per_sample': per_sample,
+    }
+    with open(os.path.join(outdir, 'clustering_meta.json'), 'w', encoding='utf-8') as f:
+        json.dump(meta, f, ensure_ascii=False, indent=2)
+
+    print('OK')
+    print('Wrote:', outdir)
+
+
+if __name__ == '__main__':
+    main()

package/skills/16_Animal_Behavior/ethoclaw-multiparameter-clustermap-generate/scripts/cluster_all_params_from_config.py

@@ -0,0 +1,236 @@
+# -*- coding: utf-8 -*-
+"""Cluster all kinematic parameters across all samples from a folder of .h5 files.
+
+Reads config from TOML.
+
+Each sample is summarized into one feature vector (one value per parameter)
+from KinematicParameter/ParameterData (T x P).
+
+Outputs:
+- clustermap_all_params.png/.pdf
+- feature_matrix.csv
+- row_linkage.npy / col_linkage.npy
+- clustering_meta.json
+
+Usage:
+  python scripts/cluster_all_params_from_config.py --config references/config.example.toml
+
+You can copy config.example.toml and edit it.
+"""
+
+import argparse, os, re, glob, json
+import numpy as np
+
+import h5py
+import pandas as pd
+import seaborn as sns
+import matplotlib
+matplotlib.use('Agg')
+
+from scipy.cluster.hierarchy import linkage
+
+try:
+    import tomllib  # py3.11+
+except Exception:  # pragma: no cover
+    import tomli as tomllib  # type: ignore
+
+
+def natural_key(s: str):
+    return [int(t) if t.isdigit() else t.lower() for t in re.split(r'(\d+)', s)]
+
+
+def _decode(x):
+    if isinstance(x, bytes):
+        return x.decode('utf-8', errors='ignore')
+    return str(x)
+
+
+def summarize_ts(x: np.ndarray, method: str) -> float:
+    x = np.asarray(x, dtype=float)
+    x[~np.isfinite(x)] = np.nan
+    if method == 'median':
+        return float(np.nanmedian(x))
+    if method == 'max':
+        return float(np.nanmax(x))
+    return float(np.nanmean(x))
+
+
+def col_zscore(M: np.ndarray) -> np.ndarray:
+    mu = np.nanmean(M, axis=0, keepdims=True)
+    sd = np.nanstd(M, axis=0, keepdims=True)
+    sd[sd == 0] = 1.0
+    return (M - mu) / sd
+
+
+def read_toml(path: str) -> dict:
+    with open(path, 'rb') as f:
+        return tomllib.load(f)
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--config', required=True, help='Path to TOML config')
+    args = ap.parse_args()
+
+    cfg = read_toml(args.config)
+
+    root = cfg['io']['root']
+    outdir = cfg['io']['outdir']
+    if not os.path.isabs(outdir):
+        outdir = os.path.join(root, outdir)
+    os.makedirs(outdir, exist_ok=True)
+
+    param_name_ds = cfg['h5'].get('param_name_dataset', 'KinematicParameter/ParameterName')
+    param_data_ds = cfg['h5'].get('param_data_dataset', 'KinematicParameter/ParameterData')
+
+    summary = cfg['features'].get('summary', 'mean')
+    normalize = cfg['features'].get('normalize', 'col_zscore')
+
+    linkage_method = cfg['clustering'].get('linkage', 'average')
+    metric = cfg['clustering'].get('metric', 'euclidean')
+
+    style = cfg['plot'].get('style', 'nature')
+    cmap = cfg['plot'].get('cmap', 'RdBu_r')
+    linewidths = float(cfg['plot'].get('linewidths', 0.4))
+    linecolor = cfg['plot'].get('linecolor', 'white')
+    figwidth = float(cfg['plot'].get('figwidth', 18))
+    figheight = float(cfg['plot'].get('figheight', 10))
+    xtick_rotation = float(cfg['plot'].get('xtick_rotation', 90))
+    xtick_fontsize = float(cfg['plot'].get('xtick_fontsize', 7))
+    ytick_fontsize = float(cfg['plot'].get('ytick_fontsize', 8))
+    save_png = bool(cfg['plot'].get('save_png', True))
+    save_pdf = bool(cfg['plot'].get('save_pdf', True))
+    png_dpi = int(cfg['plot'].get('png_dpi', 300))
+
+    h5_files = sorted(glob.glob(os.path.join(root, '*.h5')), key=natural_key)
+    if not h5_files:
+        raise SystemExit(f'No .h5 files found under {root}')
+
+    sample_names = []
+    feats_list = []
+    per_sample = {}
+    param_names_ref = None
+
+    for hp in h5_files:
+        sample = os.path.splitext(os.path.basename(hp))[0]
+        with h5py.File(hp, 'r') as h5:
+            if param_name_ds not in h5 or param_data_ds not in h5:
+                continue
+            names_raw = h5[param_name_ds][()]
+            param_names = [_decode(n).strip() for n in names_raw]
+            data = np.asarray(h5[param_data_ds][()])
+            if data.ndim != 2:
+                continue
+
+            if param_names_ref is None:
+                param_names_ref = param_names
+            else:
+                if len(param_names) != len(param_names_ref) or any(a != b for a, b in zip(param_names, param_names_ref)):
+                    raise SystemExit(f"ParameterName mismatch in {os.path.basename(hp)}; cannot combine reliably.")
+
+            feats = [summarize_ts(data[:, j], summary) for j in range(data.shape[1])]
+
+            sample_names.append(sample)
+            feats_list.append(np.array(feats, dtype=float))
+            per_sample[sample] = {
+                'h5': os.path.basename(hp),
+                'n_frames': int(data.shape[0]),
+                'n_params': int(data.shape[1]),
+            }
+
+    if not feats_list:
+        raise SystemExit('No valid kinematic parameter data found in any .h5')
+
+    M = np.vstack(feats_list)
+    if normalize == 'col_zscore':
+        M = col_zscore(M)
+
+    df = pd.DataFrame(M, index=sample_names, columns=param_names_ref)
+
+    df.to_csv(os.path.join(outdir, 'feature_matrix.csv'))
+
+    row_link = linkage(df.values, method=linkage_method, metric=metric)
+    col_link = linkage(df.values.T, method=linkage_method, metric=metric)
+
+    np.save(os.path.join(outdir, 'row_linkage.npy'), row_link)
+    np.save(os.path.join(outdir, 'col_linkage.npy'), col_link)
+
+    # --- plotting style presets (lightweight, journal-ish defaults) ---
+    style_l = str(style).lower()
+    if style_l == 'cell':
+        sns.set_theme(style='white', context='paper', font_scale=0.9)
+        # diverging, publication-friendly
+        cmap_use = 'RdBu_r'
+        linewidths = linewidths if linewidths is not None else 0.4
+    elif style_l == 'nature':
+        sns.set_theme(style='white', context='paper', font_scale=0.95)
+        cmap_use = 'vlag'  # clean diverging
+    elif style_l == 'minimal':
+        sns.set_theme(style='white', context='paper', font_scale=0.9)
+        cmap_use = cmap
+        linewidths = 0.0
+    else:
+        sns.set_theme(style='white', context='paper', font_scale=0.9)
+        cmap_use = cmap
+
+    g = sns.clustermap(
+        df,
+        row_linkage=row_link,
+        col_linkage=col_link,
+        cmap=cmap_use,
+        center=0.0 if normalize == 'col_zscore' else None,
+        linewidths=linewidths,
+        linecolor=linecolor,
+        xticklabels=True,
+        yticklabels=True,
+        figsize=(figwidth, figheight),
+    )
+
+    # tick label polish
+    try:
+        g.ax_heatmap.set_xticklabels(g.ax_heatmap.get_xticklabels(), rotation=xtick_rotation, ha='right', fontsize=xtick_fontsize)
+        g.ax_heatmap.set_yticklabels(g.ax_heatmap.get_yticklabels(), fontsize=ytick_fontsize)
+    except Exception:
+        pass
+
+    g.fig.suptitle(
+        f"All kinematic params ({summary}) | norm={normalize} | linkage={linkage_method}, metric={metric}",
+        y=1.02,
+    )
+
+    if save_png:
+        g.savefig(os.path.join(outdir, 'clustermap_all_params.png'), dpi=png_dpi, bbox_inches='tight')
+    if save_pdf:
+        g.savefig(os.path.join(outdir, 'clustermap_all_params.pdf'), bbox_inches='tight')
+
+    meta = {
+        'root': root,
+        'outdir': outdir,
+        'source': {'param_name_dataset': param_name_ds, 'param_data_dataset': param_data_ds},
+        'summary': summary,
+        'normalize': normalize,
+        'linkage_method': linkage_method,
+        'distance_metric': metric,
+        'plot': {
+            'style': style,
+            'cmap': cmap_use,
+            'linewidths': linewidths,
+            'linecolor': linecolor,
+            'xtick_rotation': xtick_rotation,
+            'xtick_fontsize': xtick_fontsize,
+            'ytick_fontsize': ytick_fontsize,
+            'png_dpi': png_dpi,
+        },
+        'n_samples': int(df.shape[0]),
+        'n_params': int(df.shape[1]),
+        'per_sample': per_sample,
+    }
+    with open(os.path.join(outdir, 'clustering_meta.json'), 'w', encoding='utf-8') as f:
+        json.dump(meta, f, ensure_ascii=False, indent=2)
+
+    print('OK')
+    print('Wrote:', outdir)
+
+
+if __name__ == '__main__':
+    main()

package/skills/16_Animal_Behavior/ethoclaw-multiparameter-radar-generate/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: ethoclaw-multiparameter-radar-generate
+description: Generate GraphPad Prism-like multi-parameter radar charts from a folder of HDF5 .h5/.hdf5 files (KinematicParameter/ParameterName + ParameterData). Summarize frames per sample (mean/median/max), normalize (min-max or z-score), and plot per-sample radars and/or group-mean comparison radars (group inferred from filenames). Outputs publication-style PNG/PDF and CSV. Use when user asks for multi-parameter radar chart generation/radar chart comparison.
+---
+
+# H5 Multi-parameter Radar
+
+One skill, focused on the two outputs you want:
+
+- **per_sample**: single-sample radar for each sample (all parameters).
+- **group_means** (recommended for group comparison): one polygon per group, using each group mean.
+- **both**: generate both per_sample + group_means in one run.
+
+(Still supports **all_samples** as a legacy overlay mode, if you ever need it.)
+
+## Assumed HDF5 layout
+
+Preferred:
+- `/KinematicParameter/ParameterName`
+- `/KinematicParameter/ParameterData` (frames × params)
+
+## Grouping
+
+Default group inference regex (1 capture group):
+- `rec-\d+-([^-_]+)[-_]`
+
+Override with `--group_regex` if your filenames differ.
+
+## Run (Windows / Anaconda example)
+
+### Generate both outputs (recommended)
+
+```bat
+D:\Anaconda3\python.exe plot_h5_radar.py --project_dir "C:\Users\ASUS\Desktop\2Dxy_test_project\random_project" --mode both --stat mean --normalize minmax --style nature
+```
+
+### Group means only (one polygon per group)
+
+```bat
+D:\Anaconda3\python.exe plot_h5_radar.py --project_dir "C:\Users\ASUS\Desktop\2Dxy_test_project\random_project" --mode group_means --stat mean --normalize minmax --style nature
+```
+
+### Per-sample only (one radar per sample)
+
+```bat
+D:\Anaconda3\python.exe plot_h5_radar.py --project_dir "C:\Users\ASUS\Desktop\2Dxy_test_project\random_project" --mode per_sample --stat mean --normalize minmax --style nature
+```
+
+### Legacy: all samples overlay
+
+```bat
+D:\Anaconda3\python.exe plot_h5_radar.py --project_dir "C:\Users\ASUS\Desktop\2Dxy_test_project\random_project" --mode all_samples --stat mean --normalize minmax --max_samples_combined 50 --style nature
+```
+
+## Key flags
+
+- `--mode`: `both|per_sample|group_means|all_samples`
+- `--stat`: `mean|median|max`
+- `--normalize`: `none|minmax|zscore`
+- `--n_params`: limit to N parameters for readability
+- `--max_samples_combined`: limit sample count in all-samples combined overlay
+
+## Outputs
+
+Default output root (relative to `project_dir`):
+- `results/h5_radar/<mode>/` (for `both`, it writes into `results/h5_radar/per_sample/` and `results/h5_radar/group_means/`)
+
+Includes CSV matrices and PNG/PDF radars. If some files lack required datasets, see `skipped_files.txt`.

package/skills/16_Animal_Behavior/ethoclaw-multiparameter-radar-generate/references/notes.md

@@ -0,0 +1,5 @@
+# Notes
+
+- group_means mode computes group mean AFTER per-sample summarization and normalization.
+- all_samples mode overlays individual sample profiles; legend is by group to avoid huge legends.
+- Style: clean white background, subtle grid, Nature/Cell-like palette; PDFs use editable text.