Skip to content

themes

The themes module provides complete MSU theming for matplotlib plots.

Module Overview

This module provides:

  • Complete MSU theme application
  • Seaborn style integration
  • Theme reset functionality
  • Automatic font registration

Functions

theme_msu(base_size=11, base_family='Metropolis', use_grid=False, grid_color='#E5E5E5', grid_linewidth=0.8, spine_color='#000000', spine_linewidth=1.0, color_cycle=None, register_fonts=True)

Apply MSU theme to matplotlib plots.

This function sets matplotlib rcParams to use MSU branding including: - Metropolis font (automatically registered) - MSU color palette - Clean, professional styling - Optional grid lines

Args: base_size: Base font size for all text elements (default: 11) base_family: Font family to use (default: "Metropolis") use_grid: Whether to show grid lines (default: False) grid_color: Color of grid lines (default: "#E5E5E5") grid_linewidth: Width of grid lines (default: 0.8) spine_color: Color of axis spines (default: "#000000") spine_linewidth: Width of axis spines (default: 1.0) color_cycle: Custom color cycle (default: MSU colors) register_fonts: Whether to register Metropolis fonts (default: True)

Returns: Dictionary of applied rcParams

Examples: >>> from msuthemes import theme_msu >>> import matplotlib.pyplot as plt >>> >>> # Apply MSU theme >>> theme_msu() >>> >>> # Create plot with MSU styling >>> plt.plot([1, 2, 3], [1, 4, 2]) >>> plt.title('MSU Plot') >>> plt.show()

>>> # Apply theme with grid
>>> theme_msu(use_grid=True)

>>> # Apply theme with larger font
>>> theme_msu(base_size=14)
Source code in msuthemes/themes.py 
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def theme_msu(
    base_size: float = 11,
    base_family: str = "Metropolis",
    use_grid: bool = False,
    grid_color: str = "#E5E5E5",
    grid_linewidth: float = 0.8,
    spine_color: str = "#000000",
    spine_linewidth: float = 1.0,
    color_cycle: Optional[list] = None,
    register_fonts: bool = True,
) -> Dict[str, Any]:
    """Apply MSU theme to matplotlib plots.

    This function sets matplotlib rcParams to use MSU branding including:
    - Metropolis font (automatically registered)
    - MSU color palette
    - Clean, professional styling
    - Optional grid lines

    Args:
        base_size: Base font size for all text elements (default: 11)
        base_family: Font family to use (default: "Metropolis")
        use_grid: Whether to show grid lines (default: False)
        grid_color: Color of grid lines (default: "#E5E5E5")
        grid_linewidth: Width of grid lines (default: 0.8)
        spine_color: Color of axis spines (default: "#000000")
        spine_linewidth: Width of axis spines (default: 1.0)
        color_cycle: Custom color cycle (default: MSU colors)
        register_fonts: Whether to register Metropolis fonts (default: True)

    Returns:
        Dictionary of applied rcParams

    Examples:
        >>> from msuthemes import theme_msu
        >>> import matplotlib.pyplot as plt
        >>>
        >>> # Apply MSU theme
        >>> theme_msu()
        >>>
        >>> # Create plot with MSU styling
        >>> plt.plot([1, 2, 3], [1, 4, 2])
        >>> plt.title('MSU Plot')
        >>> plt.show()

        >>> # Apply theme with grid
        >>> theme_msu(use_grid=True)

        >>> # Apply theme with larger font
        >>> theme_msu(base_size=14)
    """
    # Register Metropolis fonts if requested
    if register_fonts:
        try:
            register_metropolis_fonts(verbose=False)
        except Exception as e:
            warnings.warn(
                f"Could not register Metropolis fonts: {e}. Using default font.",
                RuntimeWarning
            )

    # Check if Metropolis is available, fallback to sans-serif if not
    if not is_metropolis_available() and base_family == "Metropolis":
        warnings.warn(
            "Metropolis font not available. Using 'sans-serif' instead. "
            "Try clearing matplotlib cache or restarting Python.",
            RuntimeWarning
        )
        base_family = "sans-serif"

    # Get color cycle
    if color_cycle is None:
        color_cycle = _get_msu_color_cycle()

    # Calculate relative sizes
    small_size = base_size * 0.85
    medium_size = base_size
    large_size = base_size * 1.15

    # Define MSU rcParams
    msu_params = {
        # Figure
        'figure.facecolor': 'white',
        'figure.edgecolor': 'white',
        'figure.figsize': (8, 6),
        'figure.dpi': 100,

        # Font
        'font.family': base_family,
        'font.size': base_size,
        'font.weight': 'normal',

        # Text sizes
        'axes.titlesize': large_size,
        'axes.labelsize': medium_size,
        'xtick.labelsize': small_size,
        'ytick.labelsize': small_size,
        'legend.fontsize': small_size,
        'figure.titlesize': large_size,

        # Axes
        'axes.facecolor': 'white',
        'axes.edgecolor': spine_color,
        'axes.linewidth': spine_linewidth,
        'axes.labelcolor': 'black',
        'axes.axisbelow': True,  # Grid lines below plot elements
        'axes.prop_cycle': cycler('color', color_cycle),
        'axes.spines.top': False,
        'axes.spines.right': False,
        'axes.spines.left': True,
        'axes.spines.bottom': True,

        # Grid
        'axes.grid': use_grid,
        'axes.grid.axis': 'both',
        'grid.color': grid_color,
        'grid.linestyle': '-',
        'grid.linewidth': grid_linewidth,
        'grid.alpha': 0.5,

        # Ticks
        'xtick.color': 'black',
        'ytick.color': 'black',
        'xtick.direction': 'out',
        'ytick.direction': 'out',
        'xtick.major.size': 5,
        'ytick.major.size': 5,
        'xtick.minor.size': 3,
        'ytick.minor.size': 3,
        'xtick.major.width': spine_linewidth,
        'ytick.major.width': spine_linewidth,

        # Legend
        'legend.frameon': True,
        'legend.framealpha': 0.8,
        'legend.facecolor': 'white',
        'legend.edgecolor': '#CCCCCC',
        'legend.fancybox': False,
        'legend.shadow': False,

        # Lines
        'lines.linewidth': 2.0,
        'lines.markersize': 6,
        'lines.markeredgewidth': 0,

        # Patches
        'patch.linewidth': 0.5,
        'patch.edgecolor': 'black',

        # Savefig
        'savefig.dpi': 300,
        'savefig.facecolor': 'white',
        'savefig.edgecolor': 'white',
        'savefig.bbox': 'tight',
    }

    # Apply the theme
    mpl.rcParams.update(msu_params)

    return msu_params

