Plot in the terminal using braille dots.
Project description
Plotille
========
|Build Status| |Coverage Status| |Tested CPython Versions| |Tested PyPy
Versions| |PyPi version| |PyPi license|
Plot, scatter plots and histograms in the terminal using braille dots,
with no external dependancies. For good visualization, use a font /
terminal with monospaced braille characters.
Install:
::
pipenv install plotille
Similar to other libraries:
- like `drawille <https://github.com/asciimoo/drawille>`__, but focused
on graphing – plus X/Y-axis.
- like `termplot <https://github.com/justnoise/termplot>`__, but with
braille (finer dots), left to right histogram and linear
interpolation for plotting function.
- like `termgraph <https://github.com/sgeisler/termgraph>`__ (not on
pypi), but very different style.
- like `terminalplot <https://github.com/kressi/terminalplot>`__, but
with braille, X/Y-axis, histogram, linear interpolation.
Documentation
-------------
.. code:: python
In [1]: import plotille
In [2]: import numpy as np
In [3]: X = sorted(np.random.normal(size=1000))
**Plot:**
.. code:: python
In [4]: plotille.plot?
Signature: plot(X, Y, width=80, height=40, X_label='X', Y_label='Y', linesep='\n', interp='linear', x_min=None, x_max=None, y_min=None, y_max=None)
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.
hight: 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 seperator. 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.
Returns:
str: plot over `X`, `Y`.
In [5]: print(plotille.plot(X, np.sin(X), height=50))
.. figure:: https://github.com/tammoippen/plotille/blob/master/imgs/plot.png
:alt: Plot example
Plot example
**Scatter:**
.. code:: python
In [6]: plotille.scatter?
Signature: scatter(X, Y, width=80, height=40, X_label='X', Y_label='Y', linesep='\n', x_min=None, x_max=None, y_min=None, y_max=None)
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.
hight: 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 seperator. default: os.linesep
x_min, x_max: float Limits for the displayed X values.
y_min, y_max: float Limits for the displayed Y values.
Returns:
str: scatter plot over `X`, `Y`.
In [7]: print(plotille.scatter(X, np.sin(X), height=50))
.. figure:: https://github.com/tammoippen/plotille/blob/master/imgs/scatter.png
:alt: Plot example
Plot example
**Hist:**
Inspired by
`crappyhist <http://kevinastraight.x10host.com/2013/12/28/python-histograms-from-the-console/>`__.
.. code:: python
In [8]: plotille.hist?
Signature: hist(X, bins=40, width=80, log_scale=False, linesep='\n')
Docstring:
Create histogram over `X` from left to right
The values on the left are the center of the bucket, i.e. `(bin[i] + bin[i+1]) / 2`.
The values on the right are the total counts of this bucket.
Parameters:
X: List[float] The items to count over.
bins: int The number of bins to put X entries in (rows).
width: int The number of characters for the width (columns).
log_scale: bool Scale the histogram with `log` function.
linesep: str The requested line seperator. default: os.linesep
Returns:
str: histogram over `X` from left to right.
In [9]: print(plotille.hist(np.random.normal(size=10000)))
.. figure:: https://github.com/tammoippen/plotille/blob/master/imgs/hist.png
:alt: Hist example
Hist example
**Histogram:**
There is also another more 'usual' histogram function available:
.. code:: python
In [10]: plotille.hist?
Signature: histogram(X, bins=160, width=80, height=40, X_label='X', Y_label='Counts', linesep='\n', x_min=None, x_max=None, y_min=None, y_max=None)
Docstring:
Create histogram over `X`
In contrast to `hist`, this is the more `usual` histogram from bottom
to up. The X-axis represents the values in `X` and the Y-axis is the
corresponding frequency.
Parameters:
X: List[float] The items to count over.
bins: int The number of bins to put X entries in (columns).
height: int The number of characters for the height (rows).
X_label: str Label for X-axis.
Y_label: str Label for Y-axis. max 8 characters.
linesep: str The requested line seperator. default: os.linesep
x_min, x_max: float Limits for the displayed X values.
y_min, y_max: float Limits for the displayed Y values.
Returns:
str: histogram over `X`.
In [11]: print(plotille.histogram(np.random.normal(size=10000)))
.. figure:: https://github.com/tammoippen/plotille/blob/master/imgs/histogram.png
:alt: Histogram example
Histogram example
**Canvas:**
The underlying plotting area is modeled as the ``Canvas`` class:
.. code:: python
In [12]: plotille.Canvas?
Init signature: Canvas(width, height, xmin=0, ymin=0, xmax=1, ymax=1)
Docstring:
A canvas object for plotting braille dots
A Canvas object has a `width` x `height` characters large canvas, in which it
can plot indivitual braille point, lines out of braille points, rectangles,...
Since a full braille character has 2 x 4 dots (⣿), the canvas has `width` * 2, `height` * 4
dots to plot into in total.
It maintains two coordinate systems: a reference system with the limits (xmin, ymin)
in the lower left corner to (xmax, ymax) in the upper right corner is transformed
into the canvas discrete, i.e. dots, coordinate system (0, 0) to (`width` * 2, `height` * 4).
It does so transparently to clients of the Canvas, i.e. all plotting functions
only accept coordinates in the reference system. If the coordinates are outside
the reference system, they are not plotted.
Init docstring:
Initiate a Canvas object
Parameters:
width: int The number of characters for the width (columns) of the canvas.
hight: int The number of characters for the hight (rows) of the canvas.
xmin, ymin: float Lower left corner of reference system.
xmax, ymax: float Upper right corner of reference system.
Reurns:
Canvas object
The most interesting functions are:
*point:*
.. code:: python
In [13]: plotille.Canvas.point?
Signature: Canvas.point(self, x, y, set_=True)
Docstring:
Put a point into the canvas at (x, y) [reference coordinate system]
Parameters:
x: float x-coordinate on reference system.
y: float y-coordinate on reference system.
set_: bool Whether to plot or remove the point.
*line:*
.. code:: python
In [14]: Canvas.line?
Signature: Canvas.line(self, x0, y0, x1, y1, set_=True)
Docstring:
Plot line between point (x0, y0) and (x1, y1) [reference coordinate system].
Parameters:
x0, y0: float Point 0
x1, y1: float Point 1
set_: bool Whether to plot or remove the line.
*rect:*
.. code:: python
In [15]: Canvas.rect?
Signature: Canvas.rect(self, xmin, ymin, xmax, ymax, set_=True)
Docstring:
Plot rectangle with bbox (xmin, ymin) and (xmax, ymax) [reference coordinate system].
Parameters:
xmin, ymin: float Lower left corner of rectangle.
xmax, ymax: float Upper right corner of rectangle.
set_: bool Whether to plot or remove the rect.
*plot:*
.. code:: python
In [16]: Canvas.plot?
Signature: Canvas.plot(self, x_axis=False, y_axis=False, y_label='Y', x_label='X', linesep='\n')
Docstring:
Transform canvas into `print`-able string
Parameters:
x_axis: bool Add a X-axis at the bottom.
y_axis: bool Add a Y-axis to the left.
y_label: str Label for Y-axis. max 8 characters.
x_label: str Label for X-axis.
linesep: str The requested line seperator. default: os.linesep
Returns:
unicode: The cancas as a string.
You can use it for example to plot a house in the terminal:
.. code:: python
In [17]: c = Canvas(width=40, height=20)
In [18]: c.rect(0.1, 0.1, 0.6, 0.6)
In [19]: c.line(0.1, 0.1, 0.6, 0.6)
In [20]: c.line(0.1, 0.6, 0.6, 0.1)
In [21]: c.line(0.1, 0.6, 0.35, 0.8)
In [22]: c.line(0.35, 0.8, 0.6, 0.6)
In [23]: print(c.plot())
.. figure:: https://github.com/tammoippen/plotille/blob/master/imgs/house.png
:alt: House example
House example
.. |Build Status| image:: https://travis-ci.org/tammoippen/plotille.svg?branch=master
:target: https://travis-ci.org/tammoippen/plotille
.. |Coverage Status| image:: https://coveralls.io/repos/github/tammoippen/plotille/badge.svg?branch=master
:target: https://coveralls.io/github/tammoippen/plotille?branch=master
.. |Tested CPython Versions| image:: https://img.shields.io/badge/cpython-2.7%2C%203.5%2C%203.6%2C%20nightly-brightgreen.svg
:target: https://img.shields.io/badge/cpython-2.7%2C%203.5%2C%203.6%2C%20nightly-brightgreen.svg
.. |Tested PyPy Versions| image:: https://img.shields.io/badge/pypy-2.7--5.8.0%2C%203.5--5.8.0-brightgreen.svg
:target: https://img.shields.io/badge/pypy-2.7--5.8.0%2C%203.5--5.8.0-brightgreen.svg
.. |PyPi version| image:: https://img.shields.io/pypi/v/plotille.svg
:target: https://pypi.python.org/pypi/plotille
.. |PyPi license| image:: https://img.shields.io/pypi/l/plotille.svg
:target: https://pypi.python.org/pypi/plotille
========
|Build Status| |Coverage Status| |Tested CPython Versions| |Tested PyPy
Versions| |PyPi version| |PyPi license|
Plot, scatter plots and histograms in the terminal using braille dots,
with no external dependancies. For good visualization, use a font /
terminal with monospaced braille characters.
Install:
::
pipenv install plotille
Similar to other libraries:
- like `drawille <https://github.com/asciimoo/drawille>`__, but focused
on graphing – plus X/Y-axis.
- like `termplot <https://github.com/justnoise/termplot>`__, but with
braille (finer dots), left to right histogram and linear
interpolation for plotting function.
- like `termgraph <https://github.com/sgeisler/termgraph>`__ (not on
pypi), but very different style.
- like `terminalplot <https://github.com/kressi/terminalplot>`__, but
with braille, X/Y-axis, histogram, linear interpolation.
Documentation
-------------
.. code:: python
In [1]: import plotille
In [2]: import numpy as np
In [3]: X = sorted(np.random.normal(size=1000))
**Plot:**
.. code:: python
In [4]: plotille.plot?
Signature: plot(X, Y, width=80, height=40, X_label='X', Y_label='Y', linesep='\n', interp='linear', x_min=None, x_max=None, y_min=None, y_max=None)
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.
hight: 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 seperator. 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.
Returns:
str: plot over `X`, `Y`.
In [5]: print(plotille.plot(X, np.sin(X), height=50))
.. figure:: https://github.com/tammoippen/plotille/blob/master/imgs/plot.png
:alt: Plot example
Plot example
**Scatter:**
.. code:: python
In [6]: plotille.scatter?
Signature: scatter(X, Y, width=80, height=40, X_label='X', Y_label='Y', linesep='\n', x_min=None, x_max=None, y_min=None, y_max=None)
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.
hight: 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 seperator. default: os.linesep
x_min, x_max: float Limits for the displayed X values.
y_min, y_max: float Limits for the displayed Y values.
Returns:
str: scatter plot over `X`, `Y`.
In [7]: print(plotille.scatter(X, np.sin(X), height=50))
.. figure:: https://github.com/tammoippen/plotille/blob/master/imgs/scatter.png
:alt: Plot example
Plot example
**Hist:**
Inspired by
`crappyhist <http://kevinastraight.x10host.com/2013/12/28/python-histograms-from-the-console/>`__.
.. code:: python
In [8]: plotille.hist?
Signature: hist(X, bins=40, width=80, log_scale=False, linesep='\n')
Docstring:
Create histogram over `X` from left to right
The values on the left are the center of the bucket, i.e. `(bin[i] + bin[i+1]) / 2`.
The values on the right are the total counts of this bucket.
Parameters:
X: List[float] The items to count over.
bins: int The number of bins to put X entries in (rows).
width: int The number of characters for the width (columns).
log_scale: bool Scale the histogram with `log` function.
linesep: str The requested line seperator. default: os.linesep
Returns:
str: histogram over `X` from left to right.
In [9]: print(plotille.hist(np.random.normal(size=10000)))
.. figure:: https://github.com/tammoippen/plotille/blob/master/imgs/hist.png
:alt: Hist example
Hist example
**Histogram:**
There is also another more 'usual' histogram function available:
.. code:: python
In [10]: plotille.hist?
Signature: histogram(X, bins=160, width=80, height=40, X_label='X', Y_label='Counts', linesep='\n', x_min=None, x_max=None, y_min=None, y_max=None)
Docstring:
Create histogram over `X`
In contrast to `hist`, this is the more `usual` histogram from bottom
to up. The X-axis represents the values in `X` and the Y-axis is the
corresponding frequency.
Parameters:
X: List[float] The items to count over.
bins: int The number of bins to put X entries in (columns).
height: int The number of characters for the height (rows).
X_label: str Label for X-axis.
Y_label: str Label for Y-axis. max 8 characters.
linesep: str The requested line seperator. default: os.linesep
x_min, x_max: float Limits for the displayed X values.
y_min, y_max: float Limits for the displayed Y values.
Returns:
str: histogram over `X`.
In [11]: print(plotille.histogram(np.random.normal(size=10000)))
.. figure:: https://github.com/tammoippen/plotille/blob/master/imgs/histogram.png
:alt: Histogram example
Histogram example
**Canvas:**
The underlying plotting area is modeled as the ``Canvas`` class:
.. code:: python
In [12]: plotille.Canvas?
Init signature: Canvas(width, height, xmin=0, ymin=0, xmax=1, ymax=1)
Docstring:
A canvas object for plotting braille dots
A Canvas object has a `width` x `height` characters large canvas, in which it
can plot indivitual braille point, lines out of braille points, rectangles,...
Since a full braille character has 2 x 4 dots (⣿), the canvas has `width` * 2, `height` * 4
dots to plot into in total.
It maintains two coordinate systems: a reference system with the limits (xmin, ymin)
in the lower left corner to (xmax, ymax) in the upper right corner is transformed
into the canvas discrete, i.e. dots, coordinate system (0, 0) to (`width` * 2, `height` * 4).
It does so transparently to clients of the Canvas, i.e. all plotting functions
only accept coordinates in the reference system. If the coordinates are outside
the reference system, they are not plotted.
Init docstring:
Initiate a Canvas object
Parameters:
width: int The number of characters for the width (columns) of the canvas.
hight: int The number of characters for the hight (rows) of the canvas.
xmin, ymin: float Lower left corner of reference system.
xmax, ymax: float Upper right corner of reference system.
Reurns:
Canvas object
The most interesting functions are:
*point:*
.. code:: python
In [13]: plotille.Canvas.point?
Signature: Canvas.point(self, x, y, set_=True)
Docstring:
Put a point into the canvas at (x, y) [reference coordinate system]
Parameters:
x: float x-coordinate on reference system.
y: float y-coordinate on reference system.
set_: bool Whether to plot or remove the point.
*line:*
.. code:: python
In [14]: Canvas.line?
Signature: Canvas.line(self, x0, y0, x1, y1, set_=True)
Docstring:
Plot line between point (x0, y0) and (x1, y1) [reference coordinate system].
Parameters:
x0, y0: float Point 0
x1, y1: float Point 1
set_: bool Whether to plot or remove the line.
*rect:*
.. code:: python
In [15]: Canvas.rect?
Signature: Canvas.rect(self, xmin, ymin, xmax, ymax, set_=True)
Docstring:
Plot rectangle with bbox (xmin, ymin) and (xmax, ymax) [reference coordinate system].
Parameters:
xmin, ymin: float Lower left corner of rectangle.
xmax, ymax: float Upper right corner of rectangle.
set_: bool Whether to plot or remove the rect.
*plot:*
.. code:: python
In [16]: Canvas.plot?
Signature: Canvas.plot(self, x_axis=False, y_axis=False, y_label='Y', x_label='X', linesep='\n')
Docstring:
Transform canvas into `print`-able string
Parameters:
x_axis: bool Add a X-axis at the bottom.
y_axis: bool Add a Y-axis to the left.
y_label: str Label for Y-axis. max 8 characters.
x_label: str Label for X-axis.
linesep: str The requested line seperator. default: os.linesep
Returns:
unicode: The cancas as a string.
You can use it for example to plot a house in the terminal:
.. code:: python
In [17]: c = Canvas(width=40, height=20)
In [18]: c.rect(0.1, 0.1, 0.6, 0.6)
In [19]: c.line(0.1, 0.1, 0.6, 0.6)
In [20]: c.line(0.1, 0.6, 0.6, 0.1)
In [21]: c.line(0.1, 0.6, 0.35, 0.8)
In [22]: c.line(0.35, 0.8, 0.6, 0.6)
In [23]: print(c.plot())
.. figure:: https://github.com/tammoippen/plotille/blob/master/imgs/house.png
:alt: House example
House example
.. |Build Status| image:: https://travis-ci.org/tammoippen/plotille.svg?branch=master
:target: https://travis-ci.org/tammoippen/plotille
.. |Coverage Status| image:: https://coveralls.io/repos/github/tammoippen/plotille/badge.svg?branch=master
:target: https://coveralls.io/github/tammoippen/plotille?branch=master
.. |Tested CPython Versions| image:: https://img.shields.io/badge/cpython-2.7%2C%203.5%2C%203.6%2C%20nightly-brightgreen.svg
:target: https://img.shields.io/badge/cpython-2.7%2C%203.5%2C%203.6%2C%20nightly-brightgreen.svg
.. |Tested PyPy Versions| image:: https://img.shields.io/badge/pypy-2.7--5.8.0%2C%203.5--5.8.0-brightgreen.svg
:target: https://img.shields.io/badge/pypy-2.7--5.8.0%2C%203.5--5.8.0-brightgreen.svg
.. |PyPi version| image:: https://img.shields.io/pypi/v/plotille.svg
:target: https://pypi.python.org/pypi/plotille
.. |PyPi license| image:: https://img.shields.io/pypi/l/plotille.svg
:target: https://pypi.python.org/pypi/plotille
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.
Source Distribution
plotille-2.0.tar.gz
(18.6 kB
view hashes)