research_helpers.figures
Provides shared matplotlib styling. Requires the figures extra. See Figures.
- research_helpers.figures.current_settings(**overrides)[source]
Return the current figure styling, with ‘overrides’ applied on top.
Reads ‘[tool.research-helpers.figures]’ from the enclosing project if there is one, and falls back to package defaults otherwise.
- Parameters:
**overrides (
Any) – any field of ‘FigureSettings’. A None is treated as ‘not specified’.- Return type:
- Returns:
The resolved styling.
- research_helpers.figures.apply_style(*, profile=None, palette=None, font=None, dpi=None, text_width_in=None, column_width_in=None, width='text', print_height_in=None, figsize=None, font_size=None, style_sheet=DEFAULT_STYLE, grid=True)[source]
Apply the project’s figure style to the current matplotlib session.
Every rcParam is reset first, so repeated calls are idempotent and no earlier style can leak through.
- Parameters:
profile (
str|None, default:None) – ‘screen’ or ‘print’. Defaults to the project’s setting.palette (
str|None, default:None) – seaborn palette name, e.g. ‘husl’, ‘colorblind’, ‘deep’.dpi (
int|None, default:None) – resolution figures are saved at.text_width_in (
float|None, default:None) – the document’s ‘textwidth’.column_width_in (
float|None, default:None) – the document’s ‘columnwidth’.width (
str, default:'text') – which of the two the print profile uses to lay the figure out.print_height_in (
float|None, default:None) – the print profile’s figure height. Defaults to the project’s setting.figsize (
tuple[float,float] |None, default:None) – explicit figure size in inches, overriding the profile’s.font_size (
float|None, default:None) – explicit base font size in points, overriding the profile’s.style_sheet (
str, default:DEFAULT_STYLE) – matplotlib style sheet supplying the base look.grid (
bool, default:True) – whether axes carry a grid.
- Return type:
- Returns:
The settings that were applied.
- Raises:
ValueError – if ‘profile’ is not one of ‘PROFILES’, or ‘width’ is not one of ‘WIDTHS’.
- research_helpers.figures.style(**kwargs)[source]
Apply a style for the duration of the block, then restore the previous rcParams.
Takes the same arguments as ‘apply_style’. For use in notebooks, where an ‘apply_style(profile=”print”)’ would otherwise shrink every figure afterwards.
- Yields:
The settings that were applied.
- Return type:
- Parameters:
kwargs (Any)
- research_helpers.figures.save(figure, path, *, tight=True, pad_inches=0.02, **kwargs)[source]
Write a figure to ‘path’, creating the parent directory, and return the path.
- Parameters:
figure (
Figure) – the figure to write.path (
Path|str) – destination, including the extension, which selects the format.tight (
bool, default:True) – crop to the drawn content. Pass ‘False’ to match width to the print profile.pad_inches (
float, default:0.02) – padding left around the content when ‘tight’.**kwargs (
Any) – passed to ‘Figure.savefig’, e.g. ‘dpi’ or ‘transparent’.
- Return type:
- Returns:
The path written.
- research_helpers.figures.render(figure, *, fmt='png', tight=True, pad_inches=0.02, **kwargs)[source]
Return a figure as bytes, for an emitter registered with ‘research_helpers.build’.
- Parameters:
figure (
Figure) – the figure to render.fmt (
str, default:'png') – the file format, e.g. ‘png’ or ‘pdf’.tight (
bool, default:True) – crop to the drawn content.pad_inches (
float, default:0.02) – padding left around the content when ‘tight’.**kwargs (
Any) – passed to ‘Figure.savefig’, e.g. ‘dpi’.
- Return type:
- Returns:
The encoded figure.
- research_helpers.figures.fit_x(figure, ax, pad=0.1, passes=2)[source]
Narrow the x limits to what the axes actually draws, leaving ‘pad’ data units either side.
Matplotlib’s own margins work in data coordinates, so they leave too much room beside wide artists such as bar labels. Two passes are usually enough for the limits to settle.