plotting.py 21.6 KB
Newer Older
1
2
# coding: utf-8
# pylint: disable = C0103
3
"""Plotting library."""
4
5
from __future__ import absolute_import

wxchan's avatar
wxchan committed
6
import warnings
7
from copy import deepcopy
wxchan's avatar
wxchan committed
8
9
from io import BytesIO

10
11
import numpy as np

wxchan's avatar
wxchan committed
12
from .basic import Booster
13
14
from .compat import (MATPLOTLIB_INSTALLED, GRAPHVIZ_INSTALLED, LGBMDeprecationWarning,
                     range_, zip_, string_type)
15
16
17
from .sklearn import LGBMModel


18
19
def _check_not_tuple_of_2_elements(obj, obj_name='obj'):
    """Check object is not tuple or does not have 2 elements."""
20
21
    if not isinstance(obj, tuple) or len(obj) != 2:
        raise TypeError('%s must be a tuple of 2 elements.' % obj_name)
wxchan's avatar
wxchan committed
22
23


24
25
26
27
28
29
def _float2str(value, precision=None):
    return ("{0:.{1}f}".format(value, precision)
            if precision is not None and not isinstance(value, string_type)
            else str(value))


30
31
32
33
def plot_importance(booster, ax=None, height=0.2,
                    xlim=None, ylim=None, title='Feature importance',
                    xlabel='Feature importance', ylabel='Features',
                    importance_type='split', max_num_features=None,
34
35
                    ignore_zero=True, figsize=None, grid=True,
                    precision=None, **kwargs):
36
    """Plot model's feature importances.
37
38
39

    Parameters
    ----------
wxchan's avatar
wxchan committed
40
    booster : Booster or LGBMModel
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
        Booster or LGBMModel instance which feature importance should be plotted.
    ax : matplotlib.axes.Axes or None, optional (default=None)
        Target axes instance.
        If None, new figure and axes will be created.
    height : float, optional (default=0.2)
        Bar height, passed to ``ax.barh()``.
    xlim : tuple of 2 elements or None, optional (default=None)
        Tuple passed to ``ax.xlim()``.
    ylim : tuple of 2 elements or None, optional (default=None)
        Tuple passed to ``ax.ylim()``.
    title : string or None, optional (default="Feature importance")
        Axes title.
        If None, title is disabled.
    xlabel : string or None, optional (default="Feature importance")
        X-axis title label.
        If None, title is disabled.
    ylabel : string or None, optional (default="Features")
        Y-axis title label.
        If None, title is disabled.
    importance_type : string, optional (default="split")
        How the importance is calculated.
        If "split", result contains numbers of times the feature is used in a model.
        If "gain", result contains total gains of splits which use the feature.
    max_num_features : int or None, optional (default=None)
65
        Max number of top features displayed on plot.
66
67
68
69
70
71
72
        If None or <1, all features will be displayed.
    ignore_zero : bool, optional (default=True)
        Whether to ignore features with zero importance.
    figsize : tuple of 2 elements or None, optional (default=None)
        Figure size.
    grid : bool, optional (default=True)
        Whether to add a grid for axes.
73
74
    precision : int or None, optional (default=None)
        Used to restrict the display of floating point values to a certain precision.
75
    **kwargs
76
        Other parameters passed to ``ax.barh()``.
77
78
79

    Returns
    -------
80
81
    ax : matplotlib.axes.Axes
        The plot with model's feature importances.
82
    """
83
    if MATPLOTLIB_INSTALLED:
84
        import matplotlib.pyplot as plt
85
    else:
wxchan's avatar
wxchan committed
86
        raise ImportError('You must install matplotlib to plot importance.')
87
88

    if isinstance(booster, LGBMModel):
wxchan's avatar
wxchan committed
89
90
91
92
93
94
        booster = booster.booster_
    elif not isinstance(booster, Booster):
        raise TypeError('booster must be Booster or LGBMModel.')

    importance = booster.feature_importance(importance_type=importance_type)
    feature_name = booster.feature_name()
