Skip to content

Plots API Reference

pgfplots

PGFPlots classes for LaTeX figure generation.

Coordinates dataclass

Coordinates for a plot.

Examples:

Static coordinates (list of tuples)

Coordinates([(0, 1), (1, 2), (2, 4)])

From separate x, y arrays (numpy arrays or lists)

Coordinates(x=[0, 1, 2], y=[1, 2, 4]) Coordinates(x=np.array([0, 1, 2]), y=np.array([1, 2, 4]))

3D coordinates

Coordinates([(0, 0, 1), (1, 1, 2)]) Coordinates(x=[0, 1], y=[0, 1], z=[1, 2])

Dynamic coordinates from data

Coordinates(Iter(Ref("points"), x=Ref("x"), y=Ref("y")))

With marker size data (for scatter plots)

Coordinates(x=[0, 1, 2], y=[1, 2, 4], marker_size=[5, 10, 15]) Coordinates(Iter(Ref("points"), x=Ref("x"), y=Ref("y"), marker_size=Ref("size")))

Control precision (default 6 significant figures)

Coordinates(x=[0.123456789], y=[0.987654321]) # Outputs (0.123457, 0.987654) Coordinates(x=[0.123456789], y=[0.987654321], precision=3) # Outputs (0.123, 0.988) Coordinates(x=[0.123456789], y=[0.987654321], precision=None) # No rounding

Source code in src/texer/pgfplots.py 
 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
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
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
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
@dataclass
class Coordinates:
    """Coordinates for a plot.

    Examples:
        # Static coordinates (list of tuples)
        Coordinates([(0, 1), (1, 2), (2, 4)])

        # From separate x, y arrays (numpy arrays or lists)
        Coordinates(x=[0, 1, 2], y=[1, 2, 4])
        Coordinates(x=np.array([0, 1, 2]), y=np.array([1, 2, 4]))

        # 3D coordinates
        Coordinates([(0, 0, 1), (1, 1, 2)])
        Coordinates(x=[0, 1], y=[0, 1], z=[1, 2])

        # Dynamic coordinates from data
        Coordinates(Iter(Ref("points"), x=Ref("x"), y=Ref("y")))

        # With marker size data (for scatter plots)
        Coordinates(x=[0, 1, 2], y=[1, 2, 4], marker_size=[5, 10, 15])
        Coordinates(Iter(Ref("points"), x=Ref("x"), y=Ref("y"), marker_size=Ref("size")))

        # Control precision (default 6 significant figures)
        Coordinates(x=[0.123456789], y=[0.987654321])  # Outputs (0.123457, 0.987654)
        Coordinates(x=[0.123456789], y=[0.987654321], precision=3)  # Outputs (0.123, 0.988)
        Coordinates(x=[0.123456789], y=[0.987654321], precision=None)  # No rounding
    """

    source: list[tuple[Any, ...]] | Iter | Spec | None = None
    x: Any = None
    y: Any = None
    z: Any = None
    marker_size: Any = None  # For data-driven marker sizes
    precision: int | None = 6  # Number of significant figures (None = no rounding)

    def __post_init__(self) -> None:
        """Validate that either source or x/y are provided."""
        if self.source is None and self.x is None:
            raise ValueError("Either 'source' or 'x' and 'y' must be provided")
        if self.source is not None and (self.x is not None or self.y is not None):
            raise ValueError("Cannot specify both 'source' and 'x'/'y' parameters")
        if self.x is not None and self.y is None:
            raise ValueError("If 'x' is provided, 'y' must also be provided")

    def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
        """Render coordinates to LaTeX."""
        if scope is None:
            scope = {}

        # Handle x, y, z arrays
        if self.x is not None:
            # Resolve x, y, z if they are Specs
            x_resolved = resolve_value(self.x, data, scope)
            y_resolved = resolve_value(self.y, data, scope)
            z_resolved = resolve_value(self.z, data, scope) if self.z is not None else None
            marker_size_resolved = resolve_value(self.marker_size, data, scope) if self.marker_size is not None else None
            points = self._arrays_to_points_resolved(x_resolved, y_resolved, z_resolved, marker_size_resolved)
        # Resolve the source
        elif isinstance(self.source, (Iter, Spec)):
            points = self.source.resolve(data, scope)
        else:
            points = self.source  # type: ignore[assignment]

        # Determine if we have marker_size data
        # Check both direct marker_size attribute and Iter source with marker_size
        has_marker_size = (
            self.marker_size is not None or
            (isinstance(self.source, Iter) and self.source.marker_size is not None)
        )

        # If we have marker_size, use table format instead of coordinates
        # because \thisrow{size} only works with table input
        if has_marker_size:
            return self._render_as_table(points)

        # Format as coordinates (standard format without marker_size)
        coord_strs = []
        for point in points:
            if isinstance(point, tuple):
                formatted_values = [self._format_value(v) for v in point]
                coord_strs.append(f"({', '.join(formatted_values)})")
            else:
                # Single value (rare case)
                coord_strs.append(f"({self._format_value(point)})")

        return "coordinates {" + " ".join(coord_strs) + "}"

    def _render_as_table(self, points: list[tuple[Any, ...]]) -> str:
        """Render coordinates as table format for marker_size support."""
        if not points:
            return "table {x y size\n}"

        # Determine if 3D based on point length
        first_point = points[0]
        is_3d = len(first_point) == 4  # (x, y, z, size) for 3D

        # Build header
        if is_3d:
            header = "x y z size"
        else:
            header = "x y size"

        # Build data rows
        rows = [header]
        for point in points:
            formatted = [self._format_value(v) for v in point]
            rows.append(" ".join(formatted))

        return "table {\n" + "\n".join(rows) + "\n}"

    def _arrays_to_points_resolved(self, x: Any, y: Any, z: Any = None, marker_size: Any = None) -> list[tuple[Any, ...]]:
        """Convert resolved x, y, z, marker_size arrays to list of tuples."""
        # Convert to lists if numpy arrays
        x_list = self._to_list(x)
        y_list = self._to_list(y)

        if z is not None:
            z_list = self._to_list(z)
            if marker_size is not None:
                marker_size_list = self._to_list(marker_size)
                if not (len(x_list) == len(y_list) == len(z_list) == len(marker_size_list)):
                    raise ValueError(
                        f"x, y, z, and marker_size must have the same length "
                        f"(got {len(x_list)}, {len(y_list)}, {len(z_list)}, {len(marker_size_list)})"
                    )
                return list(zip(x_list, y_list, z_list, marker_size_list))
            else:
                if not (len(x_list) == len(y_list) == len(z_list)):
                    raise ValueError(f"x, y, and z must have the same length (got {len(x_list)}, {len(y_list)}, {len(z_list)})")
                return list(zip(x_list, y_list, z_list))
        else:
            if marker_size is not None:
                marker_size_list = self._to_list(marker_size)
                if not (len(x_list) == len(y_list) == len(marker_size_list)):
                    raise ValueError(
                        f"x, y, and marker_size must have the same length "
                        f"(got {len(x_list)}, {len(y_list)}, {len(marker_size_list)})"
                    )
                return list(zip(x_list, y_list, marker_size_list))
            else:
                if len(x_list) != len(y_list):
                    raise ValueError(f"x and y must have the same length (got {len(x_list)}, {len(y_list)})")
                return list(zip(x_list, y_list))

    @staticmethod
    def _to_list(arr: Any) -> list[Any]:
        """Convert array-like to list, handling numpy arrays."""
        # Check if it's a numpy array
        if hasattr(arr, '__array__') or hasattr(arr, 'tolist'):
            result: list[Any] = arr.tolist()
            return result
        # Already a list or tuple
        elif isinstance(arr, (list, tuple)):
            return list(arr)
        else:
            raise TypeError(f"Expected array-like object, got {type(arr)}")

    def _format_value(self, value: Any) -> str:
        """Format a numeric value with specified precision."""
        # If precision is None, no rounding
        if self.precision is None:
            return str(value)

        # Try to format as float with significant figures
        try:
            val = float(value)
            # Handle special cases
            if val == 0:
                return "0"

            # Use the 'g' format specifier which uses significant figures
            # and automatically switches between fixed and scientific notation
            format_str = f"{{:.{self.precision}g}}"
            return format_str.format(val)
        except (ValueError, TypeError):
            # Not a number, return as-is
            return str(value)

__post_init__()

Validate that either source or x/y are provided.

Source code in src/texer/pgfplots.py 
81
82
83
84
85
86
87
88
def __post_init__(self) -> None:
    """Validate that either source or x/y are provided."""
    if self.source is None and self.x is None:
        raise ValueError("Either 'source' or 'x' and 'y' must be provided")
    if self.source is not None and (self.x is not None or self.y is not None):
        raise ValueError("Cannot specify both 'source' and 'x'/'y' parameters")
    if self.x is not None and self.y is None:
        raise ValueError("If 'x' is provided, 'y' must also be provided")

render(data, scope=None)

Render coordinates to LaTeX.

Source code in src/texer/pgfplots.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
    """Render coordinates to LaTeX."""
    if scope is None:
        scope = {}

    # Handle x, y, z arrays
    if self.x is not None:
        # Resolve x, y, z if they are Specs
        x_resolved = resolve_value(self.x, data, scope)
        y_resolved = resolve_value(self.y, data, scope)
        z_resolved = resolve_value(self.z, data, scope) if self.z is not None else None
        marker_size_resolved = resolve_value(self.marker_size, data, scope) if self.marker_size is not None else None
        points = self._arrays_to_points_resolved(x_resolved, y_resolved, z_resolved, marker_size_resolved)
    # Resolve the source
    elif isinstance(self.source, (Iter, Spec)):
        points = self.source.resolve(data, scope)
    else:
        points = self.source  # type: ignore[assignment]

    # Determine if we have marker_size data
    # Check both direct marker_size attribute and Iter source with marker_size
    has_marker_size = (
        self.marker_size is not None or
        (isinstance(self.source, Iter) and self.source.marker_size is not None)
    )

    # If we have marker_size, use table format instead of coordinates
    # because \thisrow{size} only works with table input
    if has_marker_size:
        return self._render_as_table(points)

    # Format as coordinates (standard format without marker_size)
    coord_strs = []
    for point in points:
        if isinstance(point, tuple):
            formatted_values = [self._format_value(v) for v in point]
            coord_strs.append(f"({', '.join(formatted_values)})")
        else:
            # Single value (rare case)
            coord_strs.append(f"({self._format_value(point)})")

    return "coordinates {" + " ".join(coord_strs) + "}"

