plotext plots data directly on terminal
Project description
The package plotext
allows to plot data directly on terminal.
Basic Example
You can use plotext
to plot directly on terminal, as you would normally with matplotlib
. Here is a basic example on how to use it:
import plotext.plot as plx
plx.scatter(x, y)
plx.show()
where x
and y
are the lists for the of points coordinates; optionally, a single y
list could be provided. Alternatively, you could plot data points with lines connecting them using the plot
function instead of the scatter
one. Multiple data set could also be plotted using consecutive scatter
or plot
functions. Here is an output example:
Each data point is represented by a character (in this case a •
).
Installation
To install the latest version of the plotext
package use the following command:
sudo H pip install plotext
Parameters
You can personalize the plots in different ways using the scatter
and plot
function parameters. Here they are:

cols It sets the number of columns of the plot. Only integers are allowed. By default, it is set to the highest value allowed by the the terminal size. Alternatively you could set the number of rows using
set_cols(cols)
after the scatter function. 
rows It sets the number of rows of the plot. Only integers are allowed. By default, it is set to the highest value allowed by the the terminal size. Alternatively you could set the number of columns using
set_rows(rows)
after thescatter
orplot
function. 
force_size The plot dimensions are limited by the terminal size, when
force_size
is False and are allowed to be bigger otherwise. The default value isFalse
. Alternatively you could setforce_size
usingset_force_size(force_size)
after thescatter
orplot
function but beforeset_cols(cols)
andset_rows(rows)
. 
xlim It sets the minimum and maximum limits of the plot in the
x
axis. It requires a list of two numbers, where the first sets the left (minimum) limit and the second the right (maximum) limit. If one or both values are not provided, they are calculated automatically. Alternatively you could useset_xlim(xlim)
after thescatter
orplot
function. 
ylim It sets the minimum and maximum limits of the plot in the
y
axis. It requires a list of two numbers, where the first sets the lower (minimum) limit and the second the upper (maximum) limit. If one or both values are not provided, they are calculated automatically. Alternatively you could useset_ylim(ylim)
after thescatter
orplot
function. 
point When
True
, the plot shows the scatter data points. The default value isTrue
. 
point_marker It sets the marker used to identify each data point on the plot. Only single characters are allowed (eg:
'*'
). The default value is'•'
. 
point_color It sets the color used for the point marker. Use
get_colors()
to find the available color codes. The default value is'norm'
. 
line When True, the plot shows the lines between each data points. The default value is
False
. 
line_marker It sets the marker used to identify the lines between data points. Only single characters are allowed (eg:
'*')
. The default value is'•'
. 
line_color It sets the color used for the line marker. Use
get_colors()
to find the available color codes. The default value is'norm'
. 
background It sets the plot background color. Use
get_colors()
to find the available color codes. The default value is'norm'
. Alternatively you could set the background color usingset_background(background)
after thescatter
orplot
function. 
axes When True, the
x
andy
axes are added to the plot. A list of two Boolean will set thex
andy
axes separately (eg:axes = [True, False]
). The default value isTrue
. 
axes_color It sets the color of the axes, ticks and equations, when present. Use
get_colors()
to find the available color codes. The default value is'norm'
. Alternatively you could set the axes color usingset_axes_color(axes_color)
after the scatter function. 
ticks When
True
, thex
andy
ticks are added to the respective axes (even when absent). A list of two Boolean will set thex
andy
ticks separately (eg:ticks = [True, False]
). The default value isTrue
. 
spacing It sets the spacing between the
x
andy
ticks. When a list of two numbers is given, the spacing of thex
andy
ticks are set separately (eg:spacing = [5, 8]
). Only positive integers are allowed. The default value is[10, 5]
. Alternatively you could useset_spacing(spacing)
after thescatter
orplot
function. 
equations When
True
, the equations  needed to to find the realx
andy
values from the plot coordinates  are added at the end of the plot. The default value isFalse
. 
decimals It sets the number of decimal points shown in the equations. Only positive integers are allowed. The default value is
2
. Alternatively you could set the decimal points usingset_decimals(decimals)
after thescatter
orplot
function.
Save Plot
You can save your plot, as a text file, using plx.savefig(path)
where path
is the file address where the data will be written. Note that (for now), this function doesn't preserve the plot colors.
Streaming Data
The following functions are useful for example when continuously plotting a stream of data.
In order to clear the plot canvas use:
plx.clear_plot()
and to clear the terminal use:
plx.clear_terminal()
A common problem when plotting streaming data is the screen flickering. In order to remove or reduce this problem use:
plx.sleep(time)
which adds a sleeping time to the computation. An input of, for example, 0.01
would add approximately 0.01
secs to the computation. The time
parameters will depend on your processor speed and it needs some manual tweaking.
Here is an example of plotting a continuous stream of data:
Equations
As previously written, you could add two equations at the end of the plot to transform the column and row coordinatesdisplayeddisplayed into real x
and y
coordinates. Here is an example of a plot with equations at the end:
The errors in the equations are due to the fact that the pixel size reduces the resolution of the data displayed.
Alternatively you could access the functions plx.get_x_from_col(col)
and plx.get_y_from_row(row)
to make python do the transformation from your chosen column and row to real, respectively, x
and y
coordinates.
Colors
You can access the function plx.get_colors()
in order to find the available full ground and background color codes. Here is the output for simplicity:
Test
You can run a simple initial test of your newly installed package, to check that plotext
works well in your machine. Just use plx.run_test()
Version
In order to check the installed version of the package use the command plx.get_version()
Other Documentation
The full documentation of any of the functions shown above could be accessed using commands like these:
print(plx.scatter.__doc__)
print(plx.plot.__doc__)
print(plx.show.__doc__)
Main Updates:
plotext
now works also in Windows comand line (CMD) with colorsplotext
now works also using Python IDLE3 but with no colors and no adaptive dimensions new color codes with background codes added
force_size
option addedsavefig
function addedget_version
function addedrun_test
function added no need for
numpy
ortime
packages  the code has been updated and it is more legible
 the documentation has been updated
equations
options now is set by default toFalse
 When
thick
isFalse
, the axes non numerical thicks are also removed  Removed get functions for plot parameters
Creator
 Author: Savino Piccolomo
 email: piccolomo@gmail.com
Contributors
 Dominik Wetzel, Schmetzler for the Windows support
 Dominik Wetzel for force_size idea
 Kexul, Madrian for their inputs regarding plotting multiple lines
Project details
Release history Release notifications  RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.