document WilkinsonTicks

[t-bltg]

Description

Fix #3164.

• supersedes Document WilkinsonTicks #3717 by instead dynamically interpolate the docstring from PlotUtils.optimize_ticks (default values are identical);
• rename tickvalues -> ticklocations for consistency with the aforementioned docstring;
• remove unused min_px_dist;
• update CHANGELOG.

Resulting docstring:

help?> Makie.WilkinsonTicks
  Wilkinson's algorithm for positioning ticks.

  optimizeticks(xmin, xmax; extendticks::Bool = false, Q = [(1.0,1.0), (5.0,
  0.9), (2.0, 0.7), (2.5, 0.5), (3.0, 0.2)], kmin = 2, kmax = 10, kideal = 5,
  granularityweight = 1/4, simplicityweight = 1/6, coverageweight = 1/3,
  nicenessweight = 1/4, strictspan = true, span_buffer = nothing)

  Find some reasonable values for tick marks.

  This is basically Wilkinson's ad-hoc scoring method that tries to balance
  tight fit around the data, optimal number of ticks, and simple numbers.

  Arguments:
  ==========

    •  xmax:
       The maximum value occurring in the data.

    •  xmin:
       The minimum value occurring in the data.

    •  extend_ticks:
       Determines whether to extend tick computation. Defaults to false.

    •  strict_span:
       True if no ticks should be outside [xmin, xmax]. Defaults to true.

    •  Q:
       A distribution of nice numbers from which labellings are sampled.
       Stored in the form (number, score).

    •  k_min:
       The minimum number of ticks.

    •  k_max:
       The maximum number of ticks.

    •  k_ideal:
       The ideal number of ticks.

    •  granularity_weight:
       Encourages returning roughly the number of labels requested.

    •  simplicity_weight:
       Encourages nicer labeling sequences by preferring step sizes that
       appear earlier in Q. Also rewards labelings that include 0 as a
       way to ground the sequence.

    •  coverage_weight:
       Encourages labelings that do not extend far beyond the range of
       the data, penalizing unnecessary whitespace.

    •  niceness_weight:
       Encourages labellings to produce nice ranges.

  Returns:
  ========

  (ticklocations::Vector{Float64}, x_min, x_max)

  Mathematical details
  ====================

  Wilkinson’s optimization function is defined as the sum of three components.
  If the user requests m labels and a possible labeling has k labels, then the
  components are simplicity, coverage and granularity.

  These components are defined as follows:

:$

  \begin{aligned} &\text{simplicity} = 1 - \frac{i}{|Q|} + \frac{v}{|Q|}\
  &\text{coverage} = \frac{x{max} - x{min}}{\mathrm{label}{max} -
  \mathrm{label}{min}}\ &\text{granularity}= 1 - \frac{\left|k - m\right|}{m}
  \end{aligned} :$

  and the variables here are:

    •  q: element of Q.

    •  i: index of q ∈ Q.

    •  v: 1 if label range includes 0, 0 otherwise.

Type of change

Delete options that do not apply:

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

• Added an entry in CHANGELOG.md (for new features and breaking changes)
• Added or changed relevant sections in the documentation
• Added unit tests for new algorithms, conversion methods, etc.
• Added reference image tests for new plotting functions, recipes, visual options, etc.

[jkrumbiegel]

Good idea, I think it would be best to add the default arguments manually in the docstring and after that add a line like

`WilkinsonTicks` is a thin wrapper over `PlotUtils.optimize_ticks`, the docstring of which is reproduced below:

This way it's clearer that we didn't write that part with Makie in mind.

Also, could you revert the unrelated formatting change of the commented out code, please.

[t-bltg]

Good idea, I think it would be best to add the default arguments manually in the docstring and after that add a line like

Thanks, I've added the suggestions, and the default values to the wrapper.

Also, could you revert the unrelated formatting change of the commented out code, please.

Could you clarify which changes you are referring to ?
There is no consensus about the code style to use in Makie 😕 .
#2520 was made for that purpose (avoiding style change discussions), but it doesn't seem to move forward.

[jkrumbiegel]

that one

I'd be all for deciding for a formatter style and enforcing that for consistency. It's just a bit disruptive whenever it happens. Maybe after 0.21 is a good point as I want to focus on docs and other usability stuff anyway.

[t-bltg]

To whoever will be merging this PR, please retain credits when squashing for @laikq 's contribution in #3717.

[jkrumbiegel]

you can squash your other commits into one and force push back