Figure Graphing Skill

Create publication-quality figures for scientific papers and reports.

Automatic PowerPoint Sync

IMPORTANT: When generating figures using generate_paper_figures.py, the PowerPoint is automatically updated:

bash
1# Generate figure and auto-update PowerPoint
2python generate_paper_figures.py --figure 3
3
4# Skip PowerPoint update (figures only)
5python generate_paper_figures.py --figure 3 --no-pptx

The script automatically:

1. Generates figure PNGs to Output/PowerPoint_Figures/Fig_X/
2. Unpacks Output/PowerPoint_Figures/Cardiac_RODEO_Tracked.pptx
3. Copies updated images to the correct media slots
4. Repacks the PowerPoint

Figure-to-Image Mapping:

Quick Reference

Standard Figure Types

1. Bar Charts - Accuracy, AUC, metric comparisons (always with error bars)
2. Grouped Bar Charts - Multiple metrics per model (always with error bars)
3. ROC Curves - MUST have shaded confidence bands (bootstrap ±1 std, use fill_between)
4. Confusion Matrices - With counts and percentages (Blues cmap)
5. Scatter Plots - Per-drug/per-sample predictions
6. Heatmaps - Correlation (RdBu_r), performance (RdYlGn), SHAP (coolwarm)
7. Threshold Analysis - Horizontal scatter, drugs on Y-axis, green/red colors
8. 3D Surface Plots - PK-PD response surfaces
9. SHAP Aligned Pairs - Positive/negative SHAP paired by magnitude, blue/grey colors
10. Accuracy vs AUC Scatter - X=Accuracy, Y=AUC, comparing equations across ML models

Color Palettes

Primary Color Palette (MANDATORY)

Use these colors consistently across ALL figures:

python
1PRIMARY_COLORS = {
2    'beige': '#E3D5B2',      # Warm neutral - backgrounds, secondary elements
3    'blue': '#6C92ED',       # Primary accent - main data series
4    'pink': '#ECA0C0',       # Secondary accent - comparison data
5    'orange': '#F8B274',     # Tertiary accent - highlights
6}
7
8# Extended palette (same theme)
9EXTENDED_COLORS = {
10    'dark_blue': '#4A6FBF',  # Darker blue for emphasis
11    'light_pink': '#F5C6D6', # Lighter pink for fills
12    'coral': '#E89B7A',      # Warm coral
13    'sage': '#A8C4A2',       # Muted green
14    'lavender': '#B8A9D9',   # Soft purple
15    'cream': '#F5EFE0',      # Light background
16}

Model Comparison Colors

python
1colors = {
2    'CNN (DIQT Transfer)': '#ECA0C0',   # Pink
3    'CNN (5-fold on 25)': '#6C92ED',    # Blue
4    'Organoid (5-fold)': '#F8B274',     # Orange
5    'ADMET-AI': '#6C92ED',              # Blue
6    'SwissADME': '#ECA0C0',             # Pink
7}

Metric Colors

python
1metric_colors = {
2    'Accuracy': '#6C92ED',    # Blue
3    'F1 Score': '#F8B274',    # Orange
4    'MCC': '#ECA0C0',         # Pink
5    'AUC': '#4A6FBF',         # Dark Blue
6    'Sensitivity': '#E89B7A', # Coral
7    'Specificity': '#A8C4A2', # Sage
8}

Classification Colors

python
1class_colors = {
2    'Positive': '#ECA0C0',    # Pink
3    'Negative': '#6C92ED',    # Blue
4    'True Positive': '#6C92ED',
5    'False Positive': '#F8B274',
6    'True Negative': '#A8C4A2',
7    'False Negative': '#E89B7A',
8}

Output Requirements

CRITICAL: Size Changes Mean GRAPH Size, Not Image Canvas

When the user asks to change figure dimensions (e.g., "make it smaller", "1.7 inches"), they mean the ACTUAL GRAPH/PLOT size, not the overall image canvas.

DO NOT:

• Shrink the graph while keeping the image canvas the same size (creates wasted whitespace)
• Add padding/margins to achieve a target image size
• Scale down the plot area within a larger figure

DO:

• Change figsize=(width, height) to directly control the plot dimensions
• The graph should fill the figure with minimal margins
• Use bbox_inches='tight' when saving to remove excess whitespace

python
1# CORRECT: figsize controls the actual graph size
2fig, ax = plt.subplots(figsize=(1.7, 1.7))  # Graph is 1.7" x 1.7"
3plt.savefig('output.png', dpi=600, bbox_inches='tight')
4
5# WRONG: Large canvas with small graph inside
6fig, ax = plt.subplots(figsize=(4, 4))  # 4" canvas
7ax.set_position([0.3, 0.3, 0.4, 0.4])  # Graph only 1.6" - DON'T DO THIS

The figsize parameter IS the graph size (plus minimal axis labels/title). When asked for "1.7 inch square", use figsize=(1.7, 1.7).

Always Save Both Formats

python
1# Save PDF for LaTeX/publication
2plt.savefig('Output/path/figures/figure_name.pdf', bbox_inches='tight')
3# Save PNG at 600 DPI for high-quality viewing
4plt.savefig('Output/path/Figure_Name.png', dpi=600, bbox_inches='tight')
5plt.close()

