template

# Adapted for numpy/ma/cdms2 by convertcdms.py # Template (P) module

class vcs.template.P(Pic_name=None, Pic_name_src='default')

The template primary method (P) determines the location of each picture segment, the space to be allocated to it, and related properties relevant to its display.

Useful Functions:

# Show predefined templates
a.show('template')
# Show predefined text table methods
a.show('texttable')
# Show predefined text orientation methods
a.show('textorientation')
# Show predefined line methods
a.show('line')
# Show templates as a Python list
a.listelements('template')
# Updates the VCS Canvas at user's request
a.update()

Make a Canvas object to work with:

# VCS Canvas constructor
a=vcs.init()

Create a new instance of template:

# Two ways to create a templates:
# Copies content of 'hovmuller' to 'new'
temp=a.createtemplate('new','hovmuller')
# Copies content of 'default' to 'new'
temp=a.createtemplate('new')

Modify an existing template:

temp=a.gettemplate('hovmuller')

blank(attribute=None)

This function turns off elements of a template object.

Parameters

attribute (None or str or list) – String or list, indicating the elements of a template which should be turned off. If attribute is left blank, or is None, all elements of the template will be turned off.

drawAttributes(x, slab, gm, bg=False, **kargs)

Draws attributes of slab onto a canvas

Example

>>> a=vcs.init()
>>> import cdms2 # We need cdms2 to create a slab
>>> f = cdms2.open(vcs.sample_data+'/clt.nc') # open data file
>>> s = f('clt') # use the data file to create a slab
>>> t=a.gettemplate()
>>> b=a.getboxfill() # boxfill gm
>>> t.drawAttributes(a,s,b) # shows attributes of s on canvas
[...]

Parameters

• x (vcs.Canvas.Canvas) – vcs canvas onto which attributes will be drawn

• slab (cdms2.tvariable.TransientVariable or numpy.ndarray) – slab to get attributes from

drawColorBar(colors, levels, legend=None, ext_1='n', ext_2='n', x=None, bg=False, priority=None, cmap=None, style=['solid'], index=[1], opacity=[], pixelspacing=[15, 15], pixelscale=12, **kargs)

This function, draws the colorbar, it needs:

colors : The colors to be plotted levels : The levels that each color represent legend : To overwrite, saying just draw box at certain values and display some specific text instead of the value ext_1 and ext_2: to draw the arrows x : the canvas where to plot it bg: background mode ? returns a list of displays used :param colors: :param levels: :param legend: :param ext_1: :param ext_2: :param x: :param bg: :param priority: :param cmap: :param style: :param index: :param opacity: :param kargs: :return:

drawLinesAndMarkersLegend(canvas, linecolors, linetypes, linewidths, markercolors, markertypes, markersizes, strings, scratched=None, stringscolors=None, stacking='horizontal', bg=False, render=True, smallestfontsize=None, backgroundcolor=None)

Draws a legend with line/marker/text inside a template legend box. Auto adjusts text size to make it fit inside the box. Auto arranges the elements to fill the box nicely.

Example

>>> x = vcs.init()
>>> t = vcs.createtemplate()
>>> l_colors=["red","blue","green"]
>>> l_types=["solid","dash","dot"]
>>> l_widths=[1,4,8]
>>> m_colors=["blue","green","red"]
>>> m_types=["cross","square","dot"]
>>> m_sizes=[3,4,5]
>>> strings=["sample A","type B","thing C"]
>>> scratch=[True,False,True]
>>> t.drawLinesAndMarkersLegend(x, l_colors, l_types, l_widths,
...     m_colors, m_types, m_sizes, strings, scratch)
>>> x.png("sample")

Parameters

• canvas (vcs.Canvas.Canvas) – a VCS canvas object onto which to draw the legend

• linecolors (list) – A list containing the colors of each line to draw. Colors are represented as either an int from 0-255, an rgba tuple, or a string color name.

