ContEx
ContEx v0.5.0

View Source Contex.Mapping (ContEx v0.5.0)

Mappings generalize the process of associating columns in the dataset to the elements of a plot. As part of creating a mapping, these associations are validated to confirm that a column has been assigned to each of the graphical elements that are necessary to draw the plot, and that all of the assigned columns exist in the dataset.

The Mapping struct stores accessor functions for the assigned columns, which are used to retrieve values for those columns from the dataset to support drawing the plot. The accessor functions have the same name as the associated plot element; this allows plot-drawing functions to access data based that plot's required elements without knowing anything about the dataset.

Link to this section Summary

Types

t()

Functions

new(expected_mappings, provided_mappings, dataset)

Given expected mappings for a plot and a map associating plot elements with dataset columns, creates a Mapping struct for the plot that stores accessor functions for each element and returns a mapping. Raises if the map does not include all required elements of the specified plot type or if the dataset columns are not present in the dataset.

update(mapping, updated_mappings)

Given a plot that already has a mapping and a new map of elements to columns, updates the mapping accordingly and returns the plot.

Link to this section Types

Link to this type

t()

View Source 
@type t() :: %Contex.Mapping{
  accessors: term(),
  column_map: term(),
  dataset: term(),
  expected_mappings: term()
}

Link to this section Functions

Link to this function

new(expected_mappings, provided_mappings, dataset)

View Source 
@spec new(keyword(), map(), Contex.Dataset.t()) :: t()

Given expected mappings for a plot and a map associating plot elements with dataset columns, creates a Mapping struct for the plot that stores accessor functions for each element and returns a mapping. Raises if the map does not include all required elements of the specified plot type or if the dataset columns are not present in the dataset.

Expected mappings are passed as a keyword list where each plot element is one of the following:

  • :exactly_one - indicates that the plot needs exactly one of these elements, for example a column representing categories in a barchart.
  • :one_more_more - indicates that the plot needs at least one of these elements, for example y columns in a point plot
  • :zero_or_one - indicates that the plot will use one of these elements if it is available, for example a fill colour column in a point plot
  • :zero_or_more - indicates that plot will use one or more of these elements if it is available

For example, the expected mappings for a barchart are represented as follows: [category_col: :exactly_one, value_cols: :one_or_more]

and for a point point: [ x_col: :exactly_one, y_cols: :one_or_more, fill_col: :zero_or_one]

Provided mappings are passed as a map with the map key matching the expected mapping and the map value representing the columns in the underlying dataset. So for a barchart the column mappings may be: %{category_col: "Quarter", value_cols: ["Australian Sales", "Kiwi Sales", "South African Sales"]}

If columns are not specified for optional plot elements, an accessor function that returns nil is created for those elements.

Link to this function

update(mapping, updated_mappings)

View Source 
@spec update(t(), map()) :: t()

Given a plot that already has a mapping and a new map of elements to columns, updates the mapping accordingly and returns the plot.