View Source GGity.Labels (GGity v0.5.0)

Common functions for transforming axis tick labels.

Break (i.e. axis tick or legend item) labels are formatted based on a scale's :labels option. This option can be provided in several forms:

  • nil - No labels are drawn
  • :waivers - drawn using the default formatting (Kernel.to_string/1)
  • a function that takes a single argument representing the break value and returns a binary
  • an atom, representing the name of a built-in formatting function (e.g., commas/1)

Note that the built-in formatting functions are not intended to be robust. One option for finely-tuned formatting would be to pass functions from the Cldr family of packages (must be added as a separate dependency).

examples

Examples

data
|> Plot.new(%{x: "x", y: "y"})
|> Plot.geom_point()
|> Plot.scale_x_continuous(labels: nil)
# value 1000 is printed as an empty string
data
|> Plot.new(%{x: "x", y: "y"})
|> Plot.geom_point()
|> Plot.scale_x_continuous() # This is equivalent to Plot.scale_x_continuous(labels: :waivers)
# value 1000 (integer) is printed as "1000"
# value 1000.0 (float) is printed as "1.0e3"
data
|> Plot.new(%{x: "x", y: "y", c: "color"})
|> Plot.geom_point()
|> Plot.scale_color_viridis(labels: fn value -> value  <> "!" end)
# value "First Item" is printed as "First Item!"
data
|> Plot.new(%{x: "x", y: "y"})
|> Plot.geom_point()
|> Plot.scale_x_continuous(labels: :commas)
# value 1000 (integer) is printed as "1,000"
# value 1000 (float) is printed as "1,000"

Date scales (e.g., GGity.Scale.X.Date) are a special case. For those scales, if a value for :date_labels has been specified, that pattern overrides any value for the :labels option. See GGity.Plot.scale_x_date/2 for more information regarding date labels.

Link to this section Summary

Functions

Applies a comma separator to a number and converts it to a string.

Formats a number in U.S. dollars and cents.

Formats a number as a percent.

Link to this section Types

@type tick_value() ::
  %Date{calendar: term(), day: term(), month: term(), year: term()}
  | %DateTime{
      calendar: term(),
      day: term(),
      hour: term(),
      microsecond: term(),
      minute: term(),
      month: term(),
      second: term(),
      std_offset: term(),
      time_zone: term(),
      utc_offset: term(),
      year: term(),
      zone_abbr: term()
    }
  | number()

Link to this section Functions

@spec commas(number()) :: String.t()

Applies a comma separator to a number and converts it to a string.

If the number is a float, it is first rounded using Kernel.to_string/1.

Note that simple floating point arithmetic is used; the various issues/errors associated with floating point values apply.

iex> GGity.Labels.commas(5000.0)
"5,000"

iex> GGity.Labels.commas(1000.6)
"1,001"

iex> GGity.Labels.commas(100.0)
"100"

iex> GGity.Labels.commas(10_000_000)
"10,000,000"
@spec dollar(number()) :: String.t()

Formats a number in U.S. dollars and cents.

If the value is greater than or equal to 100,000 rounds to the nearest dollar and does not display cents.

Note that simple floating point arithmetic is used; the various issues/errors associated with floating point values apply.

iex> GGity.Labels.dollar(5000.0)
"$5,000.00"

iex> GGity.Labels.dollar(1000.6)
"$1,000.60"

iex> GGity.Labels.dollar(100.0)
"$100.00"

iex> GGity.Labels.dollar(10_000_000)
"$10,000,000"
Link to this function

percent(value, options \\ [precision: 0])

View Source
@spec percent(
  number(),
  keyword()
) :: String.t()

Formats a number as a percent.

Accepts a :precision option specifying the number of decimal places to be displayed.

Note that simple floating point arithmetic is used; the various issues/errors associated with floating point values apply.

iex> GGity.Labels.percent(0.5)
"50%"

iex> GGity.Labels.percent(0.111)
"11%"

iex> GGity.Labels.percent(0.015, precision: 1)
"1.5%"

iex> GGity.Labels.percent(10)
"1000%"