[Thread Prev][Thread Next][Index]
Re: [ferret_users] shuffle or how to permute randomly elements
Hi Patrick,
I do have PyFerret in an alpha version. Attached is the help message
for the pyferret python module. A script is provided that will start it
and give the ferret command prompt, thus providing the regular ferret
interface for users that have no use for the python extensions.
The "run" method allows you to run ferret commands individually or enter
into the ferret command loop. The ferret command "exit /topy" will take
you back to the python prompt. You can use python scripts as external
functions. If you have CDAT's cdms2 and cdtime modules available in the
version of python being used, you can retrieve ("get" method)
floating-point data arrays from ferret as cdms2 TransientVariable
objects complete with axes. The "put" method is still under development.
There are some known issues that I am working on. I am interested in
knowing your opinion of the seriousness of this first problem:
(1) User-defined Fortran external functions do not work properly because
the EF_MEM_SUBSC common block is no longer visible. (Ferret
functionality is now in a shared-object library separate from the
external function shared-object library.) A Fortran function is
provided to retrieve the data in these common blocks, but this would
mean some code rewriting.
(2) PyFerret messes up command history in Python
(3) Finish "put" method
(4) Enable "get" and "put" methods when cdms2 and cdtime packages are
not available (just return masked arrays?)
Let me know if you want to evaluate this early version. I can provide a
RHEL5 32-bit or 64-bit version for Python 2.4 or 2.6.
Karl
Patrick.Brockmann@xxxxxx wrote:
I am wondering if a shuffle function could be added to ferret ?
Any news to share about link between python and ferret ?
Patrick
--
Karl M. Smith, Ph.D.
Research Scientist and Software Developer
UW/JISAO and NOAA/PMEL/TMAP
karl.smith@xxxxxxxx
(206) 526-4806
"The contents of this message are mine personally and do
not necessarily reflect any position of the Government
or the National Oceanic and Atmospheric Administration."
NAME
pyferret - A Python module for running Ferret.
FILE
..../python2.6/site-packages/pyferret/__init__.py
DESCRIPTION
A Python extension module that interfaces with Ferret functionality.
In order to use this module:
start must first be called to allocate the required memory and
initialize Ferret
resize can be used to resize Ferret's allocated memory block
run is used to submit individual Ferret commands or enter into
Ferret's command prompting mode
get is used to retrieve (a copy of) Ferret numeric data arrays
as NumPy ndarrays
stop can be used to shutdown Ferret and free the allocated memory.
The FERR_* values are the possible values of err_int in the return
values from the run command. The err_int return value FERR_OK
indicates no errors.
PACKAGE CONTENTS
_pyferret
FUNCTIONS
ferret_pyfunc()
A dummy function (which just returns this help message) used to document the
requirements of python modules used as ferret external functions (using the
ferret command: DEFINE PYFUNC [/NAME=<alias>] <module.name>). Two methods,
ferret_init and ferret_compute, must be provided by such a module:
ferret_init(id)
Arguments:
id - ferret's integer ID of this external function
Returns a dictionary defining the following keys:
"numargs": number of input arguments [1 - 9; required]
"descript": string description of the function [required]
"axes": 4-tuple (X,Y,Z,T) of result grid axis defining values,
which are:
AXIS_ABSTRACT: indexed, ferret_result_limits
called to define the axis,
AXIS_CUSTOM: ferret_custom_axes called to
define the axis,
AXIS_DOES_NOT_EXIST: does not exist in (normal to)
the results grid,
AXIS_IMPLIED_BY_ARGS: same as the corresponding axis
in one or more arguments,
AXIS_REDUCED: reduced to a single point
[optional; default: AXIS_IMPLIED_BY_ARGS for each axis]
"argnames": N-tuple of names for the input arguments
[optional; default: (A, B, ...)]
"argdescripts": N-tuple of descriptions for the input arguments
[optional; default: no descriptions]
"influences": N-tuple of 4-tuples of booleans indicating whether the
corresponding input argument's (X,Y,Z,T) axis influences
the result grid's (X,Y,Z,T) axis. [optional; default,
and when None is given for a 4-tuple: True for every axis]
NOTE: If the "influences" value for an axis is True (which is the
default), the "axes" value for this axis must be either
AXIS_IMPLIED_BY_ARGS (the default) or AXIS_REDUCED.
"extends": N-tuple of 4-tuples of pairs of integers. The n-th tuple,
if not None, gives the (X,Y,Z,T) extension pairs for the
n-th argument. An extension pair, if not None, is the
number of points extended in the (low,high) indices for
that axis of that argument beyond the implied axis of the
result grid. Thus,
(None, (None, None, None, (-1,1)), None)
means the T axis of the second argument is extended by two
points (low dimension lowered by 1, high dimension raised
by 1) beyond the implied axis of the result.
[optional; default: no extensions assigned]
NOTE: If an "extends" pair is given for an axis, the "axes"
value for this axis must be either AXIS_IMPLIED_BY_ARGS
(the default). The "extends" pair more precisely means
the axis in the argument, exactly as provided in the
ferret command, is larger by the indicated amount from
the implied result grid axis.
If an exception is raised, Ferret is notified that an error occurred using
the message of the exception.
ferret_compute(id, result_array, result_bdf, input_arrays, input_bdfs)
Arguments:
id - ferret's integer ID of this external function
result_array - a writeable NumPy float32 ndarray of four dimensions (X,Y,Z,T)
to contain the results of this computation. The shape and
strides of this array has been configured so that only (and
all) the data points that should be assigned are accessible.
result_bdf - a NumPy ndarray of one dimension containing the bad-data-flag
value for the result array.
input_arrays - tuple of read-only NumPy float32 ndarrays of four dimensions
(X,Y,Z,T) containing the given input data. The shape and
strides of these array have been configured so that only (and
all) the data points that should be accessible are accessible.
input_bdfs - a NumPy ndarray of one dimension containing
the bad-data-flag values for each of the input arrays.
Any return value is ignored.
If an exception is raised, Ferret is notified that an error occurred using
the message of the exception.
If the dictionary returned from ferret_init assigned a result axis as AXIS_ABSTRACT,
then the ferret_result_limits method must also be defined:
ferret_result_limits(id)
Arguments:
id - ferret's integer ID of this external function
Returns a (X,Y,Z,T) 4-tuple of either None or (low, high) pairs of integers.
If an axis was not designated as AXIS_ABSTRACT, None should be given for that axis.
If an axis was designated as AXIS_ABSTRACT, a (low, high) pair of integers should
be given, and are used as the low and high Ferret indices for that axis.
[The indices of the NumPy ndarray to be assigned will be from 0 until (high-low)].
If an exception is raised, Ferret is notified that an error occurred using
the message of the exception.
If the dictionary returned from ferret_init assigned a result axis as AXIS_CUSTOM,
then the ferret_custom_axes method must also be defined:
ferret_custom_axes(id)
Arguments:
id - ferret's integer ID of this external function
Returns a (X,Y,Z,T) 4-tuple of either None or a (low, high, delta, unit_name,
is_modulo) tuple. If an axis was not designated as AXIS_CUSTOM, None should be
given for that axis. If an axis was designated as AXIS_CUSTOM, a (low, high,
delta, unit_name, is_modulo) tuple should be given where low and high are the
"world" coordinates (floating point) limits for the axis, delta is the step
increments in "world" coordinates, unit_name is a string used in describing the
"world" coordinates, and is_modulo is either True or False, indicating if this
is a modulo ("wrapping") coordinate system.
If an exception is raised, Ferret is notified that an error occurred using
the message of the exception.
get(name, create_mask=True)
Returns the numeric data array described in name.
Arguments:
name: the name of the numeric data array to retrieve
Returns:
A cdms2 TransientVariable object (cdms2.tvariable) containing the
numeric data. The data, axes, and missing value will be assigned.
If create_mask is True (or not given), the mask attribute will be
assigned using the missing value.
Raises:
ValueError if the data name is invalid
MemoryError if Ferret has not been started or has been stopped
get_axis_box_limits(id, arg, axis)
Returns the "box limits", in "world" coordinate units,
for an axis of an argument to an external function
Arguments:
id: the ferret id of the external function
arg: the index (zero based) of the argument (can use ARG1, ARG2, ..., ARG9)
axis: the index (zero based) of the axis (can use X_AXIS, Y_AXIS, Z_AXIS, T_AXIS)
Returns:
a tuple of two NumPy float64 ndarrays containing the low and high "box limits",
or None if the values cannot be determined at the time this was called
Raises:
ValueError if id, arg, or axis is invalid
get_axis_box_sizes(id, arg, axis)
Returns the "box sizes", in "world" coordinate units,
for an axis of an argument to an external function
Arguments:
id: the ferret id of the external function
arg: the index (zero based) of the argument (can use ARG1, ARG2, ..., ARG9)
axis: the index (zero based) of the axis (can use X_AXIS, Y_AXIS, Z_AXIS, T_AXIS)
Returns:
a NumPy float32 ndarray containing the "box sizes",
or None if the values cannot be determined at the time this was called
Raises:
ValueError if id, arg, or axis is invalid
get_axis_coordinates(id, arg, axis)
Returns the "world" coordinates for an axis of an argument to an external function
Arguments:
id: the ferret id of the external function
arg: the index (zero based) of the argument (can use ARG1, ARG2, ..., ARG9)
axis: the index (zero based) of the axis (can use X_AXIS, Y_AXIS, Z_AXIS, T_AXIS)
Returns:
a NumPy float64 ndarray containing the "world" coordinates,
or None if the values cannot be determined at the time this was called
Raises:
ValueError if id, arg, or axis is invalid
get_axis_info(id, arg, axis)
Returns information about the axis of an argument to an external function
Arguments:
id: the ferret id of the external function
arg: the index (zero based) of the argument (can use ARG1, ARG2, ..., ARG9)
axis: the index (zero based) of the axis (can use X_AXIS, Y_AXIS, Z_AXIS, T_AXIS)
Returns:
a dictionary defining the following keys:
"name": name string for the axis coordinate
"unit": name string for the axis unit
"backwards": boolean - reversed axis?
"modulo": boolean - periodic/wrapping axis?
"regular": boolean - evenly spaced axis?
"size": number of coordinates on this axis, or -1 if the value
cannot be determined at the time this was called
Raises:
ValueError if id, arg, or axis is invalid
put(datavar, axis_pos=None, dset='', name=None, title=None)
Creates a Ferret data variable with a copy of the data given in datavar.
Arguments:
datavar: a cdms2 AbstractVariable describing the data variable
to be created in Ferret. Any masked values in the data
of datavar will be set to the missing value for datavar
before extracting the data as 32-bit floating-point
values for Ferret.
axis_pos: a four-tuple given the Ferret positions for each axis in
datavar. If the axes in datavar are in (time, level, lat.,
long.) order, the tuple (T_AXIS, Z_AXIS, Y_AXIS, X_AXIS)
should be used for proper axis handling in Ferret. If not
given (or None), the first longitude axis will be made the
X_AXIS, the first latitude axis will be made the Y_AXIS,
the first level axis will be made the Z_AXIS, the first
time axis will be made the T_AXIS, and any remaining axes
are then filled into the remaining unassigned positions.
dset: the dataset name or number to be associated with this new
variable. If blank or not given, the current dataset is
used. If None or 'None', no dataset will be associated
with the new variable.
name: the code name for the variable in Ferret (eg, 'SST').
If not given (or None), the value of datavar.id will be
used. The code name must be a non-empty string and
(ideally) should not contain whitespace characters.
title: the title name for the variable in Ferret (eg, 'Sea
Surface Temperature'). If not given (or None), the
value of datavar.name, if present, or the value of
datavar.id is used.
Returns:
None
Raises:
AttributeError: if datavar does not have the needed methods or
attributes of an AbstractVariable
MemoryError: if Ferret has not been started or has been stopped
ValueError: if there is a problem with the contents of the arguments
resize(memsize)
Resets the the amount of memory allocated for Ferret from Python-managed memory.
Arguments:
memsize: the new size, in megawords (where a "word" is 32 bits),
for Ferret's memory block
Returns:
True if successful - Ferret has the new amount of memory
False if unsuccessful - Ferret has the previous amount of memory
Raises:
ValueError if memsize if not a positive number
MemoryError if Ferret has not been started or has been stopped
run(command=None)
Runs a Ferret command just as if entering a command at the Ferret prompt.
If the command is not given, is None, or is a blank string, Ferret will
prompt you for commands until "EXIT /TOPYTHON" is given. In this case,
the return tuple will be for the last error, if any, that occurred in
the sequence of commands given to Ferret.
Arguments:
command: the Ferret command to be executed.
Returns:
(err_int, err_string)
err_int: one of the FERR_* data values (FERR_OK if there are no errors)
err_string: error or warning message (can be empty)
Error messages normally start with "**ERROR"
Warning messages normally start with "*** NOTE:"
Raises:
ValueError if command is neither None nor a String
MemoryError if Ferret has not been started or has been stopped
start(memsize=25.600000000000001, journal=True, verify=True)
Initializes Ferret. This allocates the initial amount of memory for Ferret
(from Python-managed memory), opens the journal file, if requested, and sets
Ferret's verify mode. This does NOT run any user initialization scripts.
Arguments:
memsize: the size, in megawords (where a "word" is 32 bits),
to allocate for Ferret's memory block
journal: turn on Ferret's journal mode?
verify: turn on Ferret's verify mode?
Returns:
True is successful
False if Ferret has already been started
Raises:
ValueError if memsize if not a positive number
MemoryError if unable to allocate the needed memory
IOError if unable to open the journal file
stop()
Shuts down and release all memory used by Ferret.
After calling this function do not call any Ferret functions except start,
which will restart Ferret and re-enable the other functions.
Returns:
False if Ferret has not been started or has already been stopped
True otherwise
DATA
ARG1 = 0
ARG2 = 1
ARG3 = 2
ARG4 = 3
ARG5 = 4
ARG6 = 5
ARG7 = 6
ARG8 = 7
ARG9 = 8
AXIS_ABSTRACT = 104
AXIS_CUSTOM = 101
AXIS_DOES_NOT_EXIST = 103
AXIS_IMPLIED_BY_ARGS = 102
AXIS_REDUCED = 202
FERR_BAD_DELTA = 433
FERR_CMND_TOO_COMPLEX = 409
FERR_DATA_TYPE_ERROR = 438
FERR_DEL_PERM_VAR = 403
FERR_DESCRIPTOR_ERROR = 432
FERR_DIM_UNDERSPEC = 416
FERR_EF_ERROR = 437
FERR_ERREQ = 4
FERR_EXPR_TOO_COMPLEX = 422
FERR_GRID_DEF_ERROR = 417
FERR_INCONSIST_GRID = 421
FERR_INCONSIST_PLANE = 420
FERR_INSUFF_MEMORY = 401
FERR_INTERNAL_ERROR = 418
FERR_INTERRUPT = 5
FERR_INVALID_COMMAND = 407
FERR_INVALID_SUBCMND = 413
FERR_LIMITS_ERROR = 431
FERR_LINE_TOO_LONG = 419
FERR_NOT_ATTRIBUTE = 441
FERR_NOT_IMPLEMENTED = 412
FERR_NO_COACH_MESSAGE = 439
FERR_NO_RANGE = 428
FERR_ODR_ERROR = 202
FERR_OK = 3
FERR_OUT_OF_RANGE = 425
FERR_PROG_LIMIT = 426
FERR_REGRID_ERROR = 408
FERR_RELATIVE_COORD_ERROR = 414
FERR_SILENT_ERROR = 203
FERR_STACK_OVERFLOW = 423
FERR_STACK_UNDERFLOW = 424
FERR_STATE_NOT_SET = 435
FERR_SYNTAX_ERROR = 404
FERR_TMAP_ERROR = 201
FERR_TOO_MANY_ARGS = 411
FERR_TOO_MANY_VARS = 402
FERR_TRANSFORM_ERROR = 434
FERR_UNKNOWN_ARG = 415
FERR_UNKNOWN_ATTRIBUTE = 440
FERR_UNKNOWN_COMMAND = 436
FERR_UNKNOWN_DATA_SET = 410
FERR_UNKNOWN_FILE_TYPE = 430
FERR_UNKNOWN_GRID = 427
FERR_UNKNOWN_QUALIFIER = 405
FERR_UNKNOWN_VARIABLE = 406
FERR_VAR_NOT_IN_SET = 429
T_AXIS = 3
X_AXIS = 0
Y_AXIS = 1
Z_AXIS = 2
[Thread Prev][Thread Next][Index]
Contact Us
Dept of Commerce /
NOAA /
OAR /
PMEL /
Ferret
Privacy Policy | Disclaimer | Accessibility Statement