AddPlot dataclass

An \addplot command for PGFPlots.

Examples:

AddPlot( color="blue", mark="*", coords=Coordinates([(0, 1), (1, 2)]) )

AddPlot( style="dashed", domain="0:10", expression="x^2" )

Scatter plot with data-driven marker sizes

AddPlot( scatter=True, only_marks=True, coords=Coordinates(x=[0, 1, 2], y=[1, 2, 4], marker_size=[5, 10, 15]) )

Source code in src/texer/pgfplots.py 
225
226
227
228
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
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
@dataclass
class AddPlot:
    """An \\addplot command for PGFPlots.

    Examples:
        AddPlot(
            color="blue",
            mark="*",
            coords=Coordinates([(0, 1), (1, 2)])
        )

        AddPlot(
            style="dashed",
            domain="0:10",
            expression="x^2"
        )

        # Scatter plot with data-driven marker sizes
        AddPlot(
            scatter=True,
            only_marks=True,
            coords=Coordinates(x=[0, 1, 2], y=[1, 2, 4], marker_size=[5, 10, 15])
        )
    """

    # Coordinate-based plot
    coords: Coordinates | None = None

    # Expression-based plot
    expression: str | Spec | None = None
    domain: str | Spec | None = None
    samples: int | Spec | None = None

    # Style options
    color: ColorName | str | Spec | None = None
    mark: MarkStyle | str | Spec | None = None
    mark_size: str | float | Spec | None = None  # Static marker size (e.g., "3pt" or 3)
    style: LineStyle | str | Spec | None = None
    line_width: str | Spec | None = None
    only_marks: bool | Spec = False
    no_marks: bool | Spec = False
    smooth: bool | Spec = False
    thick: bool | Spec = False

    # Scatter plot options (for data-driven marker sizes)
    scatter: bool | Spec = False
    scatter_src: str | Spec | None = None  # Which coordinate controls marker size ("explicit" uses meta column)

    # Plot name for legend
    name: str | Spec | None = None

    # 3D options
    surf: bool = False
    mesh: bool = False

    # Error bars
    error_bars: bool = False
    error_bar_style: dict[str, Any] = field(default_factory=dict)

    # Cycle list option
    use_cycle_list: bool = False

    # Raw options escape hatch
    _raw_options: str | None = None

    def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
        """Render the addplot command."""
        if scope is None:
            scope = {}

        parts = []

        # Build options (resolve Specs like Ref)
        options = {}
        if self.color:
            color_value = resolve_value(self.color, data, scope)
            # Convert hex colors to PGF RGB format
            if isinstance(color_value, str) and is_hex_color(color_value):
                color_value = hex_to_pgf_rgb(color_value)
            options["color"] = color_value
        if self.mark:
            options["mark"] = resolve_value(self.mark, data, scope)
        if self.mark_size:
            mark_size_val = resolve_value(self.mark_size, data, scope)
            # If numeric, add pt unit; otherwise use as-is
            if isinstance(mark_size_val, (int, float)):
                options["mark size"] = f"{mark_size_val}pt"
            else:
                options["mark size"] = mark_size_val
        if self.style:
            resolved_style = resolve_value(self.style, data, scope)
            options[resolved_style] = True
        if self.line_width:
            options["line width"] = self.line_width
        if self.only_marks:
            options["only marks"] = True
        if self.no_marks:
            options["mark"] = "none"
        if self.smooth:
            options["smooth"] = True
        if self.thick:
            options["thick"] = True
        if self.domain:
            options["domain"] = self.domain
        if self.samples:
            options["samples"] = self.samples
        if self.surf:
            options["surf"] = True
        if self.mesh:
            options["mesh"] = True

        # Scatter plot options
        scatter_enabled = resolve_value(self.scatter, data, scope) if isinstance(self.scatter, Spec) else self.scatter

        # Check if coordinates have marker_size data
        has_marker_size_data = False
        if self.coords:
            # Check if marker_size is directly on Coordinates object (x/y/marker_size style)
            if self.coords.marker_size is not None:
                has_marker_size_data = True
            # Check if source is an Iter with marker_size (Iter style)
            elif isinstance(self.coords.source, Iter) and self.coords.source.marker_size is not None:
                has_marker_size_data = True

        if scatter_enabled:
            if self.scatter_src:
                # User explicitly wants scatter with color mapping
                options["scatter"] = True
                scatter_src_val = resolve_value(self.scatter_src, data, scope)
                options["scatter src"] = scatter_src_val
            elif has_marker_size_data:
                # User wants variable marker sizes but not scatter coloring
                # We need to enable scatter mode for the marker code to work,
                # but we disable scatter's color mapping to keep the user's specified color
                options["scatter"] = True
                # Use current color (.) instead of mapped color - prevents gradient
                options["scatter/use mapped color"] = "{draw=.!0!.,fill=.!0!.}"
                options["visualization depends on"] = r"{\thisrow{size} \as \perpointmarksize}"
                options["scatter/@pre marker code/.append style"] = "{/tikz/mark size=\\perpointmarksize}"
            else:
                # scatter=True but no marker_size and no scatter_src
                # Enable basic scatter mode
                options["scatter"] = True

        # 3D variant
        base_cmd = "\\addplot3" if self.surf or self.mesh else "\\addplot"

        # Check if we should use cycle list automatically
        # Use + if use_cycle_list is explicitly set, OR if there are no color/mark/style options
        has_style_options = bool(self.color or self.mark or self.style or self.line_width or self.mark_size)
        should_use_cycle = self.use_cycle_list or not has_style_options

        # Add + for cycle list usage
        plot_cmd = base_cmd + "+" if should_use_cycle else base_cmd

        # Format options string
        opts_str = format_options(options, self._raw_options)
        if opts_str:
            parts.append(f"{plot_cmd}[{opts_str}]")
        else:
            parts.append(plot_cmd)

        # Add coordinates or expression
        if self.coords is not None:
            parts.append(self.coords.render(data, scope))
        elif self.expression is not None:
            parts.append(f"{{{self.expression}}}")

        return " ".join(parts) + ";"

    def __repr__(self) -> str:
        return f"AddPlot(color={self.color!r}, mark={self.mark!r}, ...)"

render(data, scope=None)

Render the addplot command.

Source code in src/texer/pgfplots.py 
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
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
    """Render the addplot command."""
    if scope is None:
        scope = {}

    parts = []

    # Build options (resolve Specs like Ref)
    options = {}
    if self.color:
        color_value = resolve_value(self.color, data, scope)
        # Convert hex colors to PGF RGB format
        if isinstance(color_value, str) and is_hex_color(color_value):
            color_value = hex_to_pgf_rgb(color_value)
        options["color"] = color_value
    if self.mark:
        options["mark"] = resolve_value(self.mark, data, scope)
    if self.mark_size:
        mark_size_val = resolve_value(self.mark_size, data, scope)
        # If numeric, add pt unit; otherwise use as-is
        if isinstance(mark_size_val, (int, float)):
            options["mark size"] = f"{mark_size_val}pt"
        else:
            options["mark size"] = mark_size_val
    if self.style:
        resolved_style = resolve_value(self.style, data, scope)
        options[resolved_style] = True
    if self.line_width:
        options["line width"] = self.line_width
    if self.only_marks:
        options["only marks"] = True
    if self.no_marks:
        options["mark"] = "none"
    if self.smooth:
        options["smooth"] = True
    if self.thick:
        options["thick"] = True
    if self.domain:
        options["domain"] = self.domain
    if self.samples:
        options["samples"] = self.samples
    if self.surf:
        options["surf"] = True
    if self.mesh:
        options["mesh"] = True

    # Scatter plot options
    scatter_enabled = resolve_value(self.scatter, data, scope) if isinstance(self.scatter, Spec) else self.scatter

    # Check if coordinates have marker_size data
    has_marker_size_data = False
    if self.coords:
        # Check if marker_size is directly on Coordinates object (x/y/marker_size style)
        if self.coords.marker_size is not None:
            has_marker_size_data = True
        # Check if source is an Iter with marker_size (Iter style)
        elif isinstance(self.coords.source, Iter) and self.coords.source.marker_size is not None:
            has_marker_size_data = True

    if scatter_enabled:
        if self.scatter_src:
            # User explicitly wants scatter with color mapping
            options["scatter"] = True
            scatter_src_val = resolve_value(self.scatter_src, data, scope)
            options["scatter src"] = scatter_src_val
        elif has_marker_size_data:
            # User wants variable marker sizes but not scatter coloring
            # We need to enable scatter mode for the marker code to work,
            # but we disable scatter's color mapping to keep the user's specified color
            options["scatter"] = True
            # Use current color (.) instead of mapped color - prevents gradient
            options["scatter/use mapped color"] = "{draw=.!0!.,fill=.!0!.}"
            options["visualization depends on"] = r"{\thisrow{size} \as \perpointmarksize}"
            options["scatter/@pre marker code/.append style"] = "{/tikz/mark size=\\perpointmarksize}"
        else:
            # scatter=True but no marker_size and no scatter_src
            # Enable basic scatter mode
            options["scatter"] = True

    # 3D variant
    base_cmd = "\\addplot3" if self.surf or self.mesh else "\\addplot"

    # Check if we should use cycle list automatically
    # Use + if use_cycle_list is explicitly set, OR if there are no color/mark/style options
    has_style_options = bool(self.color or self.mark or self.style or self.line_width or self.mark_size)
    should_use_cycle = self.use_cycle_list or not has_style_options

    # Add + for cycle list usage
    plot_cmd = base_cmd + "+" if should_use_cycle else base_cmd

    # Format options string
    opts_str = format_options(options, self._raw_options)
    if opts_str:
        parts.append(f"{plot_cmd}[{opts_str}]")
    else:
        parts.append(plot_cmd)

    # Add coordinates or expression
    if self.coords is not None:
        parts.append(self.coords.render(data, scope))
    elif self.expression is not None:
        parts.append(f"{{{self.expression}}}")

    return " ".join(parts) + ";"

