<jupyter_start><jupyter_text>Custom Display Logic  Overview As described in the [Rich Output](Rich Output.ipynb) tutorial, the IPython display system can display rich representations of objects in the following formats:* JavaScript* HTML* PNG* JPEG* SVG* LaTeX* PDFThis 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:1. Implementing special display methods such as `_repr_html_` when you define your class.2. Registering a display function for a particular existing class.This Notebook describes and illustrates both approaches. Import the IPython display functions.<jupyter_code>from IPython.display import (
    display, display_html, display_png, display_svg
)<jupyter_output><empty_output><jupyter_text>Parts of this notebook need the matplotlib inline backend:<jupyter_code>import numpy as np
import matplotlib.pyplot as plt
plt.ion()<jupyter_output><empty_output><jupyter_text>Special display methods The main idea of the first approach is that you have to implement special display methods when you define your class, one for each representation you want to use. Here is a list of the names of the special methods and the values they must return:* `_repr_html_`: return raw HTML as a string* `_repr_json_`: return a JSONable dict* `_repr_jpeg_`: return raw JPEG data* `_repr_png_`: return raw PNG data* `_repr_svg_`: return raw SVG data as a string* `_repr_latex_`: return LaTeX commands in a string surrounded by "$".* `_repr_mimebundle_`: return a full mimebundle containing the mapping from all mimetypes to data  As an illustration, we build a class that holds data generated by sampling a Gaussian distribution with given mean and standard deviation. Here is the definition of the `Gaussian` class, which has a custom PNG and LaTeX representation.<jupyter_code>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.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
        
    def _figure_data(self, format):
        fig, ax = plt.subplots()
        ax.hist(self.data, bins=50)
        ax.set_title(self._repr_latex_())
        ax.set_xlim(-10.0,10.0)
        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
        
    def _repr_png_(self):
        if self._png_data is None:
            self._png_data = self._figure_data('png')
        return self._png_data
    
    def _repr_latex_(self):
        return r'$\mathcal{N}(\mu=%.2g, \sigma=%.2g),\ N=%d$' % (self.mean,
                                                                 self.std, self.size)<jupyter_output><empty_output><jupyter_text>Create an instance of the Gaussian distribution and return it to display the default representation:<jupyter_code>x = Gaussian(2.0, 1.0)
