Introduction à matplotlib

par Samuel Bancal, EPFL-ENAC-IT, © Creative Commons BY-SA

(Document en cours de rédaction rev. 2019-12-11)

1 Introduction

1.1 Ce support de cours

Ce support de cours a pour vocation de faire une introduction rapide de la librairie matplotlib en couvrant une partie des fonctions essentielles à son utilisation. Il n’a pas pour but d’être exhaustif, ni dans le choix des fonctions, ni dans les paramètres des fonctions documentées.

Certaines méthodes peuvent être appelées depuis l’espace global plt, tel que plt.plot(). Cela s’appliquera à la figure et l’Axes courant. Il est possible de faire le même appel de façon plus ciblée ainsi : ax.plot(). Ainsi le graph sera effectué dans l’espace relatif à l’objet ax préalablement créé.

Beaucoup d’exemples donnés dans ce support sont issus de la documentation originale, avec ou sans adaptation.

Les informations originales et comlètes peuvent être trouvées en suivant les lien qui accompagnent chaque chapitre.

Pour accéder à la documentation complète de matplotlib, vous pouvez vous rendre sur extern-linkhttps://matplotlib.org/3.1.1/contents.html

Certains termes sont volontairements conservés en anglais, pour aider le lecteur à faire le lien avec la fonction ou la classe à laquelle il fait référence.

1.2 Pour suivre ce cours

Tout code Python peut être écrit dans un fichier dont l’extension est .py. Ce fichier peut ensuite être exécuté.

Pour ce cours, nous allons utiliser l’outil JupyterLab que vous pouvez librement télécharger et installer sur votre machine selon cette documentation extern-linkhttps://jupyter.org/install.html.

L’EPFL offre également un service centralisé JupyterLab ici : extern-linkhttps://noto.epfl.ch/

JupyterLab (qui est une évolution de Jupyter Notebook) nous permet d’écrire et exécuter notre code par portions et d’en voir le résultat (en texte ou en graphique), au fur et à mesure de la rédaction.

Chaque code mentionné dans ce document assume que les 3 lignes suivantes ont été exécutées en premier :

%matplotlib inline
import numpy as np
from matplotlib import pyplot as plt

2 Exemples de graphiques réalisables avec Matplotlib

Voici quelques illustrations pour rapidement voir ce qui est réalisable. Plus d’exemples peuvent être vus dans la extern-linkgalerie matlplotlib.

2.1 Simple plot

X = np.linspace(-np.pi, np.pi, 256, endpoint=True)
C, S = np.cos(X), np.sin(X)
plt.plot(X, C, label='cosinus')
plt.plot(X, S, label='sinus')

plt.title('Simple plot')
plt.legend()

plt.show()
ex_simple.png

2.2 Subplots

plt.figure(figsize=(6, 4))
plt.subplot(2, 1, 1)
plt.xticks(())
plt.yticks(())
plt.text(0.5, 0.5, 'subplot(2,1,1)', ha='center',
         va='center', size=24, alpha=.5)

plt.subplot(2, 1, 2)
plt.xticks(())
plt.yticks(())
plt.text(0.5, 0.5, 'subplot(2,1,2)', ha='center',
         va='center', size=24, alpha=.5)

plt.tight_layout()
plt.show()
ex_subplots.png

2.3 Axes

plt.axes([.1, .1, .8, .8])
plt.xticks(())
plt.yticks(())
plt.text(.6, .6, 'axes([0.1, 0.1, .8, .8])',
         ha='center', va='center',
         size=20, alpha=.5)

plt.axes([.2, .2, .3, .3])
plt.xticks(())
plt.yticks(())
plt.text(.5, .5, 'axes([0.2, 0.2, .3, .3])',
         ha='center', va='center',
         size=16, alpha=.5)

plt.show()
ex_axes.png

2.4 Ticks

def tickline():
    plt.xlim(0, 10)
    plt.ylim(-1, 0)
    plt.yticks([])
    ax = plt.gca()
    ax.spines['right'].set_color('none')
    ax.spines['left'].set_color('none')
    ax.spines['top'].set_color('none')
    ax.xaxis.set_ticks_position('bottom')
    ax.spines['bottom'].set_position(('data',0))
    ax.yaxis.set_ticks_position('none')
    ax.xaxis.set_minor_locator(plt.MultipleLocator(0.1))
    ax.plot(np.arange(11), np.ones(11))
    return ax