Standard Figure Sizes

python
1# Single panel
2fig, ax = plt.subplots(figsize=(8, 6))
3
4# Side-by-side panels
5fig, axes = plt.subplots(1, 2, figsize=(12, 5))
6
7# Three panels horizontal
8fig, axes = plt.subplots(1, 3, figsize=(14, 4))
9
10# Grid layout
11fig, axes = plt.subplots(2, 2, figsize=(12, 10))
12
13# Wide scatter plot (per-drug)
14fig, ax = plt.subplots(figsize=(16, 6))
15
16# Default square graph (for bar charts, scatter plots, Accuracy vs AUC, etc.)
17SQUARE_SIZE = 1.7  # inches - standard square panel
18fig, ax = plt.subplots(figsize=(SQUARE_SIZE, SQUARE_SIZE))
19
20# Heatmap (MANDATORY size - 1:2 ratio)
21HEATMAP_HEIGHT = 1.7   # inches
22HEATMAP_WIDTH = 3.4    # inches (2x height)
23fig, ax = plt.subplots(figsize=(HEATMAP_WIDTH, HEATMAP_HEIGHT))
24
25# Accuracy vs AUC scatter (use square size, same as bar charts)
26fig, ax = plt.subplots(figsize=(1.7, 1.7))  # 1:1 square
27# Or for 3-panel comparison with shared axis:
28fig, axes = plt.subplots(1, 3, figsize=(5.1, 1.7), sharey=True)  # 3 × 1.7" width
29
30# Bar chart (use square size)
31fig, ax = plt.subplots(figsize=(1.7, 1.7))  # Standard square

Common Figure Templates

1. Grouped Bar Chart (Accuracy, F1, MCC) with Error Bars

python
1import numpy as np
2import matplotlib.pyplot as plt
3
4models = ['Model A', 'Model B', 'Model C']
5metrics = ['Accuracy', 'F1 Score', 'MCC']
6# Mean values
7data = np.array([
8    [0.56, 0.72, 0.00],  # Model A
9    [0.68, 0.73, 0.34],  # Model B
10    [0.74, 0.77, 0.46],  # Model C
11])
12# Standard deviations (ALWAYS include error bars)
13data_std = np.array([
14    [0.05, 0.04, 0.00],  # Model A
15    [0.03, 0.05, 0.08],  # Model B
16    [0.04, 0.03, 0.06],  # Model C
17])
18
19x = np.arange(len(models))
20width = 0.25
21colors = ['#6C92ED', '#F8B274', '#ECA0C0']  # Use project color palette
22
23# Use 1.7" square for single bar charts (or scale up for grouped)
24SQUARE_SIZE = 1.7
25fig, ax = plt.subplots(figsize=(SQUARE_SIZE * 2, SQUARE_SIZE))  # 2:1 ratio for grouped
26for i, (metric, color) in enumerate(zip(metrics, colors)):
27    bars = ax.bar(x + i*width - width, data[:, i], width,
28                  yerr=data_std[:, i], capsize=4,  # Error bars with caps
29                  label=metric, color=color, edgecolor='black')
30    # Add value labels above error bars
31    for j, bar in enumerate(bars):
32        height = bar.get_height()
33        err = data_std[j, i]
34        ax.annotate(f'{height:.2f}',
35                    xy=(bar.get_x() + bar.get_width()/2, height + err),
36                    xytext=(0, 3), textcoords='offset points',
37                    ha='center', va='bottom', fontsize=9, fontweight='bold')
38
39ax.set_ylabel('Score', fontsize=9)
40ax.set_title('Performance Comparison', fontsize=10, fontweight='bold')
41ax.set_xticks(x)
42ax.set_xticklabels(models, fontsize=8)
43ax.tick_params(axis='both', labelsize=8)
44ax.legend(loc='upper left', fontsize=8)
45ax.set_ylim(0, 1.1)  # Extra space for error bars
46ax.grid(axis='y', alpha=0.3)
47plt.tight_layout()

2. ROC Curve with Bootstrap Confidence Bands (MANDATORY)

CRITICAL: ALL ROC curves MUST include shaded confidence bands. ROC curves without shaded uncertainty regions are NOT acceptable for publication figures.

What the shaded band represents:

• The band shows ±1 standard deviation of TPR at each FPR point
• Computed via bootstrap resampling (default: 300 iterations)
• Wider bands = more uncertainty, narrower bands = more confidence
• Band is clamped to [0, 1] range (valid probability bounds)

