feat!: merge axis channels (e.g., `x` and `xe`); group channels as an `encoding` property #575

sehilyi · 2021-11-01T21:06:44Z

Summary of Changes

In addition to #533, this PR changes grammar around visual channels.

This PR contains a relatively large amount of changes, but many parts are changes on the examples (src/example/*.ts) and tests (*.test.ts) reflecting the grammatical changes that have been introduced in this PR. This PR introduces the following major grammatical changes.

C1. Axis channels are combined

from:

x: { field: 'start', type: 'genomic', axis: 'top', linkingId: 'overview' },
xe: { field: 'end', type: 'genomic', axis: 'top' }

to:

x: { startField: 'start', endField: 'end', type: 'genomic', axis: 'top', linkingId: 'overview' }

This way, axis channels convey a more clear meaning:

multiple axes do not exist for the x-axis (i.e., x and xe) or the y-axis (i.e., y and ye).
Instead, multiple fields can be used for a single axis (i.e., startField and endField in an x channel).

More importantly, this prevents users from making uncertain specs, such as

using different types for the single axis (e.g., nominal field for y and then quantitative field for ye)
defining properties multiple times for a single axis that should be defined only once (e.g., axis: 'top' or linkingId: 'overview'):

x: { field: 'start', type: 'genomic', axis: 'top', linkingId: 'overview' },
xe: { field: 'end', type: 'genomic', axis: 'bottom', linkingId: 'ab' }

C2. The `encoding` property is added

Track now has a encoding property that wraps all channels:

tracks: [{
   mark: 'line',
   encoding: {
      x: { startField: 'start', endField: 'end', type: 'genomic', axis: 'top', linkingId: 'overview' },
      color: { value: 'black' }
   },
   width: 100,
   height: 30
}]

This is consistent with the Vega-Lite and is beneficial in gos (gosling-lang/gos#34 (comment)).

C3. `TemplateTrack` modified accordingly

As we made a grammatical change to channels (i.e., x and xe --> x: { startField: ...., endField: ..., ...}), the template mapper logic was changed as well:

// part of a TemplateTrackDef spec
x: { base: { startField: 'startPosition', endField: 'endPosition', ... }

C4. `DataTrack` is removed entirely

We did not support DataTrack anymore, but it was still included in our code. I removed all related codes. We could support a similar feature with Track Templates in Gosling in the future:

{ template: 'vector-track', data: { ... }, width: 1000, height: 30}

To Test Locally

Run the following command to update your local gosling.schema.json since this PR updates the grammar.

yarn schema

BREAKING CHANGE

This PR introduces breaking changes. To change your existing specification for previous versions (~v0.9.9), you need to change your spec following the instructions described below.

If you are using multiple fields for a single axis in your spec:

x: { field: 'start', type: 'genomic', axis: 'top', linkingId: 'overview' },
xe: { field: 'end', type: 'genomic', axis: 'top' }

You need to combine them to a single axis using up to four fields (i.e., startField, endField, startField2, endField2):

x: { startField: 'start', endField: 'end', type: 'genomic', axis: 'top', linkingId: 'overview' }

Single-field axes are not changed (i.e., field properties are used):

x: { field: 'position', type: 'genomic', axis: 'top', linkingId: 'overview' }

Add an encoding property to all tracks.

From:

tracks: [{
   data: ...,
   mark: ...,
   x: ...,
   y: ...,
   ...
}]

To:

tracks: [{
   data: ...,
   mark: ...,
   encoding: {
      x: ...,
      y: ...,
      ...
   },
   ...
}]

TODO

Update all example specs that use multiple fields for a single axis
Update encoding parts of all marks
Update all tests
Rename '|xe - x|' threshold to 'assignedWidth'?

sehilyi · 2021-11-03T19:49:04Z

src/index.ts

@@ -2,7 +2,7 @@ export { name, version } from '../package.json';
 import GoslingSchema from '../schema/gosling.schema.json';
 import ThemeSchema from '../schema/theme.schema.json';

-export type { GoslingSpec, TemplateTrackDef } from './core/gosling.schema';
+export type { GoslingSpec, Encoding, TemplateTrackDef } from './core/gosling.schema';


Would need to ensure to have Encoding in the schema.json file.

Reference: #565 (comment)

src/core/gosling.schema.guards.ts

sehilyi · 2021-11-03T21:52:56Z

src/core/compile.ts

@@ -15,9 +15,6 @@ export function compile(
    // Make sure to keep the original spec as is
    const _spec = JSON.parse(JSON.stringify(spec));

-    // Override default visual encoding (i.e., `DataTrack` => `BasicSingleTrack`)
-    overrideDataTemplates(_spec);


Removed this since DataTrack had been deprecated.

src/core/compile.ts

sehilyi · 2021-11-16T19:14:39Z

src/core/gosling.schema.ts

@@ -459,9 +436,11 @@ export interface ChannelDeepCommon {
    field?: string;
 }

-export interface X extends ChannelDeepCommon {


Key changes can be found in this file.

sehilyi · 2021-11-16T19:55:50Z

@manzt, sorry that this update was delayed. It turns out to be more significant updates than I expected.

Can you review this PR? I would be interested in hearing from you whether the grammatical changes look okay and these updates work for you to continue working on gosling-lang/gos#71. Please review code bases as deeply as you would like to.

manzt · 2021-11-16T19:57:02Z

No problem! Won't be able to look today but probably tomorrow.

manzt · 2021-12-10T23:13:36Z

@sehilyi I completely lost track of this. Will review this weekend -- sorry! Do you have any thoughts regarding how to reserve these merge conflict?

sehilyi · 2021-12-11T01:22:53Z

@manzt No worries! I was basically thinking of manually resolving conflicts which I hope to be manageable.

Also, please let me know if all grammatical changes introduced in this PR make sense to you. Since this PR introduces breaking changes, I would like to merge this carefully.

sehilyi · 2022-07-05T19:36:30Z

@manzt Since this will introduce breaking changes and is too far behind the current version, I am reluctant to resolve conflicts and merge this.

I think we can revisit this (at least making an encoding property in a SingleTrack) later when we plan to make a major version bump.

manzt · 2022-07-05T20:28:27Z

Agreed!

manzt · 2022-07-06T13:05:16Z

@sehilyi I just wanted to apologize that your hard work here never got a thorough review. I think this PR had several different aims and touched many internals of Gosling that at the time I struggled to understand.

sehilyi · 2022-07-07T11:48:56Z

@manzt No worries. This was such a huge PR. And I am sure we can revisit this and repurpose it for future PRs.

chore: working on grouping and merging encoding

8e892f2

sehilyi mentioned this pull request Nov 1, 2021

feat!: merge axis channels (i.e., x: { startField, endField } instead of x: { ... }, xe: { ...}) #539

Closed

4 tasks

sehilyi changed the title ~~feat!: merging and grouping encodings~~ feat!: merging axis channels; explicit encoding property Nov 1, 2021

sehilyi changed the title ~~feat!: merging axis channels; explicit encoding property~~ feat!: merge axis channels; group channels as a encoding property Nov 3, 2021

sehilyi changed the title ~~feat!: merge axis channels; group channels as a encoding property~~ feat!: merge axis channels (e.g., x and xe); group channels as a encoding property Nov 3, 2021

sehilyi changed the title ~~feat!: merge axis channels (e.g., x and xe); group channels as a encoding property~~ feat!: merge axis channels (e.g., x and xe); group channels as an encoding property Nov 3, 2021

chore: update more examples; edit all marks

622b68d

sehilyi commented Nov 3, 2021

View reviewed changes

fix: arc example

4faed6e

sehilyi commented Nov 3, 2021

View reviewed changes

src/core/gosling.schema.guards.ts Show resolved Hide resolved

sehilyi added 3 commits November 3, 2021 16:40

fix: correctly calculate domain of stacked bars

fe23347

fix: merge scales when multiple fields are encoded to a single axis

1fd4ced

chore: more examples

94716ef

sehilyi commented Nov 3, 2021

View reviewed changes

chore: more examples

5a0b1dd

sehilyi commented Nov 4, 2021

View reviewed changes

src/core/compile.ts Show resolved Hide resolved

sehilyi added 4 commits November 4, 2021 11:18

chore: rest of examples

bef1d56

chore: fix all tests reflecting grammar change

119dd25

fix: all examples and test; support field-wise aggregation

7bf0d17

chore: fixing tests

ea9befe

manzt mentioned this pull request Nov 8, 2021

More concise (text-based) columnar data definitions #579

Closed

sehilyi added 3 commits November 16, 2021 11:03

fix: fix all example and issue regarding overlaying

dbc5c2a

feat: update templates accordingly

743e30c

fix: fix all tests

c9560a3

sehilyi commented Nov 16, 2021

View reviewed changes

manzt self-assigned this Dec 10, 2021

manzt mentioned this pull request Jul 5, 2022

feat: add shorthand syntax option for gos.Tooltip gosling-lang/gos#97

Merged

sehilyi closed this Jul 5, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat!: merge axis channels (e.g., `x` and `xe`); group channels as an `encoding` property #575

feat!: merge axis channels (e.g., `x` and `xe`); group channels as an `encoding` property #575

sehilyi commented Nov 1, 2021 •

edited

Loading

sehilyi Nov 3, 2021 •

edited

Loading

sehilyi Nov 3, 2021 •

edited

Loading

sehilyi Nov 16, 2021

sehilyi commented Nov 16, 2021

manzt commented Nov 16, 2021

manzt commented Dec 10, 2021 •

edited

Loading

sehilyi commented Dec 11, 2021 •

edited

Loading

sehilyi commented Jul 5, 2022

manzt commented Jul 5, 2022

manzt commented Jul 6, 2022

sehilyi commented Jul 7, 2022

feat!: merge axis channels (e.g., x and xe); group channels as an encoding property #575

feat!: merge axis channels (e.g., x and xe); group channels as an encoding property #575

Conversation

sehilyi commented Nov 1, 2021 • edited Loading

Summary of Changes

C1. Axis channels are combined

C2. The encoding property is added

C3. TemplateTrack modified accordingly

C4. DataTrack is removed entirely

To Test Locally

BREAKING CHANGE

sehilyi Nov 3, 2021 • edited Loading

Choose a reason for hiding this comment

sehilyi Nov 3, 2021 • edited Loading

Choose a reason for hiding this comment

sehilyi Nov 16, 2021

Choose a reason for hiding this comment

sehilyi commented Nov 16, 2021

manzt commented Nov 16, 2021

manzt commented Dec 10, 2021 • edited Loading

sehilyi commented Dec 11, 2021 • edited Loading

sehilyi commented Jul 5, 2022

manzt commented Jul 5, 2022

manzt commented Jul 6, 2022

sehilyi commented Jul 7, 2022

feat!: merge axis channels (e.g., `x` and `xe`); group channels as an `encoding` property #575

feat!: merge axis channels (e.g., `x` and `xe`); group channels as an `encoding` property #575

sehilyi commented Nov 1, 2021 •

edited

Loading

C2. The `encoding` property is added

C3. `TemplateTrack` modified accordingly

C4. `DataTrack` is removed entirely

sehilyi Nov 3, 2021 •

edited

Loading

sehilyi Nov 3, 2021 •

edited

Loading

manzt commented Dec 10, 2021 •

edited

Loading

sehilyi commented Dec 11, 2021 •

edited

Loading