utils

AxesType `module-attribute`

AxesType: Type[Union["MplAxes", "MplAxes3D", "BkFigure"]] = Union[
    "MplAxes", "MplAxes3D", "BkFigure"
]

Plottable `module-attribute`

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

addPrincipleAxis

addPrincipleAxis(
    ax: "PolarAxes",
    *,
    length: float = 1.15,
    arrow_length: float = 0.05,
    relative: bool = True
) -> "PolarAxes"

Add the principle axis to the polar plot.

PARAMETER	DESCRIPTION
`ax`	Polar axes to add the principle axis TYPE: `PolarAxes`
`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`
`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

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

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: "PolarAxes",
    *,
    length: float = 1.15,
    arrow_length: float = 0.05,
    grid_length: float = 1.05,
    show_sectors: bool = False,
    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: `PolarAxes`
`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`
`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`
`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(
    numfig: int = 1,
    *,
    numfig_extra: int = 0,
    on: Plottable | None = None,
    ncols: int = 2,
    subfigsize: Tuple[int | float, int | float] = (6, 4),
    figsize: Tuple[int | float, int | float] | 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 | List[str] | None = None,
    **subplot_kw
) -> AxesType | List[AxesType] | List[List[AxesType | None]]

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

PARAMETER	DESCRIPTION
`numfig`	Number of figures to create, by default 1 TYPE: `int` DEFAULT: `1`
`numfig_extra`	Extra number of figures to create, by default 0 TYPE: `int` DEFAULT: `0`
`on`	Axes to plot on, by default None TYPE: `PlotAxes` DEFAULT: `None`
`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`
`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 False. 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 \| List[str]` 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

AxesType or List[AxesType] or List[List[AxesType | None]]

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