Create publication-quality scientific figure panels with a consistent layout

MATLAB-panel-builder helps you compose publication-quality scientific figure panels with precise and repeatable layouts in MATLAB. The shared precise layout lets you align panels perfectly into complete figures by simply stacking them vertically or horizontally. MATLAB-panel-builder can thus be combined with TikZ for stacking panels into complete figures with a creation pipeline that is fully reproducible and under version control in Git.

Features

• 📏 Precise Layout Control: Define panel dimensions in centimeters for exact sizing
• 🎨 Consistent Styling: Maintain uniform fonts, margins, and aesthetics across panels
• 📊 Flexible Panel Composition: Easy vertical and horizontal stacking of panels
• 🔄 Reproducible Workflow: Version-controlled figure creation pipeline
• 🎯 Publication-Ready: Optimized for scientific publication requirements

Installation

1. Add the matlab-panel-builder directory to your MATLAB path:

   addpath('path/to/matlab-panel-builder');

2. Or place the +PanelBuilder package directory in your working directory.

Basic usage

Quick Start

% Configure panel dimensions, margins, and axes separation
config = struct();
config.panel = struct();
config.panel.dimensions = struct('widthCm', 10, 'heightCm', 8);
config.panel.margins = struct('leftCm', 1.5, 'bottomCm', 1.5, 'rightCm', 0.5, 'topCm', 0.5);
config.panel.axesSeparation = struct('xCm', 1.0, 'yCm', 1.0);

% Define style properties that can be set via groot
config.style = struct();
config.style.properties = struct();
config.style.properties.defaultAxesFontSize = 8;

PanelBuilder.configure(config);
PanelBuilder.setStyle();

% Create a simple panel
[fig, axs] = PanelBuilder.createPanel();
ax = axs{1,1};
plot(ax, 1:10, rand(1,10));

Multi-panel Layouts

% Create a 2x2 grid of panels
[fig, axs] = PanelBuilder.createPanel('rows', 2, 'cols', 2);

% Plot in different panels
plot(axs{1,1}, 1:10, rand(1,10));
scatter(axs{1,2}, 1:10, rand(1,10));
bar(axs{2,1}, 1:5, rand(1,5));
histogram(axs{2,2}, randn(100,1));

Configuration Override

For advanced configuration scenarios, the configure() function also supports special operators to modify the existing configuration:

% Initial configuration (width = 10 cm, font size = 8)
config = struct();
config.panel = struct('dimensions', struct('widthCm', 10));
PanelBuilder.configure(config);

% Increase width by 2 cm (now 12 cm)
configUpdate = struct();
configUpdate.panel = struct('dimensions', struct('widthCm', '+=2'));
PanelBuilder.configure(configUpdate);

Supported operators:

• "+=X": Add X to current value
• "-=X": Subtract X from current value
• "*X": Multiply current value by X
• "=X": Set value to X

Note: Override operators are not supported for style.properties fields. Properties only support direct assignment since default values cannot be defined for all possible groot properties.

Extra Features

Extra features include wrappers for systematically aligning legends, scale bars, colorbars, and annotations. In addition, the package includes a feature for placing a grid over the whole panel to verify that all elements have their intended position.

Adding Annotations

% Add corner annotations with optional background colors
PanelBuilder.Features.addAnnotation(ax, 'TEXT', 'loc', 'northwest');

Scale Bars

% Add X and Y scale bars
PanelBuilder.Features.drawXScaleBar(ax, 1, '1 cm');  % 1 cm scale bar
PanelBuilder.Features.drawYScaleBar(ax, 2, '2 cm');  % 2 cm scale bar

Legends

% Add legend with automatic styling and positioning
plot(ax, x, y1, 'DisplayName', 'Series 1');
plot(ax, x, y2, 'DisplayName', 'Series 2');
leg = PanelBuilder.Features.addLegend(ax, 'Location', 'northeast');

Colorbars

% Add colorbar in different positions
scatterHandle = scatter(ax, x, y, [], colors, 'filled');
cbar = PanelBuilder.Features.addColorbar(ax, scatterHandle, 'right');

Debug Gridlines

% Add gridlines to verify positioning (0.5 cm resolution by default)
PanelBuilder.Features.drawGridlines(fig);

Project Structure

+PanelBuilder/              % Main package namespace
├── configManager.m         % Central configuration management
├── configure.m             % Public configuration interface
├── createPanel.m           % Core panel creation with grid layouts
├── getConfig.m             % Configuration retrieval
├── resetConfig.m           % Reset configuration to defaults
├── setStyle.m              % Apply styling to graphics root
├── +Features/              % Specialized features
│   ├── addAnnotation.m     % Panel corner annotations
│   ├── addColorbar.m       % Colorbar positioning
│   ├── addLegend.m         % Legend styling and positioning
│   ├── drawGridlines.m     % Debug grid overlay
│   ├── drawXScaleBar.m     % Horizontal scale bars
│   └── drawYScaleBar.m     % Vertical scale bars
└── +Helpers/               % Utility functions
    ├── adjustAxesSize.m    % Axes dimension adjustments
    ├── applyLegendStyle.m  % Legend style application
    ├── centerAxes.m        % Axes centering utilities
    ├── cmToAxesRel.m       % CM to axes relative coordinates
    ├── cmToFigRel.m        % CM to figure relative coordinates
    ├── cmToPixels.m        % CM to pixel conversion
    ├── copyAxes.m          % Axes copying utilities
    ├── createFullFigureAxes.m % Full-figure axes creation
    ├── ptToCm.m            % Point to centimeter conversion
    ├── validateAxesUnits.m % Axes units validation
    └── validateFigureUnits.m % Figure units validation

examples/                   % Usage examples and templates
├── exampleConfig.m         % Complete configuration template
└── usageExample.m          % Comprehensive feature demonstration

tests/                      % Unit tests
├── testConfigureOverride.m % Configuration override tests
└── testHelperFunctions.m   % Helper function tests

docs/                       % Additional documentation
└── STYLEGUIDE.md           % Code style guidelines and conventions

assets/                     % Logo and visual assets
└── MATLAB-panel-builder logo.png  % Project logo

Examples

Complete Usage Example

See examples/usageExample.m for a comprehensive demonstration that shows:

• 2×2 panel creation with precise 11×11 cm dimensions
• Complete configuration setup (dimensions, margins, styling)
• All annotation positions (NW, NE, SW, SE) with background colors
• Y-axis and X-axis scale bars with custom labels
• Colorbars in all 4 positions (left, right, top, bottom)
• Debug gridlines for visual validation
• Publication-ready styling with consistent fonts

% Run the comprehensive usage example
run('examples/usageExample.m');

Saving Panels

To ensure that panels maintain their intended dimensions when saved, it is recommended to use the export_fig package. MATLAB's default figure saving functions may not preserve the precise centimeter-based dimensions that PanelBuilder is designed around.

% Save with export_fig to preserve dimensions
export_fig(fig, 'panel.pdf', '-pdf');
export_fig(fig, 'panel.png', '-png', '-r300');  % 300 DPI for high quality

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes following the style guidelines
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

License

This project is released under the MIT License.