Various Python objects and pyferret methods have been created which interact with the Ferret "engine" at the heart of PyFerret.These pyferret methods, or methods in these Python objects, perform the most common operations used in traditional Ferret and PyFerret.Using these objects and methods, Python users are alleviated from learning the Ferret "language" used to interact with this Ferret "engine" in PyFerret.Python users familiar with traditional Ferret can also use these objects and functions to quickly perform many Ferret operations before performing particular customizations at the Ferret prompt in PyFerret.
Please note that this is an on-going effort to eliminate the need for Python users to learn the Ferret "language" except for the most esoteric uses.At this time there are still many Ferret operations that need to be performed using the pyferret.run function using Ferret syntax.Also note that these objects (such as FerAxis) may change somewhat as more requirementson these objects are added.
Two fundamental PyFerret Python objects are the FerDSet, representing a Ferret data set, and the FerVar, representing a Ferret variable.
FerDSet
A FerDSet represents a dataset in Ferret.It is created giving the name of the dataset, which can be a URL to a remote dataset.(This translates into a call to Ferret USE command.)
FerDSet(filename, title='', qual='')
- filename (string): name of the dataset filename or http address
- title (string): title for the dataset for plots and listing.If not given, the Ferret name for the dataset will be used.
- qual (string): Ferret qualifiers to be used with the "USE" command
>>> coads = pyferret.FerDSet('coads_climatology')
>>> coads.show()
...
name title I J K L
SST SEA SURFACE TEMPERATURE 1:180 1:90 ... 1:12
AIRT AIR TEMPERATURE 1:180 1:90 ... 1:12
SPEH SPECIFIC HUMIDITY 1:180 1:90 ... 1:12
WSPD WIND SPEED 1:180 1:90 ... 1:12
UWND ZONAL WIND 1:180 1:90 ... 1:12
VWND MERIDIONAL WIND 1:180 1:90 ... 1:12
SLP SEA LEVEL PRESSURE 1:180 1:90 ... 1:12When the FerDSet is created, a FerVar object is created for each variable in the dataset. Each of these FerVar objects is associated with the FerDSet and can be access as an attribute of the FerDSet whose name is the name of the variable (case insensitive).
>>> coads.sstFerVar(varname='SST', dsetname='coads_climatology', title = '', defn='SST[d=coads_climatology]')
These FerVar objects can also be accessed using the the variable name as a key look-up value.
>>> coads['sst']FerVar(varname='SST', dsetname='coads_climatology', title = '', defn='SST[d=coads_climatology]')
which can be useful if your variable name happens to collide with the name of a FerDSet method (such as close).
FerVar
A FerVar represents a variable in Ferret. More specifically, it represents a Ferret variable definition. As such, it makes use of Ferret's delayed-mode analysis and "intelligent" on-demand access of data. A FerVar can be used in mathematical operations with other FerVar objects as well as numbers to create new FerVar objects.A FerVar must be associated with some FerDSet for it to be "known" in Ferret.So the following:
>>> coads.myval = (coads.uwnd**2 + coards.vwnd**2)**1.5 / (coads.sst + 273.15) >>> coads.show() ... MYVAL[D=...] = ((((UWND[D=...]) ^ 2) + ((VWND[D=...]) ^ 2)) ^ 1.5) / ((SST[D=...]) + 273.15)
defines a new variable myval as part of the coads dataset (only within Ferret), and assigns a new FerVarwith that definition to the attribute myval of the coads FerDSet.(This attribute is created if it did not exist, or the FerVar of an existing attribute is replaced.)No data values are actually accessed or computed, however, until there is a need for these values, such as for plotting or pulling the data into Python as a NumPy array.
>>> pyferret.shadeplot(coads.myval['120E':'120W','20S':'20N','15-JUN']) >>> myval_dataarray = coads.myval.data >>> myval_dataarray.shape (180, 90, 1, 12, 1, 1)
A FerVar has attributes for obtaining the data array (.data), the grid for the data (.grid), the unit string for the data (.unit), and the missing value for the data (.missval).The are also corresponding FerVar methods for obtaining these values (getdata, getgrid, getunit, getmissval).A FerVar variable can be regridded to to the grid of another variable using the regrid method,thus allow two variables on different grids to be combined.Any created Ferret variables can be redefined simple by reassigning the attribute
>>> coads.myval = (coads.uwnd**2 + coards.vwnd**2)**0.5
or can be deleted by deleting the attribute (del coads.myval).Note that variables from the data set file (such a coads.sst) cannot be redefined or deleted.
A FerVar can be constructed from a definition in Ferret syntax, although this is not normally done by a PyFerret user.Again, note that the variable name and definition is not known to the Ferret "engine" until the FerVar is assignedas an attribute to a FerDSet, with the attribute name used as the name of the variable in the Ferret "engine".
FerVar(defn=None, title=None)
- defn (string): Ferret-syntax definition of the variable
- title (string): title (descriptive long name) for this variable
FerAggDSet
Ferret and PyFerret now support on-the-fly aggregation of a number of data sets along the time (T), ensemble (E), or forecast (F) axis.The FerAggDSet is a type of FerDSet that provides this on-the-fly aggregation of datasets in Ferret to Python users.
FerAggDSet(name, dsets, along='T', title='', warn=True, hide=False)
Aggregates the given list of datasets along the given axis. For each data variable in common among these datasets, a FerVar is created and assigned as an attribute of this class instance using the name of the variable.
- name (string): Ferret name for this aggregated dataset
- dsets (sequence of strings and/or FerDSets): datasets to aggregate.A string will be interpreted as a filename for creating a FerDSet.
- along ('T', 'E', 'F'): axis along which to aggregate the datasets
- title (string): title for the dataset for plots and listing;if not given, the Ferret name for the dataset will be used
- warn (bool): issue warning messages about variables not in common amongall member datasets (either not present or not using the same grid)
- hide (bool): hide the member datasets in standard Ferret listings such as with pyferret.show()
Since a FerAggDSet is a type of FerDSet, it can be used anywhere a FerDSet can be used.
FerPyVar
PyFerret allows data in a Python NumPy array to be added as a Ferret variable.The FerPyVar simplifies this process.
FerPyVar(data, grid, missval=nan, unit=None, title=None)
- data (up to 6D array/array-like of float): data for the variable
- grid (FerGrid): grid for the variable
- missval (float or single-element array of float): value used to indicate missing data
- unit (string): unit for the data
- title (string): title (descriptive long name) for the variable in Ferret
Because a FerPyVar is a type of FerVar, it can be used wherever a FerVar can be used.
FerGrid
The FerGrid object represents a grid for a variable in Ferret.The grid of a FerVar can be obtained using the .grid attribute or getgrid method of the FerVar.A new FerGrid can be obtained by modifying one axis of an existing FerGrid using the copy method.Or a FerGrid can be created new by supplying the sequence of FerAxis objects making up the grid.
FerGrid(axes=None, name=None)
- axes (sequence of FerAxis): axes of this grid
- name (string): Ferret name for the grid
FerAxis
Note: this FerAxis object is not complete and is likely to undergo changes.
The FerAxis object represents an axis in Ferret.At this time a FerAxis object is created by providing the axis type, axis coordinates and unit, and a name for the axis.
FerAxis(coords=None, axtype=None, unit=None, name=None)
- axtype (int): type of the axis; valid values are
- pyferret.AXISTYPE_LONGITUDE
- pyferret.AXISTYPE_LATITUDE
- pyferret.AXISTYPE_LEVEL
- pyferret.AXISTYPE_TIME
- pyferret.AXISTYPE_CUSTOM (axis unit not recognized by Ferret)
- pyferret.AXISTYPE_ABSTRACT (axis is unit-less integer values)
- pyferret.AXISTYPE_NORMAL (axis is normal to the data)
If not given but coords is given, AXISTYPE_CUSTOM is used;if not given and coords is not given, AXISTYPE_NORMAL is used.
- coords (sequence of numeric): coordinate values of the axis.For an abstract axis or an axis normal to the data, this argument is ignored.
- unit (string): unit of the axis.For abstract axes, or axes normal to the data, this argument is ignored.
- name (string): Ferret name for the axis.For an axis normal to the data, this argument is ignored.
FerRegion
Note: this is a newer object added to PyFerret, but the intent is to support specification of FerRegion objects invarious methods to conveniently limit the area of operations to that specified by the FerRegion.More support will be added for various region format specifications.
A FerRegion represents a region of in Ferret. This region specifies the longitude, latitude, level, time, ensemble, and/or forecast elements of an area of interest.
FerRegion(X=None, Y=None, Z=None, T=None, E=None, F=None, I=None, J=None, K=None, L=None, M=None, N=None, qual='')
A FerRegion is created by giving the region limits as slices along the longitude (X or I), latitude (Y or J), level (Z or K), time (T or L),ensemble (E or M), and/or forecast (F or N) axes in terms of coordinates (X, Y, Z, T, E, F) or indices (I, J, K, L, M, N).So the following specified a tropical Pacific region:
>>> troppac = pyferret.FerRegion(X='120E:120W', Y='20S:20N')
New pyferret methods include:
showdata
Show information about all datasets currently open in the Ferret.
showdata(brief=True, qual='')
- brief (boolean): if True (default), a brief report is shown; otherwise a full report is shown.
- qual (string): Ferret qualifiers to add to the SHOW DATA command
setwindow
Specify the plotting window, including size of the window, to use for subsequent plots.
setwindow(num=1, plotasp=None, axisasp=None, color=None, thick=None, logo=None)
- num (int): window number 1-8 to use for plots.
- plotasp (float): aspect ratio (Y/X) for the plot window. If not given, the current ratio is unchanged. The default ratio on start-up is 0.86
- axisasp (float): aspect ratio (Y/X) for the plot axes. If not given, the current ratio is unchanged. The default ratio on start-up is 0.75
- color (string, tuple of int): background color for the plot; can be one of the color names 'black', 'blue', 'green', 'lightblue', 'purple', or 'red', or a tuple of int values in [0,100] giving RGB or RGBA values. If not given, the current value is unchanged. The default background color on start-up is opaque white.
- thick (float): line thickness scaling factor for the plot. If not given, the current scaling factor is unchanged. The default line thickness scaling factor on start-up is 1.0
- logo (boolean): include the Ferret logo in the plot? If not given, the current value is unchanged. The default on start-up is to include the logo.
settextstyle
Specify the style, including font, of the text in any subsequent plots.
settextstyle(font='', color='', bold=False, italic=False)
- font (string): name of the font to use; if empty, 'Arial' is used.
- color (string): color name, RGB tuple, or RGBA tuple describing the color of the text. The R,G,B, and A components are integer percentages; thus values in [0,100]
- bold (bool): use bold font?
- italic (bool): use italic font?
contourplot
Create a contour plot of a (two-dimensional) Ferret variable.
contourplot(fvar, region=None, over=False, qual='')
- fvar (string or FerVar): Ferret variable to plot
- region (FerRegion): space-time region to plot; if None, the full extents of the data will be used
- over (bool): overlay on an existing plot?
- qual (string): qualifiers to add to the Ferret SHADE command
fillplot
Create a color-filled contour plot of a Ferret variable. Drawing of the contour lines themselves is optional.
fillplot(fvar, line=False, region=None, over=False, qual='')
- fvar (string or FerVar): Ferret variable to plot
- line (bool): draw the contour lines?
- region (FerRegion): space-time region to plot; if None, the full extents of the data will be used
- over (bool): overlay on an existing plot?
- qual (string): qualifiers to add to the Ferret SHADE command
lineplot
Create a line plot of the given Ferret variable, possibly versus another Ferret variable, possibly colored by yet another Ferret variable.
lineplot(fvar, vs=None, color=None, thick=None, dash=None, title=None, region=None, over=False, label=True, qual='')
- fvar (string or FerVar): Ferret variable to plot
- vs (string or FerVar): if given, plot the above variable versus this variables
- color: line color or variable used to determine line color; if
- None: Ferret default color used,
- color name (string): name of color to use,
- color tuple (3 or 4-tupe of [0,100] int values): RGB or RGBA of color to use,
- FerVar or variable name string: color according to the value of this variable
Note: color name strings are limited to (case insensitive) 'black', 'red', 'green', 'blue', 'lightblue', and 'purple'; other strings are assumed to be variable names
- thick (float): line thickness scaling factor
- dash (4-tuple of float): draws the line as a dashed line where the four values are the first drawn stroke length, first undrawn stroke length, second drawn stroke length, second undrawn stroke length of two dashes
- title (string): title for the plot; if not given, Ferret's default title is used
- region (FerRegion): space-time region to plot; if None, the full extents of the data will be used
- over (bool): overlay onto an existing plot
- label (bool): if False, suppress all plot labels
- qual (string): qualifiers to add to the Ferret PLOT/LINE command
pointplot
Create a point (scatter) plot of the given Ferret variable, possibly versus another Ferret variable, possibly colored by yet another Ferret variable.
pointplot(fvar, vs=None, color=None, sym=None, symsize=None, thick=None, line=False, title=None, region=None, over=False, label=True, qual='')
- fvar (string or FerVar): Ferret variable to plot
- vs (string or FerVar): if given, plot the above variable versus this variables
- color: line color or variable used to determine line color; if
- None: Ferret default color used,
- color name (string): name of color to use,
- color tuple (3 or 4-tupe of [0,100] int values): RGB or RGBA of color to use,
- FerVar or variable name string: color according to the value of this variable
Note: color name strings are limited to (case insensitive) 'black', 'red', 'green', 'blue', 'lightblue', and 'purple'; other strings are assumed to be variable names
- sym (int): Ferret symbol number of the symbol to draw for the points. If not given, Ferret selects an appropriate symbol.
- symsize (float): size of the symbol in inches. If not given, Ferret select an appropriate size.
- thick (float): line thickness scaling factor when drawing symbols and lines
- line (bool): if True, draw a line between symbols/points
- title (string): title for the plot; if not given, Ferret's default title is used
- region (FerRegion): space-time region to plot; if None, the full extents of the data will be used
- over (bool): overlay onto an existing plot
- label (bool): if False, suppress all plot labels
- qual (string): qualifiers to add to the Ferret PLOT/LINE command
shadeplot
Create a grid plot colored by values of a Ferret variable
shadeplot(fvar, region=None, over=False, qual='')
- fvar (string or FerVar): Ferret variable to plot
- region (FerRegion): space-time region to plot; if None, the full extents of the data will be used
- over (bool): overlay on an existing plot?
- qual (string): qualifiers to add to the Ferret SHADE command
shadeland
Shade land masses for the current longitude-latitude plot or a specified X-Y region.
shadeland(res=20, color='gray', over=True, solid=True, X=None, Y=None)
- res (int): ETOPO dataset resolution (in minutes of a degree) to use; the corresponding ETOPO dataset (eg, etopo20.cdf for 20) must be available. Typically 5, 10, 20, 40, 60, 120 are available from Ferret's standard datasets.
- color (str): name of the color or color palette to used for land.
- over (bool): if true, overlay onto the current longitude-latitude plot; if False, create a new plot of the given region
- solid (bool): if True, shade the land in a single solid color; if False, shade different elevations using the given color palette
- X (str): longitude limits for the region as low:high If not given and over is False, '0E:360E' is used. if not given and over is True, the full range of the given plot is used.
- Y (str): latitude limits for the region as low:high If not given and over is False, '90S:90N' is used. If not given and over is True, the full range of the given plot is used.
shadewater
Shade water masses for the current longitude-latitude plot or a specified X-Y region.
shadewater(res=20, color='gray', over=True, solid=True, X=None, Y=None)
- res (int): ETOPO dataset resolution (in minutes of a degree) to use; the corresponding ETOPO dataset (eg, etopo20.cdf for 20) must be available. Typically 5, 10, 20, 40, 60, 120 are available from Ferret's standard datasets.
- color (str): name of the color or color palette to used for water masses
- over (bool): if true, overlay onto the current longitude-latitude plot; if False, create a new plot of the given region
- solid (bool): if True, shade the water masses in a single solid color; if False, shade different depths using the given color palette
- X (str): longitude limits for the region as low:high; if not given and over is False, '0E:360E' is used
- Y (str): latitude limits for the region as low:high; if not given and over is False, '90S:90N'
saveplot
Save the current plot in a specified format; size of the saved plot can be specified
saveplot(name, fmt='', xpix=None, ypix=None, xinch=None, yinch=None, qual='')
- name (string): name of the file to contain the plot
- fmt (string): format of the plot file; if not given, the format is guessed from the filenam extension.
- xpix (int): number of pixels in width of the saved raster (eg, PNG) plot
- ypix (int): number of pixels in the height of the saved raster (eg, PNG) plot
- xinch (float): inch width of the saved vector (eg, PDF) plot
- yinch (float): inch height of the save vector (eg, PDF) plot
- qual (string): qualifiers to add to the Ferret FRAME command