• linetypes (list) – A list containing the type of each line to draw. Line types are represented as either integers or strings. See vcs.line.Tl for more information.

• linewidths (list) – A list containing floats each representing the width of each line.

• markercolors (list) – A list of the markers colors to draw. Colors are represented as either an int from 0-255, an rgba tuple, or a string color name.

• markertypes (list) – A list of the marker types to draw. Marker types are represented as either integers or strings. See vcs.marker.Tm for more information.

• markersizes (list) – A list of floats representing marker sizes.

• strings (list) – A list of strings to draw next to each line/marker.

• scratched (None or list) –

  A list indicating which strings should be “scratched” off in the template.

  To “scratch” a string, the corresponding location in the scratched list must contain either True or the line type to use for the scratch. A value of False at a given index will leave the corresponding index of strings untouched.

  Size of the scratched list must be equal to the size of the strings list.

  Scratch color will match that of text.

  If scratched is None, or is not provided, no strings will be scratched.

• stringscolors (`string`_) – A list of the strings colors to draw. Colors are represented as either an int from 0-255, an rgba tuple, or a string color name.

• stacking – Prefered direction to stack element (‘horizontal’ or ‘vertical’)

• bg (bool) – Boolean value indicating whether or not to draw in the background. Defaults to False.

• render (bool) – Boolean value indicating whether or not to render. Defaults to True.

• smallestfontsize – Integer value indicating the smallest font size we can use for rendering None means no limit, 0 means use original size. Downscaling will still be used by algorigthm to try to fit everything in the legend box.

• backgroundcolor (list) – A list indicating the background color of the legended box. Colors are represented as either an int from 0-255, an rgba tuple, or a string color name.

drawTicks(slab, gm, x, axis, number, vp, wc, bg=False, X=None, Y=None, mintic=False, **kargs)

Draws the ticks for the axis x number number using the label passed by the graphic method vp and wc are from the actual canvas, they have been reset when they get here…

list(single=None)

Lists the current values of object attributes

Example

>>> a=vcs.init()
>>> obj=a.gettemplate() # default
>>> obj.list() # print template attributes
---------- ... ----------
...

param single

String value indicating which properties to list

type single

str

move(p, axis)

Move a template by p% along the axis ‘x’ or ‘y’. Positive values of p mean movement toward right/top Negative values of p mean movement toward left/bottom The reference point is t.data.x1/y1

Example

>>> t=vcs.createtemplate('t_move') # inherits default template
>>> t.move(0.2,'x') # Move everything right by 20%
>>> t.move(0.2,'y') # Move everything up by 20%

Parameters

• p (float) – Float indicating the percentage by which the template should move. i.e. 0.2 = 20%.

• axis (str) – The axis on which the template will move. One of [‘x’, ‘y’].

moveto(x, y)

Move a template to point (x,y), adjusting all attributes so data.x1 = x, and data.y1 = y.

Example

>>> t=vcs.createtemplate('t_move2') # inherits default template
>>> t.moveto(0.2, 0.2) # Move template so x1 and y1 are 0.2

Parameters

• x (float) – Float representing the new coordinate of the template’s data.x1 attribute.

• y (float) – Float representing the new coordinate of the template’s data.y1 attribute.

ratio(Rwished, Rout=None, box_and_ticks=True, x=None)

Computes ratio to shrink the data area of a template to have an y/x ratio of Rwished has the least possible deformation in linear projection

Example

>>> t=vcs.gettemplate()
>>> t.ratio(2) # y is twice x

Parameters

• Rwished (float or int) – Ratio y/x wished. Rwished MUST be provided.

• Rout (str or None) – Ratio of output (default is SCREEN). Also you can pass a string: “A4”,”US LETTER”, “X”/”SCREEN”, the latest uses the window information box_and_ticks: Also redefine box and ticks to the new region

• box_and_ticks (int or bool) – Also scale the boxes and ticks default True