95
96

    if not len(importance):
97
        raise ValueError("Booster's feature_importance is empty.")
98

99
    tuples = sorted(zip_(feature_name, importance), key=lambda x: x[1])
100
101
102
103
    if ignore_zero:
        tuples = [x for x in tuples if x[1] > 0]
    if max_num_features is not None and max_num_features > 0:
        tuples = tuples[-max_num_features:]
104
    labels, values = zip_(*tuples)
105
106

    if ax is None:
107
        if figsize is not None:
108
            _check_not_tuple_of_2_elements(figsize, 'figsize')
wxchan's avatar
wxchan committed
109
        _, ax = plt.subplots(1, 1, figsize=figsize)
110
111
112
113

    ylocs = np.arange(len(values))
    ax.barh(ylocs, values, align='center', height=height, **kwargs)

114
    for x, y in zip_(values, ylocs):
115
116
117
        ax.text(x + 1, y,
                _float2str(x, precision) if importance_type == 'gain' else x,
                va='center')
118
119
120
121
122

    ax.set_yticks(ylocs)
    ax.set_yticklabels(labels)

    if xlim is not None:
123
        _check_not_tuple_of_2_elements(xlim, 'xlim')
124
125
126
127
128
    else:
        xlim = (0, max(values) * 1.1)
    ax.set_xlim(xlim)

    if ylim is not None:
129
        _check_not_tuple_of_2_elements(ylim, 'ylim')
130
131
132
133
134
135
136
137
138
139
140
141
    else:
        ylim = (-1, len(values))
    ax.set_ylim(ylim)

    if title is not None:
        ax.set_title(title)
    if xlabel is not None:
        ax.set_xlabel(xlabel)
    if ylabel is not None:
        ax.set_ylabel(ylabel)
    ax.grid(grid)
    return ax
wxchan's avatar
wxchan committed
142
143


144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
def plot_split_value_histogram(booster, feature, bins=None, ax=None, width_coef=0.8,
                               xlim=None, ylim=None,
                               title='Split value histogram for feature with @index/name@ @feature@',
                               xlabel='Feature split value', ylabel='Count',
                               figsize=None, grid=True, **kwargs):
    """Plot split value histogram for the specified feature of the model.

    Parameters
    ----------
    booster : Booster or LGBMModel
        Booster or LGBMModel instance of which feature split value histogram should be plotted.
    feature : int or string
        The feature name or index the histogram is plotted for.
        If int, interpreted as index.
        If string, interpreted as name.
    bins : int, string or None, optional (default=None)
        The maximum number of bins.
        If None, the number of bins equals number of unique split values.
        If string, it should be one from the list of the supported values by ``numpy.histogram()`` function.
    ax : matplotlib.axes.Axes or None, optional (default=None)
        Target axes instance.
        If None, new figure and axes will be created.
    width_coef : float, optional (default=0.8)
        Coefficient for histogram bar width.
    xlim : tuple of 2 elements or None, optional (default=None)
        Tuple passed to ``ax.xlim()``.
    ylim : tuple of 2 elements or None, optional (default=None)
        Tuple passed to ``ax.ylim()``.
    title : string or None, optional (default="Split value histogram for feature with @index/name@ @feature@")
        Axes title.
        If None, title is disabled.
        @feature@ placeholder can be used, and it will be replaced with the value of ``feature`` parameter.
        @index/name@ placeholder can be used,
        and it will be replaced with ``index`` word in case of ``int`` type ``feature`` parameter
        or ``name`` word in case of ``string`` type ``feature`` parameter.
    xlabel : string or None, optional (default="Feature split value")
        X-axis title label.
        If None, title is disabled.
    ylabel : string or None, optional (default="Count")
        Y-axis title label.
        If None, title is disabled.
    figsize : tuple of 2 elements or None, optional (default=None)
        Figure size.
    grid : bool, optional (default=True)
        Whether to add a grid for axes.
    **kwargs
        Other parameters passed to ``ax.bar()``.

    Returns
    -------
    ax : matplotlib.axes.Axes
        The plot with specified model's feature split value histogram.
    """
    if MATPLOTLIB_INSTALLED:
        import matplotlib.pyplot as plt
        from matplotlib.ticker import MaxNLocator
    else:
        raise ImportError('You must install matplotlib to plot split value histogram.')

    if isinstance(booster, LGBMModel):
        booster = booster.booster_
    elif not isinstance(booster, Booster):
        raise TypeError('booster must be Booster or LGBMModel.')

    hist, bins = booster.get_split_value_histogram(feature=feature, bins=bins, xgboost_style=False)
    if np.count_nonzero(hist) == 0:
        raise ValueError('Cannot plot split value histogram, '
                         'because feature {} was not used in splitting'.format(feature))
    width = width_coef * (bins[1] - bins[0])
    centred = (bins[:-1] + bins[1:]) / 2

    if ax is None:
        if figsize is not None:
            _check_not_tuple_of_2_elements(figsize, 'figsize')
        _, ax = plt.subplots(1, 1, figsize=figsize)

    ax.bar(centred, hist, align='center', width=width, **kwargs)

    if xlim is not None:
        _check_not_tuple_of_2_elements(xlim, 'xlim')
    else:
        range_result = bins[-1] - bins[0]
        xlim = (bins[0] - range_result * 0.2, bins[-1] + range_result * 0.2)
    ax.set_xlim(xlim)

    ax.yaxis.set_major_locator(MaxNLocator(integer=True))
    if ylim is not None:
        _check_not_tuple_of_2_elements(ylim, 'ylim')
    else:
        ylim = (0, max(hist) * 1.1)
    ax.set_ylim(ylim)

    if title is not None:
        title = title.replace('@feature@', str(feature))
        title = title.replace('@index/name@', ('name' if isinstance(feature, string_type) else 'index'))
        ax.set_title(title)
    if xlabel is not None:
        ax.set_xlabel(xlabel)
    if ylabel is not None:
        ax.set_ylabel(ylabel)
    ax.grid(grid)
    return ax