Legend dataclass

Legend entries for a plot.

Examples:

Legend(["Series A", "Series B"]) Legend([Ref("legend_label")])

Source code in src/texer/pgfplots.py 
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
440
441
442
443
444
445
446
@dataclass
class Legend:
    """Legend entries for a plot.

    Examples:
        Legend(["Series A", "Series B"])
        Legend([Ref("legend_label")])
    """

    entries: list[Any] | Iter | Spec

    def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
        """Render legend command."""
        if scope is None:
            scope = {}

        from texer.eval import _evaluate_impl

        # Resolve entries if it's a Spec (like Iter)
        entries = resolve_value(self.entries, data, scope)

        # Validate that entries is iterable
        if entries is None:
            raise TypeError(
                f"Legend entries resolved to None. "
                f"Check that your Iter source path exists in the data. "
                f"Entries spec: {self.entries!r}"
            )

        if isinstance(entries, Iter):
            raise TypeError(
                f"Legend entries is an unresolved Iter object. "
                f"This usually means the Iter's source path was not found or returned None. "
                f"Iter source: {entries.source!r}. "
                f"Available data keys: {list(data.keys()) if isinstance(data, dict) else 'N/A'}"
            )

        if not hasattr(entries, "__iter__") or isinstance(entries, str):
            raise TypeError(
                f"Legend entries must be a list or iterable, got {type(entries).__name__}. "
                f"If using an Iter, ensure the source path exists and contains a collection."
            )

        resolved = []
        for entry in entries:
            resolved.append(_evaluate_impl(entry, data, scope, escape=False))

        return "\\legend{" + ", ".join(resolved) + "}"

render(data, scope=None)

Render legend command.

Source code in src/texer/pgfplots.py 
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
440
441
442
443
444
445
446
def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
    """Render legend command."""
    if scope is None:
        scope = {}

    from texer.eval import _evaluate_impl

    # Resolve entries if it's a Spec (like Iter)
    entries = resolve_value(self.entries, data, scope)

    # Validate that entries is iterable
    if entries is None:
        raise TypeError(
            f"Legend entries resolved to None. "
            f"Check that your Iter source path exists in the data. "
            f"Entries spec: {self.entries!r}"
        )

    if isinstance(entries, Iter):
        raise TypeError(
            f"Legend entries is an unresolved Iter object. "
            f"This usually means the Iter's source path was not found or returned None. "
            f"Iter source: {entries.source!r}. "
            f"Available data keys: {list(data.keys()) if isinstance(data, dict) else 'N/A'}"
        )

    if not hasattr(entries, "__iter__") or isinstance(entries, str):
        raise TypeError(
            f"Legend entries must be a list or iterable, got {type(entries).__name__}. "
            f"If using an Iter, ensure the source path exists and contains a collection."
        )

    resolved = []
    for entry in entries:
        resolved.append(_evaluate_impl(entry, data, scope, escape=False))

    return "\\legend{" + ", ".join(resolved) + "}"

Axis dataclass

A PGFPlots axis environment.

Examples:

Axis( xlabel="Time (s)", ylabel="Temperature (K)", plots=[AddPlot(...)], legend=["Data"] )

Source code in src/texer/pgfplots.py 
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
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
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
@dataclass
class Axis:
    """A PGFPlots axis environment.

    Examples:
        Axis(
            xlabel="Time (s)",
            ylabel="Temperature (K)",
            plots=[AddPlot(...)],
            legend=["Data"]
        )
    """

    plots: list[AddPlot] | Iter | Spec = field(default_factory=list)

    # Axis labels
    xlabel: str | Spec | None = None
    ylabel: str | Spec | None = None
    zlabel: str | Spec | None = None
    title: str | Spec | None = None
    title_style: str | Spec | None = None

    # Axis limits
    xmin: float | Spec | None = None
    xmax: float | Spec | None = None
    ymin: float | Spec | None = None
    ymax: float | Spec | None = None
    zmin: float | Spec | None = None
    zmax: float | Spec | None = None

    # Legend
    legend: list[Any] | Legend | Iter | Spec | None = None
    legend_pos: LegendPos | str | Spec | None = None
    legend_style: str | Spec | None = None
    legend_cell_align: Literal["left", "center", "right"] | str | Spec | None = None
    legend_columns: int | Spec | None = None
    transpose_legend: bool | Spec | None = None

    # Grid
    grid: GridStyle | bool | Spec | None = None

    # Axis type
    axis_type: Literal["axis", "semilogxaxis", "semilogyaxis", "loglogaxis"] = "axis"

    # Scale
    width: str | Spec | None = None
    height: str | Spec | None = None

    # Other common options
    enlargelimits: bool | float | Spec | None = None
    clip: bool | Spec | None = None
    axis_lines: AxisLines | str | Spec | None = None

    # Cycle list options
    cycle_list_name: str | Spec | None = None
    cycle_list: list[dict[str, Any]] | list[str] | Spec | None = None

    # Tick positions and labels
    xtick: list[float | int] | str | Spec | None = None
    ytick: list[float | int] | str | Spec | None = None
    ztick: list[float | int] | str | Spec | None = None
    xticklabels: list[str] | str | Spec | None = None
    yticklabels: list[str] | str | Spec | None = None
    zticklabels: list[str] | str | Spec | None = None

    # Raw options escape hatch
    _raw_options: str | None = None

    def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
        """Render the axis environment."""
        if scope is None:
            scope = {}

        from texer.eval import _evaluate_impl

        # Build options
        options: dict[str, Any] = {}

        # Labels (resolve if Spec)
        if self.xlabel is not None:
            options["xlabel"] = _evaluate_impl(self.xlabel, data, scope, escape=False)
        if self.ylabel is not None:
            options["ylabel"] = _evaluate_impl(self.ylabel, data, scope, escape=False)
        if self.zlabel is not None:
            options["zlabel"] = _evaluate_impl(self.zlabel, data, scope, escape=False)
        if self.title is not None:
            options["title"] = _evaluate_impl(self.title, data, scope, escape=False)

        # Limits (resolve if Spec)
        if self.xmin is not None:
            options["xmin"] = resolve_value(self.xmin, data, scope)
        if self.xmax is not None:
            options["xmax"] = resolve_value(self.xmax, data, scope)
        if self.ymin is not None:
            options["ymin"] = resolve_value(self.ymin, data, scope)
        if self.ymax is not None:
            options["ymax"] = resolve_value(self.ymax, data, scope)
        if self.zmin is not None:
            options["zmin"] = resolve_value(self.zmin, data, scope)
        if self.zmax is not None:
            options["zmax"] = resolve_value(self.zmax, data, scope)

        # Legend options (resolve if Spec)
        if self.legend_pos is not None:
            options["legend pos"] = resolve_value(self.legend_pos, data, scope)
        if self.legend_style is not None:
            options["legend style"] = resolve_value(self.legend_style, data, scope)
        if self.title_style is not None:
            options["title style"] = resolve_value(self.title_style, data, scope)
        if self.legend_cell_align is not None:
            options["legend cell align"] = resolve_value(self.legend_cell_align, data, scope)
        if self.legend_columns is not None:
            options["legend columns"] = resolve_value(self.legend_columns, data, scope)
        if self.transpose_legend is not None:
            transpose_value = resolve_value(self.transpose_legend, data, scope)
            if transpose_value:
                options["transpose legend"] = True

        # Grid (resolve if Spec)
        grid_value = resolve_value(self.grid, data, scope) if isinstance(self.grid, Spec) else self.grid
        if grid_value is True:
            options["grid"] = "major"
        elif grid_value:
            options["grid"] = grid_value

        # Dimensions (resolve if Spec)
        if self.width is not None:
            options["width"] = resolve_value(self.width, data, scope)
        if self.height is not None:
            options["height"] = resolve_value(self.height, data, scope)

        # Other options (resolve if Spec)
        if self.enlargelimits is not None:
            options["enlargelimits"] = resolve_value(self.enlargelimits, data, scope)
        if self.clip is not None:
            options["clip"] = resolve_value(self.clip, data, scope)
        if self.axis_lines is not None:
            options["axis lines"] = resolve_value(self.axis_lines, data, scope)

        # Cycle list options (resolve if Spec)
        if self.cycle_list_name is not None:
            options["cycle list name"] = resolve_value(self.cycle_list_name, data, scope)
        elif self.cycle_list is not None:
            cycle_list_resolved = resolve_value(self.cycle_list, data, scope)
            # Format cycle list
            cycle_entries = []
            for entry in cycle_list_resolved:
                if isinstance(entry, dict):
                    # Format as key=value pairs wrapped in braces
                    entry_str = format_options(entry, None)
                    cycle_entries.append("{" + entry_str + "}")
                else:
                    # Plain string entry
                    cycle_entries.append(str(entry))
            options["cycle list"] = "{" + ",".join(cycle_entries) + "}"

        # Tick positions (resolve if Spec)
        if self.xtick is not None:
            xtick_val = resolve_value(self.xtick, data, scope)
            if isinstance(xtick_val, list):
                options["xtick"] = "{" + ",".join(str(v) for v in xtick_val) + "}"
            else:
                options["xtick"] = xtick_val
        if self.ytick is not None:
            ytick_val = resolve_value(self.ytick, data, scope)
            if isinstance(ytick_val, list):
                options["ytick"] = "{" + ",".join(str(v) for v in ytick_val) + "}"
            else:
                options["ytick"] = ytick_val
        if self.ztick is not None:
            ztick_val = resolve_value(self.ztick, data, scope)
            if isinstance(ztick_val, list):
                options["ztick"] = "{" + ",".join(str(v) for v in ztick_val) + "}"
            else:
                options["ztick"] = ztick_val

        # Tick labels (resolve if Spec)
        if self.xticklabels is not None:
            xticklabels_val = resolve_value(self.xticklabels, data, scope)
            if isinstance(xticklabels_val, list):
                options["xticklabels"] = "{" + ",".join(str(v) for v in xticklabels_val) + "}"
            else:
                options["xticklabels"] = xticklabels_val
        if self.yticklabels is not None:
            yticklabels_val = resolve_value(self.yticklabels, data, scope)
            if isinstance(yticklabels_val, list):
                options["yticklabels"] = "{" + ",".join(str(v) for v in yticklabels_val) + "}"
            else:
                options["yticklabels"] = yticklabels_val
        if self.zticklabels is not None:
            zticklabels_val = resolve_value(self.zticklabels, data, scope)
            if isinstance(zticklabels_val, list):
                options["zticklabels"] = "{" + ",".join(str(v) for v in zticklabels_val) + "}"
            else:
                options["zticklabels"] = zticklabels_val

        # Format options
        opts_str = format_options(options, self._raw_options)

        lines = []

        # Opening
        if opts_str:
            lines.append(f"\\begin{{{self.axis_type}}}[{opts_str}]")
        else:
            lines.append(f"\\begin{{{self.axis_type}}}")

        # Plots (handle Iter specially to preserve scope)
        if isinstance(self.plots, Iter):
            # Resolve the Iter source to get items
            if isinstance(self.plots.source, str):
                import glom  # type: ignore[import-untyped]
                items = glom.glom(data, self.plots.source)
            else:
                items = self.plots.source.resolve(data, scope)

            # For each item, create updated scope and render template
            for item in items:
                item_scope = dict(scope) if scope else {}
                if isinstance(item, dict):
                    item_scope.update(item)
                # Resolve and render the template with the item scope
                plot = resolve_value(self.plots.template, item, item_scope)
                lines.append(f"  {plot.render(data, item_scope)}")
        else:
            # Regular list of plots
            plots = resolve_value(self.plots, data, scope)
            for plot in plots:
                lines.append(f"  {plot.render(data, scope)}")

        # Legend
        if self.legend is not None:
            if isinstance(self.legend, Legend):
                lines.append(f"  {self.legend.render(data, scope)}")
            else:
                legend = Legend(self.legend)
                lines.append(f"  {legend.render(data, scope)}")

        # Closing
        lines.append(f"\\end{{{self.axis_type}}}")

        return "\n".join(lines)

