5/12/2017 GitHubhaibuihoang/higrads:Agradsscriptlibraryformanagingsubplots&andotherplottingfunctions

Features Business Explore Pricing This repository Search Sign in or Sign up

haibuihoang / higrads Watch 1 Star 1 Fork 0

Code Issues 0 Pull requests 0 Projects 0 Pulse Graphs

A grads script library for managing subplots & and other plotting functions

48 commits 1 branch 1 release 1 contributor MIT

Branch: master New pull request Find file Clone or download

haibuihoang update example Latest commit b178697 17 days ago

examples update example 17 days ago

library update draw tickmarks 17 days ago

releases First version a year ago

LICENSE.md Update LICENSE.md a year ago

README.md Update README.md 17 days ago

README.md

HiGrads
HiGrads is a GrADS script library which helps compose Grads subplot in an easy way as well as provide some additional chart
plotting functions. HiGrads is created initially for generating higher quality figures using GrADS for paper publishing during
my Postdoctoral research at Kyoto University.

The figure below shows the fundamental concept of frames in HiGrads approach. Each frame is considered a block, which is
placed adjacent to each other. This concept is borrowed from CSSs box model, which is standard in web design. Beside the
plotting area dimensions width & height, a box has four margins top, right, bottom, left. The code to generated this plot is
just about 60 lines of code and is included in the library h_demo.gs.

https://github.com/haibuihoang/higrads 1/9
5/12/2017 GitHubhaibuihoang/higrads:Agradsscriptlibraryformanagingsubplots&andotherplottingfunctions

##A crash course

1. Installation
You just need to unpack the library zip file and copy all the files to GrADs library. For easy maintenance, all HiGrads files have
the prefix h_.

Then, you can test HiGrads by open GrADS portrait mode recommended and type h_test

grads p

h_test

If you get the following plot, then HiGrads work!

https://github.com/haibuihoang/higrads 2/9
5/12/2017 GitHubhaibuihoang/higrads:Agradsscriptlibraryformanagingsubplots&andotherplottingfunctions

You can open file h_test.gs which included in the library to have a glance of how short and easy the plot is made. There is
even not needed any data file! In the next section, we will go on a short tutorial of how these things work.

2. HiGrads basic usage

HiGrads is exclusively written for GrADS script which in general, you cannot use from GrADS command windows but in a
GrADS script .gs file. In a .gs file, you need to enable grads script function by the following code:

r=gsfallow('on')

The first step, you need to initialize everything

h_initframe()

This function might take a parameter: 'l2r' default: frames are places from left to right, 't2b': frames are place from top to
bottom

Define a new frame, you can use function h_newframe(w,h). Where w & h are width & height parameters in inches
remember, GrADS page size is either 11x8.5 inches or 8.5x11 inches depends on landscape or portrait mode. For examples:

h_newframe(3,3)

Means that you define a box with w=3 and h=3 inches. After using that function, every GrADS display commands will be
bound in the plotting area of that box. To create a new box, you can simply call h_newframe again with same or different
parameters.

What about margin? Well, all margins take the default values of 0.5 inches. To manage the margin of the frame, you use the
function h_setmargin(top,right,bottom,left) before h_newframe. Remember the first is the top, then run clockwise
direction, similar to CSS margin. For example:

h_setmargin(0.5,0.2,0.5,0.5)

https://github.com/haibuihoang/higrads 3/9
5/12/2017 GitHubhaibuihoang/higrads:Agradsscriptlibraryformanagingsubplots&andotherplottingfunctions

Will set right margin to 0.2, while all other margin is 0.5 inch

If all the margins have the same value, e.g. 0.3, you only need to set h_setmargin(0.3). If you set h_setmargin(0.3,0.1), that
means top and bottom =0.2, left = right=0.1 If every frame has the same margins, you only need to set it once.

Now, try putting everything together example1.gs.

First, we reinitialize everything and open data file, init HiGrads and set default margins

'setdisplaycolorwhite';'c'
'openmodel.ctl'

r=gsfallow('on')
h_initframe()
h_set_margin(0.5,0.2,0.5,0.5)

We intend to have 2 equal subplots with w=3 & h=3. Total horizontal spaced needed will be the width of the two 6 inches,
Plus the margins 0.5 + 0.2 + 0.5 + 0.2 = 1.4, in total = 7.4, so that we know it will fit on portrait paper w=8.5