248
249
250
251
252
253
254
255
256
257
def plot_metric(booster, metric=None, dataset_names=None,
                ax=None, xlim=None, ylim=None,
                title='Metric during training',
                xlabel='Iterations', ylabel='auto',
                figsize=None, grid=True):
    """Plot one metric during training.

    Parameters
    ----------
    booster : dict or LGBMModel
258
259
        Dictionary returned from ``lightgbm.train()`` or LGBMModel instance.
    metric : string or None, optional (default=None)
260
261
        The metric name to plot.
        Only one metric supported because different metrics have various scales.
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
        If None, first metric picked from dictionary (according to hashcode).
    dataset_names : list of strings or None, optional (default=None)
        List of the dataset names which are used to calculate metric to plot.
        If None, all datasets are used.
    ax : matplotlib.axes.Axes or None, optional (default=None)
        Target axes instance.
        If None, new figure and axes will be created.
    xlim : tuple of 2 elements or None, optional (default=None)
        Tuple passed to ``ax.xlim()``.
    ylim : tuple of 2 elements or None, optional (default=None)
        Tuple passed to ``ax.ylim()``.
    title : string or None, optional (default="Metric during training")
        Axes title.
        If None, title is disabled.
    xlabel : string or None, optional (default="Iterations")
        X-axis title label.
        If None, title is disabled.
    ylabel : string or None, optional (default="auto")
        Y-axis title label.
        If 'auto', metric name is used.
        If None, title is disabled.
    figsize : tuple of 2 elements or None, optional (default=None)
        Figure size.
    grid : bool, optional (default=True)
        Whether to add a grid for axes.
287
288
289

    Returns
    -------
290
291
    ax : matplotlib.axes.Axes
        The plot with metric's history over the training.
292
    """
293
    if MATPLOTLIB_INSTALLED:
294
        import matplotlib.pyplot as plt
