Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

wip: doc for color scales #3021

Draft
wants to merge 20 commits into
base: main
Choose a base branch
from
Draft

wip: doc for color scales #3021

wants to merge 20 commits into from

Conversation

mattijn
Copy link
Contributor

@mattijn mattijn commented Apr 15, 2023

@mattijn
Copy link
Contributor Author

mattijn commented Apr 26, 2023

I'm struggling a bit with this one. @joelostblom, can you have a look if this is going in the right direction? Its maybe a bit too lengthy. I also doubt on the order of the sections. Currently the page starts with some color-theory including examples of good vs bad practices to continue with the predefined color schemes in Altair. I can imagine that one does not want to scroll through the theory each time to reach the available color schemes in Altair..

@joelostblom
Copy link
Contributor

Sorry for the delay in reviewing this @mattijn I had a go now but something is up with my environment, so I will try again tomorrow or during next week.

Copy link
Contributor

@joelostblom joelostblom left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section is great! I would love to have more explanatory sections for good choices to make effective visualizations somehow linked to the Altair docs. I don't know exactly how this section will fit with the current color sections, but I think that is one of the things we will discuss on our call, so I just made some comments for now without knowing exactly where this will go in the end. Thanks for working on this!

Comment on lines +8 to +16
Effective visualization of scientific data requires careful attention
to color selection. Choosing the right colors can be a complex task,
involving considerations such as color perception, accessibility,
and aesthetics. Fortunately, there are a number of resources available
to help simplify this process, including pre-designed color schemes
and tools for exploring and modifying color scales. In this guide,
we'll explore some of the basics of color selection for scientific
data visualization, including different types of color scales and
examples of their use.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Effective visualization of scientific data requires careful attention
to color selection. Choosing the right colors can be a complex task,
involving considerations such as color perception, accessibility,
and aesthetics. Fortunately, there are a number of resources available
to help simplify this process, including pre-designed color schemes
and tools for exploring and modifying color scales. In this guide,
we'll explore some of the basics of color selection for scientific
data visualization, including different types of color scales and
examples of their use.
Effective data visualization requires careful attention
to color selection. Choosing the right colors can be a complex task,
involving considerations such as color perception, accessibility,
and aesthetics. Fortunately, there are a number of resources available
to help simplify this process, including pre-designed color schemes
and tools for exploring and modifying color scales. In this guide,
we'll explore some of the basics of color selection for
data visualization, including different types of color scales and
examples of their use.

Comment on lines +225 to +227
Color selection is an essential aspect of creating clear and informative
visualizations of scientific data. To make the most effective choices,
it's important to understand the basics of color perception and theory.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Color selection is an essential aspect of creating clear and informative
visualizations of scientific data. To make the most effective choices,
it's important to understand the basics of color perception and theory.
Color selection is an essential aspect of creating clear and informative
data visualizations. To make the most effective color choices,
it's important to understand the basics of color perception and theory.
In this section we start by explaining colors as perceived with standard color vision
and proceed to discuss how common color vision deficiencies alter color perception.

Comment on lines +234 to +240
.. altair-plot::
:remove-code:

percep_schemes = {
"two_color": ['blue','orange']
}
plot_scheme("two_color", percep_schemes, cvd=False, continuous=False, method='hcl').configure_scale(rectBandPaddingInner=0.1)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In all the plots in this section, could we remove the "normal vision" label and only include it in the section that talks about different types of color vision? I think the blue and orange rectangles could look better if they were made a bit smaller as well.

In the later plots, we might also want to consider calling it something like "Standard/reference/perfect color vision" instead of "normal". And likewise change "color blindness" to "color vision deficiencies" which is more descriptive of the partial loss in color vision that most people with this condition have (rather than a complete color blindness which is quite rare)

Comment on lines +229 to +230
Color perception and theory
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of starting with talking about how to define a path between two colors, what do you think about having a more data-centric explanation that explains the different scenarios for how color could be used with data? These would be varying the hue/color to represent categorical values and varying mainly luminance to represent change in a quantitative value (with two sub categories: sequential and diverging colormaps, both which should be perceptually uniform). Personally, I'm a fan of how the seaborn docs introduce this topic as it becomes really tangible how the concepts of color applies to data right across the bath. I think talking about categorical and numerical data also maps nicely to that these concepts are already used in channel encodings and maybe our categories would be nominal data on the one hand, and then ordinal and quantitative together (as discrete and continuous sequential (or diverging) color scales). What do you think?

The section you have is really interesting and I love that the color space plot is made directly in Altair, so I want to keep it as part of the "Sequential" subsection where we talk more about how these color palettes are defined.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I start my class on this with these three slides:

image

image

image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I also really like these from the mpl docs on what perceptually uniform looks like in terms of the lightness increase:

image

image

Comment on lines +242 to +244
Now, lets say we want to define a gradient between ``blue`` and ``orange``.
That means we have to go gradually from ``blue`` to ``orange``.
The interpolation between colors can follow several methods.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Now, lets say we want to define a gradient between ``blue`` and ``orange``.
That means we have to go gradually from ``blue`` to ``orange``.
The interpolation between colors can follow several methods.
Now, lets say we want to define a gradient between ``blue`` and ``orange``.
That means we have to gradually transition from ``blue`` to ``orange``,
which is also called an "interpolation" between the two colors.

