Skip to content

himena.standards.plotting

Standard plotting models.

Axes

Layout model for 2D axes.

Parameters:

Name Type Description Default
models list[BasePlotModel]

Child plot models.

 <dynamic>
title str | StyledText | None

Title of the axes.

 None
x Axis

X-axis settings.

 <dynamic>
y Axis

Y-axis settings.

 <dynamic>
axis_color str

Axis color.

 '#000000'
Source code in src\himena\standards\plotting\layout.py 
221
222
223
224
225
226
class Axes(AxesBase, ModelsRef):
    """Layout model for 2D axes."""

    x: Axis = Field(default_factory=Axis, description="X-axis settings.")
    y: Axis = Field(default_factory=Axis, description="Y-axis settings.")
    axis_color: str = Field("#000000", description="Axis color.")

Axes3D

Layout model for 3D axes.

Parameters:

Name Type Description Default
models list[BasePlotModel]

Child plot models.

 <dynamic>
title str | StyledText | None

Title of the axes.

 None
x Axis

X-axis settings.

 <dynamic>
y Axis

Y-axis settings.

 <dynamic>
z Axis

Z-axis settings.

 <dynamic>
Source code in src\himena\standards\plotting\layout3d.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
class Axes3D(AxesBase):
    """Layout model for 3D axes."""

    x: Axis = Field(default_factory=Axis, description="X-axis settings.")
    y: Axis = Field(default_factory=Axis, description="Y-axis settings.")
    z: Axis = Field(default_factory=Axis, description="Z-axis settings.")

    def scatter(
        self,
        x: Sequence[float],
        y: Sequence[float],
        z: Sequence[float],
        *,
        symbol: str = "o",
        size: float | None = None,
        **kwargs,
    ) -> _m3d.Scatter3D:
        """Create a 3D scatter plot."""
        model = _m3d.Scatter3D(
            x=x, y=y, z=z, symbol=symbol, size=size, **parse_face_edge(kwargs)
        )
        self.models.append(model)
        return model

    def plot(
        self,
        x: Sequence[float],
        y: Sequence[float],
        z: Sequence[float],
        **kwargs,
    ) -> _m3d.Line3D:
        """Create a 3D line plot."""
        model = _m3d.Line3D(x=x, y=y, z=z, **parse_edge(kwargs))
        self.models.append(model)
        return model

    def surface(
        self,
        x: "NDArray[np.number]",
        y: "NDArray[np.number]",
        z: "NDArray[np.number]",
        **kwargs,
    ) -> _m3d.Surface3D:
        """Create a 3D surface plot."""
        model = _m3d.Surface3D(x=x, y=y, z=z, **parse_face_edge(kwargs))
        self.models.append(model)
        return model

    def mesh(
        self,
        vertices: "NDArray[np.number]",
        face_indices: "NDArray[np.number]",
        **kwargs,
    ) -> _m3d.Mesh3D:
        """Create a 3D mesh plot."""
        model = _m3d.Mesh3D(
            vertices=vertices, face_indices=face_indices, **parse_face_edge(kwargs)
        )
        self.models.append(model)
        return model
mesh(vertices, face_indices, **kwargs)

Create a 3D mesh plot.

Source code in src\himena\standards\plotting\layout3d.py 
66
67
68
69
70
71
72
73
74
75
76
77
def mesh(
    self,
    vertices: "NDArray[np.number]",
    face_indices: "NDArray[np.number]",
    **kwargs,
) -> _m3d.Mesh3D:
    """Create a 3D mesh plot."""
    model = _m3d.Mesh3D(
        vertices=vertices, face_indices=face_indices, **parse_face_edge(kwargs)
    )
    self.models.append(model)
    return model
plot(x, y, z, **kwargs)

Create a 3D line plot.

Source code in src\himena\standards\plotting\layout3d.py 
42
43
44
45
46
47
48
49
50
51
52
def plot(
    self,
    x: Sequence[float],
    y: Sequence[float],
    z: Sequence[float],
    **kwargs,
) -> _m3d.Line3D:
    """Create a 3D line plot."""
    model = _m3d.Line3D(x=x, y=y, z=z, **parse_edge(kwargs))
    self.models.append(model)
    return model
scatter(x, y, z, *, symbol='o', size=None, **kwargs)

Create a 3D scatter plot.

Source code in src\himena\standards\plotting\layout3d.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
def scatter(
    self,
    x: Sequence[float],
    y: Sequence[float],
    z: Sequence[float],
    *,
    symbol: str = "o",
    size: float | None = None,
    **kwargs,
) -> _m3d.Scatter3D:
    """Create a 3D scatter plot."""
    model = _m3d.Scatter3D(
        x=x, y=y, z=z, symbol=symbol, size=size, **parse_face_edge(kwargs)
    )
    self.models.append(model)
    return model
surface(x, y, z, **kwargs)

Create a 3D surface plot.

Source code in src\himena\standards\plotting\layout3d.py 
54
55
56
57
58
59
60
61
62
63
64
def surface(
    self,
    x: "NDArray[np.number]",
    y: "NDArray[np.number]",
    z: "NDArray[np.number]",
    **kwargs,
) -> _m3d.Surface3D:
    """Create a 3D surface plot."""
    model = _m3d.Surface3D(x=x, y=y, z=z, **parse_face_edge(kwargs))
    self.models.append(model)
    return model

Axis

Model that represents a plot axis.

Parameters:

Name Type Description Default
lim tuple[float, float] | None

Axis limits.

 None
scale Literal[str, str]

Axis scale.

 'linear'
label str | StyledText | None

Axis label.

 None
ticks Any | None

Axis ticks.

 None
grid bool

