diff --git a/.gitignore b/.gitignore index d4585a764..3904b30e2 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ *.egg-info build/ docs/_build +docs/doctest_info/ dist/ .idea/ dist/ diff --git a/docs/API/Canvas.rst b/docs/API/Canvas/Canvas.rst similarity index 100% rename from docs/API/Canvas.rst rename to docs/API/Canvas/Canvas.rst diff --git a/docs/API/README.md b/docs/API/README.md new file mode 100644 index 000000000..8fe633a62 --- /dev/null +++ b/docs/API/README.md @@ -0,0 +1,4 @@ +Note: +----- + +Run `build_func_index.py` every once in a while to make sure the VCS function index is being updated diff --git a/docs/API/build_func_index.py b/docs/API/build_func_index.py new file mode 100644 index 000000000..ab95b14af --- /dev/null +++ b/docs/API/build_func_index.py @@ -0,0 +1,30 @@ +import vcs, inspect + +# VCS objects to generate function references for. Some are modules, some are classes. +# Probably will need to add to this later when there's more documentation +objects = [vcs.boxfill.Gfb, vcs.Canvas.Canvas, vcs.colormap.Cp, vcs.fillarea.Tf, vcs.isofill.Gfi, vcs.isoline.Gi, + vcs.line.Tl, vcs.marker.Tm, vcs.meshfill.Gfm, vcs.projection.Proj, vcs.taylor.Gtd, vcs.template.P, + vcs.textcombined.Tc,vcs.textorientation.To, vcs.texttable.Tt, vcs.unified1D.G1d, vcs.vector.Gv, + vcs.manageElements, vcs.queries, vcs.utils, vcs.animate_helper, vcs.dv3d, vcs.colors, vcs.displayplot.Dp, + vcs.vcshelp, ] + +# iterate through objects to find the functions of each, and write RST links for those out to +# API/functions/$MODULE_NAME.rst +for obj in objects: + if inspect.isclass(obj): + key = obj.__module__ + '.' + obj.__name__ + pred = inspect.ismethod + else: + key = obj.__name__ + pred = inspect.isfunction + funcs = [] + tup_l = inspect.getmembers(obj, predicate=pred) + for tup in tup_l: + if not tup[0][0] == '_': + funcs.append(':func:`' + key + '.' + tup[0] + '`\n\n') + fname = key.split('.')[1] + with open('functions/' + fname + ".rst", "w+") as f: + f.write(fname + "\n") + map(lambda x: f.write('-'), range(len(fname))) + f.write("\n\n") + f.writelines(funcs) diff --git a/docs/API/functions/Canvas.rst b/docs/API/functions/Canvas.rst new file mode 100644 index 000000000..218204d91 --- /dev/null +++ b/docs/API/functions/Canvas.rst @@ -0,0 +1,307 @@ +Canvas +------ + +:func:`vcs.Canvas.Canvas.addfont` + +:func:`vcs.Canvas.Canvas.boxfill` + +:func:`vcs.Canvas.Canvas.canvasid` + +:func:`vcs.Canvas.Canvas.canvasinfo` + +:func:`vcs.Canvas.Canvas.cgm` + +:func:`vcs.Canvas.Canvas.change_display_graphic_method` + +:func:`vcs.Canvas.Canvas.check_name_source` + +:func:`vcs.Canvas.Canvas.clean_auto_generated_objects` + +:func:`vcs.Canvas.Canvas.clear` + +:func:`vcs.Canvas.Canvas.close` + +:func:`vcs.Canvas.Canvas.configure` + +:func:`vcs.Canvas.Canvas.copyfontto` + +:func:`vcs.Canvas.Canvas.create1d` + +:func:`vcs.Canvas.Canvas.create3d_dual_scalar` + +:func:`vcs.Canvas.Canvas.create3d_scalar` + +:func:`vcs.Canvas.Canvas.create3d_vector` + +:func:`vcs.Canvas.Canvas.createboxfill` + +:func:`vcs.Canvas.Canvas.createcolormap` + +:func:`vcs.Canvas.Canvas.createfillarea` + +:func:`vcs.Canvas.Canvas.createisofill` + +:func:`vcs.Canvas.Canvas.createisoline` + +:func:`vcs.Canvas.Canvas.createline` + +:func:`vcs.Canvas.Canvas.createmarker` + +:func:`vcs.Canvas.Canvas.createmeshfill` + +:func:`vcs.Canvas.Canvas.createprojection` + +:func:`vcs.Canvas.Canvas.createscatter` + +:func:`vcs.Canvas.Canvas.createtaylordiagram` + +:func:`vcs.Canvas.Canvas.createtemplate` + +:func:`vcs.Canvas.Canvas.createtext` + +:func:`vcs.Canvas.Canvas.createtextcombined` + +:func:`vcs.Canvas.Canvas.createtextorientation` + +:func:`vcs.Canvas.Canvas.createtexttable` + +:func:`vcs.Canvas.Canvas.createvector` + +:func:`vcs.Canvas.Canvas.createxvsy` + +:func:`vcs.Canvas.Canvas.createxyvsy` + +:func:`vcs.Canvas.Canvas.createyxvsx` + +:func:`vcs.Canvas.Canvas.destroy` + +:func:`vcs.Canvas.Canvas.drawfillarea` + +:func:`vcs.Canvas.Canvas.drawline` + +:func:`vcs.Canvas.Canvas.drawlogooff` + +:func:`vcs.Canvas.Canvas.drawlogoon` + +:func:`vcs.Canvas.Canvas.drawmarker` + +:func:`vcs.Canvas.Canvas.drawtext` + +:func:`vcs.Canvas.Canvas.drawtextcombined` + +:func:`vcs.Canvas.Canvas.dual_scalar3d` + +:func:`vcs.Canvas.Canvas.dummy_user_action` + +:func:`vcs.Canvas.Canvas.endconfigure` + +:func:`vcs.Canvas.Canvas.eps` + +:func:`vcs.Canvas.Canvas.ffmpeg` + +:func:`vcs.Canvas.Canvas.fillarea` + +:func:`vcs.Canvas.Canvas.flush` + +:func:`vcs.Canvas.Canvas.geometry` + +:func:`vcs.Canvas.Canvas.get1d` + +:func:`vcs.Canvas.Canvas.get3d_dual_scalar` + +:func:`vcs.Canvas.Canvas.get3d_scalar` + +:func:`vcs.Canvas.Canvas.get3d_vector` + +:func:`vcs.Canvas.Canvas.get_selected_display` + +:func:`vcs.Canvas.Canvas.getantialiasing` + +:func:`vcs.Canvas.Canvas.getboxfill` + +:func:`vcs.Canvas.Canvas.getcolorcell` + +:func:`vcs.Canvas.Canvas.getcolormap` + +:func:`vcs.Canvas.Canvas.getcolormapname` + +:func:`vcs.Canvas.Canvas.getcontinentsline` + +:func:`vcs.Canvas.Canvas.getcontinentstype` + +:func:`vcs.Canvas.Canvas.getdrawlogo` + +:func:`vcs.Canvas.Canvas.getfillarea` + +:func:`vcs.Canvas.Canvas.getfont` + +:func:`vcs.Canvas.Canvas.getfontname` + +:func:`vcs.Canvas.Canvas.getfontnumber` + +:func:`vcs.Canvas.Canvas.getisofill` + +:func:`vcs.Canvas.Canvas.getisoline` + +:func:`vcs.Canvas.Canvas.getline` + +:func:`vcs.Canvas.Canvas.getmarker` + +:func:`vcs.Canvas.Canvas.getmeshfill` + +:func:`vcs.Canvas.Canvas.getplot` + +:func:`vcs.Canvas.Canvas.getprojection` + +:func:`vcs.Canvas.Canvas.getscatter` + +:func:`vcs.Canvas.Canvas.gettaylordiagram` + +:func:`vcs.Canvas.Canvas.gettemplate` + +:func:`vcs.Canvas.Canvas.gettext` + +:func:`vcs.Canvas.Canvas.gettextcombined` + +:func:`vcs.Canvas.Canvas.gettextextent` + +:func:`vcs.Canvas.Canvas.gettextorientation` + +:func:`vcs.Canvas.Canvas.gettexttable` + +:func:`vcs.Canvas.Canvas.getvector` + +:func:`vcs.Canvas.Canvas.getxvsy` + +:func:`vcs.Canvas.Canvas.getxyvsy` + +:func:`vcs.Canvas.Canvas.getyxvsx` + +:func:`vcs.Canvas.Canvas.gif` + +:func:`vcs.Canvas.Canvas.grid` + +:func:`vcs.Canvas.Canvas.gs` + +:func:`vcs.Canvas.Canvas.initLogoDrawing` + +:func:`vcs.Canvas.Canvas.interact` + +:func:`vcs.Canvas.Canvas.isinfile` + +:func:`vcs.Canvas.Canvas.islandscape` + +:func:`vcs.Canvas.Canvas.isofill` + +:func:`vcs.Canvas.Canvas.isoline` + +:func:`vcs.Canvas.Canvas.isopened` + +:func:`vcs.Canvas.Canvas.isportrait` + +:func:`vcs.Canvas.Canvas.landscape` + +:func:`vcs.Canvas.Canvas.line` + +:func:`vcs.Canvas.Canvas.listelements` + +:func:`vcs.Canvas.Canvas.marker` + +:func:`vcs.Canvas.Canvas.match_color` + +:func:`vcs.Canvas.Canvas.meshfill` + +:func:`vcs.Canvas.Canvas.objecthelp` + +:func:`vcs.Canvas.Canvas.onClosing` + +:func:`vcs.Canvas.Canvas.open` + +:func:`vcs.Canvas.Canvas.orientation` + +:func:`vcs.Canvas.Canvas.pdf` + +:func:`vcs.Canvas.Canvas.plot` + +:func:`vcs.Canvas.Canvas.plot_annotation` + +:func:`vcs.Canvas.Canvas.plot_filledcontinents` + +:func:`vcs.Canvas.Canvas.png` + +:func:`vcs.Canvas.Canvas.portrait` + +:func:`vcs.Canvas.Canvas.postscript` + +:func:`vcs.Canvas.Canvas.processParameterChange` + +:func:`vcs.Canvas.Canvas.pstogif` + +:func:`vcs.Canvas.Canvas.put_png_on_canvas` + +:func:`vcs.Canvas.Canvas.raisecanvas` + +:func:`vcs.Canvas.Canvas.removeP` + +:func:`vcs.Canvas.Canvas.remove_display_name` + +:func:`vcs.Canvas.Canvas.removeobject` + +:func:`vcs.Canvas.Canvas.return_display_names` + +:func:`vcs.Canvas.Canvas.savecontinentstype` + +:func:`vcs.Canvas.Canvas.saveinitialfile` + +:func:`vcs.Canvas.Canvas.scalar3d` + +:func:`vcs.Canvas.Canvas.scatter` + +:func:`vcs.Canvas.Canvas.scriptobject` + +:func:`vcs.Canvas.Canvas.scriptrun` + +:func:`vcs.Canvas.Canvas.setAnimationStepper` + +:func:`vcs.Canvas.Canvas.setantialiasing` + +:func:`vcs.Canvas.Canvas.setbgoutputdimensions` + +:func:`vcs.Canvas.Canvas.setcolorcell` + +:func:`vcs.Canvas.Canvas.setcolormap` + +:func:`vcs.Canvas.Canvas.setcontinentsline` + +:func:`vcs.Canvas.Canvas.setcontinentstype` + +:func:`vcs.Canvas.Canvas.setdefaultfont` + +:func:`vcs.Canvas.Canvas.show` + +:func:`vcs.Canvas.Canvas.start` + +:func:`vcs.Canvas.Canvas.svg` + +:func:`vcs.Canvas.Canvas.switchfonts` + +:func:`vcs.Canvas.Canvas.taylordiagram` + +:func:`vcs.Canvas.Canvas.text` + +:func:`vcs.Canvas.Canvas.textcombined` + +:func:`vcs.Canvas.Canvas.update` + +:func:`vcs.Canvas.Canvas.updateorientation` + +:func:`vcs.Canvas.Canvas.vector` + +:func:`vcs.Canvas.Canvas.vector3d` + +:func:`vcs.Canvas.Canvas.xvsy` + +:func:`vcs.Canvas.Canvas.xyvsy` + +:func:`vcs.Canvas.Canvas.yxvsx` + diff --git a/docs/API/functions/animate_helper.rst b/docs/API/functions/animate_helper.rst new file mode 100644 index 000000000..cccb12f79 --- /dev/null +++ b/docs/API/functions/animate_helper.rst @@ -0,0 +1,5 @@ +animate_helper +-------------- + +:func:`vcs.animate_helper.showerror` + diff --git a/docs/API/functions/boxfill.rst b/docs/API/functions/boxfill.rst new file mode 100644 index 000000000..8038bf79a --- /dev/null +++ b/docs/API/functions/boxfill.rst @@ -0,0 +1,29 @@ +boxfill +------- + +:func:`vcs.boxfill.Gfb.colors` + +:func:`vcs.boxfill.Gfb.datawc` + +:func:`vcs.boxfill.Gfb.exts` + +:func:`vcs.boxfill.Gfb.getlegendlabels` + +:func:`vcs.boxfill.Gfb.getlevels` + +:func:`vcs.boxfill.Gfb.list` + +:func:`vcs.boxfill.Gfb.rename` + +:func:`vcs.boxfill.Gfb.script` + +:func:`vcs.boxfill.Gfb.xmtics` + +:func:`vcs.boxfill.Gfb.xticlabels` + +:func:`vcs.boxfill.Gfb.xyscale` + +:func:`vcs.boxfill.Gfb.ymtics` + +:func:`vcs.boxfill.Gfb.yticlabels` + diff --git a/docs/API/functions/colormap.rst b/docs/API/functions/colormap.rst new file mode 100644 index 000000000..8bdedb36f --- /dev/null +++ b/docs/API/functions/colormap.rst @@ -0,0 +1,19 @@ +colormap +-------- + +:func:`vcs.colormap.Cp.getcolorcell` + +:func:`vcs.colormap.Cp.getindex` + +:func:`vcs.colormap.Cp.getname` + +:func:`vcs.colormap.Cp.list` + +:func:`vcs.colormap.Cp.script` + +:func:`vcs.colormap.Cp.setcolorcell` + +:func:`vcs.colormap.Cp.setindex` + +:func:`vcs.colormap.Cp.setname` + diff --git a/docs/API/functions/colors.rst b/docs/API/functions/colors.rst new file mode 100644 index 000000000..14d9d3209 --- /dev/null +++ b/docs/API/functions/colors.rst @@ -0,0 +1,9 @@ +colors +------ + +:func:`vcs.colors.matplotlib2vcs` + +:func:`vcs.colors.rgb2str` + +:func:`vcs.colors.str2rgb` + diff --git a/docs/API/functions/displayplot.rst b/docs/API/functions/displayplot.rst new file mode 100644 index 000000000..498a35b9d --- /dev/null +++ b/docs/API/functions/displayplot.rst @@ -0,0 +1,5 @@ +displayplot +----------- + +:func:`vcs.displayplot.Dp.list` + diff --git a/docs/API/functions/dv3d.rst b/docs/API/functions/dv3d.rst new file mode 100644 index 000000000..5d3ad3245 --- /dev/null +++ b/docs/API/functions/dv3d.rst @@ -0,0 +1,3 @@ +dv3d +---- + diff --git a/docs/API/functions/fillarea.rst b/docs/API/functions/fillarea.rst new file mode 100644 index 000000000..a7150d712 --- /dev/null +++ b/docs/API/functions/fillarea.rst @@ -0,0 +1,7 @@ +fillarea +-------- + +:func:`vcs.fillarea.Tf.list` + +:func:`vcs.fillarea.Tf.script` + diff --git a/docs/API/functions/index.rst b/docs/API/functions/index.rst new file mode 100644 index 000000000..0f4c927b8 --- /dev/null +++ b/docs/API/functions/index.rst @@ -0,0 +1,30 @@ +Index of VCS functions +---------------------- + +.. toctree:: + + Canvas + boxfill + dv3d + isofill + isoline + meshfill + taylor + unified1D + vector + animate_helper + colors + queries + vcshelp + colormap + displayplot + manageElements + projection + utils + fillarea + line + marker + textcombined + textorientation + texttable + template \ No newline at end of file diff --git a/docs/API/functions/isofill.rst b/docs/API/functions/isofill.rst new file mode 100644 index 000000000..3cf86bc1c --- /dev/null +++ b/docs/API/functions/isofill.rst @@ -0,0 +1,23 @@ +isofill +------- + +:func:`vcs.isofill.Gfi.colors` + +:func:`vcs.isofill.Gfi.datawc` + +:func:`vcs.isofill.Gfi.exts` + +:func:`vcs.isofill.Gfi.list` + +:func:`vcs.isofill.Gfi.script` + +:func:`vcs.isofill.Gfi.xmtics` + +:func:`vcs.isofill.Gfi.xticlabels` + +:func:`vcs.isofill.Gfi.xyscale` + +:func:`vcs.isofill.Gfi.ymtics` + +:func:`vcs.isofill.Gfi.yticlabels` + diff --git a/docs/API/functions/isoline.rst b/docs/API/functions/isoline.rst new file mode 100644 index 000000000..f2063e80e --- /dev/null +++ b/docs/API/functions/isoline.rst @@ -0,0 +1,21 @@ +isoline +------- + +:func:`vcs.isoline.Gi.datawc` + +:func:`vcs.isoline.Gi.list` + +:func:`vcs.isoline.Gi.script` + +:func:`vcs.isoline.Gi.setLineAttributes` + +:func:`vcs.isoline.Gi.xmtics` + +:func:`vcs.isoline.Gi.xticlabels` + +:func:`vcs.isoline.Gi.xyscale` + +:func:`vcs.isoline.Gi.ymtics` + +:func:`vcs.isoline.Gi.yticlabels` + diff --git a/docs/API/functions/line.rst b/docs/API/functions/line.rst new file mode 100644 index 000000000..05989a944 --- /dev/null +++ b/docs/API/functions/line.rst @@ -0,0 +1,7 @@ +line +---- + +:func:`vcs.line.Tl.list` + +:func:`vcs.line.Tl.script` + diff --git a/docs/API/functions/manageElements.rst b/docs/API/functions/manageElements.rst new file mode 100644 index 000000000..d29812d1b --- /dev/null +++ b/docs/API/functions/manageElements.rst @@ -0,0 +1,147 @@ +manageElements +-------------- + +:func:`vcs.manageElements.check_name_source` + +:func:`vcs.manageElements.create1d` + +:func:`vcs.manageElements.create3d_dual_scalar` + +:func:`vcs.manageElements.create3d_scalar` + +:func:`vcs.manageElements.create3d_vector` + +:func:`vcs.manageElements.createboxfill` + +:func:`vcs.manageElements.createcolormap` + +:func:`vcs.manageElements.createfillarea` + +:func:`vcs.manageElements.createisofill` + +:func:`vcs.manageElements.createisoline` + +:func:`vcs.manageElements.createline` + +:func:`vcs.manageElements.createmarker` + +:func:`vcs.manageElements.createmeshfill` + +:func:`vcs.manageElements.createprojection` + +:func:`vcs.manageElements.createscatter` + +:func:`vcs.manageElements.createtaylordiagram` + +:func:`vcs.manageElements.createtemplate` + +:func:`vcs.manageElements.createtext` + +:func:`vcs.manageElements.createtextcombined` + +:func:`vcs.manageElements.createtextorientation` + +:func:`vcs.manageElements.createtexttable` + +:func:`vcs.manageElements.createvector` + +:func:`vcs.manageElements.createxvsy` + +:func:`vcs.manageElements.createxyvsy` + +:func:`vcs.manageElements.createyxvsx` + +:func:`vcs.manageElements.get1d` + +:func:`vcs.manageElements.get3d_dual_scalar` + +:func:`vcs.manageElements.get3d_scalar` + +:func:`vcs.manageElements.get3d_vector` + +:func:`vcs.manageElements.getboxfill` + +:func:`vcs.manageElements.getcolormap` + +:func:`vcs.manageElements.getfillarea` + +:func:`vcs.manageElements.getisofill` + +:func:`vcs.manageElements.getisoline` + +:func:`vcs.manageElements.getline` + +:func:`vcs.manageElements.getmarker` + +:func:`vcs.manageElements.getmeshfill` + +:func:`vcs.manageElements.getprojection` + +:func:`vcs.manageElements.getscatter` + +:func:`vcs.manageElements.gettaylordiagram` + +:func:`vcs.manageElements.gettemplate` + +:func:`vcs.manageElements.gettext` + +:func:`vcs.manageElements.gettextcombined` + +:func:`vcs.manageElements.gettextorientation` + +:func:`vcs.manageElements.gettexttable` + +:func:`vcs.manageElements.getvector` + +:func:`vcs.manageElements.getxvsy` + +:func:`vcs.manageElements.getxyvsy` + +:func:`vcs.manageElements.getyxvsx` + +:func:`vcs.manageElements.removeCp` + +:func:`vcs.manageElements.removeG` + +:func:`vcs.manageElements.removeG1d` + +:func:`vcs.manageElements.removeGSp` + +:func:`vcs.manageElements.removeGXY` + +:func:`vcs.manageElements.removeGXy` + +:func:`vcs.manageElements.removeGYx` + +:func:`vcs.manageElements.removeGfb` + +:func:`vcs.manageElements.removeGfi` + +:func:`vcs.manageElements.removeGfm` + +:func:`vcs.manageElements.removeGi` + +:func:`vcs.manageElements.removeGtd` + +:func:`vcs.manageElements.removeGv` + +:func:`vcs.manageElements.removeP` + +:func:`vcs.manageElements.removeProj` + +:func:`vcs.manageElements.removeTc` + +:func:`vcs.manageElements.removeTf` + +:func:`vcs.manageElements.removeTl` + +:func:`vcs.manageElements.removeTm` + +:func:`vcs.manageElements.removeTo` + +:func:`vcs.manageElements.removeTt` + +:func:`vcs.manageElements.removeobject` + +:func:`vcs.manageElements.setLineAttributes` + diff --git a/docs/API/functions/marker.rst b/docs/API/functions/marker.rst new file mode 100644 index 000000000..18e64b6f6 --- /dev/null +++ b/docs/API/functions/marker.rst @@ -0,0 +1,7 @@ +marker +------ + +:func:`vcs.marker.Tm.list` + +:func:`vcs.marker.Tm.script` + diff --git a/docs/API/functions/meshfill.rst b/docs/API/functions/meshfill.rst new file mode 100644 index 000000000..bc5c2a15f --- /dev/null +++ b/docs/API/functions/meshfill.rst @@ -0,0 +1,23 @@ +meshfill +-------- + +:func:`vcs.meshfill.Gfm.colors` + +:func:`vcs.meshfill.Gfm.datawc` + +:func:`vcs.meshfill.Gfm.exts` + +:func:`vcs.meshfill.Gfm.list` + +:func:`vcs.meshfill.Gfm.script` + +:func:`vcs.meshfill.Gfm.xmtics` + +:func:`vcs.meshfill.Gfm.xticlabels` + +:func:`vcs.meshfill.Gfm.xyscale` + +:func:`vcs.meshfill.Gfm.ymtics` + +:func:`vcs.meshfill.Gfm.yticlabels` + diff --git a/docs/API/functions/projection.rst b/docs/API/functions/projection.rst new file mode 100644 index 000000000..60aaade9d --- /dev/null +++ b/docs/API/functions/projection.rst @@ -0,0 +1,9 @@ +projection +---------- + +:func:`vcs.projection.Proj.checkPP` + +:func:`vcs.projection.Proj.list` + +:func:`vcs.projection.Proj.script` + diff --git a/docs/API/functions/queries.rst b/docs/API/functions/queries.rst new file mode 100644 index 000000000..a64b9b93d --- /dev/null +++ b/docs/API/functions/queries.rst @@ -0,0 +1,61 @@ +queries +------- + +:func:`vcs.queries.graphicsmethodlist` + +:func:`vcs.queries.graphicsmethodtype` + +:func:`vcs.queries.is1d` + +:func:`vcs.queries.is3d_dual_scalar` + +:func:`vcs.queries.is3d_scalar` + +:func:`vcs.queries.is3d_vector` + +:func:`vcs.queries.isboxfill` + +:func:`vcs.queries.iscolormap` + +:func:`vcs.queries.isfillarea` + +:func:`vcs.queries.isgraphicsmethod` + +:func:`vcs.queries.isisofill` + +:func:`vcs.queries.isisoline` + +:func:`vcs.queries.isline` + +:func:`vcs.queries.ismarker` + +:func:`vcs.queries.ismeshfill` + +:func:`vcs.queries.isplot` + +:func:`vcs.queries.isprojection` + +:func:`vcs.queries.isscatter` + +:func:`vcs.queries.issecondaryobject` + +:func:`vcs.queries.istaylordiagram` + +:func:`vcs.queries.istemplate` + +:func:`vcs.queries.istext` + +:func:`vcs.queries.istextcombined` + +:func:`vcs.queries.istextorientation` + +:func:`vcs.queries.istexttable` + +:func:`vcs.queries.isvector` + +:func:`vcs.queries.isxvsy` + +:func:`vcs.queries.isxyvsy` + +:func:`vcs.queries.isyxvsx` + diff --git a/docs/API/functions/taylor.rst b/docs/API/functions/taylor.rst new file mode 100644 index 000000000..1fa1d89a0 --- /dev/null +++ b/docs/API/functions/taylor.rst @@ -0,0 +1,29 @@ +taylor +------ + +:func:`vcs.taylor.Gtd.addMarker` + +:func:`vcs.taylor.Gtd.convert` + +:func:`vcs.taylor.Gtd.defaultSkillFunction` + +:func:`vcs.taylor.Gtd.draw` + +:func:`vcs.taylor.Gtd.drawFrame` + +:func:`vcs.taylor.Gtd.drawSkill` + +:func:`vcs.taylor.Gtd.drawarrow` + +:func:`vcs.taylor.Gtd.getArc` + +:func:`vcs.taylor.Gtd.list` + +:func:`vcs.taylor.Gtd.plot` + +:func:`vcs.taylor.Gtd.rename` + +:func:`vcs.taylor.Gtd.script` + +:func:`vcs.taylor.Gtd.setWorldCoordinate` + diff --git a/docs/API/functions/template.rst b/docs/API/functions/template.rst new file mode 100644 index 000000000..8d81cb16a --- /dev/null +++ b/docs/API/functions/template.rst @@ -0,0 +1,33 @@ +template +-------- + +:func:`vcs.template.P.blank` + +:func:`vcs.template.P.drawAttributes` + +:func:`vcs.template.P.drawColorBar` + +:func:`vcs.template.P.drawLinesAndMarkersLegend` + +:func:`vcs.template.P.drawTicks` + +:func:`vcs.template.P.list` + +:func:`vcs.template.P.move` + +:func:`vcs.template.P.moveto` + +:func:`vcs.template.P.plot` + +:func:`vcs.template.P.ratio` + +:func:`vcs.template.P.ratio_linear_projection` + +:func:`vcs.template.P.reset` + +:func:`vcs.template.P.scale` + +:func:`vcs.template.P.scalefont` + +:func:`vcs.template.P.script` + diff --git a/docs/API/functions/textcombined.rst b/docs/API/functions/textcombined.rst new file mode 100644 index 000000000..e6005b9c2 --- /dev/null +++ b/docs/API/functions/textcombined.rst @@ -0,0 +1,7 @@ +textcombined +------------ + +:func:`vcs.textcombined.Tc.list` + +:func:`vcs.textcombined.Tc.script` + diff --git a/docs/API/functions/textorientation.rst b/docs/API/functions/textorientation.rst new file mode 100644 index 000000000..952321c7f --- /dev/null +++ b/docs/API/functions/textorientation.rst @@ -0,0 +1,7 @@ +textorientation +--------------- + +:func:`vcs.textorientation.To.list` + +:func:`vcs.textorientation.To.script` + diff --git a/docs/API/functions/texttable.rst b/docs/API/functions/texttable.rst new file mode 100644 index 000000000..24a7e6d68 --- /dev/null +++ b/docs/API/functions/texttable.rst @@ -0,0 +1,7 @@ +texttable +--------- + +:func:`vcs.texttable.Tt.list` + +:func:`vcs.texttable.Tt.script` + diff --git a/docs/API/functions/unified1D.rst b/docs/API/functions/unified1D.rst new file mode 100644 index 000000000..75d07ac5f --- /dev/null +++ b/docs/API/functions/unified1D.rst @@ -0,0 +1,19 @@ +unified1D +--------- + +:func:`vcs.unified1D.G1d.datawc` + +:func:`vcs.unified1D.G1d.list` + +:func:`vcs.unified1D.G1d.script` + +:func:`vcs.unified1D.G1d.setLineAttributes` + +:func:`vcs.unified1D.G1d.xmtics` + +:func:`vcs.unified1D.G1d.xticlabels` + +:func:`vcs.unified1D.G1d.ymtics` + +:func:`vcs.unified1D.G1d.yticlabels` + diff --git a/docs/API/functions/utils.rst b/docs/API/functions/utils.rst new file mode 100644 index 000000000..5fa5bc354 --- /dev/null +++ b/docs/API/functions/utils.rst @@ -0,0 +1,83 @@ +utils +----- + +:func:`vcs.utils.creategraphicsmethod` + +:func:`vcs.utils.download_sample_data_files` + +:func:`vcs.utils.drawLinesAndMarkersLegend` + +:func:`vcs.utils.dumpToDict` + +:func:`vcs.utils.dumpToJson` + +:func:`vcs.utils.generate_time_labels` + +:func:`vcs.utils.getDataWcValue` + +:func:`vcs.utils.get_png_dims` + +:func:`vcs.utils.getcolorcell` + +:func:`vcs.utils.getcolormap` + +:func:`vcs.utils.getcolors` + +:func:`vcs.utils.getdotdirectory` + +:func:`vcs.utils.getfontname` + +:func:`vcs.utils.getfontnumber` + +:func:`vcs.utils.getgraphicsmethod` + +:func:`vcs.utils.getworldcoordinates` + +:func:`vcs.utils.listelements` + +:func:`vcs.utils.loadTemplate` + +:func:`vcs.utils.loadVCSItem` + +:func:`vcs.utils.match_color` + +:func:`vcs.utils.matplotlib2vcs` + +:func:`vcs.utils.minmax` + +:func:`vcs.utils.mkevenlevels` + +:func:`vcs.utils.mklabels` + +:func:`vcs.utils.mkscale` + +:func:`vcs.utils.monotonic` + +:func:`vcs.utils.png_read_metadata` + +:func:`vcs.utils.prettifyAxisLabels` + +:func:`vcs.utils.process_range_from_old_scr` + +:func:`vcs.utils.process_src_element` + +:func:`vcs.utils.return_display_names` + +:func:`vcs.utils.rgb2str` + +:func:`vcs.utils.rgba_color` + +:func:`vcs.utils.saveinitialfile` + +:func:`vcs.utils.scriptrun` + +:func:`vcs.utils.scriptrun_scr` + +:func:`vcs.utils.setTicksandLabels` + +:func:`vcs.utils.setcolorcell` + +:func:`vcs.utils.show` + +:func:`vcs.utils.str2rgb` + diff --git a/docs/API/functions/vcshelp.rst b/docs/API/functions/vcshelp.rst new file mode 100644 index 000000000..17409980c --- /dev/null +++ b/docs/API/functions/vcshelp.rst @@ -0,0 +1,11 @@ +vcshelp +------- + +:func:`vcs.vcshelp.help` + +:func:`vcs.vcshelp.help__doc__` + +:func:`vcs.vcshelp.mode__doc__` + +:func:`vcs.vcshelp.objecthelp` + diff --git a/docs/API/functions/vector.rst b/docs/API/functions/vector.rst new file mode 100644 index 000000000..c010d6c5d --- /dev/null +++ b/docs/API/functions/vector.rst @@ -0,0 +1,21 @@ +vector +------ + +:func:`vcs.vector.Gv.datawc` + +:func:`vcs.vector.Gv.list` + +:func:`vcs.vector.Gv.script` + +:func:`vcs.vector.Gv.setLineAttributes` + +:func:`vcs.vector.Gv.xmtics` + +:func:`vcs.vector.Gv.xticlabels` + +:func:`vcs.vector.Gv.xyscale` + +:func:`vcs.vector.Gv.ymtics` + +:func:`vcs.vector.Gv.yticlabels` + diff --git a/docs/API/graphics/dv3d.rst b/docs/API/graphics/dv3d.rst index 752bd53a4..571bf9325 100644 --- a/docs/API/graphics/dv3d.rst +++ b/docs/API/graphics/dv3d.rst @@ -1,4 +1,70 @@ -dv3d ----- +=================== +3D Graphics Methods +=================== + +Deriving actionable information from climate simulations requires the capacity to detect, compare, and analyze features +spanning large heterogeneous, multi-variate, multi-dimensional datasets with spatial and temporal references. The +brain’s capacity to detect visual patterns is invaluable in this knowledge discovery process. Visual mapping techniques +are very effective in expressing the results of feature detection and analysis algorithms as they naturally employ the +visual information processing capacity of the cerebral cortex, which is extremely difficult to emulate using statistical +and machine learning approaches alone. Visual representations, which play an important role in addressing data +complexity, can be enhanced by an increase in the number of “degrees of freedom” in the visual mapping process. +Interactive three-dimensional views into complex high dimensional datasets can offer a widened perspective and a more +comprehensive gestalt facilitating the recognition of significant features and the discovery of important patterns and +relationships in the climate knowledge discovery process. + + +3D Plot Constituents +-------------------- + +In the VCS model 3D perspectives are provided by the 3d_scalar and 3d_vector graphics methods. + +The 3d_scalar graphics method provides the :term:`Volume`, :term:`Surface`, and :term:`Slice` display +techniques (denoted henceforth as “plot constituents”). It can be used to display data in both the default (x-y-z) and +Hovmoller3D (x-y-t)geometries. + +The 3d_vector graphics method provides the :term:`Vector` slice plot constituent. + +.. glossary:: + + Volume + The Volume plot enables scientists to create an overview of the topology of the data, revealing complex 3D structures at + a glance. It is generated using a “transfer function” to linearly map an adjustable range of variable values to an + adjustable range of opacity values at each point of a 3D volume. Values of the variable that fall outside of the range + are invisible (transparent). In addition, the rendered color is determined by mapping the variable’s value at each point + of the volume to an adjustable range of colormap values. All three adjustable ranges can be configured either statically + using a script or interactively using sliders in an active plot window. + + Surface + The Surface plot can produce views similar to a volume rendering while facilitating the comparison of two variables. It + is displayed as an isosurface (the higher dimensional analog of an isoline or contour line on a weather or terrain map), + illustrating the surfaces of constant value for one variable and optionally colored by the spatially correspondent + values of a second variable. The rendered color is determined by mapping the second variable’s value at each point of + the surface to an adjustable range of colormap values. The isosurface value and the colormap range can be configured + either statically using a script or interactively using sliders in an active plot window. + + Slice + The Slice plot allows scientists to quickly and easily browse the 3D structure of a dataset, compare variables in 3D, + and probe data values. It provides a set of three slice planes (perpendicular to the x, y, and z axes) that can be + interactively dragged over the dataset. A slice through the data volume at the plane’s location is displayed by mapping + the variable’s value at each point of the plane to an adjustable range of colormap values. A slice through a second data + volume can also be overlaid as a contour map over the first. In an active plot window a shift-right-click on one of the + planes will display the coordinates and value of the variable(s) at that point. The slice positions and the colormap + range can be configured either statically using a script or interactively using sliders in an active plot window + + Vector + The Vector slice plot allows scientists to browse the 3D structure of variables (such as wind velocity) that have both + magnitude and direction. It provides a horizontal slice plane that can be interactively dragged over a vector field + dataset (consisting of a pair of variables denoting the X and Y components of a vector at each point). A slice through + the data volume at the plane’s location is displayed using a set of vector glyphs denoting the direction and magnitude + of the field at a regularly spaced set of points on the plane. The slice position and the density and scaling of the + vector glyphs can be configured either statically using a script or interactively using sliders in an active plot + window. + + .. note:: + + This display technique can be very computationally intensive so that the higher glyph densities may cause diminished + interactivity. + .. automodule:: vcs.dv3d :members: \ No newline at end of file diff --git a/docs/API/misc/misc.rst b/docs/API/misc/misc.rst index ae7a37768..ec1f15684 100644 --- a/docs/API/misc/misc.rst +++ b/docs/API/misc/misc.rst @@ -10,7 +10,6 @@ These are a variety of modules from VCS that help out with useful functionality. colormap colors displayplot - error manageElements queries utils diff --git a/docs/API/template/templ.rst b/docs/API/template/templ.rst index 3599b5b5b..702354e75 100644 --- a/docs/API/template/templ.rst +++ b/docs/API/template/templ.rst @@ -1,7 +1,8 @@ Templating ---------- -Templates define the layout of your visualization. The Template object is used to lay out labels, lines, tick marks, etc.; it uses the P* objects to do so. +Templates define the layout of your visualization. The Template object is used to lay out labels, lines, tick marks, etc.; +it uses the P* objects to do so. .. toctree:: diff --git a/docs/API/template/template.rst b/docs/API/template/template.rst index c31376e97..31a30f5fe 100644 --- a/docs/API/template/template.rst +++ b/docs/API/template/template.rst @@ -1,4 +1,5 @@ template -------- .. automodule:: vcs.template - :members: \ No newline at end of file + :members: + :exclude-members: plot, epsilon_gte, epsilon_lte \ No newline at end of file diff --git a/docs/API/vcs.rst b/docs/API/vcs.rst index 441e356e3..d5c120817 100644 --- a/docs/API/vcs.rst +++ b/docs/API/vcs.rst @@ -7,8 +7,9 @@ VCS API Documentation .. toctree:: - Canvas + Canvas/Canvas graphics/gm template/templ secondary/gms misc/misc + functions/index \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index cc3fcd57b..7338b8fd7 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -38,11 +38,84 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', 'sphinx.ext.extlinks', 'sphinx.ext.doctest'] +extensions = ['sphinx.ext.autodoc', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinx.ext.mathjax', + 'sphinx.ext.ifconfig', + 'sphinx.ext.viewcode', + 'sphinx.ext.extlinks', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx'] # turn off doctests of autodoc included files (these are tested elsewhere) -doctest_test_doctest_blocks = None - +# doctest_test_doctest_blocks = None +doctest_path = sys.path + +# Not currently doctesting VCS with sphinx due to some conflicting name errors across tests +# in the same python instance. +# Setup and cleanup might be able to fix it, but I couldn't get it to work +doctest_global_setup = """ +import vcs, cdms2, os +ex = ex1 = ex2 = None +__examples = [ex, ex1, ex2] +# Copy vcs.elements so we can do a diff later. +# check if it already exists so we don't overwrite the first copy +try: + elts +except: + elts = {} + for key in vcs.elements.keys(): + if type(vcs.elements[key]) == dict: + elts[key]=dict(vcs.elements[key]) + else: + elts[key]=vcs.elements[key] +try: + vcs.removeobject(vcs.elements['texttable']['EXAMPLE_tt']) + vcs.removeobject(vcs.elements['textorientation']['EXAMPLE_tto']) + vcs.removeobject(vcs.elements['template']['example1']) + vcs.removeobject(vcs.elements['colormap']['example']) + a.close() +except: + pass + """ + +doctest_global_cleanup = """ +import glob, sys +f=open("dt_cleanup_log", "a+", 1) +log=[] +gb = glob.glob +patterns = ["example.*", "*.json", "*.svg", "ex_*", "my*", "filename.*"] +files = [] +for pattern in patterns: + fnames = gb(pattern) + for name in fnames: + files.append(name) +for file in files: + try: + os.remove(file) + except: + log.append("COULD NOT delete file: " + file + "\\n") +for key in vcs.elements.keys(): + for _ in vcs.elements[key].keys(): + if not elts[key].has_key(_) and (key,_) != ('line','red'): + try: + vcs.removeobject(vcs.elements[key][_]) + except: + pass + else: + log.append("Removed object: vcs.elements['%s']['%s']%s" % (key,_,'\\n')) +selected_items = [('texttable','EXAMPLE_tt'),('textorientation','EXAMPLE_tto'),('template','example1'),('colormap','example1')] +for item in selected_items: + try: + vcs.removeobject(vcs.elements[item[0]][item[1]]) + except: + log.append("COULD NOT remove object: vcs.elements['%s']['%s']%s" % (item[0],item[1],'\\n')) + else: + log.append("Removed object: vcs.elements['%s']['%s']%s" % (item[0],item[1],'\\n')) +f.writelines(log) +f.flush() +""" # Add any paths that contain templates here, relative to this directory. templates_path = ['templates'] @@ -56,8 +129,9 @@ master_doc = 'index' # General information about the project. -project = 'VCS' -copyright = '2016, LLNL' +project = u'VCS' +copyright = u'2016, LLNL' +author = u'LLNL AIMS Team' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -67,10 +141,10 @@ # flags to set them explicitly using a variable defined there. # # The short X.Y version. -version = '0.1' +version = '2.8.0' # The full version, including alpha/beta/rc tags. -release = '0.1.0' +release = '2.8.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -84,7 +158,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = [] +exclude_patterns = ['_build'] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None @@ -124,9 +198,7 @@ # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = { -# 'bootswatch_theme': "readable" -#} +# html_theme_options = { "stickysidebar" : "true" } # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] @@ -168,7 +240,7 @@ #html_additional_pages = {} # If false, no module index is generated. -html_domain_indices = False +html_domain_indices = True # If false, no index is generated. #html_use_index = True @@ -197,7 +269,7 @@ #html_file_suffix = None # Output file base name for HTML help builder. -htmlhelp_basename = 'VCSDoc' +htmlhelp_basename = 'vcsdoc' # -- Options for LaTeX output -------------------------------------------------- @@ -211,28 +283,28 @@ # Additional stuff for the LaTeX preamble. #'preamble': '', +'classoptions': ',oneside' } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'vcs.tex', 'VCS Documentation', - 'LLNL', 'manual'), + ("API/vcs", 'vcs.tex', u'VCS API Documentation', + u'AIMS Team', 'manual'), ] - # The name of an image file (relative to this directory) to place at the top of # the title page. #latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. -#latex_use_parts = False +#latex_toplevel_sectioning = 'section' # If true, show page references after internal links. -#latex_show_pagerefs = False +latex_show_pagerefs = True # If true, show URL addresses after external links. -#latex_show_urls = False +latex_show_urls = 'no' # Documents to append as an appendix to all manuals. #latex_appendices = [] @@ -260,9 +332,9 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'vcs', 'vcs Documentation', - 'LLNL', 'vcs', 'Visualization library', - 'Miscellaneous'), + (master_doc, 'VCS', u'VCS Documentation', + author, 'VCS', 'Visualization Control System', + 'Miscellaneous'), ] # Documents to append as an appendix to all manuals. diff --git a/docs/index.rst b/docs/index.rst index f2c0b7c6f..fd7a087d4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,8 +1,8 @@ VCS: Visualization Control System -================================== +================================= What is VCS? ---------------- +------------ The PCMDI Visualization Control System (VCS) is expressly designed to meet the needs of scientific community. VCS allows wide-ranging changes to be made to the data display, provides for hardcopy output, and includes a means for recovery of a previous display. @@ -56,6 +56,6 @@ API index --------- .. toctree:: - :maxdepth: 3 + :maxdepth: 4 - API/vcs \ No newline at end of file + API/vcs \ No newline at end of file diff --git a/vcs/Canvas.py b/vcs/Canvas.py index e767825d2..a33efea12 100644 --- a/vcs/Canvas.py +++ b/vcs/Canvas.py @@ -1,9 +1,20 @@ """ -Canvas - The object onto which all plots are drawn. - - Usually created using :py:func:`vcs.init`, this object provides easy access - to the functionality of the entire VCS module. + Canvas objects are the 'visualization' component of VCS. Canvases allow the user to take data and plot it on a + visible window. This gives users an easy way to preview how changes to data representation in VCS will change the + visualization of that data. + + .. pragma: skip-doctest + + .. _list: https://docs.python.org/2/library/functions.html#list + .. _tuple: https://docs.python.org/2/library/functions.html#tuple + .. _dict: https://docs.python.org/2/library/stdtypes.html#mapping-types-dict + .. _None: https://docs.python.org/2/library/constants.html?highlight=none#None + .. _str: https://docs.python.org/2/library/functions.html?highlight=str#str + .. _bool: https://docs.python.org/2/library/functions.html?highlight=bool#bool + .. _float: https://docs.python.org/2/library/functions.html?highlight=float#float + .. _int: https://docs.python.org/2/library/functions.html?highlight=float#int + .. _long: https://docs.python.org/2/library/functions.html?highlight=float#long + .. _file: https://docs.python.org/2/library/functions.html?highlight=open#file """ import warnings import numpy.ma @@ -42,8 +53,7 @@ import inspect import VCS_validation_functions from xmldocs import plot_keywords_doc, graphics_method_core, axesconvert, xaxisconvert, \ - plot_1D_input, plot_2D_input, plot_output, plot_2_1D_input, \ - plot_2_1D_options + plot_1D_input, plot_2D_input, plot_output, plot_2_1D_input, plot_2_1D_options gui_canvas_closed = 0 canvas_closed = 0 import vcsaddons # noqa @@ -104,7 +114,7 @@ def dictionarytovcslist(dictionary, name): def _determine_arg_list(g_name, actual_args): - "Determine what is in the argument list for plotting graphics methods" + """Determine what is in the argument list for plotting graphics methods""" itemplate_name = 2 igraphics_method = 3 @@ -288,11 +298,13 @@ def _process_keyword(obj, target, source, keyargs, default=None): class Canvas(object): - """ - The object onto which all plots are drawn. + """Usually created using :py:func:`vcs.init`, this object provides easy access + to the functionality of the entire VCS module: - Usually created using :py:func:`vcs.init`, this object provides easy access - to the functionality of the entire VCS module. + See :py:func:`vcs.Canvas.Canvas.plot` for more information on the type of + data that can be plotted on a Canvas object. + + .. pragma: skip-doctest """ __slots__ = [ '_mode', @@ -475,6 +487,24 @@ def start(self, *args, **kargs): self.interact(*args, **kargs) def interact(self, *args, **kargs): + """Puts the canvas into interactive mode. + This allows the user to click on the canvas to add markers, + add textboxes, configure settings, rotate 3d plots, and more. + + Press 'Q' with the Canvas selected to quit. + + :Example: + + .. code-block:: python + + a=vcs.init() + b=a.getboxfill() + array=[range(10) for _ in range(10)] + a.plot(b,array) + a.interact() # interactively configure Canvas + + .. pragma: skip-doctest Because testing interact() can't be handled in a doctest + """ self.configure() self.backend.interact(*args, **kargs) @@ -783,8 +813,7 @@ def _reconstruct_tv(self, arglist, keyargs): return tv def objecthelp(self, *arg): - """ - Print out information on the VCS object. See example below on its use. + """Print out information on the VCS object. See example below on its use. :Example: @@ -793,12 +822,14 @@ def objecthelp(self, *arg): >>> a=vcs.init() >>> ln=a.getline('red') # Get a VCS line object >>> a.objecthelp(ln) # This will print out information on how to use ln + The Line object ... + """ for x in arg: print getattr(x, "__doc__", "") - def __init__(self, mode=1, pause_time=0, - call_from_gui=0, size=None, backend="vtk", geometry=None, bg=None): + def __init__(self, mode=1, pause_time=0, call_from_gui=0, size=None, + backend="vtk", geometry=None, bg=None): self._canvas_id = vcs.next_canvas_id self.ParameterChanged = SIGNAL('ParameterChanged') vcs.next_canvas_id += 1 @@ -930,8 +961,7 @@ def processParameterChange(self, args): # Functions to set/querie drawing of UV-CDAT logo def drawlogoon(self): - """ - Show UV-CDAT logo on the canvas + """Show UV-CDAT logo on the canvas :Example: @@ -945,8 +975,7 @@ def drawlogoon(self): self.enableLogo = True def drawlogooff(self): - """ - Hide UV-CDAT logo on the canvas + """Hide UV-CDAT logo on the canvas :Example: @@ -960,8 +989,7 @@ def drawlogooff(self): self.enableLogo = False def getdrawlogo(self): - """ - Returns value of draw logo. By default, draw logo is set to True. + """Returns value of draw logo. By default, draw logo is set to True. :Example: @@ -980,11 +1008,23 @@ def getdrawlogo(self): return self.enableLogo def initLogoDrawing(self): + """Initializes logo drawing for the canvas. + + :Example: + + .. doctest:: canvas_initLogoDrawing + + >>> a=vcs.init() + >>> a.initLogoDrawing() # will draw logo when plot is called + >>> array=[range(10) for _ in range(10)] + >>> a.plot(array) # should have logo in lower right corner + + + """ self.drawLogo = self.enableLogo def update(self, *args, **kargs): - """ - If a series of commands are given to VCS and the Canvas Mode is + """If a series of commands are given to VCS and the Canvas Mode is set to manual, then use this function to update the plot(s) manually. @@ -1011,9 +1051,8 @@ def update(self, *args, **kargs): return self.backend.update(*args, **kargs) def scriptobject(self, obj, script_filename=None, mode=None): - """ - Save individual attributes sets (i.e., individual primary class - objects and/or secondary class objects). These attribute sets + """Save individual attributes sets (i.e., individual primary class + objects and/or secondary objects). These attribute sets are saved in the user's current directory in one of two formats: Python script, or a Javascript Object. @@ -1040,17 +1079,17 @@ def scriptobject(self, obj, script_filename=None, mode=None): .. doctest:: canvas_scriptobject >>> a=vcs.init() - >>> i=a.createisoline('dean') # Create an instance of default isoline object - >>> a.scriptobject(i,'ex_isoline.py') # Save isoline object as a Python file 'isoline.py' - >>> a.scriptobject(i,'ex_isoline2') # Save isoline object as a JSON object 'isoline2.json' + >>> i=a.createisoline('dean') # default isoline object instance + >>> a.scriptobject(i,'ex_isoline.py') # Save to 'isoline.py' + >>> a.scriptobject(i,'ex_isoline2') # Save to 'isoline2.json' :param script_filename: Name of the output script file. - :type script_filename: str + :type script_filename: `str`_ :param mode: Mode is either "w" for replace or "a" for append. - :type mode: str + :type mode: `str`_ - :param obj: Any VCS primary class or secondary class object. + :param obj: Any VCS primary class or secondary object. :type obj: VCS object """ if istemplate(obj): @@ -1106,8 +1145,7 @@ def removeP(self, *args): return vcs.removeP(*args) def clean_auto_generated_objects(self, type=None): - """ - Cleans up all automatically generated VCS objects. + """Cleans up all automatically generated VCS objects. This function will delete all references to objects that VCS created automatically in response to user actions but are @@ -1115,7 +1153,28 @@ def clean_auto_generated_objects(self, type=None): but if you're running into performance/memory issues, calling it periodically may help. - :param type: Type of objects to remove. By default, will remove everything. + :Example: + + .. doctest:: canvas_clean_auto_generated_objects + + >>> a=vcs.init() + >>> clean=a.clean_auto_generated_objects # alias long name + >>> clean() # clean possible old objects from vcs + >>> txt=a.listelements('textorientation') # initial objects + >>> array=[range(10) for _ in range(10)] + >>> a.plot(array) + + >>> new_txt=a.listelements('textorientation') # has new names + >>> txt == new_txt # should not be the same + False + >>> clean() + >>> new_txt=a.listelements('textorientation') # back to initial + >>> txt == new_txt # should have the same contents + True + + + :param type: Type of objects to remove. By default, will remove + all object types. :type type: None, str, list/tuple (of str) """ @@ -1177,49 +1236,50 @@ def getboxfill(self, Gfb_name_src='default'): getboxfill.__doc__ = vcs.manageElements.getboxfill.__doc__ def boxfill(self, *args, **parms): - """ - Generate a boxfill plot given the data, boxfill graphics method, and - template. If no boxfill class object is given, then the 'default' boxfill - graphics method is used. Similarly, if no template class object is given, + """Generate a boxfill plot given the data, boxfill graphics method, and + template. If no boxfill object is given, then the 'default' boxfill + graphics method is used. Similarly, if no template object is given, then the 'default' template is used. - - :Example: .. doctest:: canvas_boxfill >>> a=vcs.init() - >>> a.show('boxfill') # Show all the existing boxfill graphics methods + >>> a.show('boxfill') # Show all boxfills *******************Boxfill Names List********************** ... *******************End Boxfill Names List********************** >>> box=a.getboxfill('quick') # Create instance of 'quick' - >>> array=[range(10) for _ in range(10)] - >>> a.boxfill(array, box) # Plot array using specified box and default template + >>> arr=[range(10) for _ in range(10)] # data to plot + >>> a.boxfill(arr, box) # Plot array w/ box; default template - >>> template = a.gettemplate('quick') # get quick template + >>> t = a.gettemplate('quick') # get quick template >>> a.clear() # Clear VCS canvas - >>> a.boxfill(array, box, template) # Plot array using specified box and template + >>> a.boxfill(arr, box, t) # Plot w/ box and 'quick' template - >>> a.boxfill(box, array, template) # Plot array using specified box and template + >>> a.boxfill(box, arr, t) # Plot w/ box and 'quick' template - >>> a.boxfill(template, array, box) # Plot array using specified box and template + >>> a.boxfill(t, arr, box) # Plot w/ box and 'quick' template - >>> a.boxfill(template, box, array) # Plot array using specified box and template + >>> a.boxfill(t, box, arr) # Plot w/ box and 'quick' template - >>> a.boxfill(array, 'hovmuller', 'quick') # Use 'hovmuller' template and 'quick' boxfill + >>> a.boxfill(arr, 'polar', 'polar') # 'polar' template/boxfill - >>> a.boxfill('hovmuller', array, 'quick') # Use 'hovmuller' template and 'quick' boxfill + >>> a.boxfill('polar', arr, 'polar') # 'polar' template/boxfill - >>> a.boxfill('hovmuller', 'quick', array) # Use 'hovmuller template and 'quick' boxfill + >>> a.boxfill('polar', 'polar', arr) # 'polar' template/boxfill .. note:: - As shown above, the array, 'template', and 'box' parameters can be provided in any order. + As shown above, the data, 'template', and 'box' parameters can be provided in any order. The 'template' and 'box' parameters can either be VCS template and boxfill objects, or string names of template and boxfill objects. + + The first string provided is assumed to be a template name. The second is assumed to be a + boxfill name. + %s %s %s @@ -1240,10 +1300,9 @@ def gettaylordiagram(self, Gtd_name_src='default'): gettaylordiagram.__doc__ = vcs.manageElements.gettaylordiagram.__doc__ def taylordiagram(self, *args, **parms): - """ - Generate a taylordiagram plot given the data, taylordiagram graphics method, and - template. If no taylordiagram class object is given, then the 'default' taylordiagram - graphics method is used. Similarly, if no template class object is given, + """Generate a taylordiagram plot given the data, taylordiagram graphics method, and + template. If no taylordiagram object is given, then the 'default' taylordiagram + graphics method is used. Similarly, if no template object is given, then the 'default' template is used. :Example: @@ -1279,10 +1338,9 @@ def getmeshfill(self, Gfm_name_src='default'): getmeshfill.__doc__ = vcs.manageElements.getmeshfill.__doc__ def meshfill(self, *args, **parms): # noqa - """ - Generate a meshfill plot given the data, the mesh, a meshfill graphics method, and - a template. If no meshfill class object is given, then the 'default' meshfill - graphics method is used. Similarly, if no template class object is given, + """Generate a meshfill plot given the data, the mesh, a meshfill graphics method, and + a template. If no meshfill object is given, then the 'default' meshfill + graphics method is used. Similarly, if no template object is given, then the 'default' template is used. Format: @@ -1290,7 +1348,7 @@ def meshfill(self, *args, **parms): # noqa In addition the mesh array must be of the same shape than data with 2 additional dimension representing the vertices coordinates for the Y (0) and X (1) dimension Let's say you want to plot a spatial assuming mesh containing 10,000 grid cell, then data must be shape (10000,) - or (n1,n2,n3,...,10000) if additional dimensions exist (ex time,level), these dimension would be used only + or (n1,n2,n3,...,10000) if additional dimensions exist (ex time,level), these dimensions would be used only for animation and will be ignored in the rest of this example. The shape of the mesh, assuming 4 vertices per grid cell, must be (1000,2,4), where the array [:,0,:] represent the Y coordinates of the vertices (clockwise or counterclockwise) and the array [:,1:] @@ -1304,18 +1362,19 @@ def meshfill(self, *args, **parms): # noqa .. doctest:: canvas_meshfill >>> a=vcs.init() - >>> a.show('meshfill') # Show all the existing meshfill graphics methods + >>> a.show('meshfill') # Show all meshfill graphics methods *******************Meshfill Names List********************** ... *******************End Meshfill Names List********************** >>> import cdms2 # Need cdms2 to create a slab - >>> f = cdms2.open(vcs.sample_data+'/clt.nc') # use cdms2 to open a data file - >>> slab = f('clt') # use the data file to create a cdms2 slab - >>> mesh=a.getmeshfill() # Create instance of 'default' - >>> a.meshfill(slab,mesh) # Plot array using specified mesh and default template + >>> f = cdms2.open(vcs.sample_data+'/clt.nc') # open data file + >>> slab = f('clt') # use data file to create a cdms2 slab + >>> m=a.getmeshfill() # Create instance of 'default' + >>> a.meshfill(slab,m) # Plot with default mesh & template >>> a.clear() # Clear VCS canvas - >>> a.meshfill(slab,mesh,'quick','a_polar_meshfill') # Plot slab with polar mesh, quick template + >>> p='a_polar_meshfill' # will use this to plot + >>> a.meshfill(slab,m,'quick', p) # polar mesh, quick template :returns: A VCS displayplot object. @@ -1334,6 +1393,34 @@ def get3d_scalar(self, Gfdv3d_name_src='default'): get3d_scalar.__doc__ = vcs.manageElements.get3d_scalar.__doc__ def scalar3d(self, *args, **parms): + """Generate a 3d_scalar plot given the data, 3d_scalar + graphics method, and template. If no 3d_scalar object is given, + then the 'default' 3d_scalar graphics method is used. + Similarly, if no template is given, the 'default' template is used. + + :Example: + + .. doctest:: canvas_scalar3d + + >>> a=vcs.init() + >>> a.show('3d_scalar') # Show all 3d_scalars + *******************3d_scalar Names List********************** + ... + *******************End 3d_scalar Names List********************** + >>> ds=a.get3d_scalar() # default 3d_scalar + >>> import cdms2 # Need cdms2 to create a slab + >>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data file + >>> s = f('clt') # use data file to create a cdms2 slab + >>> a.scalar3d(ds,s) # Plot slab with defaults + initCamera: Camera => (...) + + >>> a.clear() # Clear VCS canvas + saved state data to file <...> + >>> t = a.gettemplate('polar') + >>> a.scalar3d(s,ds,t) # Plot with 'polar' template + initCamera: Camera => (...) + + """ arglist = _determine_arg_list('3d_scalar', args) return self.__plot(arglist, parms) @@ -1347,6 +1434,43 @@ def get3d_vector(self, Gfdv3d_name_src='default'): get3d_vector.__doc__ = vcs.manageElements.get3d_vector.__doc__ def vector3d(self, *args, **parms): + """Generate a 3d_vector plot given the data, 3d_vector + graphics method, and template. If no 3d_vector object is given, + then the 'default' 3d_vector graphics method is used. + Similarly, if no template is given, the 'default' template is used. + + .. note:: + + 3d_vectors need 2 data objects (slabs) to plot. + + :Example: + + .. doctest:: canvas_vector3d + + >>> a=vcs.init() + >>> a.show('3d_vector') # Show all 3d_vectors + *******************3d_vector Names List********************** + ... + *******************End 3d_vector Names List********************** + >>> dv3=a.get3d_vector() # default 3d_vector + >>> import cdms2 # Need cdms2 to create a slab + >>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data file + >>> s = f('u') # use data file to create a cdms2 slab + >>> s2 = f('v') # need two slabs, so get another + >>> a.vector3d(dv3,s,s2) # Plot slabs + Sample rate: 6 + Sample rate: 6 + initCamera: Camera => (...) + + >>> a.clear() # Clear VCS canvas + saved state data to file <...> + >>> t = a.gettemplate('polar') + >>> a.vector3d(s,s2,dv3,t) # Plot with 'polar' template + Sample rate: 6 + Sample rate: 6 + initCamera: Camera => (...) + + """ arglist = _determine_arg_list('3d_vector', args) return self.__plot(arglist, parms) @@ -1360,9 +1484,43 @@ def get3d_dual_scalar(self, Gfdv3d_name_src='default'): get3d_dual_scalar.__doc__ = vcs.manageElements.get3d_dual_scalar.__doc__ def dual_scalar3d(self, *args, **parms): + """Generate a 3d_dual_scalar plot given the data, 3d_dual_scalar + graphics method, and template. If no 3d_dual_scalar object is given, + then the 'default' 3d_dual_scalar graphics method is used. + Similarly, if no template is given, the 'default' template is used. + + .. note:: + + 3d_dual_scalars need 2 data objects (slabs) to plot. + + :Example: + + .. doctest:: canvas_dual_scalar3d + + >>> a=vcs.init() + >>> a.show('3d_dual_scalar') # Show all 3d_dual_scalars + *******************3d_dual_scalar Names List********************** + ... + *******************End 3d_dual_scalar Names List********************** + >>> ds3=a.get3d_dual_scalar() # default 3d_dual_scalar + >>> import cdms2 # Need cdms2 to create a slab + >>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data file + >>> s = f('clt') # use data file to create a cdms2 slab + >>> s2 = f('v') # need two slabs, so get another + >>> a.dual_scalar3d(ds3,s,s2) # Plot slabs + initCamera: Camera => (...) + + >>> a.clear() # Clear VCS canvas + saved state data to file <...> + >>> t = a.gettemplate('polar') + >>> a.dual_scalar3d(s,s2,ds3,t) # Plot w/ 'polar' template + initCamera: Camera => (...) + + """ arglist = _determine_arg_list('3d_dual_scalar', args) return self.__plot(arglist, parms) + def createisofill(self, name=None, source='default'): return vcs.createisofill(name, source) createisofill.__doc__ = vcs.manageElements.createisofill.__doc__ @@ -1372,10 +1530,9 @@ def getisofill(self, Gfi_name_src='default'): getisofill.__doc__ = vcs.manageElements.getisofill.__doc__ def isofill(self, *args, **parms): - """ - Generate a isofill plot given the data, isofill graphics method, and - template. If no isofill class object is given, then the 'default' isofill - graphics method is used. Similarly, if no template class object is given, + """Generate an isofill plot given the data, isofill graphics method, and + template. If no isofill object is given, then the 'default' isofill + graphics method is used. Similarly, if no template object is given, then the 'default' template is used. :Example: @@ -1383,19 +1540,19 @@ def isofill(self, *args, **parms): .. doctest:: canvas_isofill >>> a=vcs.init() - >>> a.show('isofill') # Show all the existing isofill graphics methods + >>> a.show('isofill') # Show all isofill graphics methods *******************Isofill Names List********************** ... *******************End Isofill Names List********************** >>> iso=a.getisofill('quick') # Create instance of 'quick' >>> import cdms2 # Need cdms2 to create a slab - >>> f = cdms2.open(vcs.sample_data+'/clt.nc') # use cdms2 to open a data file - >>> slab = f('clt') # use the data file to create a cdms2 slab - >>> a.isofill(slab,iso) # Plot array using specified iso and default template + >>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data file + >>> slab = f('clt') # use data file to create a cdms2 slab + >>> a.isofill(slab,iso) # Plot slab with iso; default template >>> a.clear() # Clear VCS canvas - >>> template = a.gettemplate('hovmuller') - >>> a.isofill(slab,iso,template) # Plot array using specified iso and template + >>> t = a.gettemplate('hovmuller') + >>> a.isofill(slab,iso,t) # Plot with 'hovmuller' template %s @@ -1403,9 +1560,6 @@ def isofill(self, *args, **parms): %s %s %s - - :returns: A VCS displayplot object. - :rtype: vcs.displayplot.Dp """ arglist = _determine_arg_list('isofill', args) return self.__plot(arglist, parms) @@ -1421,10 +1575,9 @@ def getisoline(self, Gi_name_src='default'): getisoline.__doc__ = vcs.manageElements.getisoline.__doc__ def isoline(self, *args, **parms): - """ - Generate a isoline plot given the data, isoline graphics method, and - template. If no isoline class object is given, then the 'default' isoline - graphics method is used. Similarly, if no template class object is given, + """Generate a isoline plot given the data, isoline graphics method, and + template. If no isoline object is given, then the 'default' isoline + graphics method is used. Similarly, if no template object is given, then the 'default' template is used. :Example: @@ -1450,9 +1603,6 @@ def isoline(self, *args, **parms): %s %s %s - - :returns: A VCS displayplot object. - :rtype: vcs.displayplot.Dp """ arglist = _determine_arg_list('isoline', args) return self.__plot(arglist, parms) @@ -1465,7 +1615,7 @@ def create1d(self, name=None, source='default'): def get1d(self, name): return vcs.get1d(name) - create1d.__doc__ = vcs.manageElements.create1d.__doc__ + get1d.__doc__ = vcs.manageElements.get1d.__doc__ def createxyvsy(self, name=None, source='default'): return vcs.createxyvsy(name, source) @@ -1476,10 +1626,9 @@ def getxyvsy(self, GXy_name_src='default'): getxyvsy.__doc__ = vcs.manageElements.getxyvsy.__doc__ def xyvsy(self, *args, **parms): - """ - Generate a Xyvsy plot given the data, Xyvsy graphics method, and - template. If no Xyvsy class object is given, then the 'default' Xyvsy - graphics method is used. Similarly, if no template class object is given, + """Generate a Xyvsy plot given the data, Xyvsy graphics method, and + template. If no Xyvsy object is given, then the 'default' Xyvsy + graphics method is used. Similarly, if no template object is given, then the 'default' template is used. :Example: @@ -1505,9 +1654,6 @@ def xyvsy(self, *args, **parms): %s %s %s - - :returns: A VCS displayplot object. - :rtype: vcs.displayplot.Dp """ arglist = _determine_arg_list('xyvsy', args) return self.__plot(arglist, parms) @@ -1523,10 +1669,9 @@ def getyxvsx(self, GYx_name_src='default'): getyxvsx.__doc__ = vcs.manageElements.getyxvsx.__doc__ def yxvsx(self, *args, **parms): - """ - Generate a Yxvsx plot given the data, Yxvsx graphics method, and - template. If no Yxvsx class object is given, then the 'default' Yxvsx - graphics method is used. Simerly, if no template class object is given, + """Generate a Yxvsx plot given the data, Yxvsx graphics method, and + template. If no Yxvsx object is given, then the 'default' Yxvsx + graphics method is used. Simerly, if no template object is given, then the 'default' template is used. :Example: @@ -1552,9 +1697,6 @@ def yxvsx(self, *args, **parms): %s %s %s - - :returns: A VCS displayplot object. - :rtype: vcs.displayplot.Dp """ arglist = _determine_arg_list('yxvsx', args) return self.__plot(arglist, parms) @@ -1570,10 +1712,9 @@ def getxvsy(self, GXY_name_src='default'): getxvsy.__doc__ = vcs.manageElements.getxvsy.__doc__ def xvsy(self, *args, **parms): - """ - Generate a XvsY plot given the data, XvsY graphics method, and - template. If no XvsY class object is given, then the 'default' XvsY - graphics method is used. Similarly, if no template class object is given, + """Generate a XvsY plot given the data, XvsY graphics method, and + template. If no XvsY object is given, then the 'default' XvsY + graphics method is used. Similarly, if no template object is given, then the 'default' template is used. :Example: @@ -1602,9 +1743,6 @@ def xvsy(self, *args, **parms): %s %s %s - - :returns: A VCS displayplot object. - :rtype: vcs.displayplot.Dp """ arglist = _determine_arg_list('xvsy', args) return self.__plot(arglist, parms) @@ -1623,10 +1761,9 @@ def getvector(self, Gv_name_src='default'): getvector.__doc__ = vcs.manageElements.getvector.__doc__ def vector(self, *args, **parms): - """ - Generate a vector plot given the data, vector graphics method, and - template. If no vector class object is given, then the 'default' vector - graphics method is used. Similarly, if no template class object is given, + """Generate a vector plot given the data, vector graphics method, and + template. If no vector object is given, then the 'default' vector + graphics method is used. Similarly, if no template object is given, then the 'default' template is used. :Example: @@ -1664,10 +1801,9 @@ def getscatter(self, GSp_name_src='default'): getscatter.__doc__ = vcs.manageElements.getscatter.__doc__ def scatter(self, *args, **parms): - """ - Generate a scatter plot given the data, scatter graphics method, and - template. If no scatter class object is given, then the 'default' scatter - graphics method is used. Similarly, if no template class object is given, + """Generate a scatter plot given the data, scatter graphics method, and + template. If no scatter object is given, then the 'default' scatter + graphics method is used. Similarly, if no template object is given, then the 'default' template is used. :Example: @@ -1695,9 +1831,6 @@ def scatter(self, *args, **parms): %s %s %s - - :returns: A VCS displayplot object. - :rtype: vcs.displayplot.Dp """ arglist = _determine_arg_list('scatter', args) @@ -1722,8 +1855,7 @@ def getline(self, name='default', ltype=None, width=None, color=None, getline.__doc__ = vcs.manageElements.getline.__doc__ def line(self, *args, **parms): - """ - Plot a line segment on the Vcs Canvas. If no line class + """Plot a line segment on the Vcs Canvas. If no line class object is given, then an error will be returned. :Example: @@ -1754,8 +1886,7 @@ def drawline(self, name=None, ltype='solid', width=1, color=241, # noqa priority=1, viewport=[0.0, 1.0, 0.0, 1.0], worldcoordinate=[0.0, 1.0, 0.0, 1.0], x=None, y=None, projection='default', bg=0): - """ - Generate and draw a line object on the VCS Canvas. + """Generate and draw a line object on the VCS Canvas. :Example: @@ -1774,38 +1905,20 @@ def drawline(self, name=None, ltype='solid', width=1, color=241, # noqa >>> a.line(ln) # Plot using specified line object - :param name: Name of created object - :type name: str + %s :param ltype: One of "dash", "dash-dot", "solid", "dot", or "long-dash". - :type ltype: str + :type ltype: `str`_ :param width: Thickness of the line to be drawn - :type width: int - - :param color: A color name from the `X11 Color Names list `_, - or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) - :type color: str or int - - :param priority: The layer on which the line will be drawn. - :type priority: int + :type width: `int`_ - :param viewport: 4 floats between 0 and 1. - These specify the area that the X/Y values are mapped to inside of the canvas - :type viewport: list of floats - - :param worldcoordinate: List of 4 floats (xmin, xmax, ymin, ymax) - :type worldcoordinate: list of floats - - :param x: List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1]. - :type x: list of floats - - :param y: List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3]. - :type y: list of floats - - :param projection: Specify a geographic projection used to convert x/y - from spherical coordinates into 2D coordinates. - :type projection: str or projection object + %s + %s + %s + %s + %s + %s :returns: A VCS line object :rtype: vcs.line.Tl @@ -1830,6 +1943,8 @@ def drawline(self, name=None, ltype='solid', width=1, color=241, # noqa self.line(ln, bg=bg) return ln + drawline.__doc__ = drawline.__doc__ % (xmldocs.name, xmldocs.color, xmldocs.priority, xmldocs.viewport, + xmldocs.worldcoordinate, xmldocs.x_y_coords, xmldocs.projection) def createmarker(self, name=None, source='default', mtype=None, # noqa size=None, color=None, priority=1, @@ -1848,8 +1963,7 @@ def getmarker(self, name='default', mtype=None, size=None, color=None, getmarker.__doc__ = vcs.manageElements.getmarker.__doc__ def marker(self, *args, **parms): - """ - Plot a marker segment on the Vcs Canvas. If no marker class + """Plot a marker segment on the Vcs Canvas. If no marker class object is given, then an error will be returned. :Example: @@ -1880,8 +1994,7 @@ def drawmarker(self, name=None, mtype='solid', size=1, color=241, priority=1, viewport=[0.0, 1.0, 0.0, 1.0], worldcoordinate=[0.0, 1.0, 0.0, 1.0], x=None, y=None, bg=0): - """ - Generate and draw a marker object on the VCS Canvas. + """Generate and draw a marker object on the VCS Canvas. :Example: @@ -1900,34 +2013,20 @@ def drawmarker(self, name=None, mtype='solid', size=1, color=241, >>> a.marker(mrk) # Plot using specified marker object - :param name: Name of created object - :type name: str + %s :param mtype: Marker type, i.e. 'dot', 'plus', 'star, etc. - :type mtype: str + :type mtype: `str`_ :param size: Size of the marker to draw - :type size: int - - :param color: A color name from the `X11 Color Names list `_, - or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) - :type color: str or int + :type size: `int`_ - :param priority: The layer on which the marker will be drawn. - :type priority: int - - :param viewport: 4 floats between 0 and 1. - These specify the area that the X/Y values are mapped to inside of the canvas - :type viewport: list of floats - - :param worldcoordinate: List of 4 floats (xmin, xmax, ymin, ymax) - :type worldcoordinate: list of floats - - :param x: List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1]. - :type x: list of floats - - :param y: List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3]. - :type y: list of floats + %s + %s + %s + %s + %s + %s :returns: A drawmarker object :rtype: vcs.marker.Tm @@ -1952,6 +2051,9 @@ def drawmarker(self, name=None, mtype='solid', size=1, color=241, return mrk + drawmarker.__doc__ = drawmarker.__doc__ % (xmldocs.name, xmldocs.color, xmldocs.priority, xmldocs.viewport, + xmldocs.worldcoordinate, xmldocs.x_y_coords, xmldocs.bg) + def createfillarea(self, name=None, source='default', style=None, index=None, color=None, priority=1, viewport=None, worldcoordinate=None, @@ -1970,8 +2072,7 @@ def getfillarea(self, name='default', style=None, getfillarea.__doc__ = vcs.manageElements.getfillarea.__doc__ def fillarea(self, *args, **parms): - """ - Generate a fillarea plot + """Generate a fillarea plot Plot a fillarea segment on the Vcs Canvas. If no fillarea class object is given, then an error will be returned. @@ -1981,16 +2082,16 @@ def fillarea(self, *args, **parms): .. doctest:: canvas_fillarea >>> a=vcs.init() - >>> a.show('fillarea') # Show all the existing fillarea objects + >>> a.show('fillarea') # Show all fillarea objects *******************Fillarea Names List********************** ... *******************End Fillarea Names List********************** - >>> fa=a.createfillarea() # Create instance of default fillarea - >>> fa.style=1 # Set the fillarea style - >>> fa.index=4 # Set the fillarea index - >>> fa.color = 242 # Set the fillarea color - >>> fa.x=[0.25,0.75] # Set the x value points - >>> fa.y=[0.2,0.5] # Set the y value points + >>> fa=a.createfillarea() # instance of default fillarea + >>> fa.style=1 # Set fillarea style + >>> fa.index=4 # Set fillarea index + >>> fa.color = 242 # Set fillarea color + >>> fa.x=[0.25,0.75] # Set x value points + >>> fa.y=[0.2,0.5] # Set y value points >>> a.fillarea(fa) # Plot using specified fillarea object @@ -2004,8 +2105,7 @@ def drawfillarea(self, name=None, style=1, index=1, color=241, priority=1, viewport=[0.0, 1.0, 0.0, 1.0], worldcoordinate=[0.0, 1.0, 0.0, 1.0], x=None, y=None, bg=0): - """ - Generate and draw a fillarea object on the VCS Canvas. + """Generate and draw a fillarea object on the VCS Canvas. :Example: @@ -2024,44 +2124,28 @@ def drawfillarea(self, name=None, style=1, index=1, color=241, >>> a.fillarea(fa) # Plot using specified fillarea object - :param name: Name of created object - :type name: str + %s :param style: One of "hatch", "solid", or "pattern". - :type style: str + :type style: `str`_ - :param index: Specifies which `pattern `_ - to fill the fillarea with. Accepts ints from 1-20. + :param index: Specifies which `pattern`_ to fill the fillarea with. + Accepts ints from 1-20. - :type index: int + :type index: `int`_ - :param color: A color name from the `X11 Color Names list `_, - or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) - - :type color: str or int - - :param priority: The layer on which the fillarea will be drawn. - :type priority: int - - :param viewport: 4 floats between 0 and 1. - These specify the area that the X/Y values are mapped to inside of the canvas - :type viewport: list of floats - - :param worldcoordinate: List of 4 floats (xmin, xmax, ymin, ymax) - :type worldcoordinate: list of floats - - :param x: List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1]. - :type x: list of floats - - :param y: List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3]. - :type y: list of floats + %s + %s + %s + %s + %s + %s - :param bg: Boolean value. True => object drawn in background (not shown on canvas). - False => object shown on canvas. - :type bg: bool :returns: A fillarea object :rtype: vcs.fillarea.Tf + + .. _pattern: http://uvcdat.llnl.gov/gallery/fullsize/pattern_chart.png """ if (name is None) or (not isinstance(name, str)): raise vcsError('Must provide string name for the fillarea.') @@ -2083,6 +2167,9 @@ def drawfillarea(self, name=None, style=1, index=1, color=241, return fa + drawfillarea.__doc__ = drawfillarea.__doc__ % (xmldocs.name, xmldocs.color, xmldocs.priority, xmldocs.viewport, + xmldocs.worldcoordinate, xmldocs.x_y_coords, xmldocs.bg) + def createtexttable(self, name=None, source='default', font=None, spacing=None, expansion=None, color=None, priority=None, viewport=None, worldcoordinate=None, @@ -2134,15 +2221,9 @@ def gettextcombined(self, Tt_name_src='default', To_name_src=None, string=None, gettext = gettextcombined def textcombined(self, *args, **parms): - """ - Plot a textcombined segment on the Vcs Canvas. If no textcombined class + """Plot a textcombined segment on the Vcs Canvas. If no textcombined class object is given, then an error will be returned. - .. note:: - - The text() function is an alias for textcombined(). - See example for usage. - :Example: .. doctest:: canvas_textcombined @@ -2204,8 +2285,7 @@ def textcombined(self, *args, **parms): text = textcombined def gettextextent(self, textobject): - """ - Returns the coordinate of the box surrounding a text object once printed + """Returns the coordinate of the box surrounding a text object once printed :Example: @@ -2220,10 +2300,10 @@ def gettextextent(self, textobject): [[...]] :param textobject: A VCS text object - :type textobject: textcombined + :type textobject: vcs.textcombined.Tc :returns: list of floats containing the coordinates of the text object's bounding box. - :rtype: list + :rtype: `list`_ """ if not vcs.istext(textobject): raise vcsError('You must pass a text object') @@ -2233,6 +2313,7 @@ def gettextextent(self, textobject): def match_color(self, color, colormap=None): # noqa return vcs.match_color(color, colormap) + match_color.__doc__ = vcs.utils.match_color.__doc__ def drawtextcombined(self, Tt_name=None, To_name=None, string=None, font=1, spacing=2, expansion=100, color=241, @@ -2241,59 +2322,37 @@ def drawtextcombined(self, Tt_name=None, To_name=None, string=None, priority=1, viewport=[0.0, 1.0, 0.0, 1.0], worldcoordinate=[0.0, 1.0, 0.0, 1.0], x=None, y=None, bg=0): - """ - Generate and draw a textcombined object on the VCS Canvas. + """Draw a textcombined object on the VCS Canvas. :Example: .. doctest:: canvas_drawtextcombined >>> a=vcs.init() - >>> a.show('texttable') # Show all the existing texttable objects + >>> drawtc=a.drawtextcombined # alias long function name + >>> a.show('texttable') # Show all the existing texttable objects *******************Texttable Names List********************** ... *******************End Texttable Names List********************** - >>> tc=a.drawtextcombined(Tt_name = 'std_example', To_name='7left_example', - ... string='Hello example!', spacing=5, - ... color=242, priority=1, viewport=[0, 1.0, 0, 1.0], - ... worldcoordinate=[0,100, 0,50], - ... x=[0,20,40,60,80,100], - ... y=[0,10,20,30,40,50]) # Create instance of texttable object 'red' - >>> a.textcombined(tc) # Plot using specified texttable object - - :param name: Name of created object - :type name: str + >>> vcs.createtextcombined('draw_tt','qa', 'draw_tto', '7left') + + >>> msg=["Hello", "drawtextcombined!"] + >>> tc=drawtc(Tt_name='draw_tt',To_name='draw_tto',string=msg) - :param style: One of "hatch", "solid", or "pattern". - :type style: str - - :param index: Specifies which `pattern `_ - to fill the fillarea with. Accepts ints from 1-20. - :type index: int - - :param color: A color name from the `X11 Color Names list `_, - or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) - :type color: str or int - - :param priority: The layer on which the fillarea will be drawn. - :type priority: int + :param Tt_name: String name of a texttable object + :type Tt_name: `str`_ - :param viewport: 4 floats between 0 and 1. - These specify the area that the X/Y values are mapped to inside of the canvas - :type viewport: list of floats + :param To_name: String name of a textorientation object + :type To_name: `str`_ - :param worldcoordinate: List of 4 floats (xmin, xmax, ymin, ymax) - :type worldcoordinate: list of floats + :param string: String to put onto the new textcombined + :type string: `str`_ - :param x: List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1]. - :type x: list of floats - - :param y: List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3]. - :type y: list of floats - - :param bg: Boolean value. True => object drawn in background (not shown on canvas). - False => object shown on canvas. - :type bg: bool + %s + %s + %s + %s + %s :returns: A texttable object :rtype: vcs.texttable.Tt @@ -2336,6 +2395,8 @@ def drawtextcombined(self, Tt_name=None, To_name=None, string=None, # # Set alias for the secondary drawtextcombined. drawtext = drawtextcombined + drawtextcombined.__doc__ = drawtextcombined.__doc__ % (xmldocs.color, xmldocs.viewport, xmldocs.worldcoordinate, + xmldocs.x_y_coords, xmldocs.bg) _plot_keywords_ = ['variable', 'grid', 'xaxis', 'xarray', 'xrev', 'yaxis', 'yarray', 'yrev', 'continents', 'xbounds', 'ybounds', 'zaxis', 'zarray', 'taxis', 'tarray', 'waxis', 'warray', 'bg', 'ratio', @@ -2351,44 +2412,59 @@ def drawtextcombined(self, Tt_name=None, To_name=None, string=None, # self.plot(*self.__last_plot_actual_args, **self.__last_plot_keyargs) def plot(self, *actual_args, **keyargs): - """ - Plot an array(s) of data given a template and graphics method. The VCS template is - used to define where the data and variable attributes will be displayed on the VCS - Canvas. The VCS graphics method is used to define how the array(s) will be shown - on the VCS Canvas. + """Plot an array(s) of data given a template and graphics method. - .. describe:: Plot Usage: + The VCS template is used to define where the data and variable + attributes will be displayed on the VCS Canvas. - .. code-block:: python + The VCS graphics method is used to define how the array(s) will be + shown on the VCS Canvas. - plot(array1=None, array2=None, template_name=None, - graphics_method=None, graphics_name=None, - [key=value [, key=value [, ...]]]) + .. describe:: Plot Usage: - .. note:: + .. doctest:: canvas_plot_usage - array1 and array2 are NumPy arrays. + >>> import numpy + >>> a=vcs.init() + >>> a.show('template') # list vcs template types + *******************Template Names List********************** + ... + *******************End Template Names List********************** + >>> a.show('boxfill') # one of many graphics method types + *******************Boxfill Names List********************** + ... + *******************End Boxfill Names List********************** + >>> array1 = numpy.array([range(10) for _ in range(10)]) # data + >>> a.plot(variable=array1) + + >>> a.plot(array1,'ASD',gm='boxfill') # boxfill, ASD template + .. describe:: Plot attribute keywords: - .. note:: - More specific attributes take precedence over general attributes. In particular, - specific attributes override variable object attributes, dimension attributes and - arrays override axis objects, which override grid objects, which override variable + .. note:: **Attribute Precedence** + + Specific attributes take precedence over general attributes. + In particular, specific attributes override variable object + attributes, dimension attributes and arrays override axis + objects, which override grid objects, which override variable objects. - For example, if both 'file_comment' and 'variable' keywords are specified, the value of - 'file_comment' is used instead of the file comment in the parent of variable. Similarly, - if both 'xaxis' and 'grid' keywords are specified, the value of 'xaxis' takes precedence - over the x-axis of grid. + For example, if both 'file_comment' and 'variable' keywords are + specified, the value of 'file_comment' is used instead of the + file comment in the parent of variable. Similarly, if both + 'xaxis' and 'grid' keywords are specified, the value of 'xaxis' + takes precedence over the x-axis of grid. - * ratio [default is none] + * ratio [default is None] * None: let the self.ratio attribute decide - * 0,'off': overwrite self.ratio and do nothing about the ratio + * 0, 'off': overwrite self.ratio and do nothing about the ratio * 'auto': computes an automatic ratio - * '3',3: y dim will be 3 times bigger than x dim (restricted to original tempalte.data area - * Adding a 't' at the end of the ratio, makes the tickmarks and boxes move along. + * '3', 3: y dim will be 3 times bigger than x dim (restricted + to original template.data area) + * Adding a 't' at the end of the ratio, makes the tickmarks and + boxes move along. * Dimension attribute keys (dimension length=n): @@ -2462,6 +2538,7 @@ def plot(self, *actual_args, **keyargs): * 5 signifies "Rivers" .. note:: + Values 6 through 11 signify the line type defined by the files data_continent_other7 through data_continent_other12. @@ -2505,7 +2582,7 @@ def plot(self, *actual_args, **keyargs): .. code-block:: python - # if ==1, create images in the background + # if 1, create images in the background (not on canvas) bg = 0|1 :Example: @@ -2514,20 +2591,20 @@ def plot(self, *actual_args, **keyargs): >>> a=vcs.init() >>> import cdms2 # Need cdms2 to create a slab - >>> f = cdms2.open(vcs.sample_data+'/clt.nc') # use cdms2 to open a data file + >>> f = cdms2.open(vcs.sample_data+'/clt.nc') # open data file >>> slab1 = f('u') # use the data file to create a cdms2 slab >>> slab2 = f('v') # need 2 slabs, so get another - >>> a.plot(slab1) # this call will use default settings for template and boxfill + >>> a.plot(slab1) # default settings for template and boxfill - >>> a.plot(slab1, 'polar', 'isofill', 'polar') # this is specifying the template and graphics method + >>> a.plot(slab1,'polar','isofill','polar') # specify template and graphics method >>> t=a.gettemplate('polar') # get the polar template >>> vec=a.getvector() # get default vector - >>> a.plot(slab1, slab2, t, vec) # plot the data as a vector using the 'AMIP' template + >>> a.plot(slab1, slab2, t, vec) # plot data as vector using polar template >>> a.clear() # clear the VCS Canvas of all plots >>> box=a.getboxfill() # get default boxfill graphics method - >>> a.plot(box,t,slab2) # plot array data using box 'new' and template 't' + >>> a.plot(box,t,slab2) # plot data with boxfill and polar %s @@ -3967,14 +4044,48 @@ def setAnimationStepper(self, stepper): self.backend.setAnimationStepper(stepper) def return_display_names(self, *args): + """Show the list of display names associated with all active plots + on the canvas. + + :Example: + + .. doctest:: canvas_return_display_name + + >>> a=vcs.init() + >>> a.return_display_names() # new canvas should have none + [] + >>> array=[range(10) for _ in range(10)] + >>> a.plot(array) + + >>> a.return_display_names() # has display name for new plot + [...] + + :return: A list of the display names of images currently plotted + on the canvas. + :rtype: `list`_ + """ return self.display_names def remove_display_name(self, *args): - """ - Removes a plotted item from the canvas. + """Removes a plotted item from the canvas. + + :Example: + + .. doctest:: canvas_remove_display_name + + >>> a=vcs.init() + >>> a.return_display_names() # new canvas should have none + [] + >>> array=[range(10) for _ in range(10)] + >>> plot=a.plot(array) # store plot for reference to plot name + >>> a.return_display_names() # has display name for new plot + [...] + >>> a.remove_display_name(plot.name) + >>> a.return_display_names() # should be empty again + [] :param args: Any number of display names to remove. - :type args: str list + :type args: list of `str`_ """ for a in args: if a in self.display_names: @@ -3983,10 +4094,18 @@ def remove_display_name(self, *args): def cgm(self, file, mode='w'): """ + .. deprecated:: 2.6.1 + + Exporting images to CGM format is no longer supported. + To generate an image from the canvas, see + :py:func:`vcs.Canvas.Canvas.png` or :py:func:`vcs.Canvas.Canvas.svg` + Export an image in CGM format. :param file: Filename to save :param mode: Ignored. + + .. pragma: skip-doctest REMOVE WHEN IT WORKS AGAIN! """ if mode != 'w': @@ -3996,8 +4115,7 @@ def cgm(self, file, mode='w'): return self.backend.cgm(file) def clear(self, *args, **kargs): - """ - Clears all the VCS displays on a page (i.e., the VCS Canvas object). + """Clears all the VCS displays on a page (i.e., the VCS Canvas object). :Example: @@ -4040,8 +4158,7 @@ def clear(self, *args, **kargs): return def close(self, *args, **kargs): - """ - Close the VCS Canvas. It will not deallocate the VCS Canvas object. + """Close the VCS Canvas. It will not deallocate the VCS Canvas object. To deallocate the VCS Canvas, use the destroy method. :Example: @@ -4063,8 +4180,7 @@ def close(self, *args, **kargs): return a def destroy(self): - """ - Destroy the VCS Canvas. It will deallocate the VCS Canvas object. + """Destroy the VCS Canvas. It will deallocate the VCS Canvas object. :Example: @@ -4084,15 +4200,28 @@ def destroy(self): gc.collect() def change_display_graphic_method(self, display, type, name): - """ - Changes the type and graphic method of a plot. + """Changes the type and graphic method of a plot. + + :Example: + + .. doctest:: canvas_change_display_graphic_method + + >>> a=vcs.init() + >>> cdgm=a.change_display_graphic_method # alias long name + >>> array=[range(10) for _ in range(10)] + >>> disp=a.plot(array) + >>> a.show('boxfill') # list boxfill names + *******************Boxfill Names List********************** + ... + *******************End Boxfill Names List********************** + >>> cdgm(disp, 'boxfill', 'polar') # change graphics method :param display: Display to change. :param type: New graphics method type. :param name: Name of new graphics method. - :type display: str or vcs.displayplot.Dp - :type name: str - :type type: str + :type display: `str`_ or vcs.displayplot.Dp + :type name: `str`_ + :type type: `str`_ """ if isinstance(display, (str, unicode)): @@ -4103,9 +4232,12 @@ def change_display_graphic_method(self, display, type, name): def get_selected_display(self): """ - .. deprecated:: 2.0 + .. attention:: + + This function does not currently work. + It will be implemented in the future. - This function is no longer supported. + .. pragma: skip-doctest REMOVE WHEN IT WORKS AGAIN! """ return self.canvas.get_selected_display(*()) @@ -4113,8 +4245,7 @@ def plot_annotation(self, *args): self.canvas.plot_annotation(*args) def flush(self, *args): - """ - The flush command executes all buffered X events in the queue. + """The flush command executes all buffered X events in the queue. :Example: @@ -4129,8 +4260,7 @@ def flush(self, *args): return self.backend.flush(*args) def geometry(self, *args): - """ - The geometry command is used to set the size and position of the VCS canvas. + """The geometry command is used to set the size and position of the VCS canvas. :Example: @@ -4155,17 +4285,33 @@ def geometry(self, *args): return a def canvasinfo(self, *args, **kargs): - """ - Obtain the current attributes of the VCS Canvas window. + """Obtain the current attributes of the VCS Canvas window. + + :Example: - :returns: Dictionary with keys: "mapstate" (whether the canvas is opened), "height", "width", "depth", "x", "y" + .. doctest:: canvas_canvasinfo + + >>> a=vcs.init() + >>> ci=a.canvasinfo() + >>> keys=a.canvasinfo().keys() + >>> keys.sort() + >>> for key in keys: + ... print key, str(ci[key]) + depth ... + height ... + mapstate ... + width ... + x ... + y ... + + :returns: Dictionary with keys: "mapstate" (whether the canvas is opened), + "height", "width", "depth", "x", "y" :rtype: dict """ return self.backend.canvasinfo(*args, **kargs) def getcontinentstype(self, *args): - """ - Retrieve continents type from VCS; either an integer between 0 and 11 or the + """Retrieve continents type from VCS; either an integer between 0 and 6 or the path to a custom continentstype. :Example: @@ -4173,10 +4319,12 @@ def getcontinentstype(self, *args): .. doctest:: canvas_getcontinentstype >>> a=vcs.init() - >>> cont_type = a.getcontinentstype() # Get the continents type + >>> a.setcontinentstype(6) + >>> a.getcontinentstype() # Get the continents type + 6 - :returns: An int between 1 and 0, or the path to a custom continentstype - :rtype: int or system filepath + :returns An int between 0 and 6, or the path to a custom continentstype + :rtype: `int`_ or system filepath """ try: return self._continents @@ -4184,8 +4332,7 @@ def getcontinentstype(self, *args): return None def pstogif(self, filename, *opt): - """ - In some cases, the user may want to save the plot out as a gif image. This + """In some cases, the user may want to save the plot out as a gif image. This routine allows the user to convert a postscript file to a gif file. :Example: @@ -4196,18 +4343,15 @@ def pstogif(self, filename, *opt): >>> array = [range(1, 11) for _ in range(1, 11)] >>> a.plot(array) - >>> a.pstogif('filename.ps') # convert the postscript file to a gif file (l=landscape) + >>> a.pstogif('filename.ps') # convert the postscript file to a gif file >>> a.pstogif('filename.ps','l') # convert the postscript file to a gif file (l=landscape) >>> a.pstogif('filename.ps','p') # convert the postscript file to a gif file (p=portrait) :param filename: String name of the desired output file - :type filename: str + :type filename: `str`_ :param opt: One of 'l' or 'p', indicating landscape or portrait mode, respectively. - :type opt: str - - :returns: ??? - :rtype: ??? + :type opt: `str`_ """ from os import popen @@ -4243,17 +4387,12 @@ def grid(self, *args): than the graphics method. This will also be used for animating plots over the third and fourth dimensions. + .. attention:: - :Example: - - .. doctest:: canvas_grid - - >>> a=vcs.init() - >>> a.grid(12,12,0,71,0,45) - - .. admonition:: Not Yet Implemented + This function does not currently work. + It will be implemented in the future. - :py:func`vcs.Canvas.grid`_ does not work. + .. pragma: skip-doctest REMOVE WHEN IT WORKS AGAIN! """ p = self.canvas.grid(*args) @@ -4261,8 +4400,7 @@ def grid(self, *args): return p def landscape(self, width=-99, height=-99, x=-99, y=-99, clear=0): - """ - Change the VCS Canvas orientation to Landscape. + """Change the VCS Canvas orientation to Landscape. .. note:: @@ -4293,21 +4431,15 @@ def landscape(self, width=-99, height=-99, x=-99, y=-99, clear=0): >>> a.landscape(x=100, y = 200) # Change to landscape and set the x and y screen position >>> a.landscape(width = 400, height = 337, x=100, y = 200, clear=1) # landscape with more settings - :param width: Width of the canvas, in pixels - :type width: int - - :param height: Height of the canvas, in pixels - :type height: int + %s + %s :param x: Unused - :type x: int + :type x: `int`_ :param y: Unused - :type y: int - - :param clear: Indicates the canvas should be cleared (1), - or should not be cleared (0), when orientation is changed. - :type clear: int + :type y: `int`_ + %s """ if (self.orientation() == 'landscape'): return @@ -4338,16 +4470,11 @@ def landscape(self, width=-99, height=-99, x=-99, y=-99, clear=0): l = self.backend.landscape(*args) return l + landscape.__doc__ = landscape.__doc__ % (xmldocs.canvas_width, xmldocs.canvas_height, xmldocs.canvas_clear) def listelements(self, *args): - """ - Returns a Python list of all the VCS class objects. - - The list that will be returned: - ['1d', '3d_dual_scalar', '3d_scalar', '3d_vector', 'boxfill', 'colormap', 'display', 'fillarea', - 'font', 'fontNumber', 'isofill', 'isoline', 'line', 'list', 'marker', 'meshfill', 'projection', - 'scatter', 'taylordiagram', 'template', 'textcombined', 'textorientation', 'texttable', - 'vector', 'xvsy', 'xyvsy', 'yxvsx'] + """Returns a sorted Python list of all VCS object names, or a list of + names of objects of the given type. :Example: @@ -4357,8 +4484,12 @@ def listelements(self, *args): >>> a.listelements() ['1d', '3d_dual_scalar', '3d_scalar', ...] - :returns: A list of string names of all VCS class objects - :rtype: list + :param args: A string containing the name of a VCS object type, or None + :type args: `str`_ or `None`_ + + :returns: If args is None, returns a list of string names of all VCS objects. + If args is a string name of a VCS object + :rtype: `list`_ """ f = vcs.listelements L = sorted(f(*args)) @@ -4366,19 +4497,28 @@ def listelements(self, *args): return L def updateorientation(self, *args): - """ - .. deprecated:: 2.0 + """Takes a string 'portrait' or 'landscape' and updates a Canvas object's + orientation accordingly. + + :param args: String with value 'landscape' or 'portrait' + :type args: `str`_ + + .. attention:: + + This function does not currently work. + It will be implemented in the future. Use :func:`landscape` or :func:`portrait` instead. + + .. pragma: skip-doctest REMOVE WHEN IT WORKS AGAIN! """ a = self.canvas.updateorientation(*args) return a def open(self, width=None, height=None, **kargs): - """ - Open VCS Canvas object. This routine really just manages the VCS canvas. It will - popup the VCS Canvas for viewing. It can be used to display the VCS Canvas. + """Open VCS Canvas object. This routine really just manages the VCS canvas. + It can be used to display the VCS Canvas. :Example: @@ -4388,28 +4528,34 @@ def open(self, width=None, height=None, **kargs): >>> a.open() >>> a.open(800,600) - :param width: Integer representing the desire width of the opened window in pixels - :type width: int - - :param height: Integer representing the desire height of the opened window in pixels - :type height: int + %s + %s """ a = self.backend.open(width, height, **kargs) return a + open.__doc__ = open.__doc__ % (xmldocs.canvas_width, xmldocs.canvas_height) def canvasid(self, *args): - """ - Get the ID of this canvas. + """Get the ID of this canvas. + This ID number is found at the top of the VCS Canvas, + as part of its title. + + :Example: + + .. doctest:: canvas_canvasid + + >>> a=vcs.init() + >>> cid = a.canvasid() # store the canvas id - This ID number is found at the top of the VCS Canvas, as part of its title. + :returns: The ID of the canvas on which canvasid() is called. + :rtype: int """ return self._canvas_id def portrait(self, width=-99, height=-99, x=-99, y=-99, clear=0): - """ - Change the VCS Canvas orientation to Portrait. + """Change the VCS Canvas orientation to Portrait. .. note:: @@ -4429,11 +4575,8 @@ def portrait(self, width=-99, height=-99, x=-99, y=-99, clear=0): >>> a.portrait(x=100, y = 200) # Change to portrait and set the x and y screen position >>> a.portrait(width = 337, height = 400, x=100, y = 200, clear=1) # portrait, with more specifications - :param width: Width to set the canvas to (in pixels) - :type width: int - - :param height: Height to set the canvas to (in pixels) - :type height: int + %s + %s :param x: Unused. :type x: None @@ -4441,9 +4584,7 @@ def portrait(self, width=-99, height=-99, x=-99, y=-99, clear=0): :param y: Unused. :type y: None - :param clear: 0: Do not clear the canvas when orientation is changed. - 1: clear the canvas when orientation is changed. - :type clear: int + %s """ if (self.orientation() == 'portrait'): return @@ -4475,9 +4616,10 @@ def portrait(self, width=-99, height=-99, x=-99, y=-99, clear=0): return p + portrait.__doc__ = portrait.__doc__ % (xmldocs.canvas_width, xmldocs.canvas_height, xmldocs.canvas_clear) + def ffmpeg(self, movie, files, bitrate=1024, rate=None, options=None): - """ - MPEG output from a list of valid files. + """MPEG output from a list of valid files. Can output to more than just mpeg format. .. note:: @@ -4498,38 +4640,46 @@ def ffmpeg(self, movie, files, bitrate=1024, rate=None, options=None): >>> v = f('v') # use the data file to create a cdms2 slab >>> u = f('u') # use the data file to create a cdms2 slab >>> png_files = [] # for saving file names to make the mpeg - >>> plots = [] # for saving plots for later reference >>> for i in range(10): # create a number of pngs to use for an mpeg ... a.clear() ... if (i%2): - ... plots.append(a.plot(u,v)) + ... a.plot(u,v) ... else: - ... plots.append(a.plot(v,u)) + ... a.plot(v,u) ... a.png('my_png__%i' % i) ... png_files.append('my_png__%i.png' % i) - >>> a.ffmpeg('mymovie.mpeg',png_files) # generates from list of files - True - >>> a.ffmpeg('mymovie.mpeg',files="my_png__[0-9]*\.png") # generate from files with name matching regex + + + + + + + + + + + >>> a.ffmpeg('m1.mpeg',png_files) # using list of files True - >>> a.ffmpeg('mymovie.mpeg',png_files,bitrate=512) # generates mpeg at 512kbit + >>> a.ffmpeg('m2.mpeg',png_files,bitrate=512) # 512kbit rate True - >>> a.ffmpeg('mymovie.mpeg',png_files,rate=50) # generates movie with 50 frame per second + >>> a.ffmpeg('m3.mpeg',png_files,rate=50) # 50 frames/second True :param movie: Output video file name - :type movie: str + :type movie: `str`_ - :param files: String file name - :type files: str, list, or tuple + :param files: String name of a file, + or a list or tuple of multiple file names + :type files: `str`_, `list`_, or :py:class:`tuple` :param rate: Desired output framerate - :type rate: str + :type rate: `str`_ :param options: Additional FFMPEG arguments - :type options: str + :type options: `str`_ :returns: The output string generated by ffmpeg program - :rtype: str + :rtype: `str`_ """ args = ["ffmpeg", "-y"] @@ -4611,20 +4761,42 @@ def ffmpeg(self, movie, files, bitrate=1024, rate=None, options=None): return result == 0 def getantialiasing(self): + """Returns the current antialiasing rate for the canvas. + + :Example: + + .. doctest:: canvas_getantialiasing + + >>> a=vcs.init() + >>> a.setantialiasing(0) # turn off antialiasing + >>> a.getantialiasing() # will return current antialiasing rate + 0 + + :return: antialiasing rate for the canvas + :rtype: int + """ return self.backend.getantialiasing() def setantialiasing(self, antialiasing): - """ - Set antialiasing rate. + """Sets the antialiasing rate for the canvas. + + :Example: + + .. doctest:: canvas_setantialiasing - :param antialiasing: Integer from 0-64, representing the antialising rate (0 means no antialiasing). - :type antialiasing: int + >>> a=vcs.init() + >>> a.setantialiasing(20) + >>> a.getantialiasing() + 20 + + :param antialiasing: Integer from 0-64, representing the antialising + rate (0 means no antialiasing). + :type antialiasing: `int`_ """ self.backend.setantialiasing(antialiasing) def setbgoutputdimensions(self, width=None, height=None, units='inches'): - """ - Sets dimensions for output in bg mode. + """Sets dimensions for output in bg mode. :Example: @@ -4634,14 +4806,9 @@ def setbgoutputdimensions(self, width=None, height=None, units='inches'): >>> a.setbgoutputdimensions(width=11.5, height= 8.5) # US Legal >>> a.setbgoutputdimensions(width=21, height=29.7, units='cm') # A4 - :param width: Float representing the desired width of the output, using the specified unit of measurement - :type width: float - - :param height: Float representing the desired height of the output, using the specified unit of measurement. - :type height: float - - :param units: One of ['inches', 'in', 'cm', 'mm', 'pixel', 'pixels', 'dot', 'dots']. Defaults to 'inches'. - :type units: str + %s + %s + %s """ if units not in [ 'inches', 'in', 'cm', 'mm', 'pixel', 'pixels', 'dot', 'dots']: @@ -4656,38 +4823,45 @@ def setbgoutputdimensions(self, width=None, height=None, units='inches'): self.bgY = H return # display ping + setbgoutputdimensions.__doc__ = setbgoutputdimensions.__doc__ % (xmldocs.output_width, xmldocs.output_height, + xmldocs.output_units) def put_png_on_canvas( self, filename, zoom=1, xOffset=0, yOffset=0, units="percent", fitToHeight=True, *args, **kargs): - """ - Display a PNG file on the canvas + """Display a PNG file on the canvas :Example: - :: + .. doctest:: manageElements_put_png_on_canvas - a=vcs.init() - # Put a png on Canvas - a.put_on_png_on_canvas("path.png",zoom=1, xOffset=0, yOffset=0, units="percent", fitToHeight=True) + >>> a=vcs.init() + >>> array=[range(10) for i in range(10)] + >>> a.plot(array) + + >>> a.png("bars.png") # make a png named 'bars.png' + >>> a.clear() # clear the bars off the canvas + >>> a.put_png_on_canvas("bars.png") # put 'bars.png' on canvas -:param file: Input image filename -:type file: str + :param file: Input image filename + :type file: `str`_ -:param zoom: scale factor -:type zoom: int + :param zoom: scale factor + :type zoom: `int`_ -:param xOffset: Horizontal Offset -:type xOffset: float + :param xOffset: Horizontal Offset + :type xOffset: float -:param yOffset: Vertical Offset -:type yOffset: float + :param yOffset: Vertical Offset + :type yOffset: float -:param units: Offsets units percent or pixels -:type units" str + :param units: Specifies the units used for x and y Offsets. + One of ['percent','pixels']. + :type units: `str`_ -:param fitToHeight: fits the picture (before scaling) to the canvas full height, if False then use png original size -:type fitToHeight: bool + :param fitToHeight: If True, fits the picture (before scaling) to the canvas full height, + if False then use png original size. + :type fitToHeight: bool """ self.backend.put_png_on_canvas( filename, @@ -4701,8 +4875,7 @@ def put_png_on_canvas( def png(self, file, width=None, height=None, units=None, draw_white_background=True, **args): - """ - PNG output, dimensions set via setbgoutputdimensions + """PNG output, dimensions set via setbgoutputdimensions :Example: @@ -4714,19 +4887,13 @@ def png(self, file, width=None, height=None, >>> a.png('example') # Overwrite a png file - :param file: Output image filename - :type file: str - - :param width: Float representing the desired width of the output png, using the specified unit of measurement - :type width: float - - :param height: Float representing the desired height of the output png, using the specified unit of measurement - :type height: float - - :param units: One of ['inches', 'in', 'cm', 'mm', 'pixel', 'pixels', 'dot', 'dots']. Defaults to 'inches'. - :type units: str + %s + %s + %s + %s - :param draw_white_background: Boolean value indicating if the background should be white. Defaults to True. + :param draw_white_background: Boolean value indicating if the + background should be white. Defaults to True. :type draw_white_background: bool """ base = os.path.dirname(file) @@ -4742,11 +4909,11 @@ def png(self, file, width=None, height=None, width, height, units) return self.backend.png( file, W, H, units, draw_white_background, **args) + png.__doc__ = png.__doc__ % (xmldocs.output_file, xmldocs.output_width, xmldocs.output_height, xmldocs.output_units) def pdf(self, file, width=None, height=None, units='inches', textAsPaths=True): - """ - PDF output is another form of vector graphics. + """PDF output is another form of vector graphics. .. note:: @@ -4764,18 +4931,10 @@ def pdf(self, file, width=None, height=None, units='inches', >>> a.pdf('example', width=11.5, height= 8.5) # US Legal >>> a.pdf('example', width=21, height=29.7, units='cm') # A4 - :param file: Desired string name of the output file - :type file: str - - :param width: Integer specifying the desired width of the output, measured in the chosen units - :type width: int - - :param height: Integer specifying the desired height of the output, measured in the chosen units - :type height: int - - :param units: Must be one of ['inches', 'in', 'cm', 'mm', 'pixel', 'pixels', 'dot', 'dots']. - Default is 'inches'. - :type units: str + %s + %s + %s + %s :param textAsPaths: Specifies whether to render text objects as paths. :type textAsPaths: bool @@ -4791,11 +4950,11 @@ def pdf(self, file, width=None, height=None, units='inches', if not file.split('.')[-1].lower() in ['pdf']: file += '.pdf' return self.backend.pdf(file, width=W, height=H, units=units, textAsPaths=textAsPaths) + pdf.__doc__ = pdf.__doc__ % (xmldocs.output_file, xmldocs.output_width, xmldocs.output_height, xmldocs.output_units) def svg(self, file, width=None, height=None, units='inches', textAsPaths=True): - """ - SVG output is another form of vector graphics. + """SVG output is another form of vector graphics. .. note:: @@ -4813,17 +4972,10 @@ def svg(self, file, width=None, height=None, units='inches', >>> a.svg('example', width=11.5, height= 8.5) # US Legal >>> a.svg('example', width=21, height=29.7, units='cm') # A4 - :param file: - :type file: - - :param width: Float to set width of output SVG, in specified unit of measurement - :type width: float - - :param height: Float to set height of output SVG, in specified unit of measurement - :type height: float - - :param units: One of ['inches', 'in', 'cm', 'mm', 'pixel', 'pixels', 'dot', 'dots']. Deafults to 'inches'. - :type units: str + %s + %s + %s + %s :param textAsPaths: Specifies whether to render text objects as paths. :type textAsPaths: bool @@ -4839,6 +4991,7 @@ def svg(self, file, width=None, height=None, units='inches', if not file.split('.')[-1].lower() in ['svg']: file += '.svg' return self.backend.svg(file, width=W, height=H, units=units, textAsPaths=textAsPaths) + svg.__doc__ = svg.__doc__ % (xmldocs.output_file, xmldocs.output_width, xmldocs.output_height, xmldocs.output_units) def _compute_margins( self, W, H, top_margin, bottom_margin, right_margin, left_margin, dpi): @@ -4938,8 +5091,20 @@ def _compute_margins( return top_margin, bottom_margin, right_margin, left_margin def isopened(self): - """ - Returns a boolean value indicating whether the canvas is opened or not. + """Returns a boolean value indicating whether the canvas is opened or not. + + :Example: + + .. doctest:: convas_isopened + + >>> a=vcs.init() + >>> a.isopened() # canvas defaults to being closed + False + >>> array=[range(10) for _ in range(10)] + >>> a.plot(array) + + >>> a.isopened() # plotting opened the canvas + True :returns: A boolean value indicating whether the Canvas is opened (1), or closed (0) :rtype: bool @@ -5020,18 +5185,18 @@ def _compute_width_height(self, width, height, units, ps=False): return W, H def postscript(self, file, mode='r', orientation=None, width=None, height=None, units='inches', textAsPaths=True): - """ - Postscript output is another form of vector graphics. It is larger than its CGM output + """Postscript output is another form of vector graphics. It is larger than its CGM output counter part, because it is stored out in ASCII format. - There are two modes for saving a postscript file: `Append' (a) mode appends postscript - output to an existing postscript file; and `Replace' (r) mode overwrites an existing + There are two modes for saving a postscript file: 'Append' (a) mode appends postscript + output to an existing postscript file; and 'Replace' (r) mode overwrites an existing postscript file with new postscript output. The default mode is to overwrite an existing - postscript file (i.e. mode (r)). + postscript file. .. note:: - The textAsPaths parameter preserves custom fonts, but text can no longer be edited in the file + The textAsPaths parameter preserves custom fonts, but text can no + longer be edited in the file :Example: @@ -5048,21 +5213,15 @@ def postscript(self, file, mode='r', orientation=None, width=None, height=None, >>> a.postscript('example', width=11.5, height= 8.5) # US Legal (default) >>> a.postscript('example', width=21, height=29.7, units='cm') # A4 - :param file: String name of the desired output file - :type file: str - + %s :param mode: The mode in which to open the file. One of 'r' or 'a'. - :type mode: str - - :param orientation: Deprecated. - :type orientation: None - - :param width: Desired width of the postscript output, in the specified unit of measurement - :type width: int + When mode is 'r', file will be opened in replace mode. + When mode is 'a', file will be opened in append mode. + :type mode: `str`_ - :param height: Desired height of the postscript output, in the specified unit of measurement - :type height: int - :type units: str + %s + %s + %s :param textAsPaths: Specifies whether to render text objects as paths. :type textAsPaths: bool @@ -5095,16 +5254,49 @@ def postscript(self, file, mode='r', orientation=None, width=None, height=None, os.remove(psnm) else: shutil.move(psnm, file) + postscript.__doc__ = postscript.__doc__ % (xmldocs.output_file, xmldocs.output_width, xmldocs.output_height, + xmldocs.output_units) + def _scriptrun(self, *args): return vcs._scriptrun(*args) def scriptrun(self, aFile, *args, **kargs): + """ + Given the path to a script containing a VCS object, scriptrun + runs that script to build the object. + + :Example: + + .. doctest:: canvas_scriptrun + + >>> b=vcs.createboxfill('new_box') + >>> b.script('new_box') # json representation of 'new_box' + >>> bfs=vcs.listelements('boxfill') # list all boxfills + >>> i=bfs.index('new_box') + >>> bfs[i] # shows 'new_box' exists + 'new_box' + >>> vcs.removeobject(b) # remove new_box + 'Removed boxfill object new_box' + >>> bfs=vcs.listelements('boxfill') # list all boxfills + >>> try: + ... bfs.index('new_box') + ... except: + ... print ("boxfill 'new_box' doesn't exist") + boxfill 'new_box' doesn't exist + >>> vcs.scriptrun('new_box.json') # re-creates 'new_box' + >>> bfs=vcs.listelements('boxfill') # list all boxfills + >>> i=bfs.index('new_box') + >>> bfs[i] # shows 'new_box' exists (again) + 'new_box' + + :param aFile: String representing the path to a the script. + :type aFile: str + """ vcs.scriptrun(aFile, *args, **kargs) def setcolormap(self, name): - """ - It is necessary to change the colormap. This routine will change the VCS + """It is necessary to change the colormap. This routine will change the VCS color map. If the the visual display is 16-bit, 24-bit, or 32-bit TrueColor, then a redrawing @@ -5123,7 +5315,7 @@ def setcolormap(self, name): :param name: Name of the colormap to use - :type name: str + :type name: `str`_ """ # Don't update the VCS segment if there is no Canvas. This condition # happens in the initalize function for VCDAT only. This will cause a @@ -5138,8 +5330,7 @@ def setcolormap(self, name): return def setcolorcell(self, *args): - """ - Set a individual color cell in the active colormap. If default is + """Set a individual color cell in the active colormap. If default is the active colormap, then return an error string. If the the visul display is 16-bit, 24-bit, or 32-bit TrueColor, then a redrawing @@ -5171,8 +5362,7 @@ def setcolorcell(self, *args): return a def setcontinentsline(self, line="default"): - """ - One has the option of configuring the appearance of the lines used to + """One has the option of configuring the appearance of the lines used to draw continents by providing a VCS Line object. :Example: @@ -5186,34 +5376,54 @@ def setcontinentsline(self, line="default"): >>> a.setcontinentsline("default") # Use default line :param line: Line to use for drawing continents. Can be a string name of a line, or a VCS line object - :type line: str or :py:class:`vcs.line.Tl` + :type line: `str`_ or :py:class:`vcs.line.Tl` """ linename = VCS_validation_functions.checkLine(self, "continentsline", line) line = vcs.getline(linename) self._continents_line = line def getcontinentsline(self): + """Returns the continents line associated with the canvas. + + :Example: + + .. doctest:: canvas_getcontinentsline + + >>> a=vcs.init() + >>> cl=a.getcontinentsline() # should be the default + >>> cl.name + 'default' + + :return: The line object associated with the canvas's continents_line + property + :rtype: vcs.line.Tl + """ if self._continents_line is None: return vcs.getline("default") else: return self._continents_line def setcontinentstype(self, value): - """ - One has the option of using continental maps that are predefined or that + """One has the option of using continental maps that are predefined or that are user-defined. Predefined continental maps are either internal to VCS or are specified by external files. User-defined continental maps are specified by additional external files that must be read as input. The continents-type values are integers ranging from 0 to 11, where: - 0 signifies "No Continents" - 1 signifies "Fine Continents" - 2 signifies "Coarse Continents" - 3 signifies "United States" (with "Fine Continents") - 4 signifies "Political Borders" (with "Fine Continents") - 5 signifies "Rivers" (with "Fine Continents") - 6 uses a custom continent set + * 0 signifies "No Continents" + + * 1 signifies "Fine Continents" + + * 2 signifies "Coarse Continents" + + * 3 signifies "United States" (with "Fine Continents") + + * 4 signifies "Political Borders" (with "Fine Continents") + + * 5 signifies "Rivers" (with "Fine Continents") + + * 6 uses a custom continent set You can also pass a file by path. @@ -5222,13 +5432,15 @@ def setcontinentstype(self, value): .. doctest:: canvas_setcontinentstype >>> a=vcs.init() - >>> a.setcontinentstype(3) - >>> array = [range(1, 11) for _ in range(1, 11)] - >>> a.plot(array,'default','isofill','quick') + >>> a.setcontinentstype(4) # "Political Borders" + >>> import cdms2 # We need cdms2 to create a slab + >>> f = cdms2.open(vcs.sample_data+'/clt.nc') # open data file + >>> v = f('v') # use the data file to create a slab + >>> a.plot(v,'default','isofill','quick') # map with borders :param value: Integer representing continent type, as specified in function description - :type value: int + :type value: `int`_ """ continent_path = VCS_validation_functions.checkContinents(self, value) self._continents = value @@ -5252,8 +5464,7 @@ def _continentspath(self): def gif(self, filename='noname.gif', merge='r', orientation=None, geometry='1600x1200'): - """ - In some cases, the user may want to save the plot out as a gif image. This + """In some cases, the user may want to save the plot out as a gif image. This routine allows the user to save the VCS canvas output as a SUN gif file. This file can be converted to other gif formats with the aid of xv and other such imaging tools found freely on the web. @@ -5266,21 +5477,12 @@ def gif(self, filename='noname.gif', merge='r', orientation=None, file; 'Replace' (r) mode overwrites an existing gif file with new gif output. The default mode is to overwrite an existing gif file (i.e. mode (r)). - :Example: + .. attention:: - .. doctest:: canvas_gif + This function does not currently work. + It will be implemented in the future. - >>> a=vcs.init() - >>> array = [range(1, 11) for _ in range(1, 11)] - >>> a.plot(array) - - >>> a.gif(filename='example.gif', merge='a', orientation='l', geometry='800x600') - >>> a.gif('example') # overwrite existing gif file (default is merge='r') - >>> a.gif('example',merge='r') # overwrite existing gif file - >>> a.gif('example',merge='a') # merge gif image into existing gif file - >>> a.gif('example',orientation='l') # merge gif image into existing gif file with landscape orientation - >>> a.gif('example',orientation='p') # merge gif image into existing gif file with portrait orientation - >>> a.gif('example',geometry='600x500') # merge gif image into existing gif file and set gif geometry + .. pragma: skip-doctest REMOVE WHEN IT WORKS AGAIN! """ if orientation is None: orientation = self.orientation()[0] @@ -5297,8 +5499,7 @@ def gs(self, filename='noname.gs', device='png256', warnings.warn("Export to GhostScript is no longer supported", DeprecationWarning) def eps(self, file, mode='r', orientation=None, width=None, height=None, units='inches', textAsPaths=True): - """ - In some cases, the user may want to save the plot out as an Encapsulated + """In some cases, the user may want to save the plot out as an Encapsulated PostScript image. This routine allows the user to save the VCS canvas output as an Encapsulated PostScript file. This file can be converted to other image formats with the aid of xv and other @@ -5319,23 +5520,14 @@ def eps(self, file, mode='r', orientation=None, width=None, height=None, units=' >>> a.postscript('example', width=11.5, height= 8.5) # US Legal (default) >>> a.postscript('example', width=21, height=29.7, units='cm') # A4 - :param file: String name of the desired output file - :type file: str + %s :param mode: The mode in which to open the file. One of 'r' or 'a'. - :type mode: str - - :param orientation: Deprecated. - :type orientation: None - - :param width: Width of the output image, in the unit of measurement specified - :type width: float - - :param height: Height of the output image, in the unit of measurement specified - :type height: float + :type mode: `str`_ - :param units: One of ['inches', 'in', 'cm', 'mm', 'pixel', 'pixels', 'dot', 'dots']. Defaults to 'inches'. - :type units: str + %s + %s + %s """ ext = file.split(".")[-1] if ext.lower() != 'eps': @@ -5355,28 +5547,40 @@ def eps(self, file, mode='r', orientation=None, width=None, height=None, units=' os.popen("ps2epsi %s %s" % (tmpfile, file)).readlines() os.remove(tmpfile) + eps.__doc__ = eps.__doc__ % (xmldocs.output_file, xmldocs.output_width, xmldocs.output_height, xmldocs.output_units) def show(self, *args): return vcs.show(*args) - show.__doc__ = vcs.__doc__ + show.__doc__ = vcs.utils.show.__doc__ def isinfile(self, GM, file=None): - """ - Checks if a graphic method is stored in a file + """Checks if a graphic method is stored in a file if no file name is passed then looks into the initial.attributes file + :Example: + + .. doctest:: canvas_isinfile + + >>> a=vcs.init() + >>> box=a.getboxfill() + >>> a.scriptobject(box, 'deft_box.py') + >>> a.isinfile(box, 'deft_box.py') + 1 + :param GM: The graphics method to search for - :type GM: str + :type GM: `str`_ - :param file: String name of the file to search - :type file: str + :param file: String name of the file to search. + If None, VCS will search initial.attributes. + :type file: `str`_ - :returns: ??? - :rtype: ??? + :returns: 1 if the graphic method is stored in the file, nothing if it is not. + + .. pragma: skip-doctest This function needs to be fixed """ nm = GM.name gm = GM.g_name - key = gm + '_' + nm + '(' + key = key = gm + '_' + nm + '(' if file is None: file = os.path.join( os.path.expanduser("~"), @@ -5390,24 +5594,25 @@ def isinfile(self, GM, file=None): return def saveinitialfile(self): - """ - At start-up, VCS reads a script file named initial.attributes that + """At start-up, VCS reads a script file named initial.attributes that defines the initial appearance of the VCS Interface. Although not required to run VCS, this initial.attributes file contains many predefined settings to aid the beginning user of VCS. :Example: - .. doctest:: canvas_saveinitial + .. code-block:: python - >>> a=vcs.init() - >>> a.saveinitialfile() + a=vcs.init() + box=vcs.createboxfill('m_box') + line=vcs.createline('m_line') + a.saveinitialfile() # m_line, m_box saved for future sessions .. warning:: - This removes first ALL objects generated automatically - (i.e. whose name starts with '__') in order to preserve this, rename objects first - e.g: + This removes first ALL objects generated automatically (i.e. whose + name starts with '__'). To preserve these, rename objects first + e.g.: .. doctest:: canvas_saveinitial_warning @@ -5418,14 +5623,21 @@ def saveinitialfile(self): return vcs.saveinitialfile() def raisecanvas(self, *args): - """ - Raise the VCS Canvas to the top of all open windows. + """Raise the VCS Canvas to the top of all open windows. + + :Example: + + .. doctest:: canvas_raisecanvas + + >>> a=vcs.init() + >>> a.open() + >>> a.raisecanvas() # canvas should now be at the top + """ return self.backend.raisecanvas(*args) def islandscape(self): - """ - Indicates if VCS's orientation is landscape. + """Indicates if VCS's orientation is landscape. Returns a 1 if orientation is landscape. Otherwise, it will return a 0, indicating false (not in landscape mode). @@ -5442,7 +5654,7 @@ def islandscape(self): ... a.portrait() # Set VCS's orientation to portrait mode :returns: Integer indicating VCS is in landscape mode (1), or not (0) - :rtype: int + :rtype: `int`_ """ if (self.orientation() == 'landscape'): return 1 @@ -5450,8 +5662,7 @@ def islandscape(self): return 0 def isportrait(self): - """ - Indicates if VCS's orientation is portrait. + """Indicates if VCS's orientation is portrait. :Example: @@ -5474,24 +5685,26 @@ def isportrait(self): return 0 def getplot(self, Dp_name_src='default', template=None): - """ - .. deprecated:: 2.0 - - The getplot function is deprecated. Do not use it. - - This function will create a display plot object from an existing display + """This function will create a display plot object from an existing display plot object from an existing VCS plot. If no display plot name is given, then None is returned. :param Dp_name_src: String name of an existing display plot object - :type Dp_name_src: str + :type Dp_name_src: `str`_ :param template: The displayplot template to inherit from :type template: :returns: A VCS displayplot object :rtype: vcs.displayplot.Dp + + .. attention:: + + This function does not currently work. + It will be implemented in the future. + + .. pragma: skip-doctest REMOVE WHEN IT WORKS AGAIN! """ if not isinstance(Dp_name_src, str): raise ValueError('Error - The argument must be a string.') @@ -5511,14 +5724,15 @@ def getcolormap(self, Cp_name_src='default'): getcolormap.__doc__ = vcs.manageElements.getcolormap.__doc__ def addfont(self, path, name=""): - """ - Add a font to VCS. + """Add a font to VCS. :param path: Path to the font file you wish to add (must be .ttf) - :type path: str + :type path: `str`_ :param name: Name to use to represent the font. - :type name: str + :type name: `str`_ + + .. pragma: skip-doctest If you can reliably test it, please do. """ if not os.path.exists(path): raise ValueError('Error - The font path does not exists') @@ -5561,8 +5775,7 @@ def getfontname(self, number): getfontname.__doc__ = vcs.utils.getfontname.__doc__ def getfont(self, font): - """ - Get the font name/number associated with a font number/name + """Get the font name/number associated with a font number/name :Example: @@ -5581,11 +5794,13 @@ def getfont(self, font): [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16] :param font: The font name/number - :type font: int or str + :type font: `int`_ or `str`_ - :returns: If font parameter was a string, will return the integer associated with that string. - If font parameter was an integer, will return the string associated with that integer. - :rtype: int or str + :returns: If font parameter was a string, will return the integer + associated with that string. + If font parameter was an integer, will return the string + associated with that integer. + :rtype: `int`_ or str """ if isinstance(font, int): return self.getfontname(font) @@ -5595,14 +5810,26 @@ def getfont(self, font): raise vcsError("Error you must pass a string or int") def switchfonts(self, font1, font2): - """ - Switch the font numbers of two fonts. + """Switch the font numbers of two fonts. + + :Example: + + .. doctest:: canvas_switchfonts + + >>> a=vcs.init() + >>> maths1 = a.getfontnumber('Maths1') # store font number + >>> maths2 = a.getfontnumber('Maths2') # store font number + >>> a.switchfonts('Maths1','Maths2') # switch font numbers + >>> new_maths1 = a.getfontnumber('Maths1') + >>> new_maths2 = a.getfontnumber('Maths2') + >>> maths1 == new_maths2 and maths2 == new_maths1 # check + True :param font1: The first font - :type font1: int or str + :type font1: `int`_ or str :param font2: The second font - :type font2: int or str + :type font2: `int`_ or str """ if isinstance(font1, str): index1 = self.getfont(font1) @@ -5627,14 +5854,20 @@ def switchfonts(self, font1, font2): vcs.elements['fontNumber'][index2] = tmp def copyfontto(self, font1, font2): - """ - Copy 'font1' into 'font2'. + """Copy 'font1' into 'font2'. :param font1: Name/number of font to copy - :type font1: str or int + :type font1: `str`_ or int :param font2: Name/number of destination - :type font2: str or int + :type font2: `str`_ or `int`_ + + .. attention:: + + This function does not currently work. + It will be added in the future. + + .. pragma: skip-doctest REMOVE WHEN IT WORKS AGAIN! """ if isinstance(font1, str): index1 = self.getfont(font1) @@ -5657,19 +5890,24 @@ def copyfontto(self, font1, font2): return self.canvas.copyfontto(*(index1, index2)) def setdefaultfont(self, font): - """ - Sets the passed/def show font as the default font for vcs + """Sets the passed/def show font as the default font for vcs :param font: Font name or index to use as default - :type font: str or int + :type font: `str`_ or `int`_ + + .. attention:: + + This function does not currently work. + It will be implemented in the future. + + .. pragma: skip-doctest REMOVE WHEN IT WORKS AGAIN! """ if isinstance(font, str): font = self.getfont(font) return self.copyfontto(font, 1) def orientation(self, *args, **kargs): - """ - Return canvas orientation. + """Return canvas orientation. The current implementation does not use any args or kargs. @@ -5682,7 +5920,7 @@ def orientation(self, *args, **kargs): 'landscape' :returns: A string indicating the orientation of the canvas, i.e. 'landscape' or 'portrait' - :rtype: str + :rtype: `str`_ """ return self.backend.orientation(*args, **kargs) @@ -5691,16 +5929,52 @@ def getcolorcell(self, *args): getcolorcell.__doc__ = vcs.utils.getcolorcell.__doc__ def getcolormapname(self): - """ - Returns the name of the colormap this canvas is set to use by default. + """Returns the name of the colormap this canvas is set to use by default. + + :Example: + + .. doctest:: canvas_getcolormapname - To set that colormap, use :ref:`setcolormap`_. + >>> a=vcs.init() + >>> a.show('colormap') + *******************Colormap Names List********************** + ... + *******************End Colormap Names List********************** + >>> a.setcolormap('rainbow') # set canvas's default colormap + >>> a.getcolormapname() + 'rainbow' + + To set that colormap, use :py:func:`setcolormap`. """ if self.colormap is None: return vcs._colorMap return self.colormap def dummy_user_action(self, *args, **kargs): + """Given args and kargs, prints the arguments and keyword arguments + associated with those parameters. + + Use this function to test what args and kargs are, if you're unsure. + + :Example: + + .. doctest:: canvas_dummy_user_action + + >>> a=vcs.init() + >>> dua=a.dummy_user_action # alias long name + >>> dua("falafel", 37, the_answer=42) + Arguments: ('falafel', 37) + Keywords: {'the_answer': 42} + + + :param args: Any number of arguments, without a keyword specifier. + :type args: any + + :param kargs: Any number of keyword arguments, associated with any + number of data (i.e. kwd1="a string", kwd2=42). + :type kargs: any + + """ print 'Arguments:', args print 'Keywords:', kargs return None diff --git a/vcs/Pboxeslines.py b/vcs/Pboxeslines.py index 7833bcf14..b948bf578 100755 --- a/vcs/Pboxeslines.py +++ b/vcs/Pboxeslines.py @@ -33,7 +33,7 @@ class Pbl(object): - ''' + """ The Template text object allows the manipulation of line type, width, and color index. This class is used to define a line table entry used in VCS, or it @@ -42,7 +42,7 @@ class Pbl(object): :Example: -:: + :: # Basic Usage Overview: @@ -84,7 +84,7 @@ class Pbl(object): ln.type='dash-dot' # Same as ln.type=4 ln.type='long-dash' -''' + """ ########################################################################## # # # Initialize the line attributes. # diff --git a/vcs/VCS_validation_functions.py b/vcs/VCS_validation_functions.py index 4819e0843..33c898dcb 100644 --- a/vcs/VCS_validation_functions.py +++ b/vcs/VCS_validation_functions.py @@ -556,7 +556,7 @@ def checkBoolean(self, name, value): def checkFuzzyBoolean(self, name, value): - """Checks if a value can be interpreted as true or false. + __doc__ = """Checks if a value can be interpreted as true or false. Accepted values are %s. """ % fuzzy_boolean_valid_value_string diff --git a/vcs/__init__.py b/vcs/__init__.py index ea9ad0798..117e2f0f7 100755 --- a/vcs/__init__.py +++ b/vcs/__init__.py @@ -45,7 +45,6 @@ control of your plot that is needed for the truly perfect plot. Once you've customized them, you can also save them out for later use, and distribute them to other users. - """ _doValidation = True @@ -251,42 +250,35 @@ canvaslist = [] -def init(mode=1, pause_time=0, call_from_gui=0, size=None, - backend="vtk", geometry=None, bg=None): - """ - Initialize and construct a VCS Canvas object. +def init(mode=1, pause_time=0, call_from_gui=0, size=None, backend="vtk", + geometry=None, bg=None): + """Initialize and construct a VCS Canvas object. :Example: - :: - - import vcs - - # Portrait orientation of 1 width per 2 height - portrait = vcs.init(size=.5) - # also accepts "usletter" - letter = vcs.init(size="letter") - a4 = vcs.init(size="a4") - - import vtk - # Useful for embedding VCS inside another application - my_win = vtk.vtkRenderWindow() - embedded = vcs.init(backend=my_win) - - dict_init = vcs.init(geometry={"width": 1200, "height": 600}) - tuple_init = vcs.init(geometry=(1200, 600)) + .. doctest:: vcs_init - bg_canvas = vcs.init(bg=True) + >>> import vcs + >>> portrait = vcs.init(size=.5) # Portrait of 1 width per 2 height + >>> letter = vcs.init(size="letter") # also accepts "usletter" + >>> a4 = vcs.init(size="a4") + >>> import vtk + >>> my_win = vtk.vtkRenderWindow() # To embed VCS in other applications + >>> embedded = vcs.init(backend=my_win) + >>> dict_init = vcs.init(geometry={"width": 1200, "height": 600}) + >>> tuple_init = vcs.init(geometry=(1200, 600)) + >>> bg_canvas = vcs.init(bg=True) :param size: Aspect ratio for canvas (width / height) :param backend: Which VCS backend to use :param geometry: Size (in pixels) you want the canvas to be. - :param bg: Initialize a canvas to render in "background" mode (without displaying a window) + :param bg: Initialize a canvas to render in "background" mode (without + displaying a window) :type size: float or case-insensitive str - :type backend: str, `vtk.vtkRenderWindow` + :type backend: str, :py:class:`vtk.vtkRenderWindow` :type geometry: dict or tuple :type bg: bool - :return: an initialized canvas + :return: An initialized canvas :rtype: vcs.Canvas.Canvas """ canvas = Canvas.Canvas( diff --git a/vcs/animate_helper.py b/vcs/animate_helper.py index 67291822d..68a8b4df7 100644 --- a/vcs/animate_helper.py +++ b/vcs/animate_helper.py @@ -28,15 +28,6 @@ class animate_obj_old(object): See the `animation GUI documentation`_ .. _animation GUI documentation: http://www-pcmdi.llnl.gov/software/vcs - - :Example: - - .. doctest:: animate_helper_obj_old - - >>> a=vcs.init() - >>> a.plot(array,'default','isofill','quick') - >>> a.animate() - """ ########################################################################## diff --git a/vcs/boxfill.py b/vcs/boxfill.py index ae9d0fac7..7771e92b1 100755 --- a/vcs/boxfill.py +++ b/vcs/boxfill.py @@ -131,15 +131,13 @@ def process_src(nm, code): class Gfb(object): - __doc__ = """ - The boxfill graphics method (Gfb) displays a two-dimensional data array - by surrounding each data value by a colored grid box. + __doc__ = """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. - .. describe:: General use of a boxfill: .. code-block:: python @@ -305,84 +303,104 @@ class Gfb(object): * Attribute descriptions: + * Universally considered attributes: + + .. py:attribute:: boxfill_type (str) + + Type of boxfill legend. One of 'linear', 'log10', or 'custom'. + See examples above for usage. + Relevant attributes per type noted in attribute descriptions. - .. py:attribute:: boxfill_type (str) + .. py:attribute:: missing (int) - Type of boxfill legend. One of 'linear', 'log10', or 'custom'. See examples above for usage. + Color to use for missing value or values not in defined ranges. - .. py:attribute:: level_1 (float) + * boxfill_type 'linear'/'log10' relevant attributes: - Used in conjunction with boxfill_type linear/log10. Sets the value of the legend's first level + .. py:attribute:: level_1 (float) - .. py:attribute:: level_2 (float) + Used in conjunction with boxfill_type linear/log10. + Sets the value of the legend's first level - Used in conjunction with boxfill_type linear/log10, sets the value of the legend's end level + .. py:attribute:: level_2 (float) - .. py:attribute:: color_1 (float) + Used in conjunction with boxfill_type linear/log10, + sets the value of the legend's end level. - Used in conjunction with boxfill_type linear/log10, sets the legend's color range first value + .. py:attribute:: color_1 (float) - .. py:attribute:: color_2 (float) + Used in conjunction with boxfill_type linear/log10, + sets the first value of the legend's color range. - Used in conjunction with boxfill_type linear/log10, sets the legend's color range lasst value + .. py:attribute:: color_2 (float) - .. py:attribute:: levels (list of floats) + Used in conjunction with boxfill_type linear/log10. + Sets the last value of the legend's color range. - Used in conjunction for 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. + .. py:attribute:: legend ({float:str}) - .. py:attribte:: fillareacolors (list) + Used in conjunction with boxfill_type linear/log10. + replaces the legend values in the dictionary keys with their + associated string. - Used in conjunction for boxfill_type custom colors to use for each level + .. py:attribute:: ext_1 (str) - .. py:attribute:: legend ({float:str}) + Draws an extension arrow on right side of a boxfill + (values less than first range value) - Used in conjunction with boxfill_type linear/log10, replaces the - legend values in the dictionary keys with their associated string. + .. py:attribute:: ext_2 (str) - .. py:attribute:: ext_1 (str) + Draws an extension arrow on left side of a boxfill + (values greater than last range value) - Draws an extension arrow on right side (values less than first range value) + * boxfill_type 'custom' relevant attributes: - .. py:attribute:: ext_2 (str) + .. py:attribute:: levels (list of floats) - Draws an extension arrow on left side (values greater than last range value) + 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. - .. py:attribute:: missing (int) + .. py:attribute:: fillareacolors (list) - Color to use for missing value or values not in defined ranges. + Used in conjunction with boxfill_type custom. + Specifies colors to use for each level. + + * More boxfill attributes: %s + + .. pragma: skip-doctest """ % xmldocs.graphics_method_core # noqa def rename(self, newname): - """ - Renames the boxfill in the VCS name table. + """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. + 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: .. doctest:: gfb_rename - >>> b=vcs.createboxfill() - >>> b.name - '...' - >>> vcs.listelements('boxfill') # list will include the name show above - [...] + >>> b=vcs.createboxfill('bar') + >>> l=vcs.listelements('boxfill') # list of boxfills + >>> 'bar' in l # shows l contains new boxfill + True >>> b.rename('foo') - >>> b.name - 'foo' - >>> vcs.listelements('boxfill') # list will include 'foo', but not the old name - [...'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 :param newname: The new name you want given to the boxfill - :type newname: + :type newname: str """ if newname == "default": raise Exception( @@ -820,12 +838,12 @@ def _setdatawc_y2(self, value): def colors(self, color1=0, color2=255): self.color_1 = color1 self.color_2 = color2 - colors.__doc__ = xmldocs.colorsdoc + colors.__doc__ = xmldocs.colorsdoc % {"name": "boxfill", "data": "array"} def exts(self, ext1='n', ext2='y'): self.ext_1 = ext1 self.ext_2 = ext2 - exts.__doc__ = xmldocs.extsdoc + exts.__doc__ = xmldocs.extsdoc.format(name="boxfill", data="array") # # Doesn't make sense to inherit. This would mean more coding in C. # I put this code back. @@ -834,39 +852,59 @@ def exts(self, ext1='n', ext2='y'): def xticlabels(self, xtl1='', xtl2=''): self.xticlabels1 = xtl1 self.xticlabels2 = xtl2 - xticlabels.__doc__ = xmldocs.xticlabelsdoc + xticlabels.__doc__ = xmldocs.xticlabelsdoc % {"name": "boxfill", "data": "f('u')"} def xmtics(self, xmt1='', xmt2=''): self.xmtics1 = xmt1 self.xmtics2 = xmt2 - xmtics.__doc__ = xmldocs.xmticsdoc + xmtics.__doc__ = xmldocs.xmticsdoc.format(name="boxfill") def yticlabels(self, ytl1='', ytl2=''): self.yticlabels1 = ytl1 self.yticlabels2 = ytl2 - yticlabels.__doc__ = xmldocs.yticlabelsdoc + yticlabels.__doc__ = xmldocs.yticlabelsdoc % {"name": "boxfill", "data": "f('u')"} def ymtics(self, ymt1='', ymt2=''): self.ymtics1 = ymt1 self.ymtics2 = ymt2 - ymtics.__doc__ = xmldocs.ymticsdoc + ymtics.__doc__ = xmldocs.xmticsdoc.format(name="boxfill") def datawc(self, dsp1=1e20, dsp2=1e20, dsp3=1e20, dsp4=1e20): - """ - -""" self.datawc_y1 = dsp1 self.datawc_y2 = dsp2 self.datawc_x1 = dsp3 self.datawc_x2 = dsp4 - datawc.__doc__ = xmldocs.datawcdoc + datawc.__doc__ = xmldocs.datawcdoc.format(name="boxfill") def xyscale(self, xat='linear', yat='linear'): self.xaxisconvert = xat self.yaxisconvert = yat - xyscale.__doc__ = xmldocs.xyscaledoc % (('boxfill',) * 2) + xyscale.__doc__ = xmldocs.xyscaledoc.format(name='boxfill') def getlevels(self, varmin, varmax): + """Given a minimum and a maximum, will generate levels for the boxfill + starting at varmin and ending at varmax. + + :Example: + + .. doctest:: boxfill_getlevels + + >>> b=vcs.createboxfill() + >>> lvls = b.getlevels(0,100) # 257 levels from 0-100 + >>> b.levels = list(lvls) # set boxfill's levels attribute + + :param varmin: The smallest number desired for the boxfill's levels + attribute. + :type varmin: float + + :param varmax: The largest number desired for the boxfill's levels + attribute. + :type varmin: float + + :return: A numpy array of 257 floats, evenly distributed from varmin to + varmax. + :rtype: numpy.ndarray + """ if self.boxfill_type == "custom": return self.levels @@ -944,7 +982,7 @@ def getlegendlabels(self, levels): def list(self): if (self.name == '__removed_from_VCS__'): raise ValueError('This instance has been removed from VCS.') - print "", "----------Boxfill (Gfb) member (attribute) listings ----------" + print "---------- Boxfill (Gfb) member (attribute) listings ----------" print "graphics method =", self.g_name print "name =", self.name print "projection =", self.projection @@ -980,7 +1018,7 @@ def list(self): print "ext_1 = ", self.ext_1 print "ext_2 = ", self.ext_2 print "missing = ", self.missing - list.__doc__ = xmldocs.listdoc + list.__doc__ = xmldocs.listdoc.format(name="boxfill", parent="") ########################################################################### # # # Script out primary boxfill graphics method in VCS to a file. # @@ -1115,7 +1153,7 @@ def script(self, script_filename, mode='a'): fp.write("%s.legend = %s\n" % (unique_name, self.legend)) fp.write("%s.ext_1 = '%s'\n" % (unique_name, self.ext_1)) fp.write("%s.ext_2 = '%s'\n" % (unique_name, self.ext_2)) - fp.write("%s.missing = %g\n" % (unique_name, self.missing)) + fp.write("%s.missing = %s\n" % (unique_name, repr(self.missing))) fp.write( "%s.datawc_calendar = %g\n" % (unique_name, self.datawc_calendar)) diff --git a/vcs/colormap.py b/vcs/colormap.py index 1ccf43b0d..763e72a48 100644 --- a/vcs/colormap.py +++ b/vcs/colormap.py @@ -1,5 +1,16 @@ """ # Colormap (Cp) module + + .. _list: https://docs.python.org/2/library/functions.html#list + .. _tuple: https://docs.python.org/2/library/functions.html#tuple + .. _dict: https://docs.python.org/2/library/stdtypes.html#mapping-types-dict + .. _None: https://docs.python.org/2/library/constants.html?highlight=none#None + .. _str: https://docs.python.org/2/library/functions.html?highlight=str#str + .. _bool: https://docs.python.org/2/library/functions.html?highlight=bool#bool + .. _float: https://docs.python.org/2/library/functions.html?highlight=float#float + .. _int: https://docs.python.org/2/library/functions.html?highlight=float#int + .. _long: https://docs.python.org/2/library/functions.html?highlight=float#long + .. _file: https://docs.python.org/2/library/functions.html?highlight=open#file """ ########################################################################## # # @@ -231,6 +242,7 @@ class Cp(object): # R, G, B values range from 0 to 100, where 0 is low intensity and 100 is highest intensity cp.color=17,0,0,100 + .. pragma: skip-doctest """ __slots__ = ["s_name", "name", "_name", "index", "_index"] @@ -251,7 +263,7 @@ def getindex(self): return self._index def setindex(self, value): - # usually we cannot set index, but there is an exception for lading + # usually we cannot set index, but there is an exception for loading # from json files if not(isinstance(value, dict) and value.keys() == [u'data', ]): raise Exception("invalid") @@ -300,31 +312,30 @@ def __init__(self, Cp_name, Cp_name_src='default'): # Set a colorcell RGB def setcolorcell(self, index, red, green, blue, alpha=100.): - """ - Sets the R,G,B,A values of a colorcell + """Sets the R,G,B,A values of a colorcell :Example: .. doctest:: colormap_setcolorcell >>> a = vcs.init() # Create a vcs Canvas - >>> cmap = a.createcolormap('example', 'default') # Create a colormap + >>> cmap = a.createcolormap('scc_cmap') # Create a colormap >>> cmap.setcolorcell(40,80,95,1.0) # Set RGBA values :param index: Integer from 0-255. - :type index: int + :type index: `int`_ :param red: Integer from 0-255 representing the concentration of red in the colorcell. - :type red: int + :type red: `int`_ :param green: Integer from 0-255 representing the concentration of green in the colorcell. - :type green: int + :type green: `int`_ :param blue: Integer from 0-255 representing the concentration of blue in the colorcell. - :type blue: int + :type blue: `int`_ :param alpha: Float representing the percentage of opacity in the colorcell. - :type alpha: float + :type alpha: `float`_ """ self.index[index] = [red, green, blue, alpha] @@ -338,15 +349,15 @@ def getcolorcell(self, index): .. doctest:: colormap_getcolorcell >>> a=vcs.init() # Create a vcs Canvas - >>> cmap = a.createcolormap('example', 'default') # Create a colormap + >>> cmap = a.createcolormap('gcc_cmap') # Create a colormap >>> cmap.getcolorcell(1) # Get RGBA values - [0, 0, 0, 100.0] + [26, 0, 33, 100] :param index: Index of a cell in the colormap. Must be an integer from 0-255. - :type index: int + :type index: `int`_ :returns: A list containing the red, green, blue, and alpha values of the colorcell at the given index. - :rtype: list + :rtype: `list`_ """ return self.index[index] @@ -358,10 +369,11 @@ def getcolorcell(self, index): def list(self): if (self.name == '__removed_from_VCS__'): raise ValueError('This instance has been removed from VCS.') - print "", "----------Colormap (Cp) member (attribute) listings ----------" + print "---------- Colormap (Cp) member (attribute) listings ----------" print "secondary method =", self.s_name print "name =", self.name print "index =", self.index + list.__doc__ = xmldocs.listdoc.format(name="colormap", parent="") ########################################################################## # # diff --git a/vcs/colors.py b/vcs/colors.py index 825ca03cc..afc8b5cd7 100644 --- a/vcs/colors.py +++ b/vcs/colors.py @@ -8,10 +8,10 @@ def matplotlib2vcs(cmap, vcs_name=None): Optional second argument: vcs_name, name of the resulting vcs colormap :param cmap: A matplotlib colormap or string name of a matplotlib colormap - :type cmap: str , matplotlib colormap + :type cmap: :py:class:`str` , matplotlib.cm :param vcs_name: String to set the name of the generated VCS colormap - :type vcs_name: str + :type vcs_name: :py:class:`str` :returns: A VCS colormap object :rtype: vcs.colormap.Cp diff --git a/vcs/displayplot.py b/vcs/displayplot.py index aca5b79d0..036f4a9d3 100755 --- a/vcs/displayplot.py +++ b/vcs/displayplot.py @@ -25,6 +25,7 @@ # import VCS_validation_functions import vcs +from xmldocs import listdoc class Dp(object): @@ -78,6 +79,8 @@ class Dp(object): p1.g_name='quick' # List of all the array names p1.array=['a1'] + + .. pragma: skip-doctest """ __slots__ = ["name", "_name", @@ -298,9 +301,23 @@ def __init__(self, Dp_name, Dp_name_src='default', parent=None): ########################################################################## def list(self): + """Lists the current values of object attributes + + :Example: + + .. doctest:: displayplot_listdoc + + >>> a=vcs.init() + >>> array = [range(10) for _ in range(10)] + >>> obj=a.getboxfill() # default boxfill + >>> dsp = a.plot(obj,array) # store displayplot + >>> dsp.list() + ---------- ... ---------- + ... + """ if (self.name == '__removed_from_VCS__'): raise ValueError('This instance has been removed from VCS.') - print "", "----------Display Plot (Dp) member (attribute) listings ----------" + print "---------- Display Plot (Dp) member (attribute) listings ----------" print "Display plot method =", self.s_name print "name =", self.name print "off =", self.off diff --git a/vcs/dv3d.py b/vcs/dv3d.py index 74d5219a9..b10651c37 100644 --- a/vcs/dv3d.py +++ b/vcs/dv3d.py @@ -1,20 +1,43 @@ -''' -Created on Jun 18, 2014 - -@author: tpmaxwel -''' - +""" +If in interact mode (see :func:`vcs.Canvas.Canvas.interact`), these attributes can be configured interactively, via the +method described in the **Interact Mode** section of the attribute description. +""" +# @author: tpmaxwel import VCS_validation_functions import multiprocessing import vcs import time from DV3D.ConfigurationFunctions import ConfigManager +from xmldocs import toggle_surface, toggle_volume, xslider, yslider, zslider, verticalscaling, scalecolormap, \ + scaletransferfunction, toggleclipping, isosurfacevalue, scaleopacity, basemapopacity, camera, scriptdocs class Gfdv3d(object): - """ - - """ + __doc__ = """ + Gfdv3d is class from which Gf3Dvector, Gf3Dscalar, and Gf3DDualScalar + inherit. It sets up properties and functions common to all of the 3d + graphics method objects. + + Attributes + ---------- + + %s + %s + %s + %s + %s + %s + %s + %s + %s + %s + %s + %s + %s + + .. pragma: skip-doctest + """ % (toggle_surface, toggle_volume, xslider, yslider, zslider, verticalscaling, scalecolormap, + scaletransferfunction, toggleclipping, isosurfacevalue, scaleopacity, basemapopacity, camera) __slots__ = [ '__doc__', 'name', @@ -115,6 +138,7 @@ def script(self, script_filename=None, mode=None): f = open(script_filename, mode) vcs.utils.dumpToJson(self, f) f.close() + # can we add a scriptdocs[g_name] here and have each derived class pick up the documentation correctly? def __init__(self, Gfdv3d_name, Gfdv3d_name_src='default'): if not isinstance(Gfdv3d_name, str): @@ -223,7 +247,7 @@ def initDefaultState(self): self.cfgManager.initDefaultState() def list(self): - print ' ---------- DV3D (Gfdv3d) member (attribute) listings ---------' + print '---------- DV3D (Gfdv3d) member (attribute) listings ----------' print 'name =', self.name print 'axes =', self.axes for pname in self.parameter_names: @@ -232,14 +256,18 @@ def list(self): class Gf3Dvector(Gfdv3d): - + """ + Gf3Dvector + """ def __init__(self, Gfdv3d_name, Gfdv3d_name_src='default'): self.g_name = '3d_vector' Gfdv3d.__init__(self, Gfdv3d_name, Gfdv3d_name_src=Gfdv3d_name_src) class Gf3Dscalar(Gfdv3d): - + """ + Gf3Dscalar + """ def __init__(self, Gfdv3d_name, Gfdv3d_name_src='default'): self.g_name = '3d_scalar' Gfdv3d.__init__(self, Gfdv3d_name, Gfdv3d_name_src=Gfdv3d_name_src) @@ -247,7 +275,9 @@ def __init__(self, Gfdv3d_name, Gfdv3d_name_src='default'): class Gf3DDualScalar(Gfdv3d): - + """ + Gf3DDualScalar + """ def __init__(self, Gfdv3d_name, Gfdv3d_name_src='default'): self.g_name = '3d_dual_scalar' Gfdv3d.__init__(self, Gfdv3d_name, Gfdv3d_name_src=Gfdv3d_name_src) diff --git a/vcs/fillarea.py b/vcs/fillarea.py index d4267df22..5bffbbb24 100755 --- a/vcs/fillarea.py +++ b/vcs/fillarea.py @@ -25,7 +25,7 @@ import VCS_validation_functions import vcs import genutil -from xmldocs import scriptdocs +from xmldocs import scriptdocs, listdoc def getmember(self, name): @@ -99,15 +99,13 @@ def process_src(nm, code): # # -# Fillarea (Tm) Class. # +# Fillarea (Tf) Class. # # # class Tf(object): - - """ - The Fillarea class object allows the user to edit fillarea attributes, including + """The Fillarea class allows the user to edit fillarea attributes, including fillarea interior style, style index, and color index. This class is used to define an fillarea table entry used in VCS, or it @@ -192,6 +190,7 @@ class Tf(object): # List of FloatTypes fa.y=[[.5,.4,.3], [.2,.1,0]] + .. pragma: skip-doctest """ __slots__ = [ 'name', @@ -464,7 +463,7 @@ def __init__(self, Tf_name=None, Tf_name_src='default'): def list(self): if (self.name == '__removed_from_VCS__'): raise ValueError('This instance has been removed from VCS.') - print "", "----------Fillarea (Tf) member (attribute) listings ----------" + print "---------- Fillarea (Tf) member (attribute) listings ----------" print "secondary method =", self.s_name print "name =", self.name print "style =", self.style @@ -480,6 +479,7 @@ def list(self): print "y =", self.y print "projection =", self.projection print "colormap =", self.colormap + list.__doc__ = listdoc.format(name="fillarea", parent="") # # diff --git a/vcs/isofill.py b/vcs/isofill.py index 4fbbb9562..c30e7261b 100755 --- a/vcs/isofill.py +++ b/vcs/isofill.py @@ -306,7 +306,10 @@ class Gfi(object): .. describe:: Attribute descriptions: %s - %s""" % (xmldocs.graphics_method_core, xmldocs.isofill_doc) + %s + + .. pragma: skip-doctest + """ % (xmldocs.graphics_method_core, xmldocs.isofill_doc) colormap = VCS_validation_functions.colormap __slots__ = [ @@ -677,12 +680,12 @@ def __init__(self, Gfi_name, Gfi_name_src='default'): def colors(self, color1=16, color2=239): self.fillareacolors = range(color1, color2) - colors.__doc__ = xmldocs.colorsdoc + colors.__doc__ = xmldocs.colorsdoc % {"name": "isofill", "data": "array"} def exts(self, ext1='n', ext2='y'): self.ext_1 = ext1 self.ext_2 = ext2 - exts.__doc__ = xmldocs.extsdoc + exts.__doc__ = xmldocs.extsdoc.format(name="isofill", data="array") # # Doesn't make sense to inherit. This would mean more coding in C. # I put this code back. @@ -691,37 +694,37 @@ def exts(self, ext1='n', ext2='y'): def xticlabels(self, xtl1='', xtl2=''): self.xticlabels1 = xtl1 self.xticlabels2 = xtl2 - xticlabels.__doc__ = xmldocs.xticlabelsdoc + xticlabels.__doc__ = xmldocs.xticlabelsdoc % {"name": "isofill", "data": "f('u')"} def xmtics(self, xmt1='', xmt2=''): self.xmtics1 = xmt1 self.xmtics2 = xmt2 - xmtics.__doc__ = xmldocs.xmticsdoc + xmtics.__doc__ = xmldocs.xmticsdoc.format(name="isofill") def yticlabels(self, ytl1='', ytl2=''): self.yticlabels1 = ytl1 self.yticlabels2 = ytl2 - yticlabels.__doc__ = xmldocs.yticlabelsdoc + yticlabels.__doc__ = xmldocs.yticlabelsdoc % {"name": "isofill", "data": "f('u')"} def ymtics(self, ymt1='', ymt2=''): self.ymtics1 = ymt1 self.ymtics2 = ymt2 - ymtics.__doc__ = xmldocs.ymticsdoc + ymtics.__doc__ = xmldocs.xmticsdoc.format(name="isofill") def datawc(self, dsp1=1e20, dsp2=1e20, dsp3=1e20, dsp4=1e20): self.datawc_y1 = dsp1 self.datawc_y2 = dsp2 self.datawc_x1 = dsp3 self.datawc_x2 = dsp4 - datawc.__doc__ = xmldocs.datawcdoc + datawc.__doc__ = xmldocs.datawcdoc.format(name="isofill") def xyscale(self, xat='', yat=''): self.xaxisconvert = xat self.yaxisconvert = yat - xyscale.__doc__ = xmldocs.xyscaledoc % (('isofill',) * 2) + xyscale.__doc__ = xmldocs.xyscaledoc.format(name='isofill') def list(self): - print "", "----------Isofill (Gfi) member (attribute) listings ----------" + print "---------- Isofill (Gfi) member (attribute) listings ----------" print "graphics method =", self.g_name print "name =", self.name print "projection =", self.projection @@ -752,7 +755,7 @@ def list(self): print "fillareapixelscale = ", self.fillareapixelscale print "levels = ", self.levels print "legend = ", self.legend - list.__doc__ = xmldocs.listdoc + list.__doc__ = xmldocs.listdoc.format(name="isofill", parent="") # # diff --git a/vcs/isoline.py b/vcs/isoline.py index f67dd0e4e..e5a28f4e6 100755 --- a/vcs/isoline.py +++ b/vcs/isoline.py @@ -388,37 +388,48 @@ class Gi(object): * Attribute descriptions: .. py:attribute:: label (str) - Turn on/off labels on isolines + + Turn on/off labels on isolines .. py:attribute:: labelskipdistance (float) - Minimum distance between isoline labels + + Minimum distance between isoline labels .. py:attribute:: labelbackgroundcolors ([float]) - Background color for isoline labels + + Background color for isoline labels .. py:attribute:: labelbackgroundopacities ([float]) - Background opacity for isoline labels + + Background opacity for isoline labels .. py:attribute:: level ([float,...]) - Isocountours to display + + Isocountours to display .. py:attribute:: 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 + + Draw directional arrows + +-(0,1,2) Indicate none/clockwise/clokwise on y axis >0. + Clockwise on x axis positive negative value invert behaviour .. py:attribute:: scale ([float,...]) - Scales the directional arrow lengths + + Scales the directional arrow lengths .. py:attribute:: angle ([float,...]) - Directional arrows head angle + + Directional arrows head angle .. py:attribute:: spacing ([float,...]) - Scales spacing between directional arrows + + Scales spacing between directional arrows %s %s %s + + .. pragma: skip-doctest """ % (xmldocs.graphics_method_core, xmldocs.linesdoc, xmldocs.textsdoc) colormap = VCS_validation_functions.colormap @@ -740,10 +751,12 @@ def _setline(self, value): line = property(_getline, _setline) def setLineAttributes(self, mixed): - ''' + """ Add either a (linetype, 1, 1) or (linetype, linecolor, linewidth) based on if mixed[i] is a linetype or a line object name. - ''' + + .. pragma: skip-doctest TODO: add a setLineAttributes example + """ import queries types = [] colors = [] @@ -981,39 +994,39 @@ def xticlabels(self, xtl1='', xtl2=''): # specific_options_doc self.xticlabels1 = xtl1 self.xticlabels2 = xtl2 - xticlabels.__doc__ = xmldocs.xticlabelsdoc + xticlabels.__doc__ = xmldocs.xticlabelsdoc % {"name": "isoline", "data": "f('u')"} def xmtics(self, xmt1='', xmt2=''): self.xmtics1 = xmt1 self.xmtics2 = xmt2 - xmtics.__doc__ = xmldocs.xmticsdoc + xmtics.__doc__ = xmldocs.xmticsdoc.format(name="isoline") def yticlabels(self, ytl1='', ytl2=''): self.yticlabels1 = ytl1 self.yticlabels2 = ytl2 - yticlabels.__doc__ = xmldocs.yticlabelsdoc + yticlabels.__doc__ = xmldocs.yticlabelsdoc % {"name": "isoline", "data": "f('u')"} def ymtics(self, ymt1='', ymt2=''): self.ymtics1 = ymt1 self.ymtics2 = ymt2 - ymtics.__doc__ = xmldocs.ymticsdoc + ymtics.__doc__ = xmldocs.xmticsdoc.format(name="isoline") def datawc(self, dsp1=1e20, dsp2=1e20, dsp3=1e20, dsp4=1e20): self.datawc_y1 = dsp1 self.datawc_y2 = dsp2 self.datawc_x1 = dsp3 self.datawc_x2 = dsp4 - datawc.__doc__ = xmldocs.datawcdoc + datawc.__doc__ = xmldocs.datawcdoc.format(name="isoline") def xyscale(self, xat='', yat=''): self.xaxisconvert = xat self.yaxisconvert = yat - xyscale.__doc__ = xmldocs.xyscaledoc % (('isoline',) * 2) + xyscale.__doc__ = xmldocs.xyscaledoc.format(name='isoline') def list(self): if (self.name == '__removed_from_VCS__'): raise ValueError('This instance has been removed from VCS.') - print "", "----------Isoline (Gi) member (attribute) listings ----------" + print "---------- Isoline (Gi) member (attribute) listings ----------" print "graphics method =", self.g_name print "name =", self.name print "projection =", self.projection @@ -1047,7 +1060,7 @@ def list(self): print "scale = ", self.scale print "angle = ", self.angle print "spacing = ", self.spacing - list.__doc__ = xmldocs.listdoc + list.__doc__ = xmldocs.listdoc.format(name="isoline", parent="") ########################################################################## # # diff --git a/vcs/line.py b/vcs/line.py index cae3b1d6c..4e653735f 100755 --- a/vcs/line.py +++ b/vcs/line.py @@ -25,7 +25,7 @@ import VCS_validation_functions import vcs import genutil -from xmldocs import scriptdocs +from xmldocs import scriptdocs, listdoc def process_src(nm, code): @@ -72,8 +72,7 @@ def process_src(nm, code): class Tl(object): - """ - The Line object allows the manipulation of line type, width, color index, + """The Line object allows the manipulation of line type, width, color index, view port, world coordinates, and (x,y) points. This class is used to define an line table entry used in VCS, or it @@ -84,23 +83,22 @@ class Tl(object): .. code-block:: python - # VCS Canvas Constructor - a=vcs.init() - # Show predefined line objects - a.show('line') - # Will list all the line attribute values - ln.list() - # Updates the VCS Canvas at user's request - a.update() + >>> a=vcs.init() # VCS Canvas Constructor + >>> a.show('line') # Show predefined line objects + *******************Line Names List********************** + ... + *******************End Line Names List********************** + >>> a.getline('red').list() # show properties of 'red' line + ---------- ... ---------- + ... + >>> a.update() # manually update canvas .. describe:: Create a new instance of line: .. code-block:: python - # Copies content of 'red' to 'new' - ln=a.createline('new','red') - # Copies content of 'default' to 'new' - ln=a.createline('new') + >>> ln=a.createline('new','red') # Copies 'red' to 'new' + >>> ln=a.createline('new2') # Copies 'default' to 'new2' .. describe:: Modify an existing line: @@ -108,55 +106,47 @@ class Tl(object): .. code-block:: python - ln=a.getline('red') + >>> ln=a.getline('red') * Set line color: .. code-block:: python - # Range from 1 to 256 - ln.color=100 + >>> ln.color=100 # Range from 1 to 256 * Set line width: .. code-block:: python - # Range from 1 to 300 - ln.width=100 + >>> ln.width=100 # Range from 1 to 300 * Specify the line type: .. code-block:: python - # Same as ln.type=0 - ln.type='solid' - # Same as ln.type=1 - ln.type='dash' - # Same as ln.type=2 - ln.type='dot' - # Same as ln.type=3 - ln.type='dash-dot' - # Same as ln.type=4 - ln.type='long-dash' + >>> ln.type='solid' # Same as ln.type=0 + >>> ln.type='dash' # Same as ln.type=1 + >>> ln.type='dot' # Same as ln.type=2 + >>> ln.type='dash-dot' # Same as ln.type=3 + >>> ln.type='long-dash' # Same as ln.type=4 * Set the graphics priority on the canvas: .. code-block:: python - ln.priority=1 - # FloatType [0,1]x[0,1] - ln.viewport=[0, 1.0, 0,1.0] - # FloatType [#,#]x[#,#] - ln.worldcoordinate=[0,1.0,0,1.0] + >>> ln.priority=1 + >>> ln.viewport=[0, 1.0, 0,1.0] # float [0,1]x[0,1] + >>> ln.worldcoordinate=[0,1.0,0,1.0] # float [#,#]x[#,#] * Set line x and y values: .. code-block:: python - # List of FloatTypes - ln.x=[[0,.1,.2], [.3,.4,.5]] - # List of FloatTypes - ln.y=[[.5,.4,.3], [.2,.1,0]] + >>> ln.x=[[0,.1,.2], [.3,.4,.5]] # List of floats + >>> ln.y=[[.5,.4,.3], [.2,.1,0]] # List of floats + + .. ln.x and ln.y above cause ln to be unplottable. Need a better example. + .. Use doctests in this class as a model for converting other class docstrings to use doctests. """ __slots__ = [ 's_name', @@ -386,7 +376,7 @@ def __init__(self, Tl_name, Tl_name_src='default'): def list(self): if (self.name == '__removed_from_VCS__'): raise ValueError('This instance has been removed from VCS.') - print "", "----------Line (Tl) member (attribute) listings ----------" + print "---------- Line (Tl) member (attribute) listings ----------" print "secondary method =", self.s_name print "name =", self.name print "type =", self.type @@ -399,6 +389,7 @@ def list(self): print "y =", self.y print "projection =", self.projection print "colormap =", self.colormap + list.__doc__ = listdoc.format(name="line", parent="") ########################################################################## # # @@ -406,9 +397,6 @@ def list(self): # # ########################################################################## def script(self, script_filename=None, mode=None): - """ - docstring moved to xmldocs -""" if (script_filename is None): raise ValueError( 'Error - Must provide an output script file name.') diff --git a/vcs/manageElements.py b/vcs/manageElements.py index 135f388ee..db4a22f76 100644 --- a/vcs/manageElements.py +++ b/vcs/manageElements.py @@ -1,8 +1,17 @@ -# This file aims at removing elets creation from dpeending on a Canvas, we will try to simply have -# b = vcs.createboxfill() -# rather than -# x=vcs.init() -# b=x.createboxfill() +""" + .. _list: https://docs.python.org/2/library/functions.html#list + .. _tuple: https://docs.python.org/2/library/functions.html#tuple + .. _dict: https://docs.python.org/2/library/stdtypes.html#mapping-types-dict + .. _None: https://docs.python.org/2/library/constants.html?highlight=none#None + .. _str: https://docs.python.org/2/library/functions.html?highlight=str#str + .. _bool: https://docs.python.org/2/library/functions.html?highlight=bool#bool + .. _float: https://docs.python.org/2/library/functions.html?highlight=float#float + .. _int: https://docs.python.org/2/library/functions.html?highlight=float#int + .. _long: https://docs.python.org/2/library/functions.html?highlight=float#long + .. _file: https://docs.python.org/2/library/functions.html?highlight=open#file + + .. pragma: skip-doctest +""" import vcs import boxfill import meshfill @@ -27,7 +36,40 @@ def check_name_source(name, source, typ): - """make sure it is a unique name for this type or generates a name for user""" + """Make sure it is a unique name for this type or generates a name for user. + + :Example: + + .. doctest:: manageElements_check_name_source + + >>> cns=vcs.check_name_source # alias for long function name + >>> vcs.show('boxfill') + *******************Boxfill Names List********************** + ... + *******************End Boxfill Names List********************** + >>> cns('NEW', 'quick', 'boxfill') # name 'NEW' should be available + ('NEW', 'quick') + >>> cns(None, 'default', 'boxfill') # generate unique boxfill name + ('__boxfill_...', 'default') + + :param name: Desired string name for an object of type *typ*, + inheriting from source object *source*. + If name is None, a unique name will be generated. + :type name: `str`_ or None + + :param source: Source from which the new object is meant to inherit. + Can be a VCS object or a string name of a VCS object. + :type source: `str`_ or VCS Object + + :param typ: String name of a VCS object type. + (e.g. 'boxfill', 'isofill', 'marker', etc.) + :type typ: str + + :returns: A tuple containing two strings: a unique name and a source name. + If *name* was provided and an object of type *typ* with that name + already exists, an error is raised. + :rtype: `tuple`_ + """ elts = vcs.listelements(typ) if name is None: rnd = random.randint(0, 1000000000000000) @@ -63,14 +105,14 @@ def check_name_source(name, source, typ): def createtemplate(name=None, source='default'): - """ - %s + """%s :param name: The name of the created object - :type name: str + :type name: `str`_ - :param source: The object to inherit from - :type source: a template or a string name of a template + :param source: The object to inherit from. + Can be a template, or a string name of a template + :type source: `str`_ or :class:`vcs.template.P` :returns: A template :rtype: vcs.template.P @@ -83,11 +125,10 @@ def createtemplate(name=None, source='default'): def gettemplate(Pt_name_src='default'): - """ - %s + """%s :param Pt_name_src: String name of an existing template VCS object - :type Pt_name_src: + :type Pt_name_src: `str`_ :returns: A VCS template object :rtype: vcs.template.P @@ -103,14 +144,14 @@ def gettemplate(Pt_name_src='default'): def createprojection(name=None, source='default'): - """ - %s + """%s :param name: The name of the created object - :type name: str + :type name: `str`_ - :param source: The object to inherit from - :type source: a projection or a string name of a projection + :param source: The object to inherit from. + Can be a projection, or a string name of a projection. + :type source: `str`_ or :class:`vcs.projection.Proj` :returns: A projection graphics method object :rtype: vcs.projection.Proj @@ -122,11 +163,10 @@ def createprojection(name=None, source='default'): def getprojection(Proj_name_src='default'): - """ - %s + """%s :param Proj_name_src: String name of an existing VCS projection object - :type Proj_name_src: str + :type Proj_name_src: `str`_ :returns: A VCS projection object :rtype: vcs.projection.Proj @@ -143,48 +183,32 @@ def getprojection(Proj_name_src='default'): def createboxfill(name=None, source='default'): - """ - %s + """%s :param name: The name of the created object - :type name: str + :type name: `str`_ - :param source: The object to inherit from - :type source: a boxfill or a string name of a boxfill + :param source: The object to inherit from. + can be a boxfill, or a string name of a boxfill. + :type source: `str`_ or :class:`vcs.boxfill.Gfb` :return: A boxfill graphics method object :rtype: vcs.boxfill.Gfb - - %s - %s - %s - %s - %s """ name, source = check_name_source(name, source, 'boxfill') return boxfill.Gfb(name, source) -createboxfill.__doc__ = createboxfill.__doc__ % ( - xmldocs.create_docs['boxfill'], - xmldocs.plot_keywords_doc, xmldocs.graphics_method_core, xmldocs.axesconvert, - xmldocs.create_GM_input, xmldocs.boxfill_output) +createboxfill.__doc__ = createboxfill.__doc__ % xmldocs.create_docs['boxfill'] def getboxfill(Gfb_name_src='default'): - """ - %s + """%s :param Gfb_name_src: String name of an existing boxfill VCS object - :type Gfb_name_src: str + :type Gfb_name_src: `str`_ :return: A pre-existing boxfill graphics method :rtype: vcs.boxfill.Gfb - - %s - %s - %s - %s - %s """ # Check to make sure the argument passed in is a STRING if not isinstance(Gfb_name_src, str): @@ -193,20 +217,18 @@ def getboxfill(Gfb_name_src='default'): if Gfb_name_src not in vcs.elements["boxfill"].keys(): raise "The boxfill method: '%s' does not seem to exist" return vcs.elements["boxfill"][Gfb_name_src] -getboxfill.__doc__ = getboxfill.__doc__ % ( - xmldocs.get_docs['boxfill'], xmldocs.plot_keywords_doc, xmldocs.graphics_method_core, xmldocs.axesconvert, - xmldocs.get_GM_input, xmldocs.boxfill_output) +getboxfill.__doc__ = getboxfill.__doc__ % xmldocs.get_docs['boxfill'] def createtaylordiagram(name=None, source='default'): - """ - %s + """%s :param name: The name of the created object - :type name: str + :type name: `str`_ - :param source: The object to inherit from - :type source: a taylordiagram or a string name of a + :param source: The object to inherit from. + Can be a a taylordiagram, or a string name of a taylordiagram. + :type source: `str`_ or :class:`vcs.taylor.Gtd` :returns: A taylordiagram graphics method object :rtype: vcs.taylor.Gtd @@ -229,11 +251,10 @@ def createtaylordiagram(name=None, source='default'): def gettaylordiagram(Gtd_name_src='default'): - """ - %s + """%s :param Gtd_name_src: String name of an existing taylordiagram VCS object - :type Gtd_name_src: str + :type Gtd_name_src: `str`_ :returns: A taylordiagram VCS object :rtype: vcs.taylor.Gtd @@ -253,14 +274,14 @@ def gettaylordiagram(Gtd_name_src='default'): def createmeshfill(name=None, source='default'): - """ - %s + """%s :param name: The name of the created object - :type name: str + :type name: `str`_ - :param source: The object to inherit from - :type source: a meshfill or a string name of a meshfill + :param source: The object to inherit from. + Can be a meshfill, or a string name of a meshfill. + :type source: `str`_ or :class:`vcs.meshfill.Gfm` :returns: A meshfill graphics method object :rtype: vcs.meshfill.Gfm @@ -271,11 +292,10 @@ def createmeshfill(name=None, source='default'): def getmeshfill(Gfm_name_src='default'): - """ - %s + """%s :param Gfm_name_src: String name of an existing meshfill VCS object - :type Gfm_name_src: str + :type Gfm_name_src: `str`_ :returns: A meshfill VCS object :rtype: vcs.meshfill.Gfm @@ -293,47 +313,32 @@ def getmeshfill(Gfm_name_src='default'): def createisofill(name=None, source='default'): - """ - %s + """%s :param name: The name of the created object - :type name: str + :type name: `str`_ - :param source: The object to inherit from - :type source: an isofill object, or string name of an isofill object + :param source: The object to inherit from. + Can be an isofill object, or string name of an isofill object. + :type source: `str`_ or :class:`vcs.isofill.Gfi` :returns: An isofill graphics method :rtype: vcs.isofill.Gfi - - %s - %s - %s - %s - %s """ name, source = check_name_source(name, source, 'isofill') return isofill.Gfi(name, source) -createisofill.__doc__ = createisofill.__doc__ % ( - xmldocs.create_docs['isofill'], xmldocs.plot_keywords_doc, xmldocs.graphics_method_core, - xmldocs.axesconvert, xmldocs.create_GM_input, xmldocs.isofill_output) +createisofill.__doc__ = createisofill.__doc__ % xmldocs.create_docs['isofill'] def getisofill(Gfi_name_src='default'): - """ - %s + """%s :param Gfi_name_src: String name of an existing isofill VCS object - :type Gfi_name_src: str + :type Gfi_name_src: `str`_ :returns: The specified isofill VCS object :rtype: vcs.isofill.Gfi - - %s - %s - %s - %s - %s """ # Check to make sure the argument passed in is a STRING @@ -343,53 +348,37 @@ def getisofill(Gfi_name_src='default'): if Gfi_name_src not in vcs.elements["isofill"]: raise ValueError("The isofill '%s' does not exists" % Gfi_name_src) return vcs.elements["isofill"][Gfi_name_src] -getisofill.__doc__ = getisofill.__doc__ % ( - xmldocs.get_docs['isofill'], xmldocs.plot_keywords_doc, xmldocs.graphics_method_core, xmldocs.axesconvert, - xmldocs.get_GM_input, xmldocs.isofill_output) +getisofill.__doc__ = getisofill.__doc__ % xmldocs.get_docs['isofill'] def createisoline(name=None, source='default'): - """ - %s + """%s :param name: The name of the created object - :type name: str + :type name: `str`_ - :param source: The object to inherit from - :type source: an isoline object, or string name of an isoline object + :param source: The object to inherit from. + Can be an isoline object, or string name of an isoline object. + :type source: `str`_ or :class:`vcs.isoline.Gi` :returns: An isoline graphics method object :rtype: vcs.isoline.Gi - - %s - %s - %s - %s - %s """ name, source = check_name_source(name, source, 'isoline') return isoline.Gi(name, source) -createisoline.__doc__ = createisoline.__doc__ % ( - xmldocs.create_docs['isoline'], xmldocs.plot_keywords_doc, xmldocs.graphics_method_core, xmldocs.axesconvert, - xmldocs.create_GM_input, xmldocs.isoline_output) +createisoline.__doc__ = createisoline.__doc__ % xmldocs.create_docs['isoline'] + def getisoline(Gi_name_src='default'): - """ - %s + """%s :param Gi_name_src: String name of an existing isoline VCS object - :type Gi_name_src: str + :type Gi_name_src: `str`_ :returns: The requested isoline VCS object :rtype: vcs.isoline.Gi - - %s - %s - %s - %s - %s """ # Check to make sure the argument passed in is a STRING @@ -398,17 +387,61 @@ def getisoline(Gi_name_src='default'): if Gi_name_src not in vcs.elements["isoline"]: raise ValueError("The isoline '%s' does not exists" % Gi_name_src) return vcs.elements["isoline"][Gi_name_src] -getisoline.__doc__ = getisoline.__doc__ % ( - xmldocs.get_docs['isoline'], xmldocs.plot_keywords_doc, xmldocs.graphics_method_core, xmldocs.axesconvert, - xmldocs.get_GM_input, xmldocs.isoline_output) +getisoline.__doc__ = getisoline.__doc__ % xmldocs.get_docs['isoline'] def create1d(name=None, source='default'): + """Creates a new :py:class:`vcs.unified1d.G1d` object called name, and inheriting from source. + + :Example: + + .. doctest:: manageElements_create1d + + >>> vcs.show('1d') + *******************1d Names List********************** + ... + *******************End 1d Names List********************** + >>> vcs.create1d() # inherits default, name generated + + >>> vcs.create1d("one_D") # inherits default, name "one_D" + + >>> vcs.create1d(source="one_D") # inherits from "one_D" + + + :param name: A string name for the 1d to be created. If None, a unique name will be created. + :type name: `str`_ + + :param source: A 1d object or string name of a 1d object from which the new 1d will inherit. + :type source: `str`_ or :py:class:`vcs.unified1D.G1d` + + :return: A new 1d object, inheriting from source. + :rtype: :py:class:`vcs.unified1D.G1d` + """ name, source = check_name_source(name, source, '1d') return unified1D.G1d(name, source) def get1d(name): + """Given name, returns a :py:class:`vcs.unified1d.G1d` from vcs with that name. + Unlike other VCS 'get' functions, name cannot be None when calling get1d(). + + :Example: + + .. doctest:: manageElements_get_1d + + >>> vcs.show('1d') + *******************1d Names List********************** + ... + *******************End 1d Names List********************** + >>> vcs.get1d('blue_yxvsx') + + + :param name: String name of a 1d in vcs. If there is no 1d with that name, an error will be raised. + :type name: `str`_ + + :return: A 1d from vcs with the given name. + :rtype: :py:class:`vcs.unified1d.G1d` + """ # Check to make sure the argument passed in is a STRING if not isinstance(name, str): raise vcsError('The argument must be a string.') @@ -419,24 +452,18 @@ def get1d(name): def createxyvsy(name=None, source='default'): - """ - %s + """%s :param name: The name of the created object - :type name: str + :type name: `str`_ - :param source: The object to inherit from - :type source: a xyvsy or a string name of a xyvsy + :param source: The object to inherit from. + Can be a xyvsy, or a string name of a xyvsy. + :type source: `str`_ or :class:`vcs.unified1D.G1d` :returns: A XYvsY graphics method object :rtype: vcs.unified1D.G1d - - %s - %s - %s - %s - %s """ try: gm = vcs.create1d(name, source) @@ -450,55 +477,38 @@ def createxyvsy(name=None, source='default'): raise ve gm.flip = True return gm -createxyvsy.__doc__ = createxyvsy.__doc__ % ( - xmldocs.create_docs['xyvsy'], xmldocs.plot_keywords_doc, xmldocs.graphics_method_core, xmldocs.axesconvert, - xmldocs.create_GM_input, xmldocs.xyvsy_output) +createxyvsy.__doc__ = createxyvsy.__doc__ % xmldocs.create_docs['xyvsy'] def getxyvsy(GXy_name_src='default'): - """ - %s + """%s :param GXy_name_src: String name of an existing Xyvsy graphics method - :type GXy_name_src: str + :type GXy_name_src: `str`_ :returns: An XYvsY graphics method object :rtype: vcs.unified1D.G1d - - %s - %s - %s - %s - %s """ gm = vcs.get1d(GXy_name_src) if gm.g_type != "xyvsy": # Already existed when name_src was created, most likely return vcs.get1d(GXy_name_src + "_xyvsy") return gm -getxyvsy.__doc__ = getxyvsy.__doc__ % ( - xmldocs.get_docs['xyvsy'], xmldocs.plot_keywords_doc, xmldocs.graphics_method_core, xmldocs.axesconvert, - xmldocs.get_GM_input, xmldocs.xyvsy_output) +getxyvsy.__doc__ = getxyvsy.__doc__ % xmldocs.get_docs['xyvsy'] def createyxvsx(name=None, source='default'): - """ - %s + """%s :param name: The name of the created object - :type name: str + :type name: `str`_ - :param source: The object to inherit from - :type source: a yxvsy or a string name of a yxvsy + :param source: The object to inherit from. + Can be a yxvsy, or a string name of a yxvsy. + :type source: `str`_ or :class:`vcs.unified1D.G1d` :returns: A YXvsX graphics method object :rtype: vcs.unified1D.G1d - - %s - %s - %s - %s - %s """ try: gm = vcs.create1d(name, source) @@ -511,54 +521,39 @@ def createyxvsx(name=None, source='default'): else: raise ve return gm -createyxvsx.__doc__ = createyxvsx.__doc__ % ( - xmldocs.create_docs['yxvsx'], xmldocs.plot_keywords_doc, xmldocs.graphics_method_core, xmldocs.axesconvert, - xmldocs.create_GM_input, xmldocs.yxvsx_output) +createyxvsx.__doc__ = createyxvsx.__doc__ % xmldocs.create_docs['yxvsx'] + def getyxvsx(GYx_name_src='default'): - """ - %s + """%s :param GYx_name_src: String name of an existing Yxvsx graphics method :type GYx_name_src: str :return: A Yxvsx graphics method object :rtype: vcs.unified1D.G1d - - %s - %s - %s - %s - %s """ gm = vcs.get1d(GYx_name_src) if gm.g_type != "yxvsx": return vcs.get1d(GYx_name_src + "_yxvsx") return gm -getyxvsx.__doc__ = getyxvsx.__doc__ % ( - xmldocs.get_docs['yxvsx'], xmldocs.plot_keywords_doc, xmldocs.graphics_method_core, xmldocs.axesconvert, - xmldocs.get_GM_input, xmldocs.yxvsx_output) +getyxvsx.__doc__ = getyxvsx.__doc__ % xmldocs.get_docs['yxvsx'] + def createxvsy(name=None, source='default'): - """ - %s + """%s :param name: The name of the created object - :type name: str + :type name: `str`_ - :param source: The object to inherit from - :type source: a xvsy or a string name of a xvsy + :param source: The object to inherit from. + Can be a xvsy, or a string name of a xvsy. + :type source: `str`_ or :class:`vcs.unified1D.G1d` :returns: A XvsY graphics method object :rtype: vcs.unified1D.G1d - - %s - %s - %s - %s - %s """ try: gm = vcs.create1d(name, source) @@ -571,45 +566,37 @@ def createxvsy(name=None, source='default'): else: raise ve return gm -createxvsy.__doc__ = createxvsy.__doc__ % ( - xmldocs.create_docs['xvsy'], xmldocs.plot_keywords_doc, xmldocs.graphics_method_core, xmldocs.axesconvert, - xmldocs.create_GM_input, xmldocs.xvsy_output) +createxvsy.__doc__ = createxvsy.__doc__ % xmldocs.create_docs['xvsy'] + def getxvsy(GXY_name_src='default'): - """ - %s + """%s :param GXY_name_src: String name of a 1d graphics method - :type GXY_name_src: str + :type GXY_name_src: `str`_ :returns: A XvsY graphics method object :rtype: vcs.unified1D.G1d - %s - %s - %s - %s - %s """ gm = vcs.get1d(GXY_name_src) # Deliberately yxvsx here; xvsy is just an alias if gm.g_type != "yxvsx": return vcs.get1d(GXY_name_src + "_xvsy") return gm -getxvsy.__doc__ = getxvsy.__doc__ % ( - xmldocs.get_docs['xvsy'], xmldocs.plot_keywords_doc, xmldocs.graphics_method_core, xmldocs.axesconvert, - xmldocs.get_GM_input, xmldocs.xvsy_output) +getxvsy.__doc__ = getxvsy.__doc__ % xmldocs.get_docs['xvsy'] + def createvector(name=None, source='default'): - """ - %s + """%s :param name: The name of the created object - :type name: str + :type name: `str`_ - :param source: The object to inherit from - :type source: a vector or a string name of a vector + :param source: The object to inherit from. + Can be a vector, or a string name of a vector. + :type source: `str`_ or :class:`vcs.vector.Gv` :returns: A vector graphics method object :rtype: vcs.vector.Gv @@ -620,11 +607,10 @@ def createvector(name=None, source='default'): def getvector(Gv_name_src='default'): - """ - %s + """%s :param Gv_name_src: String name of an existing vector VCS object - :type Gv_name_src: str + :type Gv_name_src: `str`_ :returns: A vector graphics method object :rtype: vcs.vector.Gv @@ -640,23 +626,17 @@ def getvector(Gv_name_src='default'): def createscatter(name=None, source='default'): - """ - %s + """%s :param name: The name of the created object - :type name: str + :type name: `str`_ - :param source: The object to inherit from - :type source: a scatter or a string name of a scatter + :param source: The object to inherit from. + Can be a scatter or, a string name of a scatter. + :type source: `str`_ or :class:`vcs.unified1D.G1d` :return: A scatter graphics method :rtype: vcs.unified1D.G1d - - %s - %s - %s - %s - %s """ try: gm = vcs.create1d(name, source) @@ -670,80 +650,69 @@ def createscatter(name=None, source='default'): raise ve gm.linewidth = 0 return gm -createscatter.__doc__ = createscatter.__doc__ % ( - xmldocs.create_docs['scatter'], xmldocs.plot_keywords_doc, xmldocs.graphics_method_core, xmldocs.axesconvert, - xmldocs.create_GM_input, xmldocs.scatter_output) +createscatter.__doc__ = createscatter.__doc__ % xmldocs.create_docs['scatter'] + def getscatter(GSp_name_src='default'): - """ - %s + """%s :param GSp_name_src: String name of an existing scatter VCS object. - :type GSp_name_src: str + :type GSp_name_src: `str`_ :returns: A scatter graphics method object :rtype: vcs.unified1D.G1d - - %s - %s - %s - %s - %s """ gm = vcs.get1d(GSp_name_src) if gm.g_type != "scatter": return vcs.get1d(GSp_name_src + "_scatter") return gm -getscatter.__doc__ = getscatter.__doc__ % ( - xmldocs.get_docs['scatter'], xmldocs.plot_keywords_doc, xmldocs.graphics_method_core, xmldocs.axesconvert, - xmldocs.get_GM_input, xmldocs.scatter_output) +getscatter.__doc__ = getscatter.__doc__ % xmldocs.get_docs['scatter'] + def createline(name=None, source='default', ltype=None, width=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None, projection=None): - """ - %s + """%s :param name: Name of created object - :type name: str + :type name: `str`_ :param source: a line, or string name of a line - :type source: str + :type source: `str`_ :param ltype: One of "dash", "dash-dot", "solid", "dot", or "long-dash". - :type ltype: str + :type ltype: `str`_ :param width: Thickness of the line to be created - :type width: int + :type width: `int`_ :param color: A color name from the `X11 Color Names list `_, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) - :type color: str or int + :type color: `str`_ or `int`_ :param priority: The layer on which the line will be drawn. - :type priority: int + :type priority: `int`_ :param viewport: 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas. - :type viewport: list of floats + :type viewport: `list`_ :param worldcoordinate: List of 4 floats (xmin, xmax, ymin, ymax) - :type worldcoordinate: list of floats + :type worldcoordinate: `list`_ :param x: List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1]. - :type x: list of floats + :type x: `list`_ :param y: List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3]. - :type y: list of floats + :type y: `list`_ :param projection: Specify a geographic projection used to convert x/y from spherical coordinates to 2D coordinates. - :type projection: str or projection object + :type projection: `str`_ or projection object :returns: A VCS line secondary method object :rtype: vcs.line.Tl - """ name, source = check_name_source(name, source, 'line') @@ -771,10 +740,30 @@ def createline(name=None, source='default', ltype=None, def setLineAttributes(to, l): - ''' - Set attributes linecolor, linewidth and linetype from line l. - l can be a line name defined in vcs.elements or a line object - ''' + """Set attributes linecolor, linewidth and linetype from line l on object to. + + :Example: + + .. doctest:: manageElements_setLineAttributes + + >>> vcs.show('line') + *******************Line Names List********************** + ... + *******************End Line Names List********************** + >>> new_isoline = vcs.createisoline('new_iso') + >>> vcs.setLineAttributes(new_isoline, 'continents') + >>> new_vector = vcs.createvector('new_vec') + >>> vcs.setLineAttributes(new_vector, 'continents') + >>> new_1d = vcs.create1d('new_1d', 'blue_yxvsx') + >>> vcs.setLineAttributes(new_1d, 'continents') + + :param to: A vector, 1d, or isoline object to set the properties of. + :type to: :class:`vcs.vector.Gv`, :class:`vcs.unified1d.G1d` + + :param l: l can be a line name defined in vcs.elements or a line object. + l will be used to set the properties of to. + :type l: :py:class:`vcs.line.Tl` or str + """ import queries line = None if (queries.isline(l)): @@ -785,45 +774,49 @@ def setLineAttributes(to, l): raise ValueError("Expecting a line object or a " + "line name defined in vcs.elements, got type " + type(l).__name__) - to.linecolor = line.color[0] - to.linewidth = line.width[0] - to.linetype = line.type[0] + if queries.isisoline(to): + to.linecolors = line.color + to.linewidths = line.width + to.linetypes = line.type + else: + to.linecolor = line.color[0] + to.linewidth = line.width[0] + to.linetype = line.type[0] def getline(name='default', ltype=None, width=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None): - """ - %s + """%s :param name: Name of created object - :type name: str + :type name: `str`_ :param ltype: One of "dash", "dash-dot", "solid", "dot", or "long-dash". - :type ltype: str + :type ltype: `str`_ :param width: Thickness of the line to be created - :type width: int + :type width: `int`_ :param color: A color name from the `X11 Color Names list `_, - or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) - :type color: str or int + or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) + :type color: `str`_ or int :param priority: The layer on which the marker will be drawn. - :type priority: int + :type priority: `int`_ :param viewport: 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas. - :type viewport: list of floats + :type viewport: `list`_ :param worldcoordinate: List of 4 floats (xmin, xmax, ymin, ymax) - :type worldcoordinate: list of floats + :type worldcoordinate: `list`_ :param x: List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1]. - :type x: list of floats + :type x: `list`_ :param y: List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3]. - :type y: list of floats + :type y: `list`_ :returns: A VCS line object :rtype: vcs.line.Tl @@ -862,40 +855,38 @@ def createmarker(name=None, source='default', mtype=None, size=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None, projection=None): - """ - %s - + """%s :param name: Name of created object - :type name: str + :type name: `str`_ :param source: A marker, or string name of a marker - :type source: str + :type source: `str`_ :param mtype: Specifies the type of marker, i.e. "dot", "circle" - :type mtype: str + :type mtype: `str`_ :param size: - :type size: int + :type size: `int`_ :param color: A color name from the `X11 Color Names list `_, - or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) - :type color: str or int + or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) + :type color: `str`_ or int :param priority: The layer on which the marker will be drawn. - :type priority: int + :type priority: `int`_ :param viewport: 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas. - :type viewport: list of floats + :type viewport: `list`_ :param worldcoordinate: List of 4 floats (xmin, xmax, ymin, ymax) - :type worldcoordinate: list of floats + :type worldcoordinate: `list`_ :param x: List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1]. - :type x: list of floats + :type x: `list`_ :param y: List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3]. - :type y: list of floats + :type y: `list`_ :returns: A secondary marker method :rtype: vcs.marker.Tm @@ -929,39 +920,38 @@ def getmarker(name='default', mtype=None, size=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None): - """ - %s + """%s :param name: Name of created object - :type name: str + :type name: `str`_ :param source: A marker, or string name of a marker - :type source: str + :type source: `str`_ :param mtype: Specifies the type of marker, i.e. "dot", "circle" - :type mtype: str + :type mtype: `str`_ :param size: Size of the marker - :type size: int + :type size: `int`_ :param color: A color name from the `X11 Color Names list `_, - or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) - :type color: str or int + or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) + :type color: `str`_ or int :param priority: The layer on which the marker will be drawn. - :type priority: int + :type priority: `int`_ :param viewport: 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas. - :type viewport: list of floats + :type viewport: `list`_ :param worldcoordinate: List of 4 floats (xmin, xmax, ymin, ymax) - :type worldcoordinate: list of floats + :type worldcoordinate: `list`_ :param x: List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1]. - :type x: list of floats + :type x: `list`_ :param y: List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3]. - :type y: list of floats + :type y: `list`_ :returns: A marker graphics method object :rtype: vcs.marker.Tm @@ -998,42 +988,40 @@ def createfillarea(name=None, source='default', style=None, index=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None): - """ - %s + """%s :param name: Name of created object - :type name: str + :type name: `str`_ :param source: a fillarea, or string name of a fillarea - :type source: str + :type source: `str`_ :param style: One of "hatch", "solid", or "pattern". - :type style: str + :type style: `str`_ :param index: Specifies which `pattern `_ to fill with. - Accepts ints from 1-20. - - :type index: int + Accepts ints from 1-20. + :type index: `int`_ :param color: A color name from the `X11 Color Names list `_, - or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) + or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) - :type color: str or int + :type color: `str`_ or int :param priority: The layer on which the fillarea will be drawn. - :type priority: int + :type priority: `int`_ :param viewport: 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas. - :type viewport: list of floats + :type viewport: `list`_ :param worldcoordinate: List of 4 floats (xmin, xmax, ymin, ymax) - :type worldcoordinate: list of floats + :type worldcoordinate: `list`_ :param x: List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1]. - :type x: list of floats + :type x: `list`_ :param y: List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3]. - :type y: list of floats + :type y: `list`_ :returns: A fillarea object :rtype: vcs.fillarea.Tf @@ -1067,41 +1055,40 @@ def getfillarea(name='default', style=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None): - """ - %s + """%s :param name: String name of an existing fillarea VCS object - :type name: str + :type name: `str`_ :param style: One of "hatch", "solid", or "pattern". - :type style: str + :type style: `str`_ :param index: Specifies which `pattern `_ to fill with. Accepts ints from 1-20. - :type index: int + :type index: `int`_ :param color: A color name from the `X11 Color Names list `_, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) - :type color: str or int + :type color: `str`_ or int :param priority: The layer on which the texttable will be drawn. - :type priority: int + :type priority: `int`_ - :param viewport: 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas. - :type viewport: list of floats + :param viewport: 4 floats between 0 and 1 which specify the area that X/Y + values are mapped to inside of the canvas. + :type viewport: `list`_ :param worldcoordinate: List of 4 floats (xmin, xmax, ymin, ymax) - :type worldcoordinate: list of floats + :type worldcoordinate: `list`_ :param x: List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1]. - :type x: list of floats + :type x: `list`_ :param y: List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3]. - :type y: list of floats + :type y: `list`_ :returns: A fillarea secondary object :rtype: vcs.fillarea.Tf - """ # Check to make sure the argument passed in is a STRING @@ -1135,42 +1122,44 @@ def createtexttable(name=None, source='default', font=None, spacing=None, expansion=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None): - """ - %s + """%s :param name: Name of created object - :type name: str + :type name: `str`_ :param source: a texttable, or string name of a texttable - :type source: str + :type source: `str`_ :param font: Which font to use (index or name). - :type font: int or string - - :param expansion: DEPRECATED - :type expansion: DEPRECATED + :type font: `int`_ or `str`_ :param color: A color name from the `X11 Color Names list `_, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) - :type color: str or int + :type color: `str`_ or int :param priority: The layer on which the texttable will be drawn. - :type priority: int + :type priority: `int`_ :param viewport: 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas. - :type viewport: list of floats + :type viewport: `list`_ :param worldcoordinate: List of 4 floats (xmin, xmax, ymin, ymax) - :type worldcoordinate: list of floats + :type worldcoordinate: `list`_ - :param x: List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1]. - :type x: list of floats + :param x: List of lists of x coordinates. + Values must be between worldcoordinate[0] and worldcoordinate[1]. + :type x: `list`_ - :param y: List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3]. - :type y: list of floats + :param y: List of lists of y coordinates. + Values must be between worldcoordinate[2] and worldcoordinate[3]. + :type y: `list`_ :returns: A texttable graphics method object :rtype: vcs.texttable.Tt + + .. note:: + + The expansion parameter is no longer used """ name, source = check_name_source(name, source, 'texttable') @@ -1206,39 +1195,39 @@ def gettexttable(name='default', font=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None): - """ - %s + """%s :param name: String name of an existing VCS texttable object - :type name: str - - :param font: ??? - :type font: ??? + :type name: `str`_ - :param expansion: ??? - :type expansion: ??? + :param font: Which font to use (index or name). + :type font: `int`_ or `str`_ :param color: A color name from the `X11 Color Names list `_, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) - :type color: str or int + :type color: `str`_ or int :param priority: The layer on which the texttable will be drawn. - :type priority: int + :type priority: `int`_ :param viewport: 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas. - :type viewport: list of floats + :type viewport: `list`_ :param worldcoordinate: List of 4 floats (xmin, xmax, ymin, ymax) - :type worldcoordinate: list of floats + :type worldcoordinate: `list`_ :param x: List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1]. - :type x: list of floats + :type x: `list`_ :param y: List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3]. - :type y: list of floats + :type y: `list`_ :returns: A texttable graphics method object :rtype: vcs.texttable.Tt + + .. note:: + + The expansion parameter is no longer used """ # Check to make sure the argument passed in is a STRING @@ -1252,14 +1241,14 @@ def gettexttable(name='default', font=None, def createtextorientation(name=None, source='default'): - """ - %s + """%s :param name: The name of the created object - :type name: str + :type name: `str`_ - :param source: The object to inherit from - :type source: a textorientation or a string name of a textorientation + :param source: The object to inherit from. + Can be a textorientation, or a string name of a textorientation. + :type source: `str`_ or :class:`vcs.textorientation.To` :returns: A textorientation secondary method :rtype: vcs.textorientation.To @@ -1272,11 +1261,10 @@ def createtextorientation(name=None, source='default'): def gettextorientation(To_name_src='default'): - """ - %s + """%s :param To_name_src: String name of an existing textorientation VCS object - :type To_name_src: str + :type To_name_src: `str`_ :returns: A textorientation VCS object :rtype: vcs.textorientation.To @@ -1298,70 +1286,64 @@ def createtextcombined(Tt_name=None, Tt_source='default', To_name=None, To_sourc font=None, spacing=None, expansion=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None, height=None, angle=None, path=None, halign=None, valign=None, projection=None): - """ - %s + """%s :param Tt_name: Name of created object - :type Tt_name: str + :type Tt_name: `str`_ :param Tt_source: Texttable object to inherit from. Can be a texttable, or a string name of a texttable. - :type Tt_source: str or vcs.texttable.Tt + :type Tt_source: `str`_ or :class:`vcs.texttable.Tt` :param To_name: Name of the textcombined's text orientation (to be created) - :type To_name: str + :type To_name: `str`_ :param To_source: Name of the textorientation to inherit. Can be a textorientation, or a string name of a textorientation. - :type To_source: str or vcs.textorientation.To + :type To_source: `str`_ or :class:`vcs.textorientation.To` :param font: Which font to use (index or name). - :type font: int or str - - :param spacing: DEPRECATED - :type spacing: DEPRECATED - - :param expansion: DEPRECATED - :type expansion: DEPRECATED + :type font: `int`_ or `str`_ :param color: A color name from the `X11 Color Names list `_, or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) - :type color: str or int + :type color: `str`_ or int :param priority: The layer on which the object will be drawn. - :type priority: int + :type priority: `int`_ :param viewport: 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas. - :type viewport: list of floats + :type viewport: `list`_ :param worldcoordinate: List of 4 floats (xmin, xmax, ymin, ymax) - :type worldcoordinate: list of floats + :type worldcoordinate: `list`_ :param x: List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1]. - :type x: list of floats + :type x: `list`_ :param y: List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3]. - :type y: list of floats + :type y: `list`_ :param height: Size of the font - :type height: int + :type height: `int`_ :param angle: Angle of the text, in degrees - :type angle: int - - :param path: DEPRECATED - :type path: DEPRECATED + :type angle: `int`_ :param halign: Horizontal alignment of the text. One of ["left", "center", "right"]. - :type halign: str + :type halign: `str`_ :param valign: Vertical alignment of the text. One of ["top", "center", "botom"]. - :type valign: str + :type valign: `str`_ :param projection: Specify a geographic projection used to convert x/y from spherical coordinates to 2D coordinates. - :type projection: str or projection object + :type projection: `str`_ or projection object :returns: A VCS text object :rtype: vcs.textcombined.Tc + + .. note:: + + The spacing, path, and expansion parameters are no longer used """ # Check if to is defined if To_name is None: @@ -1412,63 +1394,59 @@ def gettextcombined(Tt_name_src='default', To_name_src=None, string=None, font=N expansion=None, color=None, priority=None, viewport=None, worldcoordinate=None, x=None, y=None, height=None, angle=None, path=None, halign=None, valign=None): - """ - %s + """%s :param Tt_name_src: Name of created object - :type Tt_name_src: str + :type Tt_name_src: `str`_ :param To_name_src: Name of parent textorientation object - :type To_name_src: str + :type To_name_src: `str`_ :param string: Text to render - :param string: list of str + :type string: `list`_ :param font: Which font to use (index or name) - :type font: int or str - - :param spacing: DEPRECATED - :type spacing: DEPRECATED - - :param expansion: DEPRECATED - :type expansion: DEPRECATED + :type font: `int`_ or `str`_ :param color: A color name from the `X11 Color Names list `_, - or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) - :type color: str or int + or an integer value from 0-255, or an RGB/RGBA tuple/list (e.g. (0,100,0), (100,100,0,50)) + :type color: `str`_ or int :param priority: The layer on which the object will be drawn. - :type priority: int + :type priority: `int`_ :param viewport: 4 floats between 0 and 1 which specify the area that X/Y values are mapped to inside of the canvas. - :type viewport: list of floats + :type viewport: `list`_ :param worldcoordinate: List of 4 floats (xmin, xmax, ymin, ymax) - :type worldcoordinate: list of floats + :type worldcoordinate: `list`_ - :param x: List of lists of x coordinates. Values must be between worldcoordinate[0] and worldcoordinate[1]. - :type x: list of floats + :param x: List of lists of x coordinates. + Values must be between worldcoordinate[0] and worldcoordinate[1]. + :type x: `list`_ :param y: List of lists of y coordinates. Values must be between worldcoordinate[2] and worldcoordinate[3]. - :type y: list of floats + :type y: `list`_ :param height: Size of the font - :type height: int + :type height: `int`_ - :param angle: Angle of the rendered text, in degrees - :type angle: list of int - - :param path: DEPRECATED - :type path: DEPRECATED + :param angle: Angle of the rendered text, in degrees. + Must be a list of integers. + :type angle: `list`_ :param halign: Horizontal alignment of the text. One of ["left", "center", "right"] - :type halign: str + :type halign: `str`_ :param valign: Vertical alignment of the text. One of ["top", "center", "bottom"] - :type valign: str + :type valign: `str`_ :returns: A textcombined object :rtype: vcs.textcombined.Tc + + .. note:: + + The spacing, path, and expansion parameters are no longer used """ # Check to make sure the arguments passed in are a STRINGS @@ -1528,8 +1506,7 @@ def gettextcombined(Tt_name_src='default', To_name_src=None, string=None, font=N def get3d_scalar(Gfdv3d_name_src='default'): - """ - %s + """%s :param Gfdv3d_name_src: String name of an existing 3d_scalar VCS object. :type Gfdv3d_name_src: str @@ -1550,14 +1527,14 @@ def get3d_scalar(Gfdv3d_name_src='default'): def create3d_scalar(name=None, source='default'): - """ - %s + """%s :param name: The name of the created object - :type name: str + :type name: `str`_ - :param source: The object to inherit from - :type source: a 3d_scalar or a string name of a 3d_scalar + :param source: The object to inherit from. + Can be a 3d_scalar, or a string name of a 3d_scalar. + :type source: `str`_ or :class:`vcs.dv3d.Gf3Dscalar` :returns: A 3d_scalar graphics method object :rtype: vcs.dv3d.Gf3Dscalar @@ -1568,11 +1545,10 @@ def create3d_scalar(name=None, source='default'): def get3d_dual_scalar(Gfdv3d_name_src='default'): - """ - %s + """%s :param Gfdv3d_name_src: String name of an existing 3d_dual_scalar VCS object - :type Gfdv3d_name_src: str + :type Gfdv3d_name_src: `str`_ :returns: A pre-existing 3d_dual_scalar VCS object :rtype: vcs.dv3d.Gf3DDualScalar @@ -1589,14 +1565,14 @@ def get3d_dual_scalar(Gfdv3d_name_src='default'): def create3d_dual_scalar(name=None, source='default'): - """ - %s + """%s :param name: The name of the created object - :type name: str + :type name: `str`_ - :param source: The object to inherit from - :type source: a 3d_dual_scalar or a string name of a 3d_dual_scalar + :param source: The object to inherit from. + Can be a 3d_dual_scalar, or a string name of a 3d_dual_scalar. + :type source: `str`_ or :class:`vcs.dv3d.Gf3DDualScalar` :returns: A 3d_dual_scalar graphics method object :rtype: vcs.dv3d.Gf3DDualScalar @@ -1608,11 +1584,10 @@ def create3d_dual_scalar(name=None, source='default'): def get3d_vector(Gfdv3d_name_src='default'): - """ - %s + """%s :param Gfdv3d_name_src: String name of an existing 3d_vector VCS object - :type Gfdv3d_name_src: str + :type Gfdv3d_name_src: `str`_ :returns: A pre-existing 3d_vector VCS object :rtype: vcs.dv3d.Gf3Dvector @@ -1630,14 +1605,14 @@ def get3d_vector(Gfdv3d_name_src='default'): def create3d_vector(name=None, source='default'): - """ - %s + """%s :param name: The name of the created object - :type name: str + :type name: `str`_ - :param source: The object to inherit from - :type source: a 3d_vector or a string name of a 3d_vector + :param source: The object to inherit from. + Can be a 3d_vector, or a string name of a 3d_vector. + :type source: `str`_ or :class:`vcs.dv3d.Gf3Dvector` :returns: A 3d_vector graphics method object :rtype: vcs.dv3d.Gf3Dvector @@ -1655,14 +1630,14 @@ def create3d_vector(name=None, source='default'): def createcolormap(Cp_name=None, Cp_name_src='default'): - """ - %s + """%s :param Cp_name: The name of the created object - :type Cp_name: str + :type Cp_name: `str`_ - :param Cp_name_src: The object to inherit - :type Cp_name_src: a colormap or a string name of a colormap + :param Cp_name_src: The object to inherit from. + Can be a colormap or a string name of a colormap. + :type Cp_name_src: `str`_ or :class:`vcs.colormap.Cp` :returns: A VCS colormap object :rtype: vcs.colormap.Cp @@ -1674,11 +1649,10 @@ def createcolormap(Cp_name=None, Cp_name_src='default'): def getcolormap(Cp_name_src='default'): - """ - %s + """%s :param Cp_name_src: String name of an existing colormap VCS object - :type Cp_name_src: str + :type Cp_name_src: `str`_ :returns: A pre-existing VCS colormap object :rtype: vcs.colormap.Cp @@ -1797,28 +1771,24 @@ def removeP(obj): def removeobject(obj): - """ - The user has the ability to create primary and secondary class + """The user has the ability to create primary and secondary class objects. The function allows the user to remove these objects from the appropriate class list. - Note, To remove the object completely from Python, remember to - use the "del" function. + .. note:: - Also note, The user is not allowed to remove a "default" class - object. + The user is not allowed to remove a "default" class + object. :Example: .. doctest:: manageElements_removeobject >>> a=vcs.init() - >>> line=a.getline('red') # To Modify an existing line object >>> iso=a.createisoline('dean') # Create an instance of an isoline object - >>> a.removeobject(line) # Removes line object from VCS list - 'Removed line object red' >>> a.removeobject(iso) # Remove isoline object from VCS list 'Removed isoline object dean' + :param obj: Any VCS primary or secondary object :type obj: VCS object diff --git a/vcs/marker.py b/vcs/marker.py index f2554b53f..b24f2edb3 100755 --- a/vcs/marker.py +++ b/vcs/marker.py @@ -24,7 +24,7 @@ import VCS_validation_functions import vcs import genutil -from xmldocs import scriptdocs +from xmldocs import scriptdocs, listdoc def process_src(nm, code): @@ -211,6 +211,8 @@ class Tm(object): mk.x=[[0,.1,.2], [.3,.4,.5]] # List of FloatTypes mk.y=[[.5,.4,.3], [.2,.1,0]] + + .. pragma: skip-doctest """ __slots__ = [ 's_name', @@ -429,7 +431,7 @@ def __init__(self, Tm_name, Tm_name_src='default'): def list(self): if (self.name == '__removed_from_VCS__'): raise ValueError('This instance has been removed from VCS.') - print "", "----------Marker (Tm) member (attribute) listings ----------" + print "---------- Marker (Tm) member (attribute) listings ----------" print "secondary method =", self.s_name print "name =", self.name print "type =", self.type @@ -442,11 +444,9 @@ def list(self): print "y =", self.y print "projection =", self.projection print "colormap =", self.colormap + list.__doc__ = listdoc.format(name="marker", parent="") def script(self, script_filename=None, mode=None): - """ - script.__doc__ = xmldocs.marker_script -""" if (script_filename is None): raise ValueError( 'Error - Must provide an output script file name.') diff --git a/vcs/meshfill.py b/vcs/meshfill.py index 3632b97aa..45d899cc8 100644 --- a/vcs/meshfill.py +++ b/vcs/meshfill.py @@ -305,6 +305,8 @@ class Gfm(object): %s mesh :: (str/int) (0) Draws the mesh wrap :: ([float,float]) ([0.,0.]) Modulo to wrap around on either axis (automatically set to 360 for longitude axes) + + .. pragma: skip-doctest """ % (xmldocs.graphics_method_core, xmldocs.meshfill_doc) ########################################################################## @@ -694,12 +696,12 @@ def __init__(self, Gfm_name, Gfm_name_src='default'): def colors(self, color1=16, color2=239): self.fillareacolors = range(color1, color2) - colors.__doc__ = xmldocs.colorsdoc + colors.__doc__ = xmldocs.colorsdoc % {"name": "meshfill", "data": "array, array"} def exts(self, ext1='n', ext2='y'): self.ext_1 = ext1 self.ext_2 = ext2 - exts.__doc__ = xmldocs.extsdoc + exts.__doc__ = xmldocs.extsdoc.format(name="meshfill", data="array, array") # # Doesn't make sense to inherit. This would mean more coding in C. @@ -708,34 +710,34 @@ def exts(self, ext1='n', ext2='y'): def xticlabels(self, xtl1='', xtl2=''): self.xticlabels1 = xtl1 self.xticlabels2 = xtl2 - xticlabels.__doc__ = xmldocs.xticlabelsdoc + xticlabels.__doc__ = xmldocs.xticlabelsdoc % {"name": "meshfill", "data": "f('u')"} def xmtics(self, xmt1='', xmt2=''): self.xmtics1 = xmt1 self.xmtics2 = xmt2 - xmtics.__doc__ = xmldocs.xmticsdoc + xmtics.__doc__ = xmldocs.xmticsdoc.format(name="meshfill") def yticlabels(self, ytl1='', ytl2=''): self.yticlabels1 = ytl1 self.yticlabels2 = ytl2 - yticlabels.__doc__ = xmldocs.yticlabelsdoc + yticlabels.__doc__ = xmldocs.yticlabelsdoc % {"name": "meshfill", "data": "f('u')"} def ymtics(self, ymt1='', ymt2=''): self.ymtics1 = ymt1 self.ymtics2 = ymt2 - ymtics.__doc__ = xmldocs.ymticsdoc + ymtics.__doc__ = xmldocs.xmticsdoc.format(name="meshfill") def datawc(self, dsp1=1e20, dsp2=1e20, dsp3=1e20, dsp4=1e20): self.datawc_y1 = dsp1 self.datawc_y2 = dsp2 self.datawc_x1 = dsp3 self.datawc_x2 = dsp4 - datawc.__doc__ = xmldocs.datawcdoc + datawc.__doc__ = xmldocs.datawcdoc.format(name="meshfill") def xyscale(self, xat='', yat=''): self.xaxisconvert = xat self.yaxisconvert = yat - xyscale.__doc__ = xmldocs.xyscaledoc % (('meshfill',) * 2) + xyscale.__doc__ = xmldocs.xyscaledoc.format(name='meshfill') ########################################################################## # # @@ -745,7 +747,7 @@ def xyscale(self, xat='', yat=''): def list(self): if (self.name == '__removed_from_VCS__'): raise ValueError('This instance has been removed from VCS.') - print ' ---------- Meshfill (Gmf) member (attribute) listings ---------' + print '---------- Meshfill (Gmf) member (attribute) listings ----------' print 'graphics method =', self.g_name print 'name =', self.name print 'projection =', self.projection @@ -777,7 +779,7 @@ def list(self): print 'wrap =', self.wrap print 'colormap = ', self.colormap return - list.__doc__ = xmldocs.listdoc + list.__doc__ = xmldocs.listdoc.format(name="meshfill", parent="") ########################################################################## # # diff --git a/vcs/png.py b/vcs/png.py deleted file mode 100644 index ad6536b9a..000000000 --- a/vcs/png.py +++ /dev/null @@ -1,447 +0,0 @@ -# Adapted for numpy/ma/cdms2 by convertcdms.py -""" -# Fillarea (Tf) module -""" -########################################################################## -# # -# Module: fillarea (Tf) module # -# # -# Copyright: 2000, Regents of the University of California # -# This software may not be distributed to others without # -# permission of the author. # -# # -# Author: PCMDI Software Team # -# Lawrence Livermore NationalLaboratory: # -# support@pcmdi.llnl.gov # -# # -# Description: Python command wrapper for VCS's fill area secondary object. # -# # -# Version: 4.0 # -# # -########################################################################## -# -# -# -########################################################################## -# # -# Import: VCS C extension module. # -# # -########################################################################## -import _vcs -import Canvas -import VCS_validation_functions - -########################################################################## -# # -# Function: setTimember # -# # -# Description of Function: # -# Private function to update the VCS canvas plot. If the canvas mode is # -# set to 0, then this function does nothing. # -# # -# # -# Example of Use: # -# setTimember(self,name,value) # -# where: self is the class (e.g., Ti) # -# name is the name of the member that is being changed # -# value is the new value of the member (or attribute) # -# # -########################################################################## - - -def setTimember(self, member, value): - # If the VCS Canvas is displayed, then bring the canvas to the front before - # redisplaying the updated contents. - if (self.parent.mode == 1) and (self.parent.iscanvasdisplayed()): - Canvas.finish_queued_X_server_requests(self.parent) - self.parent.canvas.BLOCK_X_SERVER() - self.parent.canvasraised() - - _vcs.setifmember(self, member, value, self.parent.mode) - - # If the VCS Canvas is displayed, then update the backing store - if (self.parent.mode == 1) and (self.parent.iscanvasdisplayed()): - self.parent.flush() - self.parent.backing_store() - self.parent.canvas.UNBLOCK_X_SERVER() - -setmember = setTimember # for validation functions... -########################################################################## -# # -# Function: getTimember # -# # -# Description of Function: # -# Private function that retrieves the fillarea members from the C # -# structure and passes it back to Python. # -# # -# # -# Example of Use: # -# return_value = # -# getTimember(self,name) # -# where: self is the class (e.g., Ti) # -# name is the name of the member that is being found # -# # -########################################################################## - - -def getTimember(self, member): - return _vcs.getTimember(self, member) -getmember = getTimember - -########################################################################## -# # -# Function: renameTi # -# # -# Description of Function: # -# Private function that renames the name of an existing fillarea # -# graphics method. # -# # -# # -# Example of Use: # -# renameTi(old_name, new_name) # -# where: old_name is the current name of fillarea graphics method # -# new_name is the new name for the fillarea graphics method # -# # -########################################################################## - - -def renameTi(self, old_name, new_name): - return _vcs.renameTi(old_name, new_name) - -############################################################################# -# # -# Fillarea (Tm) Class. # -# # -############################################################################# - - -class Ti(object): - - """ - Class: Ti # Fillarea - - Description of Ti Class: - The Fillarea class object allows the user to edit fillarea attributes, including - fillarea interior style, style index, and color index. - - This class is used to define an fillarea table entry used in VCS, or it - can be used to change some or all of the fillarea attributes in an - existing fillarea table entry. - - Other Useful Functions: - a=vcs.init() # Constructor - a.show('fillarea') # Show predefined fillarea objects - a.update() # Updates the VCS Canvas at user's request - a.mode=1, or 0 # If 1, then automatic update, else if - 0, then use update function to - update the VCS Canvas. - - Example of Use: - a=vcs.init() - To Create a new instance of fillarea use: - fa=a.createfillarea('new','def37') # Copies content of 'def37' to 'new' - fa=a.createfillarea('new') # Copies content of 'default' to 'new' - - To Modify an existing fillarea use: - fa=a.getfillarea('red') - - fa.list() # Will list all the fillarea attribute values - - There are three possibilities for setting the isofill style (Ex): - fa.style = 'solid' - fa.style = 'hatch' - fa.style = 'pattern' - fa.index=1 # Range from 1 to 20 - fa.color=100 # Range from 1 to 256 - - Specify the fillarea index: - fa.index=1 - fa.index=2 - fa.index=3 - fa.index=4 - fa.index=5 - fa.index=6 - fa.index=7 - fa.index=8 - fa.index=9 - fa.index=10 - fa.index=11 - fa.index=12 - fa.index=13 - fa.index=14 - fa.index=15 - fa.index=16 - fa.index=17 - fa.index=18 - fa.index=19 - fa.index=20 - - fa.priority=1 # Set the graphics priority on the canvas - fa.viewport=[0, 1.0, 0,1.0] # FloatType [0,1]x[0,1] - fa.worldcoordinate=[0,1.0,0,1.0] # FloatType [#,#]x[#,#] - - fa.x=[[0,.1,.2], [.3,.4,.5]] # List of FloatTypes - fa.y=[[.5,.4,.3], [.2,.1,0]] # List of FloatTypes -""" - __slots__ = [ - 'setmember', - 'parent', - 'name', - 's_name', - 'color', - 'priority', - 'style', - 'index', - 'viewport', - 'worldcoordinate', - 'x', - 'y', - 'projection', - '_name', - ] - - def _getname(self): - return self._name - - def _setname(self, value): - value = VCS_validation_functions.checkname(self, 'name', value) - if value is not None: - self._name = value - setmember(self, 'name', value) - name = property(_getname, _setname) - - def _getpriority(self): - return getmember(self, 'priority') - - def _setpriority(self, value): - value = VCS_validation_functions.checkInt( - self, - 'priority', - value, - minvalue=0) - setmember(self, 'priority', value) - priority = property(_getpriority, _setpriority) - - def _getprojection(self): - return getmember(self, 'projection') - - def _setprojection(self, value): - value = VCS_validation_functions.checkProjection( - self, - 'projection', - value) - setmember(self, 'projection', value) - projection = property(_getprojection, _setprojection) - - def _getwc(self): - return getmember(self, 'worldcoordinate') - - def _setwc(self, value): - value = VCS_validation_functions.checkListOfNumbers( - self, - 'worldcoordinate', - value, - maxelements=4) - setmember(self, 'worldcoordinate', value) - worldcoordinate = property(_getwc, _setwc) - - def _getvp(self): - return getmember(self, 'viewport') - - def _setvp(self, value): - value = VCS_validation_functions.checkListOfNumbers( - self, - 'viewport', - value, - maxelements=4, - minvalue=0., - maxvalue=1.) - setmember(self, 'viewport', value) - viewport = property(_getvp, _setvp) - - def _getx(self): - return getmember(self, 'x') - - def _setx(self, value): - if not isinstance(value, (list, tuple)): - raise ValueError('%s must be a tuple or list of values.') - try: - # first we'll see if it is simply a list of values - value = VCS_validation_functions.checkListOfNumbers( - self, - 'x', - value) - except: - # ok it was not, so it maybe a list of list of numbers ? - val = [] - for v in value: - tmp = VCS_validation_functions.checkListOfNumbers(self, 'x', v) - val.append(tmp) - value = val - # ok it worked - setmember(self, 'x', value) - x = property(_getx, _setx) - - def _gety(self): - return getmember(self, 'y') - - def _sety(self, value): - if not isinstance(value, (list, tuple)): - raise ValueError('%s must be a tuple or list of values.') - try: - # first we'll see if it is simply a list of values - value = VCS_validation_functions.checkListOfNumbers( - self, - 'y', - value) - except: - # ok it was not, so it maybe a list of list of numbers ? - val = [] - for v in value: - tmp = VCS_validation_functions.checkListOfNumbers(self, 'y', v) - val.append(tmp) - value = val - # ok it worked - setmember(self, 'y', value) - y = property(_gety, _sety) - - ########################################################################## - # # - # Initialize the fillarea attributes. # - # # - ########################################################################## - def __init__( - self, parent, Ti_name=None, Ti_name_src='default', createTi=0): - # # - ########################################################### - # Initialize the fillarea class and its members # - # The getTimember function retrieves the values of the # - # fillarea members in the C structure and passes back the # - # appropriate Python Object. # - ########################################################### - # # - if (createTi == 0): - if (Ti_name is None): - raise ValueError('Must provide a fillarea name.') - else: - _vcs.copyTi(Ti_name_src, Ti_name) - self._name = Ti_name - else: - self._name = Ti_name_src - self.s_name = 'Ti' - self.parent = parent - - ########################################################################## - # # - # Fillarea out line members (attributes). # - # # - ########################################################################## - def list(self): - if (self.name == '__removed_from_VCS__'): - raise ValueError('This instance has been removed from VCS.') - print "", "----------Fillarea (Tf) member (attribute) listings ----------" - print 'Canvas Mode =', self.parent.mode - print "secondary method =", self.s_name - print "name =", self.name - print "style =", self.style - print "index =", self.index - print "color =", self.color - print "priority =", self.priority - print "viewport =", self.viewport - print "worldcoordinate =", self.worldcoordinate - print "x =", self.x - print "y =", self.y - print "projection =", self.projection - - ########################################################################## - # # - # Script out secondary fillarea method in VCS to a file. # - # # - ########################################################################## - def script(self, script_filename=None, mode=None): - """ - Function: script # Calls _vcs.scriptTf - - Description of Function: - Saves out a fillarea graphics method in Python or VCS script form to a - designated file. - - Example of Use: - script(scriptfile_name) - where: scriptfile_name is the output name of the script file. - mode is either "w" for replace or "a" for append. - - Note: If the the filename has a ".py" at the end, it will produce a - Python script. If the filename has a ".scr" at the end, it will - produce a VCS script. If neither extensions are give, then by - default a Python script will be produced. - - a=vcs.init() - fa=a.createfillarea('temp') - fa.script('filename.py') # Append to a Python file "filename.py" - fa.script('filename.scr') # Append to a VCS file "filename.scr" - fa.script('filename','w') # Create or overwrite to a Python file "filename.py" - """ - if (script_filename is None): - raise ValueError( - 'Error - Must provide an output script file name.') - - if (mode is None): - mode = 'a' - elif (mode not in ('w', 'a')): - raise ValueError( - 'Error - Mode can only be "w" for replace or "a" for append.') - - # By default, save file in python script mode - scr_type = script_filename[ - len(script_filename) - - 4:len(script_filename)] - if (scr_type == '.scr'): - print _vcs.scriptTf(self.name, script_filename, mode) - else: - mode = mode + '+' - py_type = script_filename[ - len(script_filename) - - 3:len(script_filename)] - if (py_type != '.py'): - script_filename = script_filename + '.py' - - # Write to file - fp = open(script_filename, mode) - if (fp.tell() == 0): # Must be a new file, so include below - fp.write("#####################################\n") - fp.write("# #\n") - fp.write("# Import and Initialize VCS #\n") - fp.write("# #\n") - fp.write("#############################\n") - fp.write("import vcs\n") - fp.write("v=vcs.init()\n\n") - - unique_name = '__Tf__' + self.name - fp.write( - "#----------Fillarea (Tf) member (attribute) listings ----------\n") - fp.write("tf_list=v.listelements('fillarea')\n") - fp.write("if ('%s' in tf_list):\n" % self.name) - fp.write( - " %s = v.getfillarea('%s')\n" % - (unique_name, self.name)) - fp.write("else:\n") - fp.write( - " %s = v.createfillarea('%s')\n" % - (unique_name, self.name)) - fp.write("%s.style = %s\n" % (unique_name, self.style)) - fp.write("%s.index = %s\n" % (unique_name, self.index)) - fp.write("%s.color = %s\n\n" % (unique_name, self.color)) - fp.write("%s.priority = %d\n" % (unique_name, self.priority)) - fp.write("%s.viewport = %s\n" % (unique_name, self.viewport)) - fp.write( - "%s.worldcoordinate = %s\n" % - (unique_name, self.worldcoordinate)) - fp.write("%s.x = %s\n" % (unique_name, self.x)) - fp.write("%s.y = %s\n\n" % (unique_name, self.y)) - fp.write("%s.projection = %s\n\n" % (unique_name, self.projection)) - - -########################################################################## -# END OF FILE # -########################################################################## diff --git a/vcs/projection.py b/vcs/projection.py index 6768fe18e..0b5719f47 100644 --- a/vcs/projection.py +++ b/vcs/projection.py @@ -15,7 +15,7 @@ import VCS_validation_functions import vcs import copy -from xmldocs import scriptdocs +from xmldocs import scriptdocs, listdoc # used to decide if we show longitude labels for round projections or # latitude labels for elliptical projections @@ -382,6 +382,7 @@ class Proj(object): # or iso.projection='lambert' + .. pragma: skip-doctest """ def __init__(self, Proj_name=None, Proj_name_src='default'): @@ -443,7 +444,7 @@ def __init__(self, Proj_name=None, Proj_name_src='default'): def list(self): if (self.name == '__removed_from_VCS__'): raise ValueError('This instance has been removed from VCS.') - print ' ---------- Projection (Proj) member (attribute) listings ---------' + print '---------- Projection (Proj) member (attribute) listings ----------' print 'secondary method =', self.s_name print 'name =', self.name print 'type =', self.type @@ -451,6 +452,7 @@ def list(self): for att in self.attributes: print att, '=', getattr(self, att) + list.__doc__ = listdoc.format(name="projection", parent="") @property def attributes(self): diff --git a/vcs/queries.py b/vcs/queries.py index bcf3ecb8e..92b76f9b0 100644 --- a/vcs/queries.py +++ b/vcs/queries.py @@ -20,6 +20,18 @@ ########################################################################## """ + .. _list: https://docs.python.org/2/library/functions.html#list + .. _tuple: https://docs.python.org/2/library/functions.html#tuple + .. _dict: https://docs.python.org/2/library/stdtypes.html#mapping-types-dict + .. _None: https://docs.python.org/2/library/constants.html?highlight=none#None + .. _str: https://docs.python.org/2/library/functions.html?highlight=str#str + .. _bool: https://docs.python.org/2/library/functions.html?highlight=bool#bool + .. _float: https://docs.python.org/2/library/functions.html?highlight=float#float + .. _int: https://docs.python.org/2/library/functions.html?highlight=float#int + .. _long: https://docs.python.org/2/library/functions.html?highlight=float#long + .. _file: https://docs.python.org/2/library/functions.html?highlight=open#file + + .. pragma: skip-doctest """ import boxfill import isofill @@ -45,8 +57,7 @@ def isgraphicsmethod(gobj): - """ - Indicates if the entered argument is one of the following graphics + """Indicates if the entered argument is one of the following graphics methods: boxfill, isofill, isoline, scatter, vector, xvsy, xyvsy, yxvsx. @@ -64,7 +75,7 @@ def isgraphicsmethod(gobj): :returns: Integer reperesenting whether gobj is one of the above graphics methods. 1 indicates true, 0 indicates false. - :rtype: int + :rtype: `int`_ """ import vcsaddons if (isinstance(gobj, boxfill.Gfb)): @@ -107,15 +118,14 @@ def graphicsmethodlist(): :returns: A list of available grapics methods (i.e., 'boxfill', 'isofill', 'isoline', 'meshfill', 'scatter', 'vector', 'xvsy', 'xyvsy', 'yxvsx', 'taylordiagram', '1d', '3d_scalar', '3d_dual_scalar', '3d_vector'). - :rtype: list + :rtype: `list`_ """ return ['boxfill', 'isofill', 'isoline', 'meshfill', 'scatter', 'vector', 'xvsy', 'xyvsy', 'yxvsx', 'taylordiagram', '1d', '3d_scalar', '3d_dual_scalar', '3d_vector'] def graphicsmethodtype(gobj): - """ - Check the type of a graphics object. + """Check the type of a graphics object. Returns None if the object is not a graphics method. @@ -137,10 +147,10 @@ def graphicsmethodtype(gobj): vcsError: The object passed is not a graphics method object. :returns: If gobj is a graphics method object, returns its type: 'boxfill', 'isofill', 'isoline', 'meshfill', - 'scatter', 'vector', 'xvsy', 'xyvsy', 'yxvsx', 'taylordiagram', '1d', '3d_scalar', '3d_dual_scalar', - '3d_vector'. - If gobj is not a graphics method object, raises an exception and prints a vcsError message. - :rtype: str or None + 'scatter', 'vector', 'xvsy', 'xyvsy', 'yxvsx', 'taylordiagram', '1d', '3d_scalar', '3d_dual_scalar', + '3d_vector'. + If gobj is not a graphics method object, raises an exception and prints a vcsError message. + :rtype: `str`_ or `None`_ """ import vcsaddons if (isinstance(gobj, boxfill.Gfb)): @@ -170,26 +180,23 @@ def graphicsmethodtype(gobj): def isplot(pobj): - """ - Check to see if this object is a VCS secondary display plot. + """Check to see if this object is a VCS secondary display plot. :Example: .. doctest:: queries_isplot >>> a=vcs.init() - >>> import cdms2 # need this to make a slab for a boxfill plot - >>> f = cdms2.open(vcs.sample_data + '/clt.nc') # open a variable file - >>> v = f('v') # create a slab from the variable file - >>> dsp_plot=(a.getboxfill(), v) # plot a boxfill. Should return vcs.displayplot.Dp. - >>> vcs.queries.isplot(dsp_plot) + >>> array=[range(10) for _ in range(10)] + >>> dsp=a.plot(array) # plotting should return a displayplot object + >>> vcs.queries.isplot(dsp) 1 :param obj: A VCS object :type obj: VCS Object :returns: An integer indicating whether the object is a display plot (1), or not (0). - :rtype: int + :rtype: `int`_ """ if (isinstance(pobj, displayplot.Dp)): return 1 @@ -214,25 +221,33 @@ def istemplate(gobj): def issecondaryobject(sobj): - """ - Check to see if this object is a VCS secondary object + """Check to see if this object is a VCS secondary object .. note:: Secondary objects will be one of the following: - 1.) colormap: specification of combinations of 256 available - colors - 2.) fill area: style, style index, and color index - 3.) format: specifications for converting numbers to display - strings - 4.) line: line type, width, and color index - 5.) list: a sequence of pairs of numerical and character values - 6.) marker: marker type, size, and color index - 7.) text table: text font type, character spacing, expansion, and - color index - 8.) text orientation: character height, angle, path, and - horizontal/vertical alignment - 9.) projections + + 1.) colormap: specification of combinations of 256 available + colors + + 2.) fill area: style, style index, and color index + + 3.) format: specifications for converting numbers to display + strings + + 4.) line: line type, width, and color index + + 5.) list: a sequence of pairs of numerical and character values + + 6.) marker: marker type, size, and color index + + 7.) text table: text font type, character spacing, expansion, + and color index + + 8.) text orientation: character height, angle, path, and + horizontal/vertical alignment + + 9.) projections :Example: @@ -251,7 +266,7 @@ def issecondaryobject(sobj): :type obj: VCS Object :returns: An integer indicating whether the object is a projection graphics object (1), or not (0). - :rtype: int + :rtype: `int`_ """ if (isinstance(sobj, line.Tl)): return 1 diff --git a/vcs/taylor.py b/vcs/taylor.py index 63bbd3b98..e6935a66a 100644 --- a/vcs/taylor.py +++ b/vcs/taylor.py @@ -548,6 +548,8 @@ class Gtd(object): `Taylor diagrams`_ provide a way of graphically summarizing how closely a pattern matches observations. .. _Taylor diagrams: http://www-pcmdi.llnl.gov/about/staff/Taylor/CV/Taylor_diagram_primer.pdf + + .. pragma: skip-doctest """ __slots__ = [ 'template', @@ -919,6 +921,8 @@ def defaultSkillFunction(self, s, R): :rtype: float .. _`skill`: https://en.wikipedia.org/wiki/Forecast_skill + + .. pragma: skip-doctest TODO: add an example/doctest """ alpha = self.skillCoefficient[0] # default is 1. beta = self.skillCoefficient[1] # default is 1. @@ -938,11 +942,13 @@ def defaultSkillFunction(self, s, R): def drawSkill(self, canvas, values, function=None): """ Draw a skill score. Default skill score provided in :py:func:`defaultSkillFunction` - from Karl taylor, see `PCMDI report series 55`_ for more information on `Taylor diagrams`_ and `skill`_s. + from Karl taylor, see `PCMDI report series 55`_ for more information on + `Taylor diagrams`_ and `skill`_ . - .. _PCMDI report series 55 : http://www-pcmdi.llnl.gov/publications/pdf/55.pdf + .. _`PCMDI report series 55` : http://www-pcmdi.llnl.gov/publications/pdf/55.pdf .. note:: + The function parameter must be provided for drawSkill to work. The :py:func:`defaultSkillFunction` provided in this module can be used to provide a default skill score. Be aware that, as stated in `PCMDI report series 55`_ section 5, it is not possible to define @@ -953,11 +959,13 @@ def drawSkill(self, canvas, values, function=None): :type canvas: vcs.Canvas.Canvas :param values: A list/tuple used to specify the :py:attr:`levels ` - of an :py:class:`isoline ` object. + of an :py:class:`isoline ` object. :type values: list/tuple :param function: A function for determining the skill score of a model. - :type function: + :type function: function + + .. pragma: skip-doctest TODO add an example/doctest """ if function is None: return @@ -1017,7 +1025,7 @@ def drawSkill(self, canvas, values, function=None): return canvas.plot(a, iso, tmpl, bg=self.bg) def list(self): - print ' ----------Taylordiagram (Gtd) member (attribute) listings ----------' + print '---------- Taylordiagram (Gtd) member (attribute) listings ----------' print 'graphic method = Gtd' print 'name =', self.name print 'detail =', self.detail @@ -1402,6 +1410,8 @@ def getArc(self, value, val1=0., val2=90., convert=True): :returns: The coordinates for the calculated arc. :rtype: tuple + + .. pragma: skip-doctest TODO add an example/doctest """ xs = [] ys = [] @@ -1927,6 +1937,8 @@ def plot(self, data, template='deftaylor', skill=None, bg=0, canvas=None): :param canvas: A VCS Canvas object on which the diagram will be plotted. :type canvas: vcs.Canvas.Canvas + + .. pragma: skip-doctest TODO add an example/doctest """ self.bg = bg self.displays = [] diff --git a/vcs/template.py b/vcs/template.py index 4b6af18c6..e8c509cbb 100644 --- a/vcs/template.py +++ b/vcs/template.py @@ -1,6 +1,17 @@ -# Adapted for numpy/ma/cdms2 by convertcdms.py """ +# Adapted for numpy/ma/cdms2 by convertcdms.py # Template (P) module + + .. _list: https://docs.python.org/2/library/functions.html#list + .. _tuple: https://docs.python.org/2/library/functions.html#tuple + .. _dict: https://docs.python.org/2/library/stdtypes.html#mapping-types-dict + .. _None: https://docs.python.org/2/library/constants.html?highlight=none#None + .. _str: https://docs.python.org/2/library/functions.html?highlight=str#str + .. _bool: https://docs.python.org/2/library/functions.html?highlight=bool#bool + .. _float: https://docs.python.org/2/library/functions.html?highlight=float#float + .. _int: https://docs.python.org/2/library/functions.html?highlight=float#int + .. _long: https://docs.python.org/2/library/functions.html?highlight=float#long + .. _file: https://docs.python.org/2/library/functions.html?highlight=open#file """ ############################################################################### # # @@ -38,7 +49,7 @@ import cdutil from projection import round_projections from projection import elliptical_projections -from xmldocs import scriptdocs +from xmldocs import scriptdocs, listdoc # Following for class properties @@ -138,8 +149,7 @@ def process_src(nm, code): ############################################################################# class P(object): - """ - The template primary method (P) determines the location of each picture + """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. @@ -182,7 +192,8 @@ class P(object): .. code-block:: python temp=a.gettemplate('hovmuller') -""" + .. pragma: skip-doctest TODO convert examples to working doctests + """ __slots__ = ["name", "_name", "_p_name", "p_name", "_orientation", "_orientation", "_file", "file", "_function", "function", @@ -524,11 +535,17 @@ def __init__(self, Pic_name=None, Pic_name_src='default'): vcs.elements["template"][Pic_name] = self def list(self, single=None): + """ + %s + + :param single: String value indicating which properties to list + :type single: str + """ if (self.name == '__removed_from_VCS__'): raise ValueError('This instance has been removed from VCS.') if (single is None): - print "----------Template (P) member " +\ + print "---------- Template (P) member " +\ "(attribute) listings ----------" print "method =", self.p_name print "name =", self.name @@ -746,6 +763,7 @@ def list(self, single=None): self.legend.list() elif (single == 'data'): self.data.list() + list.__doc__ = list.__doc__ % (listdoc.format(name="template", parent="")) ########################################################################### # # @@ -1003,11 +1021,12 @@ def script(self, script_filename=None, mode=None): # Canvas def drawTicks(self, slab, gm, x, axis, number, vp, wc, bg=False, X=None, Y=None, **kargs): - """ - Draws the ticks for the axis x number number + """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... + + .. pragma: skip-doctest TODO add example/doctest """ kargs["donotstoredisplay"] = True @@ -1221,13 +1240,14 @@ def drawTicks(self, slab, gm, x, axis, number, return displays def blank(self, attribute=None): - """ - This function turns off elements of a template object. + """This function turns off elements of a template object. + :param attribute: 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. + :type attribute: `None`_ or `str`_ or `list`_ - :param attribute: 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. - :type attribute: None, str, list + .. pragma: skip-doctest TODO add example/doctest """ if attribute is None: attribute = self.__slots__ @@ -1245,25 +1265,26 @@ def blank(self, attribute=None): pass def reset(self, sub_name, v1, v2, ov1=None, ov2=None): - """ - This function resets all the attributes having a + """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. you move to x1,x2 from old_x1, old_x2 + 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 + then respect how far from it you were Example: - Create template 'example1' which inherits from 'default' template - t = vcs.createtemplate('example1', 'default') - Set x1 value to 0.15 and x2 value to 0.5 - t.reset('x',0.15,0.5,t.data.x1,t.data.x2) + .. doctest:: template_reset + + >>> 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 :param sub_name: 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. + For example, sub_name='x' would cause the x1 ans x2 attributes to be set. :type sub_name: str :param v1: Float value to used to set the sub_name1 attribute. @@ -1272,10 +1293,12 @@ def reset(self, sub_name, v1, v2, ov1=None, ov2=None): :param v2: Float value used to set the sub_name2 attribute. :type v2: float - :param ov1: Float value of the old sub-name1 attribute value. Used to compute an offset ratio. + :param ov1: Float value of the old sub-name1 attribute value. + Used to compute an offset ratio. :type ov1: float - :param ov2: Float value of the old sub-name1 attribute value. Used to compute an offset ratio. + :param ov2: Float value of the old sub-name1 attribute value. + Used to compute an offset ratio. :type ov2: float """ @@ -1324,8 +1347,7 @@ def reset(self, sub_name, v1, v2, ov1=None, ov2=None): pass def move(self, p, axis): - """ - Move a template by p% along the axis 'x' or 'y'. + """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 @@ -1334,14 +1356,16 @@ def move(self, p, axis): .. doctest:: template_move - >>> t = vcs.createtemplate('example1', 'default') # Create template 'example1', inherits from 'default' + >>> 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% - :param p: Float indicating the percentage by which the template should move. i.e. 0.2 = 20%. + :param p: Float indicating the percentage by which the template should + move. i.e. 0.2 = 20%. :type p: float - :param axis: One of ['x', 'y']. The axis along which the template will move. + :param axis: The axis on which the template will move. + One of ['x', 'y']. :type axis: str """ if axis not in ['x', 'y']: @@ -1354,20 +1378,21 @@ def move(self, p, axis): self.reset(axis, v1, v2, ov1, ov2) def moveto(self, x, y): - """ - Move a template to point (x,y), adjusting all attributes so data.x1 = x, and data.y1 = y. + """Move a template to point (x,y), adjusting all attributes so data.x1 = x, and data.y1 = y. :Example: .. doctest:: template_moveto - >>> t = vcs.createtemplate('example1', 'default') # Create template 'example1', inherits from 'default' - >>> t.moveto(0.2, 0.2) # Move everything so that data.x1= 0.2 and data.y1= 0.2 + >>> t=vcs.createtemplate('t_move2') # inherits default template + >>> t.moveto(0.2, 0.2) # Move template so x1 and y1 are 0.2 - :param x: Float representing the new coordinate of the template's data.x1 attribute. + :param x: Float representing the new coordinate of the template's + data.x1 attribute. :type x: float - :param y: Float representing the new coordinate of the template's data.y1 attribute. + :param y: Float representing the new coordinate of the template's + data.y1 attribute. :type y: float """ # p/=100. @@ -1383,20 +1408,18 @@ def moveto(self, x, y): self.reset('y', v1, v2, ov1, ov2) def scale(self, scale, axis='xy', font=-1): - """ - Scale a template along the axis 'x' or 'y' by scale - Positive values of scale mean increase - Negative values of scale mean decrease - The reference point is t.data.x1/y1 + """Scale a template along the axis 'x' or 'y' by scale + Positive values of scale mean increase. + Negative values of scale mean decrease. + The reference point is the template's x1 and y1 data. :Example: .. doctest:: template_scale - - >>> t = vcs.createtemplate('example1', 'default') # Create template 'example1', inherits from 'default' + >>> t=vcs.createtemplate('t_scale') # inherits default template >>> t.scale(0.5) # Halves the template size - >>> t.scale(1.2) # Upsize everything to 20% more than the original size + >>> t.scale(1.2) # Increases size by 20% >>> t.scale(2,'x') # Double the x axis :param scale: Float representing the factor by which to scale the template. @@ -1406,8 +1429,8 @@ def scale(self, scale, axis='xy', font=-1): :type axis: str :param font: 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' + 0: means do not scale the fonts. 1: means scale the fonts. + -1: means do not scale the fonts unless axis='xy' :type font: int """ @@ -1428,15 +1451,14 @@ def scale(self, scale, axis='xy', font=-1): self.scalefont(scale) def scalefont(self, scale): - """ - Scales the template font by scale. + """Scales the template font by scale. - Example: + :Example: - Create template 'example1' which inherits from 'default' template - t = vcs.createtemplate('example1', 'default') - reduces the fonts size by 2 - t.scalefont(0.5) + .. doctest:: template_scalefont + + >>> t=vcs.createtemplate('t_scfnt') # inherits default template + >>> t.scalefont(0.5) # reduces the fonts size by 2 :param scale: Float representing the factor by which to scale the template's font size. :type scale: float @@ -1460,57 +1482,84 @@ def drawLinesAndMarkersLegend(self, canvas, linecolors, linetypes, linewidths, markercolors, markertypes, markersizes, strings, scratched=None, bg=False, render=True): - """ - Draws a legend with line/marker/text inside a template legend box - Auto adjust text size to make it fit inside the box - Auto arrange the elements to fill the box nicely + """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: .. doctest:: template_drawLinesAndMarkersLegend - >>> import vcs >>> x = vcs.init() >>> t = vcs.createtemplate() - >>> t.drawLinesAndMarkersLegend(x, - ... ["red","blue","green"], ["solid","dash","dot"],[1,4,8], - ... ["blue","green","red"], ["cross","square","dot"],[3,4,5], - ... ["sample A","type B","thing C"],True) + >>> 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") :param canvas: a VCS canvas object onto which to draw the legend :type canvas: vcs.Canvas.Canvas - :param linecolors: list containing the colors of each line to draw - :type linecolors: list of either colorInt, (r,g,b,opacity), or string color names + :param linecolors: 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. + :type linecolors: `list`_ + + :param linetypes: A list containing the type of each line to draw. + Line types are represented as either integers or strings. + See :py:class:`vcs.line.Tl` for more information. + :type linetypes: `list`_ + + :param linewidths: A list containing floats each representing the + width of each line. + :type linewidths: `list`_ + + :param markercolors: 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. + :type markercolors: `list`_ - :param linetypes: list containing the type of each line to draw - :type linetypes: list on int of line stype strings + :param markertypes: A list of the marker types to draw. + Marker types are represented as either integers or strings. + See :py:class:`vcs.marker.Tm` for more information. + :type markertypes: `list`_ - :param linewidths: list containing each line width - :type linewidths: list of float + :param markersizes: A list of floats representing marker sizes. + :type markersizes: `list`_ - :param markercolors: list of the markers colors to draw - :type markercolors: list of either colorInt, (r,g,b,opacity), or string color names + :param strings: A list of strings to draw next to each line/marker. + :type strings: `list`_ - :param markertypes: list of the marker types to draw - :type markertypes: list of int or string of marker names + :param scratched: A list indicating which strings should be "scratched" + off in the template. - :param markersizes: list of the size of each marker to draw - :type markersizes: list of float + 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. - :param strings: list of the string to draw next to each line/marker - :type strings: list of string + Size of the scratched list must be equal to the size of the strings + list. - :param scratched: None (off) or list. list contains False where no scratch is needed - For scratched provide True or line type to use for scratch - color will match that of text - :type scratched: None or list of bool + Scratch color will match that of text. - :param bg: do we draw in background or foreground + If scratched is None, or is not provided, no strings will be + scratched. + :type scratched: `None`_ or `list`_ + + :param bg: Boolean value indicating whether or not to draw in the + background. Defaults to False. :type bg: bool - :param render: do we render or not (so it less flashy) + :param render: Boolean value indicating whether or not to render. + Defaults to True. :type render: bool """ return vcs.utils.drawLinesAndMarkersLegend(canvas, @@ -1520,13 +1569,26 @@ def drawLinesAndMarkersLegend(self, canvas, strings, scratched, bg, render) def drawAttributes(self, x, slab, gm, bg=False, **kargs): - """Draws attribtes of slab onto a canvas + """Draws attributes of slab onto a canvas + + :Example: + + .. doctest:: templates_drawAttributes + + >>> 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 + [...] :param x: vcs canvas onto which attributes will be drawn :type x: vcs.Canvas.Canvas :param slab: slab to get attributes from - :type slab: cdms2.tvariable.TransientVariable, numpy.ndarray + :type slab: cdms2.tvariable.TransientVariable or numpy.ndarray """ displays = [] # figures out the min and max and set them as atributes... @@ -1601,12 +1663,10 @@ def drawAttributes(self, x, slab, gm, bg=False, **kargs): def plot(self, x, slab, gm, bg=False, min=None, max=None, X=None, Y=None, **kargs): - """ - This plots the template stuff on the Canvas. + """This plots the template stuff on the Canvas. It needs a slab and a graphic method. - :returns: A list containing all the displays used - :rtype: list + .. pragma: skip-doctest TODO add example/doctest """ displays = [] @@ -1780,6 +1840,7 @@ def drawColorBar(self, colors, levels, legend=None, ext_1='n', 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 @@ -1788,6 +1849,22 @@ def drawColorBar(self, colors, levels, legend=None, ext_1='n', 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: + + .. pragma: skip-doctest TODO add example/doctest. And more documentation... """ kargs["donotstoredisplay"] = True @@ -2062,30 +2139,43 @@ def in_bounds(x): def ratio_linear_projection(self, lon1, lon2, lat1, lat2, Rwished=None, Rout=None, box_and_ticks=0, x=None): - """ - Computes ratio to shrink the data area of a template in order - that the overall area - has the least possible deformation in linear projection + """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: - Version: 1.1 - Notes: Thanks to Karl Taylor for the equation of "optimal" ratio - - Necessary arguments: - lon1, lon2: in degrees_east : Longitude spanned by plot - lat1, lat2: in degrees_north : Latitude spanned by plot - - Optional arguments: - Rwished: Ratio y/x wished, None=automagic - Rout: 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 - Returned: - vcs template object - - Usage example: - #USA - t.ratio_linear_projection(-135,-50,20,50) + .. doctest:: template_P_ratio_linear_projection + + >>> t=vcs.gettemplate() + >>> t.ratio_linear_projection(-135,-50,20,50) # USA + + :param lon1: Start longitude for plot. + :type lon1: `float`_ or `int`_ + + :param lon2: End longitude for plot + :type lon2: `float`_ or `int`_ + + :param lat1: Start latitude for plot. + :type lat1: `float`_ or `int`_ + + :param lat2: End latitude for plot + :type lat2: `float`_ or `int`_ + + :param Rwished: Ratio y/x wished. + If None, ratio will be determined automatically. + :type Rwished: `float`_ or `int`_ + + :param Rout: 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. + :type Rout: `float`_ or `int`_ """ # Converts lat/lon to rad @@ -2115,26 +2205,29 @@ def ratio_linear_projection(self, lon1, lon2, lat1, lat2, return def ratio(self, Rwished, Rout=None, box_and_ticks=0, x=None): - """ - Computes ratio to shrink the data area of a template + """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 - Version: 1.1 - - Necessary arguments: - Rwished: Ratio y/x wished - Optional arguments: - Rout: 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 - Returned: - vcs template object - - Usage example: - # y is twice x - t.ratio(2) + :Example: + + .. doctest:: template_P_ratio + + >>> t=vcs.gettemplate() + >>> t.ratio(2) # y is twice x + + :param Rwished: Ratio y/x wished. + Rwished MUST be provided. + :type Rwished: `float`_ or `int`_ + + :param Rout: 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 + :type Rout: str or None + + :returns: vcs template object + :rtype: vcs.template.P """ if x is None: x = vcs.init() diff --git a/vcs/testtemplate.py b/vcs/testtemplate.py deleted file mode 100644 index 1ceb283c3..000000000 --- a/vcs/testtemplate.py +++ /dev/null @@ -1,123 +0,0 @@ -""" -# Test Template (P) module -""" -############################################################################### -# # -# Module: testtemplate module # -# # -# Copyright: 2000, Regents of the University of California # -# This software may not be distributed to others without # -# permission of the author. # -# # -# Author: PCMDI Software Team # -# Lawrence Livermore NationalLaboratory: # -# support@pcmdi.llnl.gov # -# # -# Description: Used to test VCS's template object. # -# # -# Version: 4.0 # -# # -############################################################################### -# -# -# -############################################################################ -# # -# Import: VCS and cu modules. # -# # -############################################################################ - - -def test(): - import vcs - import cu # import vcs and cu - - f = cu.open('clt.nc') # open clt file - s = f.getslab('clt') # get slab clt - x = vcs.init() # construct vcs canvas - - x.show('template') # show the list of templates - t = x.createtemplate('test', 'AMIP') # create template 'test' from AMIP - x.show('template') # show the list of templates - - t.script('test', 'w') # save test template as a Python script - - # create isofill 'test' from 'default' isofill - g = x.createisofill('test') - - x.plot(g, s, t) # make isofill plot -# x.isofill(g,s,t) # make isofill plot - - ########################################################################## - # Show the many different ways to show the template members (attributes) # - # and their values. # - ########################################################################## - t.list() # list the templates members - t.list('text') # list only text members, same as t.list('Pt') - t.list('format') # list only format members, same as t.list('Pf') - # list only xtickmarks members, same as t.list('Pxt') - t.list('xtickmarks') - # list only ytickmarks members, same as t.list('Pyt') - t.list('ytickmarks') - t.list('xlabels') # list only xlabels members, same as t.list('Pxl') - t.list('ylabels') # list only ylabels members, same as t.list('Pyl') - # list only boxeslines members, same as t.list('Pbl') - t.list('boxeslines') - t.list('legend') # list only legend member, same as t.list('Pls') - t.list('data') # list only data member, same as t.list('Pds') - t.list('file') # list only file member and its values - t.file.list() # list only file member and its values - t.list('mean') # list only mean member and its values - t.mean.list() # list only mean member and its values - - ########################################################################## - # The screen x and y positions on the screen are normalized between 0 and 1 # - # for both the x and y axis. # - ########################################################################## - t.mean.priority = 0 # remove the "Mean" text from the plot - t.mean.priority = 1 # re-display the "Mean" text on the plot - t.mean.x = 0.5 # move the "Mean" text to x-axis center - t.mean.y = 0.5 # move the "Mean" text to y-axis center - - ########################################################################## - # Position the data in front of the "Mean" text, then move the "Mean" text # - # in front of the data. # - ########################################################################## - t.data.priority = 2 - t.data.priority = 3 -# The above does not work. I will fix this later when time permits. - - ########################################################################## - # Change the font representation for the "Mean" text. # - # You can set the text by using text objects or text names. # - ########################################################################## - tt = x.createtexttable('test') - to = x.createtextorientation('test') - t.mean.texttable = tt # set texttable by using texttable object - # set textorientation by using textorientation name - t.mean.textorientation = 'test' - # show the mean member and their new values - t.mean.list() - tt.font = 2 # change the font - to.height = 40 # change the height - - ########################################################################## - # Change the legend space. # - ########################################################################## - t.legend.list() # list the legend members - x.mode = 0 # turn the automatic update off - t.legend.x1 = 0.85 - t.legend.y1 = 0.90 - t.legend.x2 = 0.95 - t.legend.y2 = 0.16 - x.update() -# The above does not work. I will fix this later when time permits. - - print '***************************************************************************************' - print '****** ******' - print '****** T E M P L A T E T E S T C O M P L E T E D S U C E S S F U L L Y ******' - print '****** ******' - print '***************************************************************************************' - -if __name__ == "__main__": - test() diff --git a/vcs/textcombined.py b/vcs/textcombined.py index 79fccb0f5..bf5a9bf39 100644 --- a/vcs/textcombined.py +++ b/vcs/textcombined.py @@ -2,7 +2,7 @@ # Text Combined (Tc) module """ import vcs -from xmldocs import scriptdocs +from xmldocs import scriptdocs, listdoc # Adapted for numpy/ma/cdms2 by convertcdms.py ############################################################################### @@ -201,7 +201,9 @@ class together. From combining the two classess, the user will be able to set tc.valign='base' # Same as tcvalign=4 tc.valign='bottom' -""" + + .. pragma: skip-doctest TODO: convert examples to doctests + """ __slots__ = [ 's_name', @@ -413,12 +415,25 @@ def __init__(self, Tt_name=None, Tt_name_src='default', # # ########################################################################## def list(self): + """Lists the current values of object attributes + + :Example: + + .. doctest:: listdoc + + >>> a=vcs.init() + >>> ctc = vcs.createtextcombined # alias long name + >>> obj=ctc('list_tt', 'qa', 'list_tto', '7left') + >>> obj.list() # print textcombined attributes + ---------- ... ---------- + ... + """ if ((self.Tt_name == '__removed_from_VCS__') or (self.To_name == '__removed_from_VCS__')): raise ValueError('This instance has been removed from VCS.') - print "", "----------Text combined (Tc) member (attribute) listings ----------" + print "---------- Text combined (Tc) member (attribute) listings ----------" print "secondary method =", self.s_name - print "", "----------Text Table (Tt) member (attribute) listings ----------" + print "", "---------- Text Table (Tt) member (attribute) listings ----------" print "Tt_name =", self.Tt_name print "font =", self.font print "spacing =", self.spacing @@ -432,7 +447,7 @@ def list(self): print "x =", self.x print "y =", self.y print "projection =", self.projection - print "", "----------Text Orientation (To) member (attribute) listings ----------" + print "", "---------- Text Orientation (To) member (attribute) listings ----------" print "To_name =", self.To_name print "height =", self.height print "angle =", self.angle diff --git a/vcs/textorientation.py b/vcs/textorientation.py index 017765afe..fad37536d 100755 --- a/vcs/textorientation.py +++ b/vcs/textorientation.py @@ -24,7 +24,7 @@ # import VCS_validation_functions import vcs -from xmldocs import scriptdocs +from xmldocs import scriptdocs, listdoc def process_src(nm, code): @@ -151,6 +151,8 @@ class To(object): to.valign='base' # Same as tovalign=4 to.valign='bottom' + + .. pragma: skip-doctest TODO: convert examples to doctests """ __slots__ = [ 's_name', @@ -285,7 +287,7 @@ def __init__(self, To_name, To_name_src='default'): def list(self): if (self.name == '__removed_from_VCS__'): raise ValueError('This instance has been removed from VCS.') - print "", "----------Text Orientation (To) member (attribute) listings ----------" + print "---------- Text Orientation (To) member (attribute) listings ----------" print "secondary method =", self.s_name print "name =", self.name print "height =", self.height @@ -293,6 +295,7 @@ def list(self): print "path =", self.path print "halign =", self.halign print "valign =", self.valign + list.__doc__ = listdoc.format(name="textorientation", parent="") ########################################################################## # # diff --git a/vcs/texttable.py b/vcs/texttable.py index 6598e3d51..b6a07623c 100755 --- a/vcs/texttable.py +++ b/vcs/texttable.py @@ -25,7 +25,7 @@ import VCS_validation_functions import vcs import genutil -from xmldocs import scriptdocs +from xmldocs import scriptdocs, listdoc def process_src(nm, code): @@ -174,7 +174,8 @@ class Tt(object): # List of FloatTypes tt.y=[[.5,.4,.3], [.2,.1,0]] -""" + .. pragma: skip-doctest TODO: convert examples to doctests + """ __slots__ = [ 's_name', 'name', @@ -477,7 +478,7 @@ def __init__(self, Tt_name=None, Tt_name_src='default'): def list(self): if (self.name == '__removed_from_VCS__'): raise ValueError('This instance has been removed from VCS.') - print "", "----------Text Table (Tt) member (attribute) listings ----------" + print "---------- Text Table (Tt) member (attribute) listings ----------" print "secondary method =", self.s_name print "name =", self.name print "string =", self.string @@ -494,7 +495,7 @@ def list(self): print "x =", self.x print "y =", self.y print 'colormap =', self.colormap - + list.__doc__ = listdoc.format(name="texttable", parent="") ########################################################################## # # # Script out secondary text table method in VCS to a file. # diff --git a/vcs/unified1D.py b/vcs/unified1D.py index 6246b3b20..a519a4d1a 100644 --- a/vcs/unified1D.py +++ b/vcs/unified1D.py @@ -759,34 +759,34 @@ def __init__(self, name, name_src='default'): def xticlabels(self, xtl1='', xtl2=''): self.xticlabels1 = xtl1 self.xticlabels2 = xtl2 - xticlabels.__doc__ = xmldocs.xticlabelsdoc + xticlabels.__doc__ = xmldocs.xticlabelsdoc % {"name": "1d", "data": "f('u')"} def xmtics(self, xmt1='', xmt2=''): self.xmtics1 = xmt1 self.xmtics2 = xmt2 - xmtics.__doc__ = xmldocs.xmticsdoc + xmtics.__doc__ = xmldocs.xmticsdoc.format(name="1d") def yticlabels(self, ytl1='', ytl2=''): self.yticlabels1 = ytl1 self.yticlabels2 = ytl2 - yticlabels.__doc__ = xmldocs.yticlabelsdoc + yticlabels.__doc__ = xmldocs.yticlabelsdoc % {"name": "1d", "data": "f('u')"} def ymtics(self, ymt1='', ymt2=''): self.ymtics1 = ymt1 self.ymtics2 = ymt2 - ymtics.__doc__ = xmldocs.ymticsdoc + ymtics.__doc__ = xmldocs.ymticsdoc.format(name="1d") def datawc(self, dsp1=1e20, dsp2=1e20, dsp3=1e20, dsp4=1e20): self.datawc_y1 = dsp1 self.datawc_y2 = dsp2 self.datawc_x1 = dsp3 self.datawc_x2 = dsp4 - datawc.__doc__ = xmldocs.datawcdoc + datawc.__doc__ = xmldocs.datawcdoc.format(name="1d") def list(self): if (self.name == '__removed_from_VCS__'): raise ValueError('This instance has been removed from VCS.') - print "", "----------Yxvsx (GYx) member (attribute) listings ----------" + print "---------- Yxvsx (GYx) member (attribute) listings ----------" print "graphics method =", self.g_name print "name =", self.name print "projection =", self.projection @@ -813,7 +813,7 @@ def list(self): print "markercolor = ", self.markercolor print "markersize = ", self.markersize print "flip = ", self.flip - list.__doc__ = xmldocs.listdoc + list.__doc__ = xmldocs.listdoc.format(name="1d", parent="'default'") ########################################################################### # # diff --git a/vcs/utils.py b/vcs/utils.py index 26b20ad74..52223f917 100644 --- a/vcs/utils.py +++ b/vcs/utils.py @@ -1,3 +1,16 @@ +"""Utils contains functions and objects that provide VCS with useful utilities. + +.. _list: https://docs.python.org/2/library/functions.html#list +.. _tuple: https://docs.python.org/2/library/functions.html#tuple +.. _dict: https://docs.python.org/2/library/stdtypes.html#mapping-types-dict +.. _None: https://docs.python.org/2/library/constants.html?highlight=none#None +.. _str: https://docs.python.org/2/library/functions.html?highlight=str#str +.. _bool: https://docs.python.org/2/library/functions.html?highlight=bool#bool +.. _float: https://docs.python.org/2/library/functions.html?highlight=float#float +.. _int: https://docs.python.org/2/library/functions.html?highlight=float#int +.. _long: https://docs.python.org/2/library/functions.html?highlight=float#long +.. _file: https://docs.python.org/2/library/functions.html?highlight=open#file +""" # Adapted for numpy/ma/cdms2 by convertcdms.py import numpy import cdtime @@ -53,7 +66,27 @@ def get_png_dims(fnm): - """given the path to a png, return width, height""" + """Given the path to a png, return width, height of the png. + + :Example: + + .. doctest:: utils_get_png_dims + + >>> a=vcs.init(bg=True) + >>> box=vcs.getboxfill('polar') + >>> array=[range(10) for _ in range(10)] + >>> a.plot(box,array) # plot something on canvas + + >>> a.png('box.png', width=1536, height=1186) # make a png + >>> vcs.get_png_dims('box.png') # get (width, height) of 'box.png' + (1536, 1186) + + :param fnm: String specifying the path to a .png file + :type fnm: `str`_ + + :return: A tuple containing (width, height) of the given png. + :rtype: `tuple`_ + """ try: data = open(fnm, "rb").read() w, h = struct.unpack('>LL', data[16:24]) @@ -66,8 +99,7 @@ def get_png_dims(fnm): class Logo(object): - """ - Creates a 'logo' object + """Creates a 'logo' object This also to draw a logo either from a text string or a picture (png) file. Picture will be shrunk to fit within the canvas if it's too big to fit @@ -76,41 +108,37 @@ class Logo(object): .. doctest:: utils_Logo - >>> import vcs - >>> import os - >>> import sys + >>> import os, sys >>> x=vcs.init() >>> x.open() - >>> logo1 = vcs.utils.Logo(os.path.join(sys.prefix,"share","vcs","uvcdat.png")) + >>> path=os.path.join(sys.prefix,"share","vcs","uvcdat.png") + >>> logo1=vcs.utils.Logo(path) >>> logo1.x=.7 >>> logo1.y=.8 - >>> logo2 = vcs.utils.Logo("My Test Logo") >>> logo2.x = .2 >>> logo2.y = .2 - >>> logo1.plot(x) >>> logo2.plot(x) """ def __init__(self, source=None, x=.93, y=.95, width=None, height=None): - """ - Initialize a new "logo" object to be plotted later on a canvas + """Initialize a new "logo" object to be plotted later on a canvas :param source: text string or path to png file representing the logo - :type source: str + :type source: `str`_ :param x: x position of the logo's center in fraction of canvas (0>> import vcs - >>> import os - >>> import sys + >>> import os, sys >>> x=vcs.init() >>> x.open() - >>> logo1 = vcs.utils.Logo(os.path.join(sys.prefix,"share/vcs/uvcdat.png")) + >>> path=os.path.join(sys.prefix,"share/vcs/uvcdat.png") + >>> logo1 = vcs.utils.Logo(path) >>> logo1.x=.7 >>> logo1.y=.8 - >>> logo2 = vcs.utils.Logo("My Test Logo") >>> logo2.x = .2 >>> logo2.y = .2 - >>> logo1.plot(x) >>> logo2.plot(x) @@ -166,7 +190,7 @@ def plot(self, canvas, bg=True): :type canvas: vcs.Canvas.Canvas :param bg: do we plot in background (offscreen) mode or not? True/False - :type bg: bool + :type bg: `bool`_ """ if isinstance(self.source, basestring): cnv_info = canvas.canvasinfo() @@ -235,6 +259,40 @@ def process_range_from_old_scr(code, g): def dumpToDict(obj, skipped=[], must=[]): + """Takes a VCS object and serializes its properties and their associated + values in a Python `dict`_ . + + :Example: + + .. doctest:: utils_dumpToDict + + >>> b=vcs.getboxfill() + >>> t=vcs.gettemplate() + >>> bd=vcs.dumpToDict(b) # serializes all properties + >>> td=vcs.dumpToDict(t, skipped=['legend']) # skip legend property + >>> 'legend' in td[0].keys() # 'legend' should not be in dictionary + False + + :param obj: An instance of a VCS object to serialize + :type obj: A VCS object + + :param skipped: A list of strings, associated with property names to skip. + :type skipped: `list`_ + + :param must: A list of strings, associated with property names which must + be captured in the serialization. + :type must: `list`_ + + :return: A tuple containing: + + * a dictionary with mappings of the object's property names + to the values associated with those property names. + + * a dictionary with mappings of more complex properties' names + to sets containing any associated property values. + + :rtype: `tuple`_ + """ dic = {} associated = {"texttable": set(), "textorientation": set(), @@ -268,8 +326,53 @@ def dumpToDict(obj, skipped=[], must=[]): return dic, associated -def dumpToJson(obj, fileout, skipped=[ - "info", "member"], must=[], indent=indent, sort_keys=sort_keys): +def dumpToJson(obj, fileout, skipped=["info", "member"], must=[], indent=indent, sort_keys=sort_keys): + """Uses :py:func:`vcs.utils.dumpToDict` and `json.dumps`_ to construct a + JSON representation of a VCS object's property values. + + :Example: + + .. doctest:: utils_dumpToJson + + >>> box=vcs.getboxfill() + >>> vcs.dumpToJson(box, 'box.json') # output properties to file + >>> vcs.dumpToJson(box,None) # returns JSON string + '{...}' + + :param obj: An instance of a VCS object to serialize + :type obj: A VCS object + + :param fileout: A file or a string name of a file into which the JSON + will be written. + :type fileout: `str`_ or `file`_ + + :param skipped: A list of strings, associated with property names to skip. + :type skipped: `list`_ + + :param must: A list of strings, associated with property names which must + be captured in the serialization. + :type must: `list`_ + + :param indent: An integer representing whether to pretty-print the JSON. + + * If indent is a non-negative integer, JSON will be printed with proper + indentation levels. + + * If indent is None, 0, or negative, JSON will be printed in its most + compact form. + + :type indent: `int`_ or `None`_ + + :param sort_keys: Boolean value indicating whether output should be sorted + by key (True), or not (False) + :type sort_keys: `bool`_ + + :return: The VCS object's properties serialized into a JSON formatted `str`_ . + OR None, if fileout was specified. + :rtype: `str`_ or `None`_ + + .. _json.dumps: https://docs.python.org/2/library/json.html?highlight=dumps#json.dumps + """ dic, associated = dumpToDict(obj, skipped, must) if fileout is not None: if isinstance(fileout, str): @@ -323,11 +426,19 @@ def dumpToJson(obj, fileout, skipped=[ def getfontname(number): - """ - Retrieve a font name for a given font index. + """Retrieve a font name for a given font index. + + :Example: + + .. doctest:: utils_getfontname + + >>> vcs.getfontname(1) + 'default' + >>> vcs.getfontname(4) + 'Helvetica' :param number: Index of the font to get the name of. - :type number: int + :type number: `int`_ """ if number not in vcs.elements["fontNumber"]: raise Exception("Error font number not existing %i" % number) @@ -335,11 +446,19 @@ def getfontname(number): def getfontnumber(name): - """ - Retrieve a font index for a given font name. + """Retrieve a font index for a given font name. + + :Example: + + .. doctest:: utils_getfontnumber + + >>> vcs.getfontnumber('default') + 1 + >>> vcs.getfontnumber('Helvetica') + 4 :param name: Name of the font to get the index of. - :type name: str + :type name: `str`_ """ for i in vcs.elements["fontNumber"]: if vcs.elements["fontNumber"][i] == name: @@ -394,6 +513,29 @@ def process_src_element(code): def listelements(typ=None): + """List the elements of a given VCS object type. + + :Example: + + .. doctest:: utils_listelements + + >>> vcs.listelements() # list all vcs object types + ['1d', '3d_dual_scalar', '3d_scalar', '3d_vector', 'boxfill', ...] + >>> vcs.listelements('1d') + [...] + >>> vcs.listelements('boxfill') + [...] + + :param typ: String specifying the type of VCS object to list. + If None, list will contain VCS object type names. + :type typ: `str`_ + + :return: If typ is None, returns a list of VCS object type names. + If typ is a VCS object type, returns a list of the object of that type + currently present in VCS. + :rtype: `list`_ + """ + if typ is None: return sorted(vcs.elements.keys()) if typ in ("xvsy", "yxvsx", "scatter", "xyvsy"): @@ -419,19 +561,37 @@ def listelements(typ=None): # # def show(*args): - """ - Show the list of VCS primary and secondary class objects. + """Show the list of VCS primary and secondary class objects. :Example: .. doctest:: utils_show - >>> a=vcs.init() # Create a VCS Canvas instance, named 'a' - >>> a.show('boxfill') # List boxfill objects on Canvas 'a' - >>> a.show('isofill') # List isofill objects on Canvas 'a' - >>> a.show('line') # List line objects on Canvas 'a' - >>> a.show('marker') # List marker objects on Canvas 'a' - >>> a.show('text') # List text objects on Canvas 'a' + >>> vcs.show() # show all vcs object types + ['1d', '3d_dual_scalar', '3d_scalar', '3d_vector', 'boxfill', ...] + >>> vcs.show('boxfill') # List boxfill objects + *******************Boxfill Names List********************** + ... + *******************End Boxfill Names List********************** + >>> vcs.show('3d_vector') # List 3d_vector objects + *******************3d_vector Names List********************** + ... + *******************End 3d_vector Names List********************** + >>> vcs.show('3d_scalar') # List 3d_scalar objects + *******************3d_scalar Names List********************** + ... + *******************End 3d_scalar Names List********************** + >>> vcs.show('3d_dual_scalar') # List 3d_dual_scalar objects + *******************3d_dual_scalar Names List********************** + ... + *******************End 3d_dual_scalar Names List********************** + >>> vcs.show('1d') # List 1d objects + *******************1d Names List********************** + ... + *******************End 1d Names List********************** + + :param args: String name of a type of object to show, or None + :type args: `str`_ or `None`_ """ if args == (): return vcs.listelements() @@ -951,8 +1111,7 @@ def __str__(self): def minmax(*data): - """ - Return the minimum and maximum of a series of array/list/tuples + """Return the minimum and maximum of a series of array/list/tuples (or combination of these) You can combine list/tuples/arrays pretty much any combination is allowed @@ -969,10 +1128,10 @@ def minmax(*data): (-7.0, 8.0) :param data: A comma-separated list of lists/arrays/tuples - :type data: list + :type data: `list`_ :returns: A tuple in the form (min, max) - :rtype: tuple + :rtype: `tuple`_ """ mx = -1.E77 @@ -1001,8 +1160,7 @@ def myfunction(d, mx, mn): def mkevenlevels(n1, n2, nlev=10): - """ - Return a series of evenly spaced levels going from n1 to n2. + """Return a series of evenly spaced levels going from n1 to n2. By default 10 intervals will be produced. :Example: @@ -1016,17 +1174,17 @@ def mkevenlevels(n1, n2, nlev=10): >>> vcs.mkevenlevels(100,0,nlev=5) [100.0, 80.0, 60.0, 40.0, 20.0, 0.0] - :param n1: Beginning of range. Int or float. - :type n1: int, float + :param n1: Beginning of range. + :type n1: `int`_ or `float`_ :param n2: End of range. Int or float. - :type n2: int, float + :type n2: `int`_ or `float`_ :param nlev: Number of levels by which to split the given range. - :type nlev: int + :type nlev: `int`_ :returns: List of floats, splitting range evenly between n1 and n2 - :rtype: list + :rtype: `list`_ """ import numpy.ma lev = numpy.ma.arange(nlev + 1, dtype=numpy.float) @@ -1037,8 +1195,7 @@ def mkevenlevels(n1, n2, nlev=10): def mkscale(n1, n2, nc=12, zero=1, ends=False): - """ - This function return a nice scale given a min and a max + """This function return a nice scale given a min and a max .. warning:: @@ -1064,27 +1221,27 @@ def mkscale(n1, n2, nc=12, zero=1, ends=False): [0.0, 2.0, 4.0, 6.0, 8.0, 10.0, 12.0, 14.0, 16.0, 18.0, 20.0] :param n1: Minimum number in range. - :type n1: float + :type n1: `float`_ :param n2: Maximum number in range. - :type n2: float + :type n2: `float`_ :param nc: Maximum number of intervals - :type nc: int + :type nc: `int`_ :param zero: Integer flag to indicate how zero should be handled. Flags are as follows - -1: zero MUST NOT be a contour - 0: let the function decide # NOT IMPLEMENTED - 1: zero CAN be a contour (default) - 2: zero MUST be a contour - :type zero: int + -1: zero MUST NOT be a contour + 0: let the function decide # NOT IMPLEMENTED + 1: zero CAN be a contour (default) + 2: zero MUST be a contour + :type zero: `int`_ :param end: Boolean value indicating whether n1 and n2 should be part of the returned labels. - Defaults to False. - :type end: bool + Defaults to False. + :type end: `bool`_ :returns: List of floats split into nc intervals - :rtype: list + :rtype: `list`_ """ if n1 == n2: return [n1] @@ -1175,34 +1332,50 @@ def __split2contiguous(levels): def mklabels(vals, output='dict'): - """ - This function gets levels and output strings for nice display of the + """This function gets levels and output strings for nice display of the levels values. :Examples: .. doctest:: utils_mklabels - >>> a=vcs.mkscale(2,20,zero=2) - >>> vcs.mklabels (a) - {20.0: '20', 18.0: '18', 16.0: '16', 14.0: '14', 12.0: '12', - 10.0: '10', 8.0: '8', 6.0: '6', 4.0: '4', 2.0: '2', 0.0: '0'} - >>> vcs.mklabels ( [5,.005]) - {0.0050000000000000001: '0.005', 5.0: '5.000'} - >>> vcs.mklabels ( [.00002,.00005]) - {2.0000000000000002e-05: '2E-5', 5.0000000000000002e-05: '5E-5'} - >>> vcs.mklabels ( [.00002,.00005],output='list') + >>> scale=vcs.mkscale(2,20,zero=2) + >>> labels=vcs.mklabels(scale) + >>> keys=labels.keys() + >>> keys.sort() + >>> for key in keys: + ... print key, ':', labels[key] + 0.0 : 0 + 2.0 : 2 + 4.0 : 4 + 6.0 : 6 + 8.0 : 8 + 10.0 : 10 + 12.0 : 12 + 14.0 : 14 + 16.0 : 16 + 18.0 : 18 + 20.0 : 20 + >>> labels=vcs.mklabels([.00002,.00003,.00005]) + >>> keys=labels.keys() + >>> keys.sort() + >>> for key in keys: + ... print key, ':', labels[key] + 2e-05 : 2E-5 + 3e-05 : 3E-5 + 5e-05 : 5E-5 + >>> vcs.mklabels ([.00002,.00005],output='list') ['2E-5', '5E-5'] :param vals: List or tuple of float values - :type vals: list, tuple + :type vals: `list`_, `tuple`_ :param output: Specifies the desired output type. One of ['dict', 'list']. - :type output: str + :type output: `str`_ :returns: Dictionary or list of labels for the given values. - :rtype: dict, list - """ + :rtype: `dict`_ or `list`_ + """ import numpy.ma if isinstance(vals[0], list) or isinstance(vals[0], tuple): vals = __split2contiguous(vals) @@ -1302,8 +1475,7 @@ def mklabels(vals, output='dict'): def getcolors(levs, colors=None, split=1, white="white"): - """ - For isofill/boxfill purposes + """For isofill/boxfill purposes Given a list of levels this function returns the colors that would best spread a list of "user-defined" colors (default is 0 to 255, i.e 256 colors), always using the first and last color. @@ -1320,35 +1492,35 @@ def getcolors(levs, colors=None, split=1, white="white"): >>> a=[0.0, 2.0, 4.0, 6.0, 8.0, 10.0, 12.0, 14.0, 16.0, 18.0, 20.0] >>> vcs.getcolors (a) - [16, 41, 66, 90, 115, 140, 165, 189, 214, 239] + [0, 28, 57, 85, 113, 142, 170, 198, 227, 255] >>> vcs.getcolors (a,colors=range(16,200)) [16, 36, 57, 77, 97, 118, 138, 158, 179, 199] >>> vcs.getcolors(a,colors=[16,25,15,56,35,234,12,11,19,32,132,17]) [16, 25, 15, 35, 234, 12, 11, 32, 132, 17] >>> a=[-6.0, -2.0, 2.0, 6.0, 10.0, 14.0, 18.0, 22.0, 26.0] >>> vcs.getcolors (a,white=241) - [72, 241, 128, 150, 172, 195, 217, 239] + [0, 241, 128, 153, 179, 204, 230, 255] >>> vcs.getcolors (a,white=241,split=0) - [16, 48, 80, 112, 143, 175, 207, 239] + [0, 36, 73, 109, 146, 182, 219, 255] :param levs: levels defining the color ranges - :type levs: list, tuple + :type levs: `list`_ or `tuple`_ :param colors: A list/tuple of the of colors you wish to use - :type colors: list + :type colors: `list`_ or `tuple`_ :param split: Integer flag to split colors between two equal domains. - 0 : no split - 1 : split if the levels go from <0 to >0 - 2 : split even if all the values are positive or negative - :type split: int + 0 : no split + 1 : split if the levels go from <0 to >0 + 2 : split even if all the values are positive or negative + :type split: `int`_ :param white: If split is on and an interval goes from <0 to >0 this color will be used within this interval. - :type white: int, string, tuple + :type white: `int`_ or `str`_ or `tuple`_ :returns: List of colors - :rtype: list + :rtype: `list`_ """ if colors is None: @@ -1460,40 +1632,38 @@ def getcolors(levs, colors=None, split=1, white="white"): def generate_time_labels(d1, d2, units, calendar=cdtime.DefaultCalendar): - """ - Generates a dictionary of time labels for an interval of time, + """Generates a dictionary of time labels for an interval of time, in a user defined units system. :Example: - .. doctest:: generate_time_labels + .. doctest:: utils_generate_time_labels # Two ways to generate a dictionary of time labels - >>> lbls = generate_time_labels(cdtime.reltime(0,'months since 2000'), + >>> import cdtime + >>> lbls = vcs.generate_time_labels(cdtime.reltime(0,'months since 2000'), ... cdtime.reltime(12,'months since 2000'), - ... 'days since 1800',) # for the year 2000 in units of 'days since 1800' - >>> lbls = generate_time_labels(cdtime.reltime(0,'months since 2000'), + ... 'days since 1800') # for the year 2000 in units of 'days since 1800' + >>> lbls = vcs.generate_time_labels(cdtime.reltime(0,'months since 2000'), ... cdtime.comptime(2001), - ... 'days since 1800',) # for the year 2000 in units of 'days since 1800' - >>> lbls = generate_time_labels(0, 12, 'months since 2000', ) # Generate a dictionary of time labels - # for year 2000, units of 'months since 2000' + ... 'days since 1800') # for the year 2000 in units of 'days since 1800' + >>> lbls = vcs.generate_time_labels(0, 12, 'months since 2000') # time labels for year 2000 :param d1: The beginning of the time interval to be labelled. Expects a cdtime object. Can also take int, long, or float, which will be used to create a cdtime object with the given units parameter. - :type d1: cdtime object, int, long, float + :type d1: cdtime object or `int`_ or `long`_ or `float`_ :param d2: The end of the time interval to be labelled. Expects a cdtime object. Can also take int, long, or float, which will be used to create a cdtime object with the given units parameter. - :type d2: cdtime object, int, long, float + :type d2: cdtime object or `int`_ or `long`_ or `float`_ :param units: String with the format '[time_unit] since [date]'. - :type units: str + :type units: `str`_ - :param calendar: A cdtime calendar, - :type calendar: + :param calendar: A cdtime calendar :returns: Dictionary of time labels over the given time interval :rtype: dict @@ -1626,11 +1796,7 @@ def prettifyAxisLabels(ticks, axis): def setTicksandLabels(gm, copy_gm, datawc_x1, datawc_x2, datawc_y1, datawc_y2, x=None, y=None): - """ - Sets the labels and ticks for a graphics method made in python - - :Example: - + """Sets the labels and ticks for a graphics method made in python :param gm: A VCS graphics method to alter :type gm: VCS graphics method @@ -1639,22 +1805,22 @@ def setTicksandLabels(gm, copy_gm, datawc_x1, datawc_x2, :type copy_gm: VCS graphics method :param datawc_x1: Float value to set the graphics method's datawc_x1 property to. - :type datawc_x1: float + :type datawc_x1: `float`_ :param datawc_x2: Float value to set the graphics method's datawc_x2 property to. - :type datawc_x2: float + :type datawc_x2: `float`_ :param datawc_y1: Float value to set the graphics method's datawc_y1 property to. - :type datawc_y1: float + :type datawc_y1: `float`_ :param datawc_y2: Float value to set the graphics method's datawc_y2 property to. - :type datawc_y2: float + :type datawc_y2: `float`_ :param x: If provided, must be the string 'longitude' - :type x: str + :type x: `str`_ :param y: If provided, must be the string 'latitude' - :type y: str + :type y: `str`_ :returns: A VCS graphics method object :rtype: A VCS graphics method object @@ -1786,8 +1952,7 @@ def setTicksandLabels(gm, copy_gm, datawc_x1, datawc_x2, def getcolormap(Cp_name_src='default'): - """ - VCS contains a list of secondary methods. This function will create a + """VCS contains a list of secondary methods. This function will create a colormap class object from an existing VCS colormap secondary method. If no colormap name is given, then colormap 'default' will be used. @@ -1802,16 +1967,16 @@ def getcolormap(Cp_name_src='default'): .. doctest:: utils_getcolormap >>> a=vcs.init() - >>> a.show('colormap') # Show all the existing colormap secondary methods + >>> a.show('colormap') # Show all colormap secondary methods *******************Colormap Names List********************** ... *******************End Colormap Names List********************** - >>> cp=a.getcolormap() # cp instance of 'default' colormap secondary method - >>> cp2=a.getcolormap('rainbow') # cp2 instance of existing 'rainbow' colormap secondary method + >>> cp=a.getcolormap() # 'default' colormap + >>> cp2=a.getcolormap('rainbow') # 'rainbow' colormap :param Cp_name_src: String name of an existing colormap VCS object - :type Cp_name_src: str + :type Cp_name_src: `str`_ :returns: A pre-existing VCS colormap object :rtype: vcs.colormap.Cp @@ -1824,9 +1989,9 @@ def getcolormap(Cp_name_src='default'): def getcolorcell(cell, obj=None): - """ - Gets the colorcell of the provided object's colormap at the specified cell index. - If no object is provided, or if the provided object has no colormap, the default colormap is used. + """Gets the colorcell of the provided object's colormap at the specified + cell index. If no object is provided, or if the provided object has no + colormap, the default colormap is used. :Example: @@ -1836,16 +2001,16 @@ def getcolorcell(cell, obj=None): >>> b=vcs.createboxfill() >>> b.colormap='rainbow' >>> a.getcolorcell(2,b) - [85, 85, 85, 100.0] + [26, 1, 34, 100] :param cell: An integer value indicating the index of the desired colorcell. - :type cell: int + :type cell: `int`_ - :param obj: Optional parameter containing the object to extract a colormap from. + :param obj: Optional parameter with the object to get a colormap from. :type obj: Any VCS object capable of containing a colormap :return: The RGBA values of the colormap at the specified cell index. - :rtype: list + :rtype: `list`_ """ if obj is None: cmap = vcs.getcolormap() @@ -1857,8 +2022,7 @@ def getcolorcell(cell, obj=None): def setcolorcell(obj, num, r, g, b, a=100): - """ - Set a individual color cell in the active colormap. If default is + """Set a individual color cell in the active colormap. If default is the active colormap, then return an error string. .. note:: @@ -1879,22 +2043,24 @@ def setcolorcell(obj, num, r, g, b, a=100): >>> vcs.setcolorcell("AMIP",61,70,70,70) :param obj: String name of a colormap, or a VCS object - :type obj: str or VCS object + :type obj: `str`_ or VCS object - :param num: Integer specifying which color cell to change. Must be from 0-239. - :type num: int + :param num: Integer specifying which color cell to change. + Must be from 0-239. + :type num: `int`_ :param r: Integer specifying the red value for the colorcell - :type r: int + :type r: `int`_ :param g: Integer specifying the green value for the colorcell - :type g: int + :type g: `int`_ :param b: Integer specifying the blue value for the colorcell - :type b: int + :type b: `int`_ - :param a: Integer specifying the opacity value for the colorcell. Must be from 0-100. - :type a: int + :param a: Integer specifying the opacity value for the colorcell. + Must be from 0-100. + :type a: `int`_ """ if isinstance(obj, str): @@ -1907,23 +2073,25 @@ def setcolorcell(obj, num, r, g, b, a=100): def match_color(color, colormap=None): - """ - Returns the color in the colormap that is - closest to the required color. + """Returns the color in the colormap that's closest to the specified color. :Example: .. doctest:: utils_match_color >>> a=vcs.init() - >>> print vcs.match_color('salmon') - >>> print vcs.match_color('red') + >>> print vcs.match_color('salmon', 'magma') + 192 + >>> print vcs.match_color('red', 'rainbow') + 242 >>> print vcs.match_color([0,0,100],'default') # closest color from blue + 52 :param color: Either a string name, or a rgb value between 0 and 100. - :type color: str, int + :type color: `str`_ or `int`_ - :param colormap: A VCS colormap object. If not specified, the default colormap is used. + :param colormap: A VCS colormap object. If not specified, the default + colormap is used. :type colormap: vcs.colormap.Cp :returns: Integer value representing a matching rgb color @@ -1940,7 +2108,7 @@ def match_color(color, colormap=None): # Now gets the colormap to look in if colormap is None: - colormap = vcs.getcolormapname() + colormap = 'default' cmap = vcs.getcolormap(colormap) # Now tries determines the min rms diff @@ -1959,11 +2127,68 @@ def match_color(color, colormap=None): def monotonic(x): + """Uses `numpy.diff `_ + to determine whether the data given by x is monotonic in nature. + + :Example: + + .. doctest:: utils_monotonic + + >>> import numpy, cdms2, os + >>> from random import randint + >>> array=numpy.array([range(10) for _ in range(10)]) + >>> mask=[] # we will use this to create a random mask + >>> for _ in range(10): + ... mask.append([randint(0,1) for _ in range(10)]) + >>> ma=numpy.ma.MaskedArray(array, mask) + >>> if not os.path.exists(vcs.sample_data): + ... vcs.download_sample_data_files() # get some data for cdms2 + >>> f=cdms2.open(vcs.sample_data + '/clt.nc') + >>> v=f('v') # get variable 'v' from clt.nc + >>> vcs.monotonic(array) # monotonicity of 2D numpy array + True + >>> vcs.monotonic(ma) # monotonicity of simple masked array + True + >>> vcs.monotonic(v) # monotonicity of cdms2 variable + False + + :param x: The variable to test for monotonicity. + Can be any variable with an array-like structure. + Typical examples are numpy arrays, numpy masked arrays, + and cdms2 variables (examples for each shown above). + :type x: numpy.array or numpy.ma.MaskedArray or cdms2 variable + + :return: A boolean value indicating whether the given data is monotonic. + :rtype: `bool`_ + """ dx = numpy.diff(x) return numpy.all(dx <= 0) or numpy.all(dx >= 0) def getgraphicsmethod(type, name): + """Retrieves an existing graphics method, given by type and name. + + :Example: + + .. doctest:: utils_getgraphicsmethod + + >>> vcs.show('boxfill') # list available boxfills + *******************Boxfill Names List********************** + ... + *******************End Boxfill Names List********************** + >>> vcs.getgraphicsmethod('boxfill','polar') # get polar boxfill + + + :param type: String name of a VCS graphics method type + :type type: `str`_ + + :param name: String name of a VCS graphics method of the given type. + :type name: `str`_ + + :return: A graphics method of the given type and name. + If such a graphics method doesn't exist, None will be returned. + :rtype: VCS graphics method or `None`_ + """ import vcsaddons if type == "default": type = "boxfill" @@ -1979,12 +2204,40 @@ def getgraphicsmethod(type, name): def creategraphicsmethod(gtype, gname='default', name=None): + """Creates a graphics method of the type given by gtype. + + :Example: + + .. doctest:: utils_creategraphicsmethod + + >>> cgm=vcs.creategraphicsmethod # alias long name + >>> cgm('Gfm') # meshfill inherits default; name generated + + >>> cgm('boxfill','polar') # boxfill inherits polar; name generated + + >>> cgm('Gfi',name='my_gfi') # isofill inherits default; user-named + + + :param gtype: String name of the type of graphics method object to create. + :type gtype: `str`_ + + :param gname: String name of the specific graphics method for the new + graphics method to inherit. + :type gname: `str`_ + + :param name: String name for the new object. + If None, a unique name will be generated. + :type name: `str`_ or `None`_ + + :return: A graphics method object + + """ import vcsaddons if gtype in ['isoline', 'Gi']: func = vcs.createisoline elif gtype in ['isofill', 'Gfi']: func = vcs.createisofill - elif gtype in ['boxfill', 'default']: + elif gtype in ['boxfill', 'Gfb']: func = vcs.createboxfill elif gtype in ['meshfill', 'Gfm']: func = vcs.createmeshfill @@ -2027,21 +2280,35 @@ def getDataWcValue(v): def getworldcoordinates(gm, X, Y): - """ - Given a graphics method and two axes - figures out correct world coordinates. + """Given a graphics method and two axes, calculates correct world coordinates. + + :Example: + + .. doctest:: utils_getworldcoordinates + + >>> import cdms2, os + >>> if not os.path.exists(vcs.sample_data): + ... vcs.download_sample_data_files() # get some data for cdms2 + >>> f=cdms2.open(vcs.sample_data + '/clt.nc') + >>> v=f('v') # read variable v from clt.nc + >>> xax=v.getAxis(3) # X axis + >>> yax=v.getAxis(2) # Y axis + >>> box=vcs.getboxfill() + >>> vcs.getworldcoordinates(box, xax, yax) + [-180.0, 180.0, -88.288399, 88.288399] :param gm: A VCS graphics method object to get worldcoordinates for. :type gm: graphics method object :param X: A cdms2 transient axs - :type X: cdms2 transient axis + :type X: cdms2.axis.TransientAxis :param Y: A cdms2 transient axs - :type Y: cdms2 transient axis + :type Y: cdms2.axis.TransientAxis - :returns: - :rtype: + :returns: A list of the worldcoordinates associated with the given graphics + method and axes + :rtype: `list`_ """ # compute the spanning in x and y, and adjust for the viewport wc = [0, 1, 0, 1] @@ -2128,8 +2395,7 @@ def getworldcoordinates(gm, X, Y): def rgba_color(color, colormap): - """ - Try all of the various syntaxes of colors and return 0-100 RGBA values. + """Try all of the various syntaxes of colors and return 0-100 RGBA values. :Example: @@ -2141,13 +2407,13 @@ def rgba_color(color, colormap): :param color: The color to get the rgba value for. Can be an integer from 0-255, or a string name of a color. - :type color: int, str + :type color: `int`_ or `str`_ :param colormap: A VCS colormap :type colormap: vcs.colormap.Cp :returns: List of 4 floats; the R, G, B, and A values associated with the given color. - :rtype: list + :rtype: `list`_ """ try: # Is it a colormap index? @@ -2190,6 +2456,23 @@ def png_read_metadata(path): def download_sample_data_files(path=None): + """Downloads sample data to be used with VCS. + Default download directory is vcs.sample_data, but if __path__ is provided + then data will be downloaded to that path. + + :Example: + + .. doctest:: utils_download_sample_data + + >>> import os # use this to check if sample data already exists + >>> if not os.path.isdir(vcs.sample_data): + ... vcs.download_sample_data_files() + + :param path: String of a valid filepath. + If None, sample data will be downloaded into the + vcs.sample_data directory. + :type path: `str`_ or `None`_ + """ import requests import hashlib if path is None: @@ -2237,8 +2520,7 @@ def drawLinesAndMarkersLegend(canvas, templateLegend, linecolors, linetypes, linewidths, markercolors, markertypes, markersizes, strings, scratched=None, bg=False, render=True): - """ - Draws a legend with line/marker/text inside a template legend box + """Draws a legend with line/marker/text inside a template legend box Auto adjust text size to make it fit inside the box Auto arrange the elements to fill the box nicely @@ -2252,46 +2534,57 @@ def drawLinesAndMarkersLegend(canvas, templateLegend, >>> vcs.utils.drawLinesAndMarkersLegend(x,t.legend, ... ["red","blue","green"], ["solid","dash","dot"],[1,4,8], ... ["blue","green","red"], ["cross","square","dot"],[3,4,5], - ... ["sample A","type B","thing C"], None, True, True) + ... ["sample A","type B","thing C"], bg=True) >>> x.png("sample") :param canvas: a VCS canvas object onto which to draw the legend :type canvas: vcs.Canvas.Canvas - :param templateLegend: a template legend object used to determine the coordinates of the box and the box line type + :param templateLegend: a template legend object used to determine the + coordinates of the box and the box line type :type legendTemplate: vcs.Plegend.Pls - :param linecolors: list containing the colors of each line to draw - :type linecolors: list of either colorInt, (r,g,b,opacity), or string color names + :param linecolors: list containing the colors of each line to draw. + Colors must be specified as either integers, (r,g,b,opacity), + or string color names. + :type linecolors: `list`_ - :param linetypes: list containing the type of each line to draw - :type linetypes: list on int of line stype strings + :param linetypes: list containing the type of each line to draw. + values must be int or line type strings + :type linetypes: `list`_ - :param linewidths: list containing each line width - :type linewidths: list of float + :param linewidths: list containing each line width. + line widths must be of type float. + :type linewidths: `list`_ - :param markercolors: list of the markers colors to draw - :type markercolors: list of either colorInt, (r,g,b,opacity), or string color names + :param markercolors: list of the markers colors to draw. + Colors must be specified as either integers, (r,g,b,opacity), + or string color names. + :type markercolors: `list`_ - :param markertypes: list of the marker types to draw - :type markertypes: list of int or string of marker names + :param markertypes: list of the marker types to draw. + Marker type must be int or string of marker type names. + :type markertypes: `list`_ - :param markersizes: list of the size of each marker to draw - :type markersizes: list of float + :param markersizes: list of the size of each marker to draw. + marker size must be of type float. + :type markersizes: `list`_ :param strings: list of the string to draw next to each line/marker - :type strings: list of string + :type strings: `list`_ - :param scratched: None (off) or list. list contains False where no scratch is needed - For scratched provide True or line type to use for scratch - color will match that of text - :type scratched: None or list of bool + :param scratched: None (off) or list. list contains False where no scratch is + needed. For scratched, provide True or line type to use for scratch. + Color will match that of text. + :type scratched: `None`_ or `list`_ - :param bg: do we draw in background or foreground - :type bg: bool + :param bg: Boolean value indicating to draw in background (True), + Or foreground (False). + :type bg: `bool`_ - :param render: do we render or not (so it less flashy) - :type render: bool + :param render: Boolean value indicating whether or not to render the new + lines and markers. + :type render: `bool`_ """ nlines = len(linecolors) diff --git a/vcs/vcshelp.py b/vcs/vcshelp.py index 1d2056b3b..c39f68e80 100644 --- a/vcs/vcshelp.py +++ b/vcs/vcshelp.py @@ -27,21 +27,19 @@ def objecthelp(*arg): - """ - Print the documentation of each object in the argument list. + """Print the documentation of each object in the argument list. Prints a blank line if no documentation. :Example: .. doctest:: vcshelp_objecthelp - >>> objects = [ vcs.get3d_scalar(), vcs.getcolormap(), vcs.getboxfill() ] - >>> for object in objects: - ... vcs.objecthelp(object) - + >>> fa=vcs.getfillarea() + >>> vcs.objecthelp(fa) # print fillarea class documentation + The Fillarea class ... :param arg: Instance(s) of VCS object(s) to display the documentation for. - Multiple objects should be comma-delimited. + Multiple objects should be comma-delimited. :type arg: VCS object, or list of vcs objects """ for x in arg: @@ -49,7 +47,27 @@ def objecthelp(*arg): def help(*arg): + """Prints the documentation for named VCS class(es) and/or function(s). + + :Example: + + .. doctest:: vcs_vcshelp_help + >>> vcs.help('fillareaobject') # show fillarea help + The Fillarea class ... + >>> vcs.help('getboxfill') + + + :param arg: One or multiple strings containing the name(s) of object(s) + and/or function(s) to view the documentation for. + + .. note:: + + To get help on a VCS object class, you must supply a string that + is the name of that class, plus the word "object". + (i.e. vcs.help("templateobject") will print the documentation for + the template class) + """ if (len(arg) == 0): b = ['fillarea', 'line', 'marker', 'textcombined', 'textorientation', 'texttable', 'projection'] diff --git a/vcs/vector.py b/vcs/vector.py index f108751a5..b06a56020 100755 --- a/vcs/vector.py +++ b/vcs/vector.py @@ -774,7 +774,7 @@ def xyscale(self, xat='', yat=''): self.yaxisconvert = yat def list(self): - print "", "----------Vector (Gv) member (attribute) listings ----------" + print "---------- Vector (Gv) member (attribute) listings ----------" print "graphics method =", self.g_name print "name =", self.name print "projection =", self.projection diff --git a/vcs/xmldocs.py b/vcs/xmldocs.py index 200dc6cef..1de1eea18 100644 --- a/vcs/xmldocs.py +++ b/vcs/xmldocs.py @@ -1,45 +1,86 @@ plot_keywords_doc = """ - :param xaxis: Axis object to replace the slab -1 dim axis - :param yaxis: Axis object to replace the slab -2 dim axis, only if slab has more than 1D - :param zaxis: Axis object to replace the slab -3 dim axis, only if slab has more than 2D - :param taxis: Axis object to replace the slab -4 dim axis, only if slab has more than 3D - :param waxis: Axis object to replace the slab -5 dim axis, only if slab has more than 4D - :param xrev: reverse x axis - :param yrev: reverse y axis, only if slab has more than 1D - :param xarray: Values to use instead of x axis - :param yarray: Values to use instead of y axis, only if var has more than 1D - :param zarray: Values to use instead of z axis, only if var has more than 2D - :param tarray: Values to use instead of t axis, only if var has more than 3D - :param warray: Values to use instead of w axis, only if var has more than 4D - :param continents: continents type number - :param name: replaces variable name on plot - :param time: replaces time name on plot - :param units: replaces units value on plot - :param ymd: replaces year/month/day on plot - :param hms: replaces hh/mm/ss on plot - :param file_comment: replaces file_comment on plot - :param xbounds: Values to use instead of x axis bounds values - :param ybounds: Values to use instead of y axis bounds values (if exist) - :param xname: replace xaxis name on plot - :param yname: replace yaxis name on plot (if exists) - :param zname: replace zaxis name on plot (if exists) - :param tname: replace taxis name on plot (if exists) - :param wname: replace waxis name on plot (if exists) - :param xunits: replace xaxis units on plot - :param yunits: replace yaxis units on plot (if exists) - :param zunits: replace zaxis units on plot (if exists) - :param tunits: replace taxis units on plot (if exists) - :param wunits: replace waxis units on plot (if exists) - :param xweights: replace xaxis weights used for computing mean - :param yweights: replace xaxis weights used for computing mean - :param comment1: replaces comment1 on plot - :param comment2: replaces comment2 on plot - :param comment3: replaces comment3 on plot - :param comment4: replaces comment4 on plot - :param long_name: replaces long_name on plot - :param grid: replaces array grid (if exists) - :param bg: plots in background mode - :param ratio: sets the y/x ratio ,if passed as a string with 't' at the end, will aslo moves the ticks + :param xaxis: Axis object to replace the slab -1 dim axis. + (**keyword parameter**) + :param yaxis: Axis object to replace the slab -2 dim axis, only if slab has more than 1D. + (**keyword parameter**) + :param zaxis: Axis object to replace the slab -3 dim axis, only if slab has more than 2D. + (**keyword parameter**) + :param taxis: Axis object to replace the slab -4 dim axis, only if slab has more than 3D. + (**keyword parameter**) + :param waxis: Axis object to replace the slab -5 dim axis, only if slab has more than 4D. + (**keyword parameter**) + :param xrev: reverse x axis. + (**keyword parameter**) + :param yrev: reverse y axis, only if slab has more than 1D. + (**keyword parameter**) + :param xarray: Values to use instead of x axis. + (**keyword parameter**) + :param yarray: Values to use instead of y axis, only if var has more than 1D. + (**keyword parameter**) + :param zarray: Values to use instead of z axis, only if var has more than 2D. + (**keyword parameter**) + :param tarray: Values to use instead of t axis, only if var has more than 3D. + (**keyword parameter**) + :param warray: Values to use instead of w axis, only if var has more than 4D. + (**keyword parameter**) + :param continents: continents type number. + (**keyword parameter**) + :param name: replaces variable name on plot. + (**keyword parameter**) + :param time: replaces time name on plot. + (**keyword parameter**) + :param units: replaces units value on plot. + (**keyword parameter**) + :param ymd: replaces year/month/day on plot. + (**keyword parameter**) + :param hms: replaces hh/mm/ss on plot. + (**keyword parameter**) + :param file_comment: replaces file_comment on plot. + (**keyword parameter**) + :param xbounds: Values to use instead of x axis bounds values. + (**keyword parameter**) + :param ybounds: Values to use instead of y axis bounds values (if exist). + (**keyword parameter**) + :param xname: replace xaxis name on plot. + (**keyword parameter**) + :param yname: replace yaxis name on plot (if exists). + (**keyword parameter**) + :param zname: replace zaxis name on plot (if exists). + (**keyword parameter**) + :param tname: replace taxis name on plot (if exists). + (**keyword parameter**) + :param wname: replace waxis name on plot (if exists). + (**keyword parameter**) + :param xunits: replace xaxis units on plot. + (**keyword parameter**) + :param yunits: replace yaxis units on plot (if exists). + (**keyword parameter**) + :param zunits: replace zaxis units on plot (if exists). + (**keyword parameter**) + :param tunits: replace taxis units on plot (if exists). + (**keyword parameter**) + :param wunits: replace waxis units on plot (if exists). + (**keyword parameter**) + :param xweights: replace xaxis weights used for computing mean. + (**keyword parameter**) + :param yweights: replace xaxis weights used for computing mean. + (**keyword parameter**) + :param comment1: replaces comment1 on plot. + (**keyword parameter**) + :param comment2: replaces comment2 on plot. + (**keyword parameter**) + :param comment3: replaces comment3 on plot. + (**keyword parameter**) + :param comment4: replaces comment4 on plot. + (**keyword parameter**) + :param long_name: replaces long_name on plot. + (**keyword parameter**) + :param grid: replaces array grid (if exists). + (**keyword parameter**) + :param bg: plots in background mode. + (**keyword parameter**) + :param ratio: sets the y/x ratio ,if passed as a string with 't' at the end, will aslo moves the ticks. + (**keyword parameter**) :type xaxis: cdms2.axis.TransientAxis :type yaxis: cdms2.axis.TransientAxis :type zaxis: cdms2.axis.TransientAxis @@ -156,54 +197,113 @@ xaxisconvert = axisconvert.format(axis="x") yaxisconvert = axisconvert.format(axis="y") axesconvert = xaxisconvert + yaxisconvert +# for these docs, use string.format() when you use them +# Keys: +# {name}: String name to complete the call to vcs.(get|create)$OBJ_TYPE() +# {parent}: String argument for calls to vcs.(get|create)$OBJ_TYPE() that require specification of an obj to +# inherit from. Mainly used for get1d, but possible uses for text objects also exist (maybe others too). +# If providing a parent name, use either double quotes in a string literal, or a string literal in double +# quotes (i.e. '"$PARENT"' or "'$PARENT'"). Else, use an empty string. +# {data}: String used for plugging in plotting information. Plug in whatever data is set up in the docstring +# in a way that VCS will correctly plot the object. +# {x_y}: Literally will be the string "x" or "y". +# {axis}: "lat" or "lon", corresponding to the value you put in for {x_y} + colorsdoc = """ Sets the color_1 and color_2 properties of the object. - :param color1: Sets the :py:attr:`color_1` value on 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: + + .. doctest:: %(name)s_colors + + >>> a=vcs.init() + >>> array=[range(10) for _ in range(10)] + >>> ex=a.create%(name)s() + >>> ex.colors(0, 64) # use colorcells 0-64 of colormap + >>> a.plot(ex, %(data)s) + + + :param color1: Sets the :py:attr:`color_1` value on the object. :type color1: int - :param color2: Sets the :py:attr:`color_2` value on the object + :param color2: Sets the :py:attr:`color_2` value on the object. :type color2: int """ extsdoc = """ Sets the ext_1 and ext_2 values on the object. - :param ext1: Sets the :py:attr:`ext_1` value on the object. 'y' sets it to True, 'n' sets it to False. - :type ext1: str + :Example: - :param ext2: Sets the :py:attr:`ext_2` value on the object. 'y' sets it to True, 'n' sets it to False. - :type ext2: str - """ -ticlabelsdoc = """ - Sets the %sticlabels1 and %sticlabels2 values on the object + .. doctest {name}_exts + + >>> a=vcs.init() + >>> array=[range(10) for _ in range(10)] + >>> ex=a.create{name}() + >>> ex.exts(True, True) # arrows on both ends + >>> a.plot(ex, {data}) + + + :param ext1: Sets the :py:attr:`ext_1` value on the object. + 'y' sets it to True, 'n' sets it to False. + True or False can be used in lieu of 'y' and 'n'. + :type ext1: str or bool + + :param ext2: Sets the :py:attr:`ext_2` value on the object. + 'y' sets it to True, 'n' sets it to False. + True or False can be used in lieu of 'y' and 'n'. + :type ext2: str or bool + """ +mticsdoc = """ + Sets the {x_y}mtics1 and {x_y}mtics2 values on the object. - :param %stl1: Sets the object's value for :py:attr:`%sticlabels1`. - Must be a str, or a dictionary object with float:str mappings. - :type %stl1: {float:str} or str + .. note:: - :param %stl2: Sets the object's value for :py:attr:`%sticlabels2`. - Must be a str, or a dictionary object with float:str mappings. - :type %stl2: {float:str} or str - """ -xticlabelsdoc = ticlabelsdoc % (('x',) * 8) -yticlabelsdoc = ticlabelsdoc % (('y',) * 8) + 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 {name} after setting the mtics and template, + refer to :py:func:`vcs.Canvas.plot` or :py:func:`vcs.Canvas.{name}`. -mticsdoc = """ - Sets the %smtics1 and %smtics2 values on the object + :Example: - :param %smt1: Value for :py:attr:`%smtics1`. Must be a str, or a dictionary object with float:str mappings. - :type %smt1: {float:str} or str + .. doctest:: {name}_{x_y}mtics - :param %smt2: Value for :py:attr:`%smtics2`. Must be a str, or a dictionary object with float:str mappings. - :type %smt2: {float:str} or str + >>> a=vcs.init() + >>> ex=vcs.create{name}() + >>> ex.{x_y}mtics("{axis}5") # minitick every 5 degrees + >>> tmp=vcs.createtemplate() # custom template to plot minitics + >>> tmp.{x_y}mintic1.priority = 1 # plotting shows {x_y}mtics + + :param {x_y}mt1: Value for :py:attr:`{x_y}mtics1`. + Must be a str, or a dictionary object with float:str mappings. + :type {x_y}mt1: dict or str + + :param {x_y}mt2: Value for :py:attr:`{x_y}mtics2`. + Must be a str, or a dictionary object with float:str mappings. + :type {x_y}mt2: dict or str """ -xmticsdoc = mticsdoc % (('x',) * 8) -ymticsdoc = mticsdoc % (('y',) * 8) - +xmticsdoc = mticsdoc.format(x_y="x", axis="lon", name="{name}") +ymticsdoc = mticsdoc.format(x_y="x", axis="lat", name="{name}") datawcdoc = """ Sets the data world coordinates for object + :Example: + + .. doctest:: datawc_{name} + + >>> a=vcs.init() + >>> ex=a.create{name}('{name}_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) + :param dsp1: Sets the :py:attr:`datawc_y1` property of the object. :type dsp1: float @@ -221,11 +321,11 @@ :Example: - .. doctest:: xyscale_%s + .. doctest:: xyscale_{name} >>> a=vcs.init() - >>> ex=a.create%s('xyscale_ex') # create a boxfill to work with - >>> ex.xyscale(xat='linear', yat='linear') # set xaxisconvert and yaxisconvert to 'linear' + >>> ex=a.create{name}('{name}_xys') # make a {name} + >>> ex.xyscale(xat='linear', yat='linear') :param xat: Set value for x axis conversion. :type xat: str @@ -233,126 +333,226 @@ :param yat: Set value for y axis conversion. :type yat: str """ -listdoc = """ Lists the current values of object attributes""" +listdoc = """Lists the current values of object attributes + :Example: + + .. doctest:: listdoc + + >>> a=vcs.init() + >>> obj=a.get{name}({parent}) # default + >>> obj.list() # print {name} attributes + ---------- ... ---------- + ... + """ +# due to the labels being plugged in below, we have to use a dictionary to format this docstring. +# .format() messes up because it tries to interpret the labels dictionary as a keyword. +ticlabelsdoc = """ + Sets the %(x_y)sticlabels1 and %(x_y)sticlabels2 values on the object + + :Example: + + .. doctest:: %(name)s_%(x_y)sticlabels + + >>> a = vcs.init() + >>> import cdms2 # Need cdms2 to create a slab + >>> f = cdms2.open(vcs.sample_data+'/clt.nc') # open data file + >>> ex = a.create%(name)s() + >>> ex.%(x_y)sticlabels(%(labels)s) + >>> a.plot(ex, %(data)s) # plot shows labels + + + :param %(x_y)stl1: Sets the object's value for :py:attr:`%(x_y)sticlabels1`. + Must be a str, or a dictionary object with float:str mappings. + :type %(x_y)stl1: dict or str + + :param %(x_y)stl2: Sets the object's value for :py:attr:`%(x_y)sticlabels2`. + Must be a str, or a dictionary object with float:str mappings. + :type %(x_y)stl2: dict or str + """ +xticlabelsdoc = ticlabelsdoc % {"x_y": "x", "labels": '{0: "Prime Meridian", -121.7680: "Livermore", 37.6173: "Moscow"}', + "name": "%(name)s", "data": "%(data)s"} +yticlabelsdoc = ticlabelsdoc % {"x_y": "y", "labels": '{0: "Eq.", 37.6819: "L", 55.7558: "M"}', "name": "%(name)s", + "data": "%(data)s"} def populate_docstrings(type_dict, target_dict, docstring, method): """ - A function to generate docstrings from a dictionary. + A function to populate docstrings from a dictionary. Structure of the function is pretty specific to type_dicts shaped like xmldoc.obj_details. - Indentation of the docstring snippets looks screwy because they need to maintain alignment + Indentation of the docstring snippets is screwy because they need to maintain alignment with the original docstring entries for Sphinx to pick them up correctly. :param type_dict: The dictionary to parse for values used to fill in the docstring :param target_dict: An empty dictionary to be populated with docstrings :param docstring: The template docstring :param method: The method that the docstring is for + + :return: Has no return, but at the end target_dict should be full of formatted docstrings """ - dict = {} + d = {} for obj_type in type_dict.keys(): for obj_name in type_dict[obj_type].keys(): - # default values. Change as necessary. + # default values. Change as necessary. example1 = '' example2 = '' - dict['type'] = obj_type - dict['name'] = dict['sp_name'] = obj_name - dict['parent'] = type_dict[obj_type][obj_name]['parent'] - dict['parent2'] = type_dict[obj_type][obj_name]['parent2'] - dict['sp_parent'] = '' - dict['tc'] = '' - dict['ex2'] = '' - dict['rtype'] = type_dict[obj_type][obj_name]['rtype'] + d['type'] = obj_type + d['name'] = d['sp_name'] = obj_name + d['parent'] = type_dict[obj_type][obj_name]['parent'] + d['parent2'] = type_dict[obj_type][obj_name]['parent2'] + d['sp_parent'] = '' + d['tc'] = '' + d['rtype'] = type_dict[obj_type][obj_name]['rtype'] if type_dict[obj_type][obj_name]['title']: - dict['cap'] = dict['name'].title() + d['cap'] = d['name'].title() else: - dict['cap'] = dict['name'] + d['cap'] = d['name'] if obj_name in ['3d_vector', '3d_scalar', '3d_dual_scalar']: - dict['sp_name'] = 'dv3d' + d['sp_name'] = 'dv3d' elif obj_name in ['1d', 'scatter', 'textcombined', 'xyvsy']: if obj_name == 'textcombined': - dict['tc'] = """ - >>> a.createtextcombined('EXAMPLE_tt', 'qa', 'EXAMPLE_tto', '7left') # Create 'EXAMPLE_tt' and 'EXAMPLE_tto' - """ - dict['sp_parent'] = "'EXAMPLE_tt', 'EXAMPLE_tto'" + d['tc'] = """>>> try: # try to create a new textcombined, in case none exist + ... tc = vcs.createtextcombined('EX_tt', 'qa', 'EX_tto', '7left') + ... except: + ... pass + """ + d['sp_parent'] = "'EX_tt', 'EX_tto'" elif obj_name == '1d': - dict['sp_parent'] = "'default'" + d['sp_parent'] = "'default'" else: sp_parent = 'default_'+obj_name+'_' - dict['sp_parent'] = "'%s'" % sp_parent - dict['parent'] = dict['sp_parent'] + d['sp_parent'] = "'%s'" % sp_parent + d['parent'] = d['sp_parent'] + # From here to the end of the inner for loop is intended to be a section for specific use-cases for the template + # string keywords. This section aims to take the 'method' parameter and use it to insert proper examples for + # that method. + + # section for manageElements 'get' methods if method == 'get': - example1 = """%(tc)s - >>> ex=vcs.get%(name)s(%(sp_parent)s) # instance of '%(parent)s' %(name)s %(type)s%(plot)s""" - # set up dict['plot'] and dict['plot2'] + example1 = """>>> ex=vcs.get%(name)s(%(sp_parent)s) # '%(parent)s' %(name)s""" + if d['tc'] is not '': + example1 = d['tc'] + example1 + # set up d['plot'] and d['plot2'] plot = '' plot2 = '' numslabs = type_dict[obj_type][obj_name]['slabs'] - dict['slabs'] = '' - dict['args'] = '' + d['slabs'] = '' + d['args'] = '' if numslabs > 0: - dict['slabs'] = """ + if obj_name is "taylordiagram": + d['slabs'] = """ + >>> slab1 = [[0, 1, 2, 3, 4], [0.1, 0.2, 0.3, 0.4, 0.5]] # data""" + else: + d['slabs'] = """ >>> import cdms2 # Need cdms2 to create a slab - >>> f = cdms2.open(vcs.sample_data+'/clt.nc') # use cdms2 to open a data file - >>> slab1 = f('u') # use the data file to create a cdms2 slab""" - dict['args'] = ", slab1" + >>> f = cdms2.open(vcs.sample_data+'/clt.nc') # get data with cdms2 + >>> slab1 = f('u') # take a slab from the data""" + d['args'] = ", slab1" if numslabs == 2: slab2 = """ >>> slab2 = f('v') # need 2 slabs, so get another""" - dict['slabs'] = dict['slabs'] + slab2 - dict['args'] = dict['args'] + ", slab2" - # for vcs objects that have a self-named function, i.e. fillarea() + d['slabs'] += slab2 + d['args'] += ", slab2" + # for vcs objects that have a self-named plotting function, i.e. fillarea() if type_dict[obj_type][obj_name]['callable']: - plot = """%(slabs)s - >>> a.%(name)s(ex%(args)s) # plot using specified %(name)s object + plot = """ + >>> a.%(name)s(ex%(args)s) # plot %(name)s """ # set up plot2 plot2 = """ - >>> a.%(name)s(ex2%(args)s) # plot using specified %(name)s object - """ - # for objects like template, where a call to plot() needs to be made - elif obj_name not in ['textorientation', 'texttable', 'colormap']: - plot = """%(slabs)s - >>> a.plot(ex%(args)s) # plot using specified %(name)s object - """ + >>> a.%(name)s(ex2%(args)s) # plot %(name)s + """ % d + # for objects like template, where a call to plot() needs to be made + # objects in the list cannot be plotted without a graphics method + elif obj_name not in ['textorientation', 'texttable', 'colormap', 'projection', 'template']: + plot = """ + >>> a.plot(ex%(args)s) # plot %(name)s + + """ plot2 = """ - >>> a.plot(ex2%(args)s) # plot using specified %(name)s object + >>> a.plot(ex2%(args)s) # plot %(name)s """ - dict['plot'] = plot % dict - dict['ex1'] = example1 % dict - if dict['parent2']: + if obj_name.find('3d') >= 0: + if obj_name is "3d_vector": + plot = """ + >>> a.plot(ex%(args)s) # plot %(name)s + Sample rate: 6 + Sample rate: 6 + initCamera: Camera => (...) + + """ + else: + plot = """ + >>> a.plot(ex%(args)s) # plot %(name)s + initCamera: Camera => (...) + + """ + + if d['slabs'] is not '': + plot = d['slabs'] + plot + example1 += plot + d['example'] = example1 % d + if d['parent2']: example2 = """ - >>> ex2=vcs.get%(name)s('%(parent2)s') # instance of '%(parent2)s' %(name)s %(type)s%(plot2)s - """ - dict['plot2'] = plot2 % dict - dict['ex2'] = example2 % dict + >>> ex2=vcs.get%(name)s('%(parent2)s') # %(name)s #2""" + example2 += plot2 + d['example'] += example2 % d + # section for manageElements 'create' methods elif method == 'create': + # if obj_name is tc, d['tc'] should be populated by code that creates a tc at this point if obj_name == "textcombined": - example1 = dict['tc'] + """ - >>> vcs.listelements('%(name)s') # should now contain the 'qa_tt:::left_tto' %(name)s - [...'qa_tt:::left_tto'...]""" + example1 = d['tc'] + """>>> vcs.listelements('%(name)s') # includes new object + [...'EX_tt:::EX_tto'...]""" else: - example1 = """ - >>> ex=vcs.create%(name)s('%(name)s_ex1') # Create %(name)s '%(name)s_ex1' that inherits from 'default' - >>> vcs.listelements('%(name)s') # should now contain the '%(name)s_ex1' %(name)s - [...'%(name)s_ex1'...]""" - dict['ex1'] = example1 % dict - if dict['parent2']: - example2 = """ - >>> ex2=vcs.create%(name)s('%(name)s_ex2','%(parent2)s') # create '%(name)s_ex2' from '%(parent2)s' template - >>> vcs.listelements('%(name)s') # should now contain the '%(name)s_ex2' %(name)s - [...'%(name)s_ex2'...]""" - dict['ex2'] = example2 % dict + example1 = """>>> ex=vcs.create%(name)s('%(name)s_ex1') + >>> vcs.listelements('%(name)s') # includes new object + [...'%(name)s_ex1'...] + """ + d['example'] = example1 % d + if d['parent2']: + example2 = """>>> ex2=vcs.create%(name)s('%(name)s_ex2','%(parent2)s') + >>> vcs.listelements('%(name)s') # includes new object + [...'%(name)s_ex2'...] + """ + d['example'] += example2 % d elif method == 'script': + d['example'] = """>>> ex=a.get%(call)s(%(sp_parent)s) + >>> ex.script('filename.py') # append to 'filename.py' + >>> ex.script('filename','w') # make/overwrite 'filename.json'""" if obj_name == "textcombined": - dict['call'] = obj_name - dict['name'] = 'text table and text orientation' + d['call'] = obj_name + d['name'] = 'text table and text orientation' + d['example'] = d['tc'] + d['example'] else: - dict['call'] = dict['name'] - target_dict[obj_name] = docstring % dict - dict.clear() - -# contains VCS object details used to build Example doctests and fill in docstrings + d['call'] = d['name'] + d['example'] %= d + elif method == 'is': + example = """>>> a.show('%(name)s') # available %(name)ss + *******************%(cap)s Names List********************** + ... + *******************End %(cap)s Names List********************** + >>> ex = a.get%(name)s(%(sp_parent)s) + >>> vcs.queries.is%(name)s(ex) + 1 + """ + if d['tc'] is not '': + example = d['tc'] + example + d['example'] = example % d + target_dict[obj_name] = docstring % d + d.clear() + +# obj_details contains VCS object details used to build Example doctests and fill in docstrings +# Keys: +# "graphics method" / "secondary method" : These top-level keys specify the type of objects described within +# "callable"(bool): specifies whether the object has a self-named plotting function, i.e. fillarea() +# "parent"(str): specifies the name of the object to be used in inheritance for a first example. +# Usually 'default', but it can change based on situation (textcombined, 1d, xyvsy, etc.). +# "parent2"(str): specifies a name for object inheritance in a second example. If there is no reliable second +# object, (i.e. vcs only has a 'default' object pre-made), use an empty string. +# "rtype"(VCS object type): the type of the object to be returned. This is only used for manageElements 'get' and +# 'create' docstrings. +# "slabs"(int): used to specify how many slabs are needed to plot an object of the given type. 0 for none. +# "title"(bool): specifies whether to TitleCase the object's name for the output on vcs.show() obj_details = { "graphics method": { "taylordiagram": { @@ -471,7 +671,7 @@ def populate_docstrings(type_dict, target_dict, docstring, method): "projection": { "callable": False, "parent": "default", - "parent2": "polar", + "parent2": "orthographic", "rtype": "vcs.projection.Proj", "slabs": 1, "title": True, @@ -520,7 +720,7 @@ def populate_docstrings(type_dict, target_dict, docstring, method): }, "textcombined": { "callable": True, - "parent": "EXAMPLE_tt:::EXAMPLE_tto", + "parent": "EX_tt:::EX_tto", "parent2": "", "rtype": "vcs.textcombined.Tc", "slabs": 0, @@ -544,12 +744,29 @@ def populate_docstrings(type_dict, target_dict, docstring, method): }, } } -# dictionary to store all docstring dictionaries and their associated docstrings -# this will be used to populate all the docstrings in the same for loop (should better utilize locality) +# docstrings is a dictionary to store all docstring dictionaries and their associated docstrings +# this will be used to populate all the docstrings in the same for loop (should better utilize locality (maybe)) docstrings = {} -scriptdoc = """ - Saves out a copy of the %(name)s %(type)s in JSON, or Python format to a designated file. +# keywords in these docstring tmeplates relate somewhat to keys described in obj_details above. +# Population of these strings is taken care of in the populate_docstrings function. + +# For the sanity of future developers, I'll document the meaning of the keys I used and the convention I followed: +# Keys: +# 'name' : the name of the VCS object being referred to (boxfill, 1d, textorientation, etc.). This is used to talk +# about the object and to call the object's get/create functions in most cases. +# 'type' : the type of object we are dealing with. Mostly just 'secondary method' or 'graphics method'. +# 'sp_parent' : used if the object doesn't have a sensible default for its *get* function. Examples of objects which +# need this are the 1d family of objects and textcombined objects. If the object does have a sensible default, +# (e.g. getboxfill()) this key should be an empty string. When providing a string to 'sp_parent', it should be +# of format "'blah'" or '"blah"', and if multiple arguments are needed, they should be provided ('"blah", "blah"') +# 'tc' : no textcombined objects exist by default in VCS, so this key is for an entry that will create one when +# it is needed for an example. All other times, it will be an empty string. +# 'example' : this should be filled in with code examples in doctest format. Maintain indentation with the origin +# docstring. Most of the time, this means 3 indents (12 spaces) from the left side is where all your doctest +# lines should start. Look above, in populate_docstrings() to see what I'm tlaking about. +scriptdoc = """Saves out a copy of the %(name)s %(type)s, + in JSON or Python format to a designated file. .. note:: @@ -567,15 +784,15 @@ def populate_docstrings(type_dict, target_dict, docstring, method): .. doctest:: script_examples - >>> a=vcs.init() # Make a Canvas object to work with%(tc)s - >>> ex=a.get%(call)s(%(sp_parent)s) # Get default %(call)s - >>> ex.script('filename.py') # Append to a Python script named 'filename.py' - >>> ex.script('filename','w') # Create or overwrite a JSON file 'filename.json'. + >>> a=vcs.init() + %(example)s - :param script_filename: Output name of the script file. If no extension is specified, a .json object is created. + :param script_filename: Output name of the script file. + If no extension is specified, a .json object is created. :type script_filename: str - :param mode: Either 'w' for replace, or 'a' for append. Defaults to 'a', if not specified. + :param mode: Either 'w' for replace, or 'a' for append. + Defaults to 'a', if not specified. :type mode: str """ @@ -587,60 +804,59 @@ def populate_docstrings(type_dict, target_dict, docstring, method): .. doctest:: queries_is - >>> a=vcs.init() # Make a VCS Canvas object to work with:%(tc)s - >>> a.show('%(name)s') # Show all available %(name)s - *******************%(cap)s Names List********************** - ... - *******************End %(cap)s Names List********************** - >>> ex = a.get%(name)s(%(sp_parent)s) # To test an existing %(name)s object - >>> vcs.queries.is%(name)s(ex) - 1 + >>> a=vcs.init() + %(example)s :param obj: A VCS object :type obj: VCS Object - :returns: An integer indicating whether the object is a %(name)s %(type)s (1), or not (0). + :returns: An integer indicating whether the object is a + %(name)s %(type)s (1), or not (0). :rtype: int """ -get_methods_doc = """ - VCS contains a list of %(type)ss. This function will create a - %(sp_name)s class object from an existing VCS %(sp_name)s %(type)s. If - no %(sp_name)s name is given, then %(sp_name)s '%(parent)s' will be used. +get_methods_doc = """VCS contains a list of %(type)ss. This function + will create a %(sp_name)s object from an existing + VCS %(sp_name)s %(type)s. If no %(sp_name)s name is given, + then %(parent)s %(sp_name)s will be used. .. note:: VCS does not allow the modification of 'default' attribute sets. However, a 'default' attribute set that has been copied under a - different name can be modified. (See the :py:func:`vcs.manageElements.create%(name)s` function.) + different name can be modified. + (See the :py:func:`vcs.manageElements.create%(name)s` function.) :Example: .. doctest:: manageElements_get >>> a=vcs.init() - >>> vcs.listelements('%(name)s') # Show all the existing %(name)s %(type)ss - [...]%(ex1)s%(ex2)s""" + >>> vcs.listelements('%(name)s') # list all %(name)ss + [...] + %(example)s + """ create_methods_doc = """ - Create a new %(sp_name)s %(type)s given the the name and the existing - %(sp_name)s %(type)s to copy the attributes from. If no existing - %(sp_name)s %(type)s is given, then the default %(sp_name)s %(type)s will be used as the graphics method - to which the attributes will be copied from. + Create a new %(sp_name)s %(type)s given the the name and + the existing %(sp_name)s %(type)s to copy attributes from. + If no existing %(sp_name)s %(type)s is given, + the default %(sp_name)s %(type)s will be used as the + graphics method from which attributes will be copied. .. note:: - If the name provided already exists, then an error will be returned. %(type)s - names must be unique. + If the name provided already exists, then an error will be returned. + %(type)s names must be unique. :Example: .. doctest:: manageElements_create - >>> vcs.show('%(name)s') # show all available %(name)s - *******************%(cap)s Names List********************** - ... - *******************End %(cap)s Names List**********************%(ex1)s%(ex2)s""" + >>> vcs.listelements('%(name)s') # list %(name)ss + [...] + %(example)s + """ scriptdocs = {} docstrings['script'] = [scriptdocs, scriptdoc] @@ -650,10 +866,17 @@ def populate_docstrings(type_dict, target_dict, docstring, method): docstrings['get'] = [get_docs, get_methods_doc] create_docs = {} docstrings['create'] = [create_docs, create_methods_doc] + # populate all the docstrings for method in docstrings.keys(): populate_docstrings(obj_details, docstrings[method][0], docstrings[method][1], method) +############################################################################# +# # +# Attributes section # +# # +############################################################################# + exts_attrs = """ .. py:attribute:: ext_1 (str) @@ -709,6 +932,92 @@ def populate_docstrings(type_dict, target_dict, docstring, method): Color to use for missing value or values not in defined ranges """ +# 3d plot attributes +toggle_vs = """ + .. py:attribute:: Toggle{v_s}Plot (vcs.on or vcs.off) + + Toggles the visibility of the :ref:`dv3d-{v_s}` ({i_e}) plot constituent. + + **Interact Mode:** Toggle visibility with button click. +""" +toggle_volume = toggle_vs.format(v_s="Volume", i_e="volume render") +toggle_surface = toggle_vs.format(v_s="Surface", i_e="isosurface") +axisslider = """ + .. py:attribute:: {axis}Slider (float, vcs.on or vcs.off) + + Sets the position and visibility of the {axis} :term:`Slice` plane. + The position is in {coord} coordinates. + + **Interact Mode:** Adjust position with the slider. +""" +xslider = axisslider.format(axis="X", coord="longitude") +yslider = axisslider.format(axis="Y", coord="latitude") +zslider = axisslider.format(axis="Z", coord="relative (0.0 = bottom, > 1.0 = top)") +verticalscaling = """ + .. py:attribute:: VerticalScaling (float) + + Scales the vertical dimension of the plot. + + Accepts values from ~ 0.1 -- 10.0 + + **Interact Mode:** Adjust position with the slider. +""" +scalecolormap = """ + .. py:attribute:: ScaleColormap (floats: [max,min]) + + Sets the value range of the current colormap. + Initialized to the max (full) range value of the data. + + **Interact Mode:** Adjust colormap range (min, max) with the pair of sliders. +""" +scaletransferfunction = """ + .. py:attribute:: ScaleTransferFunction (floats: [max,min]) + + Sets the value range of the :term:`Volume` plot constituent, which maps this range of variable + values to opacity. Initialized to the max (full) range value of the data. + + **Interact Mode:** Adjust TF range (min, max) with the pair of sliders. +""" +toggleclipping = """ + .. py:attribute:: ToggleClipping (Up to six floats: [ xmin, xmax, ymin, ymax, zmin, zmax ]) + + Sets the clip bounds for the :term:`Volume` plot constituent. + + **Interact Mode:** Drag the spheres on the adjustable frame. +""" +isosurfacevalue = """ + .. py:attribute:: IsosurfaceValue (float between the variable max and min values) + + Sets the variable value that defines the isosurface (:term:`Surface`). + + **Interact Mode:** Adjust the isosurface value using the slider. +""" +scaleopacity = """ + .. py:attribute:: ScaleOpacity (floats: [ max, min ]) + + Sets the opacity range of the :term:`Volume` plot constituent, + which maps the selected range of variable values to this opacity range. + Initialized to [1,1] + + **Interact Mode:** Adjust opacity range (min, max) with the pair of sliders. +""" +basemapopacity = """ + .. py:attribute:: BasemapOpacity (float between 0.0 and 1.0.) + + Sets the opacity of the underlying earth map. + + **Interact Mode:** Adjust the opacity with the slider. +""" +camera = """ + .. py:attribute:: Camera (dict with three keys: 'Position', 'ViewUp', and 'FocalPoint') + + Sets the position and orientation of the camera. + + The values of Position and FocalPoint are positions in model coordinates, and ViewUp is a unit vector. + + **Interact Mode:** Left-click in window and drag to rotate. Right-click and drag to zoom/pan. + Shift-Left-click and drag to translate. +""" meshfill_doc = """ %s %s @@ -717,35 +1026,79 @@ def populate_docstrings(type_dict, target_dict, docstring, method): %s %s """ % (levels_attr, fillarea_colors_attr, fillarea_attrs, legend_attr, exts_attrs, missing_attr) - isofill_doc = meshfill_doc - fillareadoc = """ - fillareacolor :: (int) (None) color to use for outfilling - fillareastyle :: (str) ('solid') style to use for levels filling: solid/pattenr/hatch - fillareaindex :: (int) (None) pattern to use when filling a level and using pattern/hatch - """ # noqa + .. py:attribute:: fillareacolor (int) -linesdoc = """ line :: ([str,...]/[vcs.line.Tl,...]/[int,...]) (['solid',]) line type to use for each isoline, can also pass a line object or line object name - linecolors :: ([int,...]) ([241]) colors to use for each isoline - linewidths :: ([float,...]) ([1.0]) list of width for each isoline + color to use for outfilling + + .. py:attribute:: fillareastyle (str) + + style to use for levels filling: solid/pattenr/hatch + + .. py:attribute:: fillareaindex (int) + + pattern to use when filling a level and using pattern/hatch """ # noqa -linedoc = """ line :: ([str,...]/[vcs.line.Tl,...]/[int,...]) (['solid',]) line type to use for each isoline, can also pass a line object or line object name - linecolor :: (int) (241) colors to use for each isoline - linewidth :: (float) (1.0) list of width for each isoline +linesdoc = """ + .. py:attribute:: line ([str,...]/[vcs.line.Tl,...]/[int,...]) + + line type to use for each isoline, can also pass a line object or line object name + + .. py:attribute:: linecolors ([int,...]) + + colors to use for each isoline + + .. py:attribute:: linewidths ([float,...]) + + list of width for each isoline """ # noqa +linedoc = """ + .. py:attribute:: line ([str,...]/[vcs.line.Tl,...]/[int,...]) -textsdoc = """ - text :: (None/[vcs.textcombined.Tc,...]) (None) text objects or text objects names to use for each countour labels - textcolors :: (None/[int,...]) (None) colors to use for each countour labels + line type to use for each isoline, can also pass a line object or line object name + + .. py:attribute:: linecolor (int) + + color to use for each isoline + + .. py:attribute:: linewidth (float) + + width for each isoline """ # noqa +textsdoc = """ + .. py:attribute:: text (None/[vcs.textcombined.Tc,...]) + + text objects or text objects names to use for each countour label + + .. py:attribute:: textcolors (None/[int,...]) + colors to use for each countour label + """ # noqa markerdoc = """ - marker :: (None/int/str/vcs.marker.Tm) (None) markers type to use - markercolor :: (None/int) (None) color to use for markers - markersize :: (None/int) (None) size of markers + .. py:attribute:: marker (None/int/str/vcs.marker.Tm) + + markers type to use + + .. py:attribute:: markercolor (None/int) + + color to use for markers + + .. py:attribute:: markersize (None/int) + + size of markers """ +color_one_two_doc = """ + .. py:attribute:: color_1 (float) + + Used in conjunction with boxfill_type linear/log10, + sets the first value of the legend's color range. + .. py:attribute:: color_2 (float) + + Used in conjunction with boxfill_type linear/log10. + Sets the last value of the legend's color range. + """ ############################################################################# # # # Graphics Method input section. # @@ -753,14 +1106,19 @@ def populate_docstrings(type_dict, target_dict, docstring, method): ############################################################################# create_GM_input = """ - :param new_GM_name: (Ex: 'my_awesome_gm') name of the new graphics method object. If no name is given, then one will be created for use. + :param new_GM_name: (Ex: 'my_awesome_gm') name of the new graphics method + object. If no name is given, then one will be created for use. :type new_GM_name: str - :param source_GM_name: (Ex: 'default') copy the contents of the source object to the newly created one. If no name is given, then the 'default' graphics methond contents is copied over to the new object. + + :param source_GM_name: (Ex: 'default') copy the contents of the source + object to the newly created one. If no name is given, the 'default' + graphics method contents are copied over to the new object. :type source_GM_name: str """ # noqa get_GM_input = """ - :param GM_name: (Ex: 'default') retrieve the graphics method object of the given name. If no name is given, then retrieve the 'default' graphics method. + :param GM_name: (Ex: 'default') retrieve the graphics method object of the + given name. If no name is given, retrieve the 'default' graphics method. :type GM_name: str """ # noqa @@ -775,7 +1133,8 @@ def populate_docstrings(type_dict, target_dict, docstring, method): """ # noqa plot_2_1D_input = """ - :param slab_or_primary_object: Data at least 1D, last dimension(s) will be plotted, or secondary vcs object + :param slab_or_primary_object: Data at least 1D, last dimension(s) will be + plotted, or secondary vcs object :type slab_or_primary_object: array """ # noqa plot_2_1D_options = """ @@ -792,42 +1151,114 @@ def populate_docstrings(type_dict, target_dict, docstring, method): # # ############################################################################# plot_output = """ - :return: Display Plot object representing the plot. + :return: A VCS displayplot object. :rtype: vcs.displayplot.Dp """ - boxfill_output = """ boxfill :: (Ex: 0) no default """ - isofill_output = """ isofill :: (Ex: 0) no default """ - isoline_output = """ isoline :: (Ex: 0) no default """ - yxvsx_output = """ yxvsx :: (Ex: 0) no default """ - xyvsy_output = """ xyvsy :: (Ex: 0) no default """ - xvsy_output = """ xvsy :: (Ex: 0) no default """ - scatter_output = """ scatter :: (Ex: 0) no default """ - outfill_output = """ outfill :: (Ex: 0) no default """ - outline_output = """ outline :: (Ex: 0) no default """ +############################################################################# +# # +# Parameters section # +# # +############################################################################# +name = """ + :param name: Name of the object to be created. + :type name: `str`_ + """ +priority = """ + :param priority: The layer on which the object will be drawn. + :type priority: `int`_ + """ +color = """ + :param color: A color name from the + `X11 Color Names list `_, + or an integer value from 0-255, or an RGB/RGBA tuple/list + (e.g. (0,100,0), (100,100,0,50)) + :type color: `str`_ or `int`_ or `tuple`_ + """ +viewport = """ + :param viewport: 4 floats between 0 and 1 which specify the area that + X/Y values are mapped to inside of the canvas. + :type viewport: list of floats + """ +worldcoordinate = """ + :param worldcoordinate: List of 4 floats (xmin, xmax, ymin, ymax) + :type worldcoordinate: `list`_ + """ +x_y_coords = """ + :param x: List of lists of x coordinates. Values must be floats between + worldcoordinate[0] and worldcoordinate[1]. + :type x: `list`_ + + :param y: List of lists of y coordinates. Values must be floats between + worldcoordinate[2] and worldcoordinate[3]. + :type y: `list`_ + """ +projection = """ + :param projection: Specifies a geographic projection used to convert x/y + from spherical coordinates into 2D coordinates. + Can be a VCS projection or a string name of a projection + :type projection: `str`_ or :py:class:`vcs.projection.Proj` + """ +bg = """ + :param bg: Boolean value. True => object drawn in background (not shown on canvas). + False => object shown on canvas. + :type bg: bool + """ +output_width = """ + :param width: Float specifying the desired width of the output, + in the specified unit of measurement. + :type width: `float`_ + """ +output_file = """ + :param file: Desired string name of the output file + :type file: `str`_ + """ +output_height = """ + :param height: Float specifying the desired height of the output, + measured in the chosen units + :type height: `float`_ + """ +output_units = """ + :param units: One of ['inches', 'in', 'cm', 'mm', 'pixel', 'pixels', + 'dot', 'dots']. Defaults to 'inches'. + :type units: `str`_ + """ +canvas_width = """ + :param width: Width of the canvas, in pixels + :type width: `int`_ + """ +canvas_height = """ + :param height: Height of the canvas, in pixels + :type height: `int`_ + """ +canvas_clear = """ + :param clear: Indicates the canvas should be cleared (1), + or should not be cleared (0), when orientation is changed. + :type clear: `int`_ + """