Package: plotille
PlotillePlots, 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:pipinstallplotilleSimilar to other libraries:likedrawille, but focused on graphing – plus X/Y-axis.liketermplot, but with braille (finer dots), left to right histogram and linear interpolation for plotting function.liketermgraph(not on pypi), but very different style.liketerminalplot, but with braille, X/Y-axis, histogram, linear interpolation.Basic support for timeseries plotting is provided with release 3.2: for anyXorYvalues you can also adddatetime.datetime,pendulum.datetimeornumpy.datetime64values. Labels are generated respecting the difference ofx_limitsandy_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.0If 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.DocumentationIn[1]:importplotilleIn[2]:importnumpyasnpIn[3]:X=np.sort(np.random.normal(size=1000))FigureTo construct plots the recomended way is to use aFigure:In[12]:plotille.Figure?Initsignature:plotille.Figure()Docstring:Figureclasstocomposemultipleplots.WithinaFigureyoucaneasilycomposemanyplots,assignlabelstoplotsanddefinethepropertiesoftheunderlyingCanvas.Possiblepropertiesthatcanbedefinedare:width,height:intDefinethenumberofcharactersinX/Ydirectionwhichareusedforplotting.x_limits:floatDefinetheXlimitsofthereferencecoordinatesystem,thatwillbeplottered.y_limits:floatDefinetheYlimitsofthereferencecoordinatesystem,thatwillbeplottered.color_mode:strDefinetheusedcolormode.See`plotille.color()`.with_colors:boolDefine,whethertousecolorsatall.background:multipleDefinethebackgroundcolor.x_label,y_label:strDefinetheX/Yaxislabel.Basically, you create aFigure, define the properties and add your plots. Using theshow()function, theFiguregenerates the plot using a new canvas:In[13]fig=plotille.Figure()In[14]fig.width=60In[15]fig.height=30In[16]fig.set_x_limits(min_=-3,max_=3)In[17]fig.set_y_limits(min_=-1,max_=1)In[18]fig.color_mode='byte'In[19]fig.plot([-0.5,1],[-1,1],lc=25,label='First line')In[20]fig.scatter(X,np.sin(X),lc=100,label='sin')In[21]fig.plot(X,(X+2)**2,lc=200,label='square')In[22]print(fig.show(legend=True))The available plotting functions are:# create a plot with linear interpolation between pointsFigure.plot(self,X,Y,lc=None,interp='linear',label=None,marker=None)# create a scatter plot with no interpolation between pointsFigure.scatter(self,X,Y,lc=None,label=None,marker=None)# create a histogram over XFigure.histogram(self,X,bins=160,lc=None)# print texts at coordinates X, YFigure.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 xFigure.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 yFigure.axhline(self,y,xmin=0,xmax=1,lc=None)# plot a horizontal rectangle from (xmin,ymin) to (xmax, ymax).Figure.axhspan(self,ymin,ymax,xmin=0,xmax=1,lc=None)# Display data as an image, i.e. on a 2D regular raster.Figure.imgshow(self,X,cmap=None)Other interesting functions are:# remove all plots, texts, spans and images from the figureFigure.clear(self)# Create a canvas, plot the registered plots and return the string for displaying the plotFigure.show(self,legend=False)Please have a look at theexamples/folder.GraphingThere are some utility functions for fast graphing of single plots.PlotIn[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:CreateplotwithX,YvaluesandlinearinterpolationbetweenpointsParameters:X:List[float]Xvalues.Y:List[float]Yvalues.XandYmusthavethesamenumberofentries.width:intThenumberofcharactersforthewidth(columns)ofthecanvas.hight:intThenumberofcharactersforthehight(rows)ofthecanvas.X_label:strLabelforX-axis.Y_label:strLabelforY-axis.max8characters.linesep:strTherequestedlineseperator.default:os.linesepinterp:Optional[str]Specifyinterpolation;valuesNone,'linear'x_min,x_max:floatLimitsforthedisplayedXvalues.y_min,y_max:floatLimitsforthedisplayedYvalues.lc:multipleGivethelinecolor.bg:multipleGivethebackgroundcolor.color_mode:strSpecifycolorinputmode;'names'(default),'byte'or'rgb'seeplotille.color.__docs__origin:boolWhethertoprinttheorigin.default:Truemarker:strInsteadofbrailledotssetamarkercharforactualvalues.Returns:str:plotover`X`,`Y`.In[5]:print(plotille.plot(X,np.sin(X),height=30,width=60))ScatterIn[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:CreatescatterplotwithX,YvaluesBasicallyplottingwithoutinterpolation:`plot(X,Y,...,interp=None)`Parameters:X:List[float]Xvalues.Y:List[float]Yvalues.XandYmusthavethesamenumberofentries.width:intThenumberofcharactersforthewidth(columns)ofthecanvas.hight:intThenumberofcharactersforthehight(rows)ofthecanvas.X_label:strLabelforX-axis.Y_label:strLabelforY-axis.max8characters.linesep:strTherequestedlineseperator.default:os.linesepx_min,x_max:floatLimitsforthedisplayedXvalues.y_min,y_max:floatLimitsforthedisplayedYvalues.lc:multipleGivethelinecolor.bg:multipleGivethebackgroundcolor.color_mode:strSpecifycolorinputmode;'names'(default),'byte'or'rgb'seeplotille.color.__docs__origin:boolWhethertoprinttheorigin.default:Truemarker:strInsteadofbrailledotssetamarkerchar.Returns:str:scatterplotover`X`,`Y`.In[7]:print(plotille.scatter(X,np.sin(X),height=30,width=60))HistInspired bycrappyhist(link is gone, but I made agist).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:Createhistogramover`X`fromlefttorightThevaluesontheleftarethecenterofthebucket,i.e.`(bin[i]+bin[i+1])/2`.Thevaluesontherightarethetotalcountsofthisbucket.Parameters:X:List[float]Theitemstocountover.bins:intThenumberofbinstoputXentriesin(rows).width:intThenumberofcharactersforthewidth(columns).log_scale:boolScalethehistogramwith`log`function.linesep:strTherequestedlineseperator.default:os.lineseplc:multipleGivethelinecolor.bg:multipleGivethebackgroundcolor.color_mode:strSpecifycolorinputmode;'names'(default),'byte'or'rgb'seeplotille.color.__docs__Returns:str:histogramover`X`fromlefttoright.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 asOpenTelemetry Metrics APIwhere views such asExplicitBucketHistogramAggregationonly expose access to aggregated values (counts for each bin / bucket).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:Createhistogramforaggregateddata.Parameters:counts:List[int]Countsforeachbucket.bins:List[float]Limitsforthebinsfortheprovidedcounts:limitsforbin`i`are`[bins[i],bins[i+1])`.Hence,`len(bins)==len(counts)+1`.width:intThenumberofcharactersforthewidth(columns).log_scale:boolScalethehistogramwith`log`function.linesep:strTherequestedlineseperator.default:os.lineseplc:multipleGivethelinecolor.bg:multipleGivethebackgroundcolor.color_mode:strSpecifycolorinputmode;'names'(default),'byte'or'rgb'seeplotille.color.__docs__Returns:str:histogramover`X`fromlefttoright.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.HistogramThere is also another more 'usual' histogram function available: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:Createhistogramover`X`Incontrastto`hist`,thisisthemore`usual`histogramfrombottomtoup.TheX-axisrepresentsthevaluesin`X`andtheY-axisisthecorrespondingfrequency.Parameters:X:List[float]Theitemstocountover.bins:intThenumberofbinstoputXentriesin(columns).height:intThenumberofcharactersfortheheight(rows).X_label:strLabelforX-axis.Y_label:strLabelforY-axis.max8characters.linesep:strTherequestedlineseperator.default:os.linesepx_min,x_max:floatLimitsforthedisplayedXvalues.y_min,y_max:floatLimitsforthedisplayedYvalues.lc:multipleGivethelinecolor.bg:multipleGivethebackgroundcolor.color_mode:strSpecifycolorinputmode;'names'(default),'byte'or'rgb'seeplotille.color.__docs__Returns:str:histogramover`X`.In[11]:print(plotille.histogram(np.random.normal(size=10000)))CanvasThe underlying plotting area is modeled as theCanvasclass:In[12]:plotille.Canvas?Initsignature:plotille.Canvas(width,height,xmin=0,ymin=0,xmax=1,ymax=1,background=None,**color_kwargs,)Docstring:AcanvasobjectforplottingbrailledotsACanvasobjecthasa`width`x`height`characterslargecanvas,inwhichitcanplotindivitualbraillepoint,linesoutofbraillepoints,rectangles,...Sinceafullbraillecharacterhas2x4dots(⣿),thecanvashas`width`*2,`height`*4dotstoplotintointotal.Itmaintainstwocoordinatesystems:areferencesystemwiththelimits(xmin,ymin)inthelowerleftcornerto(xmax,ymax)intheupperrightcorneristransformedintothecanvasdiscrete,i.e.dots,coordinatesystem(0,0)to(`width`*2,`height`*4).ItdoessotransparentlytoclientsoftheCanvas,i.e.allplottingfunctionsonlyacceptcoordinatesinthereferencesystem.Ifthecoordinatesareoutsidethereferencesystem,theyarenotplotted.Initdocstring:InitiateaCanvasobjectParameters:width:intThenumberofcharactersforthewidth(columns)ofthecanvas.hight:intThenumberofcharactersforthehight(rows)ofthecanvas.xmin,ymin:floatLowerleftcornerofreferencesystem.xmax,ymax:floatUpperrightcornerofreferencesystem.background:multipleBackgroundcolorofthecanvas.**color_kwargs:Moreargumentstothecolor-function.See`plotille.color()`.Returns:CanvasobjectThe most interesting functions are:point:In[11]:plotille.Canvas.point?Signature:plotille.Canvas.point(self,x,y,set_=True,color=None,marker=None)Docstring:Putapointintothecanvasat(x,y)[referencecoordinatesystem]Parameters:x:floatx-coordinateonreferencesystem.y:floaty-coordinateonreferencesystem.set_:boolWhethertoplotorremovethepoint.color:multipleColorofthepoint.marker:strInsteadofbrailledotssetamarkerchar.line:In[14]:plotille.Canvas.line?Signature:plotille.Canvas.line(self,x0,y0,x1,y1,set_=True,color=None)Docstring:Plotlinebetweenpoint(x0,y0)and(x1,y1)[referencecoordinatesystem].Parameters:x0,y0:floatPoint0x1,y1:floatPoint1set_:boolWhethertoplotorremovetheline.color:multipleColoroftheline.rect:In[15]:plotille.Canvas.rect?Signature:plotille.Canvas.rect(self,xmin,ymin,xmax,ymax,set_=True,color=None)Docstring:Plotrectanglewithbbox(xmin,ymin)and(xmax,ymax)[referencecoordinatesystem].Parameters:xmin,ymin:floatLowerleftcornerofrectangle.xmax,ymax:floatUpperrightcornerofrectangle.set_:boolWhethertoplotorremovetherect.color:multipleColoroftherect.text:In[16]:plotille.Canvas.text?Signature:plotille.Canvas.text(self,x,y,text,set_=True,color=None)Docstring:Putsometextintothecanvasat(x,y)[referencecoordinatesystem]Parameters:x:floatx-coordinateonreferencesystem.y:floaty-coordinateonreferencesystem.set_:boolWhethertosetthetextorclearthecharacters.text:strThetexttoadd.color:multipleColorofthepoint.braille_image:In[17]:plotille.Canvas.braille_image?Signature:plotille.Canvas.braille_image(self,pixels,threshold=127,inverse=False,set_=True,)Docstring:Printanimageusingbrailledotsintothecanvas.Thepixelsandbrailledotsinthecanvasarea1-to-1mapping,hencea80x80pixelimagewillneeda40x20canvas.Example:fromPILimportImageimportplotilleaspltimg=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]Allpixelsoftheimageinonelist.threshold:floatAllpixelsabovethisthresholdwillbedrawn.inverse:boolWhethertoinverttheimage.set_:boolWhethertoplotorremovethedots.image:In[18]:plotille.Canvas.image?Signature:plotille.Canvas.image(self,pixels,set_=True)Docstring:Printanimageusingbackgroundcolorsintothecanvas.Thepixelsoftheimageandthecharactersinthecanvasarea1-to-1mapping,hencea80x80imagewillneeda80x80canvas.Example:fromPILimportImageimportplotilleaspltimg=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)]Allpixelsoftheimageinonelist.set_:boolWhethertoplotorremovethebackgroundcolors.plot:In[16]:plotille.Canvas.plot?Signature:plotille.Canvas.plot(self,linesep='\n')Docstring:Transformcanvasinto`print`-ablestringParameters:linesep:strTherequestedlineseperator.default:os.linesepReturns:unicode:Thecanvasasastring.You can use it for example to plot a house in the terminal: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: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: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