295
    else:
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
        raise ImportError('You must install matplotlib to plot metric.')

    if isinstance(booster, LGBMModel):
        eval_results = deepcopy(booster.evals_result_)
    elif isinstance(booster, dict):
        eval_results = deepcopy(booster)
    else:
        raise TypeError('booster must be dict or LGBMModel.')

    num_data = len(eval_results)

    if not num_data:
        raise ValueError('eval results cannot be empty.')

    if ax is None:
        if figsize is not None:
312
            _check_not_tuple_of_2_elements(figsize, 'figsize')
313
314
315
316
317
318
319
320
321
322
323
324
325
326
        _, ax = plt.subplots(1, 1, figsize=figsize)

    if dataset_names is None:
        dataset_names = iter(eval_results.keys())
    elif not isinstance(dataset_names, (list, tuple, set)) or not dataset_names:
        raise ValueError('dataset_names should be iterable and cannot be empty')
    else:
        dataset_names = iter(dataset_names)

    name = next(dataset_names)  # take one as sample
    metrics_for_one = eval_results[name]
    num_metric = len(metrics_for_one)
    if metric is None:
        if num_metric > 1:
wxchan's avatar
wxchan committed
327
328
            msg = """more than one metric available, picking one to plot."""
            warnings.warn(msg, stacklevel=2)
329
330
331
332
333
334
        metric, results = metrics_for_one.popitem()
    else:
        if metric not in metrics_for_one:
            raise KeyError('No given metric in eval results.')
        results = metrics_for_one[metric]
    num_iteration, max_result, min_result = len(results), max(results), min(results)
335
    x_ = range_(num_iteration)
336
337
338
339
340
341
342
343
344
345
346
    ax.plot(x_, results, label=name)

    for name in dataset_names:
        metrics_for_one = eval_results[name]
        results = metrics_for_one[metric]
        max_result, min_result = max(max(results), max_result), min(min(results), min_result)
        ax.plot(x_, results, label=name)

    ax.legend(loc='best')

    if xlim is not None:
347
        _check_not_tuple_of_2_elements(xlim, 'xlim')
348
349
350
351
352
    else:
        xlim = (0, num_iteration)
    ax.set_xlim(xlim)

    if ylim is not None:
353
        _check_not_tuple_of_2_elements(ylim, 'ylim')
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
    else:
        range_result = max_result - min_result
        ylim = (min_result - range_result * 0.2, max_result + range_result * 0.2)
    ax.set_ylim(ylim)

    if ylabel == 'auto':
        ylabel = metric

    if title is not None:
        ax.set_title(title)
    if xlabel is not None:
        ax.set_xlabel(xlabel)
    if ylabel is not None:
        ax.set_ylabel(ylabel)
    ax.grid(grid)
    return ax


372
def _to_graphviz(tree_info, show_info, feature_names, precision=None, **kwargs):
373
374
375
    """Convert specified tree to graphviz instance.

    See:
376
      - https://graphviz.readthedocs.io/en/stable/api.html#digraph
377
    """
378
    if GRAPHVIZ_INSTALLED:
379
        from graphviz import Digraph
380
    else:
381
        raise ImportError('You must install graphviz to plot tree.')
wxchan's avatar
wxchan committed
382
383

    def add(root, parent=None, decision=None):
384
        """Recursively add node or edge."""
wxchan's avatar
wxchan committed
385
        if 'split_index' in root:  # non-leaf
386
            name = 'split{0}'.format(root['split_index'])
wxchan's avatar
wxchan committed
387
            if feature_names is not None:
388
                label = 'split_feature_name: {0}'.format(feature_names[root['split_feature']])
wxchan's avatar
wxchan committed
389
            else:
390
                label = 'split_feature_index: {0}'.format(root['split_feature'])
391
            label += r'\nthreshold: {0}'.format(_float2str(root['threshold'], precision))
wxchan's avatar
wxchan committed
392
            for info in show_info:
393
                if info in {'split_gain', 'internal_value', 'internal_weight'}:
394
                    label += r'\n{0}: {1}'.format(info, _float2str(root[info], precision))