set_msu_style(style='white', context='notebook', palette=None, font='Metropolis', font_scale=1.0, register_fonts=True)

Set MSU styling for seaborn plots.

This function configures seaborn with MSU branding including colors, fonts, and styling preferences.

Args: style: Seaborn style ('white', 'whitegrid', 'dark', 'darkgrid', 'ticks') Default: 'white' context: Seaborn context ('paper', 'notebook', 'talk', 'poster') Default: 'notebook' palette: Custom color palette (default: MSU colors) font: Font family (default: 'Metropolis') font_scale: Scale factor for fonts (default: 1.0) register_fonts: Whether to register Metropolis fonts (default: True)

Examples: >>> from msuthemes import set_msu_style >>> import seaborn as sns >>> import matplotlib.pyplot as plt >>> >>> # Apply MSU style to seaborn >>> set_msu_style() >>> >>> # Create seaborn plot >>> tips = sns.load_dataset('tips') >>> sns.scatterplot(data=tips, x='total_bill', y='tip') >>> plt.show()

>>> # Use with whitegrid style
>>> set_msu_style(style='whitegrid')

>>> # Use for presentation
>>> set_msu_style(context='talk', font_scale=1.2)
Source code in msuthemes/themes.py 
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
def set_msu_style(
    style: str = "white",
    context: str = "notebook",
    palette: Optional[list] = None,
    font: str = "Metropolis",
    font_scale: float = 1.0,
    register_fonts: bool = True,
) -> None:
    """Set MSU styling for seaborn plots.

    This function configures seaborn with MSU branding including colors,
    fonts, and styling preferences.

    Args:
        style: Seaborn style ('white', 'whitegrid', 'dark', 'darkgrid', 'ticks')
               Default: 'white'
        context: Seaborn context ('paper', 'notebook', 'talk', 'poster')
                Default: 'notebook'
        palette: Custom color palette (default: MSU colors)
        font: Font family (default: 'Metropolis')
        font_scale: Scale factor for fonts (default: 1.0)
        register_fonts: Whether to register Metropolis fonts (default: True)

    Examples:
        >>> from msuthemes import set_msu_style
        >>> import seaborn as sns
        >>> import matplotlib.pyplot as plt
        >>>
        >>> # Apply MSU style to seaborn
        >>> set_msu_style()
        >>>
        >>> # Create seaborn plot
        >>> tips = sns.load_dataset('tips')
        >>> sns.scatterplot(data=tips, x='total_bill', y='tip')
        >>> plt.show()

        >>> # Use with whitegrid style
        >>> set_msu_style(style='whitegrid')

        >>> # Use for presentation
        >>> set_msu_style(context='talk', font_scale=1.2)
    """
    try:
        import seaborn as sns
    except ImportError:
        raise ImportError(
            "seaborn is required for set_msu_style(). "
            "Install it with: pip install seaborn"
        )

    # Register fonts if requested
    if register_fonts:
        try:
            register_metropolis_fonts(verbose=False)
        except Exception as e:
            warnings.warn(
                f"Could not register Metropolis fonts: {e}",
                RuntimeWarning
            )

    # Check font availability
    if not is_metropolis_available() and font == "Metropolis":
        warnings.warn(
            "Metropolis font not available. Using default seaborn font.",
            RuntimeWarning
        )
        font = "sans-serif"

    # Get color palette
    if palette is None:
        palette = _get_msu_color_cycle()

    # Set seaborn style and context
    sns.set_style(style)
    sns.set_context(context, font_scale=font_scale)

    # Set color palette
    sns.set_palette(palette)

    # Set font
    mpl.rcParams['font.family'] = font

    # Additional MSU-specific styling
    mpl.rcParams.update({
        'axes.prop_cycle': cycler('color', palette),
        'axes.spines.top': False,
        'axes.spines.right': False,
    })

