# `Giggly.Scale.Binned`
[🔗](https://github.com/giggleton/giggly/blob/v0.1.0/lib/giggly/scale/binned.ex#L1)

A binned scale: a colour or fill scale that cuts its continuous values into bins at its breaks
and gives every value in a bin the same colour. Its fields:

  * `range`: the range of the finite numbers it has seen, or `:none` before it has seen any.
  * `palette`: what gives each bin its colour: `{:binned, palette}`, a discrete palette of
    `Scales.Palette`'s, such as `{:binned, {:brewer, %{palette: "Blues", direction: -1}}}`, its
    colours for as many levels as there are bins, the first for the lowest; or a continuous
    palette, such as `{:gradient, colors}`, or any other of `Scales.Palette`'s, the colour at the
    middle of each bin's place in the limits.
  * `rescaler`: how a value's place in the limits is found: `:rescale`, its distance from the
    low end over the limits' width; or `{:mid, midpoint}`, its distance from the midpoint over
    twice the further end's, so the midpoint is at the middle and the further end at 0 or 1.
  * `na_value`: what a missing value, one not a finite number, or one `oob` leaves outside
    the limits maps to: grey, `"#7F7F7F"`,
    or `:none`, no colour.
  * `guide`: the guide that draws it: `:colorsteps`, a bar of one block of colour for each
    bin; `:legend`, a key for each break; or `:none` for none.
  * `name`: its guide's title, `:none` for none, or `:default` for the title its mapping
    gives.
  * `limits`: `{low, high}`, the values it spans whatever the data, `nil` at an end the data
    decides. A value outside them is handled as `oob` says. With neither
    end given and its breaks the default, the limits are the data's range widened so the end
    bins are as wide as their neighbours: from the lowest break inside the range less the step
    to the next, to the highest plus the step from the one before; with one break inside, so
    it is the middle, from it less its distance to the further end of the range to it plus the
    same; with none inside, not widened, its ends its breaks, and a range of one value widened
    by 0.05 either side first.
  * `oob`: what happens to a value outside the limits before it is binned, as a continuous
    scale's `oob` says: `:squish`, a finite number moved onto the nearer limit, so it takes
    the colour of the bin at that end; any other of `Giggly.Scale.Continuous`'s; a value still
    outside, or missing, maps to `na_value`.
  * `breaks`: the values its bins are cut at, beside the limits: a list, those inside the
    limits kept, in the order given; a function handed the limits, `{low, high}`, and for one of
    two arguments `[n: n_breaks]` too, that returns them, or `{value, label}` pairs, a pair's
    label the break's unless `labels` says otherwise, kept as a list's are, the limits not
    widened; `:none` for one bin; or `:default` for about `n_breaks`,
    chosen as `nice_breaks` says on the limits, those at either end of the data's range left
    out where the limits are widened.
  * `n_breaks`: how many default breaks are wanted, or a breaks function of two arguments is
    asked for, 5 unless given; nice breaks may number a few more or fewer.
  * `nice_breaks`: `true` for default breaks chosen to be round numbers, as a continuous
    scale's are, `n_breaks` of them wanted, 2 or more; `false` for `n_breaks` breaks spaced
    evenly between the ends of the limits, 1 or more.
  * `labels`: a label for each break: a list, one for each of its given breaks, or of its
    default ones, a break left out taking its label with it, `nil` for a missing one; a
    function handed every break kept, that returns their labels, each a string, a power
    (`Scales.Labels.log/2`) or `nil`; `:none` for none; or `:default`, each written as a
    continuous scale writes a number.
  * `right`: where a value on a break falls: `true` in the bin below it, `false` in the bin
    above; the lowest value is in the lowest bin, and the highest in the highest.
  * `show_limits`: `true` to have colour steps label the ends of the bar with the limits,
    written by its `labels` as its breaks are, unless a break is already there; `false` for
    the breaks alone. A legend shows the breaks alone either way.

# `t`

```elixir
@type t() :: %Giggly.Scale.Binned{
  breaks:
    :default
    | :none
    | [number()]
    | ({float(), float()} -> list())
    | ({float(), float()}, keyword() -> list()),
  guide: :colorsteps | :legend | :none,
  labels:
    :default
    | :none
    | [String.t() | nil]
    | ([float()] -> [Scales.Labels.power_label()]),
  limits: {number() | nil, number() | nil},
  n_breaks: pos_integer(),
  na_value: String.t() | :none,
  name: :default | :none | String.t(),
  nice_breaks: boolean(),
  oob: Giggly.Scale.Continuous.oob(),
  palette: {:binned, Scales.Palette.t()} | Scales.Palette.t(),
  range: :none | {number(), number()},
  rescaler: :rescale | {:mid, number()},
  right: boolean(),
  show_limits: boolean()
}
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*