h_newframe(3,3)
'setlat828';'setlon100120';*Isetan*squared*aroundVietnam
'setmprojscaled';*thisforcetheplotusingthewholedefinedspace
'dtsfc'
'drawtitleSubPlot1'

The subplot is in position as expected, now the next subplot. But the tick marks and labels are quite small and dense, and I
don't like the lattitude and longitude lines. So we will use the HiGrads function for the next subplot

h_newframe(3,3)
h_nodefault()
'setgxoutshaded'
'dtsfc'
h_set_xrange(100,120)
h_set_yrange(8,28)
h_draw_xtm(90,120,1,5)
h_draw_ytm(5,30,1,5)
h_draw_ltitle('SubPlot2')
h_cbarn('r',0,0.1)

There are some new HiGrads functions h_ are envolved here. First, h_nodefault indicated that we will not use default tick
marks of grads. In order to use HiGrads ticks marks, we need to define the X and Y coordinates by h_set_xrange(x1,x2) and
h_set_yrange(y1,y2). You may add the 3rd parameter optional which can take either linear default or log for
lograrithm scale, see h_test.gs for a demonstration of how to use it.

Then h_draw_xtm and h_draw_ytm will handle the tick marks drawing. h_draw_xtm and h_draw_ytm take 4 parameters,
(start,end,increment,major), which mean it will draw minor ticks from start every increment value through end,
major ticks and labels are drawn every major ticks mark.

h_draw_ltitle is for drawing a leftaligned title similarly, h_draw_rtitle is for rightaligned title.

The last one is 'h_cbarn' function to display the color scale. It has 3 parameters, the first is either 'r' or 'b', which means right
or bottom position, the second optional is the offset of position, the 3rd optional is the font size.

The plot should look like this

https://github.com/haibuihoang/higrads 4/9
5/12/2017 GitHubhaibuihoang/higrads:Agradsscriptlibraryformanagingsubplots&andotherplottingfunctions

Adding options for displaying lat/lon see example1.gs for details and change the color scale by using h_rgb command, we
got

3. Let's draw a chart!!!

To understand more about HiGrads, let's draw a chart, and it must be an interesting one! So we are going to draw this set of
equation

x = 16sin^3t

y = 13cost 5cos2t 2cos3t cos4t

where t ranges from 0 to 2Pi

First step, set up a 6x6 inches plot with range from 30 to 30 for both x and y coordinates and draw the basic tick marks plus
two gray lines through the origin

'setdisplaycolorwhite';'c'
r=gsfallow('on')
h_initframe()
h_set_margin(1)
h_newframe(6,6)
h_set_xrange(30,30);h_set_yrange(30,30)
h_draw_xtm(30,30,1,10);h_draw_ytm(30,30,1,10)
'setline1511';
h_draw_line(30,0,30,0)
h_draw_line(0,30,0,30)
h_draw_ltitle('MyHeart')

Now we will draw the chart using function h_draw_line. This functions similar to drawline command in GrADS, but far
more powerful because it cause draw directly on chart coordinates default Or physical coordinates and you can set the
arrowhead at the start, end, or both. Please refer to HiGrads function descriptions for more details about this.

pi=4*math_atan(1)
dt=0.001
'setrgb1625540200'
'setline1616'
t=0;while(t<=2*pi)
x=16*math_pow(math_sin(t),3)
y=13*math_cos(t)5*math_cos(2*t)2*math_cos(3*t)math_cos(4*t)

https://github.com/haibuihoang/higrads 5/9
5/12/2017 GitHubhaibuihoang/higrads:Agradsscriptlibraryformanagingsubplots&andotherplottingfunctions
if(t>0)
h_draw_line(x_o,y_o,x,y)
endif
x_o=x;y_o=y
t=t+dt;endwhile

Final small touch!

*drawthearrow
'setline111'
h_draw_line(2,2,15,15,1,'s')
px=h_get_px(15);py=h_get_py(15)+0.1
'setstring1bc'
'drawstring'px''py'Youarehere!'

