toyplot.locator module¶
Strategy objects that compute the position and format of axis ticks and labels.
- class toyplot.locator.Explicit(locations=None, labels=None, titles=None, format='{:g}')[source]¶
Bases:
TickLocator
Explicitly specify a collection of tick locations and labels for an axis.
You must specify the set of locations, the set of labels, or both. If you only specify locations, the labels will be generated using a formatting string. If you only specify labels, the locations will default to integers in the range \([0, n)\). The latter behavior is especially useful for categorical axes.
- Parameters
locations (sequence numbers, optional) – Axis locations where ticks should be displayed.
labels (sequence of strings, optional) – Labels for each tick location.
titles (sequence of strings, optional) – Titles for each tick location. Typically, backends render titles as tooltips.
format (string, optional) – Format string used to generate labels from tick locations.
- ticks(domain_min, domain_max)[source]¶
Return a set of ticks for the given domain.
- Parameters
domain_min (number) –
domain_max (number) –
- Returns
locations (sequence of numbers) – Axis locations where ticks should be displayed.
labels (sequence of strings) – Labels for each tick location.
titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.
- class toyplot.locator.Extended(count=5, steps=None, weights=None, only_inside=False, format='{0:.{digits}f}')[source]¶
Bases:
TickLocator
Generate ticks using “An Extension of Wilkinson’s Algorithm for Positioning Tick Labels on Axes” by Talbot, Lin, and Hanrahan.
- Parameters
count (number, optional) – Desired number of ticks. Note that the algorithm may produce fewer ticks than requested.
steps (sequence of numbers, optional) – Prioritized list of “nice” values to use for generating ticks.
only_inside (boolean) – If set to True, only ticks inside the axis domain will be generated.
format (string, optional) – Format string used to generate labels from tick locations.
- ticks(domain_min, domain_max)[source]¶
Return a set of ticks for the given domain.
- Parameters
domain_min (number) –
domain_max (number) –
- Returns
locations (sequence of numbers) – Axis locations where ticks should be displayed.
labels (sequence of strings) – Labels for each tick location.
titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.
- class toyplot.locator.Heckbert(count=5, format='{0:.{digits}f}')[source]¶
Bases:
TickLocator
Generate ticks using the “Nice numbers for graph labels” algorithm by Paul Heckbert.
Note that this locator can produce ticks outside the minimum / maximum axis domain.
- Parameters
count (number of ticks to generate) –
format (string, optional) – Format string used to generate labels from tick locations.
- ticks(domain_min, domain_max)[source]¶
Return a set of ticks for the given domain.
- Parameters
domain_min (number) –
domain_max (number) –
- Returns
locations (sequence of numbers) – Axis locations where ticks should be displayed.
labels (sequence of strings) – Labels for each tick location.
titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.
- class toyplot.locator.Integer(step=1)[source]¶
Bases:
TickLocator
Generate evenly-spaced integer ticks
- Parameters
step (integer, optional) –
labels. (Number of integer values to skip between) –
- ticks(domain_min, domain_max)[source]¶
Return a set of ticks for the given domain.
- Parameters
domain_min (number) –
domain_max (number) –
- Returns
locations (sequence of numbers) – Axis locations where ticks should be displayed.
labels (sequence of strings) – Labels for each tick location.
titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.
- class toyplot.locator.Log(base=10, format='{base}<sup> {exponent}</sup>')[source]¶
Bases:
TickLocator
Generate ticks that are evenly spaced on a logarithmic scale
- Parameters
base (number, optional) – Logarithm base.
format (string, optional) – Python format string, see Format String Syntax for the syntax. The format string will be called with a single positional argument containing the locator value, and two keyword arguments base and exponent. If omitted, the locator will generate high-quality labels using superscript notation.
Examples
Generate locator labels using fixed decimal point notation and two significant digits:
>>> locator = toyplot.locator.Log(format="{:.2g}")
Generate locator labels using scientific notation and three significant digits:
>>> locator = toyplot.locator.Log(format="{:.3e}")
Generate locator labels using mixed scientific and decimal notation and four significant digits:
>>> locator = toyplot.locator.Log(format="{:.4g}")
Generate locator labels using “carat” notation:
>>> locator = toyplot.locator.Log(format="{base}^{exponent}")
- ticks(domain_min, domain_max)[source]¶
Return a set of ticks for the given domain.
- Parameters
domain_min (number) –
domain_max (number) –
- Returns
locations (sequence of numbers) – Axis locations where ticks should be displayed.
labels (sequence of strings) – Labels for each tick location.
titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.
- class toyplot.locator.Null[source]¶
Bases:
TickLocator
Do-nothing tick locator that generates no ticks.
Use
toyplot.locator.Null
when you want to display an axis, but omit any ticks.- ticks(domain_min, domain_max)[source]¶
Return a set of ticks for the given domain.
- Parameters
domain_min (number) –
domain_max (number) –
- Returns
locations (sequence of numbers) – Axis locations where ticks should be displayed.
labels (sequence of strings) – Labels for each tick location.
titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.
- class toyplot.locator.TickLocator[source]¶
Bases:
object
Base class for tick locators - objects that compute the position and format of axis tick labels.
- ticks(domain_min, domain_max)[source]¶
Return a set of ticks for the given domain.
- Parameters
domain_min (number) –
domain_max (number) –
- Returns
locations (sequence of numbers) – Axis locations where ticks should be displayed.
labels (sequence of strings) – Labels for each tick location.
titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.
- class toyplot.locator.Timestamp(count=None, interval=None, timezone='utc', format=None)[source]¶
Bases:
TickLocator
Generate ticks when the domain is UTC timestamps relative to the Unix epoch.
Callers may explicitly specify the desired time interval as a string:
>>> toyplot.locator.Timestamp(interval="hours")
or as a tuple containing a quantity of units:
>>> toyplot.locator.Timestamp(interval=(3, "days"))
Instead of specifying an interval, the caller may supply the desired number of ticks, and the interval that produces the closest number of ticks will be used (note that the number of ticks produced may not match exactly):
>>> toyplot.locator.Timestamp(count=4)
If the count is not specified, it defaults to 7.
- Parameters
count (number, optional) – Specifies the desired number of ticks.
interval (string or (integer, string) tuple, optional) – Specifies the desired tick interval in anthropomorphic time units. Allowed units are “millenium”, “millenia”, “century”, “centuries”, “decade”, “decades”, “year”, “years”, “quarter”, “quarters”, “month”, “months”, “week”, “weeks”, “day”, “days”, “hour”, “hours”, “minute”, “minutes”, “second”, and “seconds”.
timezone (string, optional) – Specifies a local timezone to be used for label generation. Defaults to “utc”. Supports any timezone code allowed by
arrow.arrow.Arrow
.format (string, optional) – Format string used to generate labels from tick locations. The formatted value will be a
arrow.arrow.Arrow
object, so any of the attributes and formatting provided by https://arrow.readthedocs.org may be used in the format. For example, to display the full day of the week, month, day of the month without zero padding, and year, you could use:toyplot.locator.Timestamp(format="{0 (>>>) –
- ticks(domain_min, domain_max)[source]¶
Return a set of ticks for the given domain.
- Parameters
domain_min (number) –
domain_max (number) –
- Returns
locations (sequence of numbers) – Axis locations where ticks should be displayed.
labels (sequence of strings) – Labels for each tick location.
titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.
- class toyplot.locator.Uniform(count=5, format='{:g}')[source]¶
Bases:
TickLocator
Generate \(N\) evenly spaced ticks that include the minimum and maximum values of a domain.
- Parameters
count (number, optional) – Number of ticks to generate.
format (string, optional) – Format string used to generate labels from tick locations.
- ticks(domain_min, domain_max)[source]¶
Return a set of ticks for the given domain.
- Parameters
domain_min (number) –
domain_max (number) –
- Returns
locations (sequence of numbers) – Axis locations where ticks should be displayed.
labels (sequence of strings) – Labels for each tick location.
titles (sequence of strings) – Titles for each tick location. Typically, backends render titles as tooltips.