utils

AxesListType `module-attribute`

AxesListType = Union[
    AxesType, List[AxesType], List[List[Union[AxesType, None]]]
]

AxesType `module-attribute`

AxesType = Union['MplAxes', 'MplAxes3D', 'BkFigure']

Plottable `module-attribute`

Plottable = Union[
    "MplAxes", "MplAxes3D", "MplFigure", "BkGridPlot", "BkFigure", Iterable
]

template `module-attribute`

template = "\\documentclass{standalone}\n\n\\usepackage{amsmath}\n\\usepackage{graphicx}\n\\usepackage{tikz}\n\\usetikzlibrary{fit,backgrounds,positioning}\n{{- preamble }}\n\n\\begin{document}\n\n\\begin{tikzpicture}\n    % Configurable variables\n    \\def\\figlist{ {{ figures|join(', ') }} }\n    {%- if legendfigure|length %}\n    \\def\\legendfig{ {{ legendfigure }} }\n    \\def\\legendwidth{ {{ legendwidth }} }\n    \\def\\legendtitle{ {{ legendtitle }} }\n    {%- endif %}\n    \\def\\colstep{ {{ columnstep }} }\n    \\def\\rowstep{ {{ rowstep }} }\n    \\def\\ncols{ {{ ncols }} }\n    \\def\\figurepositions{ { {{ figurepositions|join(', ') }} } }\n    \\def\\imgwidth{ {{ imagewidth }} }\n    \\def\\labelshow{ {{ labelshow }} }\n    \\def\\labeleveryfigure{ {{ labeleveryfigure }} }\n    \\def\\rowlabels{ {{ rowlabels }} }\n    \\def\\rowlabelposition{ {{ rowlabelposition }} }\n    \\def\\columnlabels{ {{ columnlabels }} }\n    \\def\\columnlabelposition{ {{ columnlabelposition }} }\n\n    \\def\\allnodes{}\n    \\foreach \\fname [count=\\n from 0] in \\figlist {\n        \\pgfmathsetmacro{\\i}{int(\\figurepositions[int(\\n)]-1)}\n        \\pgfmathsetmacro{\\j}{int(\\i+1)}\n        \\edef\\basename{fig-\\j}\n\n        % Row and column from linear index\n        \\pgfmathsetmacro{\\col}{int(mod(\\i, \\ncols))}\n        \\pgfmathsetmacro{\\row}{int(\\i / \\ncols)}\n        \\pgfmathsetmacro{\\modulo}{int(mod(\\i, \\labeleveryfigure))}\n\n        % Place the image using the full file name\n        \\node[anchor=south] at (\\col * \\colstep, -\\row * \\rowstep)\n            (img-\\basename) {\\IfFileExists{\\fname}{\\includegraphics[width=\\imgwidth]{\\fname}}{\\fbox{\\texttt{Missing \\fname}}}};\n        \\xdef\\allnodes{\\allnodes\\space(img-\\basename)}\n\n        % Label (a), (b), ...\n        \\ifnum\\modulo=0\n            \\ifnum\\labelshow=1\n                \\node[anchor={{ labelnodeanchor }}, xshift={{ labeloffset[0] }}, yshift={{ labeloffset[1] }}] at (img-\\basename.{{ labelnodeposition }})\n                    (lab-\\basename) {(\\char\\numexpr {{ labelstart }}+\\n/\\labeleveryfigure\\relax)};\n                \\xdef\\allnodes{\\allnodes\\space(lab-\\basename)}\n            \\fi\n        \\fi\n    }\n\n    % Annotations for figures\n    {{ figureannotations|join('\\n    ') }}\n\n    % Overall bounding box and legend\n    \\node[fit=\\allnodes] (all) {};\n    {%- if legendfigure|length %}\n    \\IfFileExists{\\legendfig}{\n        \\node[anchor={{ legendanchor }}, xshift={{ legendoffset[0] }}, yshift={{ legendoffset[1] }}] (legend) at (all.{{ legendposition }})\n            {\\includegraphics[width=\\legendwidth]{\\legendfig}};\n        \\node[anchor={{ legendtitleanchor }}, xshift={{ legendtitleoffset[0] }}, yshift={{ legendtitleoffset[1] }}] at (legend.{{ legendtitleposition }}) {\\legendtitle};\n    }{}\n    {%- endif %}\n\n    {%- if customlatexcode|length %}\n    % Custom LaTeX code\n    {{ customlatexcode }}\n    {%- endif %}\n\\end{tikzpicture}\n\n\\end{document}\n\n"

