scale: make tick levels useful and explicit

Currently tick level selection is essentially black box. As a result,
it's difficult for a caller to affect the optimization in interesting
ways. The only way to do this now is to pass a predicate function down
into the optimizer, but that's fairly limited.

Swap the role of the optimizer and the scale: make the scale API
expose ticks at any level, and make the optimizer a (useful) public
API that takes a scale and computes a tick level. The existing Ticks
method remains, but now callers that need more sophisticated
optimization can invoke the optimizer directly. This also eliminates
the need for the predicate since the caller can easily tweak the tick
level returned by the optimizer according to whatever criteria it has
and then pass the updated tick level back into the scale.

Author: aclements

scale/linear.go

@@ -105,6 +105,34 @@ func (s *Linear) spacingAtLevel(level int, roundOut bool) (firstN, lastN, spacin
 	return
 }
 
+// CountTicks returns the number of ticks in [s.Min, s.Max] at the
+// given tick level.
+func (s Linear) CountTicks(level int) int {
+	return linearTicker{&s, false}.CountTicks(level)
+}
+
+// TicksAtLevel returns the tick locations in [s.Min, s.Max] as a
+// []float64 at the given tick level in ascending order.
+func (s Linear) TicksAtLevel(level int) interface{} {
+	return linearTicker{&s, false}.TicksAtLevel(level)
+}
+
+type linearTicker struct {
+	s        *Linear
+	roundOut bool
+}
+
+func (t linearTicker) CountTicks(level int) int {
+	firstN, lastN, _ := t.s.spacingAtLevel(level, t.roundOut)
+	return int(lastN - firstN + 1)
+}
+
+func (t linearTicker) TicksAtLevel(level int) interface{} {
+	firstN, lastN, spacing := t.s.spacingAtLevel(level, t.roundOut)
+	n := int(lastN - firstN + 1)
+	return vec.Linspace(firstN*spacing, lastN*spacing, n)
+}
+
 func (s Linear) Ticks(o TickOptions) (major, minor []float64) {
 	if o.Max <= 0 {
 		return nil, nil
@@ -114,24 +142,11 @@ func (s Linear) Ticks(o TickOptions) (major, minor []float64) {
 		s.Min, s.Max = s.Max, s.Min
 	}
 
-	// nticksAtLevel returns the number of ticks in [s.Min, s.Max]
-	// at the given level.
-	nticksAtLevel := func(level int) int {
-		firstN, lastN, _ := s.spacingAtLevel(level, false)
-		return int(lastN - firstN + 1)
-	}
-
-	ticksAtLevel := func(level int) []float64 {
-		firstN, lastN, spacing := s.spacingAtLevel(level, false)
-		n := int(lastN - firstN + 1)
-		return vec.Linspace(firstN*spacing, lastN*spacing, n)
-	}
-
-	level, ok := o.FindLevel(nticksAtLevel, ticksAtLevel, s.guessLevel())
+	level, ok := o.FindLevel(linearTicker{&s, false}, s.guessLevel())
 	if !ok {
 		return nil, nil
 	}
-	return ticksAtLevel(level), ticksAtLevel(level - 1)
+	return s.TicksAtLevel(level).([]float64), s.TicksAtLevel(level - 1).([]float64)
 }
 
 func (s *Linear) Nice(o TickOptions) {
@@ -142,18 +157,7 @@ func (s *Linear) Nice(o TickOptions) {
 		s.Min, s.Max = s.Max, s.Min
 	}
 
-	nticksAtLevel := func(level int) int {
-		firstN, lastN, _ := s.spacingAtLevel(level, true)
-		return int(lastN - firstN + 1)
-	}
-
-	ticksAtLevel := func(level int) []float64 {
-		firstN, lastN, spacing := s.spacingAtLevel(level, true)
-		n := int(lastN - firstN + 1)
-		return vec.Linspace(firstN*spacing, lastN*spacing, n)
-	}
-
-	level, ok := o.FindLevel(nticksAtLevel, ticksAtLevel, s.guessLevel())
+	level, ok := o.FindLevel(linearTicker{s, true}, s.guessLevel())
 	if !ok {
 		return
 	}

scale/log.go

@@ -130,58 +130,64 @@ func (s *Log) spacingAtLevel(level int, roundOut bool) (firstN, lastN, ebase flo
 	return
 }
 
-func (s *Log) tickFuncs(roundOut bool) (func(level int) int, func(level int) []float64) {
-	neg, min, max := s.ebounds()
+func (s *Log) CountTicks(level int) int {
+	return logTicker{s, false}.CountTicks(level)
+}
 
-	// nticksAtLevel returns the number of ticks in [min, max] at
-	// the given level.
-	nticksAtLevel := func(level int) int {
-		if level < 0 {
-			const maxInt = int(^uint(0) >> 1)
-			return maxInt
-		}
+func (s *Log) TicksAtLevel(level int) interface{} {
+	return logTicker{s, false}.TicksAtLevel(level)
+}
 
-		firstN, lastN, _ := s.spacingAtLevel(level, roundOut)
-		return int(lastN - firstN + 1)
-	}
-
-	ticksAtLevel := func(level int) []float64 {
-		ticks := []float64{}
-
-		if level < 0 {
-			// Minor ticks for level 0. Get the major
-			// ticks, but round out so we can fill in
-			// minor ticks outside of the major ticks.
-			firstN, lastN, _ := s.spacingAtLevel(0, true)
-			for n := firstN; n <= lastN; n++ {
-				tick := math.Pow(float64(s.Base), n)
-				step := tick
-				for i := 0; i < s.Base-1; i++ {
-					if min <= tick && tick <= max {
-						ticks = append(ticks, tick)
-					}
-					tick += step
+type logTicker struct {
+	s        *Log
+	roundOut bool
+}
+
+func (t logTicker) CountTicks(level int) int {
+	if level < 0 {
+		const maxInt = int(^uint(0) >> 1)
+		return maxInt
+	}
+
+	firstN, lastN, _ := t.s.spacingAtLevel(level, t.roundOut)
+	return int(lastN - firstN + 1)
+}
+
+func (t logTicker) TicksAtLevel(level int) interface{} {
+	neg, min, max := t.s.ebounds()
+	ticks := []float64{}
+
+	if level < 0 {
+		// Minor ticks for level 0. Get the major
+		// ticks, but round out so we can fill in
+		// minor ticks outside of the major ticks.
+		firstN, lastN, _ := t.s.spacingAtLevel(0, true)
+		for n := firstN; n <= lastN; n++ {
+			tick := math.Pow(float64(t.s.Base), n)
+			step := tick
+			for i := 0; i < t.s.Base-1; i++ {
+				if min <= tick && tick <= max {
+					ticks = append(ticks, tick)
 				}
-			}
-		} else {
-			firstN, lastN, base := s.spacingAtLevel(level, roundOut)
-			for n := firstN; n <= lastN; n++ {
-				ticks = append(ticks, math.Pow(base, n))
+				tick += step
 			}
 		}
-
-		if neg {
-			// Negate and reverse order of ticks.
-			for i := 0; i < (len(ticks)+1)/2; i++ {
-				j := len(ticks) - i - 1
-				ticks[i], ticks[j] = -ticks[j], -ticks[i]
-			}
+	} else {
+		firstN, lastN, base := t.s.spacingAtLevel(level, t.roundOut)
+		for n := firstN; n <= lastN; n++ {
+			ticks = append(ticks, math.Pow(base, n))
 		}
+	}
 
-		return ticks
+	if neg {
+		// Negate and reverse order of ticks.
+		for i := 0; i < (len(ticks)+1)/2; i++ {
+			j := len(ticks) - i - 1
+			ticks[i], ticks[j] = -ticks[j], -ticks[i]
+		}
 	}
 
-	return nticksAtLevel, ticksAtLevel
+	return ticks
 }
 
 func (s Log) Ticks(o TickOptions) (major, minor []float64) {
@@ -190,23 +196,23 @@ func (s Log) Ticks(o TickOptions) (major, minor []float64) {
 	} else if s.Min == s.Max {
 		return []float64{s.Min}, []float64{s.Max}
 	}
-	count, ticks := s.tickFuncs(false)
+	t := logTicker{&s, false}
 
-	level, ok := o.FindLevel(count, ticks, 0)
+	level, ok := o.FindLevel(t, 0)
 	if !ok {
 		return nil, nil
 	}
-	return ticks(level), ticks(level - 1)
+	return t.TicksAtLevel(level).([]float64), t.TicksAtLevel(level - 1).([]float64)
 }
 
 func (s *Log) Nice(o TickOptions) {
 	if s.Min == s.Max {
 		return
 	}
 	neg, _, _ := s.ebounds()
-	count, ticks := s.tickFuncs(true)
+	t := logTicker{s, true}
 
-	level, ok := o.FindLevel(count, ticks, 0)
+	level, ok := o.FindLevel(t, 0)
 	if !ok {
 		return
 	}

scale/ticks.go

@@ -20,37 +20,40 @@ type TickOptions struct {
 	// levels to accept, respectively. If they are both 0, there is
 	// no limit on acceptable tick levels.
 	MinLevel, MaxLevel int
+}
+
+// A Ticker computes tick marks for a scale. The "level" of the ticks
+// controls how many ticks there are and how closely they are spaced.
+// Higher levels have fewer ticks, while lower levels have more ticks.
+// For example, on a numerical scale, one could have ticks at every
+// n*(10^level).
+type Ticker interface {
+	// CountTicks returns the number of ticks at level in this
+	// scale's input range. This is equivalent to
+	// len(TicksAtLevel(level)), but should be much more
+	// efficient. CountTicks is a weakly monotonically decreasing
+	// function of level.
+	CountTicks(level int) int
 
-	// Pred returns true if ticks is an acceptable set of major
-	// ticks. ticks will be in increasing order. Pred must be
-	// "monotonic" in level in the following sense: if Pred is
-	// false for level l (or ticks t), it must be false for all l'
-	// < l (or len(t') > len(t)), and if Pred is true for level l
-	// (or ticks t), it must be true for all l' > l (or len(t') <
-	// len(t)). In other words, Pred should return false if there
-	// are "too many" ticks or they are "too close together".
-	//
-	// If Pred is nil, it is assumed to always be satisfied.
-	Pred func(ticks []float64, level int) bool
+	// TicksAtLevel returns a slice of "nice" tick values in
+	// increasing order at level in this scale's input range.
+	// Typically, TicksAtLevel(l+1) is a subset of
+	// TicksAtLevel(l). That is, higher levels remove ticks from
+	// lower levels.
+	TicksAtLevel(level int) interface{}
 }
 
 // FindLevel returns the lowest level that satisfies the constraints
 // given by o:
 //
-// * count(level) <= o.Max
+// * ticker.CountTicks(level) <= o.Max
 //
 // * o.MinLevel <= level <= o.MaxLevel (if MinLevel and MaxLevel != 0).
 //
-// * o.Pred(ticks(level), level) is true (if o.Pred != nil).
-//
 // If the constraints cannot be satisfied, it returns 0, false.
 //
-// ticks(level) must return the tick marks at level in increasing
-// order. count(level) must return len(ticks(level)), but should do so
-// without constructing the ticks array because it may be very large.
-// count must be a weakly monotonically decreasing function of level.
 // guess is the level to start the optimization at.
-func (o *TickOptions) FindLevel(count func(level int) int, ticks func(level int) []float64, guess int) (int, bool) {
+func (o *TickOptions) FindLevel(ticker Ticker, guess int) (int, bool) {
 	minLevel, maxLevel := o.MinLevel, o.MaxLevel
 	if minLevel == 0 && maxLevel == 0 {
 		minLevel, maxLevel = -1000, 1000
@@ -70,20 +73,20 @@ func (o *TickOptions) FindLevel(count func(level int) int, ticks func(level int)
 	}
 
 	// Optimize count against o.Max.
-	if count(l) <= o.Max {
+	if ticker.CountTicks(l) <= o.Max {
 		// We're satisfying the o.Max and min/maxLevel
 		// constraints. count is monotonically decreasing, so
 		// decrease level to increase the count until we
 		// violate either o.Max or minLevel.
-		for l--; l >= minLevel && count(l) <= o.Max; l-- {
+		for l--; l >= minLevel && ticker.CountTicks(l) <= o.Max; l-- {
 		}
 		// We went one too far.
 		l++
 	} else {
 		// We're over o.Max. Increase level to decrease the
 		// count until we go below o.Max. This may cause us to
 		// violate maxLevel.
-		for l++; l <= maxLevel && count(l) > o.Max; l++ {
+		for l++; l <= maxLevel && ticker.CountTicks(l) > o.Max; l++ {
 		}
 		if l > maxLevel {
 			// We can't satisfy both o.Max and maxLevel.
@@ -94,18 +97,5 @@ func (o *TickOptions) FindLevel(count func(level int) int, ticks func(level int)
 	// At this point l is the lowest value that satisfies the
 	// o.Max, minLevel, and maxLevel constraints.
 
-	// Optimize ticks against o.Pred.
-	if o.Pred != nil {
-		// Increase level until Pred is satisfied. This may
-		// cause us to violate maxLevel.
-		for l <= maxLevel && !o.Pred(ticks(l), l) {
-			l++
-		}
-		if l > maxLevel {
-			// We can't satisfy both maxLevel and Pred.
-			return 0, false
-		}
-	}
-
 	return l, true
 }

scale/ticks_test.go

@@ -6,28 +6,32 @@ package scale
 
 import "testing"
 
-func TestTicks(t *testing.T) {
-	count := func(level int) int {
-		c := 10 - level
-		if c < 1 {
-			c = 1
-		}
-		return c
+type testTicker struct{}
+
+func (testTicker) CountTicks(level int) int {
+	c := 10 - level
+	if c < 1 {
+		c = 1
 	}
-	ticks := func(level int) []float64 {
-		m := make([]float64, count(level))
-		for i := 0; i < len(m); i++ {
-			m[i] = float64(i)
-		}
-		return m
+	return c
+}
+
+func (t testTicker) TicksAtLevel(level int) interface{} {
+	m := make([]float64, t.CountTicks(level))
+	for i := 0; i < len(m); i++ {
+		m[i] = float64(i)
 	}
+	return m
+}
+
+func TestTicks(t *testing.T) {
 	check := func(o TickOptions, want int) {
 		wantL, wantOK := want, true
 		if want == -999 {
 			wantL, wantOK = 0, false
 		}
 		for _, guess := range []int{0, -50, 50} {
-			l, ok := o.FindLevel(count, ticks, guess)
+			l, ok := o.FindLevel(testTicker{}, guess)
 			if l != wantL || ok != wantOK {
 				t.Errorf("%+v.FindLevel with guess %v returned %v, %v; wanted %v, %v", o, guess, l, ok, wantL, wantOK)
 			}
@@ -52,12 +56,4 @@ func TestTicks(t *testing.T) {
 	check(TickOptions{Max: 6, MaxLevel: 9}, 4)
 	check(TickOptions{Max: 6, MaxLevel: 3}, -999)
 	check(TickOptions{Max: 6, MinLevel: 10, MaxLevel: 11}, 10)
-
-	// Predicate always matches.
-	check(TickOptions{Max: 6, Pred: func(t []float64, level int) bool { return true }}, 4)
-	// Predicate matches in the middle of the satisfiable region.
-	check(TickOptions{Max: 6, Pred: func(t []float64, level int) bool { return level >= 6 }}, 6)
-	check(TickOptions{Max: 6, MinLevel: 5, MaxLevel: 1000, Pred: func(t []float64, level int) bool { return level >= 6 }}, 6)
-	// Predicate does not match in the satisfiable region.
-	check(TickOptions{Max: 6, MaxLevel: 5, Pred: func(t []float64, level int) bool { return level >= 6 }}, -999)
 }