isoline

# Isoline (Gi) module

class vcs.isoline.Gi(Gi_name, Gi_name_src='default')[source]

The Isoline graphics method (Gi) draws lines of constant value at specified levels in order to graphically represent a two-dimensional array. It also labels the values of these isolines on the VCS Canvas. The example below shows how to plot isolines of different types at specified levels and how to create isoline labels having user-specified text and line type and color.

This class is used to define an isoline table entry used in VCS, or it can be used to change some or all of the isoline attributes in an existing isoline table entry.

Useful Functions:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# VCS Canvas Constructor
a=vcs.init()
# Show predefined isoline graphics methods
a.show('isoline')
# Show predefined VCS line objects
a.show('line')
# Change the VCS color map
a.setcolormap("AMIP")
# Plot data 's' with isoline 'i' and 'default' template
a.isoline(s,a,'default')
# Updates the VCS Canvas at user's request
a.update()
Create a canvas object:
a=vcs.init()
Create a new instance of isoline:
1
2
3
4
# Copies content of 'quick' to 'new'
iso=a.createisoline('new','quick')
# Copies content of 'default' to 'new'
iso=a.createisoline('new')
Modify an existing isoline:
iso=a.getisoline('AMIP_psl')
Overview of isoline attributes:

  • List all the isoline attribute values

    iso.list()

  • Set isoline 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
    iso.projection='linear'
lon30={-180:'180W',-150:'150W',0:'Eq'}
iso.xticlabels1=lon30
iso.xticlabels2=lon30
# Will set them both
iso.xticlabels(lon30, lon30)
iso.xmtics1=''
iso.xmtics2=''
# Will set them both
iso.xmtics(lon30, lon30)
iso.yticlabels1=lat10
iso.yticlabels2=lat10
# Will set them both
iso.yticlabels(lat10, lat10)
iso.ymtics1=''
iso.ymtics2=''
# Will set them both
iso.ymtics(lat10, lat10)
iso.datawc_y1=-90.0
iso.datawc_y2=90.0
iso.datawc_x1=-180.0
iso.datawc_x2=180.0
# Will set them all
iso.datawc(-90, 90, -180, 180)
xaxisconvert='linear'
yaxisconvert='linear'
# Will set them both
iso.xyscale('linear', 'area_wt')

  • Setting isoline level values:

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
    #1) As a list of tuples (Examples):
    iso.level=[(23,32,45,50,76),]
    iso.level=[(22,33,44,55,66)]
    iso.level=[(20,0.0),(30,0),(50,0)]
    iso.level=[(23,32,45,50,76), (35, 45, 55)]
#2) As a tuple of lists (Examples):
    iso.level=([23,32,45,50,76],)
    iso.level=([22,33,44,55,66])
    iso.level=([23,32,45,50,76],)
    iso.level=([0,20,25,30,35,40],[30,40],[50,60])
#3) As a list of lists (Examples):
    iso.level=[[20,0.0],[30,0],[50,0]]
#4) As a tuple of tuples (Examples):
    iso.level=((20,0.0),(30,0),(50,0),(60,0),(70,0))

    Note

    A combination of a pairs (i.e., (30,0) or [30,0]) represents the isoline value plus its increment value. Thus, to let VCS generate “default” isolines:

    # Same as iso.level=((0,1e20),)
iso.level=[[0,1e20]]

  • Displaying isoline labels:

    1
2
3
4
    # Same as iso.label=1, will display isoline labels
iso.label='y'
# Same as iso.label=0, will turn isoline labels off
iso.label='n'

  • Specify the isoline line style (or type):

    1
2
3
4
    # The following two lines of code are equivalent.