addPrincipleAxis

addPrincipleAxis(
    ax: Union["PolarAxes", "MplAxes"],
    *,
    length: float = 1.15,
    arrow_length: float = 0.05,
    color: str = "black",
    relative: bool = True
) -> "PolarAxes"

Add the principle axis to the polar plot.

PARAMETER	DESCRIPTION
`ax`	Polar axes to add the principle axis TYPE: `Union['PolarAxes', 'MplAxes']`
`length`	Length of the principle axis, by default 1.15 TYPE: `float` DEFAULT: `1.15`
`arrow_length`	Length of the arrow, by default 0.05 TYPE: `float` DEFAULT: `0.05`
`color`	Color of the principle axis, by default "black" TYPE: `str` DEFAULT: `'black'`
`relative`	Whether the length is relative to the maximum radius, by default True TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`PolarAxes`	Polar axes with the principle axis added

crop_pdf

crop_pdf(
    file: str,
    output: str,
    rect: tuple[float, float, float, float],
    page_numbers: list[int] | None = None,
)

Crop PDF file

PARAMETER	DESCRIPTION
`file`	PDF file to be processed. TYPE: `str`
`output`	PDF file to save. TYPE: `str`
`rect`	Rectangle (x1, y1, x2, y2, relative coordinate) to crop TYPE: `tuple[float, float, float, float]`
`page_numbers`	Page numbers to crop, if None, all pages will be cropped TYPE: `list[int] or None` DEFAULT: `None`

extract_axes

extract_axes(
    obj: Plottable, types: List[type], attrs: List[str]
) -> List[AxesType]

Extract axes from the given object.

PARAMETER	DESCRIPTION
`obj`	Object to extract axes from TYPE: `Plottable`
`types`	Accepted types of the axes TYPE: `List[type]`
`attrs`	Attributes of the object to extract axes from TYPE: `List[str]`

RETURNS	DESCRIPTION
`List[AxesType]`	List of axes extracted from the object

generate_figure_grid

generate_figure_grid(
    *figures: str,
    output: str,
    column_step: str = "4.8cm",
    row_step: str = "3.2cm",
    image_width: str = "4.0cm",
    ncols: int = 2,
    legend_figure: str = "",
    legend_width: str = "1.5cm",
    legend_position: str = "west",
    legend_anchor: str = "east",
    legend_offset: tuple[str, str] = ("0.0cm", "0.0cm"),
    legend_title: str = "",
    legend_title_position: str = "north",
    legend_title_anchor: str = "south",
    legend_title_offset: tuple[str, str] = ("0.0cm", "0.0cm"),
    label_show: bool = True,
    label_start: str = "a",
    label_every_figure: int = 1,
    label_position: Literal[
        "upper left",
        "upper right",
        "upper center",
        "lower left",
        "lower right",
        "lower center",
        "center left",
        "center right",
    ] = "lower left",
    label_offset: tuple[str, str] = ("0.0cm", "0.0cm"),
    figure_positions: list[int] | None = None,
    figure_annotations: list[tuple[int, str, str, str, str]] | None = None,
    preamble: str = "",
    custom_latex_code: str = "",
    replacements: list[tuple[str, str]] | None = None
)

Generate a grid of figures in a single PDF file.

