Locators¶

Bases: BreaksLocator

Place ticks on nice numbers inside the data range.

Delegates to mizani.breaks.breaks_extended (Talbot's extended Wilkinson algorithm) with only_inside=True, so every tick lies within the interval it is given. When used on an axis, ticks are computed from the data interval, not the view interval, which is what lets a range frame hug the data.

With loose=True, computes nice numbers from the data range and extends the tick grid outward by whole steps so the outermost ticks bound the interval. A pair (low, high) frees each end on its own: the search holds a False end inside the interval and lets a True end past it, then only the True end is extended.

Parameters:

• spacing (float, default: None) –

  The gap to aim for between ticks, in tick-label heights. See BreaksLocator.

• n (int, default: None) –

  The number of ticks to aim for, overriding spacing. See BreaksLocator.

• loose (bool or tuple of two bools, default: False) –

  If True, extend the tick grid outward by whole steps so the outermost ticks bound the data interval. A pair (low, high) sets each end on its own. Default is False.

• nice_numbers (sequence of float, default: None) –

  Advanced tuning of the underlying Talbot extended-Wilkinson search: preferred step mantissas for the tick-step search (mizani's Q). Biases which step sizes the search considers; the chosen step may be a whole multiple of an entry, and ticks are multiples of the step, so tick values are not strictly limited to these mantissas. None uses mizani's default (1, 5, 2, 2.5, 4, 3).

• weights (dict, default: None) –

  Advanced tuning of the underlying Talbot extended-Wilkinson search: a partial mapping of weights for the four scoring criteria, merged over the defaults {"simplicity": 0.25, "coverage": 0.2, "density": 0.5, "legibility": 0.05} (mizani's w). Keys must be a subset of {"simplicity", "coverage", "density", "legibility"}.

• unit (float, default: 1.0) –

  Place ticks on nice numbers measured in units of unit: the search runs on (vmin / unit, vmax / unit) and the result is multiplied back. With unit=np.pi the plain decimal nice numbers (0.5, 0.25) become np.pi / 2, np.pi / 4, ticks that follow the axis width the way the default ticks do, where a fixed MultipleLocator(np.pi / 2) would not. Must be finite and strictly positive; the default 1.0 is an exact identity that leaves the default tick path unchanged. A tick is placed, not labelled "pi/2" -- write the fraction with a FuncFormatter.

__call__() -> np.ndarray

tick_values(
    vmin: float, vmax: float, n: int | None = None
) -> np.ndarray

view_limits(
    vmin: float, vmax: float
) -> tuple[float, float]

view_limits_over(
    vmin: float,
    vmax: float,
    interval: tuple[float, float] | None,
    n: int | None = None,
) -> tuple[float, float]

Bases: BreaksLocator

Place ticks on integer powers inside the data range of a log axis.

Delegates to mizani.breaks.breaks_log, which returns breaks at integer powers of base (with a sub-decade fallback for narrow ranges) that may overflow the interval; the overflow is filtered away so every tick lies within the interval. When used on an axis, ticks are computed from the data interval, not the view interval, which is what lets a range frame hug the data.

With loose=True, keeps the covering breaks and extends the grid outward by whole multiplicative steps so the outermost ticks bound the interval. A pair (low, high) frees each end on its own.

Parameters:

• spacing (float, default: None) –

  The gap to aim for between ticks, in tick-label heights. See BreaksLocator.

• n (int, default: None) –

  The number of ticks to aim for, overriding spacing. See BreaksLocator.

• loose (bool or tuple of two bools, default: False) –

  If True, extend the tick grid outward by whole multiplicative steps so the outermost ticks bound the data interval. A pair (low, high) sets each end on its own. Default is False.

• base (float, default: 10) –

  Base of the logarithm, matching the axis scale's base.

nonsingular(
    vmin: float, vmax: float
) -> tuple[float, float]

__call__() -> np.ndarray

tick_values(
    vmin: float, vmax: float, n: int | None = None
) -> np.ndarray

view_limits(
    vmin: float, vmax: float
) -> tuple[float, float]

view_limits_over(
    vmin: float,
    vmax: float,
    interval: tuple[float, float] | None,
    n: int | None = None,
) -> tuple[float, float]

Bases: BreaksLocator

Place ticks on calendar-nice dates inside the data range of a date axis.

Delegates to mizani.breaks.breaks_date, which returns breaks at calendar-nice positions (year, month, day, hour, ... starts) that may overflow the interval; the overflow is filtered away so every tick lies within the interval. When used on an axis, ticks are computed from the data interval, not the view interval, which is what lets a range frame hug the data.

Tick positions are floats in matplotlib date units; the interval is converted to datetimes at the boundary with matplotlib.dates, so any matplotlib epoch setting is respected.

With loose=True, keeps the covering breaks so the outermost ticks bound the interval. A pair (low, high) frees each end on its own.

Parameters:

• spacing (float, default: None) –

  The gap to aim for between ticks, in tick-label heights. See BreaksLocator.

• n (int, default: None) –

  The number of ticks to aim for, overriding spacing. See BreaksLocator.

• loose (bool or tuple of two bools, default: False) –

  If True, keep the covering breaks so the outermost ticks bound the data interval. A pair (low, high) sets each end on its own. Default is False.

__call__() -> np.ndarray

tick_values(
    vmin: float, vmax: float, n: int | None = None
) -> np.ndarray

view_limits(
    vmin: float, vmax: float
) -> tuple[float, float]

view_limits_over(
    vmin: float,
    vmax: float,
    interval: tuple[float, float] | None,
    n: int | None = None,
) -> tuple[float, float]

Bases: FixedLocator

Place ticks at features of the paired (x, y) data.

Each feature is a callable (x, y) -> float | ndarray returning a position (or positions) on the axis this locator is attached to. Because a feature such as a peak is a different coordinate on each axis (x[argmax(y)] on the x-axis, y[argmax(y)] on the y-axis), the feature is written for the axis it labels; the locator does not project. This is what a single-axis reduction cannot express, so it lives here rather than in SummaryLocator: the classic Doumont resonance plot labels the peak with FeatureLocator(x, y, [lambda x, y: x[np.argmax(y)]]).

The arrays are captured at construction. The features' results are flattened, non-finite positions dropped, and coincident positions collapsed to a single tick, since a tick cannot show multiplicity. Inputs are not cleaned: a feature over arbitrary (x, y) has no universal non-finite policy, so the feature owns it (use np.nanargmax, or filter the pair first). Tick labels follow the axis formatter; pass a format string such as ax.xaxis.set_major_formatter("{x:.1f}") to round them.

Parameters:

• x (array - like) –

  The plotted coordinates the features read.

• y (array - like) –

  The plotted coordinates the features read.

• features (sequence of callable or number) –

  Callables (x, y) -> float | ndarray giving tick positions on the labelled axis. A plain number (or array) is taken as a fixed position, so a constant baseline can sit beside a computed feature, as in [0, lambda x, y: y.max()].

Raises:

• ValueError –

  If the features yield no finite position.

feature_names: dict[float, tuple[str, ...]]

Bases: FixedLocator

Place ticks at summaries of one axis's own values.

Each reducer is a callable values -> float | ndarray (mean, median, any percentile, a custom statistic). This is the single-axis special case of FeatureLocator: a reducer is a feature that ignores the other axis, so both funnel through the same flatten, drop-non-finite, and collapse-coincident pipeline. Unlike FeatureLocator, the input is cleaned first: non-finite values are dropped before the reducers run. Tick labels follow the axis formatter; pass a format string such as ax.xaxis.set_major_formatter("{x:.1f}") to round them.

Parameters:

• values (array - like) –

  The plotted values whose summaries the ticks mark.

• reducers (sequence of callable or number) –

  Callables values -> float | ndarray giving tick positions. A plain number (or array) is taken as a fixed position.

Raises:

• ValueError –

  If values contains no finite value.

feature_names: dict[float, tuple[str, ...]]

Bases: SummaryLocator

Place ticks at the five-number summary of data.

The SummaryLocator preset whose reducers are the minimum, first quartile, median, third quartile, and maximum, turning a range frame into Tufte's quartile plot. Non-finite values are ignored. Coincident quantiles collapse to a single tick, since a tick cannot show multiplicity. Tick labels follow the axis formatter; pass a format string such as ax.xaxis.set_major_formatter("{x:.1f}") to round them.

Parameters:

• data (array - like) –

  The plotted values whose summary the ticks mark.

Raises:

• ValueError –

  If data contains no finite values.

Bases: Locator

Place ticks at the union of a base locator's ticks and fixed extra ticks.

The base locator is the live side: its ticks are read fresh each draw (a TalbotLocator/LogBreaksLocator/DateBreaksLocator reads the axis data interval), and it alone owns the view limits and singularity handling. extra is the fixed side, any FixedLocator (so FeatureLocator, SummaryLocator, QuartileLocator fit directly) or a bare sequence of positions, wrapped in a FixedLocator. The two tick sets are concatenated, non-finite positions dropped, and coincident positions collapsed to a single tick.

Extra ticks are expected to lie within the view; an out-of-range extra tick is kept as given and behaves like any out-of-range tick. Ticks are not projected across axes: the base and extra are read on the axis this locator is attached to.

Parameters:

• base (Locator) –

  The live locator whose ticks the extra ticks augment; owns the view limits and singularity handling.

• extra (matplotlib.ticker.Locator or sequence of float) –

  Fixed extra tick positions. A FixedLocator (or a FeatureLocator / SummaryLocator / QuartileLocator, which subclass it), or a sequence taken as fixed positions.

extra: Locator

feature_names: dict[float, tuple[str, ...]]

__call__() -> np.ndarray

tick_values(vmin: float, vmax: float) -> np.ndarray

set_axis(axis: Axis) -> None

view_limits(
    vmin: float, vmax: float
) -> tuple[float, float]

nonsingular(
    vmin: float, vmax: float
) -> tuple[float, float]