Deprecate axis_ticks_direction

Use +ve|-ve|complex values of axis_ticks_length to control the
direction of the ticks.

closes #876

doc/_quartodoc.yml

@@ -383,9 +383,6 @@ quartodoc:
  - axis_text_x
  - axis_text_y
  - axis_ticks
- - axis_ticks_direction
- - axis_ticks_direction_x
- - axis_ticks_direction_y
  - axis_ticks_length
  - axis_ticks_length_major
  - axis_ticks_length_major_x

doc/changelog.qmd

@@ -15,6 +15,13 @@ title: Changelog
  accepts the value `"hlsuv"` instead of `"husl"`. The meaning of has
  not changed, and `"husl"` is silently accepted.
 
+- Themeables `axis_ticks_direction`, `axis_ticks_direction_x` and
+ `axis_ticks_direction_y` have be deprecated. In their place, the direction
+ of the ticks can be controlled by using +ve, -ve or complex values for
+ the `axis_ticks_length`, `axis_ticks_length_major`, `axis_ticks_length_major_x`,
+ `axis_ticks_length_major_y`, `axis_ticks_length_minor`, `axis_ticks_length_minor_x`,
+ or `axis_ticks_length_minor_y`.
+
 ### Enhancements
 
 - The `family`, `fontstyle` and `fontweight` parameters of

plotnine/themes/theme.py