Show grid or not.

 False
Source code in src\himena\standards\plotting\components.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
class Axis(BaseModel):
    """Model that represents a plot axis."""

    model_config = PYDANTIC_CONFIG_STRICT

    lim: tuple[float, float] | None = Field(None, description="Axis limits.")
    scale: Literal["linear", "log"] = Field("linear", description="Axis scale.")
    label: str | StyledText | None = Field(None, description="Axis label.")
    ticks: Any | None = Field(None, description="Axis ticks.")
    grid: bool = Field(False, description="Show grid or not.")

    @field_validator("lim", mode="before")
    def _validate_lim(cls, lim) -> tuple[float, float] | None:
        if lim is None:
            return None
        _lim = tuple(lim)
        if len(_lim) != 2:
            raise ValueError(f"Must be a tuple of 2 floats but got: {lim!r}")
        return _lim

Band

Plot model for band plot.

Parameters:

Name Type Description Default
name str

Name of the plot.

 ''
x Any

X-axis values.

 required
y0 Any

Y-axis values of the lower bound.

 required
y1 Any

Y-axis values of the upper bound.

 required
orient Literal[str, str]

Orientation of the band fill.

 'vertical'
face Face

Properties of the band fill.

 <dynamic>
edge Edge

Properties of the band edge.

 <dynamic>
Source code in src\himena\standards\plotting\models.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
class Band(BasePlotModel):
    """Plot model for band plot."""

    x: Any = Field(..., description="X-axis values.")
    y0: Any = Field(..., description="Y-axis values of the lower bound.")
    y1: Any = Field(..., description="Y-axis values of the upper bound.")
    orient: Literal["vertical", "horizontal"] = Field(
        "vertical", description="Orientation of the band fill."
    )
    face: Face = Field(default_factory=Face, description="Properties of the band fill.")
    edge: Edge = Field(default_factory=Edge, description="Properties of the band edge.")

    def plot_option_dict(self) -> dict[str, Any]:
        from himena.qt.magicgui import EdgePropertyEdit, FacePropertyEdit

        return {
            "name": {"widget_type": "LineEdit", "value": self.name},
            "orient": {"choices": ["vertical", "horizontal"], "value": self.orient},
            "face": {"widget_type": FacePropertyEdit, "value": self.face.model_dump()},
            "edge": {"widget_type": EdgePropertyEdit, "value": self.edge.model_dump()},
        }

Bar

Plot model for bar plot.

Parameters:

Name Type Description Default
name str

Name of the plot.

 ''
x Any

X-axis values.

 required
y Any

Y-axis values.

 required
bottom float | Any

Bottom values of the bars.

 0
bar_width float | None

Width of the bars.

 None
orient Literal[str, str]

Orientation of the bar plots.

 'vertical'
face Face

Properties of the bars.

 <dynamic>
edge Edge

Properties of the bars.

 <dynamic>
Source code in src\himena\standards\plotting\models.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
class Bar(PlotModelXY):
    """Plot model for bar plot."""

    bottom: float | Any = Field(0, description="Bottom values of the bars.")
    bar_width: float | None = Field(None, description="Width of the bars.")
    orient: Literal["vertical", "horizontal"] = Field(
        "vertical", description="Orientation of the bar plots."
    )
    face: Face = Field(default_factory=Face, description="Properties of the bars.")
    edge: Edge = Field(default_factory=Edge, description="Properties of the bars.")

    def plot_option_dict(self) -> dict[str, Any]:
        from himena.qt.magicgui import EdgePropertyEdit, FacePropertyEdit

        return {
            "name": {"widget_type": "LineEdit", "value": self.name},
            "bar_width": {"annotation": float, "value": self.bar_width},
            "orient": {"choices": ["vertical", "horizontal"], "value": self.orient},
            "face": {"widget_type": FacePropertyEdit, "value": self.face.model_dump()},
            "edge": {"widget_type": EdgePropertyEdit, "value": self.edge.model_dump()},
        }

BaseLayoutModel

Parameters:

Name Type Description Default
hpad float | None

Horizontal padding.

 None
vpad float | None

Vertical padding.

 None
hspace float | None

Horizontal space.

 None
vspace float | None

Vertical space.

 None
background_color str

Background color.

 '#FFFFFF'
Source code in src\himena\standards\plotting\layout.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
class BaseLayoutModel(BaseModel):
    model_config = PYDANTIC_CONFIG_STRICT
    model_type: ClassVar[str] = StandardType.PLOT

    hpad: float | None = Field(None, description="Horizontal padding.")
    vpad: float | None = Field(None, description="Vertical padding.")
    hspace: float | None = Field(None, description="Horizontal space.")
    vspace: float | None = Field(None, description="Vertical space.")
    background_color: str = Field("#FFFFFF", description="Background color.")

    def merge_with(self, other: "BaseLayoutModel") -> "BaseLayoutModel":
        raise NotImplementedError

    def model_dump_typed(self) -> dict:
        return {"type": type(self).__name__.lower(), **self.model_dump()}

    @classmethod
    def construct(self, model_type: str, dict_: dict) -> "BaseLayoutModel":
        from himena.standards.plotting.layout3d import SingleAxes3D

        if model_type == "singleaxes":
            return SingleAxes.model_validate(dict_)
        if model_type == "row":
            return Row.model_validate(dict_)
        if model_type == "column":
            return Column.model_validate(dict_)
        if model_type == "grid":
            return Grid.model_validate(dict_)
        if model_type == "singleaxes3d":
            return SingleAxes3D.model_validate(dict_)
        raise ValueError(f"Unknown layout model type: {model_type!r}")

    def show(self) -> None:
        """Show the layout in the current himena window."""
        from himena.widgets import current_instance

        ui = current_instance()
        ui.add_object(self, type=self.__class__.model_type, title="Plot")
        return None