render(data, scope=None)

Render the axis environment.

Source code in src/texer/pgfplots.py 
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
    """Render the axis environment."""
    if scope is None:
        scope = {}

    from texer.eval import _evaluate_impl

    # Build options
    options: dict[str, Any] = {}

    # Labels (resolve if Spec)
    if self.xlabel is not None:
        options["xlabel"] = _evaluate_impl(self.xlabel, data, scope, escape=False)
    if self.ylabel is not None:
        options["ylabel"] = _evaluate_impl(self.ylabel, data, scope, escape=False)
    if self.zlabel is not None:
        options["zlabel"] = _evaluate_impl(self.zlabel, data, scope, escape=False)
    if self.title is not None:
        options["title"] = _evaluate_impl(self.title, data, scope, escape=False)

    # Limits (resolve if Spec)
    if self.xmin is not None:
        options["xmin"] = resolve_value(self.xmin, data, scope)
    if self.xmax is not None:
        options["xmax"] = resolve_value(self.xmax, data, scope)
    if self.ymin is not None:
        options["ymin"] = resolve_value(self.ymin, data, scope)
    if self.ymax is not None:
        options["ymax"] = resolve_value(self.ymax, data, scope)
    if self.zmin is not None:
        options["zmin"] = resolve_value(self.zmin, data, scope)
    if self.zmax is not None:
        options["zmax"] = resolve_value(self.zmax, data, scope)

    # Legend options (resolve if Spec)
    if self.legend_pos is not None:
        options["legend pos"] = resolve_value(self.legend_pos, data, scope)
    if self.legend_style is not None:
        options["legend style"] = resolve_value(self.legend_style, data, scope)
    if self.title_style is not None:
        options["title style"] = resolve_value(self.title_style, data, scope)
    if self.legend_cell_align is not None:
        options["legend cell align"] = resolve_value(self.legend_cell_align, data, scope)
    if self.legend_columns is not None:
        options["legend columns"] = resolve_value(self.legend_columns, data, scope)
    if self.transpose_legend is not None:
        transpose_value = resolve_value(self.transpose_legend, data, scope)
        if transpose_value:
            options["transpose legend"] = True

    # Grid (resolve if Spec)
    grid_value = resolve_value(self.grid, data, scope) if isinstance(self.grid, Spec) else self.grid
    if grid_value is True:
        options["grid"] = "major"
    elif grid_value:
        options["grid"] = grid_value

    # Dimensions (resolve if Spec)
    if self.width is not None:
        options["width"] = resolve_value(self.width, data, scope)
    if self.height is not None:
        options["height"] = resolve_value(self.height, data, scope)

    # Other options (resolve if Spec)
    if self.enlargelimits is not None:
        options["enlargelimits"] = resolve_value(self.enlargelimits, data, scope)
    if self.clip is not None:
        options["clip"] = resolve_value(self.clip, data, scope)
    if self.axis_lines is not None:
        options["axis lines"] = resolve_value(self.axis_lines, data, scope)

    # Cycle list options (resolve if Spec)
    if self.cycle_list_name is not None:
        options["cycle list name"] = resolve_value(self.cycle_list_name, data, scope)
    elif self.cycle_list is not None:
        cycle_list_resolved = resolve_value(self.cycle_list, data, scope)
        # Format cycle list
        cycle_entries = []
        for entry in cycle_list_resolved:
            if isinstance(entry, dict):
                # Format as key=value pairs wrapped in braces
                entry_str = format_options(entry, None)
                cycle_entries.append("{" + entry_str + "}")
            else:
                # Plain string entry
                cycle_entries.append(str(entry))
        options["cycle list"] = "{" + ",".join(cycle_entries) + "}"

    # Tick positions (resolve if Spec)
    if self.xtick is not None:
        xtick_val = resolve_value(self.xtick, data, scope)
        if isinstance(xtick_val, list):
            options["xtick"] = "{" + ",".join(str(v) for v in xtick_val) + "}"
        else:
            options["xtick"] = xtick_val
    if self.ytick is not None:
        ytick_val = resolve_value(self.ytick, data, scope)
        if isinstance(ytick_val, list):
            options["ytick"] = "{" + ",".join(str(v) for v in ytick_val) + "}"
        else:
            options["ytick"] = ytick_val
    if self.ztick is not None:
        ztick_val = resolve_value(self.ztick, data, scope)
        if isinstance(ztick_val, list):
            options["ztick"] = "{" + ",".join(str(v) for v in ztick_val) + "}"
        else:
            options["ztick"] = ztick_val

    # Tick labels (resolve if Spec)
    if self.xticklabels is not None:
        xticklabels_val = resolve_value(self.xticklabels, data, scope)
        if isinstance(xticklabels_val, list):
            options["xticklabels"] = "{" + ",".join(str(v) for v in xticklabels_val) + "}"
        else:
            options["xticklabels"] = xticklabels_val
    if self.yticklabels is not None:
        yticklabels_val = resolve_value(self.yticklabels, data, scope)
        if isinstance(yticklabels_val, list):
            options["yticklabels"] = "{" + ",".join(str(v) for v in yticklabels_val) + "}"
        else:
            options["yticklabels"] = yticklabels_val
    if self.zticklabels is not None:
        zticklabels_val = resolve_value(self.zticklabels, data, scope)
        if isinstance(zticklabels_val, list):
            options["zticklabels"] = "{" + ",".join(str(v) for v in zticklabels_val) + "}"
        else:
            options["zticklabels"] = zticklabels_val

    # Format options
    opts_str = format_options(options, self._raw_options)

    lines = []

    # Opening
    if opts_str:
        lines.append(f"\\begin{{{self.axis_type}}}[{opts_str}]")
    else:
        lines.append(f"\\begin{{{self.axis_type}}}")

    # Plots (handle Iter specially to preserve scope)
    if isinstance(self.plots, Iter):
        # Resolve the Iter source to get items
        if isinstance(self.plots.source, str):
            import glom  # type: ignore[import-untyped]
            items = glom.glom(data, self.plots.source)
        else:
            items = self.plots.source.resolve(data, scope)

        # For each item, create updated scope and render template
        for item in items:
            item_scope = dict(scope) if scope else {}
            if isinstance(item, dict):
                item_scope.update(item)
            # Resolve and render the template with the item scope
            plot = resolve_value(self.plots.template, item, item_scope)
            lines.append(f"  {plot.render(data, item_scope)}")
    else:
        # Regular list of plots
        plots = resolve_value(self.plots, data, scope)
        for plot in plots:
            lines.append(f"  {plot.render(data, scope)}")

    # Legend
    if self.legend is not None:
        if isinstance(self.legend, Legend):
            lines.append(f"  {self.legend.render(data, scope)}")
        else:
            legend = Legend(self.legend)
            lines.append(f"  {legend.render(data, scope)}")

    # Closing
    lines.append(f"\\end{{{self.axis_type}}}")

    return "\n".join(lines)

NextGroupPlot dataclass

A \nextgroupplot command within a groupplot environment.

Examples:

NextGroupPlot( title="Plot 1", xlabel="X", plots=[AddPlot(...)] )