locators = [
                'plt.NullLocator()',
                'plt.MultipleLocator(1.0)',
                'plt.FixedLocator([0, 2, 8, 9, 10])',
                'plt.IndexLocator(3, 1)',
                'plt.LinearLocator(5)',
                'plt.LogLocator(2, [1.0])',
                'plt.AutoLocator()',
            ]

n_locators = len(locators)

size = (512, 40 * n_locators)
dpi = 75.0
figsize = (size[0] / dpi, size[1] / dpi)
fig = plt.figure(figsize=figsize, dpi=dpi)

for i, locator in enumerate(locators):
    plt.subplot(n_locators, 1, i + 1)
    ax = tickline()
    ax.xaxis.set_major_locator(eval(locator))
    plt.text(5, 0.3, locator[3:], ha='center')

plt.subplots_adjust(bottom=.01, top=.99,
                    left=.01, right=.99)
plt.show()
ex_ticks.png

2.5 Bar plot

plt.figure(figsize=(8, 6), dpi=80)
n = 15
X = np.arange(n)
Y1 = (1 - X / float(n)) * np.random.uniform(0.5, 1.0, n)
Y2 = (1 - X / float(n)) * np.random.uniform(0.5, 1.0, n)

plt.bar(X, +Y1, facecolor='#9999ff', edgecolor='white')
plt.bar(X, -Y2, facecolor='#ff9999', edgecolor='white')

for x, y in zip(X, Y1):
    plt.text(x, y + 0.05, '%.2f' % y,
             ha='center', va='bottom')
for x, y in zip(X, Y2):
    plt.text(x, -y - 0.10, '%.2f' % y,
             ha='center', va='bottom')

plt.ylim(-1.25, +1.25)
plt.xticks(())
plt.yticks(())
plt.show()
ex_barplot.png

2.6 Scatter plot

plt.figure(figsize=(8, 8), dpi=80)
n = 1024
X = np.random.random(n) * 2.0 - 1.0
Y = np.random.random(n) * 2.0 - 1.0
T = (X**2 + Y**2)**0.5 < 1.0
#T = np.arctan2(Y, X)

#plt.axes([0.025, 0.025, 0.95, 0.95])
plt.scatter(X, Y, s=75, c=T, alpha=.5)

plt.xlim(-1.1, 1.1)
plt.xticks(())
plt.ylim(-1.1, 1.1)
plt.yticks(())

plt.show()
ex_scatter.png

2.7 Contour plot

plt.figure(figsize=(8, 6), dpi=80)

def f(x, y):
    return (1 - x / 2 + x ** 5 + y ** 3) * \
           np.exp(-x ** 2 -y ** 2)

n = 256
x = np.linspace(-3, 3, n)
y = np.linspace(-3, 3, n)
X, Y = np.meshgrid(x, y)

plt.contourf(X, Y, f(X, Y), 8, alpha=.75, cmap='jet')
C = plt.contour(X, Y, f(X, Y), 8, colors='black')
ex_contour.png

2.8 Imshow

plt.figure(figsize=(12, 8), dpi=50)

def f(x, y):
    return (1 - x / 2 + x ** 5 + y ** 3) * \
           np.exp(-x ** 2 -y ** 2)

nx, ny = 40, 30
x = np.linspace(-3, 3, nx)
y = np.linspace(-3, 3, ny)
X, Y = np.meshgrid(x, y)
Z = f(X, Y)


plt.axes([0.025, 0.025, 0.95, 0.95])
plt.imshow(Z, interpolation='nearest',
           cmap=plt.cm.gist_gray, origin='lower')
plt.colorbar(shrink=0.92)

plt.xticks(())
plt.yticks(())
plt.show()
ex_imshow.png

2.9 Polar

plt.figure(figsize=(8, 8), dpi=60)

ax = plt.axes([0.025, 0.025, 0.95, 0.95], polar=True)

N = 20
theta = np.arange(0, 2 * np.pi, 2 * np.pi / N)
radii = 10 * np.random.rand(N)
width = np.pi / 4 * np.random.rand(N)
bars = plt.bar(theta, radii, width=width, bottom=0.0)

for r, bar in zip(radii, bars):
    bar.set_facecolor(plt.cm.jet(r/10.))
    bar.set_alpha(0.5)

ax.set_xticklabels([])
ax.set_yticklabels([])
plt.show()
ex_polar.png

2.10 Pie chart

fig = plt.figure(figsize=(10, 10), dpi=60)
ax = plt.axes()


size = 0.3
vals = np.array([[60., 32.], [37., 40.], [29., 10.]])

cmap = plt.get_cmap("tab20c")
outer_colors = cmap(np.arange(3)*4)
inner_colors = cmap(np.array([1, 2, 5, 6, 9, 10]))