reset_theme()

Reset matplotlib to default settings.

This function restores matplotlib's default rcParams, removing any MSU theme customizations.

Examples: >>> from msuthemes import theme_msu, reset_theme >>> >>> # Apply MSU theme >>> theme_msu() >>> >>> # ... create plots ... >>> >>> # Reset to defaults >>> reset_theme()

Source code in msuthemes/themes.py 
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
def reset_theme() -> None:
    """Reset matplotlib to default settings.

    This function restores matplotlib's default rcParams, removing
    any MSU theme customizations.

    Examples:
        >>> from msuthemes import theme_msu, reset_theme
        >>>
        >>> # Apply MSU theme
        >>> theme_msu()
        >>>
        >>> # ... create plots ...
        >>>
        >>> # Reset to defaults
        >>> reset_theme()
    """
    mpl.rcParams.update(mpl.rcParamsDefault)

Usage Examples

Basic Theme Application

from msuthemes import theme_msu
import matplotlib.pyplot as plt

# Apply MSU theme
theme_msu()

# Create plot
plt.plot([1, 2, 3, 4], [1, 4, 2, 3])
plt.title('MSU-Themed Plot')
plt.show()

Customized Theme

from msuthemes import theme_msu
import matplotlib.pyplot as plt

# Apply theme with customization
theme_msu(
    base_size=12,
    grid=True,
    spines='bl'
)

# Create plot
plt.plot([1, 2, 3, 4], [1, 4, 2, 3])
plt.show()

Seaborn Integration

from msuthemes import set_msu_style
import seaborn as sns
import matplotlib.pyplot as plt

# Apply MSU style to seaborn
set_msu_style()

# Create seaborn plot
sns.boxplot(data=data)
plt.show()

Resetting Theme

from msuthemes import theme_msu, reset_theme
import matplotlib.pyplot as plt

# Apply MSU theme
theme_msu()
plt.plot([1, 2, 3], [1, 4, 2])
plt.show()

# Reset to defaults
reset_theme()
plt.plot([1, 2, 3], [1, 4, 2])
plt.show()

Different Spine Configurations

from msuthemes import theme_msu
import matplotlib.pyplot as plt

# Only bottom and left spines (default)
theme_msu(spines='bl')
plt.plot([1, 2, 3], [1, 4, 2])
plt.show()

# All spines
theme_msu(spines='all')
plt.plot([1, 2, 3], [1, 4, 2])
plt.show()

# No spines
theme_msu(spines='none')
plt.plot([1, 2, 3], [1, 4, 2])
plt.show()

Presentation vs Publication

from msuthemes import theme_msu
import matplotlib.pyplot as plt

# Larger text for presentations
theme_msu(base_size=14, grid=True)
plt.plot([1, 2, 3], [1, 4, 2])
plt.title('Presentation Figure')
plt.show()

# Smaller text for publications
theme_msu(base_size=9, grid=False, spines='bl')
plt.plot([1, 2, 3], [1, 4, 2])
plt.title('Publication Figure')
plt.show()

Theme Components

The MSU theme modifies these matplotlib rcParams:

Fonts

  • Font family: Metropolis
  • Scaled font sizes based on base_size parameter

Colors

  • Color cycle using MSU colors
  • Axes colors and backgrounds
  • Grid colors

Layout

  • Figure size and DPI
  • Axes line widths
  • Grid line styles

Spines

  • Configurable axes borders
  • Options: 'bl', 'all', 'none', or combinations

See Also