Ferret

Contents

Title Page

Chapter 1: INTRODUCTION

Ferret User's Group

Ferret Home Page

GETTING STARTED

Thinking like a Ferret:

Unix command line switches

Sample sessions

Accessing a netCDFdata set

Reading an ASCII data file

Using viewports

Using abstract variables

Using transformations

Using algebraic expressions

Finding the 20-degree isotherm

COMMON COMMANDS

Demonstration files

Writing GO tools

Documenting GO tools

Preserving the Ferret state in GO tools

Silent GO tools

Arguments to GO tools

Documentation and checking arguments to GO tools

Flow Control in GO tools

Debugging GO tools

SAMPLE DATA SETS

Examples and demonstrations

Help from within Ferret

Web-based information

Chapter 2: DATA SET BASICS

NetCDF data and strides

NetCDF data attributes

NetCDF Data with the bounds attribute

Multi-file NetCDF data sets

Non-standard NetCDF data sets

NetCDF and non-standard calendars

TMAP-FORMATTED DATA

FORTRAN-structured binary files

Records of uniform length

Records of non-uniform length

Fortran binary files, variables on different grids.

Stream binary files

Simple stream files

Mixed stream files

Byte-swapped stream files

Reading ASCII files

Reading "DELIMITED" data files

TRICKS TO READING BINARY AND ASCII FILES

ACCESS TO REMOTE DATA SETS WITH DODS

Accessing Remote Data Sets

Debugging Access to Remote DODS Data Sets

Sharing Data Sets via DODS

Chapter 3: VARIABLES AND EXPRESSIONS

Variable syntax

Pseudo-variables

Grids and axes of pseudo-variables

User-defined variables

Abstract variables

Missing value flags

Missing values in input files

Missing values in user-defined variables

Missingvalues in output NetCDF files

Displaying the missing value flag

Returning properties of variables

Variable and dataset attributes

SHOW ATTRIBUTE commands

Attribute keywords

Programmatic access to attributes

Editing attributes

Output attributes to NetCDF fies

Output Variables to NetCDF files

Multi-dimensional expressions

XSEQUENCE, YSEQUENCE, ZSEQUENCE, TSEQUENCE

SAMPLEXY_CLOSEST

SCAT2GRIDGAUSS_XY

SCAT2GRIDGAUSS_XZ

SCAT2GRIDGAUSS_YZ

SCAT2GRIDLAPLACE_XY

SCAT2GRIDLAPLACE_XZ

SCAT2GRIDLAPLACE_YZ

Transformations

General information about transformations

Transformations applied to irregular regions

General information about smoothing transformations

@DIN—definite integral

@IIN—indefinite integral

VAR—weighted variance

@SBX:n—boxcar smoother

@SBN:n—binomial smoother

@SHN:n—Hanning smoother

@SPZ:n—Parzen smoother

@SWL:n—Welch smoother

@DDC—centered derivative

@DDF—forward derivative

@DDB—backward derivative

@NGD—number of good points

@NBD—number of bad points

@SUM—unweighted sum

@RSUM—running unweighted sum

@FAV:n—averaging filler

@FLN:n—linear interpolation filler

@FNR—nearest neighbor filler

@LOC—location of

@WEQ—weighted equal; integration kernel

@ITP—interpolate

@CDA—closest distance above

@CDB—closest distance below

@CIA—closest index above

@CIB—closest index below

IF-THEN logic ("masking")

Lists of constants ("constant arrays")

EMBEDDED EXPRESSIONS

Special calculations using embedded expressions

DEFINING NEW VARIABLES

Global, local, and default variable definitions

DEBUGGING COMPLEX HIERARCHIES OF EXPRESSIONS

Chapter 4: GRIDS AND REGIONS

Time axes and calendars

Dynamic grids and axes

Dynamic pseudo-variables

Regridding transformations

Modulo regridding

Modulo regridding statistics

Subspan Modulo Axes

Region Conflicts

FERRET PROGRAM LIMITS

Chapter 5: ANIMATIONS AND GIF IMAGES

Animating on the fly

Note on using whirlgif to make a movie

CREATING AN HDF MOVIE

DISPLAYING AN HDF MOVIE

ADVANCED MOVIE-MAKING

Initializing the color table

Making movies in batch mode

CREATING GIF IMAGES

CREATING MPEG ANIMATIONS

Chapter 6: CUSTOMIZING PLOTS

GRAPHICAL OUTPUT

