boxfill¶
# Boxfill (Gfb) module
-
class
vcs.boxfill.
Gfb
(Gfb_name=None, Gfb_name_src='default')[source]¶ The boxfill graphics method (Gfb) displays a two-dimensional data array by surrounding each data value by a colored grid box.
This class is used to define a boxfill table entry used in VCS, or it can be used to change some or all of the attributes in an existing boxfill table entry.
-
General use of a boxfill:
1 2 3 4 5 6 7 8
# Constructor a=vcs.init() # Show predefined boxfill graphics methods a.show('boxfill') # Change the VCS color map a.setcolormap("AMIP") # Plot data 's' with boxfill 'b' and 'default' template a.boxfill(s,b,'default')
-
Updating a boxfill:
1 2 3 4 5 6
# Updates the VCS Canvas at user's request a.update() # Set VCS Canvas to automatic update mode a.mode=1 # Use update function to update the VCS Canvas a.mode=0
-
Create a new instance of boxfill:
1 2 3 4
# Copies content of 'quick' to 'new' box=a.createboxfill('new','quick') # Copies content of 'default' to 'new' box=a.createboxfill('new')
-
Modifying an existing boxfill:
1 2 3 4 5 6 7 8 9 10 11 12
fill=a.getboxfill('quick') # Set index using fillarea box.fillareaindices=(7,fill,4,9,fill,15) # list fillarea attributes fill.list() # change style fill.style='hatch' # change color fill.color='black' # change style index fill.index=3
-
Overview of boxfill attributes:
Listing all the boxfill attribute values:
box.list()
Setting boxfill attribute values:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
box.projection='linear' lon30={-180:'180W',-150:'150W',0:'Eq'} box.xticlabels1=lon30 box.xticlabels2=lon30 # Will set them both box.xticlabels(lon30, lon30) box.xmtics1='' box.xmtics2='' # Will set them both box.xmtics(lon30, lon30) box.yticlabels1=lat10 box.yticlabels2=lat10 # Will set them both box.yticlabels(lat10, lat10) box.ymtics1='' box.ymtics2='' # Will set them both box.ymtics(lat10, lat10) box.datawc_y1=-90.0 box.datawc_y2=90.0 box.datawc_x1=-180.0 box.datawc_x2=180.0 # Will set them all box.datawc(-90, 90, -180, 180) box.xaxisconvert='linear' box.yaxisconvert='linear' # Will set them both box.xyscale('linear', 'area_wt') box.level_1=1e20 box.level_2=1e20 box.color_1=0 box.color_2=255 # Will set them both box.colors(0, 255 ) # 'linear' - compute or specify legend box.boxfill_type='linear' # 'log10' - plot using log10 box.boxfill_type='log10' # 'custom' - use custom values to display legend evenly box.boxfill_type='custom' # Hold the legend values box.legend=None # Show left overflow arrow box.ext_1='n' # Show right overflow arrow box.ext_2='y' # Will set them both box.exts('n', 'y' ) box.missing='black'
Setting the boxfill levels:
1 2 3 4 5 6 7 8 9
# Case 1: Levels are all contiguous: box.levels=([0,20,25,30,35,40],) box.levels=([0,20,25,30,35,40,45,50]) box.levels=[0,20,25,30,35,40] box.levels=(0.0,20.0,25.0,30.0,35.0,40.0,50.0) # Case 2: Levels are not contiguous: box.levels=([0,20],[30,40],[50,60]) box.levels=([0,20,25,30,35,40],[30,40],[50,60])
Setting the fillarea color indices:
1 2 3 4
# Three different methods for setting color indices: box.fillareacolors=([22,33,44,55,66,77]) box.fillareacolors=(16,19,33,44) box.fillareacolors=None
Setting the fillarea style:
box.fillareastyle = 'solid' box.fillareastyle = 'hatch' box.fillareastyle = 'pattern'
Setting the fillarea hatch or pattern indices:
box.fillareaindices=([1,3,5,6,9,20]) box.fillareaindices=(7,1,4,9,6,15)
Using the fillarea secondary object (Ex):
1 2 3 4 5 6
f=createfillarea('fill1') #To Create a new instance of fillarea use: # Copies 'quick' to 'new' fill=a.createfillarea('new','quick') # Copies 'default' to 'new' fill=a.createfillarea('new')
Attribute descriptions:
Universally considered attributes:
boxfill_type ‘linear’/’log10’ relevant attributes:
-
level_1
(float)¶ Used in conjunction with boxfill_type linear/log10. Sets the value of the legend’s first level
-
level_2
(float)¶ Used in conjunction with boxfill_type linear/log10, sets the value of the legend’s end level.
-
color_1
(float)¶ Used in conjunction with boxfill_type linear/log10, sets the first value of the legend’s color range.
-
color_2
(float)¶ Used in conjunction with boxfill_type linear/log10. Sets the last value of the legend’s color range.
-
legend
({float:str})¶ Used in conjunction with boxfill_type linear/log10. replaces the legend values in the dictionary keys with their associated string.
-
ext_1
(str)¶ Draws an extension arrow on right side of a boxfill (values less than first range value)
-
ext_2
(str)¶ Draws an extension arrow on left side of a boxfill (values greater than last range value)
-
boxfill_type ‘custom’ relevant attributes:
-
levels
(list of floats)¶ Used in conjunction with boxfill_type custom. Sets the levels range to use. Can be either a list of contiguous levels, or list of tuples indicating first and last value of the range.
-
fillareacolors
(list)¶ Used in conjunction with boxfill_type custom. Specifies colors to use for each level.
-
More boxfill attributes:
-
xmtics1
(str/{float:str})¶ (Ex: ‘’) dictionary with location of intermediate tics as keys for 1st side of y axis
-
xmtics2
(str/{float:str})¶ (Ex: ‘’) dictionary with location of intermediate tics as keys for 2nd side of y axis
-
ymtics1
(str/{float:str})¶ (Ex: ‘’) dictionary with location of intermediate tics as keys for 1st side of y axis
-
ymtics2
(str/{float:str})¶ (Ex: ‘’) dictionary with location of intermediate tics as keys for 2nd side of y axis
-
xticlabels1
(str/{float:str})¶ (Ex: ‘*’) values for labels on 1st side of x axis
-
xticlabels2
(str/{float:str})¶ (Ex: ‘*’) values for labels on 2nd side of x axis
-
yticlabels1
(str/{float:str})¶ (Ex: ‘*’) values for labels on 1st side of y axis
-
yticlabels2
(str/{float:str})¶ (Ex: ‘*’) values for labels on 2nd side of y axis
-
projection
(str/vcs.projection.Proj)¶ (Ex: ‘default’) projection to use, name or object
-
datawc_x1
(float)¶ (Ex: 1.E20) first value of xaxis on plot
-
datawc_x2
(float)¶ (Ex: 1.E20) second value of xaxis on plot
-
datawc_y1
(float)¶ (Ex: 1.E20) first value of yaxis on plot
-
datawc_y2
(float)¶ (Ex: 1.E20) second value of yaxis on plot
-
datawc_timeunits
(str)¶ (Ex: ‘days since 2000’) units to use when displaying time dimension auto tick
-
datawc_calendar
(int)¶ (Ex: 135441) calendar to use when displaying time dimension auto tick, default is proleptic gregorian calendar
-
colors
(color1=0, color2=255)[source]¶ Sets the color_1 and color_2 properties of the object.
Note
color_1 and color_2 control which parts of the colormap to use for the plot. It defaults to the full range of the colormap (0-255), but if you use fewer colors, it will break up your data into precisely that many discrete colors.
- Example
1 2 3 4 5 6
>>> a=vcs.init() >>> array=[range(10) for _ in range(10)] >>> ex=a.createboxfill() >>> ex.colors(0, 64) # use colorcells 0-64 of colormap >>> a.plot(ex, array) <vcs.displayplot.Dp object at 0x...>
- Parameters
-
datawc
(dsp1=1e+20, dsp2=1e+20, dsp3=1e+20, dsp4=1e+20)[source]¶ Sets the data world coordinates for object
- Example
1 2 3 4 5
>>> a=vcs.init() >>> ex=a.createboxfill('boxfill_dwc') >>> ex.datawc(0.0, 0.1, 1.0, 1.1) # sets datawc y1, y2, x1, x2 >>> ex.datawc_y1, ex.datawc_y2, ex.datawc_x1, ex.datawc_x2 (0.0, 0.1, 1.0, 1.1)
- Parameters
-
property
ext_1
¶ Turns on extensions arrows for values before the first level
-
property
ext_2
¶ Turns on extensions arrows for values after the last level
-
getlevels
(varmin, varmax)[source]¶ Given a minimum and a maximum, will generate levels for the boxfill starting at varmin and ending at varmax.
- Example
>>> b=vcs.createboxfill() >>> lvls = b.getlevels(0,100) # 257 levels from 0-100 >>> b.levels = list(lvls) # set boxfill's levels attribute
- Parameters
varmin (float) – The smallest number desired for the boxfill’s levels attribute.
varmax – The largest number desired for the boxfill’s levels attribute.
- Returns
A numpy array of 257 floats, evenly distributed from varmin to varmax.
- Return type
numpy.ndarray
-
property
levels
¶ Sets the levels on a graphic method, optionally turns on/off extensions arrows
-
list
()[source]¶ Lists the current values of object attributes
- Example
1 2 3 4 5
>>> a=vcs.init() >>> obj=a.getboxfill() # default >>> obj.list() # print boxfill attributes ---------- ... ---------- ...
-
rename
(newname)[source]¶ Renames the boxfill in the VCS name table.
Note
This function will not rename the ‘default’ boxfill. If rename is called on the ‘default’ boxfill, newname is associated with default in the VCS name table, but the boxfill’s name will not be changed, and will behave in all ways as a ‘default’ boxfill.
- Example
1 2 3 4 5 6 7 8 9 10
>>> b=vcs.createboxfill('bar') >>> l=vcs.listelements('boxfill') # list of boxfills >>> 'bar' in l # shows l contains new boxfill True >>> b.rename('foo') >>> l=vcs.listelements('boxfill') # new list of boxfills >>> 'foo' in l # new name is in list True >>> 'bar' in l # old name is not False
- Parameters
newname (str) – The new name you want given to the boxfill
-
script
(script_filename, mode='a')[source]¶ Saves out a copy of the boxfill graphics method, in JSON or Python format to a designated file.
Note
If the the filename has a ‘.py’ at the end, it will produce a Python script. If no extension is given, then by default a .json file containing a JSON serialization of the object’s data will be produced.
Warning
VCS Scripts Deprecated. SCR script files are no longer generated by this function.
- Example
1 2 3 4
>>> a=vcs.init() >>> ex=a.getboxfill() >>> ex.script('filename.py') # append to 'filename.py' >>> ex.script('filename','w') # make/overwrite 'filename.json'
- Parameters
script_filename (str) – Output name of the script file. If no extension is specified, a .json object is created.
mode (str) – Either ‘w’ for replace, or ‘a’ for append. Defaults to ‘a’, if not specified.
-
xmtics
(xmt1='', xmt2='')[source]¶ Sets the xmtics1 and xmtics2 values on the object.
Note
The mtics attributes are not inherently plotted by the default template. The example below shows how to apply a custom template and enable it to plot mtics. To plot a the boxfill after setting the mtics and template, refer to
vcs.Canvas.plot()
orvcs.Canvas.boxfill()
.- Example
1 2 3 4 5
>>> a=vcs.init() >>> ex=vcs.createboxfill() >>> ex.xmtics("lon5") # minitick every 5 degrees >>> tmp=vcs.createtemplate() # custom template to plot minitics >>> tmp.xmintic1.priority = 1 # plotting shows xmtics
- Parameters
-
xticlabels
(xtl1='', xtl2='')[source]¶ Sets the xticlabels1 and xticlabels2 values on the object
- Example
1 2 3 4 5 6 7
>>> a = vcs.init() >>> import cdms2 # Need cdms2 to create a slab >>> f = cdms2.open(vcs.sample_data+'/clt.nc') # open data file >>> ex = a.createboxfill() >>> ex.xticlabels({0: "Prime Meridian", -121.7680: "Livermore", 37.6173: "Moscow"}) >>> a.plot(ex, f('u')) # plot shows labels <vcs.displayplot.Dp object at 0x...>
- Parameters
xtl1 (dict or str) – Sets the object’s value for
xticlabels1
. Must be a str, or a dictionary object with float:str mappings.xtl2 (dict or str) – Sets the object’s value for
xticlabels2
. Must be a str, or a dictionary object with float:str mappings.
-
xyscale
(xat='linear', yat='linear')[source]¶ Sets xaxisconvert and yaxisconvert values for the object.
- Example
>>> a=vcs.init() >>> ex=a.createboxfill('boxfill_xys') # make a boxfill >>> ex.xyscale(xat='linear', yat='linear')
- Parameters
xat (str) – Set value for x axis conversion.
yat (str) – Set value for y axis conversion.
-
ymtics
(ymt1='', ymt2='')[source]¶ Sets the xmtics1 and xmtics2 values on the object.
Note
The mtics attributes are not inherently plotted by the default template. The example below shows how to apply a custom template and enable it to plot mtics. To plot a the boxfill after setting the mtics and template, refer to
vcs.Canvas.plot()
orvcs.Canvas.boxfill()
.- Example
1 2 3 4 5
>>> a=vcs.init() >>> ex=vcs.createboxfill() >>> ex.xmtics("lon5") # minitick every 5 degrees >>> tmp=vcs.createtemplate() # custom template to plot minitics >>> tmp.xmintic1.priority = 1 # plotting shows xmtics
- Parameters
-
yticlabels
(ytl1='', ytl2='')[source]¶ Sets the yticlabels1 and yticlabels2 values on the object
- Example
1 2 3 4 5 6 7
>>> a = vcs.init() >>> import cdms2 # Need cdms2 to create a slab >>> f = cdms2.open(vcs.sample_data+'/clt.nc') # open data file >>> ex = a.createboxfill() >>> ex.yticlabels({0: "Eq.", 37.6819: "L", 55.7558: "M"}) >>> a.plot(ex, f('u')) # plot shows labels <vcs.displayplot.Dp object at 0x...>
- Parameters
ytl1 (dict or str) – Sets the object’s value for
yticlabels1
. Must be a str, or a dictionary object with float:str mappings.ytl2 (dict or str) – Sets the object’s value for
yticlabels2
. Must be a str, or a dictionary object with float:str mappings.
-