new package on SSC: brewscheme

[wbuchanan]

Thanks to Kit Baum's work maintaining the SSC archives, I can share a program that I've been working on for a little bit with the rest of the Stata community. The package

brewscheme

provides functionality analogous to the <a href="https://cran.r-project.org/web/packages/RColorBrewer/index.html">RColorBrewer</a> package in R, with a few notable exceptions. As a simple example, you can create a scheme file with a single color palette (which also makes some modifications to other defaults) using:

// Load the auto data set
sysuse auto, clear

// Create a new scheme file for all graph types
brewscheme, scheme(test) allstyle(dark2) allcolor(7)

// Make a simple graph using Stata defaults
tw scatter mpg length || lfit mpg length, name(stata, replace)

// Make the same graph using the scheme file you just created
tw scatter mpg length || lfit mpg length, scheme(test) name(brewscheme, replace)

However, unlike RColorBrewer, you can generate a scheme using multiple palettes simultaneously with varying numbers of colors (the varying number of colors part still has a few bugs that I am working on fixing but generally works fairly well).

// Create a new scheme file with different palettes and #s of color per palette
// for different graph types
brewscheme, barst(paired) barc(12) dotstyle(prgn) dotc(7) scatstyle(set1)     ///   
scatc(9) linest(dark2) linec(8) somestyle(accent) somec(8) areast(dark2)     ///   
areac(8) scheme(test2)

// Make a simple graph using Stata defaults
gr box price, over(rep78) name(stata, replace) 

// Make the same graph using the scheme file you just created
gr box price, over(rep78) asyvars scheme(test2) name(brewscheme, replace)

Additionally, the program also provides access to all of the metadata from the palettes developed by Cynthia Brewer at www.colorbrewer2.org:

// This command allows you to check characteristics of the palettes
brewmeta accent, c(5)

// The output looks like this for the command with either no properties specified
The color palette accent with 5 colors is Not color blind friendly
The color palette accent with 5 colors is Possibly LCD friendly
The color palette accent with 5 colors is Not photocopy friendly
The color palette accent with 5 colors is Possibly print friendly

In addition to the version archived in the SSC, you can access a development version of the package from:

net inst brewscheme, from("http://www.paces-consulting.org/stata")

I'm already working on adding some additional features for future releases, but welcome any/all feedback.

Billy Buchanan
Data Scientist
Minneapolis Public Schools

[wbuchanan]

Slides from the 2015 Stata Users' Group Conference in Columbus, OH are available and show a few more examples of how the program can be used : http://www.stata.com/meeting/columbu...5_buchanan.pdf

[wbuchanan]

Thanks once again to KitBaum for getting an updated version of -brewscheme- up on the SSC archives. The version posted fixes issues with varying numbers of colors across graph types. Now the selected colors will be repeated - in order - until the maximum number of colors across all graph types is reached. This version also includes some early stage utilities to add look up data to the brewscheme db on the user's local machine. There are a few other things I am trying to work out before a true version 1 release, but any/all help testing as well as any feedback anyone can provide would definitely be helpful/useful.

[Marcos Almeida]

Congrats for the new package.

I've used RColorBrewer and it's really an amazing experience. Great, having such facilities in Stata, By the way, now that this program comes to a Stata environment, does it allow point-and-click access to edit graphs?

Best,

Marcos

[wbuchanan]

Marcos Almeida There are a few differences between the two programs that should be clarified. Before that, there isn't a GUI built out for it at the moment (but if anyone else wanted to work on that I'd be more than happy to help out as much as possible). But you should be able to edit the graphs using the graph editor that is built into Stata if I'm understanding your question correctly.

RColorBrewer does a couple of things, but primarily it is used to access a single color palette from www.colorbrewer2.com and map those colors to values in a graph; it also has support for interpolating between color values. RColorBrewer seems to be designed primarily for interactive use and requires multiple calls to the same function (or to create an object storing the result of the function call to be recycled within the current session/workspace).

The brewscheme program, however, isn't necessarily meant for interactive use, although it performs well enough (at the moment at least) to still be used in an interactive way. I was really trying to solve two different problems simultaneously with the program: 1.) make it easier to generate customized scheme files that would reduce the verbosity of many graph commands that might otherwise be bogged down by lots of arguments being passed to lots of aesthetic parameters; and 2.) bring research based color selection into the Stata environment. The first issue was the bigger of the two that I was trying to deal with; I was able to quickly lop off tons of code from what I would normally have written and save time by not having to remember the different options that I needed/wanted to adjust. The second problem was basically the vehicle I used to get there.

In terms of the differences, brewscheme is probably like some hybrid of ggtheme and RColorBrewer from the R environment, but also expands upon things by pulling in palettes from other published sources and building them into the program from the beginning (e.g., there are a bunch of palettes from some work that Jeff Heer did involving semantic color mapping, a palette used by default in Tableau for categorical values, etc...). The components of the program that I'm still working on involve taking a graph and producing an analog of a proof that would show the graph in question along with three duplicates corresponding to each of the three types of colorblindness (e.g., graph once and get to check whether or not using those colors seems appropriate to put into production).