show()

Show the layout in the current himena window.

Source code in src\himena\standards\plotting\layout.py 
52
53
54
55
56
57
58
def show(self) -> None:
    """Show the layout in the current himena window."""
    from himena.widgets import current_instance

    ui = current_instance()
    ui.add_object(self, type=self.__class__.model_type, title="Plot")
    return None

BasePlotModel

Parameters:

Name Type Description Default
name str

Name of the plot.

 ''
Source code in src\himena\standards\plotting\components.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
class BasePlotModel(BaseModel):
    model_config = PYDANTIC_CONFIG_STRICT
    name: str = Field(default="", description="Name of the plot.")

    @classmethod
    def construct(cls, type: str, dict_: dict[str, Any]) -> "BasePlotModel":
        for subclass in iter_subclasses(BasePlotModel):
            if subclass.__name__.lower() == type:
                return subclass(**dict_)
        raise ValueError(f"Unknown plot type: {type!r}")

    @field_validator("name", mode="before")
    def _validate_name(cls, name: str) -> str:
        if name is None:
            return ""
        return name

    def model_dump_typed(self) -> dict[str, Any]:
        return {"type": type(self).__name__.lower(), **self.model_dump()}

    def plot_option_dict(self) -> dict[str, Any]:
        """Return the GUI option dict for this plot for editing."""
        return {"name": {"widget_type": "LineEdit", "value": self.name}}
plot_option_dict()

Return the GUI option dict for this plot for editing.

Source code in src\himena\standards\plotting\components.py 
44
45
46
def plot_option_dict(self) -> dict[str, Any]:
    """Return the GUI option dict for this plot for editing."""
    return {"name": {"widget_type": "LineEdit", "value": self.name}}

Column

Layout model for column.

Parameters:

Name Type Description Default
hpad float | None

Horizontal padding.

 None
vpad float | None

Vertical padding.

 None
hspace float | None

Horizontal space.

 None
vspace float | None

Vertical space.

 None
background_color str

Background color.

 '#FFFFFF'
axes list[Axes]

Child layouts.

 <dynamic>
share_x bool

Share x-axis or not.

 False
share_y bool

Share y-axis or not.

 False
Source code in src\himena\standards\plotting\layout.py 
473
474
class Column(Layout1D):
    """Layout model for column."""

ErrorBar

Plot model for error bar plot.

Parameters:

Name Type Description Default
name str

Name of the plot.

 ''
x Any

X-axis values.

 required
y Any

Y-axis values.

 required
x_error Any | None

X-axis error values.

 None
y_error Any | None

Y-axis error values.

 None
capsize float | None

Cap size of the error bars.

 None
edge Edge

Properties of the error bars.

 <dynamic>
Source code in src\himena\standards\plotting\models.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
class ErrorBar(PlotModelXY):
    """Plot model for error bar plot."""

    x_error: Any | None = Field(None, description="X-axis error values.")
    y_error: Any | None = Field(None, description="Y-axis error values.")
    capsize: float | None = Field(None, description="Cap size of the error bars.")
    edge: Edge = Field(
        default_factory=Edge, description="Properties of the error bars."
    )

    def plot_option_dict(self) -> dict[str, Any]:
        from himena.qt.magicgui import EdgePropertyEdit

        return {
            "name": {"widget_type": "LineEdit", "value": self.name},
            "capsize": {"annotation": float, "value": self.capsize},
            "edge": {"widget_type": EdgePropertyEdit, "value": self.edge.model_dump()},
        }

Grid

Layout model for grid.

Parameters:

Name Type Description Default
hpad float | None

Horizontal padding.

 None
vpad float | None

Vertical padding.

 None
hspace float | None

Horizontal space.

 None
vspace float | None

Vertical space.

 None
background_color str

Background color.

 '#FFFFFF'
axes list[list[Axes]]

Child layouts.

 <dynamic>
Source code in src\himena\standards\plotting\layout.py 
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
class Grid(BaseLayoutModel):
    """Layout model for grid."""

    axes: list[list[Axes]] = Field(default_factory=list, description="Child layouts.")

    def __getitem__(self, key) -> Axes:
        return self.axes[key[0]][key[1]]

    @classmethod
    def fill(cls, rows: int, cols: int) -> "Self":
        layout = cls()
        for _ in range(rows):
            layout.axes.append([Axes() for _ in range(cols)])
        return layout

    def merge_with(self, other: "Self") -> "Self":
        if not isinstance(other, type(self)):
            raise ValueError(f"Cannot merge {type(self)} with {type(other)}")
        new_axes = [
            [
                a.model_copy(update={"models": a.models + b.models})
                for a, b in zip(row_a, row_b)
            ]
            for row_a, row_b in zip(self.axes, other.axes)
        ]
        return type(self)(axes=new_axes)

Histogram

Plot model for a histogram.

Parameters:

Name Type Description Default
name str

Name of the plot.

 ''
height Any

Count or frequency values.

 required
bins Any

Bin edges.

 required
orient Literal[str, str]

Orientation of the histogram.

 'vertical'
face Face

Properties of the histogram face.

 <dynamic>
edge Edge

Properties of the histogram edge.

 <dynamic>