Now running the script example2.gs, you should get a nice animation drawing the heart because we set dt to a very small
value and this is the final result which you can print out during Valentine day as a present and prove that science is not so
boring ; You may notice two functions, h_get_px(x) and h_get_py(y), which convert chart coordinate to
plotting/physical/paper coordinates. The counterpart of the two are h_get_x(px) and h_get_y(px) will convert from paper
coordinates to chart coordinates.

Some complex example plots

Example 1 a plot of a timeheight section of zonal mean zonal wind, shear, 1day rainfall & running average rainfall. This
plot has 4 subplots with some drawing functions h_draw_mark, h_draw_line, h_draw_rect

https://github.com/haibuihoang/higrads 6/9
5/12/2017 GitHubhaibuihoang/higrads:Agradsscriptlibraryformanagingsubplots&andotherplottingfunctions

Example 2 a plot contains 28 subplots of Hovmoller diagrams, notice the axis label in between is omitted to saving the
space.

https://github.com/haibuihoang/higrads 7/9
5/12/2017 GitHubhaibuihoang/higrads:Agradsscriptlibraryformanagingsubplots&andotherplottingfunctions

Functions lists incomplete

Frame/Block setting

h_initframe(order,debug);*Thismustbecalledfromthestart.orderisoptional:'l2r'(default)or't2b'debugisoptional,defa
h_set_margin(t,r,b,l);*setmarginsimilartoCSSstyles,unitsininches
h_newframe(w,h);*Defineanewappendingblock
h_floatframe(w,h,x1,y1);*Definaafloatingblock,x1&y1istheleftbottomcornercoornidateininches
h_break();*puttheblocktothenextrowinsteadofappending

Coordinates functions

h_set_xrange(xmin,xmax,type);*settherangeforxcoordinates,typeiseither'linear'or'log'
h_set_yrange(ymin,ymax,type);*similartoh_set_xrangeforycoordinates
h_get_px(x);*fromchartcoordiates>paper/plotcoordinates(inches)
h_get_py(y)
h_get_x(px);*frompaper/plotcoordinates(inches)>chartcoordiates
h_get_y(py)

Drawing function chart lable

:h_draw_xtm(min,max,dx,maj,siz,offset);*drawtickmarks
h_draw_ytm(min,max,dy,maj,siz)

h_draw_title(title,thick,size,offset);*drawtitle,left,andrightalignedtitles
h_draw_ltitle(title,thick,size,offset)
h_draw_rtitle(title,thick,size,offset)

h_draw_xlab(title,thick,size,offset);*drawchartlables
h_draw_ylab(title,thick,size,offset)
h_draw_string(vx,vy,string,offset_x,offset_y);*drawstring,vx,vyisinchartcoordinates,offsetsininches
h_draw_mark(vx,vy,type,size);*drawmark,vx,vyinchartcoordinates
h_draw_line(x1,y1,x2,y2,onchart,arrow,angle,head);*drawline/arrow,onchart=1>usechartcoordinates(default),=0:usepapercoord
h_draw_rect(x1,y1,x2,y2,linecolor,bgcolor)

https://github.com/haibuihoang/higrads 8/9
5/12/2017 GitHubhaibuihoang/higrads:Agradsscriptlibraryformanagingsubplots&andotherplottingfunctions
h_cbarn(pos,offset,sz);*similartocbarn,pos='b'forbottompossition,='r'forright.offsetininchfromdefaultposition,sziss

Other functions

h_demo();*Ademoscripttotesthigradsfunctionality

Global variables
Global variables are used accross higrads functions, you can use them directly if needed but don't change their value.

Variable name Meanings

_debug Debuging flag

_x1,_x2,_y1,y2 Paper coordinates in inches of current bounding box

_px1,_px2,_py1,_py1 Paper coordinates in inches of current chart

_y1min The lowest coordinate

_top, _right, _bottom, _left Box margins in inches

_xmin, _xmin, _ymin, _ymax Range of chart coordinates

_ax,_bx,_apx,_bpx,_xscale,_yscale Coeficent for coordinates, DON'T mess with these!

Other links
GrADS Homepage
Open Grads
Google groups discussion for HiGrads
My personal blog

2017 GitHub, Inc. Terms Privacy Security Status Help Contact GitHub API Training Shop Blog About

https://github.com/haibuihoang/higrads 9/9