plotille 1.5

Plot in the terminal using braille dots.

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 only – 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=50, X_label='X', Y_label='Y', linesep=os.linesep, interp='linear')
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.
interp: Optional[str] Specify interpolation; values None, 'linear'

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=50, X_label=u'X', Y_label=u'Y', linesep=os.linesep)
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.

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
**Histogram:**

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=50, width=80, log_scale=False, linesep=os.linesep)
Docstring:
Create histogram over `X`

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.

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: Histogram example

Histogram 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