Source code in src\himena\standards\plotting\models.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
class Histogram(BasePlotModel):
    """Plot model for a histogram."""

    height: Any = Field(..., description="Count or frequency values.")
    bins: Any = Field(..., description="Bin edges.")
    orient: Literal["vertical", "horizontal"] = Field(
        "vertical", description="Orientation of the histogram."
    )
    face: Face = Field(
        default_factory=Face, description="Properties of the histogram face."
    )
    edge: Edge = Field(
        default_factory=Edge, description="Properties of the histogram edge."
    )

    def plot_option_dict(self) -> dict[str, Any]:
        from himena.qt.magicgui import EdgePropertyEdit, FacePropertyEdit

        return {
            "name": {"widget_type": "LineEdit", "value": self.name},
            "orient": {"choices": ["vertical", "horizontal"], "value": self.orient},
            "face": {"widget_type": FacePropertyEdit, "value": self.face.model_dump()},
            "edge": {"widget_type": EdgePropertyEdit, "value": self.edge.model_dump()},
        }

    def to_band(self) -> Band:
        """Convert the histogram to a band plot."""
        x = np.repeat(self.bins, 3)[1:-1]
        y = np.zeros_like(x)
        y[1::3] = self.height
        y[2::3] = self.height
        return Band(
            x=x,
            y0=y,
            y1=np.zeros_like(y),
            orient=self.orient,
            face=self.face,
            edge=self.edge,
        )
to_band()

Convert the histogram to a band plot.

Source code in src\himena\standards\plotting\models.py 
170
171
172
173
174
175
176
177
178
179
180
181
182
183
def to_band(self) -> Band:
    """Convert the histogram to a band plot."""
    x = np.repeat(self.bins, 3)[1:-1]
    y = np.zeros_like(x)
    y[1::3] = self.height
    y[2::3] = self.height
    return Band(
        x=x,
        y0=y,
        y1=np.zeros_like(y),
        orient=self.orient,
        face=self.face,
        edge=self.edge,
    )

Line

Plot model for line plot.

Parameters:

Name Type Description Default
name str

Name of the plot.

 ''
x Any

X-axis values.

 required
y Any

Y-axis values.

 required
edge Edge

Properties of the line.

 <dynamic>
marker Scatter | None

Marker of the line.

 None
Source code in src\himena\standards\plotting\models.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
class Line(PlotModelXY):
    """Plot model for line plot."""

    edge: Edge = Field(default_factory=Edge, description="Properties of the line.")
    marker: Scatter | None = Field(None, description="Marker of the line.")

    def plot_option_dict(self) -> dict[str, Any]:
        from himena.qt.magicgui import EdgePropertyEdit

        return {
            "name": {"widget_type": "LineEdit", "value": self.name},
            "edge": {"widget_type": EdgePropertyEdit, "value": self.edge.model_dump()},
        }

Line3D

Plot model for a 3D line plot.

Parameters:

Name Type Description Default
name str

Name of the plot.

 ''
x Any

X-axis values.

 required
y Any

Y-axis values.

 required
edge Edge

Properties of the line.

 <dynamic>
marker Scatter | None

Marker of the line.

 None
z Any

Z-axis values.

 required
Source code in src\himena\standards\plotting\models3d.py 
15
16
17
18
class Line3D(_m.Line):
    """Plot model for a 3D line plot."""

    z: Any = Field(..., description="Z-axis values.")

Mesh3D

Plot model for a 3D mesh plot.

Parameters:

Name Type Description Default
name str

Name of the plot.

 ''
vertices Any

Vertices of the mesh.

 required
face_indices Any

Face indices of the mesh.

 required
face Face

Properties of the faces.

 <dynamic>
edge Edge

Properties of the edges.

 <dynamic>
Source code in src\himena\standards\plotting\models3d.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
class Mesh3D(BasePlotModel):
    """Plot model for a 3D mesh plot."""

    vertices: Any = Field(..., description="Vertices of the mesh.")
    face_indices: Any = Field(..., description="Face indices of the mesh.")
    face: Face = Field(default_factory=Face, description="Properties of the faces.")
    edge: Edge = Field(default_factory=Edge, description="Properties of the edges.")

    def plot_option_dict(self) -> dict[str, Any]:
        from himena.qt.magicgui import EdgePropertyEdit, FacePropertyEdit

        return {
            "name": {"widget_type": "LineEdit", "value": self.name},
            "face": {"widget_type": FacePropertyEdit, "value": self.face.model_dump()},
            "edge": {"widget_type": EdgePropertyEdit, "value": self.edge.model_dump()},
        }

Row

Layout model for row.

Parameters:

Name Type Description Default
hpad float | None

Horizontal padding.

 None
vpad float | None

Vertical padding.

 None
hspace float | None

Horizontal space.

 None
vspace float | None

Vertical space.

 None
background_color str

Background color.

 '#FFFFFF'
axes list[Axes]

Child layouts.

 <dynamic>
share_x bool

Share x-axis or not.

 False
share_y bool

Share y-axis or not.

 False
Source code in src\himena\standards\plotting\layout.py 
469
470
class Row(Layout1D):
    """Layout model for row."""

Scatter

Plot model for scatter plot.

Parameters:

Name Type Description Default
name str

Name of the plot.

 ''
x Any

X-axis values.

 required
y Any

Y-axis values.

 required
symbol Any | None

Symbol of the markers.

 None
size Any | None

Size of the markers.

 None
face Face

Properties of the marker faces.

 <dynamic>
edge Edge

Properties of the marker edges.

 <dynamic>
