Setting defaults once, with rcParams

import matplotlib.pyplot as plt
import matplotlib_inline.backend_inline
from loguru import logger

# Crisp retina output + sane default DPI for the rendered docs
matplotlib_inline.backend_inline.set_matplotlib_formats("retina")
plt.rcParams["figure.dpi"] = 150
logger.remove()

I have typed cmap="viridis" into eleven calls in this notebook. Is there one place I can say it instead?

There is: mnutils.rcParams, a single validated mapping of every default MNUtils ships. It works the way matplotlib.rcParams does, deliberately — the muscle memory transfers, including the escape hatches.

What is in there¶

import mnutils
from mnutils.GESeries import MRISeries
from mnutils.plotting.images import display_images
from mnutils.testing import build_fake_exam
from mnutils.utils.nifti import get_display_zooms

sorted(mnutils.rcParams)

Every example below displays one anatomical volume, from a fake exam built on the fly by mnutils.testing.build_fake_exam -- the same fixtures the GESeries page uses:

DATA_FOLDER = build_fake_exam("brain_mrs_mrsi_exam") / "data"

t1 = MRISeries(DATA_FOLDER, 2)  # 002_3D_Ax_T1_BRAVO
anatomical = t1.images()
zooms = get_display_zooms(t1.nii)
anatomical.shape, zooms

The names are dotted and grouped by what they configure: image.* for how image panels are drawn, grid.* for how big the display_images grid gets, spectra.* for spectral axes, nifti.* for orientation and resampling, save.* for figure saving.

mnutils.rcParams["image.cmap"], mnutils.rcParams["nifti.orientation"]

Change it for the session¶

Assign, and every later call picks it up:

mnutils.rcParams["image.cmap"] = "viridis"

display_images(anatomical, zooms=zooms, fig_title="viridis, because rcParams says so")

An anatomical scan wants "gray", of course -- which is what the next section is for.

def display_images(..., cmap: str = DEFAULT_PARAMS["cmap"]):  # ❌ frozen

def display_images(..., cmap: str | None = None):  # ✅ read at call time
    cmap = resolve_rc(cmap, "image.cmap")

Change it for one block¶

A session-wide assignment is the wrong tool when one figure needs different treatment. rc_context() applies overrides and restores whatever was there before, exception or not:

with mnutils.rc_context({"image.cmap": "gray"}):
    print("inside :", mnutils.rcParams["image.cmap"])

print("outside:", mnutils.rcParams["image.cmap"])

inside : gray
outside: viridis

# STRICT TESTS: rc_context restores the previous value, including on an exception
assert mnutils.rcParams["image.cmap"] == "viridis"
try:
    with mnutils.rc_context({"image.cmap": "gray"}):
        raise RuntimeError("boom")
except RuntimeError:
    pass
assert mnutils.rcParams["image.cmap"] == "viridis"

mnutils.rcdefaults()
assert mnutils.rcParams["image.cmap"] == "magma"

rcdefaults() puts everything back, which is the fastest way out of a notebook whose defaults have drifted:

mnutils.rcdefaults()
mnutils.rcParams["image.cmap"]

The saving contexts are the same mechanism wearing a name. save_figure(..., context="poster") applies the "poster" entry of rc_presets through rc_context — there is no separate poster-parameters dict to keep in sync:

mnutils.rc_presets

A typo raises instead of doing nothing¶

Every assignment goes through a validator that owns that key, so the failure lands where the mistake is:

try:
    mnutils.rcParams["image.cmpa"] = "gray"
except KeyError as err:
    print(err)

"'image.cmpa' is not a valid rcParam; did you mean 'image.cmap'?"

try:
    mnutils.rcParams["nifti.orientation"] = ("L", "P", "Z")
except ValueError as err:
    print(err)

invalid value for rcParams['nifti.orientation']: expected three axis codes from AILPRS, got ('L', 'P', 'Z')

# STRICT TESTS: unknown keys and invalid values are both rejected, and neither leaves a trace
import pytest

with pytest.raises(KeyError, match="not a valid rcParam"):
    mnutils.rcParams["image.cmpa"] = "gray"
with pytest.raises(ValueError):
    mnutils.rcParams["grid.panel_height"] = "30rem; background: red"
assert mnutils.rcParams["grid.panel_height"] == "17rem"
assert "image.cmpa" not in mnutils.rcParams

Bigger panels for an anatomical series¶

The default grid is tuned for a row of low-resolution multi-nuclear panels. A high-resolution anatomical slice at that size throws away most of what is in the data — so grid.panel_height exists, and so does a per-call argument for the one figure that needs it:

mnutils.rcParams["image.cmap"] = "gray"

display_images(anatomical, zooms=zooms, fig_title="default panel height")

display_images(anatomical, zooms=zooms, panel_height="30rem", fig_title="panel_height='30rem'")

Pass grid_max_height alongside it when the taller panels start scrolling inside their box, and set mnutils.rcParams["grid.panel_height"] instead when every grid in the notebook should be bigger.

Precedence runs in the order you would guess, and it is the same for every parameter in this page:

# STRICT TESTS: an explicit argument beats rcParams, and doesn't leak into it
mnutils.rcParams["grid.panel_height"] = "12rem"
display_images(anatomical[:, :, :2], zooms=zooms, panel_height="30rem")
assert mnutils.rcParams["grid.panel_height"] == "12rem"

# ...and a bare number is read as rem by the same validator the rcParam uses
assert mnutils.rcparams.validate_css_length(30) == "30rem"

mnutils.rcdefaults()
assert mnutils.rcParams["grid.panel_height"] == "17rem"
assert mnutils.rcParams["image.cmap"] == "magma"