ax.pie(vals.sum(axis=1), radius=1, colors=outer_colors,
       wedgeprops=dict(width=size, edgecolor='w'))

ax.pie(vals.flatten(), radius=1-size, colors=inner_colors,
       wedgeprops=dict(width=size, edgecolor='w'))

ax.set(aspect="equal", title='Pie plot with `ax.pie`')
plt.show()
ex_pie.png

2.11 3D plot

from mpl_toolkits.mplot3d import Axes3D

fig = plt.figure(dpi=80)
ax = Axes3D(fig)
X = np.arange(-5, 5, 0.25)
Y = np.arange(-5, 5, 0.25)
X, Y = np.meshgrid(X, Y)
R = np.sqrt(X**2 + Y**2)
Z = np.sin(R)

ax.plot_surface(X, Y, Z, rstride=1, cstride=1,
                cmap=plt.cm.hot)
ax.contourf(X, Y, Z, zdir='z', offset=-2,
            cmap=plt.cm.hot)
ax.set_zlim(-2, 2)
plt.show()
ex_3d.png

3 Glossaire

3.1 Quelques termes :

3.1.1 Figure

Objet de niveau supérieur qui contient tout ce qui peut être graphé.

3.1.2 Axes

Surface sur laquelle on peut grapher quelque chose. Il est possible de placer un Axes à n’importe quelle position.

3.1.3 Axis

Classe de base pour XAxis et YAxis qui sont les deux axes d’un graphique (abscisse et ordonnée).

3.1.4 Subplot

Moyen de diviser la surface de dessin en sous-graphes. Cela se fait verticalement ou horizontalement ou avec des combinaisons.

3.1.5 Ticks

Indicateur de position le long d’un Axis.

3.2 plt.plot() ax.plot()

extern-linkManuel Matplotlib : plt.plot()
extern-linkManuel Matplotlib : ax.plot()

plot([x], y, [fmt], *, data=None, **kwargs)
plot([x], y, [fmt], [x2], y2, [fmt2], ..., **kwargs)

Trace les lignes de y en fonction de x (ou avec des marqueurs)

3.3 Chaîne de formatage

La chaîne de formatage consiste en un str contenant des informations sur le marqueur, la ligne et la couleur.

fmt = '[marker][line][color]'
. point , pixel o cercle s carré
v triangle vers le bas ^ triangle vers le haut < triangle vers la gauche > triangle vers la droite
1 tri vers le bas 2 tri vers le haut 3 tri vers la gauche 4 tri vers la droite
p pentagone * étoile h hexagone 1 H hexagone 2
+ plus x x D diamant d petit diamond
| barre verticale _ barre horizontale
- continue -- traitillé
-. trait-point : pointillé
b bleu g vert r rouge c cyan
m magenta y jaune k noir w blanc

3.4 plt.show()

extern-linkManuel Matplotlib : plt.show()

show()

Affiche la figure.

Dans le cas d’une exécution avec le noyau ipython (utilisé par Jupyter), l’exécution rend immédiatement la main pour une nouvelle instruction. Dans le cas contraire (script *.py), l’exécution est suspendue, tant que la figure est ouverte. Ceci permet à l’utilisateur de travailler avec cette figure, sans que l’exécution ne s’arrête immédiatement.

3.5 plt.savefig()

extern-linkManuel Matplotlib : plt.savefig()

savefig(filename, transparent=False)

Sauve la figure dans un fichier image.

Utile lorsqu’on souhaite sauver une ou des figures sans interaction avec l’utilisateur dans des fichiers image. Les formats supportés peuvent dépendre

3.6 plt.title()

extern-linkManuel Matplotlib : plt.title()

plt.title(label, fontdict=None, loc='center', pad=None, **kwargs)

Ajoute un titre

{
  'fontsize': rcParams['axes.titlesize'],
  'fontweight': rcParams['axes.titleweight'],
  'verticalalignment': 'baseline',
  'horizontalalignment': loc
}

Il est également possible de définit le titre sur un Axes avec la méthode :

ax.set_title(label, fontdict=None, loc='center', pad=None, **kwargs)

extern-linkManuel Matplotlib : ax.set_title()

3.7 plt.legend()

extern-linkManuel Matplotlib : plt.legend()

legend(*args, **kwargs)

Place la légende sur l’axe. Il est conseillé, avant, d’avoir fourni l’argument label='inline label' pour chaque élément graphé pour lequel nous souhaitons avec une légende. Ainsi l’appel à plt.legend() peut se faire sans argument.

