Backport PR #31801: DOC: Document tick objects · matplotlib/matplotlib@1c4cde0 · GitHub
Skip to content

Commit 1c4cde0

Browse files
timhoffmmeeseeksmachine
timhoffm
authored and
meeseeksmachine
committed
Backport PR #31801: DOC: Document tick objects
1 parent 9b7a43f commit 1c4cde0

4 files changed

Lines changed: 71 additions & 3 deletions

File tree

‎doc/api/axes_api.rst‎

Lines changed: 2 additions & 0 deletions

‎doc/api/axis_api.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,8 @@ Axis Label
8080
Axis.get_label_position
8181
Axis.get_label_text
8282

83+
.. _axis-api-ticks:
84+
8385
Ticks, tick labels and Offset text
8486
----------------------------------
8587

‎galleries/users_explain/axes/axes_ticks.py‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -227,6 +227,8 @@ def fmt_two_digits(x, pos):
227227

228228
# %%
229229
#
230+
# .. _axes-ticks-styling:
231+
#
230232
# Styling ticks (tick parameters)
231233
# ===============================
232234
#
@@ -273,3 +275,53 @@ def fmt_two_digits(x, pos):
273275
grid_color='none')
274276
ax.tick_params(axis='x', color='m', length=4, direction='in', width=4,
275277
labelcolor='g', grid_color='b')
278+
279+
# %%
280+
#
281+
# .. _axes-tick-objects:
282+
#
283+
# Tick objects
284+
# ============
285+
#
286+
# .. warning::
287+
#
288+
# Ticks are managed through the autoscaling / view limit mechanism, which may
289+
# create, move and delete ticks as necessary.
290+
#
291+
# Working with tick instances should only be an option of last resort and requires
292+
# careful handling to not accidentally overwrite any manual changes through this
293+
# mechanism.
294+
#
295+
# If a tick configuration can be achieved through `.Axes.tick_params` (see
296+
# :ref:`axes-ticks-styling`), that approach should be preferred.
297+
#
298+
# On the technical level, ticks are realized through `.Tick` objects. They consist of
299+
#
300+
# - ``tick1line`` / ``tick2line`` for the tick lines on either side of the axis.
301+
# - ``label1`` / ``label2`` for the tick labels on either side of the axis.
302+
# - ``gridline`` for the grid line.
303+
#
304+
# These objects are publicly accessible through :ref:`Axes methods <axes-api-ticks>`
305+
# and :ref:`Axis methods <axis-api-ticks>` and allow extreme customization such as
306+
# coloring a specific tick line or tick label separately.
307+
308+
x = 1.1 * np.exp(-3 * np.random.random(500))
309+
y = np.random.random(500)
310+
311+
fig, ax = plt.subplots()
312+
313+
ax.plot(x, y, 'o')
314+
ax.grid()
315+
ticks = ax.set_xticks([0, 0.2, 0.4, 0.6, 0.8, 1, 1.2])
316+
ticks[5].label1.set_color("red")
317+
ticks[5].tick1line.set_markeredgecolor("red")
318+
ticks[5].gridline.set(visible=True, linestyle=':', linewidth=1.5, color='red')
319+
320+
# %%
321+
# Because of the managed nature of ticks, such operations only make sense for static
322+
# output (e.g., when using the jupyter inline backend or saving the figure to a file)
323+
# or when you are sure that the view limits of the axis will not change (e.g., when
324+
# using a fixed locator).
325+
#
326+
# In contrast, `.Axes.tick_params` configures the default properties so that they are
327+
# applied to all current and future ticks.

‎lib/matplotlib/axis.py‎

Lines changed: 15 additions & 3 deletions

0 commit comments

Comments
 (0)