def set_footnote(self, caption, alpha=0.8, lineheight=1.25, fontsize='smaller', *args, **kwargs):
"""
Add a caption to the subplot.
The caption is added just beneath the title.
The method re-draws the title to make space for the caption.
The caption is a :class:`~text.text.Annotation` object.
Any arguments that the constructor accepts can be provided to this method.
:param caption: The caption to add to the axes.
:type caption: str
:param alpha: The opacity of the caption between 0 and 1.
:type alpha: float
:param lineheight: The space between lines.
:type lineheight: float
:param fontsize: The font of the footnote, defaults to `smaller`.
:type fontsize: str or int
:return: The drawn caption.
:rtype: :class:`~text.annotation.Annotation`
"""
self.footnote = Annotation(self, caption, (0, 1), 0,
va='top', alpha=alpha, lineheight=lineheight,
transform=self.axes.transAxes, fontsize=fontsize,
*args, **kwargs)
self.footnote.draw()
self.redraw()
return self.footnote
def draw_annotation(self, label, x, y, va='bottom', *args, **kwargs):
"""
Get the annotation for the legend.
The arguments and keyword arguments are passed on to the :meth:`~text.annotation.Annotation.draw` function.
:param label: The text of the legend label.
:type label: str
:param x: The starting x-coordinate of the annotation.
:type x: float
:param y: The y-coordinate of the annotation.
:type y: float
:param va: The vertical alignment, can be one of `top`, `center` or `bottom`.
If the vertical alignment is `top`, the given y-coordinate becomes the highest point of the annotation.
If the vertical alignment is `center`, the given y-coordinate becomes the center point of the annotation.
If the vertical alignment is `bottom`, the given y-coordinate becomes the lowest point of the annotation.
:type va: str
:return: The drawn annotation.
:rtype: :class:`~text.annotation.Annotation`
"""
figure = self.drawable.figure
axis = self.drawable.axis
annotation = Annotation(self.drawable)
annotation.draw(label, (x, 1),
y,
va=va,
transform=axis.transAxes,
**kwargs)
return annotation
def draw_annotation(self, label, x, y, va='bottom', *args, **kwargs):
"""
Draw a text annotation.
This function is called by the :func:`~legend.Legend.draw` function after drawing the visual part of the legend annotation.
The text annotation is based on the :class:`~text.annotation.Annotation` class.
The arguments and keyword arguments are passed on to the :func:`~text.annotation.Annotation.draw` function.
:param label: The text of the legend label.
:type label: str
:param x: The starting x-coordinate of the annotation.
:type x: float
:param y: The y-coordinate of the annotation.
:type y: float
:param va: The vertical alignment, can be one of `top`, `center` or `bottom`.
If the vertical alignment is `top`, the given y-coordinate becomes the highest point of the annotation.
If the vertical alignment is `center`, the given y-coordinate becomes the center point of the annotation.
If the vertical alignment is `bottom`, the given y-coordinate becomes the lowest point of the annotation.
:type va: str
:return: The drawn annotation.
:rtype: :class:`~text.annotation.Annotation`
"""
figure = self.drawable.figure
axes = self.drawable.axes
annotation = Annotation(self.drawable,
label, (x, 1),
y,
va=va,
transform=axes.transAxes,
**kwargs)
annotation.draw()
return annotation
def test_set_position_no_tokens(self): """ Test that when setting the position of an annotation with no tokens, nothing changes. """ viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) self.assertEqual(None, annotation.set_position((0, 0)))
def test_align_left(self): """ Test that when aligning text left, all lines start at the same x-coordinate. """ text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground.' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) lines = annotation.draw(text, (0, 2), 0, align='left', va='top')
def test_set_position_invalid_horizontal_alignment(self): """ Test that when setting the position of an annotation with an invalid horizontal alignment, a ValueError is raised. """ text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground.' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) annotation.draw(text, (0, 1), 0) self.assertRaises(ValueError, annotation.set_position, (0, 2), ha='invalid')
def test_x_pad_justify_end(self): """ Test that when padding is applied with `justify-end` alignment, the block moves to the left. """ text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground.' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) annotation.draw(text, (0, 1), 0, pad=0.2, align='justify-end') bb = annotation.get_virtual_bb() self.assertGreaterEqual(0.8, round(bb.x1, 10))
def test_y_pad_bottom(self): """ Test that when applying padding with `bottom` vertical alignment, the block moves up. """ text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground.' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) annotation.draw(text, (0, 1), 0, pad=0.2, va='bottom') bb = annotation.get_virtual_bb() self.assertEqual(0.2, round(bb.y0, 10))
def test_center_one_line(self): """ Test that when centering a single line, each token in that line is centered. """ text = 'Memphis Depay plays for Olympique Lyonnais' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) lines = annotation.draw(text, (0, 1), 0, va='center') for token in lines[0]: bb = util.get_bb(viz.figure, viz.axis, lines[0][0]) self.assertEqual(0, (bb.y1 + bb.y0) / 2.)
def test_text(self): """ Test that the text is written correctly. """ text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground.' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) lines = annotation.draw(text, (0, 2), 0, align='left', va='top') drawn_text = self._reconstruct_text(lines) self.assertEqual(text, drawn_text)
def test_align_bottom_order(self):
"""
Test that when the vertical alignment is bottom, the order of lines is still correct.
"""
text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground.'
viz = drawable.Drawable(plt.figure(figsize=(10, 10)))
annotation = Annotation(viz)
lines = annotation.draw(text, (0, 1), 0, va='bottom')
self.assertEqual('Memphis', lines[0][0].get_text())
self.assertEqual('ground.', lines[-1][-1].get_text())
def test_align_justify_right(self): """ Test that when justifying text with the last line being right-aligned, the last line ends at the farthest right. """ text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground.' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) lines = annotation.draw(text, (0, 2), 0, align='justify-end', va='top') bb = util.get_bb(viz.figure, viz.axis, lines[0][-1]) self.assertEqual(2, round(bb.x1, 5))
def test_center_one_token(self): """ Test that when centering a single token, the middle of the annotation is equivalent to the middle coordinate of the token. """ text = 'Memphis' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) lines = annotation.draw(text, (0, 1), 0, va='center') bb = util.get_bb(viz.figure, viz.axis, lines[0][0]) self.assertEqual(0, (bb.y1 + bb.y0) / 2.) virtual_bb = annotation.get_virtual_bb() self.assertEqual(0, (virtual_bb.y1 + virtual_bb.y0) / 2.)
def test_draw_x_float(self):
"""
Test that when drawing an annotation with a float as the x-bounds, the limit of the plot is used.
"""
text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground.'
viz = drawable.Drawable(plt.figure(figsize=(10, 10)))
annotation = Annotation(viz)
annotation.draw(text, np.float64(0.2), 0)
bb = annotation.get_virtual_bb()
self.assertEqual(round(0.2, 10), round(bb.x0, 10))
self.assertLessEqual(0.95, bb.x1)
self.assertGreaterEqual(1, bb.x1)
def test_align_bottom(self): """ Test that when the alignment is top, all lines are above the provided y-coordinate. """ text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground.' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) lines = annotation.draw(text, (0, 1), 0, va='bottom') bb = util.get_bb(viz.figure, viz.axis, lines[-1][-1]) self.assertEqual(0, bb.y0) for line in lines: self.assertGreaterEqual(0, bb.y0)
def test_get_virtual_bb_line(self): """ Test that the virtual bounding box of an annotation with one line spans the entire line. """ text = 'Memphis Depay plays for Olympique Lyonnais' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) lines = annotation.draw(text, (0, 1), 0) self.assertEqual(1, len(lines)) virtual_bb = annotation.get_virtual_bb() self.assertEqual(util.get_bb(viz.figure, viz.axis, lines[0][0]).x0, virtual_bb.x0) self.assertEqual(util.get_bb(viz.figure, viz.axis, lines[0][0]).y0, virtual_bb.y0) self.assertEqual(util.get_bb(viz.figure, viz.axis, lines[0][-1]).x1, virtual_bb.x1) self.assertEqual(util.get_bb(viz.figure, viz.axis, lines[0][-1]).y1, virtual_bb.y1)
def test_get_virtual_bb_single_token(self): """ Test that the virtual bounding box of an annotation with one token is equivalent to the bounding box of a single token. """ text = 'Memphis' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) lines = annotation.draw(text, (0, 1), 0) bb = util.get_bb(viz.figure, viz.axis, lines[0][0]) virtual_bb = annotation.get_virtual_bb() self.assertEqual(bb.x0, virtual_bb.x0) self.assertEqual(bb.y0, virtual_bb.y0) self.assertEqual(bb.x1, virtual_bb.x1) self.assertEqual(bb.y1, virtual_bb.y1)
def test_align_bottom_lines_do_not_overlap(self): """ Test that when annotations are vertically aligned to the bottom, the lines do not overlap. """ text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground.' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) lines = annotation.draw(text, (0, 1), 0, va='bottom') for i in range(0, len(lines) - 1): bb0 = util.get_bb(viz.figure, viz.axis, lines[i][0]) bb1 = util.get_bb(viz.figure, viz.axis, lines[i + 1][0]) self.assertGreaterEqual(bb0.y0, bb1.y1)
def test_center_multiple_even_lines(self): """ Test that when centering multiple even lines, the block is centered around the given point. """ text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground. Depay began his professional career with PSV Eindhoven.' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) lines = annotation.draw(text, (0, 1), 0, va='center') self.assertGreater(len(lines), 1) self.assertFalse(len(lines) % 2) tokens = [ tokens[0] for tokens in lines ] bb1 = util.get_bb(viz.figure, viz.axis, tokens[0]) bb2 = util.get_bb(viz.figure, viz.axis, tokens[-1]) self.assertEqual(0, round((bb1.y1 + bb2.y0) / 2., 10))
def test_get_virtual_bb_multiple_lines(self): """ Test that the virtual bounding box of an annotation with multiple lines spans the entire block. """ text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground.' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) lines = annotation.draw(text, (0, 1), 0) self.assertGreater(len(lines), 1) virtual_bb = annotation.get_virtual_bb() self.assertEqual(util.get_bb(viz.figure, viz.axis, lines[0][0]).x0, virtual_bb.x0) self.assertEqual(util.get_bb(viz.figure, viz.axis, lines[-1][-1]).y0, virtual_bb.y0) self.assertEqual(max(util.get_bb(viz.figure, viz.axis, lines[line][-1]).x1 for line in range(0, len(lines))), virtual_bb.x1) self.assertEqual(util.get_bb(viz.figure, viz.axis, lines[0][0]).y1, virtual_bb.y1)
def test_align_bottom_line_alignment(self): """ Test that the lines all have the same vertical position when they are aligned to the top. """ text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground.' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) lines = annotation.draw(text, (0, 1), 0, va='bottom') for line in lines: bb = util.get_bb(viz.figure, viz.axis, line[0]) y1 = bb.y1 for token in line: bb = util.get_bb(viz.figure, viz.axis, token) self.assertEqual(y1, bb.y1)
def annotate(self, text, x, y, marker=None, pad=0.01, *args, **kwargs):
"""
Add a text annotation to the plot.
This function can be used to draw attention to certain or describe the visualization on the plot itself.
Any additional arguments and keyword arguments are passed on to the :class:`~text.annotation.Annotation`'s :func:`~text.annotation.Annotation.draw` function.
For example, the `va` can be provided to specify the text's vertical alignment, andthe `align` parameter can be used to specify the text's alignment.
:param text: The text of the annotation to draw.
:type text: str
:param x: A tuple containing the start and end x-coordinates of the annotation.
:type x: tuple
:param y: The y-coordinate of the annotation.
:type y: float
:param marker: The marker style.
If it is not given, no marker is drawn.
:type marker: None or dict
:param pad: The amount of padding applied to the annotation.
:type pad: float
:return: The drawn annotation.
:rtype: :class:`~text.annotation.Annotation`
"""
annotation = Annotation(self)
self.figure.canvas.draw()
"""
Draw the marker if it is given.
The color is obtained from the kwargs if a marker color is not given.
The point of the marker is based on the alignment of the annotation.
"""
if marker is not None:
marker = dict(
marker) # make a copy to avoid overwriting dictionaries
marker['color'] = marker.get('color', kwargs.get('color'))
if kwargs.get('align', 'left') == 'left':
self.axes.plot(x[0], y, *args, **marker)
elif kwargs.get('align') == 'right':
self.axes.plot(x[1], y, *args, **marker)
elif kwargs.get('align') == 'center':
self.axes.plot((x[0] + x[1]) / 2., y, *args, **marker)
tokens = annotation.draw(text, x, y, pad=pad, *args, **kwargs)
self.annotations.append(annotation)
return annotation
def test_align_right(self): """ Test that when aligning text right, all lines end at the same x-coordinate. """ text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground.' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) lines = annotation.draw(text, (0, 2), 0, align='right', va='top') x = 0 for i, lines in enumerate(lines): bb = util.get_bb(viz.figure, viz.axis, lines[-1]) if i == 0: x = bb.x1 self.assertEqual(round(x, 5), round(bb.x1, 5))
def test_align_invalid(self): """ Test that when an invalid alignment is given, a :class:`~ValueError` is raised. """ text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground.' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) self.assertRaises(ValueError, annotation.draw, text, (0, 2), 0, va='top', align='invalid')
def __init__(self, figure, axis=None):
"""
Create the drawable with the figure.
:param figure: The figure that the :class:`~Drawable` class wraps.
This is mainly used to get the figure renderer.
:type figure: :class:`matplotlib.figure.Figure`
:param axis: The axis (or subplot) where to plot visualizations.
If `None` is not given, the plot's main subplot is used instead.
:type axis: `None` or :class:`matplotlib.axis.Axis`
"""
self.figure = figure
self.axis = plt.gca() if axis is None else axis
self.caption = Annotation(self)
self.annotations = []
self.legend = Legend(self)
self.timeseries = None
def test_align_center(self): """ Test that when centering text, all of the lines' centers are the same. """ text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground.' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) lines = annotation.draw(text, (0, 2), 0, align='center', va='top') x = 0 for i, lines in enumerate(lines[:-1]): bb0 = util.get_bb(viz.figure, viz.axis, lines[0]) bb1 = util.get_bb(viz.figure, viz.axis, lines[-1]) center = (bb0.x0 + bb1.x1) / 2. if i == 0: x = center self.assertEqual(round(x, 5), round(center, 5))
def test_align_justify(self): """ Test that when justifying text, all lines start and end at the same x-coordinate. The calculation is made on the center since the bboxes of text do not start or end at the exact same coordinate. """ text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground.' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) lines = annotation.draw(text, (0, 2), 0, align='justify', va='top') x = 0 for i, lines in enumerate(lines[:-1]): # skip the last line as it is not justified bb0 = util.get_bb(viz.figure, viz.axis, lines[0]) bb1 = util.get_bb(viz.figure, viz.axis, lines[-1]) center = (bb0.x0 + bb1.x1) / 2. if i == 0: x = center self.assertEqual(round(x, 5), round(center, 5))
def draw_label(self,
label,
x,
y,
va='center',
max_iterations=100,
*args,
**kwargs):
"""
Draw a label at the end of the line.
Any additional arguments and keyword arguments are passed on to the :func:`text.annotation.Annotation.draw` function.
:param label: The label to draw.
:type label: str
:param x: The x-position of the annotation.
The function expects either a float or a tuple.
If a float is given, it is taken to be the start x-position of the annotation.
The end x-position is taken from the axes limit.
If a tuple is given, the first two values are the start and end x-position of the annotation.
:type x: float
:param y: The y-position of the last point on the line.
:type y: float
:param va: The vertical alignment, can be one of `top`, `center` or `bottom`.
If the vertical alignment is `top`, the annotation grows down.
If the vertical alignment is `center`, the annotation is centered around the given y-coordinate.
If the vertical alignment is `bottom`, the annotation grows up.
:type va: str
:param max_iterations: The maximum number of iterations to spend arranging the labels.
:type max_iterations: int
:return: The drawn label.
:rtype: :class:`~text.annotation.Annotation`
"""
figure = self.drawable.figure
axes = self.drawable.axes
style = dict(kwargs)
style = {
key: value
for key, value in style.items()
if not (key.startswith('marker') or key.startswith('line'))
}
annotation = Annotation(self.drawable,
label,
x,
y,
va=va,
*args,
**style)
self.labels.append(annotation)
self._arrange_labels(annotation, max_iterations=max_iterations)
return annotation
def annotate(self, text, x, y, marker=None, pad=0.01, *args, **kwargs):
"""
Add an annotation to the plot.
Any additional arguments and keyword arguments are passed on to the annotation's :meth:`~text.text.Annotation.draw` function.
For example, the `va` can be provided to specify the vertical alignment.
The `align` parameter can be used to specify the text's alignment.
:param text: The text of the annotation to draw.
:type text: str
:param x: A tuple containing the start and end x-coordinates of the annotation.
:type x: tuple
:param y: The y-coordinate of the annotation.
:type y: float
:param marker: The marker style.
If it is not given, no marker is drawn.
:type marker: None or dict
:param pad: The amount of padding applied to the annotation.
:type pad: float
"""
annotation = Annotation(self)
"""
Draw the marker if it is given.
The color is obtained from the kwargs if a marker color is not given.
The point of the marker is based on the alignment of the annotation.
"""
if marker is not None:
marker['color'] = marker.get('color', kwargs.get('color'))
if kwargs.get('align', 'left') == 'left':
self.axis.plot(x[0], y, *args, **marker)
elif kwargs.get('align') == 'right':
self.axis.plot(x[1], y, *args, **marker)
elif kwargs.get('align') == 'center':
self.axis.plot((x[0] + x[1]) / 2., y, *args, **marker)
tokens = annotation.draw(text, x, y, pad=pad, *args, **kwargs)
self.annotations.append(annotation)
return tokens
def test_set_position_horizontal_center(self): """ Test that when moving an annotation with a `center` horizontal alignment, the block is centered around the given point. """ text = 'Memphis Depay, commonly known simply as Memphis, is a Dutch professional footballer and music artist who plays as a forward and captains French club Lyon and plays for the Netherlands national team. He is known for his pace, ability to cut inside, dribbling, distance shooting and ability to play the ball off the ground.' viz = drawable.Drawable(plt.figure(figsize=(10, 10))) annotation = Annotation(viz) annotation.draw(text, (0, 1), 0, align='center') annotation.set_position((2, 0), ha='center') bb = annotation.get_virtual_bb() self.assertEqual(2, (bb.x0 + bb.x1)/2.)