Source code in src\himena\standards\plotting\models.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
class Scatter(PlotModelXY):
    """Plot model for scatter plot."""

    symbol: Any | None = Field(None, description="Symbol of the markers.")
    size: Any | None = Field(None, description="Size of the markers.")
    face: Face = Field(
        default_factory=Face, description="Properties of the marker faces."
    )
    edge: Edge = Field(
        default_factory=Edge, description="Properties of the marker edges."
    )

    def plot_option_dict(self) -> dict[str, Any]:
        from himena.qt.magicgui import EdgePropertyEdit, FacePropertyEdit

        return {
            "name": {"widget_type": "LineEdit", "value": self.name},
            "symbol": {"widget_type": "LineEdit", "value": self.symbol},
            "size": {"annotation": float, "value": self.size},
            "face": {"widget_type": FacePropertyEdit, "value": self.face.model_dump()},
            "edge": {"widget_type": EdgePropertyEdit, "value": self.edge.model_dump()},
        }

Scatter3D

Plot model for a 3D scatter plot.

Parameters:

Name Type Description Default
name str

Name of the plot.

 ''
x Any

X-axis values.

 required
y Any

Y-axis values.

 required
symbol Any | None

Symbol of the markers.

 None
size Any | None

Size of the markers.

 None
face Face

Properties of the marker faces.

 <dynamic>
edge Edge

Properties of the marker edges.

 <dynamic>
z Any

Z-axis values.

 required
Source code in src\himena\standards\plotting\models3d.py 
 9
10
11
12
class Scatter3D(_m.Scatter):
    """Plot model for a 3D scatter plot."""

    z: Any = Field(..., description="Z-axis values.")

SingleAxes

Parameters:

Name Type Description Default
hpad float | None

Horizontal padding.

 None
vpad float | None

Vertical padding.

 None
hspace float | None

Horizontal space.

 None
vspace float | None

Vertical space.

 None
background_color str

Background color.

 '#FFFFFF'
axes Axes

Child axes.

 <dynamic>
Source code in src\himena\standards\plotting\layout.py 
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
class SingleAxes(BaseLayoutModel):
    axes: Axes = Field(default_factory=Axes, description="Child axes.")

    @property
    def x(self) -> Axis:
        """X-axis settings."""
        return self.axes.x

    @property
    def y(self) -> Axis:
        """Y-axis settings."""
        return self.axes.y

    @property
    def axis_color(self) -> str:
        """Axis color."""
        return self.axes.axis_color

    @axis_color.setter
    def axis_color(self, value):
        self.axes.axis_color = value

    @property
    def title(self) -> str:
        """Title of the central axes."""
        return self.axes.title

    @title.setter
    def title(self, value):
        self.axes.title = value

    def merge_with(self, other: "SingleAxes") -> "SingleAxes":
        """Merge with another SingleAxes layout."""
        new_axes = self.axes.model_copy(
            update={"models": self.axes.models + other.axes.models}
        )
        return SingleAxes(axes=new_axes)

    ### Because there's only one axes, we can directly call the axes methods.
    def scatter(
        self,
        x: Sequence[float],
        y: Sequence[float] | None = None,
        *,
        symbol: str = "o",
        size: float | None = None,
        **kwargs,
    ) -> _m.Scatter:
        """Add a scatter plot model to the axes."""
        return self.axes.scatter(x=x, y=y, symbol=symbol, size=size, **kwargs)

    def plot(
        self,
        x: Sequence[float],
        y: Sequence[float] | None = None,
        **kwargs,
    ) -> _m.Line:
        """Add a line plot model to the axes."""
        return self.axes.plot(x=x, y=y, **kwargs)

    def bar(
        self,
        x: Sequence[float],
        y: Sequence[float] | None = None,
        *,
        bottom: "float | Sequence[float] | NDArray[np.number] | None" = None,
        bar_width: float | None = None,
        orient: Literal["vertical", "horizontal"] = "vertical",
        **kwargs,
    ) -> _m.Bar:
        """Add a bar plot model to the axes."""
        return self.axes.bar(
            x=x, y=y, bottom=bottom, bar_width=bar_width, orient=orient, **kwargs
        )

    def errorbar(
        self,
        x: Sequence[float],
        y: Sequence[float] | None = None,
        *,
        x_error: "float | Sequence[float] | NDArray[np.number] | None" = None,
        y_error: "float | Sequence[float] | NDArray[np.number] | None" = None,
        capsize: float | None = None,
        **kwargs,
    ) -> _m.ErrorBar:
        """Add an error bar plot model to the axes."""
        return self.axes.errorbar(
            x=x, y=y, x_error=x_error, y_error=y_error, capsize=capsize, **kwargs
        )

    def band(
        self,
        x: Sequence[float],
        y0: Sequence[float],
        y1: Sequence[float] | None = None,
        *,
        orient: Literal["vertical", "horizontal"] = "vertical",
        **kwargs,
    ) -> _m.Band:
        """Add a band plot model to the axes."""
        return self.axes.band(x=x, y0=y0, y1=y1, orient=orient, **kwargs)

    def hist(
        self,
        data: "Sequence[float] | NDArray[np.number]",
        *,
        bins: int = 10,
        range: tuple[float, float] | None = None,
        orient: Literal["vertical", "horizontal"] = "vertical",
        stat: Literal["count", "density", "probability"] = "count",
        **kwargs,
    ) -> _m.Histogram:
        """Add a histogram plot model to the axes."""
        return self.axes.hist(
            data=data, bins=bins, range=range, orient=orient, stat=stat, **kwargs
        )

    def text(
        self,
        x: Sequence[float],
        y: Sequence[float],
        text: Sequence[str],
        *,
        size: int = 12,
        color: str = "black",
        family: str = "Arial",
        rotation: float = 0,
        anchor: _m.ANCHOR_STRINGS = "center",
    ) -> _m.Texts:
        """Add a text plot model to the axes."""
        return self.axes.text(
            x=x, y=y, text=text, size=size, color=color, family=family, anchor=anchor,
            rotation=rotation,
        )  # fmt: skip
axis_color property writable

Axis color.

title property writable

