SwiftNiceScale

Generate ‘nice’ numbers for label ticks over a range, such as for y-axis on a chart.

Adapted from pseudo-code in Graphics Gems, Volume 1 by Andrew S. Glassner (1995). See also Tufte’s The Visual Display of Quantitative Information (p149 in 2001 edition) for a discussion of topic.

Available as an open source Swift library to be incorporated in other apps.

SwiftNiceScale is part of the OpenAlloc family of open source Swift software tools.

NiceScale

let ns = NiceScale(105...543, desiredTicks: 5)!

print("nice range=\(ns.range)")

=> "nice range=100.0...600.0"

print("tick interval=\(ns.tickInterval)")

=> "tick interval=100.0"

print("labels=\(ns.tickValues)")

=> "labels=[100.0, 200.0, 300.0, 400.0, 500.0, 600.0]"

Types

The ValueRange type is declared within NiceScale, where T is your BinaryFloatingPoint data type:

typealias ValueRange = ClosedRange<T>

Instance Properties and Methods

Initializer

init?(_ rawRange: NiceScale<T>.ValueRange, desiredTicks: Int) - create a new NiceScale instance

Initialization will fail and return nil if provided nonsense parameters, such as a range with zero extent, or a desired tick count less than 2.

The initialization values are also available as properties:

let rawRange: NiceScale<T>.ValueRange - the source range from which to calculate a nice scaling
let desiredTicks: Int - the desired number of ticks in the scaling (default: 10)

Instance Properties

Computed properties are lazy, meaning that they are only calculated when first needed.

The basic set of properties…

var range: NiceScale<T>.ValueRange - The calculated ‘nice’ range, which should include the ‘raw’ range used to initialize this object.
var extent: T - The distance between bounds of the range.
var ticks: Int - The number of ticks in the range. This may differ from the desiredTicks used to initialize the object.
var tickInterval: T - The distance between ticks in the range.
var tickValues: [T] - The values for the ticks in the range.
var tickFractionDigits: Int - Number of fractional digits to show in tick label values.

More specialized properties dealing with positive and negative portions of scale…

var hasNegativeRange: Bool - If true, the range includes negative values.
var hasPositiveRange: Bool - If true, the range includes positive values.
var negativeRange: NiceScale<T>.ValueRange - The portion of the range that is negative. 0…0 if none.
var positiveRange: NiceScale<T>.ValueRange - The portion of the range that is positive. 0…0 if none.
var negativeExtent: T - If there’s a negative portion of range, the distance between its lower bound and 0. A non-negative value.
var positiveExtent: T - If there’s a positive portion of range, the distance between its upper bound and 0. A non-negative value.
var negativeExtentUnit: T? - The negativeExtent, expressed as unit value in the range 0…1.
var positiveExtentUnit: T? - The positiveExtent, expressed as unit value in the range 0…1.

Instance Methods

func scaleToUnit(T) -> T - Scale value to 0…1 in the range.
func scaleToUnitNegative(T) -> T - Scale value to 0…1 in the negative portion of range, if any.
func scaleToUnitPositive(T) -> T - Scale value to 0…1 in the positive portion of range, if any.

License

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Contributing

Other contributions are welcome too. You are encouraged to submit pull requests to fix bugs, improve documentation, or offer new features.

The pull request need not be a production-ready feature or fix. It can be a draft of proposed changes, or simply a test to show that expected behavior is buggy. Discussion on the pull request can proceed from there.

Contributions should ultimately have adequate test coverage. See tests for current entities to see what coverage is expected.