In Python, objects can declare their textual representation using the __repr__ method. IPython expands on this idea and allows objects to declare other, richer representations including:
This Notebook shows how you can add custom display logic to your own classes, so that they can be displayed using these rich representations. There are two ways of accomplishing this:
_repr_html_.In this Notebook we show how both approaches work.
Parts of this notebook need the inline matplotlib backend:
In [1]:
%matplotlib inline
import numpy as np
import matplotlib.pyplot as plt
The main idea of the first approach is that you have to implement special display methods, one for each representation you want to use. The names of the special methods are self explanatory:
_repr_html__repr_json__repr_jpeg__repr_png__repr_svg__repr_latex_As an illustration, we build a class that holds data generated by sampling a Gaussian distribution with given mean and variance. Each frontend can then decide which representation it will display be default. Further, we show how to display a particular representation.
The next cell defines the Gaussian class:
In [2]:
from IPython.core.pylabtools import print_figure
from IPython.display import Image, SVG, Math
class Gaussian(object):
"""A simple object holding data sampled from a Gaussian distribution.
"""
def __init__(self, mean=0, std=1, size=1000):
self.data = np.random.normal(mean, std, size)
self.mean = mean
self.std = std
self.size = size
# For caching plots that may be expensive to compute
self._png_data = None
self._svg_data = None
def _figure_data(self, format):
fig, ax = plt.subplots()
ax.plot(self.data, 'o')
ax.set_title(self._repr_latex_())
data = print_figure(fig, format)
# We MUST close the figure, otherwise IPython's display machinery
# will pick it up and send it as output, resulting in a double display
plt.close(fig)
return data
# Here we define the special repr methods that provide the IPython display protocol
# Note that for the two figures, we cache the figure data once computed.
def _repr_png_(self):
if self._png_data is None:
self._png_data = self._figure_data('png')
return self._png_data
def _repr_svg_(self):
if self._svg_data is None:
self._svg_data = self._figure_data('svg').decode('utf-8')#.encode('utf-8')
return self._svg_data
def _repr_latex_(self):
return r'$\mathcal{N}(\mu=%.2g, \sigma=%.2g),\ N=%d$' % (self.mean,
self.std, self.size)
# We expose as properties some of the above reprs, so that the user can see them
# directly (since otherwise the client dictates which one it shows by default)
@property
def png(self):
return Image(self._repr_png_(), embed=True)
@property
def svg(self):
return SVG(self._repr_svg_())
@property
def latex(self):
return Math(self._repr_latex_())
# An example of using a property to display rich information, in this case
# the histogram of the distribution. We've hardcoded the format to be png
# in this case, but in production code it would be trivial to make it an option
@property
def hist(self):
fig, ax = plt.subplots()
ax.hist(self.data, bins=100)
ax.set_title(self._repr_latex_())
data = print_figure(fig, 'png')
plt.close(fig)
return Image(data, embed=True)
Now, we create an instance of the Gaussian distribution, whose default representation will be its LaTeX form:
In [3]:
x = Gaussian()
x
Out[3]:
We can view the data in png or svg formats:
In [4]:
x.png
Out[4]:
In [5]:
x.svg
Out[5]:
Since IPython only displays by default as an Out[] cell the result of the last computation, we can use the
display() function to show more than one representation in a single cell:
In [6]:
from IPython.display import display
In [7]:
display(x.png)
display(x.svg)
Now let's create a new Gaussian with different parameters
In [8]:
x2 = Gaussian(0.5, 0.2, 2000)
x2
Out[8]:
We can easily compare them by displaying their histograms
In [9]:
display(x.hist)
display(x2.hist)
When you are directly writing your own classes, you can adapt them for display in IPython by following the above example. But in practice, we often need to work with existing code we can't modify. We now illustrate how to add these kinds of extended display capabilities to existing objects. We will use the NumPy polynomials and change their default representation to be a formatted LaTeX expression.
First, consider how a numpy polynomial object renders by default:
In [10]:
p = np.polynomial.Polynomial([1,2,3], [-10, 10])
p
Out[10]:
Next, we define a function that pretty-prints a polynomial as a LaTeX string:
In [11]:
def poly2latex(p):
terms = ['%.2g' % p.coef[0]]
if len(p) > 1:
term = 'x'
c = p.coef[1]
if c!=1:
term = ('%.2g ' % c) + term
terms.append(term)
if len(p) > 2:
for i in range(2, len(p)):
term = 'x^%d' % i
c = p.coef[i]
if c!=1:
term = ('%.2g ' % c) + term
terms.append(term)
px = '$P(x)=%s$' % '+'.join(terms)
dom = r', domain: $[%.2g,\ %.2g]$' % tuple(p.domain)
return px+dom
This produces, on our polynomial p, the following:
In [12]:
poly2latex(p)
Out[12]:
In [13]:
from IPython.display import Latex
Latex(poly2latex(p))
Out[13]:
But we can configure IPython to do this automatically for us as follows. We hook into the
IPython display system and instruct it to use poly2latex for the latex mimetype, when
encountering objects of the Polynomial type defined in the
numpy.polynomial.polynomial module:
In [14]:
ip = get_ipython()
latex_formatter = ip.display_formatter.formatters['text/latex']
latex_formatter.for_type_by_name('numpy.polynomial.polynomial',
'Polynomial', poly2latex)
For more examples on how to use the above system, and how to bundle similar print functions
into a convenient IPython extension, see sympy's printing extension.
Once our special printer has been loaded, all polynomials will be represented by their mathematical form instead:
In [15]:
p
Out[15]:
In [16]:
p2 = np.polynomial.Polynomial([-20, 71, -15, 1])
p2
Out[16]:
Rich reprs can only display one object or mime-type at a time. Sometimes this is not enough, because you need to get javascript on the page, or you want LaTeX and a PNG. This can be done with multiple calls to display easily enough, but then users need to know more than they should.
In IPython 2.0, we added a special _ipython_display_ method,
that allows your objects to take control of displaying.
If this method is defined, IPython will call it, and make no effort to display the object itself.
It's a way for you to say "Back off, IPython, I got this."
In [17]:
import json
import uuid
from IPython.display import display_javascript, display_html, display
class FlotPlot(object):
def __init__(self, x, y):
self.x = x
self.y = y
self.uuid = str(uuid.uuid4())
def _ipython_display_(self):
json_data = json.dumps(zip(self.x, self.y))
display_html('<div id="{}" style="height: 300px; width:80%;"></div>'.format(self.uuid),
raw=True
)
display_javascript("""
require(["//cdnjs.cloudflare.com/ajax/libs/flot/0.8.2/jquery.flot.min.js"], function() {
var line = JSON.parse("%s");
console.log(line);
$.plot("#%s", [line]);
});
""" % (json_data, self.uuid), raw=True)
In [18]:
import numpy as np
x = np.linspace(0,10)
y = np.sin(x)
FlotPlot(x, np.sin(x))