Source code in src/texer/pgfplots.py 
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
@dataclass
class NextGroupPlot:
    """A \\nextgroupplot command within a groupplot environment.

    Examples:
        NextGroupPlot(
            title="Plot 1",
            xlabel="X",
            plots=[AddPlot(...)]
        )
    """

    plots: list[AddPlot] | Iter | Spec = field(default_factory=list)

    # Axis labels
    xlabel: str | Spec | None = None
    ylabel: str | Spec | None = None
    zlabel: str | Spec | None = None
    title: str | Spec | None = None
    title_style: str | Spec | None = None

    # Axis limits
    xmin: float | Spec | None = None
    xmax: float | Spec | None = None
    ymin: float | Spec | None = None
    ymax: float | Spec | None = None
    zmin: float | Spec | None = None
    zmax: float | Spec | None = None

    # Legend
    legend: list[Any] | Legend | Iter | Spec | None = None
    legend_pos: LegendPos | str | Spec | None = None
    legend_style: str | Spec | None = None
    legend_cell_align: Literal["left", "center", "right"] | str | Spec | None = None
    legend_columns: int | Spec | None = None
    transpose_legend: bool | Spec | None = None

    # Grid
    grid: GridStyle | bool | Spec | None = None

    # Other options
    enlargelimits: bool | float | Spec | None = None
    clip: bool | Spec | None = None
    axis_lines: AxisLines | str | Spec | None = None

    # Cycle list options
    cycle_list_name: str | Spec | None = None
    cycle_list: list[dict[str, Any]] | list[str] | Spec | None = None

    # Tick positions and labels
    xtick: list[float | int] | str | Spec | None = None
    ytick: list[float | int] | str | Spec | None = None
    ztick: list[float | int] | str | Spec | None = None
    xticklabels: list[str] | str | Spec | None = None
    yticklabels: list[str] | str | Spec | None = None
    zticklabels: list[str] | str | Spec | None = None

    # Raw options escape hatch
    _raw_options: str | None = None

    def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
        """Render the nextgroupplot command and its contents."""
        if scope is None:
            scope = {}

        from texer.eval import _evaluate_impl

        # Build options
        options: dict[str, Any] = {}

        # Labels (resolve if Spec)
        if self.xlabel is not None:
            options["xlabel"] = _evaluate_impl(self.xlabel, data, scope, escape=False)
        if self.ylabel is not None:
            options["ylabel"] = _evaluate_impl(self.ylabel, data, scope, escape=False)
        if self.zlabel is not None:
            options["zlabel"] = _evaluate_impl(self.zlabel, data, scope, escape=False)
        if self.title is not None:
            options["title"] = _evaluate_impl(self.title, data, scope, escape=False)

        # Limits (resolve if Spec)
        if self.xmin is not None:
            options["xmin"] = resolve_value(self.xmin, data, scope)
        if self.xmax is not None:
            options["xmax"] = resolve_value(self.xmax, data, scope)
        if self.ymin is not None:
            options["ymin"] = resolve_value(self.ymin, data, scope)
        if self.ymax is not None:
            options["ymax"] = resolve_value(self.ymax, data, scope)
        if self.zmin is not None:
            options["zmin"] = resolve_value(self.zmin, data, scope)
        if self.zmax is not None:
            options["zmax"] = resolve_value(self.zmax, data, scope)

        # Legend options (resolve if Spec)
        if self.legend_pos is not None:
            options["legend pos"] = resolve_value(self.legend_pos, data, scope)
        if self.legend_style is not None:
            options["legend style"] = resolve_value(self.legend_style, data, scope)
        if self.title_style is not None:
            options["title style"] = resolve_value(self.title_style, data, scope)
        if self.legend_cell_align is not None:
            options["legend cell align"] = resolve_value(self.legend_cell_align, data, scope)
        if self.legend_columns is not None:
            options["legend columns"] = resolve_value(self.legend_columns, data, scope)
        if self.transpose_legend is not None:
            transpose_value = resolve_value(self.transpose_legend, data, scope)
            if transpose_value:
                options["transpose legend"] = True

        # Grid (resolve if Spec)
        grid_value = resolve_value(self.grid, data, scope) if isinstance(self.grid, Spec) else self.grid
        if grid_value is True:
            options["grid"] = "major"
        elif grid_value:
            options["grid"] = grid_value

        # Other options (resolve if Spec)
        if self.enlargelimits is not None:
            options["enlargelimits"] = resolve_value(self.enlargelimits, data, scope)
        if self.clip is not None:
            options["clip"] = resolve_value(self.clip, data, scope)
        if self.axis_lines is not None:
            options["axis lines"] = resolve_value(self.axis_lines, data, scope)

        # Cycle list options (resolve if Spec)
        if self.cycle_list_name is not None:
            options["cycle list name"] = resolve_value(self.cycle_list_name, data, scope)
        elif self.cycle_list is not None:
            cycle_list_resolved = resolve_value(self.cycle_list, data, scope)
            # Format cycle list
            cycle_entries = []
            for entry in cycle_list_resolved:
                if isinstance(entry, dict):
                    # Format as key=value pairs wrapped in braces
                    entry_str = format_options(entry, None)
                    cycle_entries.append("{" + entry_str + "}")
                else:
                    # Plain string entry
                    cycle_entries.append(str(entry))
            options["cycle list"] = "{" + ",".join(cycle_entries) + "}"

        # Tick positions (resolve if Spec)
        if self.xtick is not None:
            xtick_val = resolve_value(self.xtick, data, scope)
            if isinstance(xtick_val, list):
                options["xtick"] = "{" + ",".join(str(v) for v in xtick_val) + "}"
            else:
                options["xtick"] = xtick_val
        if self.ytick is not None:
            ytick_val = resolve_value(self.ytick, data, scope)
            if isinstance(ytick_val, list):
                options["ytick"] = "{" + ",".join(str(v) for v in ytick_val) + "}"
            else:
                options["ytick"] = ytick_val
        if self.ztick is not None:
            ztick_val = resolve_value(self.ztick, data, scope)
            if isinstance(ztick_val, list):
                options["ztick"] = "{" + ",".join(str(v) for v in ztick_val) + "}"
            else:
                options["ztick"] = ztick_val

        # Tick labels (resolve if Spec)
        if self.xticklabels is not None:
            xticklabels_val = resolve_value(self.xticklabels, data, scope)
            if isinstance(xticklabels_val, list):
                options["xticklabels"] = "{" + ",".join(str(v) for v in xticklabels_val) + "}"
            else:
                options["xticklabels"] = xticklabels_val
        if self.yticklabels is not None:
            yticklabels_val = resolve_value(self.yticklabels, data, scope)
            if isinstance(yticklabels_val, list):
                options["yticklabels"] = "{" + ",".join(str(v) for v in yticklabels_val) + "}"
            else:
                options["yticklabels"] = yticklabels_val
        if self.zticklabels is not None:
            zticklabels_val = resolve_value(self.zticklabels, data, scope)
            if isinstance(zticklabels_val, list):
                options["zticklabels"] = "{" + ",".join(str(v) for v in zticklabels_val) + "}"
            else:
                options["zticklabels"] = zticklabels_val

        # Format options
        opts_str = format_options(options, self._raw_options)

        lines = []

        # Opening
        if opts_str:
            lines.append(f"\\nextgroupplot[{opts_str}]")
        else:
            lines.append("\\nextgroupplot")

        # Plots (handle Iter specially to preserve scope)
        if isinstance(self.plots, Iter):
            # Resolve the Iter source to get items
            if isinstance(self.plots.source, str):
                import glom
                items = glom.glom(data, self.plots.source)
            else:
                items = self.plots.source.resolve(data, scope)

            # For each item, create updated scope and render template
            for item in items:
                item_scope = dict(scope) if scope else {}
                if isinstance(item, dict):
                    item_scope.update(item)
                # Resolve and render the template with the item scope
                plot = resolve_value(self.plots.template, item, item_scope)
                lines.append(f"  {plot.render(data, item_scope)}")
        else:
            # Regular list of plots
            plots = resolve_value(self.plots, data, scope)
            for plot in plots:
                lines.append(f"  {plot.render(data, scope)}")

        # Legend
        if self.legend is not None:
            if isinstance(self.legend, Legend):
                lines.append(f"  {self.legend.render(data, scope)}")
            else:
                legend = Legend(self.legend)
                lines.append(f"  {legend.render(data, scope)}")

        return "\n".join(lines)

render(data, scope=None)

Render the nextgroupplot command and its contents.

