# 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]

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, domain_max (number) 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]

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, domain_max (number) 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]

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, domain_max (number) 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]

Generate evenly-spaced integer ticks

Parameters: step (integer, optional) – Number of integer values to skip between labels.
ticks(domain_min, domain_max)[source]

Return a set of ticks for the given domain.

Parameters: domain_min, domain_max (number) 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]

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, domain_max (number) 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]

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, domain_max (number) 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, domain_max (number) 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]

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 (dddd}, {0:MMMM} {0:D}, {0:YYYY}”))
ticks(domain_min, domain_max)[source]

Return a set of ticks for the given domain.

Parameters: domain_min, domain_max (number) 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]

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, domain_max (number) 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.