iso.line=([0,1,2,3,4])
# Both specify the isoline style
iso.line=(['solid, 'dash', 'dot', 'dash-dot', 'long-dash'])

  • There are three possibilities for setting the line color indices:

    1
2
3
4
5
6
    # The following two lines of code are equivalent
# Both will set the isoline to a specific color index
iso.linecolors=(22,33,44,55,66,77)
iso.linecolors=([22,33,44,55,66,77])
# Turns off the line color index
iso.linecolors=None

  • There are three possibilities for setting the line widths:

    1
2
3
4
5
6
    # The following two lines of code are equivalent
iso.linewidths=(1,10,3,4,5,6,7,8)
# Both will set the isoline to a specific width size
iso.linewidths=([1,2,3,4,5,6,7,8])
# Turns off the line width size
iso.linewidths=None

    Note

    If the number of line styles, colors or widths are less than the number of levels, we extend the attribute list using the last attribute value in the attribute list.

  • There are three ways to specify the text or font number:

    1
2
3
4
5
6
    # Font numbers are between 1 and 9
iso.text=(1,2,3,4,5,6,7,8,9)
iso.text=[9,8,7,6,5,4,3,2,1]
iso.text=([1,3,5,6,9,2])
# Removes the text settings
iso.text=None

  • There are three possibilities for setting the text color indices:

    1
2
3
4
    iso.textcolors=([22,33,44,55,66,77])
iso.textcolors=(16,19,33,44)
# Turns off the text color index
iso.textcolors=None

  • Attribute descriptions:

    label(str)

    Turn on/off labels on isolines

    labelskipdistance(float)

    Minimum distance between isoline labels

    labelbackgroundcolors([float])

    Background color for isoline labels

    labelbackgroundopacities([float])

    Background opacity for isoline labels

    level([float, ...])

    Isocountours to display

    clockwise([int, ...])

    Draw directional arrows +-(0,1,2) Indicate none/clockwise/clokwise on y axis >0. Clockwise on x axis positive negative value invert behaviour

    scale([float, ...])

    Scales the directional arrow lengths

    angle([float, ...])

    Directional arrows head angle

    spacing([float, ...])

    Scales spacing between directional arrows

    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

line([str, ...]/[vcs.line.Tl, ...]/[int, ...])

line type to use for each isoline, can also pass a line object or line object name

linecolors([int, ...])

colors to use for each isoline

linewidths([float, ...])

list of width for each isoline

text(None/[vcs.textcombined.Tc,...])

text objects or text objects names to use for each countour label

textcolors(None/[int,...])

colors to use for each countour label

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.createisoline('isoline_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

  • dsp1 (float) – Sets the datawc_y1 property of the object.

  • dsp2 (float) – Sets the datawc_y2 property of the object.

  • dsp3 (float) – Sets the datawc_x1 property of the object.

  • dsp4 (float) – Sets the datawc_x2 property of the object.

list()[source]

Lists the current values of object attributes

Example
1
2
3
4
5
>>> a=vcs.init()
>>> obj=a.getisoline() # default
>>> obj.list() # print isoline attributes
---------- ... ----------
...
script(script_filename, mode='a')[source]

Saves out a copy of the isoline 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.getisoline()
>>> 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.

setLineAttributes(mixed)[source]

Add either a (linetype, 1, 1) or (linetype, linecolor, linewidth) based on if mixed[i] is a linetype or a line object name.

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 isoline after setting the mtics and template, refer to vcs.Canvas.plot() or vcs.Canvas.isoline().

Example
1
2
3
4
5
>>> a=vcs.init()
>>> ex=vcs.createisoline()
>>> ex.xmtics("lon5") # minitick every 5 degrees
>>> tmp=vcs.createtemplate() # custom template to plot minitics
>>> tmp.xmintic1.priority = 1 # plotting shows xmtics
Parameters

  • xmt1 (dict or str) – Value for xmtics1. Must be a str, or a dictionary object with float:str mappings.

  • xmt2 (dict or str) – Value for xmtics2. Must be a str, or a dictionary object with float:str mappings.

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.createisoline()
>>> 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='', yat='')[source]

Sets xaxisconvert and yaxisconvert values for the object.

Example
>>> a=vcs.init()
>>> ex=a.createisoline('isoline_xys') # make a isoline
>>> 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 isoline after setting the mtics and template, refer to vcs.Canvas.plot() or vcs.Canvas.isoline().

Example
1
2
3
4
5
>>> a=vcs.init()
>>> ex=vcs.createisoline()
>>> ex.xmtics("lon5") # minitick every 5 degrees
>>> tmp=vcs.createtemplate() # custom template to plot minitics
>>> tmp.xmintic1.priority = 1 # plotting shows xmtics
Parameters

  • xmt1 (dict or str) – Value for xmtics1. Must be a str, or a dictionary object with float:str mappings.

  • xmt2 (dict or str) – Value for xmtics2. Must be a str, or a dictionary object with float:str mappings.

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.createisoline()
>>> 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.