python
1import figure_config  # FIRST LINE - registers Helvetica
2from sklearn.metrics import roc_curve, auc
3import numpy as np
4import matplotlib.pyplot as plt
5
6def bootstrap_roc_stats(y_true, y_prob, n_boot=300, seed=42):
7    """
8    Bootstrap ROC statistics for confidence intervals.
9
10    Returns:
11        mean_fpr: Common FPR points (0 to 1, 100 points)
12        mean_tpr: Mean TPR at each FPR point
13        std_tpr: Standard deviation of TPR (for shaded band)
14        auc_mean: Mean AUC across bootstrap samples
15        auc_std: Standard deviation of AUC
16    """
17    rng = np.random.default_rng(seed)
18    y_true, y_prob = np.asarray(y_true), np.asarray(y_prob)
19    n = len(y_true)
20    mean_fpr = np.linspace(0, 1, 100)
21    tprs, aucs = [], []
22
23    for _ in range(n_boot):
24        idx = rng.integers(0, n, n)
25        if len(np.unique(y_true[idx])) < 2:
26            continue
27        fpr, tpr, _ = roc_curve(y_true[idx], y_prob[idx])
28        tpr_interp = np.interp(mean_fpr, fpr, tpr)
29        tpr_interp[0] = 0.0
30        tprs.append(tpr_interp)
31        aucs.append(auc(mean_fpr, tpr_interp))
32
33    tprs = np.array(tprs)
34    return mean_fpr, tprs.mean(axis=0), tprs.std(axis=0), np.mean(aucs), np.std(aucs)
35
36def plot_roc_with_bands(ax, mean_fpr, mean_tpr, std_tpr, auc_val, auc_std, color, label):
37    """
38    Plot ROC curve with MANDATORY shaded confidence band.
39
40    The shaded region represents ±1 std of TPR at each FPR point,
41    showing the uncertainty from bootstrap resampling.
42    """
43    # Plot the mean ROC curve
44    ax.plot(mean_fpr, mean_tpr, color=color, lw=2,
45            label=f'{label} (AUC={auc_val:.2f}±{auc_std:.2f})')
46
47    # MANDATORY: Shaded confidence band between upper and lower bounds
48    lower_bound = np.maximum(mean_tpr - std_tpr, 0)  # Clamp to 0 minimum
49    upper_bound = np.minimum(mean_tpr + std_tpr, 1)  # Clamp to 1 maximum
50
51    ax.fill_between(
52        mean_fpr,           # X values (FPR points)
53        lower_bound,        # Lower edge of shaded region
54        upper_bound,        # Upper edge of shaded region
55        color=color,
56        alpha=0.2,          # Semi-transparent shading
57        edgecolor='none'    # No edge line on the shaded region
58    )
59
60# COMPLETE USAGE EXAMPLE
61fig, ax = plt.subplots(figsize=(7, 6))
62
63# Example: Plot ROC for multiple models
64models_data = [
65    ('Model A', y_true_a, y_prob_a, '#6C92ED'),  # Blue
66    ('Model B', y_true_b, y_prob_b, '#ECA0C0'),  # Pink
67    ('Model C', y_true_c, y_prob_c, '#F8B274'),  # Orange
68]
69
70for label, y_true, y_prob, color in models_data:
71    # Compute bootstrap statistics
72    mean_fpr, mean_tpr, std_tpr, auc_val, auc_std = bootstrap_roc_stats(y_true, y_prob)
73    # Plot with MANDATORY shaded band
74    plot_roc_with_bands(ax, mean_fpr, mean_tpr, std_tpr, auc_val, auc_std, color, label)
75
76# Random classifier baseline (diagonal)
77ax.plot([0, 1], [0, 1], 'k--', lw=1, label='Random (AUC=0.50)')
78
79ax.set_xlabel('False Positive Rate', fontsize=9)
80ax.set_ylabel('True Positive Rate', fontsize=9)
81ax.set_title('ROC Curves with Confidence Bands', fontsize=10, fontweight='bold')
82ax.tick_params(axis='both', labelsize=8)
83ax.legend(loc='lower right', fontsize=8)
84ax.set_xlim([0, 1])
85ax.set_ylim([0, 1])
86ax.grid(alpha=0.3)
87plt.tight_layout()
88
89# Save both formats
90plt.savefig('roc_curves.pdf', bbox_inches='tight')
91plt.savefig('roc_curves.png', dpi=600, bbox_inches='tight')
92plt.close()

Visual representation of shaded band:

TPR
 1 ┤                    ╭───────── Upper bound (mean + std)
   │                 ╭──┤░░░░░░░░░
   │              ╭──┤░░░░░░░░░░░│ ← Shaded region shows uncertainty
   │           ╭──┤░░░░░░░░░░░░░│
   │        ╭──┤░░░░░░░░░░░░░░░─╯
   │     ╭──┤░░░░░░░░░░░░░░░╯     ← Mean ROC curve (solid line)
   │  ╭──┤░░░░░░░░░░░░░╯
   │╭─┤░░░░░░░░░░░░╯               Lower bound (mean - std)
 0 ┼──────────────────────────────
   0                            1  FPR

3. Confusion Matrix with Percentages

CRITICAL Sizing Rules:

• Use square figure size (SQUARE_SIZE = 1.7")
• Use aspect='equal' in imshow() to force square cells
• Margins: left=0.18, right=0.98, top=0.85, bottom=0.18 to maximize plot area
• DO NOT use set_box_aspect(1) - it constrains plot size and wastes space

python
1import figure_config  # FIRST LINE - registers Helvetica
2import numpy as np
3import matplotlib.pyplot as plt
4
5SQUARE_SIZE = 1.7  # Standard square panel size
6
7def plot_confusion_matrix(cm, labels, title, output_path=None):
8    """
9    Plot confusion matrix with counts and row percentages.
10    Uses square cells that fill the figure properly.
11    """
12    cm = np.asarray(cm, dtype=float)
13    row_sums = cm.sum(axis=1, keepdims=True)
14    row_sums[row_sums == 0] = 1.0
15    row_pct = cm / row_sums
16
17    # Square figure with tight margins to maximize plot area
18    fig, ax = plt.subplots(figsize=(SQUARE_SIZE, SQUARE_SIZE))
19    fig.subplots_adjust(left=0.18, right=0.98, top=0.85, bottom=0.18)
20
21    # CRITICAL: Use aspect='equal' for square cells (NOT set_box_aspect)
22    im = ax.imshow(cm, cmap='Blues', aspect='equal')
23
24    ax.set_title(title, fontsize=10, fontweight='bold')
25    ax.set_xticks(np.arange(len(labels)))
26    ax.set_yticks(np.arange(len(labels)))
27    ax.set_xticklabels(labels, fontsize=8)
28    ax.set_yticklabels(labels, fontsize=8)
29    ax.set_xlabel('Predicted', fontsize=9)
30    ax.set_ylabel('Actual', fontsize=9)
31
32    max_val = cm.max() if cm.size else 0
33    for i in range(cm.shape[0]):
34        for j in range(cm.shape[1]):
35            count = int(cm[i, j])
36            pct = row_pct[i, j] * 100
37            color = 'white' if max_val > 0 and cm[i, j] > max_val / 2 else 'black'
38            ax.text(j, i, f"{count}\n{pct:.1f}%",
39                    ha='center', va='center', color=color, fontsize=9)
40
41    if output_path:
42        plt.savefig(output_path, dpi=600, bbox_inches='tight')
43        plt.close()
44    return fig, ax, im

4. Per-Drug Scatter Plot

python
1fig, ax = plt.subplots(figsize=(16, 6))
2x_pos = np.arange(len(drugs))
3
4# Plot each model with offset
5for i, (model, probs, color, marker) in enumerate(model_data):
6    offset = (i - 1) * 0.15
7    mask = true_labels.astype(bool)
8    colors_arr = np.where(mask, color, 'lightgray')
9    ax.scatter(x_pos + offset, probs, s=100, c=colors_arr,
10               marker=marker, edgecolor='black', linewidth=1.5,
11               zorder=3, label=model)
12
13ax.axhline(0.5, color='red', linestyle='--', linewidth=2, alpha=0.7)
14ax.set_ylabel('Probability', fontsize=9)
15ax.set_xlabel('Drug', fontsize=9)
16ax.set_xticks(x_pos)
17ax.set_xticklabels(drugs, rotation=45, ha='right', fontsize=8)
18ax.tick_params(axis='both', labelsize=8)
19ax.set_ylim(-0.05, 1.15)
20ax.grid(axis='y', alpha=0.3)
21ax.legend(loc='upper right')

5. Heatmap (Red-White-Blue Diverging)

CRITICAL Heatmap Rules:

1. Square cells - Always use square=True, never rectangles
2. No borders/gaps - Always use linewidths=0 (no white space between cells)
3. Axis orientation - X-axis = Time (hours), Y-axis = Concentration (mM)
4. Data matrix - Rows = concentrations, Columns = time points
5. Clean labels - Remove duplicate decimal suffixes (8.1 → 8), keep meaningful ones (0.1 stays 0.1)

python
1import figure_config  # FIRST LINE - registers Helvetica
2import numpy as np
3import matplotlib.pyplot as plt
4import seaborn as sns
5import pandas as pd
6import re
7
8def clean_concentration_labels(labels):
9    """
10    Clean concentration labels by removing duplicate decimal suffixes.
11
12    Examples:
13        '8.1' → '8'      (removes .1 suffix that's just numbering)
14        '8.2' → '8'      (removes .2 suffix)
15        '0.1' → '0.1'    (keeps meaningful decimal - it's the actual value)
16        '0.1.1' → '0.1'  (removes duplicate suffix from 0.1)
17    """
18    cleaned = []
19    for label in labels:
20        label_str = str(label)
21        # Pattern: number.number.number (like 0.1.1) → keep first two parts
22        if re.match(r'^\d+\.\d+\.\d+$', label_str):
23            parts = label_str.split('.')
24            cleaned.append(f"{parts[0]}.{parts[1]}")
25        # Pattern: integer.single_digit at end (like 8.1, 8.2) → remove suffix
26        elif re.match(r'^(\d+)\.[1-9]$', label_str):
27            cleaned.append(re.match(r'^(\d+)\.[1-9]$', label_str).group(1))
28        else:
29            cleaned.append(label_str)
30    return cleaned
31
32# Example: Drug response heatmap
33# CRITICAL: Rows = concentrations (Y-axis), Columns = time (X-axis)
34n_concentrations = 8
35n_timepoints = 40
36
37data_matrix = pd.DataFrame(
38    np.random.randn(n_concentrations, n_timepoints),
39    index=[f'{c}' for c in [0, 0.1, 1, 2, 4, 8, 16, 32]],  # Concentration labels
40    columns=[f'{t}' for t in range(0, n_timepoints * 2, 2)]  # Time labels (hours)
41)
42
43# Clean concentration labels (Y-axis)
44y_labels = clean_concentration_labels(data_matrix.index.tolist())
45x_labels = data_matrix.columns.tolist()  # Time labels (X-axis)
46
47# Setup custom colormap with project colors
48from matplotlib.colors import LinearSegmentedColormap
49
50# Project heatmap colors (MANDATORY)
51HEATMAP_BLUE = '#123BFF'   # Low values
52HEATMAP_RED = '#FF2908'    # High values
53
54# Create custom diverging colormap: Blue -> White -> Red
55cmap = LinearSegmentedColormap.from_list(
56    'cardiac_rodeo',
57    [HEATMAP_BLUE, 'white', HEATMAP_RED]
58)
59cmap.set_bad('white')  # NaN values display as white
60
61# MANDATORY Figure size for heatmaps (1:2 ratio)
62HEATMAP_HEIGHT = 1.7   # inches
63HEATMAP_WIDTH = 3.4    # inches (2x height)
64fig, ax = plt.subplots(figsize=(HEATMAP_WIDTH, HEATMAP_HEIGHT))
65
66# Create heatmap with SQUARE cells and NO borders/gaps
67sns.heatmap(
68    data_matrix,
69    annot=False,              # No cell annotations
70    cmap=cmap,
71    cbar_kws={'label': 'Response', 'shrink': 0.8},
72    xticklabels=x_labels,     # Time labels (X-axis)
73    yticklabels=y_labels,     # Concentration labels (Y-axis)
74    square=True,              # CRITICAL: Square cells, not rectangles
75    mask=False,
76    linewidths=0               # CRITICAL: No borders/gaps between cells
77)
78
79# Customize tick labels - FIXED SIZES
80ax.set_xticklabels(x_labels, rotation=0, ha='center', fontsize=8)
81ax.set_yticklabels(y_labels, fontsize=8, rotation=0)
82
83# CRITICAL: X = Time, Y = Concentration - FIXED FONT SIZES
84ax.set_xlabel('Time (Hours)', fontsize=9)
85ax.set_ylabel('Concentration (mM)', fontsize=9)
86ax.set_title('Drug Response Heatmap', fontsize=10, fontweight='bold')
87
88plt.tight_layout()

Heatmap Axis Orientation (MANDATORY):

         X-axis: Time (Hours) →
        ┌─────────────────────────┐
    Y   │  0   2   4   6  ...  78 │
    a   ├─────────────────────────┤
    x   │ 32 │ ■ │ ■ │ ■ │     │ ■ │
    i   │ 16 │ ■ │ ■ │ ■ │     │ ■ │
    s   │  8 │ ■ │ ■ │ ■ │     │ ■ │
    :   │  4 │ ■ │ ■ │ ■ │     │ ■ │
    C   │  2 │ ■ │ ■ │ ■ │     │ ■ │
    o   │  1 │ ■ │ ■ │ ■ │     │ ■ │
    n   │0.1 │ ■ │ ■ │ ■ │     │ ■ │
    c   │  0 │ ■ │ ■ │ ■ │     │ ■ │
        └─────────────────────────┘

Heatmap Colormap Reference:

MANDATORY Heatmap Colors:

python
1HEATMAP_BLUE = '#123BFF'  # For low values
2HEATMAP_RED = '#FF2908'   # For high values

6. Threshold Analysis Scatter Plot (Horizontal)

python
1import numpy as np
2import matplotlib.pyplot as plt
3import pandas as pd
4
5# Example data
6drugs = ['Amiodarone', 'Bortezomib', 'Chlorpromazine', 'Doxorubicin', 'Erlotinib',
7         'Ibuprofen', 'Nifedipine', 'Sotalol', 'Vincristine', 'Vioxx']
8predictions = np.array([85, 72, 45, 90, 30, 25, 55, 78, 40, 65])  # Probability %
9actual_positive = np.array([True, True, False, True, False, False, True, True, False, True])
10
11# Sort drugs: by classification (positive first), then alphabetically
12df = pd.DataFrame({'Drug': drugs, 'Pred': predictions, 'Positive': actual_positive})
13df = df.sort_values(['Positive', 'Drug'], ascending=[False, True])
14drugs_sorted = df['Drug'].tolist()
15preds_sorted = df['Pred'].values
16status_sorted = df['Positive'].values
17
18# Colors: Green = positive, Red = negative
19pos_color = '#2ca02c'   # Green
20neg_color = '#d62728'   # Red
21threshold_color = '#1f77b4'  # Blue for threshold line
22
23# Create horizontal scatter plot (drugs on Y-axis)
24fig, ax = plt.subplots(figsize=(10, max(6, len(drugs) * 0.4)))
25
26positions = np.arange(len(drugs_sorted))
27point_colors = [pos_color if s else neg_color for s in status_sorted]
28
29# Scatter: X = probability, Y = drug position
30ax.scatter(preds_sorted, positions, c=point_colors, s=100,
31           edgecolors='black', linewidth=0.5, zorder=3)
32
33# Compute threshold: max(negative samples) + margin, rounded to nearest 5
34margin_pp = 2.0
35neg_preds = preds_sorted[~status_sorted]
36if len(neg_preds) > 0:
37    threshold = float(np.max(neg_preds)) + margin_pp
38else:
39    threshold = 50.0
40threshold = float(5 * np.ceil(threshold / 5.0))  # Round up to nearest 5
41
42# Vertical threshold line
43ax.axvline(threshold, color=threshold_color, linestyle='--', linewidth=2, zorder=2)
44ax.text(threshold + 1, len(drugs_sorted) - 0.5, f'{threshold:.0f}%',
45        color=threshold_color, fontsize=10, fontweight='bold', va='top')
46
47# Axis setup with padding for 0% and 100% visibility
48ax.set_xlim(-5, 105)  # Padding so edge points are visible
49ax.set_ylim(-0.5, len(drugs_sorted) - 0.5)
50
51ax.set_yticks(positions)
52ax.set_yticklabels(drugs_sorted, fontsize=8)
53ax.set_xlabel('Predicted Probability (%)', fontsize=9)
54ax.set_title('Threshold Analysis: Arrhythmia Prediction', fontsize=10, fontweight='bold')
55ax.tick_params(axis='both', labelsize=8)
56
57ax.grid(axis='x', linestyle='--', alpha=0.4)
58ax.invert_yaxis()  # First drug at top
59
60# Legend
61from matplotlib.lines import Line2D
62legend_elements = [
63    Line2D([0], [0], marker='o', color='w', markerfacecolor=pos_color,
64           markersize=10, label='Positive (Actual)'),
65    Line2D([0], [0], marker='o', color='w', markerfacecolor=neg_color,
66           markersize=10, label='Negative (Actual)'),
67    Line2D([0], [0], color=threshold_color, linestyle='--', linewidth=2, label='Threshold')
68]
69ax.legend(handles=legend_elements, loc='lower right', fontsize=8)
70
71plt.tight_layout()

Key Features:

• Drugs on Y-axis for readable labels
• X-axis: 0-100% with -5, 105 limits for edge visibility
• Green = positive class, Red = negative class
• Sorted by classification (positive first) then alphabetically
• Threshold = max(negative) + margin, rounded to nearest 5%
• Vertical threshold line with axvline

7. 3D Surface Plot (PK-PD)

python
1from mpl_toolkits.mplot3d import Axes3D
2import numpy as np
3
4fig = plt.figure(figsize=(10, 8))
5ax = fig.add_subplot(111, projection='3d')
6
7# Create meshgrid
8time = np.linspace(0, 96, 50)
9dose_ratio = np.linspace(0, 2, 50)
10T, Dr = np.meshgrid(time, dose_ratio)
11Response = compute_response(T, Dr, params)  # Your function
12
13surf = ax.plot_surface(T, Dr, Response, cmap='viridis',
14                       edgecolor='none', alpha=0.9)
15ax.set_xlabel('Time (hours)', fontsize=9)
16ax.set_ylabel('Dose Ratio (C0/Cmax)', fontsize=9)
17ax.set_zlabel('Response', fontsize=9)
18ax.set_title('Drug Response Surface', fontsize=10, fontweight='bold')
19ax.tick_params(axis='both', labelsize=8)
20ax.view_init(elev=25, azim=-158)
21fig.colorbar(surf, shrink=0.5, aspect=10)

8. SHAP Aligned Pairs Plot

python
1import figure_config  # FIRST LINE - registers Helvetica
2import numpy as np
3import matplotlib.pyplot as plt
4import pandas as pd
5from matplotlib.lines import Line2D
6
7# Load SHAP values (example: arrhythmia)
8shap_df = pd.read_csv('Output/SHAP_Data/shap_arrhythmia_values.csv')
9drug_class = pd.read_csv('Cleaned_Data/drug_classification.csv')
10
11# Create label map: drug -> actual class (True/False)
12label_map = {}
13for _, row in drug_class.iterrows():
14    drug = row['Drug']
15    val = row['Arrhythmia']  # or 'heart_damage', 'Concern', etc.
16    label_map[drug] = str(val).lower() == 'true' if isinstance(val, str) else bool(val)
17
18# Colors: Blue for positive class, Grey for negative class
19COLORS = {
20    'pass': '#6C92ED',   # Blue - positive class
21    'fail': '#888888',   # Grey - negative class
22}
23
24# Get feature columns and select top 5 by |mean SHAP|
25feature_cols = [col for col in shap_df.columns if col != 'Drug']
26mean_shap = shap_df[feature_cols].abs().mean()
27top_5_features = mean_shap.nlargest(5).index.tolist()
28
29# Figure size: 2x width for SHAP plots
30SQUARE_SIZE = 1.7
31fig, ax = plt.subplots(figsize=(SQUARE_SIZE * 2, SQUARE_SIZE))
32fig.subplots_adjust(left=0.25, right=0.85, top=0.88, bottom=0.12)
33
34n_features = len(top_5_features)
35n_drugs = len(shap_df)
36feature_spacing = 1.0
37drug_offset = 0.03
38
39y_positions = []
40y_labels = []
41
42for feat_idx, feature in enumerate(reversed(top_5_features)):
43    base_y = feat_idx * feature_spacing
44    y_positions.append(base_y)
45    y_labels.append(feature)
46
47    # Sort drugs by SHAP value for this feature
48    sorted_idx = np.argsort(shap_df[feature].values)
49
50    for i, idx in enumerate(sorted_idx):
51        drug = shap_df['Drug'].iloc[idx]
52        val = shap_df[feature].iloc[idx]
53        y = base_y + (i - n_drugs/2) * drug_offset
54
55        # Color by actual class
56        is_positive = label_map.get(drug, False)
57        color = COLORS['pass'] if is_positive else COLORS['fail']
58
59        # Draw line from 0 to SHAP value
60        ax.hlines(y, 0, val, colors=color, linewidth=1.2, alpha=0.8)
61
62ax.axvline(x=0, color='black', linewidth=0.8)
63ax.set_yticks(y_positions)
64ax.set_yticklabels(y_labels, fontsize=8)
65ax.set_xlabel('SHAP Value', fontsize=9)
66ax.set_title('SHAP Feature Importance', fontsize=10, fontweight='bold')
67ax.spines['top'].set_visible(False)
68ax.spines['right'].set_visible(False)
69ax.grid(axis='x', alpha=0.3)
70ax.tick_params(axis='x', labelsize=8)
71
72legend_elements = [
73    Line2D([0], [0], color=COLORS['pass'], linewidth=2, label='Pos'),
74    Line2D([0], [0], color=COLORS['fail'], linewidth=2, label='Neg'),
75]
76ax.legend(handles=legend_elements, fontsize=8, loc='upper right')
77
78plt.savefig('Output/SHAP_Data/shap_aligned_target.png', dpi=600)
79plt.close()

Key Features:

• Shows top 5 features by |mean SHAP|
• For each feature, all drugs are plotted as horizontal lines from 0 to their SHAP value
• Lines sorted by SHAP value within each feature group
• Color indicates actual class (not SHAP sign): blue=positive, grey=negative
• Simple, clean visualization without complex pairing logic
• Compact size (3.4" × 1.7") for PowerPoint integration

Data Export Pattern (for Excel recreation):

python
1excel_data = []
2for feature, y_pos, shap_val, drug, actual in plot_records:
3    excel_data.append({
4        'Feature': feature,
5        'Y_Position': y_pos,
6        'SHAP_Value': shap_val,
7        'Drug': drug,
8        'Actual_Class': 'Positive' if actual else 'Negative'
9    })
10pd.DataFrame(excel_data).to_excel('shap_aligned_pairs_data.xlsx', index=False)

9. Accuracy vs AUC Scatter Plot (Equation/Model Comparison)

NOT a bar chart! This is a scatter plot comparing equations across ML models.

• X-axis = Accuracy
• Y-axis = AUC
• Each point = one (equation, model) combination
• Color/marker by equation, grouped by model

python
1import figure_config  # FIRST LINE - registers Helvetica
2import numpy as np
3import matplotlib.pyplot as plt
4import pandas as pd
5
6# Example data: 3 equations × 3 ML models = 9 points
7equations = ['dual_exponential', 'modified_hill_hormesis', 'pkpd_elimination']
8models = ['XGBoost', 'SVM_RBF', 'RandomForest']
9
10# Simulated results (replace with actual loocv_results.csv data)
11data = {
12    ('dual_exponential', 'XGBoost'): {'Accuracy': 0.72, 'AUC': 0.78},
13    ('dual_exponential', 'SVM_RBF'): {'Accuracy': 0.68, 'AUC': 0.72},
14    ('dual_exponential', 'RandomForest'): {'Accuracy': 0.70, 'AUC': 0.75},
15    ('modified_hill_hormesis', 'XGBoost'): {'Accuracy': 0.76, 'AUC': 0.82},
16    ('modified_hill_hormesis', 'SVM_RBF'): {'Accuracy': 0.74, 'AUC': 0.80},
17    ('modified_hill_hormesis', 'RandomForest'): {'Accuracy': 0.73, 'AUC': 0.78},
18    ('pkpd_elimination', 'XGBoost'): {'Accuracy': 0.80, 'AUC': 0.86},
19    ('pkpd_elimination', 'SVM_RBF'): {'Accuracy': 0.78, 'AUC': 0.84},
20    ('pkpd_elimination', 'RandomForest'): {'Accuracy': 0.77, 'AUC': 0.82},
21}
22
23# Colors by equation
24equation_colors = {
25    'dual_exponential': '#e74c3c',      # Red
26    'modified_hill_hormesis': '#3498db', # Blue
27    'pkpd_elimination': '#2ecc71',       # Green
28}
29
30# Markers by model
31model_markers = {
32    'XGBoost': 'o',       # Circle
33    'SVM_RBF': 's',       # Square
34    'RandomForest': '^',  # Triangle
35}
36
37# Use 1.7" square (same as bar charts)
38SQUARE_SIZE = 1.7
39fig, ax = plt.subplots(figsize=(SQUARE_SIZE, SQUARE_SIZE))
40
41# Plot each point
42for (eq, model), metrics in data.items():
43    ax.scatter(
44        metrics['Accuracy'], metrics['AUC'],
45        c=equation_colors[eq],
46        marker=model_markers[model],
47        s=40,  # Appropriate markers for 1.7" square
48        edgecolors='black',
49        linewidth=1,
50        label=f'{eq} / {model}' if model == models[0] else '',  # Only label once per equation
51        zorder=3
52    )
53
54# Reference lines
55ax.axhline(0.5, color='gray', linestyle='--', alpha=0.5, linewidth=1)  # AUC baseline
56ax.axvline(0.5, color='gray', linestyle='--', alpha=0.5, linewidth=1)  # Accuracy baseline
57
58# Axis settings - FIXED FONT SIZES
59ax.set_xlabel('Accuracy', fontsize=9)
60ax.set_ylabel('AUC', fontsize=9)
61ax.set_title('Equation Comparison: Accuracy vs AUC', fontsize=10, fontweight='bold')
62ax.tick_params(axis='both', labelsize=8)
63ax.set_xlim(0.4, 1.0)
64ax.set_ylim(0.4, 1.0)
65ax.set_aspect('equal')  # Square plot for equal scaling
66ax.grid(True, alpha=0.3)
67
68# Custom legend
69from matplotlib.lines import Line2D
70from matplotlib.patches import Patch
71
72# Equation colors legend
73eq_legend = [Patch(facecolor=c, edgecolor='black', label=eq.replace('_', ' ').title())
74             for eq, c in equation_colors.items()]
75
76# Model markers legend
77model_legend = [Line2D([0], [0], marker=m, color='w', markerfacecolor='gray',
78                       markersize=10, label=model, markeredgecolor='black')
79                for model, m in model_markers.items()]
80
81legend1 = ax.legend(handles=eq_legend, title='Equation', loc='upper left', fontsize=8)
82ax.add_artist(legend1)
83ax.legend(handles=model_legend, title='Model', loc='lower right', fontsize=8)
84
85plt.tight_layout()

Key Features:

• X = Accuracy, Y = AUC (NOT bar chart)
• Each point represents one (equation, model) combination
• Color distinguishes equations
• Marker shape distinguishes ML models
• Square plot with equal scaling for fair comparison
• Reference lines at 0.5 for both axes (random baseline)

Space-Saving Rules for Multi-Panel Figures

CRITICAL: Shared Axes for Same-Scale Graphs

When multiple graphs share the same axis scale, place them side-by-side and show only ONE axis instead of repeating.

This eliminates wasted space from duplicate axis labels and tick marks.

python
1import figure_config
2import matplotlib.pyplot as plt
3import matplotlib.gridspec as gridspec
4
5# WRONG: Each subplot has its own Y-axis (wastes space)
6fig, axes = plt.subplots(1, 3, figsize=(9, 3))
7for ax in axes:
8    ax.set_ylabel('Response')  # Repeated 3 times!
9
10# CORRECT: Share Y-axis, only label the leftmost
11fig, axes = plt.subplots(1, 3, figsize=(7, 3), sharey=True)
12axes[0].set_ylabel('Response')  # Only once on the left
13for ax in axes[1:]:
14    ax.tick_params(labelleft=False)  # Hide Y tick labels on others
15
16# BEST: Use GridSpec for tight control and minimal gaps
17fig = plt.figure(figsize=(5.19, 1.44))  # 3 heatmaps side-by-side
18gs = gridspec.GridSpec(1, 3, wspace=0.05)  # Minimal horizontal gap
19
20axes = [fig.add_subplot(gs[0, i]) for i in range(3)]
21axes[0].set_ylabel('Concentration (mM)')  # Only on leftmost
22for ax in axes[1:]:
23    ax.set_yticklabels([])  # No Y labels on middle/right panels

Visual comparison:

WRONG (wasted space):                    CORRECT (shared axis):
┌─────────┐ ┌─────────┐ ┌─────────┐     ┌─────────────────────────┐
│  Y      │ │  Y      │ │  Y      │     │  Y                      │
│  │ ■■■  │ │  │ ■■■  │ │  │ ■■■  │     │  │ ■■■ │ ■■■ │ ■■■     │
│  │ ■■■  │ │  │ ■■■  │ │  │ ■■■  │     │  │ ■■■ │ ■■■ │ ■■■     │
│  └──X   │ │  └──X   │ │  └──X   │     │  └──────────────X       │
└─────────┘ └─────────┘ └─────────┘     └─────────────────────────┘
 Drug A      Drug B      Drug C           Drug A  Drug B  Drug C

CRITICAL: Shared Legends and Colorbars

When multiple graphs in the same panel use the same color scale or legend, show only ONE colorbar/legend for all of them.

python
1import matplotlib.pyplot as plt
2import matplotlib.gridspec as gridspec
3import numpy as np
4
5# Example: 3 heatmaps with one shared colorbar
6fig = plt.figure(figsize=(5.5, 1.44))
7
8# Create GridSpec: 3 heatmaps + 1 narrow colorbar column
9gs = gridspec.GridSpec(1, 4, width_ratios=[1, 1, 1, 0.05], wspace=0.1)
10
11# Determine shared vmin/vmax across all data
12all_data = [data1, data2, data3]
13vmin = min(d.min() for d in all_data)
14vmax = max(d.max() for d in all_data)
15
16# Plot heatmaps with same color scale
17for i, data in enumerate(all_data):
18    ax = fig.add_subplot(gs[0, i])
19    im = ax.imshow(data, vmin=vmin, vmax=vmax, cmap='RdBu_r')
20    if i == 0:
21        ax.set_ylabel('Concentration')
22    else:
23        ax.set_yticklabels([])  # No Y labels on non-leftmost
24
25# Single colorbar for all three
26cbar_ax = fig.add_subplot(gs[0, 3])
27fig.colorbar(im, cax=cbar_ax, label='Response')