3.8 plt.figure()

extern-linkManuel Matplotlib : plt.figure()

figure([num], [figsize], [dpi], [facecolor], [edgecolor], [clear])

Créée une nouvelle figure.

Retourne l’objet d’instance de la figure.

3.9 plt.subplot()

extern-linkManuel Matplotlib : plt.subplot()

subplot(nrows, ncols, index, projection=None, polar=False)
subplot(pos, projection=None, polar=False)

Créée une nouvelle figure.

Retourne l’objet Axes du subplot sélectionné

3.10 fig.subplots()

extern-linkManuel Matplotlib : fig.subplot()

[...] = fig.subplots(nrows, ncols, sharex=False, sharey=False)

Ajoute un jeu de subplots à la figure courante et retourne les Axes créés pour ceux-ci.

Retourne une liste des objets Axes des subplots créés sur la figure

3.11 plt.text() ax.text() figure.text()

extern-linkManuel Matplotlib : plt.text()
extern-linkManuel Matplotlib : ax.text()
extern-linkManuel Matplotlib : figure.text()

text(x, y, s, **kwargs)

Écrit le texte à l’emplacement définit

3.12 plt.tight_layout() figure.tight_layout()

extern-linkManuel Matplotlib : plt.tight_layout()
extern-linkManuel Matplotlib : figure.tight_layout()

tight_layout(pad=1.08, h_pad=None, w_pad=None, rect=None)

Ajuste les espacements entre les subplots

3.13 plt.axes()

extern-linkManuel Matplotlib : plt.axes()

axes(rect, projection=None, polar=False, **kwargs)
axes(ax)

Ajoute un Axes à la figure courante et le rend actif.

Retourne un objet de type Axes ou une sous-classe.

3.14 plt.gca()

extern-linkManuel Matplotlib : plt.gca()

gca()

GCA comme «Get Current Axes»
Retourne l’objet Axes courant. Utile lorsqu’on souhaite agir directement dessus.

3.15 plt.xticks() et plt.yticks() ax.set_xticks ax.set_yticks ax.set_xticklabels ax.set_yticklabels …

extern-linkManuel Matplotlib : plt.xticks()
extern-linkManuel Matplotlib : plt.yticks()

locs, labels = plt.xticks()                   # obtient la position et les labels
plt.xticks(ticks=None, labels=None, **kwargs) # définit la position et les labels

Obtient ou définit la position et les labels des ticks sur l’axe X et Y.

Retourne un tuple (locs, labels)

L’équivalent peut être fait sur un Axes avec :

ax.set_xticks(self, ticks, minor=False)
ax.set_yticks(self, ticks, minor=False)
ax.set_xticklabels(self, labels, fontdict=None, minor=False, **kwargs)
ax.set_yticklabels(self, labels, fontdict=None, minor=False, **kwargs)

loc = ax.get_xticks(self, minor=False)
loc = ax.get_yticks(self, minor=False)
labels = ax.get_xticklabels(self, minor=False, which=None)
labels = ax.get_yticklabels(self, minor=False, which=None)

extern-linkManuel Matplotlib : ax.set_xticks()
extern-linkManuel Matplotlib : ax.set_xticklabels()
extern-linkManuel Matplotlib : ax.get_xticks()
extern-linkManuel Matplotlib : ax.get_xticklabels()

3.16 fig.autofmt_xdate()

extern-linkManuel Matplotlib : fig.autofmt_xdate()

fig.autofmt_xdate()

Lorsque l’axis des X est rempli de dates, les ticks labels se chevauchent facilement. L’appel de cette méthode formate automatiquemnt les ticks de sorte qu’ils soient inclinés à 45° et aient un bon alignement.

3.17 plt.xlim() plt.ylim() ax.xlim() ax.ylim()

extern-linkManuel Matplotlib : plt.xlim()
extern-linkManuel Matplotlib : plt.ylim()

left, right = plt.xlim()
plt.xlim(left, right)
bottom, top = plt.ylim()
plt.ylim(bottom, top)

Obtient ou définit les limites sur l’Axis X, respectivement Y

L’équivalent peut être fait sur un Axes avec :

ax.set_xlim(left, right)
left, right = ax.get_xlim()

ax.set_ylim(bottom, top)
bottom, top = ax.get_ylim()

extern-linkManuel Matplotlib : ax.set_xlim()
extern-linkManuel Matplotlib : ax.get_xlim()
extern-linkManuel Matplotlib : ax.set_ylim()
extern-linkManuel Matplotlib : ax.get_ylim()

