tikzfigure.core.axis

Classes

Name	Description
Axis2D	A 2-D pgfplots axis environment with one or more plots.

Axis2Dclass#

View source

class Axis2D(xlabel: str = '', ylabel: str = '', xlim: tuple[float, float] | None = None, ylim: tuple[float, float] | None = None, xlog: bool = False, ylog: bool = False, grid: bool | str | None = True, label: str = '', comment: str | None = None, layer: int = 0, width: str | float | None = None, height: str | float | None = None, title: str = '', options: OptionInput | None = None, library_loader: Callable[[str], None] | None = None, spy_scope_enabler: Callable[[], None] | None = None, **kwargs: Any)

Bases: TikzObject

A 2-D pgfplots axis environment with one or more plots.

Manages axis configuration (labels, title, limits, grid, ticks, legend). Renders as \begin{axis}…\end{axis}: the plots, images (:meth:add_graphics) and raw code (:meth:add_raw) in the order they were added, then coordinates and spies.

coordinateattributeclass attributeinstance attribute#

View source

coordinate = add_coordinate

spyattributeclass attributeinstance attribute#

View source

spy = add_spy

extrasproperty#

View source

extras: list[AxisGraphics | RawTikz]

Images and raw code rendered between the plots, in order.

gridproperty#

View source

grid: bool | str | None

Grid setting for pgfplots.

heightproperty#

View source

height: str | None

Return the axis height as a pgfplots-compatible string.

itemsproperty#

View source

items: list[Coordinate | Spy]

List of non-plot commands rendered inside this axis.

plotsproperty#

View source

plots: list[Plot2D]

List of Plot2D objects in this axis.

titleproperty#

View source

title: str

Title above the axis.

widthproperty#

View source

width: str | None

Return the axis width as a pgfplots-compatible string.

xlabelproperty#

View source

xlabel: str

X-axis label.

xlimproperty#

View source

xlim: tuple[float, float] | None

X-axis limits as (min, max) or None.

xlogproperty#

View source

xlog: bool

Whether the x-axis is logarithmic.

ylabelproperty#

View source

ylabel: str

Y-axis label.

ylimproperty#

View source

ylim: tuple[float, float] | None

Y-axis limits as (min, max) or None.

ylogproperty#

View source

ylog: bool

Whether the y-axis is logarithmic.

add_coordinatemethod#

View source

def add_coordinate(label: str, x: CoordinateValue | CoordinateTuple2D | CoordinateTuple3D | TikzCoordinate | None = None, y: CoordinateValue | None = None, z: CoordinateValue | None = None, at: str | None = None, comment: str | None = None) -> Coordinate

Add a named coordinate inside the axis environment.

add_graphicsmethod#

View source

def add_graphics(xmin: float, xmax: float, ymin: float, ymax: float, path: str | None = None, data: bytes | None = None, filename: str | None = None, comment: str | None = None, plot_options: list[str] | None = None, **kwargs: Any) -> AxisGraphics

Place an image in the axis, its edges at the given data coordinates.

Renders as \addplot graphics. Give an existing file as path, or the image bytes as data: the figure then writes them as filename next to the TikZ code when it compiles or saves it (see :meth:TikzFigure.savefig).

Parameters

Name	Type	Default	Description
xmin, xmax, ymin, ymax		required	Data coordinates of the image edges.
path	str | None	None	An existing image file.
data	bytes | None	None	Image bytes, e.g. a PNG.
filename	str | None	None	File name for data; derived from the bytes if omitted.
comment	str | None	None	Optional comment prepended in the TikZ output.
plot_options	list[str] | None	None	Options of the \addplot itself, e.g. ["forget plot"] to leave the image out of the legend.
**kwargs	Any	{}	Further \addplot graphics options.

Returns

AxisGraphics

The new :class:AxisGraphics.

add_plotmethod#

View source

def add_plot(x: list[float] | None = None, y: list[float] | None = None, func: str | None = None, label: str = '', **kwargs: Any) -> Plot2D

Add a plot to this axis.

Parameters

Name	Type	Default	Description
x	list[float] | None	None	List of x values. Mutually exclusive with func.
y	list[float] | None	None	List of y values. Mutually exclusive with func.
func	str | None	None	PGF function string (e.g., “sin(x)”, “x^2”). Mutually exclusive with x/y.
label	str	''	Plot label for legend. Defaults to "".
**kwargs	Any	{}	Keyword-style pgfplots options (e.g., color=“red”).

Returns

Plot2D

The newly created Plot2D object.

Raises

ValueError

If neither (x, y) nor func is provided, or both are provided.

add_rawmethod#

View source

def add_raw(tikz_code: str) -> RawTikz

Insert verbatim code inside the axis, after what was added so far.

Use it for commands that need the axis coordinate system, e.g. \node at (axis cs:1,2) {peak};.

Parameters

Name	Type	Description
tikz_code	str	The code, written as given.

Returns

RawTikz

The new :class:RawTikz.

add_spymethod#

View source

def add_spy(on: Any, *, comment: str | None = None, options: OptionInput | None = None, magnification: float | None = None, lens: OptionInput | str | None = None, lens_kwargs: dict[str, Any] | None = None, size: str | object | None = None, width: str | object | None = None, height: str | object | None = None, connect_spies: bool = False, at: Any = None, node_label: str | None = None, node_options: OptionInput | None = None, node_style: dict[str, Any] | None = None, **kwargs: Any) -> Spy

Add a \spy command inside the axis environment.

axis_optionsmethod#

View source

def axis_options(output_unit: str | None = None) -> list[str]

The options of the axis environment, as a list.

