PyFerret Python functions and constants - Ferret/PyFerret Documentation

Python functions and constants provided by the pyferret module

Below is a listing of the functions provided by the pyferret module at this time along with a brief description of the function. A more complete listing and complete descriptions of the functions can be found using the Python help command. The command help(pyferret) will give the latest description of the module and detailed descriptions of all the functions contained in the module. Using help with a specific pyferret function, such as help(pyferret.run) will give the latest detailed

Ferret engine control

start(memsize=25.6, journal=True, verify=True, restrict=False, server=False, metaname=None, unmapped=False): configures the Ferret engine within PyFerret using function arguments. This routine does NOT run any user initialization scripts.
init(arglist=None, enterferret=True): configures the Ferret engine within PyFerret using an array of command-line argument strings given in arglist. If a user initialization script ($HOME/.ferret) exists, the Ferret commands in that script will be executed. The argument enterferret indicates whether to enter into the Ferret command-line processing mode.
run(command=None): executes the Ferret command, or enter into Ferret command mode if no command is given. Returns the pair of values ((err_int, err_msg) where err_int is one of the return value constants given below, and err_msg is an informative error or warning message string.
resize(memsize): changes the size of the memory block used by the Ferret engine
stop(): stops the Ferret engine and release any resources used by the Ferret engine

Data exchange between Ferret and Python

For working with Ferret variables and data in Python, see the FerVar and FerPyVar PyFerret Python objects. /pyferret/pyferret-python-objects These objects handle interacting with the getdata and putdata methods mentioned here and provide a simpler interface to the data and metadata.

get(name, create_mask=True): returns Ferret data as a cdms2.TransientVariable object. If create_mask is True, the mask attribute will be assigned.
getdata(name, create_mask=True): returns Ferret numeric data as a Python dictionary containing the variable's metadata and data array. If create_mask is True, the data array associated with the "data" key will be a MaskedArray NumPy array instead an ordinary NumPy array. See the section PyFerret metadata-and-data dictionaries for more details about the dictionary returned and examples of using this function.
getstrdata(name): returns Ferret string data as a Python dictionary containing the variable's metadata and data array. The data array associated with the "data" key will be a NumPy array of strings whose maximum length is one more that the longest string given. See the section PyFerret metadata-and-data dictionaries for more details about the dictionary returned.
metastr(datadict): returns a string describing the metadata contained in the Python dictionary of metadata and data. Usually you will want to print this string to the console (print pyferret.metastr(datadict)) See the section PyFerret metadata-and-data dictionaries for more details about the dictionary used and examples of using this function.
put(datavar, axis_pos=None): create a Python data variable in Ferret using the metadata and data in the provided the cdms2.TransientVariable object datavar. The order of the axes in Ferret can be explicitly specified in axis_pos; otherwise a reasonable guess for the order will be made from examining the axis types.
putdata(datavar_dict, axis_pos=None): create a Python data variable in Ferret using the metadata and data in the provided Python dictionary datavar_dict. The order of the axes in Ferret can be explicitly specified in axis_pos; otherwise a reasonable guess for the order will be made from examining the axis types. See the section PyFerret metadata-and-data dictionaries for more details about the dictionary used and examples of using this function.

Support for Ferret external functions written in Python (PyEFs)

The most up-to-date information for these functions can be obtained using Python help on the function; for example, help(pyferret.get_axis_info). The id argument in these functions is provided as an argument in the ferret_init, ferret_compute, ferret_custom_axes, and ferret_result_limits functions when they are called. The arg argument indicates which argument of the Ferret function you want to examine, and the axis argument indicates which a

get_axis_info(id, arg, axis): returns a Python dictionary of information about the specified argument axis
get_axis_coordinates(id, arg, axis): returns a one-dimensional floating-point NumPy array of "world" coordinates for the specified argument axis
get_axis_box_limits(id, arg, axis): returns a pair (box_low, box_high) of one-dimensional floating-point NumPy arrays giving the lower and upper grid-box limits, in "world" coordinates, for the specified argument axis
get_axis_box_sizes(id, arg, axis): returns a one-dimensional floating-point NumPy array giving the sizes of the gird boxes for the specified argument axis
ferret_pyfunc(): a dummy function that just returns its help message, documenting the requirements for a Python module to be used as a Ferret external function

Return-value constants from pyferret.run

The run function of the pyferret module returns a pair of values. The first value of the pair is an integer corresponding to one of the following contants. The second value of the pair is a string giving a informative error or warning message.

FERR_OK: the normal return value, returned when ferret did not encounter any errors. The message paired with this return value is normally empty, although it may contain an informative warning message that can be displayed to the user.
FERR_BAD_DELTA,FERR_CMND_TOO_COMPLEX,FERR_DATA_TYPE_ERROR,FERR_DEL_PERM_VAR,FERR_DESCRIPTOR_ERROR,FERR_DIM_UNDERSPEC,FERR_EF_ERROR,FERR_ERREQ,FERR_EXPR_TOO_COMPLEX,FERR_GRID_DEF_ERROR,FERR_INCONSIST_GRID,FERR_INCONSIST_PLANE,FERR_INSUFF_MEMORY,FERR_INTERNAL_ERROR,FERR_INTERRUPT,FERR_INVALID_COMMAND,FERR_INVALID_SUBCMND,FERR_LIMITS_ERROR,FERR_LINE_TOO_LONG,FERR_NOT_ATTRIBUTE,FERR_NOT_IMPLEMENTED,FERR_NO_COACH_MESSAGE,FERR_NO_RANGE,FERR_ODR_ERROR,FERR_OUT_OF_RANGE,FERR_PROG_LIMIT,FERR_REGRID_ERROR,FERR_RE: error return values, indicating the type of error that occurred. The message paired with these values will contain an informative error message that can be shown to the user.

Constants for Ferret external functions written in Python (PyEFs)

The following constants are useful in avoiding mistakes and producing more legible code when writing Ferret external functions in Python. See the section Ferret external functions in Python for examples using these values.

ARG1, ARG2, ARG3, ARG4, ARG5, ARG6, ARG7, ARG8, ARG9: indices for the arguments of a PyEF. These can be used in arrays of data and can be used as arguments when calling PyEF support functions.
X_AXIS, Y_AXIS, Z_AXIS, T_AXIS, E_AXIS, F_AXIS: indices for the axes of data arrays of a PyEF. These can be used in arrays of data and can be used as arguments when calling PyEF support functions.
AXIS_IMPLIED_BY_ARGS, AXIS_CUSTOM, AXIS_ABSTRACT, AXIS_DOES_NOT_EXIST, AXIS_REDUCED: result-axis types used in the dictionary returned by the ferret_init function of a PyEF. The "axes" key in the dictionary contains a tuple of these integer values.
FLOAT_ARG, FLOAT_ARRAY, FLOAT_ONEVAL, STRING_ARG, STRING_ARRAY, STRING_ONEVAL: argument and result types used in the dictionary returned by the ferret_init function of a PyEF. Used with the "argtypes" and "restype" keys in the dictionary.

Metadata and data dictionary constants

The following constants are useful when analyzing or assigning metadata, or even the data, in the metadata and data dictionaries used by the getdata and putdata functions in the pyferret module. See the section PyFerret metadata-and-data dictionaries for more information about using these constants in the dictionaries, as well as examples using some of these values.

X_AXIS, Y_AXIS, Z_AXIS, T_AXIS, E_AXIS, F_AXIS: indices for the axes of metadata and data arrays.
AXISTYPE_LONGITUDE, AXISTYPE_LATITUDE, AXISTYPE_LEVEL, AXISTYPE_TIME, AXISTYPE_CUSTOM, AXISTYPE_ABSTRACT, AXISTYPE_NORMAL: axis type values given in the metadata array associated with the "axis_types" key.
TIMEARRAY_YEARINDEX, TIMEARRAY_MONTHINDEX, TIMEARRAY_DAYINDEX, TIMEARRAY_HOURINDEX, TIMEARRAY_MINUTEINDEX, TIMEARRAY_SECONDINDEX: indices for the year, month, day, hour, minute, and second in a time axis coordinates array. Each time coordinate is an array of six values which can be accessed using these constants.

Previous Next