Ferret graphical output controls

PPLUS graphical output commands

Ferret axis formatting

PPLUS axis commands

Overlaying symbols on a time axis

Removing movable labels

Axis labels and title

Ferret label controls

PPLUS label commands

Positioning labels relative to other plot elements

Positioning labels using the mouse pointer

Labeling details with arrows and text

Text and line colors2

Ferret color controls for lines

PPLUS text and line color commands

Shade and fill colors

Ferret shade and fill color controls

PPLUS shade color commands

Ferret font and text color

PPLUS font and text color commands

Ferret layout controls

Pre-defined viewports

Advanced usage of viewports

Viewport Symbols

PPLUS layout commands

Controlling the white space around plots

Ferret contour controls

/LEVELS qualifier

/PEN, /SIZE, /SIGDIG, /SPACING qualifiers

PPLUS contour commands

SPECIAL SYMBOLS

MAP PROJECTIONS AND CURVILINEAR COORDINATES

Three-argument (curvilinear) version of SHADE, FILL, CONTOUR, and VECTOR

Gridded data sets on curvilinear coordinates

Layered (sigma) coordinates

Map Projections

Using Map Projection scripts

Overlays with Map Projections

Map Projection scripts

Chapter 7: HANDLING STRING DATA: STRING VARIABLES AND "SYMBOLS"

STRING VARIABLES

STRING FUNCTIONS

STRCMP(string1, string2)

STRLEN(string1)

UPCASE(string1)

DNCASE(string1)

STRINDEX(string1, substring)

STRRINDEX(string1, substring)

SUBSTRING(string1, offset, len)

STRCAT(string1, str2)

STRFLOAT(string1)

LABWID(string, charsize)

Algebraic operations with string variables.

Logical operators with strings

Shift transformation of string arrays

Strings in IF-THEN-ELSE

String concatenation with "+":

Strings as Function arguments

Regridding string arrays

NetCDF input and output of string data

SYMBOL COMMANDS

AUTOMATICALLY GENERATED SYMBOLS

USE WITH EMBEDDED EXPRESSIONS

ORDER OF STRING SUBSTITUTIONS

CUSTOMIZING THE POSITION AND STYLE OF PLOT LABELS

USING SYMBOLS IN COMMAND FILES

PLOT+ STRING EDITING TOOLS

SPECIAL SYMBOLS

Chapter 8: WORKING WITH SPECIAL DATA SETS

WHAT IS NON-GRIDDED DATA?

Getting point data into Ferret

How point data is structured in Ferret

Working with dates

Subsampling gridded fields onto point locations and times

Defining gridded variables from point data

Visualization techniques for point data

VERTICAL PROFILES

How collections of profiles are structured in Ferret

Getting profile data into Ferret

Defining vertical sections from profiles

Visualization and analysis techniques for profile sections

Subsampling gridded fields onto profile coordinates

COLLECTIONS OF TIME SERIES

COLLECTIONS OF 2-DIMENSIONAL GRIDS

LAGRANGIAN DATA

Visualization techniques for Lagrangian data

SIGMA COORDINATE DATA

Visualization techniques for sigma coordinate data

Analysis techniques for sigma coordinate data

CURVILINEAR COORDINATE DATA

Visualization techniques for curvilinear coordinate data

Analysis techniques for curvilinear coordinate data

Visualization techniques for polygonal data

Analysis techniques for polygonal data

Chapter 9: COMPUTING ENVIRONMENT

SETTING UP TO RUN FERRET

FILES AND ENVIRONMENT VARIABLES USED BY FERRET

HARD COPY AND METAFILE TRANSLATION

1Hard copy: postscript output

Metafile translation

Hard Copy: gif files

OUTPUT FILE NAMING

INPUT FILE NAMING

Relative version numbers

Chapter 10: CONVERTING TO NetCDF

SIMPLE CONVERSIONS USING FERRET

WRITING A CONVERSION PROGRAM

Creating a CDL file with Ferret

Standardized NetCDF attributes

Directing data to a CDF file

Advanced NetCDF procedures

Unevenly spaced coordinates

Evenly spaced coordinates (long axes)

Reversed-coordinate axes

Converting time word data to numerical data

Example CDL file

CREATING A MULTI-FILE NETCDF DATA SET

Tools for making descriptor files

Example descriptor file

Chapter 11: WRITING EXTERNAL FUNCTIONS

GETTING STARTED

Getting example/development code