3.18 plt.grid() ax.grid()

extern-linkManuel Matplotlib : plt.grid()
extern-linkManuel Matplotlib : ax.grid()

grid(b=None, which='major', axis='both', **kwargs)

Active ou désactive la grille, principale ou secondaire sur l’axe désiré.

3.19 ax.set_xlabel(), ax.set_ylabel(), ax.set_zlabel()

extern-linkManuel Matplotlib : ax.set_xlabel
extern-linkManuel Matplotlib : ax.set_ylabel
extern-linkManuel Matplotlib : ax.set_zlabel

ax.set_xlabel(self, xlabel, labelpad=None, **kwargs)
ax.set_ylabel(self, ylabel, labelpad=None, **kwargs)
ax.set_zlabel(self, zlabel, labelpad=None, **kwargs)

Définit le label de l’axe X, Y, respectivement Z.

3.20 plt.bar() ax.bar()

extern-linkManuel Matplotlib : plt.bar()
extern-linkManuel Matplotlib : ax.bar()

bar(x, height, width=0.8, bottom=None, *, align='center', data=None, **kwargs)

Trace un graphe composé de barres verticales

3.21 plt.fill_between() ax.fill_between()

extern-linkManuel Matplotlib : plt.fill_between()
extern-linkManuel Matplotlib : ax.fill_between()

plt.fill_between(x, y1, y2, where, **kwargs)

Color une surface entre y1 et y2 en fonction de x, où where est True

3.22 plt.scatter() ax.scatter()

extern-linkManuel Matplotlib : plt.scatter()
extern-linkManuel Matplotlib : ax.scatter()

scatter(x, y, s=None, c=None, marker=None,
        cmap=None, norm=None, vmin=None, vmax=None,
        alpha=None, linewidths=None, verts=None,
        edgecolors=None, *, plotnonfinite=False,
        data=None, **kwargs)

Graphe de nuage de points aux coordonnées fixées avec différents marqueurs, tailles et/ou couleurs

3.23 Colormaps

extern-linkManuel Matplotlib : Colormap reference

Chaque élément graphé peut être non-seulement positionné selon des axes (X, Y et Z), mais peut également être enrichit avec une couleur prise dans une table de couleurs indiquant ainsi une information supplémentaire. Ainsi un graph 2-D pourra devenir un graph dit 2-D et demi, un graph 3-D pourra devenir un graph dit 4-D.

Les colormaps à disposition peuvent être consultés en ligne ici : extern-linkhttps://matplotlib.org/3.1.1/gallery/color/colormap_reference.html

3.24 plt.colorbar() fig.colorbar()

extern-linkManuel Matplotlib : plt.colorbar()
extern-linkManuel Matplotlib : fig.colorbar()

colorbar(**kwargs)
colorbar(mappable, **kwargs)
colorbar(mappable, cax=cax, **kwargs)
colorbar(mappable, ax=ax, **kwargs)

Ajoute l’affichage du Colormap à côté du graph.

3.25 ax.set_aspect()

extern-linkManuel Matplotlib : ax.set_aspect()

set_aspect(self, aspect, adjustable=None, anchor=None, share=False

Définit l’aspect (ratio y/x) de l’Axes

3.26 plt.pcolormesh() ax.pcolormesh()

extern-linkManuel Matplotlib : plt.pcolormesh()
extern-linkManuel Matplotlib : ax.pcolormesh()

pcolormesh([X, Y,] C, **kwargs)

Dessine l’image ou les données représentés par l’array 2-D.

3.27 plt.contour() ax.contour()

extern-linkManuel Matplotlib : plt.contour()
extern-linkManuel Matplotlib : ax.contour()

contour([X, Y,] Z, [levels], **kwargs)

Dessine un graphe de contour.

3.28 plt.imshow() ax.imshow()

extern-linkManuel Matplotlib : plt.imshow()
extern-linkManuel Matplotlib : ax.imshow()

imshow(X, cmap=None, norm=None, aspect=None, interpolation=None,
       alpha=None, vmin=None, vmax=None, origin=None, extent=None,
       shape=<deprecated parameter>, filternorm=1, filterrad=4.0,
       imlim=<deprecated parameter>, resample=None, url=None, *,
       data=None, **kwargs)

Dessine l’image ou les données représentés par l’array 2-D.

3.29 ax.plot_surface()

extern-linkManuel Matplotlib : ax.plot_surface()

plot_surface(self, X, Y, Z, *args,
             norm=None, vmin=None, vmax=None, lightsource=None, **kwargs)

Dessine un graph de surface 3-D