Dataset is a simple wrapper around a datasource for plotting charts.

Dataset marshalls a couple of different data structures into a consistent form for consumption by the chart plotting functions. It allows a list of maps, list of lists or a list of tuples to be treated the same.

The most sensible way to work with a dataset is to provide column headers - it makes code elsewhere readable. When the provided data is a list of maps, headers are inferred from the map keys. If you don't want to, you can also refer to columns by index.

Dataset provides a few convenience functions for calculating data extents for a column, extracting unique values from columns, calculating combined extents for multiple columns (handy when plotting bar charts) and guessing column type (handy when determining whether to use a Contex.TimeScale or a Contex.ContinuousLinearScale).

Datasets can be created from a list of maps:

iex> data = [
...>        %{x: 0.0, y: 0.0, category: "Hippo"},
...>        %{x: 0.2, y: 0.3, category: "Rabbit"}
...>        ] # Wherever your data comes from (e.g. could be straight from Ecto)
...> dataset = Dataset.new(data)
%Contex.Dataset{
  data: [
    %{category: "Hippo", x: 0.0, y: 0.0},
    %{category: "Rabbit", x: 0.2, y: 0.3}
  ],
  headers: nil,
  title: nil
}
iex> Dataset.column_names(dataset)
[:category, :x, :y] # Note ordering of column names from map data is not guaranteed

or from a list of tuples (or lists):

iex> data = [
...>        {0.0, 0.0, "Hippo"},
...>        {0.5, 0.3, "Turtle"},
...>        {0.4, 0.3, "Turtle"},
...>        {0.2, 0.3, "Rabbit"}
...>        ]
...> dataset = Dataset.new(data, ["x", "y", "category"]) # Attach descriptive headers
iex> Dataset.column_names(dataset)
["x", "y", "category"]
...> Dataset.column_extents(dataset, "x") # Get extents for a named column
{0.0, 0.5}
iex> Dataset.column_index(dataset, "x") # Get index of column by name
0
iex> category_col = Dataset.column_name(dataset, 2) # Get name of column by index
"category"
iex> Enum.map(dataset.data, fn row -> # Enumerate values in a column
...>    accessor = Dataset.value_fn(dataset, category_col)
...>    accessor.(row)
...> end)
["Hippo", "Turtle", "Turtle", "Rabbit"]
iex> Dataset.unique_values(dataset, "category") # Extract unique values for legends etc.
["Hippo", "Turtle", "Rabbit"]

Dataset gives facilities to map between names and column indexes. Where headers are not supplied (either directly or via map keys), the column index is treated as the column name internally. Data values are retrieved by column name using accessor functions, in order to avoid expensive mappings in tight loops.

Note There are very few validation checks when a dataset is created (for example, to checks that number of headers supplied matches) the size of each array or tuple in the data. If there are any issues finding a value, nil is returned.