QUICK START EXAMPLE

The times2bad20 function

ANATOMY OF AN EXTERNAL FUNCTION

The ~_init subroutine (required)

The ~_compute subroutine (required)

The ~_work_size subroutine (required when work arrays are defined)

The ~_result_limits subroutine (required if result has a custom or abstract axis)

The ~_custom_axes subroutine (required if result has a custom axis)

NOTES AND SUGGESTIONS

Inheriting axes

String Arguments

UTILITY FUNCTIONS

Available utility functions

ef_set_desc(id, desc)

ef_set_num_args(id, num)

ef_set_axis_inheritance(id, Xsrc, Ysrc, Zsrc, Tsrc)

ef_set_piecemeal_ok(id, Xyn, Yyn, Zyn, Tyn)

ef_set_arg_name(id, arg, name)

ef_set_arg_desc(id, arg, desc)

ef_set_arg_unit(id, arg, unit)

ef_set_arg_type(id, arg, type)

ef_set_axis_extend(id, arg, axis, lo_amt, hi_amt)

ef_set_axis_influence(id, arg, Xyn, Yyn, Zyn, Tyn)

ef_set_axis_reduction(id, Xred, Yred, Zred, Tred)

ef_set_axis_limits(id, axis, lo, hi)

ef_set_custom_axis(id, axis, lo, hi, delta, unit, modulo)

ef_set_num_work_arrays(id, nwork)

ef_set_work_array_dims(id, iarray, xlo, ylo, zlo, tlo, xhi, yhi, zhi, thi)

ef_get_res_subscripts(id, res_lo_ss, res_hi_ss, res_incr)

ef_get_arg_info(id, iarg, arg_name, arg_title, arg_units)

ef_get_arg_string(id, iarg, text)

ef_get_one_arg_string(id, iarg, text)

ef_get_axis_info(id, iarg, axname, ax_units, backward, modulo, regular)

ef_get_axis_dates(id, iarg, taxis, numtimes, datebuf)

ef_get_axis_calendar(id, iarg, calname, yrdays, nmonths, days_in_month)

ef_get_arg_subscripts(id, arg_lo_ss, arg_hi_ss, arg_incr)

ef_get_arg_ss_extremes(id, num_args, ss_min, ss_max)

ef_get_bad_flags(id, bad_flag, bad_flag_result)

ef_get_coordinates(id, arg, axis, lo, hi, coords)

ef_get_box_size(id, arg, axis, lo, hi, size)

ef_get_box_limits(id, arg, axis, lo, hi, lo_lims, hi_lims)

ef_get_one_val(id, arg, value)

ef_get_string_arg_element(id, arg, i,j,k,l, str_arg, slen, text)

ef_get_string_arg_element_len (id, arg, str_arg, i,j,k,l, slen)

ef_get_string_arg_max_len (id, arg, str_arg, slen)

ef_version_test (version)

ef_bail_out(id, text)

Part II: COMMANDS REFERENCE

CANCEL ATTRIBUTE

CANCEL VIEWPORT

DEFINE ATTRIBUTE

DEFINE VARIABLE

DEFINE VIEWPORT

IF-THEN-ELSE conditional execution

IF-THEN-ELSE logic for masking

SET MODE ASCII_FONT

SET MODE CALENDAR

SET MODE DEPTH_LABEL

SET MODE DESPERATE

SET MODE DIAGNOSTIC

SET MODE GRATICULE

SET MODE IGNORE_ERROR

SET MODE INTERPOLATE

SET MODE LABELS

SET MODE JOURNAL

SET MODE LATIT_LABEL

SET MODE LONG_LABEL

SET MODE METAFILE

SET MODE PPLLIST

SET MODE REFRESH

SET MODE SEGMENTS

SET MODE STUPID

SET MODE UPCASE_OUTPUT

SET MODE VERIFY

SET VARIABLE/BAD=

SET VARIABLE/GRID=

SET VARIABLE/TITLE=

SET VARIABLE/OFFSET=

SET VARIABLE/SCALE=

SHOW EXPRESSION

Objective analysis

Scattered sampling

Appendix A: EXTERNAL FUNCTIONS

CURV_TO_RECT_MAP

DAYS1900TOYMDHMS

ELEMENT_INDEX_STRING

IS_ELEMENT_OF_STR

Appendix B: PPLUS Users Guide

GETTING STARTED

Required Definitions

Optional Definitions

COMMAND SYNOPSIS

