help grstyle                                   http://repec.sowi.unibe.ch/stata/grstyle
---------------------------------------------------------------------------------------

Title

    grstyle -- Customize the overall look of graphs


Syntax

        grstyle init [ newscheme, path(path) replace ]

        grstyle scheme entry

        grstyle set subcmd ...

        grstyle type

        grstyle clear [, erase]


Description

    grstyle allows you to customize the overall look of graphs from within a do-file
    without having to fiddle around with external scheme files. The advantage of
    grstyle over manually editing a scheme file is that everything needed to
    reproduce your graphs can be included in a single do-file.

    grstyle init starts recording the custom style settings. Optionally, if newscheme
    is provided, a new scheme file is created and stored in the current working
    directory as "scheme-newscheme.scheme". grstyle init uses the active graph scheme
    as the base scheme for the custom style settings. The default scheme according to
    factory settings is s2color. Apply set scheme schemename prior to running grstyle
    init if you want to use a different scheme as the base scheme.

    After running grstyle init, use grstyle scheme entry to add a custom style
    setting. Use grstyle scheme entry repeatedly to add multiple settings. The syntax
    of scheme entry is described in scheme entries.

    In addition, you can use grstyle set to add sets of custom settings. grstyle set
    provides a number of precoded collections of scheme entries. Furthermore, it
    provides tools to automize the generation of certain types of scheme entries
    (e.g. colors or sizes).

    grstyle type views the custom settings (i.e., types the contents of the custom
    scheme file).

    grstyle clear deactivates the custom style settings. grstyle clear is only needed
    if you want to restore the original graph settings within the same Stata session;
    changes made by grstyle are only temporary and restarting Stata will remove the
    custom settings even if grstyle clear has not been specified. Furthermore,
    grstyle init automatically runs grstyle clear before initializing new settings.

    Some features of grstyle require the palettes package (providing commands 
    colorpalette, symbolpalette, and linepalette) to be installed on the system; type
    ssc install palettes to install the package.


Options for grstyle init

    path(path) specifies a path (absolute or relative) for the scheme file cerated by
        grstyle init newscheme. Option path() is only allowed if newscheme is
        specified. The default is to store the scheme file in the current working
        directory. Note that the graphs using the scheme will only display correctly
        if the scheme file is stored in a location where it is found by Stata (see 
        adopath).

    replace allows overwriting an existing file. replace is only allowed if newscheme
        is specified.


Options for grstyle clear

    erase causes the scheme file created by grstyle to be erased from disk. The
        default is not to erase the scheme file.


Examples

    Stata's default graph size is 5.5 by 4 inches. If you want all your graphs to be,
    say, 5 by 5 inches, you could change these defaults using grstyle as follows
    instead of adding options ysize(5) and xsize(5) to each graph command:

        . grstyle init
        . grstyle graphsize x 5
        . grstyle graphsize y 5
        . sysuse auto
        . scatter price weight
        . scatter price mpg
        . grstyle clear

    Here are a number of other useful style settings, starting from the s2color
    scheme:

        . set scheme s2color
        . grstyle init

    - get rid of background shading

        . grstyle color background white

    - use horizontal labels on vertical axis

        . grstyle anglestyle vertical_tick horizontal

    - add some space between tick labels and axis titles

        . grstyle gsize axis_title_gap tiny

    - also draw grid lines on horizontal axis

        . grstyle yesno draw_major_hgrid yes

    - always include minimum and maximum grid lines

        . grstyle yesno grid_draw_min yes
        . grstyle yesno grid_draw_max yes

    - change color, width, and pattern of grid lines

        . grstyle color major_grid gs8
        . grstyle linewidth major_grid thin
        . grstyle linepattern major_grid dot

    - place legend on the right and remove the frame

        . grstyle clockdir legend_position 4
        . grstyle numstyle legend_cols 1
        . grstyle linestyle legend none

    - thicker lines in line plots

        . grstyle linewidth plineplot medthick

    - transparent markers (for p1 and p2) (not supported in Stata 14 or below)

        . grstyle color p1markline navy%0
        . grstyle color p1markfill navy%50
        . grstyle color p2markline maroon%0
        . grstyle color p2markfill maroon%50

    - transparent confidence intervals (not supported in Stata 14 or below)

        . grstyle color ci_area gs12%50
        . grstyle color ci_arealine gs12%0

    - now draw some graphs:

        . sysuse auto
        . two (scatter price weight if foreign==0) (scatter price weight if
            foreign==1) (lfitci price weight if foreign==0, clstyle(p1line)) (lfitci
            price weight if foreign==1, clstyle(p2line)), legend(order(1 "domestic" 2
            "foreign"))
        . two (scatter price mpg if foreign==0) (scatter price mpg if foreign==1)
            (lfitci price mpg if foreign==0, clstyle(p1line)) (lfitci price mpg if
            foreign==1, clstyle(p2line)), legend(order(1 "domestic" 2 "foreign"))

    - revert back to s2color style

        . grstyle clear

    Most of the above can also be achieved with less typing using grstyle set.


Technical remarks

    Unless newscheme is provided, grstyle init creates a scheme called _GRSTYLE_ and
    stores it in file "scheme-_GRSTYLE_.scheme" in the PERSONAL ado-file directory
    (see help sysdir). That is, unless a custom scheme name is specified, grstyle
    will always use the same file to store the style settings. Be aware of this
    limitation if you use grstyle in parallel Stata sessions.

    grstyle maintains global macro GRSTYLE_FN containing the path and name of the
    scheme file used to store the custom style settings, global macro GRSTYLE_SN
    containing the corresponding scheme name, and global macro GRSTYLE_SN0 containing
    the name of the scheme that was active when initializing grstyle. Furthermore,
    depending on context, global macro GRSTYLE_RSIZE containing information on the
    reference size for size calculation will be set. grstyle clear removes these
    global macros.


Author

    Ben Jann, University of Bern, ben.jann@soz.unibe.ch

    Thanks for citing this software as follows:

        Jann, B. (2017). grstyle: Stata module to customize the overall look of
        graphs. Available from http://ideas.repec.org/c/boc/bocode/s458414.html.


Also see

    Online:  help for grstyle set, graph, schemes, scheme files, scheme entries