Source code in src/texer/pgfplots.py 
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
    """Render the nextgroupplot command and its contents."""
    if scope is None:
        scope = {}

    from texer.eval import _evaluate_impl

    # Build options
    options: dict[str, Any] = {}

    # Labels (resolve if Spec)
    if self.xlabel is not None:
        options["xlabel"] = _evaluate_impl(self.xlabel, data, scope, escape=False)
    if self.ylabel is not None:
        options["ylabel"] = _evaluate_impl(self.ylabel, data, scope, escape=False)
    if self.zlabel is not None:
        options["zlabel"] = _evaluate_impl(self.zlabel, data, scope, escape=False)
    if self.title is not None:
        options["title"] = _evaluate_impl(self.title, data, scope, escape=False)

    # Limits (resolve if Spec)
    if self.xmin is not None:
        options["xmin"] = resolve_value(self.xmin, data, scope)
    if self.xmax is not None:
        options["xmax"] = resolve_value(self.xmax, data, scope)
    if self.ymin is not None:
        options["ymin"] = resolve_value(self.ymin, data, scope)
    if self.ymax is not None:
        options["ymax"] = resolve_value(self.ymax, data, scope)
    if self.zmin is not None:
        options["zmin"] = resolve_value(self.zmin, data, scope)
    if self.zmax is not None:
        options["zmax"] = resolve_value(self.zmax, data, scope)

    # Legend options (resolve if Spec)
    if self.legend_pos is not None:
        options["legend pos"] = resolve_value(self.legend_pos, data, scope)
    if self.legend_style is not None:
        options["legend style"] = resolve_value(self.legend_style, data, scope)
    if self.title_style is not None:
        options["title style"] = resolve_value(self.title_style, data, scope)
    if self.legend_cell_align is not None:
        options["legend cell align"] = resolve_value(self.legend_cell_align, data, scope)
    if self.legend_columns is not None:
        options["legend columns"] = resolve_value(self.legend_columns, data, scope)
    if self.transpose_legend is not None:
        transpose_value = resolve_value(self.transpose_legend, data, scope)
        if transpose_value:
            options["transpose legend"] = True

    # Grid (resolve if Spec)
    grid_value = resolve_value(self.grid, data, scope) if isinstance(self.grid, Spec) else self.grid
    if grid_value is True:
        options["grid"] = "major"
    elif grid_value:
        options["grid"] = grid_value

    # Other options (resolve if Spec)
    if self.enlargelimits is not None:
        options["enlargelimits"] = resolve_value(self.enlargelimits, data, scope)
    if self.clip is not None:
        options["clip"] = resolve_value(self.clip, data, scope)
    if self.axis_lines is not None:
        options["axis lines"] = resolve_value(self.axis_lines, data, scope)

    # Cycle list options (resolve if Spec)
    if self.cycle_list_name is not None:
        options["cycle list name"] = resolve_value(self.cycle_list_name, data, scope)
    elif self.cycle_list is not None:
        cycle_list_resolved = resolve_value(self.cycle_list, data, scope)
        # Format cycle list
        cycle_entries = []
        for entry in cycle_list_resolved:
            if isinstance(entry, dict):
                # Format as key=value pairs wrapped in braces
                entry_str = format_options(entry, None)
                cycle_entries.append("{" + entry_str + "}")
            else:
                # Plain string entry
                cycle_entries.append(str(entry))
        options["cycle list"] = "{" + ",".join(cycle_entries) + "}"

    # Tick positions (resolve if Spec)
    if self.xtick is not None:
        xtick_val = resolve_value(self.xtick, data, scope)
        if isinstance(xtick_val, list):
            options["xtick"] = "{" + ",".join(str(v) for v in xtick_val) + "}"
        else:
            options["xtick"] = xtick_val
    if self.ytick is not None:
        ytick_val = resolve_value(self.ytick, data, scope)
        if isinstance(ytick_val, list):
            options["ytick"] = "{" + ",".join(str(v) for v in ytick_val) + "}"
        else:
            options["ytick"] = ytick_val
    if self.ztick is not None:
        ztick_val = resolve_value(self.ztick, data, scope)
        if isinstance(ztick_val, list):
            options["ztick"] = "{" + ",".join(str(v) for v in ztick_val) + "}"
        else:
            options["ztick"] = ztick_val

    # Tick labels (resolve if Spec)
    if self.xticklabels is not None:
        xticklabels_val = resolve_value(self.xticklabels, data, scope)
        if isinstance(xticklabels_val, list):
            options["xticklabels"] = "{" + ",".join(str(v) for v in xticklabels_val) + "}"
        else:
            options["xticklabels"] = xticklabels_val
    if self.yticklabels is not None:
        yticklabels_val = resolve_value(self.yticklabels, data, scope)
        if isinstance(yticklabels_val, list):
            options["yticklabels"] = "{" + ",".join(str(v) for v in yticklabels_val) + "}"
        else:
            options["yticklabels"] = yticklabels_val
    if self.zticklabels is not None:
        zticklabels_val = resolve_value(self.zticklabels, data, scope)
        if isinstance(zticklabels_val, list):
            options["zticklabels"] = "{" + ",".join(str(v) for v in zticklabels_val) + "}"
        else:
            options["zticklabels"] = zticklabels_val

    # Format options
    opts_str = format_options(options, self._raw_options)

    lines = []

    # Opening
    if opts_str:
        lines.append(f"\\nextgroupplot[{opts_str}]")
    else:
        lines.append("\\nextgroupplot")

    # Plots (handle Iter specially to preserve scope)
    if isinstance(self.plots, Iter):
        # Resolve the Iter source to get items
        if isinstance(self.plots.source, str):
            import glom
            items = glom.glom(data, self.plots.source)
        else:
            items = self.plots.source.resolve(data, scope)

        # For each item, create updated scope and render template
        for item in items:
            item_scope = dict(scope) if scope else {}
            if isinstance(item, dict):
                item_scope.update(item)
            # Resolve and render the template with the item scope
            plot = resolve_value(self.plots.template, item, item_scope)
            lines.append(f"  {plot.render(data, item_scope)}")
    else:
        # Regular list of plots
        plots = resolve_value(self.plots, data, scope)
        for plot in plots:
            lines.append(f"  {plot.render(data, scope)}")

    # Legend
    if self.legend is not None:
        if isinstance(self.legend, Legend):
            lines.append(f"  {self.legend.render(data, scope)}")
        else:
            legend = Legend(self.legend)
            lines.append(f"  {legend.render(data, scope)}")

    return "\n".join(lines)

GroupPlot dataclass

A groupplot environment for creating multiple plots in a grid layout.

Examples:

GroupPlot( group_style={"group size": "2 by 2"}, plots=[ NextGroupPlot(title="Plot 1", plots=[...]), NextGroupPlot(title="Plot 2", plots=[...]), NextGroupPlot(title="Plot 3", plots=[...]), NextGroupPlot(title="Plot 4", plots=[...]), ] )

Source code in src/texer/pgfplots.py 
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
@dataclass
class GroupPlot:
    """A groupplot environment for creating multiple plots in a grid layout.

    Examples:
        GroupPlot(
            group_style={"group size": "2 by 2"},
            plots=[
                NextGroupPlot(title="Plot 1", plots=[...]),
                NextGroupPlot(title="Plot 2", plots=[...]),
                NextGroupPlot(title="Plot 3", plots=[...]),
                NextGroupPlot(title="Plot 4", plots=[...]),
            ]
        )
    """

    plots: list[NextGroupPlot] | Iter | Spec = field(default_factory=list)

    # Group style options
    group_size: str | Spec | None = None  # e.g., "2 by 2"
    horizontal_sep: str | Spec | None = None
    vertical_sep: str | Spec | None = None
    xlabels_at: str | Spec | None = None  # e.g., "edge bottom"
    ylabels_at: str | Spec | None = None  # e.g., "edge left"
    xticklabels_at: str | Spec | None = None
    yticklabels_at: str | Spec | None = None

    # Common axis options (applied to all subplots)
    width: str | Spec | None = None
    height: str | Spec | None = None
    xmin: float | Spec | None = None
    xmax: float | Spec | None = None
    ymin: float | Spec | None = None
    ymax: float | Spec | None = None

    # Cycle list options (applied to all subplots)
    cycle_list_name: str | Spec | None = None
    cycle_list: list[dict[str, Any]] | list[str] | Spec | None = None

    # Raw options escape hatch
    _raw_options: str | None = None
    _raw_group_style: str | None = None

    def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
        """Render the groupplot environment."""
        if scope is None:
            scope = {}

        # Build group style options (resolve if Spec)
        group_style_opts = {}
        if self.group_size is not None:
            group_style_opts["group size"] = resolve_value(self.group_size, data, scope)
        if self.horizontal_sep is not None:
            group_style_opts["horizontal sep"] = resolve_value(self.horizontal_sep, data, scope)
        if self.vertical_sep is not None:
            group_style_opts["vertical sep"] = resolve_value(self.vertical_sep, data, scope)
        if self.xlabels_at is not None:
            group_style_opts["xlabels at"] = resolve_value(self.xlabels_at, data, scope)
        if self.ylabels_at is not None:
            group_style_opts["ylabels at"] = resolve_value(self.ylabels_at, data, scope)
        if self.xticklabels_at is not None:
            group_style_opts["xticklabels at"] = resolve_value(self.xticklabels_at, data, scope)
        if self.yticklabels_at is not None:
            group_style_opts["yticklabels at"] = resolve_value(self.yticklabels_at, data, scope)

        # Build main options
        options = {}

        # Add group style if present
        group_style_str = format_options(group_style_opts, self._raw_group_style)
        if group_style_str:
            options["group style"] = f"{{{group_style_str}}}"

        # Common options (resolve if Spec)
        if self.width is not None:
            options["width"] = resolve_value(self.width, data, scope)
        if self.height is not None:
            options["height"] = resolve_value(self.height, data, scope)
        if self.xmin is not None:
            options["xmin"] = resolve_value(self.xmin, data, scope)
        if self.xmax is not None:
            options["xmax"] = resolve_value(self.xmax, data, scope)
        if self.ymin is not None:
            options["ymin"] = resolve_value(self.ymin, data, scope)
        if self.ymax is not None:
            options["ymax"] = resolve_value(self.ymax, data, scope)

        # Cycle list options (resolve if Spec)
        if self.cycle_list_name is not None:
            options["cycle list name"] = resolve_value(self.cycle_list_name, data, scope)
        elif self.cycle_list is not None:
            cycle_list_resolved = resolve_value(self.cycle_list, data, scope)
            # Format cycle list
            cycle_entries = []
            for entry in cycle_list_resolved:
                if isinstance(entry, dict):
                    # Format as key=value pairs wrapped in braces
                    entry_str = format_options(entry, None)
                    cycle_entries.append("{" + entry_str + "}")
                else:
                    # Plain string entry
                    cycle_entries.append(str(entry))
            options["cycle list"] = "{" + ",".join(cycle_entries) + "}"

        # Format options
        opts_str = format_options(options, self._raw_options)

        lines = []

        # Opening
        if opts_str:
            lines.append(f"\\begin{{groupplot}}[{opts_str}]")
        else:
            lines.append("\\begin{groupplot}")

        # Render each plot (handle Iter specially to preserve scope)
        if isinstance(self.plots, Iter):
            # Resolve the Iter source to get items
            if isinstance(self.plots.source, str):
                import glom
                items = glom.glom(data, self.plots.source)
            elif isinstance(self.plots.source, Spec):
                items = self.plots.source.resolve(data, scope)
            else:
                items = self.plots.source

            # For each item, create updated scope and render template
            for item in items:
                item_scope = dict(scope) if scope else {}
                if isinstance(item, dict):
                    item_scope.update(item)
                # Resolve and render the template with the item scope
                plot = resolve_value(self.plots.template, item, item_scope)
                plot_lines = plot.render(data, item_scope)
                for line in plot_lines.split("\n"):
                    lines.append(f"  {line}" if line else line)
        else:
            # Regular list of plots
            plots = resolve_value(self.plots, data, scope)
            for plot in plots:
                plot_lines = plot.render(data, scope)
                for line in plot_lines.split("\n"):
                    lines.append(f"  {line}" if line else line)

        # Closing
        lines.append("\\end{groupplot}")

        return "\n".join(lines)

render(data, scope=None)

Render the groupplot environment.

