Skip to content

Commit

Permalink
Substitution example: removed hedging, added links
Browse files Browse the repository at this point in the history
I revised the text after realizing that there actually are keys `:field`
and (in Vega-Lite) `"field"`.  I thought `:field` might just be a dummy
variable for the sake of an example.

I also added links to Hanami source and a Vega-Lite doc page.  Maybe
it's inappropriate to include these links in a section that's intended
to give an overview.  However, part of what's confusing is all of the
layers involved (:X is value of :field, but it's a key to look up "x",
which will be a default value for "field").  One doesn't have to follow
the links, but maybe having the exact references available will help
some readers to sort out the layers.

Fixed typos created when fixing typos
  • Loading branch information
Marshall Abrams committed Jan 3, 2022
1 parent 6dcb0c5 commit c0b4e4a
Showing 1 changed file with 1 addition and 1 deletion.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -299,7 +299,7 @@ _Substitution Keys_ can be considered or thought of in two ways. They are the ke

The second way of thinking about substitution keys is that they are the starting values of keys in templates. So, they represent parameterized values of keys in templates.

As an example consider the following. In a template (which is a Clojure map) we might have a key `:field` with value `:X`. Here `:field` could correspond to a Vega-Lite field name, in this case "field". When we apply `hc/xform` to the template, `:field`'s value `:X` will be replaced by a new value, which comes from the current substitution map. In the default substitution map `hc/_defaults`, the key `:X` has the value of "x", so the resulting key/value pair will be `:field "x"`.
As an example consider the following. In a template (which is a Clojure map) we might have a key `:field` with value `:X` (cf. [xy-encoding template](https://github.com/jsa-aerial/hanami/blob/0dd9ac62e89ec5a5d0285cd0c0da5e2bc87b2ad0/src/cljc/aerial/hanami/templates.cljc#L84)). Here `:field` corresponds to a Vega-Lite key, ["field"](https://vega.github.io/vega-lite/docs/field.html). When we apply `hc/xform` to the template, `:field`'s value `:X` will be replaced by a new value, which comes from the current substitution map. In the default substitution map [`hc/_defaults`](https://github.com/jsa-aerial/hanami/blob/9cfa38118486fa0e139defeaa20ac3595690c8f9/src/cljc/aerial/hanami/common.cljc#L161), the key `:X` has the value of `"x"`, so the resulting key/value pair will be `:field "x"`.

A more complex example would be the field and value `:encoding :ENCODING` in the predefined subcomponent `ht/view-base` which lays out the structure of a Vega-Lite _view_. As before `:ENCODING` will be replaced during transformation by the value of `:ENCODING` in the substitution map. However, the default value of `:ENCODING` is the predefined subcomponent `ht/xy-encoding`. This value is a map describing the structure of a view's `x-y` encodings and contains many fields with their own substitution keys. So, to produce a final value, `ht/xy-encoding` is recursively transformed so that the final value of `:encoding` is a fully realized `x-y` encoding for the view being processed. `ht/view-base` has several other such fields and is itself recursively transformed in the context of the current substitution map. And its final value will be the base of a chart, such as a line chart (`ht/line-chart`) or area chart (`ht/area-chart`), or some new plot/chart/layout/etc of your own for some domain specific application.

Expand Down

0 comments on commit c0b4e4a

Please sign in to comment.