diff options
| author | CoprDistGit <infra@openeuler.org> | 2023-05-05 12:33:08 +0000 |
|---|---|---|
| committer | CoprDistGit <infra@openeuler.org> | 2023-05-05 12:33:08 +0000 |
| commit | 49ccd484479d8fe6a7f1ea1a186f8a4261931fb4 (patch) | |
| tree | 95cb4932d2b80ad1e3f33899d1c390030defd70c /python-plotille.spec | |
| parent | bf21ddd569a9536dfc4462620514f1eda6a8e67b (diff) | |
automatic import of python-plotilleopeneuler20.03
Diffstat (limited to 'python-plotille.spec')
| -rw-r--r-- | python-plotille.spec | 1905 |
1 files changed, 1905 insertions, 0 deletions
diff --git a/python-plotille.spec b/python-plotille.spec new file mode 100644 index 0000000..1a508ff --- /dev/null +++ b/python-plotille.spec @@ -0,0 +1,1905 @@ +%global _empty_manifest_terminate_build 0 +Name: python-plotille +Version: 5.0.0 +Release: 1 +Summary: Plot in the terminal using braille dots. +License: MIT +URL: https://github.com/tammoippen/plotille +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/8a/73/3f342572f7f916e387e546cc502d6cad35e7162ba0bcde203669e15aa3af/plotille-5.0.0.tar.gz +BuildArch: noarch + + +%description + + +# Plotille + +[](https://github.com/tammoippen/plotille/actions/workflows/CI.yml) +[](https://codecov.io/gh/tammoippen/plotille) +[](https://lgtm.com/projects/g/tammoippen/plotille/context:python) +[](https://img.shields.io/badge/cpython-3.7%2C%203.8%2C%203.9%2C%203.10%2C%203.11-brightgreen.svg) +[](https://img.shields.io/badge/pypy-3.8%2C%203.9-brightgreen.svg) +[](https://pypi.python.org/pypi/plotille) +[](https://pepy.tech/project/plotille) +[](https://pypi.python.org/pypi/plotille) + +Plots, scatter plots, histograms and heatmaps in the terminal using braille dots, and foreground and background colors - with no dependancies. 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: + +```sh +pip 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. + +Basic support for timeseries plotting is provided with release 3.2: for any `X` or `Y` values you can also add `datetime.datetime`, `pendulum.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 + +```python +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 recomended way is to use a `Figure`: + +```python +In [12]: plotille.Figure? +Init signature: plotille.Figure() +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: float Define the X limits of the reference coordinate system, + that will be plottered. + y_limits: float Define the Y limits of the reference coordinate system, + that will be plottered. + color_mode: str Define the used color mode. See `plotille.color()`. + with_colors: bool Define, whether to use colors at all. + background: multiple 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: + +```python +# 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: + +```python +# 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/`](./examples) folder. + +### Graphing + +There are some utility functions for fast graphing of single plots. + +#### Plot + +```python +In [4]: plotille.plot? +Signature: +plotille.plot( + X, + Y, + width=80, + height=40, + X_label='X', + Y_label='Y', + linesep=os.linesep, + interp='linear', + x_min=None, + x_max=None, + y_min=None, + y_max=None, + lc=None, + bg=None, + color_mode='names', + origin=True, + marker=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. + lc: multiple Give the line color. + bg: multiple Give the background color. + color_mode: str 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 + +```python +In [6]: plotille.scatter? +Signature: +plotille.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, + lc=None, + bg=None, + color_mode='names', + origin=True, + marker=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. + lc: multiple Give the line color. + bg: multiple Give the background color. + color_mode: str 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. + +Returns: + str: scatter plot over `X`, `Y`. + +In [7]: print(plotille.scatter(X, np.sin(X), height=30, width=60)) +``` + + + +#### Hist + +Inspired by [crappyhist](http://kevinastraight.x10host.com/2013/12/28/python-histograms-from-the-console/) (link is gone, but I made a [gist](https://gist.github.com/tammoippen/4474e838e969bf177155231ebba52386)). + +```python +In [8]: plotille.hist? +Signature: +plotille.hist( + X, + bins=40, + width=80, + log_scale=False, + linesep='\n', + lc=None, + bg=None, + color_mode='names', +) +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 + lc: multiple Give the line color. + bg: multiple Give the background color. + color_mode: str Specify color input mode; 'names' (default), 'byte' or 'rgb' + see plotille.color.__docs__ + +Returns: + str: histogram over `X` from left to right. + +In [9]: print(plotille.hist(np.random.normal(size=10000))) +``` + + + +#### Hist (aggregated) + +This function allows you to create a histogram when your data is already aggregated (aka you don't have access to raw values, but you have access to bins and counts for each bin). + +This comes handy when working with APIs such as [OpenTelemetry Metrics API](https://opentelemetry-python.readthedocs.io/en/latest/api/metrics.html) +where views such as [ExplicitBucketHistogramAggregation](https://opentelemetry-python.readthedocs.io/en/latest/sdk/metrics.view.html#opentelemetry.sdk.metrics.view.ExplicitBucketHistogramAggregation) +only expose access to aggregated values (counts for each bin / bucket). + +```python +In [8]: plotille.hist_aggregated? +Signature: +plotille.hist_aggregated( + counts, + bins, + width=80, + log_scale=False, + linesep='\n', + lc=None, + bg=None, + color_mode='names', +) +Docstring: +Create histogram for aggregated data. + +Parameters: + counts: List[int] Counts for each bucket. + bins: List[float] Limits for the bins for the provided counts: limits for + bin `i` are `[bins[i], bins[i+1])`. + Hence, `len(bins) == len(counts) + 1`. + 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 + lc: multiple Give the line color. + bg: multiple Give the background color. + color_mode: str Specify color input mode; 'names' (default), 'byte' or 'rgb' + see plotille.color.__docs__ +Returns: + str: histogram over `X` from left to right. + +In [9]: counts = [1945, 0, 0, 0, 0, 0, 10555, 798, 0, 28351, 0] +In [10]: bins = [float('-inf'), 10, 50, 100, 200, 300, 500, 800, 1000, 2000, 10000, float('+inf')] +In [11]: print(plotille.hist_aggregated(counts, bins)) +``` + +Keep in mind that there must always be n+1 bins (n is a total number of count values, 11 in the example above). + +In this example the first bin is from [-inf, 10) with a count of 1945 and the last bin is from [10000, +inf] with a count of 0. + + + +#### Histogram + +There is also another more 'usual' histogram function available: + +```python +In [10]: plotille.histogram? +Signature: +plotille.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, + lc=None, + bg=None, + color_mode='names', +) +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. + lc: multiple Give the line color. + bg: multiple Give the background color. + color_mode: str Specify color input mode; 'names' (default), 'byte' or 'rgb' + see plotille.color.__docs__ + +Returns: + str: histogram over `X`. + +In [11]: print(plotille.histogram(np.random.normal(size=10000))) +``` + + + +### Canvas + +The underlying plotting area is modeled as the `Canvas` class: + +```python +In [12]: plotille.Canvas? +Init signature: +plotille.Canvas( + width, + height, + xmin=0, + ymin=0, + xmax=1, + ymax=1, + background=None, + **color_kwargs, +) +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. + background: multiple Background color of the canvas. + **color_kwargs: More arguments to the color-function. See `plotille.color()`. + +Returns: + Canvas object +``` + +The most interesting functions are: + +_point:_ + +```python +In [11]: plotille.Canvas.point? +Signature: plotille.Canvas.point(self, x, y, set_=True, color=None, marker=None) +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. + color: multiple Color of the point. + marker: str Instead of braille dots set a marker char. +``` + +_line:_ + +```python +In [14]: plotille.Canvas.line? +Signature: plotille.Canvas.line(self, x0, y0, x1, y1, set_=True, color=None) +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. + color: multiple Color of the line. +``` + +_rect:_ + +```python +In [15]: plotille.Canvas.rect? +Signature: plotille.Canvas.rect(self, xmin, ymin, xmax, ymax, set_=True, color=None) +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. + color: multiple Color of the rect. +``` + +_text:_ + +```python +In [16]: plotille.Canvas.text? +Signature: plotille.Canvas.text(self, x, y, text, set_=True, color=None) +Docstring: +Put some text 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 set the text or clear the characters. + text: str The text to add. + color: multiple Color of the point. +``` + +_braille_image:_ + +```python +In [17]: plotille.Canvas.braille_image? +Signature: +plotille.Canvas.braille_image( + self, + pixels, + threshold=127, + inverse=False, + set_=True, +) +Docstring: +Print an image using braille dots into the canvas. + +The pixels and braille dots in the canvas are a 1-to-1 mapping, hence +a 80 x 80 pixel image will need a 40 x 20 canvas. + +Example: + from PIL import Image + import plotille as plt + + img = Image.open("/path/to/image") + img = img.convert('L') + img = img.resize((80, 80)) + cvs = plt.Canvas(40, 20) + cvs.braille_image(img.getdata(), 125) + print(cvs.plot()) + +Parameters: + pixels: list[number] All pixels of the image in one list. + threshold: float All pixels above this threshold will be + drawn. + inverse: bool Whether to invert the image. + set_: bool Whether to plot or remove the dots. +``` + +_image:_ + +```python +In [18]: plotille.Canvas.image? +Signature: plotille.Canvas.image(self, pixels, set_=True) +Docstring: +Print an image using background colors into the canvas. + +The pixels of the image and the characters in the canvas are a +1-to-1 mapping, hence a 80 x 80 image will need a 80 x 80 canvas. + +Example: + from PIL import Image + import plotille as plt + + img = Image.open("/path/to/image") + img = img.convert('RGB') + img = img.resize((40, 40)) + cvs = plt.Canvas(40, 40, mode='rgb') + cvs.image(img.getdata()) + print(cvs.plot()) + +Parameters: + pixels: list[(R,G,B)] All pixels of the image in one list. + set_: bool Whether to plot or remove the background + colors. +``` + +_plot:_ + +```python +In [16]: plotille.Canvas.plot? +Signature: plotille.Canvas.plot(self, linesep='\n') +Docstring: +Transform canvas into `print`-able string + +Parameters: + linesep: str The requested line seperator. default: os.linesep + +Returns: + unicode: The canvas as a string. +``` + +You can use it for example to plot a house in the terminal: + +```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()) +``` + + + +Or you could render images with braille dots: + +```python +In [24]: img = Image.open('https://github.com/tammoippen/plotille/raw/master/imgs/ich.jpg') +In [25]: img = img.convert('L') +In [26]: img = img.resize((80, 80)) +In [27]: cvs = Canvas(40, 20) +In [28]: cvs.braille_image(img.getdata()) +In [29]: print(cvs.plot()) +``` + + + +Or you could render images with the background color of characters: + +```python +In [24]: img = Image.open('https://github.com/tammoippen/plotille/raw/master/imgs/ich.jpg') +In [25]: img = img.convert('RGB') +In [25]: img = img.resize((80, 40)) +In [27]: cvs = Canvas(80, 40, mode="rgb") +In [28]: cvs.image(img.getdata()) +In [29]: print(cvs.plot()) +``` + + + +## Stargazers over time + +[](https://starchart.cc/tammoippen/plotille) + + +%package -n python3-plotille +Summary: Plot in the terminal using braille dots. +Provides: python-plotille +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-plotille + + +# Plotille + +[](https://github.com/tammoippen/plotille/actions/workflows/CI.yml) +[](https://codecov.io/gh/tammoippen/plotille) +[](https://lgtm.com/projects/g/tammoippen/plotille/context:python) +[](https://img.shields.io/badge/cpython-3.7%2C%203.8%2C%203.9%2C%203.10%2C%203.11-brightgreen.svg) +[](https://img.shields.io/badge/pypy-3.8%2C%203.9-brightgreen.svg) +[](https://pypi.python.org/pypi/plotille) +[](https://pepy.tech/project/plotille) +[](https://pypi.python.org/pypi/plotille) + +Plots, scatter plots, histograms and heatmaps in the terminal using braille dots, and foreground and background colors - with no dependancies. 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: + +```sh +pip 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. + +Basic support for timeseries plotting is provided with release 3.2: for any `X` or `Y` values you can also add `datetime.datetime`, `pendulum.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 + +```python +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 recomended way is to use a `Figure`: + +```python +In [12]: plotille.Figure? +Init signature: plotille.Figure() +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: float Define the X limits of the reference coordinate system, + that will be plottered. + y_limits: float Define the Y limits of the reference coordinate system, + that will be plottered. + color_mode: str Define the used color mode. See `plotille.color()`. + with_colors: bool Define, whether to use colors at all. + background: multiple 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: + +```python +# 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: + +```python +# 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/`](./examples) folder. + +### Graphing + +There are some utility functions for fast graphing of single plots. + +#### Plot + +```python +In [4]: plotille.plot? +Signature: +plotille.plot( + X, + Y, + width=80, + height=40, + X_label='X', + Y_label='Y', + linesep=os.linesep, + interp='linear', + x_min=None, + x_max=None, + y_min=None, + y_max=None, + lc=None, + bg=None, + color_mode='names', + origin=True, + marker=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. + lc: multiple Give the line color. + bg: multiple Give the background color. + color_mode: str 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 + +```python +In [6]: plotille.scatter? +Signature: +plotille.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, + lc=None, + bg=None, + color_mode='names', + origin=True, + marker=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. + lc: multiple Give the line color. + bg: multiple Give the background color. + color_mode: str 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. + +Returns: + str: scatter plot over `X`, `Y`. + +In [7]: print(plotille.scatter(X, np.sin(X), height=30, width=60)) +``` + + + +#### Hist + +Inspired by [crappyhist](http://kevinastraight.x10host.com/2013/12/28/python-histograms-from-the-console/) (link is gone, but I made a [gist](https://gist.github.com/tammoippen/4474e838e969bf177155231ebba52386)). + +```python +In [8]: plotille.hist? +Signature: +plotille.hist( + X, + bins=40, + width=80, + log_scale=False, + linesep='\n', + lc=None, + bg=None, + color_mode='names', +) +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 + lc: multiple Give the line color. + bg: multiple Give the background color. + color_mode: str Specify color input mode; 'names' (default), 'byte' or 'rgb' + see plotille.color.__docs__ + +Returns: + str: histogram over `X` from left to right. + +In [9]: print(plotille.hist(np.random.normal(size=10000))) +``` + + + +#### Hist (aggregated) + +This function allows you to create a histogram when your data is already aggregated (aka you don't have access to raw values, but you have access to bins and counts for each bin). + +This comes handy when working with APIs such as [OpenTelemetry Metrics API](https://opentelemetry-python.readthedocs.io/en/latest/api/metrics.html) +where views such as [ExplicitBucketHistogramAggregation](https://opentelemetry-python.readthedocs.io/en/latest/sdk/metrics.view.html#opentelemetry.sdk.metrics.view.ExplicitBucketHistogramAggregation) +only expose access to aggregated values (counts for each bin / bucket). + +```python +In [8]: plotille.hist_aggregated? +Signature: +plotille.hist_aggregated( + counts, + bins, + width=80, + log_scale=False, + linesep='\n', + lc=None, + bg=None, + color_mode='names', +) +Docstring: +Create histogram for aggregated data. + +Parameters: + counts: List[int] Counts for each bucket. + bins: List[float] Limits for the bins for the provided counts: limits for + bin `i` are `[bins[i], bins[i+1])`. + Hence, `len(bins) == len(counts) + 1`. + 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 + lc: multiple Give the line color. + bg: multiple Give the background color. + color_mode: str Specify color input mode; 'names' (default), 'byte' or 'rgb' + see plotille.color.__docs__ +Returns: + str: histogram over `X` from left to right. + +In [9]: counts = [1945, 0, 0, 0, 0, 0, 10555, 798, 0, 28351, 0] +In [10]: bins = [float('-inf'), 10, 50, 100, 200, 300, 500, 800, 1000, 2000, 10000, float('+inf')] +In [11]: print(plotille.hist_aggregated(counts, bins)) +``` + +Keep in mind that there must always be n+1 bins (n is a total number of count values, 11 in the example above). + +In this example the first bin is from [-inf, 10) with a count of 1945 and the last bin is from [10000, +inf] with a count of 0. + + + +#### Histogram + +There is also another more 'usual' histogram function available: + +```python +In [10]: plotille.histogram? +Signature: +plotille.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, + lc=None, + bg=None, + color_mode='names', +) +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. + lc: multiple Give the line color. + bg: multiple Give the background color. + color_mode: str Specify color input mode; 'names' (default), 'byte' or 'rgb' + see plotille.color.__docs__ + +Returns: + str: histogram over `X`. + +In [11]: print(plotille.histogram(np.random.normal(size=10000))) +``` + + + +### Canvas + +The underlying plotting area is modeled as the `Canvas` class: + +```python +In [12]: plotille.Canvas? +Init signature: +plotille.Canvas( + width, + height, + xmin=0, + ymin=0, + xmax=1, + ymax=1, + background=None, + **color_kwargs, +) +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. + background: multiple Background color of the canvas. + **color_kwargs: More arguments to the color-function. See `plotille.color()`. + +Returns: + Canvas object +``` + +The most interesting functions are: + +_point:_ + +```python +In [11]: plotille.Canvas.point? +Signature: plotille.Canvas.point(self, x, y, set_=True, color=None, marker=None) +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. + color: multiple Color of the point. + marker: str Instead of braille dots set a marker char. +``` + +_line:_ + +```python +In [14]: plotille.Canvas.line? +Signature: plotille.Canvas.line(self, x0, y0, x1, y1, set_=True, color=None) +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. + color: multiple Color of the line. +``` + +_rect:_ + +```python +In [15]: plotille.Canvas.rect? +Signature: plotille.Canvas.rect(self, xmin, ymin, xmax, ymax, set_=True, color=None) +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. + color: multiple Color of the rect. +``` + +_text:_ + +```python +In [16]: plotille.Canvas.text? +Signature: plotille.Canvas.text(self, x, y, text, set_=True, color=None) +Docstring: +Put some text 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 set the text or clear the characters. + text: str The text to add. + color: multiple Color of the point. +``` + +_braille_image:_ + +```python +In [17]: plotille.Canvas.braille_image? +Signature: +plotille.Canvas.braille_image( + self, + pixels, + threshold=127, + inverse=False, + set_=True, +) +Docstring: +Print an image using braille dots into the canvas. + +The pixels and braille dots in the canvas are a 1-to-1 mapping, hence +a 80 x 80 pixel image will need a 40 x 20 canvas. + +Example: + from PIL import Image + import plotille as plt + + img = Image.open("/path/to/image") + img = img.convert('L') + img = img.resize((80, 80)) + cvs = plt.Canvas(40, 20) + cvs.braille_image(img.getdata(), 125) + print(cvs.plot()) + +Parameters: + pixels: list[number] All pixels of the image in one list. + threshold: float All pixels above this threshold will be + drawn. + inverse: bool Whether to invert the image. + set_: bool Whether to plot or remove the dots. +``` + +_image:_ + +```python +In [18]: plotille.Canvas.image? +Signature: plotille.Canvas.image(self, pixels, set_=True) +Docstring: +Print an image using background colors into the canvas. + +The pixels of the image and the characters in the canvas are a +1-to-1 mapping, hence a 80 x 80 image will need a 80 x 80 canvas. + +Example: + from PIL import Image + import plotille as plt + + img = Image.open("/path/to/image") + img = img.convert('RGB') + img = img.resize((40, 40)) + cvs = plt.Canvas(40, 40, mode='rgb') + cvs.image(img.getdata()) + print(cvs.plot()) + +Parameters: + pixels: list[(R,G,B)] All pixels of the image in one list. + set_: bool Whether to plot or remove the background + colors. +``` + +_plot:_ + +```python +In [16]: plotille.Canvas.plot? +Signature: plotille.Canvas.plot(self, linesep='\n') +Docstring: +Transform canvas into `print`-able string + +Parameters: + linesep: str The requested line seperator. default: os.linesep + +Returns: + unicode: The canvas as a string. +``` + +You can use it for example to plot a house in the terminal: + +```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()) +``` + + + +Or you could render images with braille dots: + +```python +In [24]: img = Image.open('https://github.com/tammoippen/plotille/raw/master/imgs/ich.jpg') +In [25]: img = img.convert('L') +In [26]: img = img.resize((80, 80)) +In [27]: cvs = Canvas(40, 20) +In [28]: cvs.braille_image(img.getdata()) +In [29]: print(cvs.plot()) +``` + + + +Or you could render images with the background color of characters: + +```python +In [24]: img = Image.open('https://github.com/tammoippen/plotille/raw/master/imgs/ich.jpg') +In [25]: img = img.convert('RGB') +In [25]: img = img.resize((80, 40)) +In [27]: cvs = Canvas(80, 40, mode="rgb") +In [28]: cvs.image(img.getdata()) +In [29]: print(cvs.plot()) +``` + + + +## Stargazers over time + +[](https://starchart.cc/tammoippen/plotille) + + +%package help +Summary: Development documents and examples for plotille +Provides: python3-plotille-doc +%description help + + +# Plotille + +[](https://github.com/tammoippen/plotille/actions/workflows/CI.yml) +[](https://codecov.io/gh/tammoippen/plotille) +[](https://lgtm.com/projects/g/tammoippen/plotille/context:python) +[](https://img.shields.io/badge/cpython-3.7%2C%203.8%2C%203.9%2C%203.10%2C%203.11-brightgreen.svg) +[](https://img.shields.io/badge/pypy-3.8%2C%203.9-brightgreen.svg) +[](https://pypi.python.org/pypi/plotille) +[](https://pepy.tech/project/plotille) +[](https://pypi.python.org/pypi/plotille) + +Plots, scatter plots, histograms and heatmaps in the terminal using braille dots, and foreground and background colors - with no dependancies. 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: + +```sh +pip 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. + +Basic support for timeseries plotting is provided with release 3.2: for any `X` or `Y` values you can also add `datetime.datetime`, `pendulum.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 + +```python +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 recomended way is to use a `Figure`: + +```python +In [12]: plotille.Figure? +Init signature: plotille.Figure() +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: float Define the X limits of the reference coordinate system, + that will be plottered. + y_limits: float Define the Y limits of the reference coordinate system, + that will be plottered. + color_mode: str Define the used color mode. See `plotille.color()`. + with_colors: bool Define, whether to use colors at all. + background: multiple 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: + +```python +# 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: + +```python +# 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/`](./examples) folder. + +### Graphing + +There are some utility functions for fast graphing of single plots. + +#### Plot + +```python +In [4]: plotille.plot? +Signature: +plotille.plot( + X, + Y, + width=80, + height=40, + X_label='X', + Y_label='Y', + linesep=os.linesep, + interp='linear', + x_min=None, + x_max=None, + y_min=None, + y_max=None, + lc=None, + bg=None, + color_mode='names', + origin=True, + marker=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. + lc: multiple Give the line color. + bg: multiple Give the background color. + color_mode: str 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 + +```python +In [6]: plotille.scatter? +Signature: +plotille.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, + lc=None, + bg=None, + color_mode='names', + origin=True, + marker=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. + lc: multiple Give the line color. + bg: multiple Give the background color. + color_mode: str 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. + +Returns: + str: scatter plot over `X`, `Y`. + +In [7]: print(plotille.scatter(X, np.sin(X), height=30, width=60)) +``` + + + +#### Hist + +Inspired by [crappyhist](http://kevinastraight.x10host.com/2013/12/28/python-histograms-from-the-console/) (link is gone, but I made a [gist](https://gist.github.com/tammoippen/4474e838e969bf177155231ebba52386)). + +```python +In [8]: plotille.hist? +Signature: +plotille.hist( + X, + bins=40, + width=80, + log_scale=False, + linesep='\n', + lc=None, + bg=None, + color_mode='names', +) +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 + lc: multiple Give the line color. + bg: multiple Give the background color. + color_mode: str Specify color input mode; 'names' (default), 'byte' or 'rgb' + see plotille.color.__docs__ + +Returns: + str: histogram over `X` from left to right. + +In [9]: print(plotille.hist(np.random.normal(size=10000))) +``` + + + +#### Hist (aggregated) + +This function allows you to create a histogram when your data is already aggregated (aka you don't have access to raw values, but you have access to bins and counts for each bin). + +This comes handy when working with APIs such as [OpenTelemetry Metrics API](https://opentelemetry-python.readthedocs.io/en/latest/api/metrics.html) +where views such as [ExplicitBucketHistogramAggregation](https://opentelemetry-python.readthedocs.io/en/latest/sdk/metrics.view.html#opentelemetry.sdk.metrics.view.ExplicitBucketHistogramAggregation) +only expose access to aggregated values (counts for each bin / bucket). + +```python +In [8]: plotille.hist_aggregated? +Signature: +plotille.hist_aggregated( + counts, + bins, + width=80, + log_scale=False, + linesep='\n', + lc=None, + bg=None, + color_mode='names', +) +Docstring: +Create histogram for aggregated data. + +Parameters: + counts: List[int] Counts for each bucket. + bins: List[float] Limits for the bins for the provided counts: limits for + bin `i` are `[bins[i], bins[i+1])`. + Hence, `len(bins) == len(counts) + 1`. + 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 + lc: multiple Give the line color. + bg: multiple Give the background color. + color_mode: str Specify color input mode; 'names' (default), 'byte' or 'rgb' + see plotille.color.__docs__ +Returns: + str: histogram over `X` from left to right. + +In [9]: counts = [1945, 0, 0, 0, 0, 0, 10555, 798, 0, 28351, 0] +In [10]: bins = [float('-inf'), 10, 50, 100, 200, 300, 500, 800, 1000, 2000, 10000, float('+inf')] +In [11]: print(plotille.hist_aggregated(counts, bins)) +``` + +Keep in mind that there must always be n+1 bins (n is a total number of count values, 11 in the example above). + +In this example the first bin is from [-inf, 10) with a count of 1945 and the last bin is from [10000, +inf] with a count of 0. + + + +#### Histogram + +There is also another more 'usual' histogram function available: + +```python +In [10]: plotille.histogram? +Signature: +plotille.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, + lc=None, + bg=None, + color_mode='names', +) +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. + lc: multiple Give the line color. + bg: multiple Give the background color. + color_mode: str Specify color input mode; 'names' (default), 'byte' or 'rgb' + see plotille.color.__docs__ + +Returns: + str: histogram over `X`. + +In [11]: print(plotille.histogram(np.random.normal(size=10000))) +``` + + + +### Canvas + +The underlying plotting area is modeled as the `Canvas` class: + +```python +In [12]: plotille.Canvas? +Init signature: +plotille.Canvas( + width, + height, + xmin=0, + ymin=0, + xmax=1, + ymax=1, + background=None, + **color_kwargs, +) +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. + background: multiple Background color of the canvas. + **color_kwargs: More arguments to the color-function. See `plotille.color()`. + +Returns: + Canvas object +``` + +The most interesting functions are: + +_point:_ + +```python +In [11]: plotille.Canvas.point? +Signature: plotille.Canvas.point(self, x, y, set_=True, color=None, marker=None) +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. + color: multiple Color of the point. + marker: str Instead of braille dots set a marker char. +``` + +_line:_ + +```python +In [14]: plotille.Canvas.line? +Signature: plotille.Canvas.line(self, x0, y0, x1, y1, set_=True, color=None) +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. + color: multiple Color of the line. +``` + +_rect:_ + +```python +In [15]: plotille.Canvas.rect? +Signature: plotille.Canvas.rect(self, xmin, ymin, xmax, ymax, set_=True, color=None) +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. + color: multiple Color of the rect. +``` + +_text:_ + +```python +In [16]: plotille.Canvas.text? +Signature: plotille.Canvas.text(self, x, y, text, set_=True, color=None) +Docstring: +Put some text 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 set the text or clear the characters. + text: str The text to add. + color: multiple Color of the point. +``` + +_braille_image:_ + +```python +In [17]: plotille.Canvas.braille_image? +Signature: +plotille.Canvas.braille_image( + self, + pixels, + threshold=127, + inverse=False, + set_=True, +) +Docstring: +Print an image using braille dots into the canvas. + +The pixels and braille dots in the canvas are a 1-to-1 mapping, hence +a 80 x 80 pixel image will need a 40 x 20 canvas. + +Example: + from PIL import Image + import plotille as plt + + img = Image.open("/path/to/image") + img = img.convert('L') + img = img.resize((80, 80)) + cvs = plt.Canvas(40, 20) + cvs.braille_image(img.getdata(), 125) + print(cvs.plot()) + +Parameters: + pixels: list[number] All pixels of the image in one list. + threshold: float All pixels above this threshold will be + drawn. + inverse: bool Whether to invert the image. + set_: bool Whether to plot or remove the dots. +``` + +_image:_ + +```python +In [18]: plotille.Canvas.image? +Signature: plotille.Canvas.image(self, pixels, set_=True) +Docstring: +Print an image using background colors into the canvas. + +The pixels of the image and the characters in the canvas are a +1-to-1 mapping, hence a 80 x 80 image will need a 80 x 80 canvas. + +Example: + from PIL import Image + import plotille as plt + + img = Image.open("/path/to/image") + img = img.convert('RGB') + img = img.resize((40, 40)) + cvs = plt.Canvas(40, 40, mode='rgb') + cvs.image(img.getdata()) + print(cvs.plot()) + +Parameters: + pixels: list[(R,G,B)] All pixels of the image in one list. + set_: bool Whether to plot or remove the background + colors. +``` + +_plot:_ + +```python +In [16]: plotille.Canvas.plot? +Signature: plotille.Canvas.plot(self, linesep='\n') +Docstring: +Transform canvas into `print`-able string + +Parameters: + linesep: str The requested line seperator. default: os.linesep + +Returns: + unicode: The canvas as a string. +``` + +You can use it for example to plot a house in the terminal: + +```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()) +``` + + + +Or you could render images with braille dots: + +```python +In [24]: img = Image.open('https://github.com/tammoippen/plotille/raw/master/imgs/ich.jpg') +In [25]: img = img.convert('L') +In [26]: img = img.resize((80, 80)) +In [27]: cvs = Canvas(40, 20) +In [28]: cvs.braille_image(img.getdata()) +In [29]: print(cvs.plot()) +``` + + + +Or you could render images with the background color of characters: + +```python +In [24]: img = Image.open('https://github.com/tammoippen/plotille/raw/master/imgs/ich.jpg') +In [25]: img = img.convert('RGB') +In [25]: img = img.resize((80, 40)) +In [27]: cvs = Canvas(80, 40, mode="rgb") +In [28]: cvs.image(img.getdata()) +In [29]: print(cvs.plot()) +``` + + + +## Stargazers over time + +[](https://starchart.cc/tammoippen/plotille) + + +%prep +%autosetup -n plotille-5.0.0 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-plotille -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Fri May 05 2023 Python_Bot <Python_Bot@openeuler.org> - 5.0.0-1 +- Package Spec generated |