Other Data Entry

PPLUS Output Files

PPLUS Command Files

COMMAND PROCEDURES

COLOR AND FONTS

PLOT APPEARANCE

PLOT GENERATION

DATA MANIPULATION

BEGINNERS GUIDE

PLOT AND CONTOUR

Unformatted Data, X-Y Plot

Pre-gridded Data, Contour Plot

Ungridded Data, Contour Plot

Time Series Plot

ROUTING PLOT FILES

Plot Files And Mom

Plotting Devices

PPLUS COMMAND FILES

SYMBOL SUBSTITUTION

GENERAL GLOBAL SYMBOLS

EPIC GLOBAL SYMBOLS

COMMAND FILE LOGIC

SPECIAL FUNCTIONS

EMBEDDED STRING COMMANDS

Character Slant

Subscripting, Superscripting And Back Spacing

SEQUENTIAL FORMATS

ADVANCED COMMANDS

%OPNPLT/qualifier

%CLSPLT/qualifiers

%LABEL/qualifier,x,y,ipos,ang,chsiz,label

%RANGE,min,max,ntic

%XAXIS/qualifier,xlow,xhigh,xtic,y[,nmstc][,lint][,xunit][,ipos][,csize][,frmt]

%YAXIS/qualifier,ylow,yhigh,ytic,x[,nmstc][,lint] [,yunit][,ipos][,csize][,frmt]

PLOT5, PPLUS DIFFERENCES

COMMAND DESCRIPTION

@file_name/qualifier arg1 arg2 arg3 ...

AXATIC,ATICX,ATICY

AXLABP,LABX,LABY

AXLEN,XLEN,YLEN

AXLINT,LINTX,LINTY

AXLSZE,HGTX,HGTY

AXNMTC,NMTCX,NMTCY

AXNSIG,NSIGX,NSIGY

AXSET,TOP,BOT,LEFT,RIGHT

AXTYPE,TYPEX,TYPEY

CONSET,HGT,NSIG,NARC,DASHLN,SPACLN,CAY,NRNG,DSLAB

DATPT,type,mark

EVAR/qualifier,x-var,y-var

F expression THEN

LABS/qualifier,n,X,Y,JST,label

LABSET,HLAB1,HXLAB,HYLAB,HLABS

LEV,arg,arg,arg ...

LIMITS,value,comparison,flag

LINE,n,MARK,TYPE,XOFF,YOFF,DN1,UP1,DN2,UP2

LINFIT,n,XIMIN,XIMAX,XOMIN,XOMAX

LIST,IMIN,IMAX,JMIN,JMAX,VCOMP,arg

LLABS,n,X,Y,TYPE

ORIGIN,XORG,YORG

PLOT/qualifiers,label

PLOTV/qualifiers,VANG,INC,label

PLOTUV/qualifiers,VANG,INC,label

RD/qualifier,NX,NY,TYPE,n,file_name

SIZE,width,height

SKP,n,file_name

TAXIS/qualifier,DT,arg

TICS,SMX,LGX,SMY,LGY,IX,IY

TIME,TMIN,TMAX,TSTART

TITLE,HLAB,label

TRANSXY,n,XFACT,XOFF,YFACT,YOFF

TXLINT,low_int,hi_int

TXTYPE,type,style

VARS,NGRP,A1,A2,A3,...,Ai

VECKEY/qualifier,x,y,ipos,format

VECSET,length,scale

VECTOR/qual,skipx,skipy,label

VELVCT,rlenfact,inc

VIEW/qualifiers,ZSCALE,IC,ZMIN,ZMAX,VCOMP,label

WHILE expression THEN

XAXIS,XLO,XHI,XTIC

YAXIS,YLO,YHI,YTIC

Appendix C: PLOTPLUS PLUS: Ferret Enhancements to PLOTPLUS

PLOTPLUS HISTORY, EVOLUTION

ENHANCED COMMANDS DESCRIPTION

ALINE/qualifier line#, minx, miny, maxx, maxy, set

COLOR n, red, green, blue

CONSET hgt, nsig, narc, dashln, spacln, cay, nrng, dslab, spline_tension, draftsman

LINE n, mark, use

PLTNME metafile_name

PLTYPE icode META

SHADE/qualifier

SHAKEY do_key, orient, klab_siz, klab_inc, klab_dig, klab_len, kx_lo, kx_hi, ky_lo, ky_hi

GKS LINE BUNDLES