Plotille

Plots, scatter plots, histograms and heatmaps in the terminal using braille dots, and foreground and background colors - with no dependencies. Make complex figures using the Figure class or make fast and simple plots using graphing function - similar to a very small sibling to matplotlib. Or use the canvas to plot dots, lines and images yourself.

Install:

pip install plotille

Similar to other libraries:

• like drawille, but focused on graphing – plus X/Y-axis.
• like termplot, but with braille (finer dots), left to right histogram and linear interpolation for plotting function.
• like termgraph (not on pypi), but very different style.
• like terminalplot, but with braille, X/Y-axis, histogram, linear interpolation.

Basic support for timeseries plotting is provided with release 3.2: for any X or Y values you can also add datetime.datetime or numpy.datetime64 values. Labels are generated respecting the difference of x_limits and y_limits.

Support for heatmaps using background colors for figures and displaying images binary with braille, or in color with background colors using the canvas - provided with release 4.0

If you are still using python 2.7, please use plotille v4 or before. With v5 I am dropping support for python 2.7, as the effort to maintain the discontinued version is too much.

Documentation

In [1]: import plotille
In [2]: import numpy as np
In [3]: X = np.sort(np.random.normal(size=1000))

Figure

To construct plots the recommended way is to use a Figure:

In [4]: plotille.Figure?
Init signature: plotille.Figure() -> None
Docstring:
Figure class to compose multiple plots.

Within a Figure you can easily compose many plots, assign labels to plots
and define the properties of the underlying Canvas. Possible properties that
can be defined are:

    width, height: int           Define the number of characters in X / Y direction
                                 which are used for plotting.
    x_limits: DataValue          Define the X limits of the reference coordinate system,
                                 that will be plotted.
    y_limits: DataValue          Define the Y limits of the reference coordinate system,
                                 that will be plotted.
    color_mode: str              Define the used color mode. See `plotille.color()`.
    with_colors: bool            Define, whether to use colors at all.
    background: ColorDefinition  Define the background color.
    x_label, y_label: str        Define the X / Y axis label.```

Basically, you create a `Figure`, define the properties and add your plots. Using the `show()` function, the `Figure` generates the plot using a new canvas:

```python
In [13] fig = plotille.Figure()
In [14] fig.width = 60
In [15] fig.height = 30
In [16] fig.set_x_limits(min_=-3, max_=3)
In [17] fig.set_y_limits(min_=-1, max_=1)
In [18] fig.color_mode = 'byte'
In [19] fig.plot([-0.5, 1], [-1, 1], lc=25, label='First line')
In [20] fig.scatter(X, np.sin(X), lc=100, label='sin')
In [21] fig.plot(X, (X+2)**2 , lc=200, label='square')
In [22] print(fig.show(legend=True))

The available plotting functions are:

# create a plot with linear interpolation between points
Figure.plot(self, X, Y, lc=None, interp='linear', label=None, marker=None)
# create a scatter plot with no interpolation between points
Figure.scatter(self, X, Y, lc=None, label=None, marker=None)
# create a histogram over X
Figure.histogram(self, X, bins=160, lc=None)
# print texts at coordinates X, Y
Figure.text(self, X, Y, texts, lc=None)

# The following functions use relative coordinates on the canvas
# i.e. all coordinates are \in [0, 1]
# plot a vertical line at x
Figure.axvline(self, x, ymin=0, ymax=1, lc=None)
# plot a vertical rectangle from (xmin,ymin) to (xmax, ymax).
Figure.axvspan(self, xmin, xmax, ymin=0, ymax=1, lc=None)
# plot a horizontal line at y
Figure.axhline(self, y, xmin=0, xmax=1, lc=None)
# plot a horizontal rectangle from (xmin,ymin) to (xmax, ymax).
Figure.axhspan(self, ymin, ymax, xmin=0, xmax=1, lc=None)