395
396
                elif info == 'internal_count':
                    label += r'\n{0}: {1}'.format(info, root[info])
wxchan's avatar
wxchan committed
397
            graph.node(name, label=label)
398
            if root['decision_type'] == '<=':
399
                l_dec, r_dec = '<=', '>'
400
            elif root['decision_type'] == '==':
401
402
403
                l_dec, r_dec = 'is', "isn't"
            else:
                raise ValueError('Invalid decision type in tree model.')
wxchan's avatar
wxchan committed
404
405
406
            add(root['left_child'], name, l_dec)
            add(root['right_child'], name, r_dec)
        else:  # leaf
407
408
            name = 'leaf{0}'.format(root['leaf_index'])
            label = 'leaf_index: {0}'.format(root['leaf_index'])
409
            label += r'\nleaf_value: {0}'.format(_float2str(root['leaf_value'], precision))
wxchan's avatar
wxchan committed
410
            if 'leaf_count' in show_info:
411
                label += r'\nleaf_count: {0}'.format(root['leaf_count'])
412
413
            if 'leaf_weight' in show_info:
                label += r'\nleaf_weight: {0}'.format(_float2str(root['leaf_weight'], precision))
wxchan's avatar
wxchan committed
414
415
416
417
            graph.node(name, label=label)
        if parent is not None:
            graph.edge(parent, name, decision)

418
    graph = Digraph(**kwargs)
wxchan's avatar
wxchan committed
419
    add(tree_info['tree_structure'])
420
421
422
423

    return graph


424
def create_tree_digraph(booster, tree_index=0, show_info=None, precision=None,
425
426
427
                        old_name=None, old_comment=None, old_filename=None, old_directory=None,
                        old_format=None, old_engine=None, old_encoding=None, old_graph_attr=None,
                        old_node_attr=None, old_edge_attr=None, old_body=None, old_strict=False, **kwargs):
428
    """Create a digraph representation of specified tree.
429

430
431
432
    Note
    ----
    For more information please visit
433
    https://graphviz.readthedocs.io/en/stable/api.html#digraph.
434

435
436
    Parameters
    ----------
437
    booster : Booster or LGBMModel
438
        Booster or LGBMModel instance to be converted.
439
440
    tree_index : int, optional (default=0)
        The index of a target tree to convert.
441
442
    show_info : list of strings or None, optional (default=None)
        What information should be shown in nodes.
443
444
        Possible values of list items:
        'split_gain', 'internal_value', 'internal_count', 'internal_weight', 'leaf_count', 'leaf_weight'.
445
446
    precision : int or None, optional (default=None)
        Used to restrict the display of floating point values to a certain precision.
447
    **kwargs
448
449
        Other parameters passed to ``Digraph`` constructor.
        Check https://graphviz.readthedocs.io/en/stable/api.html#digraph for the full list of supported parameters.
450
451
452

    Returns
    -------
453
454
    graph : graphviz.Digraph
        The digraph representation of specified tree.
455
456
457
458
459
460
    """
    if isinstance(booster, LGBMModel):
        booster = booster.booster_
    elif not isinstance(booster, Booster):
        raise TypeError('booster must be Booster or LGBMModel.')

461
462
463
464
465
    for param_name in ['old_name', 'old_comment', 'old_filename', 'old_directory',
                       'old_format', 'old_engine', 'old_encoding', 'old_graph_attr',
                       'old_node_attr', 'old_edge_attr', 'old_body']:
        param = locals().get(param_name)
        if param is not None:
466
            warnings.warn('{0} parameter is deprecated and will be removed in 2.4 version.\n'
467
468
469
470
471
                          'Please use **kwargs to pass {1} parameter.'.format(param_name, param_name[4:]),
                          LGBMDeprecationWarning)
            if param_name[4:] not in kwargs:
                kwargs[param_name[4:]] = param
    if locals().get('strict'):
472
        warnings.warn('old_strict parameter is deprecated and will be removed in 2.4 version.\n'
473
474
475
476
477
                      'Please use **kwargs to pass strict parameter.',
                      LGBMDeprecationWarning)
        if 'strict' not in kwargs:
            kwargs['strict'] = True