Title of the central axes.

x property

X-axis settings.

y property

Y-axis settings.

band(x, y0, y1=None, *, orient='vertical', **kwargs)

Add a band plot model to the axes.

Source code in src\himena\standards\plotting\layout.py 
319
320
321
322
323
324
325
326
327
328
329
def band(
    self,
    x: Sequence[float],
    y0: Sequence[float],
    y1: Sequence[float] | None = None,
    *,
    orient: Literal["vertical", "horizontal"] = "vertical",
    **kwargs,
) -> _m.Band:
    """Add a band plot model to the axes."""
    return self.axes.band(x=x, y0=y0, y1=y1, orient=orient, **kwargs)
bar(x, y=None, *, bottom=None, bar_width=None, orient='vertical', **kwargs)

Add a bar plot model to the axes.

Source code in src\himena\standards\plotting\layout.py 
289
290
291
292
293
294
295
296
297
298
299
300
301
302
def bar(
    self,
    x: Sequence[float],
    y: Sequence[float] | None = None,
    *,
    bottom: "float | Sequence[float] | NDArray[np.number] | None" = None,
    bar_width: float | None = None,
    orient: Literal["vertical", "horizontal"] = "vertical",
    **kwargs,
) -> _m.Bar:
    """Add a bar plot model to the axes."""
    return self.axes.bar(
        x=x, y=y, bottom=bottom, bar_width=bar_width, orient=orient, **kwargs
    )
errorbar(x, y=None, *, x_error=None, y_error=None, capsize=None, **kwargs)

Add an error bar plot model to the axes.

Source code in src\himena\standards\plotting\layout.py 
304
305
306
307
308
309
310
311
312
313
314
315
316
317
def errorbar(
    self,
    x: Sequence[float],
    y: Sequence[float] | None = None,
    *,
    x_error: "float | Sequence[float] | NDArray[np.number] | None" = None,
    y_error: "float | Sequence[float] | NDArray[np.number] | None" = None,
    capsize: float | None = None,
    **kwargs,
) -> _m.ErrorBar:
    """Add an error bar plot model to the axes."""
    return self.axes.errorbar(
        x=x, y=y, x_error=x_error, y_error=y_error, capsize=capsize, **kwargs
    )
hist(data, *, bins=10, range=None, orient='vertical', stat='count', **kwargs)

Add a histogram plot model to the axes.

Source code in src\himena\standards\plotting\layout.py 
331
332
333
334
335
336
337
338
339
340
341
342
343
344
def hist(
    self,
    data: "Sequence[float] | NDArray[np.number]",
    *,
    bins: int = 10,
    range: tuple[float, float] | None = None,
    orient: Literal["vertical", "horizontal"] = "vertical",
    stat: Literal["count", "density", "probability"] = "count",
    **kwargs,
) -> _m.Histogram:
    """Add a histogram plot model to the axes."""
    return self.axes.hist(
        data=data, bins=bins, range=range, orient=orient, stat=stat, **kwargs
    )
merge_with(other)

Merge with another SingleAxes layout.

Source code in src\himena\standards\plotting\layout.py 
260
261
262
263
264
265
def merge_with(self, other: "SingleAxes") -> "SingleAxes":
    """Merge with another SingleAxes layout."""
    new_axes = self.axes.model_copy(
        update={"models": self.axes.models + other.axes.models}
    )
    return SingleAxes(axes=new_axes)
plot(x, y=None, **kwargs)

Add a line plot model to the axes.

Source code in src\himena\standards\plotting\layout.py 
280
281
282
283
284
285
286
287
def plot(
    self,
    x: Sequence[float],
    y: Sequence[float] | None = None,
    **kwargs,
) -> _m.Line:
    """Add a line plot model to the axes."""
    return self.axes.plot(x=x, y=y, **kwargs)
scatter(x, y=None, *, symbol='o', size=None, **kwargs)

Add a scatter plot model to the axes.

Source code in src\himena\standards\plotting\layout.py 
268
269
270
271
272
273
274
275
276
277
278
def scatter(
    self,
    x: Sequence[float],
    y: Sequence[float] | None = None,
    *,
    symbol: str = "o",
    size: float | None = None,
    **kwargs,
) -> _m.Scatter:
    """Add a scatter plot model to the axes."""
    return self.axes.scatter(x=x, y=y, symbol=symbol, size=size, **kwargs)
text(x, y, text, *, size=12, color='black', family='Arial', rotation=0, anchor='center')

Add a text plot model to the axes.

Source code in src\himena\standards\plotting\layout.py 
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
def text(
    self,
    x: Sequence[float],
    y: Sequence[float],
    text: Sequence[str],
    *,
    size: int = 12,
    color: str = "black",
    family: str = "Arial",
    rotation: float = 0,
    anchor: _m.ANCHOR_STRINGS = "center",
) -> _m.Texts:
    """Add a text plot model to the axes."""
    return self.axes.text(
        x=x, y=y, text=text, size=size, color=color, family=family, anchor=anchor,
        rotation=rotation,
    )  # fmt: skip

SingleAxes3D

Parameters:

Name Type Description Default
hpad float | None

Horizontal padding.

 None
vpad float | None

Vertical padding.

 None
hspace float | None

Horizontal space.

 None
vspace float | None

Vertical space.

 None
background_color str

Background color.

 '#FFFFFF'
axes Axes3D

Child 3D axes.

 <dynamic>
Source code in src\himena\standards\plotting\layout3d.py 
80
81
class SingleAxes3D(BaseLayoutModel):
    axes: Axes3D = Field(default_factory=Axes3D, description="Child 3D axes.")

SingleStackedAxes

Parameters:

