Getting started  –  How to use grstyle

Introduction

The idea behind grstyle is to provide an easy way to change the default look of Stata graphs. In Stata, default attributes for the objects of a graph are set by so-called scheme files. If you want to change the defaults, you need to put together a personal scheme file (see help scheme files) and then load the scheme using set scheme. This means that the graph settings are kept in a separate file and are not part of the analysis script producing the graph.

grstyle provides a way to change graph defaults on the fly from within an analysis script without having to bother about external scheme files. Technically, grstyle does nothing else than creating a scheme file and then loading it as the default scheme. Handling the scheme file, however, is fully automated. Furthermore, grstyle provides a number of useful features such as assigning colors based on predefined palettes or setting the sizes of text and other objects in absolute units.

A first example

The basic procedure is very simple. First run grstyle init to start the custom settings. After that, apply one or more grstyle scheme entry or grstyle set commands to record the custom settings. Then create your graphs. Here is an example:

. grstyle init

. grstyle graphsize x 4

. grstyle graphsize y 4

. grstyle symbol p circle_hollow

. sysuse auto, clear
(1978 Automobile Data)

. scatter price weight

Scheme entries graphsize x 4 and graphsize y 4 set the default size of the graph, scheme entry symbol p circle_hollow sets the default marker symbol. See help scheme entries for documentation on scheme entries. See here for more further scheme entry examples.

Setting the base scheme

grstyle init uses the current scheme as starting point for the custom settings. The default scheme according to factory settings is s2color. If you want to start from a different scheme, use set scheme to change the scheme prior to applying grstyle init. For example, if you want to use s1color as starting point, type:

. set scheme s1color

. grstyle init

. grstyle graphsize x 4

. grstyle graphsize y 4

. grstyle symbol p circle_hollow

. sysuse auto, clear
(1978 Automobile Data)

. scatter price weight

Using grstyle set

grstyle set is a utility command to generate sets of style settings without much typing and without knowing much about scheme entry syntax. Here is an example:

. grstyle init

. grstyle set imesh, horizontal minor

. grstyle set legend 4, nobox

. grstyle set color hue, n(5)

. sysuse auto, clear
(1978 Automobile Data)

. separate price, by(rep) shortlabel
(output omitted)

. scatter price? weight, ytitle(Price)

grstyle set imesh renders the coordinate plane as an inverted mesh, similar to ggplot2 in R (option horizontal requests horizontal tick labels on the vertical axis, option minor adds minor grid lines). The grstyle set legend command is used to place the legend at the lower right side of the plot (position 4) and remove the frame around the legend. Furthermore, grstyle set color is used to set the marker colors (using HCL colors with evenly spaced hues). See here for further examples on grstyle set.

Viewing the settings

Use grstyle type to view the contents of the temporary scheme file creates by grstyle. For example, if you want to know what grstyle set plain does, type:

. set scheme s2color

. grstyle init

. grstyle set plain

. grstyle type
#include s2color
color background white
color plotregion none
linestyle plotregion none
color grid dimgray
color major_grid dimgray
color minor_grid dimgray
linewidth grid thin
linewidth major_grid thin
linewidth minor_grid thin
color heading black
color textbox none
color bylabel_outline none
color mat_label_box none

Clearing the settings

Type grstyle clear to drop the custom graph settings and restore the scheme that was active when calling grstyle init. grstyle clear is only needed if you want to restore the original settings within the same Stata session; changes made by grstyle are temporary and restarting Stata will remove the custom settings. Furthermore, grstyle init automatically runs grstyle clear before initializing new settings.

Creating a named scheme

By default, grstyle uses a temporary scheme to recode the custom settings. If you prefer, you can assign an explicit name to the scheme when calling grstyle init. In this case, a scheme file with the chosen name will be created in the working directory (or in the directory specified by the path() option). Example:

. grstyle init myscheme, replace

. grstyle color background white

. grstyle color major_grid gs8

. grstyle linewidth major_grid thin

. grstyle linepattern major_grid dot

. findfile scheme-myscheme.scheme
./scheme-myscheme.scheme

. type scheme-myscheme.scheme
#include s2color
color background white
color major_grid gs8
linewidth major_grid thin
linepattern major_grid dot

. grstyle clear, erase

. capture noisily findfile scheme-myscheme.scheme
file "scheme-myscheme.scheme" not found

Option replace allows grstyle init to overwrite an existing file; option erase causes grstyle clear to delete the scheme file.