PARAMETER	DESCRIPTION
`figures`	List of figure files to be arranged in a grid. TYPE: `str` DEFAULT: `()`
`output`	Output tex file name. TYPE: `str`
`column_step`	Step size between columns, by default "4.8cm" TYPE: `str` DEFAULT: `'4.8cm'`
`row_step`	Step size between rows, by default "3.2cm" TYPE: `str` DEFAULT: `'3.2cm'`
`image_width`	Width of each image, by default "4.0cm" TYPE: `str` DEFAULT: `'4.0cm'`
`ncols`	Number of columns in the grid, by default 2 TYPE: `int` DEFAULT: `2`
`legend_figure`	Figure file for the legend, by default "" TYPE: `str` DEFAULT: `''`
`legend_width`	Width of the legend, by default "1.5cm" TYPE: `str` DEFAULT: `'1.5cm'`
`legend_position`	Position for the legend, by default "north" TYPE: `str` DEFAULT: `'west'`
`legend_anchor`	Anchor for the legend, by default "south" TYPE: `str` DEFAULT: `'east'`
`legend_offset`	Offset for the legend, by default ("0.0cm", "0.0cm") TYPE: `tuple[str, str]` DEFAULT: `('0.0cm', '0.0cm')`
`legend_title`	Title for the legend, by default "" TYPE: `str` DEFAULT: `''`
`legend_title_position`	Position for the legend title, by default "north" TYPE: `str` DEFAULT: `'north'`
`legend_title_anchor`	Anchor for the legend title, by default "south" TYPE: `str` DEFAULT: `'south'`
`legend_title_offset`	Offset for the legend title, by default ("0.0cm", "0.0cm") TYPE: `tuple[str, str]` DEFAULT: `('0.0cm', '0.0cm')`
`label_show`	Whether to show labels, by default True TYPE: `bool` DEFAULT: `True`
`label_start`	Start label, by default "a" TYPE: `str` DEFAULT: `'a'`
`label_every_figure`	Add labels to every nth figure, by default 1 TYPE: `int` DEFAULT: `1`
`label_position`	Position of the label, by default "lower left" TYPE: `Literal['upper left', 'upper right', 'upper center', 'lower left', 'lower right', 'lower center', 'center left', 'center right']` DEFAULT: `'lower left'`
`label_offset`	Offset of the label, by default ("0.0cm", "0.0cm") TYPE: `tuple[str, str]` DEFAULT: `('0.0cm', '0.0cm')`
`figure_positions`	List of figure positions in the grid, by default None which means the figures are arranged in order TYPE: `list[int] \| None` DEFAULT: `None`
`figure_annotations`	Figure annotations for each figure, by default None. The list of tuples should contain (figure_number (1-based), position, anchor, options, text) for each annotation. TYPE: `list[tuple[int, str, str, str, str]] \| None` DEFAULT: `None`
`preamble`	Custom LaTeX code in the preamble. TYPE: `str` DEFAULT: `''`
`custom_latex_code`	Custom LaTeX code at the end of the tikz figure. TYPE: `str` DEFAULT: `''`
`replacements`	Regex for replacements TYPE: `list[tuple[str, str]]` DEFAULT: `None`

setAxesProps

setAxesProps(
    ax: "MplAxes",
    *,
    unpack_dict: bool = True,
    unpack_tuple: bool = True,
    **kwargs
) -> None

Set the properties for the axes. For legends, lines with same label will be combined.

PARAMETER	DESCRIPTION
`ax`	Axes to set properties TYPE: `Axes`
`unpack_dict`	Whether to unpack the dict, by default True TYPE: `bool` DEFAULT: `True`
`unpack_tuple`	Whether to unpack the tuple, by default True TYPE: `bool` DEFAULT: `True`
`kwargs`	Keyword arguments for the `Axes.set_` or `Axes.` methods. If the value is a dict and `unpack_dict` is True, then the dict will be unpacked and passed to the method as keyword arguments; if the value is a tuple and `unpack_tuple` is True, then the tuple will be unpacked and passed to the method as positional arguments; DEFAULT: `{}`

setupPiPlane

setupPiPlane(
    ax: Union["PolarAxes", "MplAxes"],
    *,
    length: float = 1.15,
    color: str = "black",
    arrow_length: float = 0.05,
    grid_length: float = 1.05,
    show_sectors: bool = False,
    sector_position: float = 0.2,
    show_xylabel: bool = False,
    show_xticks: bool = False,
    show_xticklabels: bool = False,
    show_yticks: bool = True,
    show_yticklabels: bool = False,
    yticks_min: float = 0.0,
    yticks_max: float = 1.0,
    ytiks_num: int = 6,
    relative: bool = True
) -> "PolarAxes"

Setup the pi-plane for the polar plot.

PARAMETER	DESCRIPTION
`ax`	Polar axes to add the principle axis TYPE: `Union['PolarAxes', 'MplAxes']`
`length`	Length of the principle axis, by default 1.15 TYPE: `float` DEFAULT: `1.15`
`color`	Color of the principle axis, by default "black" TYPE: `str` DEFAULT: `'black'`
`arrow_length`	Length of the arrow, by default 0.05 TYPE: `float` DEFAULT: `0.05`
`grid_length`	Length of the grid, by default 1.05 TYPE: `float` DEFAULT: `1.05`
`show_sectors`	Whether to show the sectors, by default False TYPE: `bool` DEFAULT: `False`
`sector_position`	Sector position, by default 0.2 TYPE: `float` DEFAULT: `0.2`
`yticks_min`	Minimum value of the yticks, by default 0.0 TYPE: `float` DEFAULT: `0.0`
`yticks_max`	Maximum value of the yticks, by default 1.0 TYPE: `float` DEFAULT: `1.0`
`ytiks_num`	Number of yticks, by default 6 TYPE: `int` DEFAULT: `6`
`relative`	Whether the length is relative to the maximum radius, by default True TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`PolarAxes`	Polar axes with the principle axis added

