Skip to main content

TikZ-based Figure Generator

There is a need for professional-looking figures. Good quality figures in publications are clear and easy to understand. This means they should not be badly pixelated. Though it is tempting to take a screen shot of your figures to then include in your papers, this is a sure way to produce poor-quality images. Often, the text will be hard to read, the lines will be pixelated, and important details will be lost. One solution to this is vector-based figures. Tools like MatPlotLib can already generate vector pdf images. However, this raises another problem. Vector plots of large data sets can consume significant disk space because every point is represented, even if such details cannot be seen. Even in a paper with only a few figures each megabyte large, can become too large to email. This is very a practical concern.

A typical journal paper column width is only about 3.4 in (8.636 cm). This means figures which are large on your screen with reasonably-sized text will be illegible when put into a paper. When the text of axis labels, tick labels, and legends is made large enough to read, it will take up much valuable space that would be better spent on the actual content of the figure. On top of that, libraries like MatPlotLib will impose generous margins around the figure, which further consume space. And when these margins are made smaller, there is no guarantee that some of the text will not be cut off.

Even without considering these problems, the text of typical figures will not match the typeface of the rest of your document, especially if your document is written in LaTeX, which uses its own fonts.

This library solves all these problems. It produces vector-based figures using the popular LaTeX plugin called TikZ. The output files are native LaTeX files, so all the text and formatting should be consistent with the rest of your document. By default, this library automatically performs fast line-simplification to produce the same look with less data. So, large data sets can be plotted without consuming much disk space. By default, tick labels are moved inside the plotting box so more space is used for the actual plotting. Legends are moved to the bottom of the figure, beneath the x-axis label. This way, text can be large enough to be legible without taking away valuable space from the content of the figure. The space required for axis labels, tick labels, and legends is carefully calculated ensuring just the right amount of space is provided around the content of the figure. This ensures the overall figure size matches exactly what was requested by the user.

Currently, the most commonly used plotting types are supported: plots, scatter plots, fills, and heat maps (in the form of hexagonal binning). However, much more is planned for the future.

Example

The following is a code example for creating a plot with this library:

import numpy as np
import tkz

t = np.linspace(0, 2*np.pi, 10000)
x = np.cos(t)
y = np.sin(t)

fig = tkz.graph('test_basic')
fig.plot(x, y)
fig.xlabel = 'x axis'
fig.ylabel = 'y axis'
fig.equal = True
fig.render()

First, a figure object is created with tkz.graph(). This object holds settings pertaining to the whole figure, like the width, height, and font size. Second, path objects are added with fig.plot(). This object holds everything pertaining to a particular path, like the x and y arrays, the line width, color, opacity, pattern style, and label. To render the figure, the .render() method is called on the fig object. Note, the default setting is for the LaTeX file to be generated as a standalone file with its own document class declaration and preamble. When it is standalone, this Python library will then try to automatically compile the LaTeX file with the lualatex command. If tkz.config.standalone is set to False then only the TikZ draw commands will be included. This file can then be input within the tikzpicture environment of another LaTeX file.

Global Options

tkz.config.<option> = <value>

There are some options you can set for all figures in your file:

Option Description Default Value
skip flag to skip all subsequent plotting False
directory directory of the generated figure files None
standalone flag to create standalone LaTeX file True
savetex flag to keep the LaTeX source file False
savepng flag to convert pdf to png too False
colormap color map for each subsequent plot curve tkz.MAP_WHEEL

Because compiling LaTeX files can be slow, it might be helpful sometimes to turn off all tkz renders. This can be done by setting tkz.config.skip to True. If tkz.config.directory is left as None then the figures will be generated in the current working directory. If the tka.config.standalone flag is True, this library will attempt to call the lualatex command line program to compile the .tex file and produce a pdf image automatically when the render method is called. Because you may need a rasterized version of your figure after all (see the Windows' Microsoft Office's lack of support for pdf vector images), the tkz.config.savepng option will produce a png version of the image from the pdf version. This requires the program pdftoppm from the poppler command line utilities package, and that the tkz.config.standalone option is set to True. By default, after a standalone LaTeX file is created and the pdf file is compiled, the source LaTeX file will be deleted. If you want to save the LaTeX file for inspection or tweaking, set the tkz.config.savetex option to True.

Figure Options

fig = tkz.graph(<options>)

All of the following options can be set after the graph object is created or during as class arguments.