# Display data as an image, i.e. on a 2D regular raster.
Figure.imgshow(self, X, cmap=None)

Other interesting functions are:

# remove all plots, texts, spans and images from the figure
Figure.clear(self)
# Create a canvas, plot the registered plots and return the string for displaying the plot
Figure.show(self, legend=False)

Please have a look at the examples/ folder.

Graphing

There are some utility functions for fast graphing of single plots.

Plot

In [4]: plotille.plot?
Signature:
plotille.plot(
    X: Sequence[float | int] | Sequence[datetime.datetime],
    Y: Sequence[float | int] | Sequence[datetime.datetime],
    width: int = 80,
    height: int = 40,
    X_label: str = 'X',
    Y_label: str = 'Y',
    linesep: str = '\n',
    interp: Optional[Literal['linear']] = 'linear',
    x_min: float | int | datetime.datetime | None = None,
    x_max: float | int | datetime.datetime | None = None,
    y_min: float | int | datetime.datetime | None = None,
    y_max: float | int | datetime.datetime | None = None,
    lc: Union[str, int, ColorNames, tuple[int, int, int], Sequence[int], NoneType] = None,
    bg: Union[str, int, ColorNames, tuple[int, int, int], Sequence[int], NoneType] = None,
    color_mode: Literal['names', 'byte', 'rgb'] = 'names',
    origin: bool = True,
    marker: str | None = None,
) -> str
Docstring:
Create plot with X , Y values and linear interpolation between points

Parameters:
    X: List[float]         X values.
    Y: List[float]         Y values. X and Y must have the same number of entries.
    width: int             The number of characters for the width (columns) of the
                           canvas.
    height: int            The number of characters for the hight (rows) of the
                           canvas.
    X_label: str           Label for X-axis.
    Y_label: str           Label for Y-axis. max 8 characters.    linesep: str           The requested line separator. default: os.linesep
    linesep: str           The requested line separator. default: os.linesep
    interp: Optional[str]  Specify interpolation; values None, 'linear'
    x_min, x_max: float    Limits for the displayed X values.
    y_min, y_max: float    Limits for the displayed Y values.
    lc: ColorDefinition           Give the line color.
    bg: ColorDefinition           Give the background color.
    color_mode: ColorMode        Specify color input mode; 'names' (default), 'byte' or
                           'rgb' see plotille.color.__docs__
    origin: bool           Whether to print the origin. default: True
    marker: str            Instead of braille dots set a marker char for actual
                           values.

Returns:
    str: plot over `X`, `Y`.

In [5]: print(plotille.plot(X, np.sin(X), height=30, width=60))

Scatter

In [6]: plotille.scatter?
Signature:
plotille.scatter(
    X: Sequence[float | int] | Sequence[datetime.datetime],
    Y: Sequence[float | int] | Sequence[datetime.datetime],
    width: int = 80,
    height: int = 40,
    X_label: str = 'X',
    Y_label: str = 'Y',
    linesep: str = '\n',
    x_min: float | int | datetime.datetime | None = None,
    x_max: float | int | datetime.datetime | None = None,
    y_min: float | int | datetime.datetime | None = None,
    y_max: float | int | datetime.datetime | None = None,
    lc: Union[str, int, ColorNames, tuple[int, int, int], Sequence[int], NoneType] = None,
    bg: Union[str, int, ColorNames, tuple[int, int, int], Sequence[int], NoneType] = None,
    color_mode: Literal['names', 'byte', 'rgb'] = 'names',
    origin: bool = True,
    marker: str | None = None,
) -> str
Docstring:
Create scatter plot with X , Y values

Basically plotting without interpolation:
    `plot(X, Y, ... , interp=None)`

Parameters:
    X: List[float]       X values.
    Y: List[float]       Y values. X and Y must have the same number of entries.
    width: int           The number of characters for the width (columns) of the
                         canvas.
    height: int          The number of characters for the hight (rows) of the
                         canvas.    X_label: str         Label