Name Type Description Default
hpad float | None

Horizontal padding.

 None
vpad float | None

Vertical padding.

 None
hspace float | None

Horizontal space.

 None
vspace float | None

Vertical space.

 None
background_color str

Background color.

 '#FFFFFF'
axes StackedAxes

Child axes.

 required
Source code in src\himena\standards\plotting\layout.py 
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
class SingleStackedAxes(BaseLayoutModel):
    model_type: ClassVar[str] = StandardType.PLOT_STACK

    axes: StackedAxes = Field(..., description="Child axes.")
    background_color: str = Field("#FFFFFF", description="Background color.")

    @property
    def x(self) -> Axis:
        """X-axis settings."""
        return self.axes.x

    @property
    def y(self) -> Axis:
        """Y-axis settings."""
        return self.axes.y

    @property
    def axis_color(self) -> str:
        """Axis color."""
        return self.axes.axis_color

    @axis_color.setter
    def axis_color(self, value):
        self.axes.axis_color = value

    @property
    def title(self) -> str:
        """Title of the central axes."""
        return self.axes.title

    @title.setter
    def title(self, value):
        self.axes.title = value

    @classmethod
    def fill(cls, *shape: int, multi_dims=None):
        models = {}
        for index in np.ndindex(*shape):
            models[index] = []
        return SingleStackedAxes(
            axes=StackedAxes(shape=shape, models=models, multi_dims=multi_dims)
        )

    @property
    def shape(self) -> tuple[int, ...]:
        """Shape of the stack dimensions."""
        return self.axes.shape

    def __getitem__(self, key) -> ModelsRef:
        return self.axes[key]
axis_color property writable

Axis color.

shape property

Shape of the stack dimensions.

title property writable

Title of the central axes.

x property

X-axis settings.

y property

Y-axis settings.

Span

Plot model for span plot.

Parameters:

Name Type Description Default
name str

Name of the plot.

 ''
start float

Starting value of the lower bound.

 required
end float

Ending value of the upper bound.

 required
orient Literal[str, str]

Orientation of the span. 'vertical' means the spanis vertically unlimited.

 'vertical'
face Face

Properties of the span fill.

 <dynamic>
edge Edge

Properties of the span edge.

 <dynamic>
Source code in src\himena\standards\plotting\models.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
class Span(BasePlotModel):
    """Plot model for span plot."""

    start: float = Field(..., description="Starting value of the lower bound.")
    end: float = Field(..., description="Ending value of the upper bound.")
    orient: Literal["vertical", "horizontal"] = Field(
        "vertical",
        description="Orientation of the span. 'vertical' means the span"
        "is vertically unlimited.",
    )
    face: Face = Field(default_factory=Face, description="Properties of the span fill.")
    edge: Edge = Field(default_factory=Edge, description="Properties of the span edge.")

    def plot_option_dict(self) -> dict[str, Any]:
        from himena.qt.magicgui import EdgePropertyEdit, FacePropertyEdit

        return {
            "name": {"widget_type": "LineEdit", "value": self.name},
            "x0": {"annotation": float, "value": self.start},
            "x1": {"annotation": float, "value": self.end},
            "orient": {"choices": ["vertical", "horizontal"], "value": self.orient},
            "face": {"widget_type": FacePropertyEdit, "value": self.face.model_dump()},
            "edge": {"widget_type": EdgePropertyEdit, "value": self.edge.model_dump()},
        }

StyledText

Parameters:

Name Type Description Default
text str

Text content.

 required
size float | None

Font size.

 None
color Any | None

Font color.

 None
family str | None

Font family.

 None
bold bool

Bold style or not.

 False
italic bool

Italic style or not.

 False
underline bool

Underline style or not.

 False
alignment str | None

Text alignment.

 None
Source code in src\himena\standards\plotting\components.py 
11
12
13
14
15
16
17
18
19
20
21
class StyledText(BaseModel):
    model_config = PYDANTIC_CONFIG_STRICT

    text: str = Field(..., description="Text content.")
    size: float | None = Field(None, description="Font size.")
    color: Any | None = Field(None, description="Font color.")
    family: str | None = Field(None, description="Font family.")
    bold: bool = Field(False, description="Bold style or not.")
    italic: bool = Field(False, description="Italic style or not.")
    underline: bool = Field(False, description="Underline style or not.")
    alignment: str | None = Field(None, description="Text alignment.")

Surface3D

Plot model for a 3D surface plot.

Parameters:

Name Type Description Default
name str

Name of the plot.

 ''
x Any

X-axis values.

 required
y Any

Y-axis values.

 required
z Any

Z-axis values.

 required
face Face

Properties of the faces.

 <dynamic>
edge Edge

Properties of the edges.

 <dynamic>
Source code in src\himena\standards\plotting\models3d.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
class Surface3D(BasePlotModel):
    """Plot model for a 3D surface plot."""

    x: Any = Field(..., description="X-axis values.")
    y: Any = Field(..., description="Y-axis values.")
    z: Any = Field(..., description="Z-axis values.")
    face: Face = Field(default_factory=Face, description="Properties of the faces.")
    edge: Edge = Field(default_factory=Edge, description="Properties of the edges.")

    def plot_option_dict(self) -> dict[str, Any]:
        from himena.qt.magicgui import EdgePropertyEdit, FacePropertyEdit

        return {
            "name": {"widget_type": "LineEdit", "value": self.name},
            "face": {"widget_type": FacePropertyEdit, "value": self.face.model_dump()},
            "edge": {"widget_type": EdgePropertyEdit, "value": self.edge.model_dump()},
        }

Texts

Plot model for texts.

Parameters:

Name Type Description Default
name str

Name of the plot.

 ''
