plotext Documentation

plotext is a library for plotting data directly in the terminal. It supports a wide range of visualization types and media playback:

• Main Plots: Scatter, line, bar, histogram, and date-time plots (including candlestick charts).
• Specialized Plots: Error bars and confusion matrices.
• Decorators: Adding text, lines, and shapes to existing plots.
• Media: Plotting images (including GIFs) and streaming video with audio (including YouTube).
• Utilities: Saving plots as text or colored HTML, coloring strings, and a dedicated command line tool.

Note: The library has no dependencies except for optional ones required for image and video plotting.

Common utility methods for managing the plot state:

• Display: Call show() to render the plot. Use interactive(True) to display the plot dynamically without calling show().
• Saving: Use savefig(path) to save the plot to a file.
• Clearing:
  • clear_figure(): Clears figure settings.
  • clear_data(): Clears data.
  • clear_color(): Clears color settings.
  • clear_terminal(): Clears the terminal screen.

Subplots in plotext can be nested, meaning any individual subplot can act as the parent for its own matrix of subplots. This allows for complex, hierarchical layouts.

To create a nested structure, call subplots() on an existing subplot. For example, to create a 2x2 matrix where the first subplot is itself a 3x4 matrix, you can use: plt.subplots(2, 2).subplot(1, 1).subplots(3, 4)

Note on batch operations: If you call a method on a subplot that is itself a matrix (a parent of other subplots), that method will be applied to all subplots within that matrix simultaneously. This is useful for applying consistent styling to a group of plots at once.

Use the following methods to customize your plots:

• Labels: title(), xlabel(), and ylabel().
• Markers: Use the marker parameter in plotting functions. High definition options include "hd", "fhd", and "braille".
• Colors: Use the color parameter for data points, or axes_color(), canvas_color(), and ticks_color() for axes/canvas styling. Use theme() for preset styles.
• Lines: grid(), horizontal_line(), or vertical_line().
• Axes: xaxes(), yaxes(), or frame() to add/remove axes. Use xfrequency()/xticks() and yfrequency()/yticks() to change numerical tick spacing.
• Dimensions: plotsize() to change the default terminal-adaptive size.

Integrating Plotext into a tkinter GUI involves rendering the plot to a canvas and then displaying it in a tk.Text widget.

Key steps:

1. Use plt.build() to generate the plot.
2. Access the raw canvas via plt._global.figure.monitor.matrix.canvas.
3. Use plotext._utility.uncolorize() to strip ANSI codes for the text widget.
4. To support colors in the GUI, iterate through the monitor matrix to get foreground and background colors, then use tk.Text tags (tag_add and tag_config) to apply colors to specific character coordinates.

When visualizing a continuous flow of data, use clearing methods and plt.sleep() to minimize screen flickering.

• plt.clt(): Clears the terminal.
• plt.cld(): Clears the data only.
• plt.sleep(): Adds a delay between frames.

import plotext as plt

l = 1000
frames = 200

plt.title("Streaming Data")

for i in range(frames):
    plt.clt() # to clear the terminal
    plt.cld() # to clear the data only

    y = plt.sin(periods = 2, length = l, phase = 2 * i  / frames)
    plt.scatter(y)

    plt.show()

Use the plt.plot() function to create a line plot. You can add a title using plt.title() and must call plt.show() to display the plot.

import plotext as plt
y = plt.sin()
plt.plot(y)
plt.title("Line Plot")
plt.show()

Data can be plotted on different axes using the xside and yside parameters in most plotting functions:

• xside: Choose between "lower" or "upper" (or 1 or 2).
• yside: Choose between "left" or "right" (or 1 or 2).

Legend entries will include a symbol to identify which pair of axes the data belongs to.

import plotext as plt

y1 = plt.sin()
y2 = plt.sin(2, phase = -1)

plt.plot(y1, xside = "lower", yside = "left", label = "lower left")
plt.plot(y2, xside = "upper", yside = "right", label = "upper right")

plt.title("Multiple Axes Plot")
plt.show()

This example demonstrates how to combine plot sizing, axis limits, and custom tick labeling with mathematical notation.

import plotext as plt
l, p = 300, 2
plt.plot(plt.sin(length = l, periods = p), label = "My Signal")
plt.plotsize(100, 30)
plt.title('Some Smart Title')
plt.xlabel('Time')
plt.ylabel('Movement')
plt.ticks_color('red')
plt.ticks_style('bold')
plt.xlim(-l//10, l + l//10)
plt.ylim(-1.5, 1.5)
xticks = [l * i / (2 * p)  for i in range(2 * p + 1)]
xlabels = [str(i) + "π" for i in range(2 * p + 1)]
plt.xticks(xticks, xlabels)
plt.yfrequency(5)
plt.show()