Source code in src/texer/pgfplots.py 
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
    """Render the groupplot environment."""
    if scope is None:
        scope = {}

    # Build group style options (resolve if Spec)
    group_style_opts = {}
    if self.group_size is not None:
        group_style_opts["group size"] = resolve_value(self.group_size, data, scope)
    if self.horizontal_sep is not None:
        group_style_opts["horizontal sep"] = resolve_value(self.horizontal_sep, data, scope)
    if self.vertical_sep is not None:
        group_style_opts["vertical sep"] = resolve_value(self.vertical_sep, data, scope)
    if self.xlabels_at is not None:
        group_style_opts["xlabels at"] = resolve_value(self.xlabels_at, data, scope)
    if self.ylabels_at is not None:
        group_style_opts["ylabels at"] = resolve_value(self.ylabels_at, data, scope)
    if self.xticklabels_at is not None:
        group_style_opts["xticklabels at"] = resolve_value(self.xticklabels_at, data, scope)
    if self.yticklabels_at is not None:
        group_style_opts["yticklabels at"] = resolve_value(self.yticklabels_at, data, scope)

    # Build main options
    options = {}

    # Add group style if present
    group_style_str = format_options(group_style_opts, self._raw_group_style)
    if group_style_str:
        options["group style"] = f"{{{group_style_str}}}"

    # Common options (resolve if Spec)
    if self.width is not None:
        options["width"] = resolve_value(self.width, data, scope)
    if self.height is not None:
        options["height"] = resolve_value(self.height, data, scope)
    if self.xmin is not None:
        options["xmin"] = resolve_value(self.xmin, data, scope)
    if self.xmax is not None:
        options["xmax"] = resolve_value(self.xmax, data, scope)
    if self.ymin is not None:
        options["ymin"] = resolve_value(self.ymin, data, scope)
    if self.ymax is not None:
        options["ymax"] = resolve_value(self.ymax, data, scope)

    # Cycle list options (resolve if Spec)
    if self.cycle_list_name is not None:
        options["cycle list name"] = resolve_value(self.cycle_list_name, data, scope)
    elif self.cycle_list is not None:
        cycle_list_resolved = resolve_value(self.cycle_list, data, scope)
        # Format cycle list
        cycle_entries = []
        for entry in cycle_list_resolved:
            if isinstance(entry, dict):
                # Format as key=value pairs wrapped in braces
                entry_str = format_options(entry, None)
                cycle_entries.append("{" + entry_str + "}")
            else:
                # Plain string entry
                cycle_entries.append(str(entry))
        options["cycle list"] = "{" + ",".join(cycle_entries) + "}"

    # Format options
    opts_str = format_options(options, self._raw_options)

    lines = []

    # Opening
    if opts_str:
        lines.append(f"\\begin{{groupplot}}[{opts_str}]")
    else:
        lines.append("\\begin{groupplot}")

    # Render each plot (handle Iter specially to preserve scope)
    if isinstance(self.plots, Iter):
        # Resolve the Iter source to get items
        if isinstance(self.plots.source, str):
            import glom
            items = glom.glom(data, self.plots.source)
        elif isinstance(self.plots.source, Spec):
            items = self.plots.source.resolve(data, scope)
        else:
            items = self.plots.source

        # For each item, create updated scope and render template
        for item in items:
            item_scope = dict(scope) if scope else {}
            if isinstance(item, dict):
                item_scope.update(item)
            # Resolve and render the template with the item scope
            plot = resolve_value(self.plots.template, item, item_scope)
            plot_lines = plot.render(data, item_scope)
            for line in plot_lines.split("\n"):
                lines.append(f"  {line}" if line else line)
    else:
        # Regular list of plots
        plots = resolve_value(self.plots, data, scope)
        for plot in plots:
            plot_lines = plot.render(data, scope)
            for line in plot_lines.split("\n"):
                lines.append(f"  {line}" if line else line)

    # Closing
    lines.append("\\end{groupplot}")

    return "\n".join(lines)

PGFPlot dataclass

A complete PGFPlots tikzpicture.

Examples:

Single axis

PGFPlot( Axis( xlabel="X", ylabel="Y", plots=[AddPlot(coords=Coordinates([...]))] ) )

Multiple plots in a grid with groupplot

PGFPlot( GroupPlot( group_size="2 by 2", plots=[ NextGroupPlot(...), NextGroupPlot(...), ] ) )

Source code in src/texer/pgfplots.py 
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
@dataclass
class PGFPlot:
    """A complete PGFPlots tikzpicture.

    Examples:
        # Single axis
        PGFPlot(
            Axis(
                xlabel="X",
                ylabel="Y",
                plots=[AddPlot(coords=Coordinates([...]))]
            )
        )

        # Multiple plots in a grid with groupplot
        PGFPlot(
            GroupPlot(
                group_size="2 by 2",
                plots=[
                    NextGroupPlot(...),
                    NextGroupPlot(...),
                ]
            )
        )
    """

    axis: Axis | GroupPlot
    preamble: list[str] = field(default_factory=list)
    scale: float | Spec | None = None
    _raw_options: str | None = None

    def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
        """Render the complete tikzpicture."""
        if scope is None:
            scope = {}

        lines = []

        # Preamble (for standalone use)
        for line in self.preamble:
            lines.append(line)

        # Build tikzpicture options
        options = {}
        if self.scale is not None:
            options["scale"] = self.scale

        opts_str = format_options(options, self._raw_options)

        # Opening
        if opts_str:
            lines.append(f"\\begin{{tikzpicture}}[{opts_str}]")
        else:
            lines.append("\\begin{tikzpicture}")

        # Axis content
        axis_lines = self.axis.render(data, scope)
        for line in axis_lines.split("\n"):
            lines.append(f"  {line}" if line else line)

        # Closing
        lines.append("\\end{tikzpicture}")

        return "\n".join(lines)

    def with_preamble(self, data: Any = None) -> str:
        """Return LaTeX code including package imports for standalone use.

        Args:
            data: Optional data dict for rendering (default: empty dict).
        """
        if data is None:
            data = {}

        preamble = [
            "\\documentclass{standalone}",
            "\\usepackage{pgfplots}",
            "\\pgfplotsset{compat=1.18}",
            "\\usepgfplotslibrary{groupplots}",
            "",
            "\\begin{document}",
        ]
        content = self.render(data)
        closing = ["\\end{document}"]

        return "\n".join(preamble + [content] + closing)

    def save_to_file(
        self,
        file_path: str,
        data: Any = None,
        with_preamble: bool = True,
    ) -> None:
        """Save the LaTeX code to a file.

        Args:
            file_path: Path to the output .tex file.
            data: Optional data dict for rendering (default: empty dict).
            with_preamble: Whether to include document preamble for standalone compilation (default: True).

        Examples:
            # Save with preamble for standalone compilation
            plot.save_to_file("my_plot.tex")

            # Save just the tikzpicture content
            plot.save_to_file("my_plot.tex", with_preamble=False)

            # Save with data
            plot.save_to_file("my_plot.tex", data=my_data)
        """
        if data is None:
            data = {}

        if with_preamble:
            latex_code = self.with_preamble(data)
        else:
            latex_code = self.render(data)

        with open(file_path, "w", encoding="utf-8") as f:
            f.write(latex_code)

    def compile_to_pdf(
        self,
        tex_file_path: str,
        data: Any = None,
        output_dir: str | None = None,
    ) -> str:
        """Save to .tex file and compile to PDF using pdflatex.

        Args:
            tex_file_path: Path to save the .tex file (e.g., "my_plot.tex").
            data: Optional data dict for rendering (default: empty dict).
            output_dir: Optional output directory for compilation (default: same as .tex file).

        Returns:
            Path to the generated PDF file.

        Raises:
            RuntimeError: If pdflatex is not available or compilation fails.

        Examples:
            # Simple compilation
            pdf_path = plot.compile_to_pdf("my_plot.tex")

            # With data
            pdf_path = plot.compile_to_pdf("my_plot.tex", data=my_data)

            # Specify output directory
            pdf_path = plot.compile_to_pdf("my_plot.tex", output_dir="/tmp")
        """
        import subprocess
        import shutil
        from pathlib import Path

        # Check if pdflatex is available
        if shutil.which("pdflatex") is None:
            raise RuntimeError(
                "pdflatex not found. Please install a LaTeX distribution (e.g., TeX Live, MiKTeX)."
            )

        # Save to file
        self.save_to_file(tex_file_path, data=data, with_preamble=True)

        # Determine paths
        tex_path = Path(tex_file_path).resolve()
        output_path: Path
        if output_dir is None:
            output_path = tex_path.parent
        else:
            output_path = Path(output_dir).resolve()

        # Run pdflatex
        try:
            result = subprocess.run(
                [
                    "pdflatex",
                    "-interaction=nonstopmode",
                    f"-output-directory={output_path}",
                    str(tex_path),
                ],
                capture_output=True,
                text=True,
                check=True,
            )
        except subprocess.CalledProcessError as e:
            raise RuntimeError(
                f"pdflatex compilation failed:\n{e.stderr}\n\nOutput:\n{e.stdout}"
            ) from e

        # Return path to PDF
        pdf_path = output_path / tex_path.with_suffix(".pdf").name
        return str(pdf_path)

render(data, scope=None)

Render the complete tikzpicture.

Source code in src/texer/pgfplots.py 
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
def render(self, data: Any, scope: dict[str, Any] | None = None) -> str:
    """Render the complete tikzpicture."""
    if scope is None:
        scope = {}

    lines = []

    # Preamble (for standalone use)
    for line in self.preamble:
        lines.append(line)

    # Build tikzpicture options
    options = {}
    if self.scale is not None:
        options["scale"] = self.scale

    opts_str = format_options(options, self._raw_options)

    # Opening
    if opts_str:
        lines.append(f"\\begin{{tikzpicture}}[{opts_str}]")
    else:
        lines.append("\\begin{tikzpicture}")

    # Axis content
    axis_lines = self.axis.render(data, scope)
    for line in axis_lines.split("\n"):
        lines.append(f"  {line}" if line else line)

    # Closing
    lines.append("\\end{tikzpicture}")

    return "\n".join(lines)

with_preamble(data=None)

Return LaTeX code including package imports for standalone use.

Parameters:

Name Type Description Default
data Any

Optional data dict for rendering (default: empty dict).

 None