Property Description Default Value
filename string of file without extension 'fig'
width width of pdf image in centimeters 8.636 cm (3.4 in)
height height of pdf image in centimeters 5.337 cm (2.1 in)
xmin x-axis minimum min of x
xmax x-axis maximum max of x
ymin y-axis minimum min of y
ymax y-axis maximum max of y
xpad use padding on x axis False
ypad use padding on y axis True
xlog flag to use log scaling on x axis False
ylog flag to use log scaling on y axis False
equal flag to use axis equal scaling False
fontsize font size in points 9 pt
xlabel x-axis label None
ylabel y-axis label None
xaxis flag to show x axis True
yaxis flag to show y axis True
xgrid flag to show x grid True
ygrid flag to show y grid True
xsubgrid flag to show x sub-grid True
ysubgrid flag to show y sub-grid True
xtick flag to show x ticks True
ytick flag to show y ticks True
ticksize size of tick marks (cm) 0.1 cm
xout flag to put x-axis ticks outside False
yout flag to put y-axis ticks outside False
rowmajor flag to layout legend row-major False
columns number of legend columns None
preamble added string of LaTeX code in preamble None

If either the width or height is specified, but not both, the other dimension will be calculated based on the golden aspect ratio.

Setting equal to True is equivalent to plt.axis('equal') in MatPlotLib.

Plotting Options

Plot

graph.plot(x, y=None, color=None, opacity=1.0, width=THICK,
        pattern=None, label=None, simp=True, fmt=None):

Create a graph of a connected path defined by x and y. If y is not provided, the values in x will be used as the y values and the integer indices will be used for the x values.

  • color should be a 6-character hexadecimal value for the color in the form 0xRRGGBB. If color is not given, a value will automatically be chosen from the color map.

  • opacity should be a floating-point value between 0 and 1.

  • width is the line width in points. The following values are predefined:

    Name Pixels
    THINEST 0.05
    ULTRA_THIN 0.10
    VERY_THIN 0.20
    THIN 0.40
    SEMI_THICK 0.60
    THICK 0.80
    VERY_THICK 1.20
    ULTRA_THICK 1.60
    THICKEST 100.00
  • pattern is the line pattern index. The following values are predefined.

    Name Index Pattern
    SOLID 0 ----
    DASHDOTTED 1 -.-.
    DASHED 2 - -
    DENSELYDOTTED 3 ....
    DOTTED 4 . .
    LOOSELYDOTTED 5 . .
  • label is the text with which to identify the path in the legend. Unlike MatPlotLib, if any path object has a label defined, a legend will be created. There is no additional legend command required.

  • simp is the boolean flag used to control whether the path will be subject to line simplification.

  • fmt is an optional string used to specify any additional formatting options which TikZ would understand. This option is meant for users who are experienced using the TikZ library.

Scatter

graph.scatter(x, y=None, radius=0.03, color=None, opacity=1.0,
        marker=CIRCLES, label=None, fmt=None)

Create a scatter plot of circles or dots defined by x and y. If y is not provided, the values in x will be used as the y values and the integer indices will be used for the x values.

  • radius is the radius of the circles or dots in units of points.

  • color should be a 6-character hexadecimal value for the color in the form 0xRRGGBB. If color is not given, a value will automatically be chosen from the color map.

  • opacity should be a floating-point value between 0 and 1.

  • marker is the style of the scatter plot. More styles might be added in the future, but for now the possible values are

    Name Index
    CIRCLES 0
    DOTS 1
  • label is the text with which to identify the path in the legend. Unlike MatPlotLib, if any path object has a label defined, a legend will be created. There is no additional legend command required.

  • fmt is an optional string used to specify any additional formatting options which TikZ would understand. This option is meant for users who are experienced using the TikZ library.

Note that no simp option is available, because it would not make sense for there to be.

Fill

graph.fill(x, y=None, z=None, color=None, opacity=1.0,
        label=None, simp=True, fmt=None)

Create a filled-area plot defined by x and y. If y is not provided, the values in x will be used as the y values and the integer indices will be used for the x values. If z is also provided, the area between y and z will be filled.

  • color should be a 6-character hexadecimal value for the color in the form 0xRRGGBB. If color is not given, a value will automatically be chosen from the color map.
  • opacity should be a floating-point value between 0 and 1.
  • label is the text with which to identify the path in the legend. Unlike MatPlotLib, if any path object has a label defined, a legend will be created. There is no additional legend command required.
  • simp is the boolean flag used to control whether the path will be subject to line simplification.
  • fmt is an optional string used to specify any additional formatting options which TikZ would understand. This option is meant for users who are experienced using the TikZ library.

