Quick Start Guide#

This guide will help you get started with PubliPlots quickly.

Setting Up Your Environment#

First, import the necessary libraries:

import publiplots as pp
import pandas as pd
import numpy as np

Creating Your First Plot#

Bar Plot#

Create a simple bar plot from a DataFrame:

# Create sample data
data = pd.DataFrame({
    'category': ['A', 'B', 'C', 'D'],
    'value': [23, 45, 38, 52]
})

# Create bar plot
ax = pp.barplot(
    data=data,
    x='category',
    y='value',
    title='My First Plot',
    xlabel='Category',
    ylabel='Value',
    palette='pastel'
)

pp.show()

Scatter Plot#

Create a scatter plot with color and size encoding:

# Create sample data
data = pd.DataFrame({
    'x': np.random.randn(100),
    'y': np.random.randn(100),
    'size': np.random.uniform(1, 10, 100),
    'group': np.random.choice(['A', 'B', 'C'], 100)
})

# Create scatter plot
ax = pp.scatterplot(
    data=data,
    x='x',
    y='y',
    hue='group',
    size='size',
    sizes=(50, 500),
    palette='pastel',
    title='Scatter Plot Example'
)

pp.show()

Customizing Your Plots#

Using Error Bars#

Add error bars to show variability:

# Create data with multiple measurements
data = pd.DataFrame({
    'treatment': np.repeat(['Control', 'Drug A', 'Drug B'], 10),
    'response': np.concatenate([
        np.random.normal(100, 15, 10),
        np.random.normal(120, 12, 10),
        np.random.normal(135, 18, 10),
    ])
})

# Create bar plot with error bars
ax = pp.barplot(
    data=data,
    x='treatment',
    y='response',
    errorbar='se',  # Standard error
    capsize=0.1,
    title='Drug Response'
)

Using Hatch Patterns#

Add hatch patterns for black-and-white publications:

ax = pp.barplot(
    data=data,
    x='treatment',
    y='response',
    hatch='treatment',
    hatch_map={'Control': '', 'Drug A': '//', 'Drug B': 'xx'},
    alpha=0.0,
    color='#5D83C3'
)

Advanced Plots#

Venn Diagrams#

Create Venn diagrams for set intersections:

# Create sets
set_a = set(range(1, 50))
set_b = set(range(30, 80))
set_c = set(range(60, 100))

# Create 3-way Venn diagram
ax = pp.venn(
    sets=[set_a, set_b, set_c],
    labels=['Set A', 'Set B', 'Set C'],
    colors=pp.color_palette('pastel', n_colors=3)
)

UpSet Plots#

Create UpSet plots for many-set intersections:

# Create sets
sets = {
    'Group A': set(range(1, 60)),
    'Group B': set(range(40, 100)),
    'Group C': set(range(70, 130)),
    'Group D': set(range(30, 90))
}

# Create UpSet plot
axes = pp.upsetplot(
    data=sets,
    sort_by='size',
    title='Set Intersections',
    show_counts=15
)

Saving Your Figures#

Save figures in various formats:

# Save as PNG (high resolution)
pp.savefig('my_plot.png', dpi=300)

# Save as PDF (vector format)
pp.savefig('my_plot.pdf')

# Save as SVG (editable vector format)
pp.savefig('my_plot.svg')

# Save multiple figures at once
pp.save_multiple([fig1, fig2, fig3], 'output_dir')

Configuration#

Global Settings#

Configure global plotting parameters using pp.rcParams:

# Set default colors and transparency
pp.rcParams['color'] = '#E67E7E'
pp.rcParams['alpha'] = 0.3

# Set a global edge color for patches and marker outlines.
# Default is None (each plot picks its own — typically the face color).
# Per-call ``edgecolor=`` arguments override the rcParam.
pp.rcParams['edgecolor'] = 'black'

# Set the global width (points) for the strokes publiplots draws to
# *outline* a shape: patch borders, box whiskers, violin and
# filled-density outlines, marker edges. Pairs with ``edgecolor``.
# Strokes that *are* the data (lineplot series, kde curves, contour
# isolines, regression fits) read matplotlib's ``lines.linewidth``
# instead.
#
# One exception: the confidence-band edges of lineplot, regplot and
# residplot are drawn by seaborn as fill-between collections, so they
# follow matplotlib's ``patch.linewidth`` (which publiplots pins to the
# same 0.75). Raise ``patch.linewidth`` too if you need them to follow.
pp.rcParams['edgewidth'] = 0.75

# Set hatch pattern density
pp.set_hatch_mode(2)  # 1=sparse, 2=medium, 3=dense

Figure Size#

Figures are sized in millimetres, and the quantity you control is the axes — the spine bounding box of each panel — not the canvas. Pass axes_size=(width_mm, height_mm) to pp.subplots; publiplots then grows the canvas around it to fit titles, axis labels and tick labels, so panels stay the size you asked for however much decoration they end up carrying:

# One 60 x 45 mm panel
fig, ax = pp.subplots(axes_size=(60, 45))
pp.scatterplot(data=df, x='measurement_a', y='measurement_b', ax=ax)

# A 2 x 3 grid of 35 x 25 mm panels
fig, axes = pp.subplots(2, 3, axes_size=(35, 25))

Without axes_size each panel defaults to 40 x 40 mm.

Note

figure.figsize is the one matplotlib rcParam publiplots deliberately does not manage. pp.subplots computes the canvas from axes_size plus its reservations, so setting figure.figsize has no effect on it, and passing figsize= to a publiplots plotting function raises TypeError by design.

Next Steps#

  • Explore the Plot Examples for more detailed examples

  • Check the API Reference for complete function documentation

  • Read about advanced customization options in the examples gallery