# `Giggly.Datasets`
[🔗](https://github.com/giggleton/giggly/blob/v0.1.0/lib/giggly/datasets.ex#L1)

Datasets to plot, for the examples in Giggly's notebooks and for your own: copies of tables R
and ggplot2 ship.

Each dataset is a keyword list of columns, in the dataset's own order, which `Giggly.Plot.new/2`
reads as a table, as do Explorer's `DataFrame.new/1` and Kino's data table. A column of numbers
holds integers or floats, as each dataset's doc shows; a name is a string, a date a `Date`, and
a value the data lacks `nil`.
Each is kept in Giggly's `priv/datasets` with a header saying where it came from, and read when
Giggly compiles, so asking for one reads nothing.

# `diamonds`

```elixir
@spec diamonds() :: [{atom(), [number()] | Giggly.Factor.t()}]
```

ggplot2's `diamonds`: the prices and other attributes of 53,940 round cut diamonds.

The columns: `carat`, the weight; `cut`, the quality of the cut, from `"Fair"`, `"Good"`,
`"Very Good"` and `"Premium"` to `"Ideal"`; `color`, from `"D"`, the best, to `"J"`, the worst;
`clarity`, how clear, from `"I1"`, the worst, through `"SI2"`, `"SI1"`, `"VS2"`, `"VS1"`,
`"VVS2"` and `"VVS1"` to `"IF"`, the best; `depth`, the total depth as a percentage of the
mean width, `2 * z / (x + y)`; `table`, the width of the top relative to the widest point;
`price`, in US dollars; and `x`, `y` and `z`, the length, width and depth in millimetres.
`cut`, `color` and `clarity` are `Giggly.Factor`s with those levels, in that order, and
ordered, as R's are, so a plot orders them as given here, not alphabetically; each enumerates
as its values. It is kept compressed and decoded each time it is asked for, in a few tens of
milliseconds, so bind it once.

    iex> diamonds = Giggly.Datasets.diamonds()
    iex> Keyword.keys(diamonds)
    [:carat, :cut, :color, :clarity, :depth, :table, :price, :x, :y, :z]
    iex> diamonds |> Keyword.fetch!(:price) |> length()
    53940
    iex> Enum.map(diamonds, fn {name, values} -> {name, Enum.at(values, 2)} end)
    [
      carat: 0.23,
      cut: "Good",
      color: "E",
      clarity: "VS1",
      depth: 56.9,
      table: 65.0,
      price: 327,
      x: 4.05,
      y: 4.07,
      z: 2.31
    ]

# `economics`

```elixir
@spec economics() :: [{atom(), [Date.t() | number()]}]
```

ggplot2's `economics`: US economic time series, one row a month from July 1967 to April 2015,
574 in all, from the Federal Reserve Bank of St. Louis's
[FRED](https://fred.stlouisfed.org/) database.

The columns: `date`, the month, as a `Date` on its first day; `pce`, personal consumption
expenditures, in billions of dollars; `pop`, the total population, in thousands; `psavert`, the
personal savings rate; `uempmed`, the median duration of unemployment, in weeks; and `unemploy`,
the number unemployed, in thousands. Every number is a float.

    iex> economics = Giggly.Datasets.economics()
    iex> Keyword.keys(economics)
    [:date, :pce, :pop, :psavert, :uempmed, :unemploy]
    iex> economics |> Keyword.fetch!(:date) |> length()
    574
    iex> Enum.map(economics, fn {name, values} -> {name, Enum.at(values, 0)} end)
    [
      date: ~D[1967-07-01],
      pce: 506.7,
      pop: 198712.0,
      psavert: 12.6,
      uempmed: 4.5,
      unemploy: 2944.0
    ]

# `economics_long`

```elixir
@spec economics_long() :: [{atom(), [Date.t() | String.t() | number()]}]
```

ggplot2's `economics_long`: `economics/0` in long form, a row for each month and series, 2,870
in all, so the five series can be drawn as lines of one plot.

The columns: `date`, the month, as a `Date` on its first day; `variable`, the series, `"pce"`,
`"pop"`, `"psavert"`, `"uempmed"` or `"unemploy"`, as `economics/0` names its columns; `value`,
the series' value that month, in its own units; and `value01`, the value rescaled within its
series, from 0, its lowest, to 1, its highest, so series of different units share an axis.
Every number is a float.

    iex> economics_long = Giggly.Datasets.economics_long()
    iex> Keyword.keys(economics_long)
    [:date, :variable, :value, :value01]
    iex> economics_long |> Keyword.fetch!(:date) |> length()
    2870
    iex> Enum.map(economics_long, fn {name, values} -> {name, Enum.at(values, 1)} end)
    [
      date: ~D[1967-08-01],
      variable: "pce",
      value: 509.8,
      value01: 0.0002652497197765077
    ]

# `faithfuld`

```elixir
@spec faithfuld() :: [{atom(), [float()]}]
```

ggplot2's `faithfuld`: a two-dimensional density estimate of the eruption and waiting times in
R's `faithful` data on the Old Faithful geyser, at each point of a 75 by 75 grid, 5,625 rows in
all, for drawing a surface.

The columns: `eruptions`, the eruption time in minutes; `waiting`, the waiting time to the next
eruption in minutes; and `density`, the estimated density there. Every number is a float.

    iex> faithfuld = Giggly.Datasets.faithfuld()
    iex> Keyword.keys(faithfuld)
    [:eruptions, :waiting, :density]
    iex> faithfuld |> Keyword.fetch!(:density) |> length()
    5625
    iex> Enum.map(faithfuld, fn {name, values} -> {name, Enum.at(values, 2)} end)
    [eruptions: 1.6945945945945946, waiting: 43.0, density: 0.0044355477659065081]

# `mpg`

```elixir
@spec mpg() :: [{atom(), [String.t() | number()]}]
```

ggplot2's `mpg`: fuel economy from 1999 to 2008 for 38 popular models of car, 234 cars in all, a
subset of the data the US Environmental Protection Agency publishes at
[fueleconomy.gov](https://fueleconomy.gov/), keeping only models with a new release every year
from 1999 to 2008.

The columns: `manufacturer`; `model`; `displ`, engine displacement in litres; `year`, of
manufacture; `cyl`, cylinders; `trans`, the transmission; `drv`, the drive, `"f"` front-wheel,
`"r"` rear-wheel and `"4"` four-wheel; `cty`, city miles per gallon; `hwy`, highway miles per
gallon; `fl`, the fuel type; `class`, the type of car.

    iex> mpg = Giggly.Datasets.mpg()
    iex> Keyword.keys(mpg)
    [:manufacturer, :model, :displ, :year, :cyl, :trans, :drv, :cty, :hwy, :fl, :class]
    iex> mpg |> Keyword.fetch!(:model) |> length()
    234
    iex> Enum.map(mpg, fn {name, values} -> {name, Enum.at(values, 2)} end)
    [
      manufacturer: "audi",
      model: "a4",
      displ: 2.0,
      year: 2008,
      cyl: 4,
      trans: "manual(m6)",
      drv: "f",
      cty: 20,
      hwy: 31,
      fl: "p",
      class: "compact"
    ]

# `msleep`

```elixir
@spec msleep() :: [{atom(), [String.t() | number() | nil]}]
```

ggplot2's `msleep`: the sleep of 83 mammals, an updated and expanded version of the mammals
sleep dataset. The sleep times and weights are from Savage and West (2007); the order,
conservation status and diet were added from Wikipedia.

The columns: `name`, the animal's common name; `genus`; `vore`, its diet, `"carni"`,
`"herbi"`, `"insecti"` or `"omni"`; `order`; `conservation`, its conservation status, such as
`"lc"`, least concern, or `"domesticated"`; `sleep_total`, its total sleep in hours;
`sleep_rem`, its REM sleep in hours; `sleep_cycle`, the length of its sleep cycle in hours;
`awake`, its time awake in hours; and `brainwt` and `bodywt`, its brain and body weight in
kilograms. Every number is a float, and a value the data lacks is `nil`, as R's is `NA`.

    iex> msleep = Giggly.Datasets.msleep()
    iex> Keyword.keys(msleep)
    [:name, :genus, :vore, :order, :conservation, :sleep_total, :sleep_rem, :sleep_cycle,
     :awake, :brainwt, :bodywt]
    iex> msleep |> Keyword.fetch!(:name) |> length()
    83
    iex> Enum.map(msleep, fn {name, values} -> {name, Enum.at(values, 1)} end)
    [
      name: "Owl monkey",
      genus: "Aotus",
      vore: "omni",
      order: "Primates",
      conservation: nil,
      sleep_total: 17.0,
      sleep_rem: 1.8,
      sleep_cycle: nil,
      awake: 7.0,
      brainwt: 0.0155,
      bodywt: 0.48
    ]

# `mtcars`

```elixir
@spec mtcars() :: [{atom(), [String.t() | number()]}]
```

R's `mtcars`: fuel consumption and ten aspects of design and performance for 32 cars (1973-74
models), from the 1974 *Motor Trend* US magazine (Henderson and Velleman, 1981). Every number
is a float.

The columns: `model`; `mpg`, miles per US gallon; `cyl`, cylinders; `disp`, displacement in
cubic inches; `hp`, gross horsepower; `drat`, rear axle ratio; `wt`, weight in thousands of
pounds; `qsec`, quarter-mile time in seconds; `vs`, the engine, 0 V-shaped and 1 straight; `am`,
the transmission, 0 automatic and 1 manual; `gear`, forward gears; `carb`, carburettors.

    iex> mtcars = Giggly.Datasets.mtcars()
    iex> Keyword.keys(mtcars)
    [:model, :mpg, :cyl, :disp, :hp, :drat, :wt, :qsec, :vs, :am, :gear, :carb]
    iex> mtcars |> Keyword.fetch!(:model) |> length()
    32
    iex> Enum.map(mtcars, fn {name, values} -> {name, Enum.at(values, 2)} end)
    [
      model: "Datsun 710",
      mpg: 22.8,
      cyl: 4.0,
      disp: 108.0,
      hp: 93.0,
      drat: 3.85,
      wt: 2.32,
      qsec: 18.61,
      vs: 1.0,
      am: 1.0,
      gear: 4.0,
      carb: 1.0
    ]

# `txhousing`

```elixir
@spec txhousing() :: [{atom(), [String.t() | number() | nil]}]
```

ggplot2's `txhousing`: housing sales in Texas, a row for each month from January 2000 to July
2015 and each of 46 multiple listing service areas, 8,602 in all, from the TAMU real estate
center, [trerc.tamu.edu](https://trerc.tamu.edu/).

The columns: `city`, the area's name; `year` and `month`, of the sales, integers; `sales`, the
number of sales; `volume`, their total value, in dollars; `median`, the median sale price, in
dollars; `listings`, the total active listings; `inventory`, the months it would take to sell
every listing at the current pace of sales; and `date`, the year and month as a decimal, `year +
(month - 1) / 12`. Every number but the year and month is a float, and a value the data lacks
is `nil`, as R's is `NA`. It is kept compressed and decoded each time it is asked for, in a few
milliseconds, so bind it once.

    iex> txhousing = Giggly.Datasets.txhousing()
    iex> Keyword.keys(txhousing)
    [:city, :year, :month, :sales, :volume, :median, :listings, :inventory, :date]
    iex> txhousing |> Keyword.fetch!(:city) |> length()
    8602
    iex> Enum.map(txhousing, fn {name, values} -> {name, Enum.at(values, 2)} end)
    [
      city: "Abilene",
      year: 2000,
      month: 3,
      sales: 130.0,
      volume: 9285000.0,
      median: 58100.0,
      listings: 784.0,
      inventory: 6.8,
      date: 2000.1666666666667
    ]

---

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