Returns

vcs template object

Return type

vcs.template.P

ratio_linear_projection(lon1, lon2, lat1, lat2, Rwished=None, Rout=None, box_and_ticks=0, x=None)

Computes ratio to shrink the data area of a template such that the overall area has the least possible deformation in linear projection

Note

lon1/lon2 must be specified in degrees east. lat1/lat2 must be specified in degrees north.

Example

>>> t=vcs.gettemplate()
>>> t.ratio_linear_projection(-135,-50,20,50) # USA

Parameters

• lon1 (float or int) – Start longitude for plot.

• lon2 (float or int) – End longitude for plot

• lat1 (float or int) – Start latitude for plot.

• lat2 (float or int) – End latitude for plot

• Rwished (float or int) – Ratio y/x wished. If None, ratio will be determined automatically.

• Rout (float or int) – Ratio of output (default is US Letter=11./8.5) Also you can pass a string: “A4”,”US LETTER”, “X”/”SCREEN”, the latest uses the window information box_and_ticks: Also redefine box and ticks to the new region. If None, Rout will be determined automatically.

reset(sub_name, v1, v2, ov1=None, ov2=None)

This function resets all the attributes having a sub-attribute with the specified name.

Note

Respect how far from original position you are i.e. if you move to x1,x2 from old_x1, old_x2 if your current x1 value is not == to old_x1_value, then respect how far from it you were

Example

>>> t=vcs.createtemplate('t_reset') # inherits from 'default'
>>> data, data2 = t.data.x1, t.data.x2
>>> t.reset('x',0.15,0.5,data,data2) # Set x1 to 0.15, x2 to 0.5

Parameters

• sub_name (str) – String indicating the name of the sub-attribute to be reset. For example, sub_name=’x’ would cause the x1 ans x2 attributes to be set.

• v1 (float) – Float value to used to set the sub_name1 attribute.

• v2 (float) – Float value used to set the sub_name2 attribute.

• ov1 (float) – Float value of the old sub-name1 attribute value. Used to compute an offset ratio.

• ov2 (float) – Float value of the old sub-name1 attribute value. Used to compute an offset ratio.

scale(scale, axis='xy', font=- 1)

Scale a template along the axis ‘x’ or ‘y’ by scale Values of scale greater than 1. mean increase. The reference point is the template’s x1 and y1 data.

Example

>>> t=vcs.createtemplate('t_scale') # inherits default template
>>> t.scale(0.5) # Halves the template size
>>> t.scale(1.2) # Increases size by 20%
>>> t.scale(2,'x') # Double the x axis

Parameters

• scale (float) – Float representing the factor by which to scale the template.

• axis (str) – One of [‘x’, ‘y’, ‘xy’]. Represents the axis/axes along which the template should be scaled.

• font (int) – Integer flag indicating what should be done with the template’s fonts. One of [-1, 0, 1]. 0: means do not scale the fonts. 1: means scale the fonts. -1: means do not scale the fonts unless axis=’xy’

scalefont(scale)

Scales the template font by scale.

Example

>>> t=vcs.createtemplate('t_scfnt') # inherits default template
>>> t.scalefont(0.5) # reduces the fonts size by 2

Parameters

scale (float) – Float representing the factor by which to scale the template’s font size.

script(script_filename=None, mode=None)

Saves out a copy of the template 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

>>> a=vcs.init()
>>> ex=a.gettemplate()
>>> 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.

vcs.template.applyFormat(value, format)

For template object that have a ‘format’ associated, formats the value appropriately formats described at: http://pyformat.io

Example

>>> a=vcs.init(bg=True)
>>> template =vcs.gettemplate()
>>> vcs.template.applyFormat(3.45,template.mean.format)
'3.45'

param value

Input to be formatted

type fnm

float or int or str or `object`_

param format

Format to use.

type format

str

return

A string with formatted representation of value

rtype

str