filesmethod#

View source

def files() -> dict[str, bytes]

The image files this axis needs written next to its TikZ code.

from_dictmethodclassmethod#

View source

def from_dict(d: dict[str, Any]) -> Axis2D

Reconstruct an Axis2D from a dictionary.

Parameters

Name	Type	Description
d	dict[str, Any]	Dictionary as produced by to_dict().

Returns

Axis2D

A new Axis2D instance.

set_gridmethod#

View source

def set_grid(enabled: bool | str | None) -> None

Set the pgfplots grid mode.

Parameters

Name	Type	Description
enabled	bool | str | None	True / False, a pgfplots grid mode string such as "major" or "both", or None for no grid option.

set_legendmethod#

View source

def set_legend(position: str | None = 'north east', *, at: tuple[float, float] | None = None, anchor: str | None = None, columns: int | None = None, style: str | list[str] | None = None) -> None

Configure legend.

Plots with a label get a legend entry; plots without one are left out of the legend (forget plot).

Parameters

Name	Type	Default	Description
position	str | None	'north east'	Legend position (e.g., “north east”, “north west”, “south east”, “south west”, “outer north east”). Ignored when at is given.
at	tuple[float, float] | None	None	The legend’s position in axis description coordinates, (0, 0) the lower left and (1, 1) the upper right corner of the axis, instead of position.
anchor	str | None	None	The point of the legend placed at at, e.g. “south west”. Defaults to “north east”.
columns	int | None	None	The number of legend columns.
style	str | list[str] | None	None	Further legend style options, e.g. ["draw=none"] or "font=\small".

set_ticksmethod#

View source

def set_ticks(axis: str, positions: list[float], labels: list[str] | None = None) -> None

Configure ticks for an axis.

Parameters

Name	Type	Default	Description
axis	str	required	“x” or “y”.
positions	list[float]	required	List of tick positions (must be non-empty).
labels	list[str] | None	None	Optional list of tick labels. If provided, must match positions length. If None, positions are used as labels.

Raises

ValueError

If axis is not “x” or “y”, if positions is empty, or if labels length doesn’t match positions length.

set_titlemethod#

View source

def set_title(title: str) -> None

Set the title above the axis.

Parameters

Name	Type	Description
title	str	The title text.

set_xlabelmethod#

View source

def set_xlabel(label: str) -> None

Set x-axis label.

Parameters

Name	Type	Description
label	str	The label text.

set_xlimmethod#

View source

def set_xlim(min_val: float, max_val: float) -> None

Set x-axis limits.

Parameters

Name	Type	Description
min_val	float	Minimum x value.
max_val	float	Maximum x value.

Raises

TypeError

If values are not numeric.

set_xlogmethod#

View source

def set_xlog(enabled: bool) -> None

Enable or disable logarithmic scaling on x-axis.

set_ylabelmethod#

View source

def set_ylabel(label: str) -> None

Set y-axis label.

Parameters

Name	Type	Description
label	str	The label text.

set_ylimmethod#

View source

def set_ylim(min_val: float, max_val: float) -> None

Set y-axis limits.

Parameters

Name	Type	Description
min_val	float	Minimum y value.
max_val	float	Maximum y value.

Raises

TypeError

If values are not numeric.

set_ylogmethod#

View source

def set_ylog(enabled: bool) -> None

Enable or disable logarithmic scaling on y-axis.

to_dictmethod#

View source

def to_dict() -> dict[str, Any]

Serialize this axis to a plain dictionary.

Returns

dict[str, Any]

A dictionary with all axis state and plots.

to_tikzmethod#

View source

def to_tikz(output_unit: str | None = None) -> str

Generate the pgfplots axis environment.

Returns

str

A complete \begin{axis}…\end{axis} block with all plots.

Inherited from tikzfigure.core.base.TikzObject

commentproperty#

Inherited from tikzfigure.core.base.TikzObjectView source

comment: str | None

Comment prepended to the generated TikZ code, or None.

kwargsproperty#

Inherited from tikzfigure.core.base.TikzObjectView source

kwargs: dict

Keyword-style TikZ options as a plain dict.

labelproperty#

Inherited from tikzfigure.core.base.TikzObjectView source

label: str | None

Unique identifier for this object within the figure.

layerproperty#

Inherited from tikzfigure.core.base.TikzObjectView source

layer: int | None

Layer index this object belongs to.

optionsproperty#

Inherited from tikzfigure.core.base.TikzObjectView source

options: list[OptionValue]

Flag-style TikZ options without values.

add_commentmethod#

Inherited from tikzfigure.core.base.TikzObjectView source

def add_comment(string_in: str) -> str

Prepend a TikZ comment line to a string if a comment is set.

Parameters

Name	Type	Description
string_in	str	The TikZ code string to annotate.

Returns

str

The original string prefixed with % <comment>\n when a

str

comment is set, otherwise the string unchanged.

copymethod#

Inherited from tikzfigure.core.base.TikzObjectView source

def copy(**overrides: Any) -> TikzObject

Return a copy of this object with optional constructor-style overrides.

tikz_optionsmethod#

Inherited from tikzfigure.core.base.TikzObjectView source

def tikz_options(output_unit: str | None = None) -> str

Render all options as a single TikZ option string.

Combines flag-style options and keyword options into the format expected inside TikZ square brackets, e.g. "thick, color=red, line width=1pt".

Parameters

Name	Type	Default	Description
output_unit	str | None	None	If provided, any :class:~tikzfigure.units.TikzDimension values are converted to this unit before rendering.

Returns

str

A comma-separated string of TikZ options.