x Any

X-axis values.

 required
y Any

Y-axis values.

 required
texts Any

Texts to be displayed.

 required
size int

Font size of the texts.

 12
color str

Font color of the texts.

 'black'
family str

Font family of the texts.

 'Arial'
anchor Literal[str, str, str, str, str, str, str, str, str]

Anchor position of the texts. 'center' means the center of the text.

 'center'
rotation float

Rotation angle of the texts.

 0
Source code in src\himena\standards\plotting\models.py 
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
class Texts(PlotModelXY):
    """Plot model for texts."""

    texts: Any = Field(..., description="Texts to be displayed.")
    size: int = Field(12, description="Font size of the texts.")
    color: str = Field("black", description="Font color of the texts.")
    family: str = Field("Arial", description="Font family of the texts.")
    anchor: ANCHOR_STRINGS = Field(
        "center",
        description="Anchor position of the texts. 'center' means the center of the text.",
    )
    rotation: float = Field(0, description="Rotation angle of the texts.")

    def plot_option_dict(self) -> dict[str, Any]:
        return {
            "name": {"widget_type": "LineEdit", "value": self.name},
            "font_size": {"annotation": int, "value": self.size},
            "font_color": {"annotation": str, "value": self.color},
            "font_family": {"annotation": str, "value": self.family},
        }

column(num=1, *, background_color='white')

Make a column layout model.

Parameters:

Name Type Description Default
num int

Number of columns, by default 1

 1

Examples:

from himena.standards import plotting as hplt
col = hplt.column(3)
col[0].plot([0, 1, 2], [4, 2, 3], color="blue")
col.show()  # show as a sub-window in the current widget
Source code in src\himena\standards\plotting\_api.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
def column(num: int = 1, *, background_color: Any = "white") -> layout.Column:
    """Make a column layout model.

    Parameters
    ----------
    num : int, optional
        Number of columns, by default 1

    Examples
    --------
    ``` python
    from himena.standards import plotting as hplt
    col = hplt.column(3)
    col[0].plot([0, 1, 2], [4, 2, 3], color="blue")
    col.show()  # show as a sub-window in the current widget
    ```
    """
    lo = layout.Column.fill(num)
    lo.background_color = "white"
    return lo

figure(background_color='white')

Make a single axes layout model.

Examples:

from himena.standards import plotting as hplt
fig = hplt.figure()
fig.plot([0, 1, 2], [4, 2, 3], color="red")
fig.show()  # show as a sub-window in the current widget
Source code in src\himena\standards\plotting\_api.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
def figure(background_color: Any = "white") -> layout.SingleAxes:
    """Make a single axes layout model.

    Examples
    --------
    ``` python
    from himena.standards import plotting as hplt
    fig = hplt.figure()
    fig.plot([0, 1, 2], [4, 2, 3], color="red")
    fig.show()  # show as a sub-window in the current widget
    ```
    """
    lo = layout.SingleAxes(background_color=background_color)
    return lo

figure_3d(background_color='white')

Make a single 3D axes layout model.

Examples:

from himena.standards import plotting as hplt
fig = hplt.figure_3d()
fig.plot([0, 1, 2], [4, 2, 3], [6, 8, 7], color="red")
fig.show()  # show as a sub-window in the current widget
Source code in src\himena\standards\plotting\_api.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def figure_3d(background_color: Any = "white") -> layout3d.SingleAxes3D:
    """Make a single 3D axes layout model.

    Examples
    --------
    ``` python
    from himena.standards import plotting as hplt
    fig = hplt.figure_3d()
    fig.plot([0, 1, 2], [4, 2, 3], [6, 8, 7], color="red")
    fig.show()  # show as a sub-window in the current widget
    ```
    """
    lo = layout3d.SingleAxes3D(background_color=background_color)
    return lo

grid(rows=1, cols=1, *, background_color='white')

Make a grid layout model.

Parameters:

Name Type Description Default
rows int

Number of rows, by default 1

 1
cols int

Number of columns, by default 1

 1

Examples:

from himena.standards import plotting as hplt
grd = hplt.grid(2, 3)
grd[0, 0].plot([0, 1, 2], [4, 2, 3], color="green")
grd.show()  # show as a sub-window in the current widget
Source code in src\himena\standards\plotting\_api.py 
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
def grid(
    rows: int = 1, cols: int = 1, *, background_color: Any = "white"
) -> layout.Grid:
    """Make a grid layout model.

    Parameters
    ----------
    rows : int, optional
        Number of rows, by default 1
    cols : int, optional
        Number of columns, by default 1

    Examples
    --------
    ``` python
    from himena.standards import plotting as hplt
    grd = hplt.grid(2, 3)
    grd[0, 0].plot([0, 1, 2], [4, 2, 3], color="green")
    grd.show()  # show as a sub-window in the current widget
    ```
    """
    lo = layout.Grid.fill(rows, cols)
    lo.background_color = "white"
    return lo

row(num=1, *, background_color='white')

Make a row layout model.

Examples:

from himena.standards import plotting as hplt
row = hplt.row(2)
row[0].plot([0, 1, 2], [4, 2, 3], color="red")
row.show()  # show as a sub-window in the current widget
Source code in src\himena\standards\plotting\_api.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
def row(num: int = 1, *, background_color: Any = "white") -> layout.Row:
    """Make a row layout model.

    Examples
    --------
    ``` python
    from himena.standards import plotting as hplt
    row = hplt.row(2)
    row[0].plot([0, 1, 2], [4, 2, 3], color="red")
    row.show()  # show as a sub-window in the current widget
    ```
    """
    lo = layout.Row.fill(num)
    lo.background_color = background_color
    return lo