@@ -176,9 +176,6 @@ def __init__(
  axis_ticks_pad_minor_y=None,
  axis_ticks_pad_minor=None,
  axis_ticks_pad=None,
- axis_ticks_direction_x=None,
- axis_ticks_direction_y=None,
- axis_ticks_direction=None,
  panel_spacing_x=None,
  panel_spacing_y=None,
  panel_spacing=None,

plotnine/themes/theme_gray.py

@@ -50,7 +50,6 @@ def __init__(self, base_size=11, base_family=None):
  axis_text_x=element_text(va="top", margin={"t": fifth_line}),
  axis_text_y=element_text(ha="right", margin={"r": fifth_line}),
  axis_ticks=element_line(color="#333333"),
- axis_ticks_direction="out",
  axis_ticks_length=0,
  axis_ticks_length_major=quarter_line,
  axis_ticks_length_minor=eighth_line,

plotnine/themes/theme_xkcd.py

@@ -46,8 +46,7 @@ def __init__(
  text=element_text(family=["xkcd", "Humor Sans", "Comic Sans MS"]),
  axis_ticks=element_line(color="black", size=1),
  axis_ticks_minor=element_blank(),
- axis_ticks_direction="in",
- axis_ticks_length_major=6,
+ axis_ticks_length_major=-6,
  legend_background=element_rect(color="black"),
  legend_box_margin=2,
  legend_margin=5,

plotnine/themes/themeable.py

@@ -1548,7 +1548,7 @@ class rect(
  """
 
 
-# value base themeables
+# themeables with scalar values
 
 
 class axis_ticks_length_major_x(themeable):
@@ -1557,20 +1557,32 @@ class axis_ticks_length_major_x(themeable):
 
  Parameters
  ----------
- theme_element : float
- Value in points.
+ theme_element : float | complex
+ Value in points. A negative value creates the ticks
+ inside the plot panel. A complex value (e.g. `3j`)
+ creates ticks that span both in and out of the panel.
  """
 
  def apply_ax(self, ax: Axes):
  super().apply_ax(ax)
+ value: float | complex = self.properties["value"]
+
  try:
- t = ax.xaxis.get_major_ticks()[0]
+ visible = ax.xaxis.get_major_ticks()[0].tick1line.get_visible()
  except IndexError:
- val = 0
+ value = 0
+ else:
+ if not visible:
+ value = 0
+
+ if isinstance(value, (float, int)):
+ tickdir = "in" if value < 0 else "out"
  else:
- val = self.properties["value"] if t.tick1line.get_visible() else 0
+ tickdir = "inout"
 
- ax.xaxis.set_tick_params(which="major", size=val)
+ ax.xaxis.set_tick_params(
+ which="major", length=abs(value), tickdir=tickdir
+ )
 
 
 class axis_ticks_length_major_y(themeable):
@@ -1579,20 +1591,32 @@ class axis_ticks_length_major_y(themeable):
 
  Parameters
  ----------
- theme_element : float
- Value in points.
+ theme_element : float | complex
+ Value in points. A negative value creates the ticks
+ inside the plot panel. A complex value (e.g. `3j`)
+ creates ticks that span both in and out of the panel.
  """
 
  def apply_ax(self, ax: Axes):
  super().apply_ax(ax)
+ value: float | complex = self.properties["value"]
+
  try:
- t = ax.yaxis.get_major_ticks()[0]
+ visible = ax.yaxis.get_major_ticks()[0].tick1line.get_visible()
  except IndexError:
- val = 0
+ value = 0
+ else:
+ if not visible:
+ value = 0
+
+ if isinstance(value, (float, int)):
+ tickdir = "in" if value < 0 else "out"
  else:
- val = self.properties["value"] if t.tick1line.get_visible() else 0
+ tickdir = "inout"
 
- ax.yaxis.set_tick_params(which="major", size=val)
+ ax.yaxis.set_tick_params(
+ which="major", length=abs(value), tickdir=tickdir
+ )
 
 
 class axis_ticks_length_major(
@@ -1604,7 +1628,9 @@ class axis_ticks_length_major(
  Parameters
  ----------
  theme_element : float
- Value in points.
+ Value in points. A negative value creates the ticks
+ inside the plot panel. A complex value (e.g. `3j`)
+ creates ticks that span both in and out of the panel.
  """
 
 
@@ -1614,14 +1640,23 @@ class axis_ticks_length_minor_x(themeable):
 
  Parameters
  ----------
- theme_element : float
- Value in points.
+ theme_element : float | complex
+ Value in points. A negative value creates the ticks
+ inside the plot panel. A complex value (e.g. `3j`)
+ creates ticks that span both in and out of the panel.
  """
 
  def apply_ax(self, ax: Axes):
  super().apply_ax(ax)
+ value: float | complex = self.properties["value"]
+
+ if isinstance(value, (float, int)):
+ tickdir = "in" if value < 0 else "out"
+ else:
+ tickdir = "inout"
+
  ax.xaxis.set_tick_params(
- which="minor", length=self.properties["value"]
+ which="minor", length=abs(value), tickdir=tickdir
  )
 
 
@@ -1631,14 +1666,23 @@ class axis_ticks_length_minor_y(themeable):
 
  Parameters
  ----------
- theme_element : float
- Value in points.
+ theme_element : float | complex
+ Value in points. A negative value creates the ticks
+ inside the plot panel. A complex value (e.g. `3j`)
+ creates ticks that span both in and out of the panel.
  """
 
  def apply_ax(self, ax: Axes):
  super().apply_ax(ax)
+ value: float | complex = self.properties["value"]
+
+ if isinstance(value, (float, int)):
+ tickdir = "in" if value < 0 else "out"
+ else:
+ tickdir = "inout"
+
  ax.yaxis.set_tick_params(
- which="minor", length=self.properties["value"]
+ which="minor", length=abs(value), tickdir=tickdir
  )
 
 
@@ -1650,8 +1694,10 @@ class axis_ticks_length_minor(
 
  Parameters
  ----------
- theme_element : float
- Value in points.
+ theme_element : float | complex
+ Value in points. A negative value creates the ticks
+ inside the plot panel. A complex value (e.g. `3j`)
+ creates ticks that span both in and out of the panel.
  """
 
 
@@ -1661,8 +1707,10 @@ class axis_ticks_length(axis_ticks_length_major, axis_ticks_length_minor):
 
  Parameters
  ----------
- theme_element : float
- Value in points.
+ theme_element : float | complex
+ Value in points. A negative value creates the ticks
+ inside the plot panel. A complex value (e.g. `3j`)
+ creates ticks that span both in and out of the panel.
  """
 
 
@@ -1816,57 +1864,6 @@ class axis_ticks_pad(axis_ticks_pad_major, axis_ticks_pad_minor):
  """
 
 
-class axis_ticks_direction_x(themeable):
- """
- x-axis tick direction
-
- Parameters
- ----------
- theme_element : Literal["in", "out", "inout"]
- `in` for ticks inside the panel.
- `out` for ticks outside the panel.
- `inout` for ticks inside and outside the panel.
- """
-
- def apply_ax(self, ax: Axes):
- super().apply_ax(ax)
- ax.xaxis.set_tick_params(
- which="major", tickdir=self.properties["value"]
- )
-
-
-class axis_ticks_direction_y(themeable):
- """
- y-axis tick direction
-
- Parameters
- ----------
- theme_element : Literal["in", "out", "inout"]
- `in` for ticks inside the panel.
- `out` for ticks outside the panel.
- `inout` for ticks inside and outside the panel.
- """
-
- def apply_ax(self, ax: Axes):
- super().apply_ax(ax)
- ax.yaxis.set_tick_params(
- which="major", tickdir=self.properties["value"]
- )
-
-
-class axis_ticks_direction(axis_ticks_direction_x, axis_ticks_direction_y):
- """
- axis tick direction
-
- Parameters
- ----------
- theme_element : Literal["in", "out", "inout"]
- `in` for ticks inside the panel.
- `out` for ticks outside the panel.
- `inout` for ticks inside and outside the panel.
- """
-
-
 class panel_spacing_x(themeable):
  """
  Horizontal spacing between the facet panels
@@ -2458,3 +2455,71 @@ def __init__(self):
  "of 'element_text' with 'lenged_title'."
  )
  warn(msg, FutureWarning, stacklevel=1)
+
+
+class axis_ticks_direction_x(themeable):
+ """
+ x-axis tick direction
+
+ Parameters
+ ----------
+ theme_element : Literal["in", "out"]
+ `in` for ticks inside the panel.
+ `out` for ticks outside the panel.
+ """
+
+ def __init__(self, theme_element):
+ msg = (
+ f"Themeable '{self.__class__.__name__}' is deprecated and"
+ "will be removed in a future version. "
+ "Use +ve or -ve values of the axis_ticks_length"
+ "to affect the direction of the ticks."
+ )
+ warn(msg, FutureWarning, stacklevel=1)
+ super().__init__(theme_element)
+
+ def apply_ax(self, ax: Axes):
+ super().apply_ax(ax)
+ ax.xaxis.set_tick_params(
+ which="major", tickdir=self.properties["value"]
+ )
+
+
+class axis_ticks_direction_y(themeable):
+ """
+ y-axis tick direction
+
+ Parameters
+ ----------
+ theme_element : Literal["in", "out"]
+ `in` for ticks inside the panel.
+ `out` for ticks outside the panel.
+ """
+
+ def __init__(self, theme_element):
+ msg = (
+ f"Themeable '{self.__class__.__name__}' is deprecated and"
+ "will be removed in a future version. "
+ "Use +ve/-ve/complex values of the axis_ticks_length"
+ "to affect the direction of the ticks."
+ )
+ warn(msg, FutureWarning, stacklevel=1)
+ super().__init__(theme_element)
+
+ def apply_ax(self, ax: Axes):
+ super().apply_ax(ax)
+ ax.yaxis.set_tick_params(
+ which="major", tickdir=self.properties["value"]
+ )
+
+
+class axis_ticks_direction(axis_ticks_direction_x, axis_ticks_direction_y):
+ """
+ axis tick direction
+
+ Parameters
+ ----------
+ theme_element : Literal["in", "out"]
+ `in` for ticks inside the panel.
+ `out` for ticks outside the panel.
+ """