No edge options exist, but it is simple enough to create another plot on top of a filled-area, providing the edges. This in fact does not consume any more disk space than having a single fill command with edges.

Hex Bin

graph.hexbin(x, y=None, radius=0.2, color=None, opacity=1.0, scaling=0,
        label=None, fmt=None)

Create a 2D mesh of hexagons, representing the binning of the values in x and y. If y is not provided, the values in x will be used as the y values and the integer indices will be used for the x values.

  • radius is the distance from the center of the hexagon to any vertex of the hexagon in units of centimeters. By default, hexagons with higher bin values will be more saturated with whatever the color is that is chosen for that path. Hexagons with lower bin values will be more white, blending into the color of the background. However, if radius is negative, then rather than varying the color saturation, the hexagons will vary their size. The hexagons with the highest bin values will be the full radius in size. Hexagons with lower bin values will be smaller.
  • color should be a 6-character hexadecimal value for the color in the form 0xRRGGBB. If color is not given, a value will automatically be chosen from the color map.
  • opacity should be a floating-point value between 0 and 1.
  • scaling represents a bending of the otherwise linear relationship between the bin count and color saturation (or hexagon size). If scaling is greater than zero, color (size) will be skewed towards saturated (large). If scaling is less than zero, color (size) will be skewed towards white (small).
  • label is the text with which to identify the path in the legend. Unlike MatPlotLib, if any path object has a label defined, a legend will be created. There is no additional legend command required.
  • fmt is an optional string used to specify any additional formatting options which TikZ would understand. This option is meant for users who are experienced using the TikZ library.

Note that no simp option is available, because it is unnecessary since all the points are compressed into bins.

Percentile Bands

graph.bands(x, y=None, color=AZURE, opacity=0.2, label=None, simp=False,
        fmt=None, percentiles=[0.135,99.87, 2.28,97.73, 15.87,84.13]):

Create a plot of multiple, overlapping fill areas corresponding to pairs of percentiles. So, using the default value for percentiles, the first band would represent all data from the 0.135% to the 99.87% of values at any given x value. If the y data is 2D, percentiles will be calculated across rows. If the y data is 1D, it will be reshaped to produce enough rows for the percentiles to be calculated.

  • color should be a 6-character hexadecimal value for the color in the form 0xRRGGBB. If color is not given, a value will automatically be chosen from the color map.
  • opacity should be a floating-point value between 0 and 1.
  • label is the text with which to identify the path in the legend. Unlike MatPlotLib, if any path object has a label defined, a legend will be created. There is no additional legend command required.
  • simp is the boolean flag used to control whether the path will be subject to line simplification. By default, this is set to False because the bands method already is greatly reducing the amount of data to write to the figure.
  • fmt is an optional string used to specify any additional formatting options which TikZ would understand. This option is meant for users who are experienced using the TikZ library.
  • percentiles is the list of pairs of percentile values (0 to 100) to use. Note, this list must be an even number of values.

Dual Axes

This library does not support dual axes. This is on purpose. See https://blog.datawrapper.de/dualaxis/.

Command-line Interface

This library also provides a CLI tool for converting csv files to figures:

tkzcsv [--options] csv-files

Metadata

Release files for tkz 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tkz 1.1.0
File Size Uploaded Provenance Actions
tkz-1.1.0.tar.gz 34.3 kB Without provenance Details for tkz-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tkz 1.1.0
File Interpreter ABI Platform Actions
tkz-1.1.0-py3-none-any.whl Python 3 none any Details for tkz-1.1.0-py3-none-any.whl

Total release size: 63.6 kB

Release files / tkz-1.1.0.tar.gz

Download URL tkz-1.1.0.tar.gz
Size 34.3 kB
Tags Source
SHA-256 checksum
How to use checksums
5af4c9019f4083ce7ff77e86a7f73fcc56d203531b0d61577e71dde7150770f4
BLAKE2b-256 checksum
How to use checksums
4040243f9a74189ede84914edfa7395ec2f8dc7582e463e706c90caea6159832
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.15

Release files / tkz-1.1.0-py3-none-any.whl

Download URL tkz-1.1.0-py3-none-any.whl
Size 29.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a63e87fe3d7de0b6c511ec589321d35f172be0234153c223fc5b7544aca51272
BLAKE2b-256 checksum
How to use checksums
15dc2cecd1761ae7702ff2cee0942023a518c0daea9b618bbc1e421268147358
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.15

Security for tkz 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page