[Marcos Almeida]

wbuchanan Thank you very much for the explanation. IMHO, Stata's point-and-click access to graphic editions will turn out into a remarkable advantage (at least for Stata users) of this "colorful R-born" program. That's really awesome. I'll try it out in Stata very soon. Congratulations again.

[wbuchanan]

Thanks once again to Kit Baum for posting an updated version of brewscheme to the SSC archives. This update brings several new features and functions to the brewscheme package:

brewviewer is a program to preview combinations of the color palettes of your choice. The program has options to allow you to specify the maximum number of colors to graph the colors leading up to that value sequentially (e.g., a value of 5 will show combinations with 3, 4, and 5 colors) or individually.

brewterpolate adds functionality to interpolate colors given a starting and ending color and the number of points to interpolate between them.

hextorgb is a simple hexadecimal to decimal conversion program.

Additionally, the d3.scales.category(), d3.scales.category20(), d3.scales.category20b(), and d3.scales.category20c() palettes have been added to the program. For examples of brewviewer and to learn more about the program, check the program's GitHub repository https://github.com/wbuchanan/brewscheme.

[wbuchanan]

I've finally gotten around to piecing together a quick version of something I've been thinking about/talking about for a while for this package. It isn't part of the recent SSC release, but for anyone interested the current development branch of brewscheme includes a new program called brewtheme. It is similar to brewscheme, but basically separates the global graph aesthetics (e.g., number of ticks, text sizes, etc...) from graph specific aesthetics. I've also recently rebuilt the project website which now includes an example of using brewtheme to recreate the aesthetic style of the ggplot2 package in R:

http://wbuchanan.github.io/brewscheme/brewtheme/

[wbuchanan]

Getting closer to a full version 1.0 type release and just got the foundation for the last bit of additional functionality built out. http://wbuchanan.github.io/brewscheme/brewcbsim/ This link shows examples of one of the new features which will end up being the base for additional functionality. With the

 brewbcsim

program in the brewscheme suite, you can specify an RGB tuple and will get a graph that will show you how the color would appear to individuals with different forms of color sight impairments. Additionally, the graph also shows the transformed RGB values for each of the types of "color blindness." There is also a new Mata library used for the transformations and this will be used to add translated values to the lookup tables created by brewdb/brewextra.

[wbuchanan]

For convenience, I've copied some of the example images below:

Green dominant color:


Red color dominant example


Blue color dominant example



brewtheme example

[wbuchanan]

An early update to the palette previewer brewviewer now includes an option that simulates what the colors would look like to individuals with various forms of color sightedness impairments. While not completely documented yet, there are also new features for user defined named colors, an option to add all of the named colors from the XKCD survey in 2010, a function to build a dataset with the named colors defined by StataCorp along with the RGB values transformed to simulate the forms of colorblindness, and some Mata functions/classes for simulating colorblind perception of RGB values, looking up RGB values based on named styles, and more. To keep track of the updates check the project website: https://wbuchanan.github.io/brewscheme and keep an eye on the development branch (dev) in the project's github repository https://github.com/wbuchanan/brewscheme.

[wbuchanan]

Things are getting closer. There are new updates for brewscheme and brewtheme that automatically translate the user specified color values into colors that show how they would be perceived by individuals with different forms of color blindness. This is done to develop a proofing program to allow users to check the perceptibility of their data visualizations to people with color sight impairments. As an example, I took the ggplot2 type graph example and created what the proofing program will eventually output (with some modifications still to be made).



There is additional information available on the program's project page: http://wbuchanan.github.io/brewscheme.

[wbuchanan]

Proofing program is up. To install the latest version use:

// Installs current version being tested
net inst brewscheme, from("http://wbuchanan.github.io/brewscheme/") replace

// Compiles Mata libraries required by programs on your computer for you
libbrewscheme

/* Builds out a lookup dataset for Stata named colors used by brewtheme/brewscheme
to provide automatic translation of scheme files for different forms of color sight impairment. */
brewcolordb

Additional information can be found at http://wbuchanan.github.io/brewscheme including a few simple examples and demonstrations of some of the toolkit's functionality/features.

[Andy dB]

brewscheme, scheme(punk1) allst(purples)

gives me the following message

file c:\ado\personal/b/brewmeta.dta not found

I'm using Stata on Win 10, executing it as an admin. Any ideas?

This message cross-posted here
https://github.com/wbuchanan/brewscheme/issues/21

[wbuchanan]

Windows 10 has all sorts of issues with file permissions. Make sure that C:/ado/personal is writable and it should take care of it. The first time the program is executed it will try to create a few different subdirectories in personal that it uses to store color and palette data used to construct the scheme and theme files.