subplots

subplots(
    *args: int,
    numfig: int | None = None,
    numfig_extra: int = 0,
    ncols: int = 2,
    subfigsize: Tuple[int | float, int | float] = (6, 4),
    figsize: Tuple[int | float, int | float] | None = None,
    return_figure: bool = False,
    on: Plottable | None = None,
    backend: Literal["matplotlib", "bokeh"] | str | None = None,
    squeeze: bool = True,
    ensure_1d: bool = False,
    ensure_2d: bool = False,
    clear_unused_axes: bool = True,
    numbering: Literal["numeric", "alphabetic"] | None = None,
    numbering_title_kwargs: Dict[str, Any] | None = None,
    projection: str | Projections | List[Projections] | None = None,
    **subplot_kw
) -> AxesListType | Tuple[Figure, AxesListType]

Create (or get) a list of axes (matplotlib) or figures (bokeh) for subplots.

PARAMETER	DESCRIPTION
`args`	Positional arguments for the number of figures. If no arguments are given, the number of figures is set to 1. If one argument is given, it is the number of figures, the number of columns is given by argument `ncols` (defaults to 2); if two arguments are given, they are the number of rows and columns TYPE: `tuple[int, ...]` DEFAULT: `()`
`numfig`	Number of figures, by default None which means the number of figures is given by the first argument, higher priority than `args` TYPE: `int \| None` DEFAULT: `None`
`numfig_extra`	Extra number of figures to create, by default 0 TYPE: `int` DEFAULT: `0`
`ncols`	Number of columns, by default 2 TYPE: `int` DEFAULT: `2`
`subfigsize`	Subfigure size, by default (6, 4) TYPE: `Tuple[int \| float, int \| float]` DEFAULT: `(6, 4)`
`figsize`	Figure size, higher priority than `subfigsize`, by default None TYPE: `Tuple[int \| float, int \| float]` DEFAULT: `None`
`return_figure`	Whether to return the matplotlib figure, by default False TYPE: `bool` DEFAULT: `False`
`on`	Axes to plot on, by default None TYPE: `PlotAxes` DEFAULT: `None`
`backend`	Backend to use when creating new figures , by default None which means the backend set in the environment variable `MICROMECHANICAL_PLOTTING_BACKEND`. TYPE: `Literal['matplotlib', 'bokeh'] \| str` DEFAULT: `None`
`squeeze`	Whether to squeeze the returned axes, by default True. TYPE: `bool` DEFAULT: `True`
`ensure_1d`	Whether to ensure the returned axes is 1d, by default False TYPE: `bool` DEFAULT: `False`
`ensure_2d`	Whether to ensure the returned axes is 2d, by default False TYPE: `bool` DEFAULT: `False`
`clear_unused_axes`	Whether to clear the newly created unused axes, by default True TYPE: `bool` DEFAULT: `True`
`numbering`	Numbering style for subplots, by default None TYPE: `Literal['numeric', 'alphabetic']` DEFAULT: `None`
`numbering_title_kwargs`	Keyword arguments for the title of the numbering, by default None TYPE: `Dict[str, Any]` DEFAULT: `None`
`projection`	Projection for the axes, can be a single projection for all axes or a list of projections for each axes, by default None TYPE: `str \| Projections \| List[str \| Projections]` DEFAULT: `None`
`subplot_kw`	Keyword arguments for the `plt.subplots` or `bplt.figure` method. For matplotlib, the default figsize is (6 * ncols, 4 * nrows); for bokeh, the default aspect_ratio is 1.5. DEFAULT: `{}`

RETURNS DESCRIPTION

AxesListType | Tuple[Figure, AxesListType]

Depending on the value of ensure_1d and ensure_2d, the returned value is different:

If ensure_1d is True, then a 1d list of axes or figures is returned
If ensure_2d is True, then a 2d list of lists of axes or figures is returned

Otherwise, if squeeze is True, then:

If numfig is 1, then a single axes or figure is returned
If numfig is greater than 1 and ncols is 1 or numfig is less than ncols, then a list of axes or figures is returned
Otherwise, a list of lists of axes or figures is returned

In other cases, a list of lists of axes or figures is always returned.

If a list of lists of axes or figures should be returned and numfig is less than nrows * ncols, extra axes will be set to None