478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
    model = booster.dump_model()
    tree_infos = model['tree_info']
    if 'feature_names' in model:
        feature_names = model['feature_names']
    else:
        feature_names = None

    if tree_index < len(tree_infos):
        tree_info = tree_infos[tree_index]
    else:
        raise IndexError('tree_index is out of range.')

    if show_info is None:
        show_info = []

493
    graph = _to_graphviz(tree_info, show_info, feature_names, precision, **kwargs)
494

wxchan's avatar
wxchan committed
495
496
497
498
    return graph


def plot_tree(booster, ax=None, tree_index=0, figsize=None,
499
500
              old_graph_attr=None, old_node_attr=None, old_edge_attr=None,
              show_info=None, precision=None, **kwargs):
wxchan's avatar
wxchan committed
501
502
    """Plot specified tree.

503
504
505
506
507
    Note
    ----
    It is preferable to use ``create_tree_digraph()`` because of its lossless quality
    and returned objects can be also rendered and displayed directly inside a Jupyter notebook.

wxchan's avatar
wxchan committed
508
509
    Parameters
    ----------
510
511
512
513
514
515
516
517
    booster : Booster or LGBMModel
        Booster or LGBMModel instance to be plotted.
    ax : matplotlib.axes.Axes or None, optional (default=None)
        Target axes instance.
        If None, new figure and axes will be created.
    tree_index : int, optional (default=0)
        The index of a target tree to plot.
    figsize : tuple of 2 elements or None, optional (default=None)
wxchan's avatar
wxchan committed
518
        Figure size.
519
520
    show_info : list of strings or None, optional (default=None)
        What information should be shown in nodes.
521
522
        Possible values of list items:
        'split_gain', 'internal_value', 'internal_count', 'internal_weight', 'leaf_count', 'leaf_weight'.
523
524
    precision : int or None, optional (default=None)
        Used to restrict the display of floating point values to a certain precision.
525
    **kwargs
526
527
        Other parameters passed to ``Digraph`` constructor.
        Check https://graphviz.readthedocs.io/en/stable/api.html#digraph for the full list of supported parameters.
wxchan's avatar
wxchan committed
528
529
530

    Returns
    -------
531
532
    ax : matplotlib.axes.Axes
        The plot with single tree.
wxchan's avatar
wxchan committed
533
    """
534
    if MATPLOTLIB_INSTALLED:
wxchan's avatar
wxchan committed
535
536
        import matplotlib.pyplot as plt
        import matplotlib.image as image
537
    else:
wxchan's avatar
wxchan committed
538
539
        raise ImportError('You must install matplotlib to plot tree.')

540
541
542
    for param_name in ['old_graph_attr', 'old_node_attr', 'old_edge_attr']:
        param = locals().get(param_name)
        if param is not None:
543
            warnings.warn('{0} parameter is deprecated and will be removed in 2.4 version.\n'
544
545
546
547
548
                          'Please use **kwargs to pass {1} parameter.'.format(param_name, param_name[4:]),
                          LGBMDeprecationWarning)
            if param_name[4:] not in kwargs:
                kwargs[param_name[4:]] = param

wxchan's avatar
wxchan committed
549
    if ax is None:
550
        if figsize is not None:
551
            _check_not_tuple_of_2_elements(figsize, 'figsize')
wxchan's avatar
wxchan committed
552
553
        _, ax = plt.subplots(1, 1, figsize=figsize)

554
555
    graph = create_tree_digraph(booster=booster, tree_index=tree_index,
                                show_info=show_info, precision=precision, **kwargs)
wxchan's avatar
wxchan committed
556
557

    s = BytesIO()
558
    s.write(graph.pipe(format='png'))
wxchan's avatar
wxchan committed
559
560
561
562
563
564
    s.seek(0)
    img = image.imread(s)

    ax.imshow(img)
    ax.axis('off')
    return ax