Then after this I would have the paragraph that starts with "So what is the correct interpolation...", then show the color space plot, then show the ppaths and the corresponding sequential color schemes created by each path.

temperature anomalies or changes in sea level.

.. altair-plot::
:hide-code:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
:hide-code:
:remove-code:

However, these schemes are not well suited to accurately convey value differences.

.. altair-plot::
:hide-code:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
:hide-code:
:remove-code:

the types of flowers in a garden, or different political affiliations.

.. altair-plot::
:hide-code:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
:hide-code:
:remove-code:

Comment on lines +1302 to +1306
.. altair-plot::
:output: none

tol_schemes = {
"tol_bright" : ['#4477AA', '#EE6677', '#228833', '#CCBB44', '#66CCEE', '#AA3377', '#BBBBBB'],
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This might need some more explanation on how to use these custom palettes. Maybe the section could start with an intro of how to make your own palette (like what is in the color customization section right now) and then show some from this other source. Also, I am not familiar with Paul Tol, but maybe we can think about the presentation of his palettes so that it doesn't seem like the properties listed above are not true for the built-in altair color schemes, because in many cases they are.

Comment on lines +1502 to +1513
color=alt.expr("luminance(scale('color', datum.sum_yield)) > 0.5 ? 'black' : 'white'")
)

bars + text

The lighter the bar, the higher the luminance. If the bar is light
we like a text overlay that is black. The darker the bar, the lower
the luminance. If the bar is dark, we like a text overlay that is white.

In the expression above we have written this as a predicate. The text
appear ``black`` if the luminance is above ``0.5`` and ``white`` when
the luminance is below ``0.5``. The luminance is computed using the
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
color=alt.expr("luminance(scale('color', datum.sum_yield)) > 0.5 ? 'black' : 'white'")
)
bars + text
The lighter the bar, the higher the luminance. If the bar is light
we like a text overlay that is black. The darker the bar, the lower
the luminance. If the bar is dark, we like a text overlay that is white.
In the expression above we have written this as a predicate. The text
appear ``black`` if the luminance is above ``0.5`` and ``white`` when
the luminance is below ``0.5``. The luminance is computed using the
color=alt.expr("luminance(scale('color', datum.sum_yield)) > 0.408 ? 'black' : 'white'")
)
bars + text
The lighter the bar, the higher the luminance. If the bar is light
we like a text overlay that is black. The darker the bar, the lower
the luminance. If the bar is dark, we like a text overlay that is white.
In the expression above we have written this as a predicate. The text
appear ``black`` if the luminance is above ``0.408`` and ``white`` when
the luminance is below ``0.408``. The luminance is computed using the

This section is great! I love that expression can be used for this! The reason for the change I suggest here is to stay consistent with what is used in seaborn, which is also what I chose when adding this to the text of pandas heatmaps. We could add a note about this? (I was trying to look up the reason for picking this exact number in the first place, but based on my comment here I don't think I ever knew =) )

@dangotbanned
Copy link
Member

dangotbanned commented Jul 28, 2024

@mattijn I haven't got anything to add on any of @joelostblom's comments.

I found all the examples with altair code really helpful!

The format of https://mattijn.github.io/altair-docs/user_guide/color_usage.html#guidelines-for-using-colors is a major 👍 👍 👍


Some of these are more targeted at UX/App design, but might help bring a different perspective

@mattijn
Copy link
Contributor Author

mattijn commented Jul 29, 2024

For me, this kind of PR is quite energy demanding to do right. So, if others are excited to embrace this opportunity, please don't hesitate, chime in!

Last year I had access to a bit of funding from which I partly could do maintenance and doc-writing for Altair during working hours. In that period I also had asked my colleague to start writing a conceptual guide on best practices of effective data communication. That has reached concept level, see also this .docx memo. Based on some discussions it was decided that it would be best if we can reduce this to something like 5 pages at maximum, otherwise it will become more book-like. It make sense to do some shifting of docs in this PR to the part of this, yet-to-be-written compact conceptual guide. This is now also defined on the roadmap (edit: and as issue #3117). My hope is still that the Vega project becomes a NumFOCUS project so it may be possible to get access to some funding to finish this as work.

But like what I said, if others see this as an opportunity to contribute, please feel free!

@dangotbanned
Copy link
Member

Thanks for the context @mattijn

For me, this kind of PR is quite energy demanding to do right. So, if others are excited to embrace this opportunity, please don't hesitate, chime in!

I definitely can relate to this! But after skimming through .docx memo I feel quite out of my depth on the theory required for this task.

My hope is still that the Vega project becomes a NumFOCUS project so it may be possible to get access to some funding to finish this as work.

Hopefully this will allow someone better equipt for this task to work on it.
I do have the time, for now, but I think I can utilise that more effectively in other areas of altair.

I see a lot of value in this kind of documentation and whenever it arrives - I'm sure it will be worth the wait

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

documentation of color schemes and options
3 participants