Source code in src/texer/pgfplots.py 
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
def with_preamble(self, data: Any = None) -> str:
    """Return LaTeX code including package imports for standalone use.

    Args:
        data: Optional data dict for rendering (default: empty dict).
    """
    if data is None:
        data = {}

    preamble = [
        "\\documentclass{standalone}",
        "\\usepackage{pgfplots}",
        "\\pgfplotsset{compat=1.18}",
        "\\usepgfplotslibrary{groupplots}",
        "",
        "\\begin{document}",
    ]
    content = self.render(data)
    closing = ["\\end{document}"]

    return "\n".join(preamble + [content] + closing)

save_to_file(file_path, data=None, with_preamble=True)

Save the LaTeX code to a file.

Parameters:

Name Type Description Default
file_path str

Path to the output .tex file.

 required
data Any

Optional data dict for rendering (default: empty dict).

 None
with_preamble bool

Whether to include document preamble for standalone compilation (default: True).

 True

Examples:

Save with preamble for standalone compilation

plot.save_to_file("my_plot.tex")

Save just the tikzpicture content

plot.save_to_file("my_plot.tex", with_preamble=False)

Save with data

plot.save_to_file("my_plot.tex", data=my_data)

Source code in src/texer/pgfplots.py 
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
def save_to_file(
    self,
    file_path: str,
    data: Any = None,
    with_preamble: bool = True,
) -> None:
    """Save the LaTeX code to a file.

    Args:
        file_path: Path to the output .tex file.
        data: Optional data dict for rendering (default: empty dict).
        with_preamble: Whether to include document preamble for standalone compilation (default: True).

    Examples:
        # Save with preamble for standalone compilation
        plot.save_to_file("my_plot.tex")

        # Save just the tikzpicture content
        plot.save_to_file("my_plot.tex", with_preamble=False)

        # Save with data
        plot.save_to_file("my_plot.tex", data=my_data)
    """
    if data is None:
        data = {}

    if with_preamble:
        latex_code = self.with_preamble(data)
    else:
        latex_code = self.render(data)

    with open(file_path, "w", encoding="utf-8") as f:
        f.write(latex_code)

compile_to_pdf(tex_file_path, data=None, output_dir=None)

Save to .tex file and compile to PDF using pdflatex.

Parameters:

Name Type Description Default
tex_file_path str

Path to save the .tex file (e.g., "my_plot.tex").

 required
data Any

Optional data dict for rendering (default: empty dict).

 None
output_dir str | None

Optional output directory for compilation (default: same as .tex file).

 None

Returns:

Type Description
str

Path to the generated PDF file.

Raises:

Type Description
RuntimeError

If pdflatex is not available or compilation fails.

Examples:

Simple compilation

pdf_path = plot.compile_to_pdf("my_plot.tex")

With data

pdf_path = plot.compile_to_pdf("my_plot.tex", data=my_data)

Specify output directory

pdf_path = plot.compile_to_pdf("my_plot.tex", output_dir="/tmp")

Source code in src/texer/pgfplots.py 
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
def compile_to_pdf(
    self,
    tex_file_path: str,
    data: Any = None,
    output_dir: str | None = None,
) -> str:
    """Save to .tex file and compile to PDF using pdflatex.

    Args:
        tex_file_path: Path to save the .tex file (e.g., "my_plot.tex").
        data: Optional data dict for rendering (default: empty dict).
        output_dir: Optional output directory for compilation (default: same as .tex file).

    Returns:
        Path to the generated PDF file.

    Raises:
        RuntimeError: If pdflatex is not available or compilation fails.

    Examples:
        # Simple compilation
        pdf_path = plot.compile_to_pdf("my_plot.tex")

        # With data
        pdf_path = plot.compile_to_pdf("my_plot.tex", data=my_data)

        # Specify output directory
        pdf_path = plot.compile_to_pdf("my_plot.tex", output_dir="/tmp")
    """
    import subprocess
    import shutil
    from pathlib import Path

    # Check if pdflatex is available
    if shutil.which("pdflatex") is None:
        raise RuntimeError(
            "pdflatex not found. Please install a LaTeX distribution (e.g., TeX Live, MiKTeX)."
        )

    # Save to file
    self.save_to_file(tex_file_path, data=data, with_preamble=True)

    # Determine paths
    tex_path = Path(tex_file_path).resolve()
    output_path: Path
    if output_dir is None:
        output_path = tex_path.parent
    else:
        output_path = Path(output_dir).resolve()

    # Run pdflatex
    try:
        result = subprocess.run(
            [
                "pdflatex",
                "-interaction=nonstopmode",
                f"-output-directory={output_path}",
                str(tex_path),
            ],
            capture_output=True,
            text=True,
            check=True,
        )
    except subprocess.CalledProcessError as e:
        raise RuntimeError(
            f"pdflatex compilation failed:\n{e.stderr}\n\nOutput:\n{e.stdout}"
        ) from e

    # Return path to PDF
    pdf_path = output_path / tex_path.with_suffix(".pdf").name
    return str(pdf_path)

SemiLogXAxis dataclass

Bases: Axis

A semi-logarithmic axis (log scale on x-axis).

Source code in src/texer/pgfplots.py 
1265
1266
1267
1268
1269
@dataclass
class SemiLogXAxis(Axis):
    """A semi-logarithmic axis (log scale on x-axis)."""

    axis_type: Literal["axis", "semilogxaxis", "semilogyaxis", "loglogaxis"] = "semilogxaxis"

SemiLogYAxis dataclass

Bases: Axis

A semi-logarithmic axis (log scale on y-axis).

Source code in src/texer/pgfplots.py 
1272
1273
1274
1275
1276
@dataclass
class SemiLogYAxis(Axis):
    """A semi-logarithmic axis (log scale on y-axis)."""

    axis_type: Literal["axis", "semilogxaxis", "semilogyaxis", "loglogaxis"] = "semilogyaxis"

LogLogAxis dataclass

Bases: Axis

A log-log axis (log scale on both axes).

Source code in src/texer/pgfplots.py 
1279
1280
1281
1282
1283
@dataclass
class LogLogAxis(Axis):
    """A log-log axis (log scale on both axes)."""

    axis_type: Literal["axis", "semilogxaxis", "semilogyaxis", "loglogaxis"] = "loglogaxis"

simple_plot(x, y, xlabel='x', ylabel='y', title=None, color='blue', mark='*', precision=6)

Create a simple line plot from x and y data.

Parameters:

Name Type Description Default
x list[float]

X-axis data points.

 required
y list[float]

Y-axis data points.

 required
xlabel str

Label for x-axis.

 'x'
ylabel str

Label for y-axis.

 'y'
title str | None

Optional plot title.

 None
color str

Line/marker color.

 'blue'
mark str

Marker style.

 '*'
precision int | None

Number of significant figures for coordinates (default: 6, None for no rounding).

 6

Returns:

Type Description
PGFPlot

A PGFPlot object ready for rendering.
Source code in src/texer/pgfplots.py 
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
def simple_plot(
    x: list[float],
    y: list[float],
    xlabel: str = "x",
    ylabel: str = "y",
    title: str | None = None,
    color: str = "blue",
    mark: str = "*",
    precision: int | None = 6,
) -> PGFPlot:
    """Create a simple line plot from x and y data.

    Args:
        x: X-axis data points.
        y: Y-axis data points.
        xlabel: Label for x-axis.
        ylabel: Label for y-axis.
        title: Optional plot title.
        color: Line/marker color.
        mark: Marker style.
        precision: Number of significant figures for coordinates (default: 6, None for no rounding).

    Returns:
        A PGFPlot object ready for rendering.
    """
    coords = Coordinates(list(zip(x, y)), precision=precision)

    return PGFPlot(
        Axis(
            xlabel=xlabel,
            ylabel=ylabel,
            title=title,
            plots=[AddPlot(color=color, mark=mark, coords=coords)],
        )
    )

scatter_plot(x, y, marker_size, xlabel='x', ylabel='y', title=None, color='blue', mark='*', precision=6)

Create a scatter plot with data-driven marker sizes (bubble chart).

Parameters:

Name Type Description Default
x list[float]

X-axis data points.

 required
y list[float]

Y-axis data points.

 required
marker_size list[float]

Marker size for each data point (in pt units).

 required
xlabel str

Label for x-axis.

 'x'
ylabel str

Label for y-axis.

 'y'
title str | None

Optional plot title.

 None
color str

Marker color.

 'blue'
mark str

Marker style.

 '*'
precision int | None

Number of significant figures for coordinates (default: 6, None for no rounding).

 6

Returns:

Type Description
PGFPlot

A PGFPlot object ready for rendering.

Examples:

Create a bubble chart

plot = scatter_plot( x=[1, 2, 3, 4, 5], y=[2, 4, 3, 5, 4], marker_size=[5, 10, 15, 20, 25], xlabel="X Value", ylabel="Y Value", title="Bubble Chart" ) print(plot.render({}))

Source code in src/texer/pgfplots.py 
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
def scatter_plot(
    x: list[float],
    y: list[float],
    marker_size: list[float],
    xlabel: str = "x",
    ylabel: str = "y",
    title: str | None = None,
    color: str = "blue",
    mark: str = "*",
    precision: int | None = 6,
) -> PGFPlot:
    """Create a scatter plot with data-driven marker sizes (bubble chart).

    Args:
        x: X-axis data points.
        y: Y-axis data points.
        marker_size: Marker size for each data point (in pt units).
        xlabel: Label for x-axis.
        ylabel: Label for y-axis.
        title: Optional plot title.
        color: Marker color.
        mark: Marker style.
        precision: Number of significant figures for coordinates (default: 6, None for no rounding).

    Returns:
        A PGFPlot object ready for rendering.

    Examples:
        # Create a bubble chart
        plot = scatter_plot(
            x=[1, 2, 3, 4, 5],
            y=[2, 4, 3, 5, 4],
            marker_size=[5, 10, 15, 20, 25],
            xlabel="X Value",
            ylabel="Y Value",
            title="Bubble Chart"
        )
        print(plot.render({}))
    """
    coords = Coordinates(x=x, y=y, marker_size=marker_size, precision=precision)

    return PGFPlot(
        Axis(
            xlabel=xlabel,
            ylabel=ylabel,
            title=title,
            plots=[
                AddPlot(
                    color=color,
                    mark=mark,
                    only_marks=True,
                    scatter=True,
                    coords=coords,
                )
            ],
        )
    )