x<jupyter_output><empty_output><jupyter_text>You can also pass the object to the `display` function to display the default representation:<jupyter_code>display(x)<jupyter_output><empty_output><jupyter_text>Use `display_png` to view the PNG representation:<jupyter_code>display_png(x)<jupyter_output><empty_output><jupyter_text>It is important to note a subtle different between display and display_png. The former computes all representations of the object, and lets the notebook UI decide which to display. The later only computes the PNG representation. Create a new Gaussian with different parameters:<jupyter_code>x2 = Gaussian(0, 2, 2000)
x2<jupyter_output><empty_output><jupyter_text>You can then compare the two Gaussians by displaying their histograms:<jupyter_code>display_png(x)
display_png(x2)<jupyter_output><empty_output><jupyter_text>Note that like `print`, you can call any of the `display` functions multiple times in a cell.  Adding IPython display support to existing objects When you are directly writing your own classes, you can adapt them for display in IPython by following the above approach.  But in practice, you often need to work with existing classes that you can't easily modify. We now illustrate how to add rich output 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:<jupyter_code>p = np.polynomial.Polynomial([1,2,3], [-10, 10])
p<jupyter_output><empty_output><jupyter_text>Next, define a function that pretty-prints a polynomial as a LaTeX string:<jupyter_code>def poly_to_latex(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', $x \in [%.2g,\ %.2g]$' % tuple(p.domain)
    return px+dom<jupyter_output><empty_output><jupyter_text>This produces, on our polynomial ``p``, the following:<jupyter_code>poly_to_latex(p)<jupyter_output><empty_output><jupyter_text>You can render this string using the `Latex` class:<jupyter_code>from IPython.display import Latex
Latex(poly_to_latex(p))<jupyter_output><empty_output><jupyter_text>However, you can configure IPython to do this automatically by registering the `Polynomial` class and the `poly_to_latex` function with an IPython display formatter. Let's look at the default formatters provided by IPython:<jupyter_code>ip = get_ipython()
for mime, formatter in ip.display_formatter.formatters.items():
    print('%24s : %s' % (mime, formatter.__class__.__name__))<jupyter_output>text/plain : PlainTextFormatter
               text/html : HTMLFormatter
           text/markdown : MarkdownFormatter
           image/svg+xml : SVGFormatter
               image/png : PNGFormatter
         application/pdf : PDFFormatter
              image/jpeg : JPEGFormatter
              text/latex : LatexFormatter
        application/json : JSONFormatter
  application/javascript : JavascriptFormatter<jupyter_text>The `formatters` attribute is a dictionary keyed by MIME types. To define a custom LaTeX display function, you want a handle on the `text/latex` formatter:<jupyter_code>ip = get_ipython()
latex_f = ip.display_formatter.formatters['text/latex']<jupyter_output><empty_output><jupyter_text>The formatter object has a couple of methods for registering custom display functions for existing types.<jupyter_code>help(latex_f.for_type)
help(latex_f.for_type_by_name)<jupyter_output>Help on method for_type_by_name in module IPython.core.formatters:

for_type_by_name(type_module, type_name, func=None) method of IPython.core.formatters.LatexFormatter instance
    Add a format function for a type specified by the full dotted
    module and name of the type, rather than the type of the object.
    
    Parameters
    ----------
    type_module : str
        The full dotted name of the module the type is defined in, like
        ``numpy``.
    type_name : str
        The name of the type (the class name), like ``dtype``
    func : callable
        A callable for computing the format data.
        `func` will be called with the object to be formatted,
        and will return the raw data in this formatter's format.
        Subclasses may use a different call signature for the
        `func` argument.
        
        If `func` is None or unspecified, there will be no change,
        only returning the current value.
    
    Returns
    -------
    oldfunc : callable
  [...]<jupyter_text>In this case, we will use `for_type_by_name` to register `poly_to_latex` as the display function for the `Polynomial` type:<jupyter_code>latex_f.for_type_by_name('numpy.polynomial.polynomial',
                                 'Polynomial', poly_to_latex)<jupyter_output><empty_output><jupyter_text>Once the custom display function has been registered, all NumPy `Polynomial` instances will be represented by their LaTeX form instead:<jupyter_code>p
p2 = np.polynomial.Polynomial([-20, 71, -15, 1])
p2<jupyter_output><empty_output><jupyter_text>Custom Mimetypes with `_repr_mimebundle_`Available on IPython 5.4+ and 6.1+.For objects needing full control over the `repr` protocol may decide to implement the `_repr_mimebundle_(include, exclude)` method.Unlike the other `_repr_*_` methods must return many representation of the object in a mapping object which keys are _mimetypes_ and value are associated data. The `_repr_mimebundle_()` method, may also return a second mapping from _mimetypes_ to metadata. Example:<jupyter_code>class Gaussian(object):
    """A simple object holding data sampled from a Gaussian distribution.
    """
    def __init__(self, mean=0.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
        
    def _figure_data(self, format):
        fig, ax = plt.subplots()
        ax.hist(self.data, bins=50)
        ax.set_xlim(-10.0,10.0)
        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
    
    def _compute_mathml(self):
        return """
        <math xmlns="http://www.w3.org/1998/Math/MathML">
          <mrow class="MJX-TeXAtom-ORD">
            <mi class="MJX-tex-caligraphic" mathvariant="script">N</mi>
          </mrow>
          <mo stretchy="false">(</mo>
          <mi>&#x03BC;<!-- μ --></mi>
          <mo>=</mo>
          <mn>{mu}</mn>
          <mo>,</mo>
          <mi>&#x03C3;<!-- σ --></mi>
          <mo>=</mo>
          <mn>{sigma}</mn>
          <mo stretchy="false">)</mo>
          <mo>,</mo>
          <mtext>&#xA0;</mtext>
          <mi>N</mi>
          <mo>=</mo>
          <mn>{N}</mn>
        </math>
        """.format(N=self.size, mu=self.mean, sigma=self.std)
        
    def _repr_mimebundle_(self, include, exclude, **kwargs):
        """
        repr_mimebundle should accept include, exclude and **kwargs
        """
        if self._png_data is None:
            self._png_data = self._figure_data('png')
        math = r'$\mathcal{N}(\mu=%.2g, \sigma=%.2g),\ N=%d$' % (self.mean,
                                                                 self.std, self.size)
        data = {'image/png':self._png_data,
                'text/latex':math,
                'application/mathml+xml': self._compute_mathml()
                }
        if include:
            data = {k:v for (k,v) in data.items() if k in include}
        if exclude:
            data = {k:v for (k,v) in data.items() if k not in exclude}
        return data
# that is definitively wrong as it should show the PNG. 
display(Gaussian())<jupyter_output><empty_output><jupyter_text>In the above example, the 3 mimetypes are embedded in the notebook document this allowing custom extensions and converters to display the representation(s) of their choice.For example, converting this noetebook to _epub_ may decide to use the MathML representation as most ebook reader cannot run mathjax (unlike browsers).  Implementation guidelinesThe `_repr_mimebundle_` methods is also given two keywords parameters :  `include` and `exclude`. Each can be a  containers (e.g.:`list`, `set` ...) of mimetypes to return or `None`, This allows implementation to avoid computing potentially unnecessary and expensive mimetypes representations. When `include` is non-empty (empty `list` or None), `_repr_mimebundle_` may decide to returns only the mimetypes in include.When `exclude` is non-empty, `_repr_mimebundle_` may decide to not return any mimetype in exclude. If both `include` and `exclude` and overlap, mimetypes present in exclude may not be returned. If implementations decide to ignore the `include` and `exclude` logic and always returns a full mimebundles, the IPython kernel will take care of removing non-desired representations.The `_repr_mimebundle_` method should accept arbitrary keyword arguments for future compatiility.<jupyter_code>display(Gaussian(), include={'text/latex'}) # only show latex
display(Gaussian(), exclude={'image/png'}) # exclude png
display(Gaussian(), include={'text/plain', 'image/png'}, exclude={'image/png'}) # keep only plain/text<jupyter_output><empty_output><jupyter_text>More complex display with `_ipython_display_` Rich output special methods and functions can only display one object or MIME type at a time. Sometimes this is not enough if you want to display multiple objects or MIME types at once. An example of this would be to use an HTML representation to put some HTML elements in the DOM and then use a JavaScript representation to add events to those elements.**IPython 2.0** recognizes another display method, `_ipython_display_`, which allows your objects to take complete control of displaying themselves. If this method is defined, IPython will call it, and make no effort to display the object using the above described `_repr_*_` methods for custom display functions. It's a way for you to say "Back off, IPython, I can display this myself." Most importantly, your `_ipython_display_` method can make multiple calls to the top-level `display` functions to accomplish its goals.Here is an object that uses `display_html` and `display_javascript` to make a plot using the [Flot](http://www.flotcharts.org/) JavaScript plotting library:<jupyter_code>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(list(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)

import numpy as np
x = np.linspace(0,10)
y = np.sin(x)
FlotPlot(x, np.sin(x))<jupyter_output><empty_output>
{'fraction_non_alphanumeric': 0.09447296486432429, 'fraction_numerical': 0.007267151143409561, 'mean_word_length': 3.4576523031203568, 'pattern_counts': {'":': 0, '<': 117, '<?xml version=': 0, '>': 119, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 3}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 5, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'chain_length': '20', 'dir': 'jupyter-structured-clean-dedup', 'id': '168970', 'license': 'MIT', 'n_tokens_mistral': 4523, 'n_tokens_neox': 4368, 'n_words': 1553, 'path': 'CustomDisplayLogic.ipynb', 'repo_name': 'RonSheely/jupyter-notebooks', 'size': '14999'}