Metadata-Version: 1.1
Name: plotille
Version: 2.1
Summary: Plot in the terminal using braille dots.
Home-page: https://github.com/tammoippen/plotille
Author: Tammo Ippen
Author-email: tammo.ippen@posteo.de
License: MIT
Download-URL: https://github.com/tammoippen/plotille/archive/v2.1.tar.gz
Description-Content-Type: UNKNOWN
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:
        
        .. code:: sh
        
            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/raw/master/imgs/hist.png
           :alt: 
        
        **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/raw/master/imgs/scatter.png
           :alt: 
        
        **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/raw/master/imgs/hist.png
           :alt: 
        
        **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/raw/master/imgs/histogram.png
           :alt: 
        
        **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/raw/master/imgs/house.png
           :alt: 
        
        .. |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
        
Keywords: plot,scatter,histogram,terminal,braille,unicode
Platform: UNKNOWN
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Terminals
