Contents Chapter 1: INTRODUCTION 1. OVERVIEW 1. Ferret User's Group 2. Ferret Home Page 2. GETTING STARTED 1. Concepts 1. Thinking like a Ferret: 2. Unix command line switches 3. Sample sessions 1. Accessing a NetCDF data set 2. Reading an ASCII data file 3. Using viewports 4. Using abstract variables 5. Using transformations 6. Using algebraic expressions 7. Finding the 20-degree isotherm 3. COMMON COMMANDS 4. COMMAND SYNTAX 5. GO FILES 1. Demonstration files 2. GO tools 3. Writing GO tools 1. Documenting GO tools 2. Preserving the Ferret state in GO tools 3. Silent GO tools 4. Arguments to GO tools 5. Flow Control in GO tools 6. Debugging GO tools 6. SAMPLE DATA SETS 7. UNIX TOOLS 8. HELP 1. Unix on-line help 2. Examples and demonstrations 3. Help from within Ferret 4. Web-based information Chapter 2: DATA SET BASICS 1. OVERVIEW 2. NETCDF DATA 1. Multi-file NetCDF data sets 2. Non-standard NetCDF data sets 3. NetCDF and non-standard calendars 3. TMAP-FORMATTED DATA 4. BINARY DATA 1. FORTRAN-structured binary files 1. Records of uniform length 2. Records of non-uniform length 3. Fortran binary files, variables on different grids. 2. Stream binary files 1. Simple stream files 2. Mixed stream files 3. Byte-swapped stream files 5. ASCII DATA 1. Reading ASCII files 6. TRICKS TO READING BINARY AND ASCII FILES 7. ACCESS TO REMOTE DATA SETS WITH DODS Chapter 3: VARIABLES AND EXPRESSIONS 1. VARIABLES 1. Variable syntax 2. File variables 3. Pseudo-variables 1. Grids and axes of pseudo-variables 4. User-defined variables 5. Abstract variables 6. Missing value flags 1. Missing values in input files 2. Missing values in user-defined variables 3. Missing values in output NetCDF files 4. Displaying the missing value flag 2. EXPRESSIONS 1. Operators 2. Multi-dimensional expressions 3. Functions 1. MAX 2. MIN 3. INT 4. ABS 5. EXP 6. LN 7. LOG 8. SIN 9. COS 10. TAN 11. ASIN 12. ACOS 13. ATAN 14. ATAN2 15. MOD 16. DAYS1900 17. MISSING 18. IGNORE0 19. RANDU 20. RANDN 21. RHO_UN 22. THETA_FO 23. RESHAPE 24. ZAXREPLACE 25. XSEQUENCE, YSEQUENCE, ZSEQUENCE, TSEQUENCE 26. FFTA 27. FFTP 28. SAMPLEI 29. SAMPLEJ 30. SAMPLEK 31. SAMPLEL 32. SAMPLEIJ 33. SAMPLET_DATE 34. SAMPLEXY 35. SCAT2GRIDGAUSS_XY 36. SCAT2GRIDGAUSS_XZ 37. SCAT2GRIDGAUSS_XY 38. SCAT2GRIDLAPLACE_XY 39. SCAT2GRIDLAPLACE_XZ 40. SCAT2GRIDLAPLACE_YZ 41. SORTI 42. SORTJ 43. SORTK 44. SORTL 45. TAUTO_COR 4. Transformations 1. General information about transformations 2. Transformations applied to irregular regions 3. General information about smoothing transformations 4. @DIN-definite integral 5. @IIN-indefinite integral 6. @AVE-average 7. VAR-weighted variance 8. MIN-minimum 9. @MAX-maximum 10. @SHF:n-shift 11. @SBX:n-boxcar smoother 12. @SBN:n-binomial smoother 13. @SHN:n-Hanning smoother 14. @SPZ:n-Parzen smoother 15. @SWL:n-Welch smoother 16. @DDC-centered derivative 17. @DDF-forward derivative 18. @DDB-backward derivative 19. @NGD-number of good points 20. @NBD-number of bad points 21. @SUM-unweighted sum 22. @RSUM-running unweighted sum 23. @FAV:n-averaging filler 24. @FLN:n-linear interpolation filler 25. @FNR:n-nearest neighbor filler 26. @LOC-location of 27. @WEQ-weighted equal; integration kernel 28. @ITP-interpolate 29. @CDA-closest distance above 30. @CDB-closest distance below 31. @CIA-closest index above 32. @CIB-closest index below 5. IF-THEN logic ("masking") 6. Lists of constants ("constant arrays") 3. EMBEDDED EXPRESSIONS 1. Special calculations using embedded expressions 4. DEFINING NEW VARIABLES 1. Global, local, and default variable definitions 5. DEBUGGING COMPLEX HIERARCHIES OF EXPRESSIONS Chapter 4: GRIDS AND REGIONS 1. OVERVIEW 2. GRIDS 1. Defining grids 2. Time axes and calendars 3. Dynamic grids and axes 1. Dynamic grids 2. Dynamic axes 3. Dynamic pseudo-variables 4. Regridding 1. Regridding transformations 5. Modulo regridding 1. Modulo regridding statistics 3. REGIONS 1. Latitude 2. Longitude 3. Depth 4. Time 5. Delta 6. Modulo axes 7. Region Conflicts Chapter 5: ANIMATIONS AND GIF IMAGES 1. OVERVIEW 1. Animating on the fly 2. Note on using whirlgif to make a movie 2. CREATING AN HDF MOVIE 3. DISPLAYING AN HDF MOVIE 4. ADVANCED MOVIE-MAKING 1. REPEAT command 1. Initializing the color table 2. Making movies in batch mode 5. CREATING GIF IMAGES 6. CREATING MPEG ANIMATIONS Chapter 6: CUSTOMIZING PLOTS 1. OVERVIEW 2. GRAPHICAL OUTPUT 1. Ferret graphical output controls 2. PPLUS graphical output commands 3. AXES 1. Ferret axis controls 2. PPLUS axis commands 3. Overlaying symbols on a time axis 4. LABELS 1. Adding labels 2. Listing labels 3. Removing movable labels 4. Axis labels and title 5. Ferret label controls 6. PPLUS label commands 7. Positioning labels using the mouse pointer 8. Labeling details with arrows and text 5. COLOR 1. Text and line colors2 1. Ferret color controls for lines 2. PPLUS text and line color commands 2. Shade and fill colors 1. Ferret shade and fill color controls 2. PPLUS shade color commands 6. FONTS 1. Ferret font controls 2. PPLUS font commands 7. PLOT LAYOUT 1. Ferret layout controls 1. Viewports 2. Pre-defined viewports 3. Advanced usage of viewports 2. PPLUS layout commands 3. Controlling the white space around plots 8. CONTOURING 1. Ferret contour controls 1. /LEVELS qualifier 2. PPLUS contour commands 9. PPLUS SPECIAL SYMBOLS 10. MAP PROJECTIONS AND CURVILINEAR COORDINATES 1. Three-argument (curvilinear) version of SHADE, FILL, CONTOUR, and VECTOR 2. Gridded data sets on curvilinear coordinates 3. Layered (sigma) coordinates 4. Map Projections 1. Using Map Projection scripts 2. Overlays with Map Projections 3. Map Projection scripts Chapter 7: HANDLING STRING DATA: STRING VARIABLES AND "SYMBOLS" 1. STRING VARIABLES 1. String arrays 2. STRING FUNCTIONS 1. STRCMP(string1, string2) 2. SPAWN command 3. Algebraic operations with string variables. 1. Logical operators with strings 2. Shift transformation of string arrays 3. Strings in IF-THEN-ELSE 4. String concatenation with "+": 5. Strings as Function arguments 6. Regridding string arrays 7. NetCDF input and output of string data 3. SYMBOL COMMANDS 4. AUTOMATICALLY GENERATED SYMBOLS 5. USE WITH EMBEDDED EXPRESSIONS 6. ORDER OF STRING SUBSTITUTIONS 7. CUSTOMIZING THE POSITION AND STYLE OF PLOT LABELS 8. USING SYMBOLS IN COMMAND FILES 9. PLOT+ STRING EDITING TOOLS 10. SYMBOL EDITING 11. SPECIAL SYMBOLS Chapter 8: WORKING WITH SPECIAL DATA SETS 1. WHAT IS NON-GRIDDED DATA? 2. POINT DATA 1. Getting point data into Ferret 2. How point data is structured in Ferret 1. Working with dates 3. Subsampling gridded fields onto point locations and times 4. Defining gridded variables from point data 5. Visualization techniques for point data 3. VERTICAL PROFILES 1. How collections of profiles are structured in Ferret 2. Getting profile data into Ferret 3. Defining vertical sections from profiles 4. Visualization and analysis techniques for profile sections 5. Subsampling gridded fields onto profile coordinates 4. COLLECTIONS OF TIME SERIES 5. COLLECTIONS OF 2-DIMENSIONAL GRIDS 6. LAGRANGIAN DATA 1. Visualization techniques for Lagrangian data 7. SIGMA COORDINATE DATA 1. Visualization techniques for sigma coordinate data 2. Analysis techniques for sigma coordinate data 8. CURVILINEAR COORDINATE DATA 1. Visualization techniques for curvilinear coordinate data 2. Analysis techniques for curvilinear coordinate data 9. POLYGONAL DATA 1. Visualization techniques for polygonal data 2. Analysis techniques for polygonal data Chapter 9: COMPUTING ENVIRONMENT 1. SETTING UP AN ACCOUNT 2. FILES AND ENVIRONMENT VARIABLES USED BY FERRET 3. MEMORY USE 4. HARD COPY AND METAFILE TRANSLATION 1. Hard copy 2. Metafile translation 5. OUTPUT FILE NAMING 6. INPUT FILE NAMING 1. Relative version numbers Chapter 10: CONVERTING TO NetCDF 1. OVERVIEW 2. SIMPLE CONVERSIONS USING FERRET 3. WRITING A CONVERSION PROGRAM 1. Creating a CDL file with Ferret 2. The CDL file 1. Dimensions 2. Variables 3. Data 3. Standardized NetCDF attributes 4. Directing data to a CDF file 5. Advanced NetCDF procedures 1. Staggered grid 2. Hyperslabs 3. Unevenly spaced coordinates 4. Evenly spaced coordinates (long axes) 5. "Modulo" axes 6. Reversed-coordinate axes 7. Converting time word data to numerical data 6. Example CDL file 4. CREATING A MULTI-FILE NETCDF DATA SET *Chapter 11: WRITING EXTERNAL FUNCTIONS 1. OVERVIEW 2. GETTING STARTED 1. Getting example/development code 3. QUICK START EXAMPLE 1. The times2bad20 function 4. ANATOMY OF AN EXTERNAL FUNCTION 1. The ~_init subroutine (required) 2. The ~_compute subroutine (required) 3. The ~_work_size subroutine (required when work arrays are defined) 4. The ~_result_limits subroutine (required if result has a custom or abstract axis) 5. The ~_custom_axes subroutine (required if result has a custom axis) 5. NOTES AND SUGGESTIONS 1. Inheriting axes 2. Loop indices 3. Reduced axes 4. String Arguments 6. UTILITY FUNCTIONS 1. EF_Util.cmn 2. Available utility functions 1. ef_set_desc(id, desc) 2. ef_set_num_args(id, num) 3. ef_set_axis_inheritance(id, Xsrc, Ysrc, Zsrc, Tsrc) 4. ef_set_piecemeal_ok(id, Xyn, Yyn, Zyn, Tyn) 5. ef_set_arg_name(id, arg, name) 6. ef_set_arg_desc(id, arg, desc) 7. ef_set_arg_unit(id, arg, unit) 8. ef_set_arg_type(id, arg, type) 9. ef_set_axis_extend(id, arg, axis, lo_amt, hi_amt) 10. ef_set_axis_influence(id, arg, Xyn, Yyn, Zyn, Tyn) 11. ef_set_axis_reduction(id, Xred, Yred, Zred, Tred) 12. ef_set_axis_limits(id, axis, lo, hi) 13. ef_set_custom_axis(id, axis, lo, hi, delta, unit, modulo) 14. ef_set_num_work_arrays(id, nwork) 15. ef_set_work_array_dims(id, iarray, xlo, ylo, zlo, tlo, xhi, yhi, zhi, thi) 16. ef_get_res_subscripts(id, res_lo_ss, res_hi_ss, res_incr) 17. ef_get_arg_info(id, iarg, arg_name, arg_title, arg_units) 18. ef_get_arg_string(id, iarg, text) 19. ef_get_axis_info(id, iarg, axname, ax_units, backward, modulo, regular) 20. ef_get_axis_dates(id, iarg, taxis, numtimes, datebuf) 21. ef_get_arg_subscripts(id, arg_lo_ss, arg_hi_ss, arg_incr) 22. ef_get_arg_ss_extremes(id, num_args, ss_min, ss_max) 23. ef_get_bad_flags(id, bad_flag, bad_flag_result) 24. ef_get_coordinates(id, arg, axis, lo, hi, coords) 25. ef_get_box_size(id, arg, axis, lo, hi, size) 26. ef_get_box_limits(id, arg, axis, lo, hi, lo_lims, hi_lims) 27. ef_get_one_val(id, arg, value) 28. ef_version_test (version) 29. ef_bail_out(id, text) *Part II: COMMANDS REFERENCE 1. ALIAS 2. CANCEL 1. CANCEL ALIAS 2. CANCEL AXIS 3. CANCEL DATA_SET 4. CANCEL EXPRESSION 5. CANCEL GRID 6. CANCEL LIST 7. CANCEL MEMORY 8. CANCEL MODE 9. CANCEL MOVIE 10. CANCEL SYMBOL 11. CANCEL REGION 12. CANCEL VARIABLE 13. CANCEL VIEWPORT 14. CANCEL WINDOW 3. CONTOUR 4. DEFINE 1. DEFINE ALIAS 2. DEFINE AXIS 3. DEFINE GRID 4. DEFINE REGION 5. DEFINE SYMBOL 6. DEFINE VARIABLE 7. DEFINE VIEWPORT 5. ELIF 6. ELSE 7. ENDIF 8. EXIT 9. FILE 10. FILL 11. FRAME 12. GO 13. HELP 14. IF 1. IF-THEN-ELSE conditional execution 2. IF-THEN-ELSE logic for masking 15. LABEL 16. LET 17. LIST 18. LOAD 19. MESSAGE 20. PALETTE 21. PATTERN 22. PAUSE 23. PLOT 24. POLYGON 25. PPLUS 26. QUERY 27. QUIT 28. REPEAT 29. SAVE 30. SAY 31. SET 1. SET AXIS 2. SET DATA_SET 3. SET EXPRESSION 4. SET GRID 5. SET LIST 6. SET MEMORY 7. SET MODE 1. SET MODE ASCII_FONT 2. SET MODE CALENDAR 3. SET MODE DEPTH_LABEL 4. SET MODE DESPERATE 5. SET MODE DIAGNOSTIC 6. SET MODE IGNORE_ERROR 7. SET MODE INTERPOLATE 8. SET MODE JOURNAL 9. SET MODE LATIT_LABEL 10. SET MODE LONG_LABEL 11. SET MODE METAFILE 12. SET MODE POLISH 13. SET MODE PPLLIST 14. SET MODE REFRESH 15. SET MODE SEGMENTS 16. SET MODE STUPID 17. SET MODE VERIFY 18. SET MODE WAIT 8. SET MOVIE 9. SET REGION 10. SET VARIABLE 11. SET VIEWPORT 12. SET WINDOW 32. SHADE 33. SHOW 1. SHOW ALIAS 2. SHOW AXIS 3. SHOW COMMANDS 4. SHOW DATA_SET 5. SHOW EXPRESSION 6. SHOW FUNCTION 7. SHOW GRID 8. SHOW LIST 9. SHOW MEMORY 10. SHOW MODE 11. SHOW MOVIE 12. SHOW QUERIES 13. SHOW REGION 14. SHOW SYMBOL 15. SHOW TRANSFORM 16. SHOW VARIABLES 17. SHOW VIEWPORT 18. SHOW WINDOWS 34. SPAWN 35. STATISTICS 36. UNALIAS 37. USE 38. USER 1. Objective analysis 2. Scattered sampling 39. VECTOR 40. WHERE 41. WIRE GLOSSARY Appendix A: EXTERNAL FUNCTIONS 1. COMPRESSI 2. COMPRESSJ 3. COMPRESSK 4. COMPRESSL 5. COMPRESSI_BY 6. COMPRESSJ_BY 7. COMPRESSK_BY 8. COMPRESSL_BY 9. CONVOLVEI 10. EOF_SPACE 11. EOF_STAT 12. EOF_TFUNC 13. WRITEV5D 14. ZAXREPLACE_AVG 15. ZAXREPLACE_BIN Appendix B: PPLUS Users Guide 1. INTRODUCTION 2. GETTING STARTED 1. VAX/VMS 2. Required Definitions 1. Optional Definitions 3. &NBSP;COMMAND FORMAT 1. THE COMMANDS 4. COMMAND SYNOPSIS 1. FILES 1. Data Files 2. Other Data Entry 3. PPLUS Output Files 4. PPLUS Command Files 2. AXIS 1. X- And Y-axis 2. Time Axis 3. LABELS 4. COMMAND PROCEDURES 5. COLOR AND FONTS 6. PLOT APPEARANCE 7. PLOT GENERATION 8. DATA MANIPULATION 9. HELP 5. BEGINNERS GUIDE 1. FORMAT 2. 5.2 VARS 3. SKP AND RD 4. PLOT AND CONTOUR 5. EXAMPLES 1. Unformatted Data, X-Y Plot 2. Pre-gridded Data, Contour Plot 3. Ungridded Data, Contour Plot 4. Time Series Plot 6. &NBSP;ROUTING PLOT FILES 1. VAX/VMS 1. Plot Files And Mom 2. Plotting Devices 3. Examples 7. &NBSP;&NBSP;&NBSP;&NBSP;&NBSP;&NBSP;&NBSP;&NBSP;PPLUS COMMAND FILES 1. INTRODUCTION 2. SYMBOL SUBSTITUTION 3. GENERAL GLOBAL SYMBOLS 4. EPIC GLOBAL SYMBOLS 5. COMMAND FILE LOGIC 6. ARITHMETIC 7. SYMBOL ARRAYS 8. SPECIAL FUNCTIONS 1. $EDIT 2. $EXTRACT 3. $INTEGE 4. $LENGTH 5. $LOCATE 6. $ELEMENT 9. LABELS 1. AXIS LABELING 2. EMBEDDED STRING COMMANDS 3. Pen Selection 4. Character Slant 5. Subscripting, Superscripting And Back Spacing 10. DATA FORMATS 1. SEQUENTIAL FORMATS 2. BIBO FORMAT 3. EPIC FORMAT 4. DSF FORMAT 11. ADVANCED COMMANDS 1. %OPNPLT/qualifier 2. %CLSPLT/qualifiers 3. %PLTLIN,n 4. %LABEL/qualifier,x,y,ipos,ang,chsiz,label 5. %RANGE,min,max,ntic 6. %XAXIS/qualifier,xlow,xhigh,xtic,y[,nmstc][,lint][,xunit][,ipos][,csize][,frmt] 7. %YAXIS/qualifier,ylow,yhigh,ytic,x[,nmstc][,lint] [,yunit][,ipos][,csize][,frmt] 8. PLOT5, PPLUS DIFFERENCES 9. &NBSP;COMMAND DESCRIPTION 1. @file_name/qualifier arg1 arg2 arg3 ... 2. AUTO,ON/OFF 3. AUTOLAB,ON/OFF 4. AXATIC,ATICX,ATICY 5. AXLABP,LABX,LABY 6. AXLEN,XLEN,YLEN 7. AXLINT,LINTX,LINTY 8. AXLSZE,HGTX,HGTY 9. AXNSIG,NSIGX,NSIGY 10. AXSET,TOP,BOT,LEFT,RIGHT 11. AXTYPE,TYPEX,TYPEY 12. BAUD,IB 13. BOX,ON/OFF 14. C 15. CLSPLT 16. CONPRE,prefix 17. CONPST,postfix 18. CONSET,HGT,NSIG,NARC,DASHLN,SPACLN,CAY,NRNG,DSLAB 19. CROSS,ICODE 20. DATPT,type,mark 21. DEBUG on/off 22. DEC symbol 23. DELETE symbol 24. DFLTFNT,font 25. DIR,arg 26. ECHO,on/off 27. ENGLISH 28. ENTER 29. EVAR/qualifier,x-var,y-var 30. GET,file_name 31. GRID[,LINEAR] 32. HELP,arg 33. HLABS,n,height 34. HLP,arg 35. F expression THEN 36. INC sym 37. LABS/qualifier,n,X,Y,JST,label 38. LABSET,HLAB1,HXLAB,HYLAB,HLABS 39. LEV,arg,arg,arg ... 40. LIMITS,value,comparison,flag 41. LINE,n,MARK,TYPE,XOFF,YOFF,DN1,UP1,DN2,UP2 42. LINFIT,n,XIMIN,XIMAX,XOMIN,XOMAX 43. LIST,IMIN,IMAX,JMIN,JMAX,VCOMP,arg 44. LISTSYM 45. LLABS,n,X,Y,TYPE 46. MARKH,n,SIZE 47. METRIC 48. NLINES 49. ORIGIN,XORG,YORG 50. PEN,n,ipen 51. PLOT/qualifiers,label 52. PLOTV/qualifiers,VANG,INC,label 53. PLOTUV/qualifiers,VANG,INC,label 54. PLTNME,fname 55. PLTYPE,ICODE 56. RD/qualifier,NX,NY,TYPE,n,file_name 57. RESET 58. RETURN 59. RLABS,n,ANG 60. ROTATE,ON/OFF 61. RWD,file_name 62. SAVE,file_name 63. SET sym arg 64. SHOW symbol 65. SIZE,width,height 66. SKP,n,file_name 67. SMOOTH,n 68. SPAWN 69. TAXIS/qualifier,DT,arg 70. TEKNME[,fname] 71. TICS,SMX,LGX,SMY,LGY,IX,IY 72. TIME,TMIN,TMAX,TSTART 73. TITLE,HLAB,label 74. TKTYPE,TYPE 75. TRANSXY,n,XFACT,XOFF,YFACT,YOFF 76. TXLABP,n 77. TXLINT,low_int,hi_int 78. TXLSZE,ht 79. TXNMTC,n 80. TXTYPE,type,style 81. VARS,NGRP,A1,A2,A3,...,Ai 82. VECKEY/qualifier,x,y,ipos,format 83. VECSET,length,scale 84. VECTOR/qual,skipx,skipy,label 85. VELVCT,rlenfact,inc 86. VIEW/qualifiers,ZSCALE,IC,ZMIN,ZMAX,VCOMP,label 87. WHILE expression THEN 88. WINDOW,ON/OFF 89. XAXIS,XLO,XHI,XTIC 90. XFOR,frmt 91. XLAB,label 92. YAXIS,YLO,YHI,YTIC 93. YFOR,frmt 94. YLAB,label 10. FONT TABLES *Appendix C: PLOTPLUS PLUS: Ferret Enhancements to PLOTPLUS 1. &NBSP;PLOTPLUS HISTORY, EVOLUTION 2. ENHANCED COMMANDS DESCRIPTION 1. ALINE/qualifier line#, minx, miny, maxx, maxy, set 2. CLSPLT 3. COLOR n, red, green, blue 4. CONSET hgt, nsig, narc, dashln, spacln, cay, nrng, dslab, spline_tension, draftsman 5. FILL/qualifier 6. LINE n, mark, use 7. LIST arg 8. PEN n, ndx 9. PLTNME metafile_name 10. PLTYPE icode META 11. SHADE/qualifier 12. SHAKEY do_key, orient, klab_siz, klab_inc, klab_dig, klab_len, kx_lo, kx_hi, ky_lo, ky_hi 13. SHASET 3. GKS LINE BUNDLES 4. HARD COPY *** Chapter 1: INTRODUCTION *** *** 1 OVERVIEW *** Ferret is an interactive computer visualization and analysis environment designed to meet the needs of oceanographers and meteorologists analyzing large and complex gridded data sets. "Gridded data sets" in the Ferret environment may be multi-dimensional model outputs, gridded data products (e.g., climatologies), singly dimensioned arrays such as time series and profiles, and for certain classes of analysis, scattered n-tuples (optionally, grid-able using an objective analysis procedure provided in Ferret). Ferret accepts data from ASCII and binary files, and from two standardized, self- describing formats. Ferret's gridded variables can be one to four dimensions -- usually (but not necessarily) longitude, latitude, depth, and time. The coordinates along each axis may be regularly or irregularly spaced. Version 4.4 and higher versions of Ferret have added a point-and-click graphical user interface (GUI) to Ferret. The GUI has been constructed to be 100% compatible with Ferret's command line interface. The user may freely mix text-based commands with mouse actions (push buttons, etc.). Ferret's journal file will log all of the actions performed during a session such that the entire session, including GUI inputs, can be replayed and edited at a later time. This User's Guide describes only the command line interface to Ferret. Other documents describe the point and click interface. Ferret was developed by the Thermal Modeling and Analysis Project (TMAP) at NOAA/PMEL in Seattle to analyze the outputs of its numerical ocean models and compare them with gridded, observational data. Model data sets are often multi-gigabyte in size with mixed 3- and 4-dimensional variables defined on staggered grids. Ferret offers the ability to define new variables interactively as mathematical expressions involving data set variables. Calculations may be applied over arbitrarily shaped regions. Ferret provides fully documented graphics, data listings, or extractions of data to files with a single command. Without leaving the Ferret environment, graphical output may be customized to produce publication-ready graphics. Animations are also available. Ferret is supported on a variety of Unix worstations with a version also available for Macintosh. A point-and-click interface is under development at the time of this writing. Ferret is available at no charge from anonymous FTP [node abyss.pmel.noaa.gov] or from the World Wide Web [URL http://www.pmel.noaa.gov/]. For users with access to the World Wide Web, Ferret may be perused in hypertext. *** 1.1 Ferret User's Group *** The Ferret User's Group provides a venue to ask experienced Ferret users for advice solving problems and to keep abreast of the latest Ferret updates. To join simply send an e-mail message to Majordomo@ferret.wrc.noaa.gov and include a message which says simply subscribe ferret_users (Note this must be in the e-mail message BODY -- not in the subject line.) To learn about the user's list without joining send this message instead to the same address: info ferret_users *** 2 GETTING STARTED *** A quick way to get to know Ferret is to run the tutorial provided with the distribution. % ferret yes? GO tutorial If Ferret is not yet installed consult Chapter 7. (The tutorial is also available through the World Wide Web.) The tutorial demonstrates many of Ferret's features, showing the user both the commands given and Ferret's textual and graphical output. You may find the explanations, terms and examples in this manual easier to understand after running the tutorial. *** 2.1 Concepts *** Words in bold below are defined in the glossary of this manual. In Ferret all variables are regarded as defined on grids. The grids tell Ferret how to locate the data in space and time (or whatever the underlying units of the grid axes are). A collection of variables stored together on disk is a data set. To access a variable Ferret must know its name, data set and the region of its grid that is desired. Regions may be specified as subscripts (indices) or in world coordinates. Data sets, after they have been pointed to with the SET DATA command, may be referred to by data set number or name. Using the LET command new variables may be created "from thin air" as abstract expressions or created from combinations of known variables as arbitrary expressions. If component variables in an expression are on different grids, then regridding may be applied simply by naming the desired grid. The user need never explicitly tell Ferret to read data. From start to finish the sequence of operations needed to obtain results from Ferret is simply: 1) specify the data set 2) specify the region 3) define the desired variable or expression (optional) 3) request the output For example (Figure 1), yes? SET DATA coads !global sea surface data yes? SET REGION/Z=0/T="16-JAN-1982"/X=160E:160W/Y=20S:20N yes? VECTOR uwnd,vwnd !wind velocity vector plot *** 2.2 Unix command line switches *** ferret [-memsize Mwords] [-unmapped] [-gui] [-help] -memsize Mwords specify the memory (data cache) size in Megawords default: 3.2 -unmapped use invisible output windows (useful for creating animations and GIF files) -gui start Ferret in point-and-click mode (may not be available on all platforms) -help obtain help on the Unix command line options *** 2.3 Sample sessions *** This section presents a number of short Ferret sessions that demonstrate common uses. Data sets used in these sessions and throughout this manual are included with the distribution. If Ferret is installed on your system, you can duplicate the examples shown. *** 2.3.1 Accessing a formatted data set *** In this sample session, the data set "monthly_navy_winds" is specified and certain aspects of it are examined. The command SHOW DATA/VARIABLES displays the variables in "monthly_navy_winds" and where on each axis they are defined. SET REGION specifies where in the grid the user wishes to examine the data. VECTOR produces a vector plot of the indicated variables over the specified region. yes? SET DATA monthly_navy_winds ! specify the data set yes? SHOW DATA/VARIABLES ! what's in it? currently SET data sets: 1> /home/r3/tmap/fer_dsets/descr/monthly_navy_winds.des (default) FNOC 2.5 Degree 1 Month Average World-wide Wind Field name title I J K L UWND ZONAL WIND 1:144 1:73 1:1 1:132 M/S on grid FNOC251 with -99.9 for missing data X=18.8E:18.8E(378.8) Y=91.3S:91.3N VWND MERIDIONAL WIND 1:144 1:73 1:1 1:132 M/S on grid FNOC251 with -99.9 for missing data X=18.8E:18.8E(378.8) Y=91.3S:91.3N time range: 16-JAN-1982 20:00 to 17-DEC-1992 03:30 *** 2.3.2 Reading an ASCII data file *** Many examples of accessing ASCII data are available later in this manual. See Chapter 2, "Data Sets." The simplest access, one variable with one value per record, looks like this: % ferret yes? FILE/VARIABLE=v1 snoopy.dat yes? PLOT v1 yes? QUIT *** 2.3.3 Using viewports *** The command SET VIEWPORT allows the user to divide the output graphics "page" into smaller display viewports. In this sample session, we create twp plots in two halves of a window (Figure2): % ferret yes? SET DATA coads_climatology yes? SET REGION/X=160E:130W yes? SET REGION/Y=-10:10/L=5 yes? SET VIEWPORT upper yes? CONTOUR sst yes? SET VIEWPORT lower yes? CONTOUR airt yes? QUIT *** 2.3.4 Using abstract variables *** Abstract variables (expressions that contain no dependencies on disk-resident data) can be easily displayed with Ferret. See Chapter 3, section "Abstract variables," for several examples and detailed information. For example, a user wishing to examine the function SIN(X) on the interval [0,3.14] might use (Figure 3): % ferret yes? PLOT/I=1:100 sin(3.14*I/100) yes? QUIT *** 2.3.5 Using transformations *** A transformation is an operation performed on a variable along a particular axis and is specified with the syntax "@trn" where "trn" is the name of a transformation. See Chapter 3, section "Transformations," for detailed information. A user may wish to look at ocean temperatures averaged over a range of depths. In this sample session, we look at temperatures averaged from 0 to 100 meters of depth using a data set which has detailed resolution in depth (Figure 4). We plot the data along longitude 160 west from latitude 30 south to 30 north. % ferret yes? SET DATA levitus_climatology yes? SET REGION/Y=30s:30n/X=160W yes? PLOT temp[Z=0:100@AVE] yes? QUIT *** 2.3.6 Using algebraic expressions *** See Chapter 3, section "Expressions" for a description of valid expressions. In this example, the data set contains raw sea surface temperatures, air temperatures, and wind speed measurements. We wish to look at a shaded plot of sensible heat at its first timestep (L=1) (Figure 5). We specify a latitude range and contour levels. % ferret yes? SET DATA coads_climatology !monthly COADS climatology yes? LET kappa = 1 !arbitrary yes? LET/TITLE="SENSIBLE HEAT" sens_heat = kappa * (airt-sst) * wspd yes? SHADE/L=1/LEV=(-20,20,5)/Y=-90:40 sens_heat yes? QUIT *** 2.3.7 Finding the 20-degree isotherm *** Isotherms can be located with the "@LOC" transform, which returns the axis location where the value of the argument of @LOC first occurs. Thus, "TEMP[Z=0:200@LOC:20]" locates the first occurrence of the temperature value 20 along the Z axis, scanning all the data between 0 and 200 meters. A session examining the 20 degree isotherm in mid-Pacific ocean data (Figure6): % ferret yes? SET DATA levitus_climatology yes? SET REG/Y=10s:30n/X=140E:140W yes? PPL CONSET .12 !label size yes? CONTOUR temp[Z=0:200@LOC:20] yes? QUIT Note that the transformation @WEQ could have been used to display ANY variable on the surface defined by the 20 degree isotherm. *** 3 COMMON COMMANDS *** A quick reference to the most commonly used Ferret commands (typing "SHOW COMMANDS" at the Ferret prompt lists all commands): Command Description SET DATA_SET names the data set to be analyzed SHOW DATA produces a summary of variables in a data set SHOW GRID examines the coordinates of a grid SET REGION sets the region to be analyzed LIST produces a listing of data PLOT produces a plot CONTOUR produces a contour plot (/FILL for color-filled contour plot) VECTOR produces a vector arrow plot SHADE produces a shaded-area plot STATISTICS produces summary statistics about variables and expressions LET defines a new variable SAVE saves data in NetCDF format GO executes Ferret commands contained in a file Information on all Ferret commands is available in Part II, Commands Reference, of this manual. *** 4 COMMAND SYNTAX *** Commands in program Ferret conform to the following template: COMM [/Q1/Q2...] [SUBCOM[/S1/S2...]] [ARG1 ARG2 ...] [!comment] where COMM is a command name yes? LIST Q1... are qualifiers of the command yes? CONTOUR/SET_UP SUBCOM is a subcommand name yes? SHOW MODE S1... are qualifiers of the subcommand yes? SET LIST/APPEND ARG1... are arguments of commands yes? CANCEL MODE INTERPOLATE notes... - Items in square brackets are optional. - One or more spaces or tabs must separate the command from the subcommand and from each of the arguments. Spaces and tabs are optional preceding qualifiers. - Multiple commands, separated by semi-colons, can be given on the same line. - Command names, subcommand names, and qualifiers require at most 4 characters. (e.g., yes? CANCEL LIST/PRECISION is equivalent to yes? CANC LIST/PREC) - Some qualifiers take an argument following " = " (e.g., yes? LIST/Y=10S:10N). - An exclamation mark normally signifies the end of a command and the start of (optional) comment text. - The backslash character (\), when placed directly before an exclamation point (!), apostrophe ('), semicolon (;), or forward slash (/), will hide it ("escape it") from Ferret. *** 5 GO FILES *** GO files are files containing Ferret commands. They can be executed with the command "GO filename". Throughout this manual, these files are referred to as GO scripts or journal files (the file names end in *.jnl). There are two kinds of GO files provided with the distribution (differing in function, not form) -- demos and tools. *** 5.1 Demonstration files *** Demonstration GO files provide examples of various Ferret capabilities (the tutorial is such a script) . The demonstration GO files may be executed simply by typing the Ferret command yes? GO demo_name example: yes? GO spirograph_demo Below is a list of the demo files provided (located in directory $FER_DIR/examples). The Unix command "Fgo demo" will list all GO scripts containing the string "demo". Name Description tutorial brief tour through Ferret capabilities topographic_relief_demo global topography coads_demo view of global climate using the Comprehensive Ocean- Atmosphere Data Set levitus_demo T-S relationships using Sydney Levitus' climatological Atlas of the World Oceans fnoc_demo Naval Fleet Numerical Oceanography Center data vector_demo vector plots wire_frame_demo 3D wire frame representation custom_contour_demo customized contour plots viewports_demo output to viewports multi_variable_demo multiple variables with multiple dependent axes objective_analysis_demo interpolating scattered data to grids polar_demo polar stereographic projections mercator_demo mercator projections log_plot_demo log plots using PPLUS in Ferret depth_to_density_demo contour with a user-defined variable as an axis file_reading_demo reading an ASCII file regridding_demo tutorial on regridding data mathematics_demo abstract function calculation statistics_demo probability distributions spirograph_demo for-fun plots from abstract functions splash_demo for-fun mathematical color shaded plots symbol_demo how to use symbols for plot layouts sigma_coordinate_demo how to work with sigma coordinates *** 5.2 GO tools *** GO tools are scripts which contain Ferret commands and perform dataset- independent tasks. For example, "GO land" overlays the outline of the continents on your plot. (Note: In order for Ferret to locate the GO scripts, the environment variable FER_GO must be properly defined. See Chapter 7, "Computing Environment," for guidance.) The Unix command Fgo has been provided to assist with locating tools within the Unix directory hierarchy. For example, % Fgo grid displays all tools with the substring "grid" in their names % Fgo '*' displays all GO tools and demonstrations Below is a table of the tools provided with your Ferret installation. Some tools accept optional arguments to control details. Use Fgo -more script_name for details on a script. Tool name Description OVERLAYS basemap a geographical basemap of continents to overlay on land overlays continental boundaries (color controls) bold_land overlays darker continental boundaries fland overlays filled continents (color and resolution controls) focean overlays ocean mask (for terrestrial plots) graticule sets the plot axis style to use a graticule (rather than tics) tics resets the plot style to use axis tics (rather than a graticule) gridxy overlays a "graticule" labeling the I,J subscripts gridxz overlays a "graticule" labeling the I,K subscripts gridxt overlays a "graticule" labeling the I,L subscripts gridyz overlays a "graticule" labeling the J,K subscripts gridyt overlays a "graticule" labeling the J,L subscripts gridzt overlays a "graticule" labeling the K,L subscripts box draws a box at the specified location on the plot ellipse draws an ellipse at the specified location on the plot MATHEMATICAL frequency_histogram makes a frequency distribution plot (histogram) of data ts_frequency creates a 2-variable histogram (typically an oceanographer's TS density diagram) polar defines R and THETA from X and Y to perform (limited) polar plots regressx defines variables for linear regression along X axis regressy defines variables for linear regression along Y axis regressz defines variables for linear regression along Z axis regresst defines variables for linear regression along T axis unit_square sets unit square as default for abstract variables variance defines variables to compute variances and covariances var_n refines TVARIANCE with corrected n/n+1 factors dynamic_height defines Ferret variables for dynamic height calculations SAMPLE DISPLAYS line_samples draws specimens of the available line styles line_thickness draws examples of pen color/thickness styles in PPLUS fill_samples draws specimens of the available fill styles show_symbols draws specimens of the default symbols show_88_syms draws specimens of all 88 PPLUS symbols GRAPHICS bar_chart makes a color-filled bar chart from a line of data bar_chart2 makes a bar chart using hollow rectangles centered_vectors makes a vector plot with coords at vector midpoints scattered_vectors makes a vector plot from an ASCII file: x,y,u,v stick_vectors makes a stick vector plot of a line of U,V values extremum annotate contour extrema on a plot split_z oceanographic-style plot with 2 z-axis scalings PLOT APPEARANCE margins tweak the sizing of the plot on the page magnify [factor] increases the data plotting area (area inside the axes) unmagnify restores the plot origin and axis lengths to default values black sets video background to black, foreground to white white sets video background to white, foreground to black bold sets up PLOT+ and Ferret to produce bolder-looking plots unbold resets plot environment to normal after "GO bold" unlabel [label #] removes a specified (numbered) PPLUS movable label remove_logo removes labels 1-3 that form the Ferret logo box_plot produces a plot with "bare" axes (no tics, no labels) reminder place small annotations in upper left corner of plot COLOR try_palette [pal] displays palette appearance for various numbers of color levels try_centered_palette displays centered palette appearance for various numbers of levels exact_colors sets up Ferret and PPLUS to modify individual colors in a color palette squeeze_colors modifies a color palette by squeezing and stretching the color scale MULTIPLE X AND Y AXES (run demo: yes? GO multi_variable_plots) left_axis_plot plots a single variable preparing for a 2nd axis on the right right_axis_plot overlays a plot of a single variable using an axis on the right multi_xaxis_plot1 draws a plot formatted for later overlays using multiple X axes multi_xaxis_overlay overlays a variable with a distinct X axis multi_yaxis_plot1 draws a plot formatted for later overlays using multiple Y axes multi_yaxis_overlay overlays a variable with a distinct Y axis POLAR STEREOGRAPHIC PROJECTIONS (run demo: yes? GO polar_demo) convert_to_polar_2d extracts (sample) data for a 2D polar plot polar_2d produces a 2D polar stereographic plot polar_fland overlays solid-filled continents on a polar plot polar_grid overlays "quick" radial longitude and curved latitude lines polar_grid_fancy overlays "fancy" radial longitude and curved latitude lines polar_land overlays the continental outlines on a polar stereographic plot polar_map_inv_eqns defines the equations used for polar projections polar_vector produces a 2D polar stereographic vector plot polar_vs performs a polar PLOT/VS of 2 variables: lat long projected_map_grid defines the map grid for a projected plot SAMPLING A GRIDDED FIELD vertical_section extract an arbitrary vertical section from a 3D field GRIDDING POINT DATA objective gridding of 2D data TESTS test tests proper functioning of FER_GO ptest produces a quick test plot squares creates a filled-area test plot *** 5.3 Writing GO tools *** A GO tool ("GO script," "journal file," ...) is simply a sequence of Ferret commands stored in a file and executed with the GO command. Writing a simple GO tool requires nothing more than typing normal commands into a file. To write a robust GO tool that may be shared, however, certain guidelines should be followed: 1) the GO tool should be well documented 2) the GO tool should leave the Ferret context unmodified 3) the GO tool may need to run "silently" 4) the GO tool may need to accept arguments (parameters) *** 5.3.1 Documenting GO tools *** Documentation consists primarily of well-chosen comment lines (lines beginning with an exclamation mark). In addition, a line of this form should be included: ! Description: [one-line summary of your GO tool] This line is displayed by the Fgo tool. *** 5.3.2 Preserving the Ferret state in GO tools *** Often a complex GO tool requires setting data sets, modifying the current region, etc. But to a user executing this tool its behavior may seem erratic if the user's previous context is modified by running the tool. A tool can restore the previous state of Ferret by these means: region: Save the current default region with the command DEFINE REGION/DEFAULT save. Restore it at the end of your GO tool with SET REGION save. data set: Save the current default data set with SET DATA/SAVE. Restore it at the end of your GO tool with SET DATA/RESTORE. grid: Save the current default grid set with SET GRID/SAVE. Restore it at the end of your GO tool with SET GRID/RESTORE. modes: If you modify a mode inside your GO tool by issuing a SET MODE or a CANCEL MODE command the original state of that mode can be restored using SET MODE/LAST. *** 5.3.3 Silent GO tools *** If a user has set mode "verify" then by default every line of your GO tool, including comment lines, will be displayed at the screen as Ferret processes it. To make your GO tool run silently include the command CANCEL MODE VERIFY at the beginning of the GO tool and SET MODE/LAST VERIFY at the end. If the backslash character "\" is found at the beginning of any line that single line will not be displayed regardless of the state of MODE VERIFY. Thus the command "\CANCEL MODE VERIFY" is often the first line of a GO tool. Note also that the command LET/SILENT is useful in GO tools which need to define variables. *** 5.3.4 Arguments to GO tools *** Arguments (parameters) may be passed to GO tools on the command line. For example, yes? GO land red passes the string "red" into the GO file named land.jnl. Inside the GO tool the argument string "red" is substituted for the string "$1" wherever it occurs. The "1" signifies that this is the first argument -- similar logic can be applied to $1,... $9 or $0 where $0 is replaced by the name of the GO tool itself. Similarly "$*" is replaced by all the arguments, 1-9 as a single string. As Ferret performs the substitution of $1 (or other) arguments it offers a number of string processing and error processing options. For example, without these options, if a user failed to supply an argument to "GO land" then Ferret would not know what to substitute for $1 and it would have to issue an error message. A default value can be supplied by the GO tool writer using the syntax $1%string% for example, $1%black% inside land.jnl would default to "black" if no color were specified. Note that in the example percent signs were used to delimit the default string but any of the characters ! # $ % or & also work as delimiters. In another case it might not be appropriate to supply a default string but instead it would be desirable to issue an instructional error message. The "<" character indicates an error message text: $1"". Thus $1"1|red>2|" specifies a default string of "1" if no argument is given but substitutes "2" if "red" is supplied. In a typical GO tool line, defaults, options, substitutions, and an error message are combined like this: PLOT/LINE=$1"1|red>2|green>3|blue>4|2|green>3|blue>4|*>7" would never generate an error and would use line style 7 (thick black) if an unrecognized argument string such as "purple" were given. An asterisk (*) can also be used on the right-hand side of a substitution, in which case it stands for the entire original argument string. For example SET VARIABLE/TITLE=$1%*>"*"% will place double quotation marks around the string in argument 1. A final style note to keep in mind when writing GO tools that use arguments: providing error message feedback and appropriate documentation for the user is essential. In complex GO tools, all arguments should be checked at the beginning of the GO tool using the no-op command (has no effect) "QUERY/IGNORE". Thus the GO tool land.jnl might contain these lines at the beginning: ! check the argument QUERY/IGNORE $1"1|red|green|blue| /home/e1/tmap/fer_dsets/descr/coads_climatology.des (default) name title I J K L SST SEA SURFACE TEMPERATURE 1:180 1:90 1:1 1:12 AIRT AIR TEMPERATURE 1:180 1:90 1:1 1:12 SPEH SPECIFIC HUMIDITY 1:180 1:90 1:1 1:12 WSPD WIND SPEED 1:180 1:90 1:1 1:12 UWND ZONAL WIND 1:180 1:90 1:1 1:12 VWND MERIDIONAL WIND 1:180 1:90 1:1 1:12 SLP SEA LEVEL PRESSURE 1:180 1:90 1:1 1:12 If multiple data sets have been requested in a single Ferret session, the last requested will be the default data set. To specify other data sets, use the name of the data set or the number of the set as given by the SHOW DATA statement. For example: yes? LIST/D=2 temp will list the data for the variable "temp" in data set number 2 as displayed by SHOW DATA/BRIEF, while yes? LIST temp[D=levitus_climatology] - temp[D=coads_climatology] will list the differences between the variable "temp" in data set "levitus_climatology" and data set "coads_climatology." *** 2 NETCDF DATA *** The Network Common Data Format (NetCDF) is an interface to a library of data access routines for storing and retrieving scientific data. NetCDF allows the creation of data sets which are self-describing and platform-independent. NetCDF was created under contract with the Division of Atmospheric Sciences of the National Scientific Foundation and is available from the Unidata Program Center in Boulder, Colorado (unidata.ucar.edu). See Chapter 8, "Converting Data to NetCDF," for a complete description of how to create NetCDF data sets or how to convert existing data sets into NetCDF. To output a variable in NetCDF, simply use: yes? LIST/FORMAT=CDF variable_name LIST/FORMAT=CDF (alias SAVE) can also be used with abstract variables: yes? SAVE/FILE=example.cdf/I=1:100 sin(I/100) This will create a file named example.cdf. The current region and data sets determine the variable names in the saved file and the range over which they are saved. Saved data can then be accessed as follows: yes? USE example (USE is an alias for SET DATA/FORMAT=CDF) If a filename is not specified, Ferret will generate one. (See command SET LIST/FILE in the Commands Reference section of this manual.) An example of converting TMAP-formatted data to NetCDF goes as follows: yes? SET DATA coads_climatology yes? SAVE/L=1 sst,airt,uwnd,vwnd These commands will save sst, airt, uwnd, and vwnd at the first time step over their entire regions to a NetCDF file named by Ferret. One advantage to using NetCDF is that users on a different system (i.e., VMS instead of Unix) with different software (i.e., with an analysis tool other than Ferret) can share data easily without substantial conversion work. NetCDF files are self-describing; with a simple command the size, shape and description of all variables, grids and axes can be seen. *** 2.1 Multi-file NetCDF data sets *** Ferret supports collections of NetCDF files that are regarded as a single NetCDF data set. Such data sets are referred to as "MC" (multi CDF) data sets. They are particularly useful to manage the outputs of numerical models. MC data sets use a descriptor file, in the style of TMAP-formatted data sets. The data set is referred to inside Ferret by the name of this descriptor file. A collection of NetCDF files is suitable to form a multi-file data set if 1) The files are connected through their time axis -- each file represents one or more time snapshots of the variables it contains. 2) Each file is self-documenting with respect to the time axis of the variables -- even if the time axis represents only a single point. (All of the time axes must be identically encoded with respect to units and date of the time origin.) 3) All non-time-dependent variables in the data set must be contained in first file of the data set (or those variables will not appear in the merged, MC, data set). A typical MC descriptor file may be found in Chapter 9, Section 4, "Creating an multi-NetCDF data set." Further documentation on MC data sets may be found in the Ferret home pages on the Web. *** 3 TMAP-FORMATTED DATA *** As of Ferret version 2.30, NetCDF is the suggested format for data storage (see Chapter 8, "Converting to NetCDF"). This section describing TMAP information is included only for users who already work with data in TMAP format. To access TMAP-formatted data sets use SET DATA_SET TMAP_set1, TMAP_set2, ... TMAP_setn must be the name of a descriptor file for a data set that is in TMAP "GT" (grids-at-timesteps) or "TS" (time series) format. ("Ferret" format and "TMAP" format are synonyms.) If the directory portion of the filename is omitted the environment variable FER_DESCR will be used to provide a list of directories to search. The order of directories in FER_DESCR determines the order of directory searches. If the extension is omitted a default of ".des" will be assumed (if the filename has more than one period, the extension must be given explicitly). Descriptors For every TMAP-formatted data set there is a descriptor file containing summary information about the contents of the data set. This includes variable names, units, grids, and coordinates. When the command SET DATA_SET is given to Ferret pointing to a GT-formatted or TS-formatted data set, it is the name of the descriptor file that must be specified. *** 4 BINARY DATA *** Binary data words must all begin on 4-byte boundaries to be accessible by Ferret. To understand how to access binary data files with Ferret it is necessary to understand something of the structure of binary files. Binary files are of two general types -- files containing record length information and files without imbedded record length information. Within each of these categories the records may actually be of uniform length or of variable length. *** 4.1 FORTRAN-structured binary files *** Files containing record length information are created by FORTRAN programs using the ACCESS="SEQUENTIAL" (the FORTRAN default) mode of file creation and also by Ferret using LIST/FORMAT=unf. Suppose "rrrr" represents 4 bytes of record length information and "dddd" represents a 4-byte data value. Then FORTRAN-structured files are organized in one of the following two ways: *** 4.1.1 Records of uniform length *** A FORTRAN-structured file with records of uniform length (3 single-precision floating point data values per record in this figure) look as follows: rrrr dddd dddd dddd rrrr rrrr dddd dddd dddd rrrr ... FORTRAN code that creates a data file of this type might look something like this (sequential access is the default and need not be specified in the OPEN statement): REAL VARI(10), VAR2(10), VAR3(10) ... OPEN(UNIT=20,FORMAT="UNFORMATTED",ACCESS="SEQUENTIAL",FILE="MYFILE.DAT") ... DO 10 I=1,10 WRITE (20) VAR1(I), VAR2(I), VAR3(I) 10 CONTINUE .... To access data from this file, use yes? SET DATA/EZ/FORMAT=UNF/VAR=var1,var2,var3/COL=3 myfile.dat or, yes? FILE/FORMAT=UNF/VAR=var1,var2,var3/COLUMNS=3 myfile.dat This is very similar to accessing ASCII data with the addition of the /FORMAT=unf qualifier. The /COLUMNS= qualifier tells Ferret the number of data values per record. Although optional in the above example, this qualifier is required if the number of data values per record is greater than the number of variables being read (examples follow in section "ASCII Data"). *** 4.1.2 Records of non-uniform length *** A FORTRAN-structured file with variable-length records may look as follows: rrrr dddd dddd rrrr rrrr dddd rrrr rrrr dddd dddd dddd dddd rrrr etc. With care, it is possible to read a data file containing variable-length records which was created using the simplest unformatted FORTRAN OPEN statement and a single WRITE statement for each variable. Use /FORMAT=stream to read such files. Note that sequential access is the FORTRAN default and does not need to be specified in the OPEN statement: REAL VAR1(1000), VAR2(500) ... OPEN (UNIT=20, FORMAT="UNFORMATTED", FILE="MYFILE.DAT") ... WRITE (20) VAR1 WRITE (20) VAR2 .... Use the qualifier /SKIP to skip past the record length information (/SKIP arguments are in units of words), and define a grid which will not read past the data values. The /COLUMNS= qualifier can be used when reading multiple variables to specify the number of words separating the start of each variable: yes? DEFINE AXIS/X=1:500:1 xaxis yes? DEFINE GRID/X=XAXIS mygrid yes? FILE/FORMAT=stream/SKIP=1003/GRID=mygrid/VAR=var2 myfile.dat The argument 1003 is the sum of the 1000 data words in record 1, plus 2 words of record length information surrounding the data values in record 1 (variable var1), plus 1 word of record information preceding the data in record 2. *** 4.2 Unstructured binary files *** Files without imbedded record length information are created by FORTRAN programs using ACCESS="DIRECT" in OPEN statements and by C programs. Suppose "dddd" represents a 4-byte data value. Then unstructured binary files are simply: dddd dddd dddd dddd dddd dddd ... Such files are also referred to as "direct access binary" files. The structure of the records is implied by the program accessing the data. FORTRAN code which generates a direct access binary file might look as follows: REAL*4 MYVAR(10,5) ... C Use RECL=40 for machines that specify in bytes OPEN(UNIT=20, FILE="myfile.dat", ACCESS="DIRECT", RECL=10) ... DO 100 j = 1, 5 100 WRITE (20,REC=j) (MYVAR(i,j),i=1,10) .... Use the following Ferret commands to read variable "myvar" from this file: yes? DEFINE AXIS/X=1:10:1 x10 yes? DEFINE AXIS/Y=1:5:1 y5 yes? DEFINE GRID/X=x10/Y=y5 g10x5 yes? FILE/VAR=MYVAR/GRID=g10x5/FORMAT=stream myfile.dat *** 5 ASCII DATA *** To access ASCII data files sets use yes? SET DATA/EZ ASCII_file_name or equivalently yes? FILE ASCII_file_name The following are qualifiers to SET DATA/EZ or FILE: Qualifier Description /VARIABLES names the variables in the file /TITLE associates a title with the data set /GRID indicates multi-dimensional data and units /COLUMNS tells how many data values are in each record /FORMAT specifies the format of the file /SKIP skips initial records of the file /ORDER specifies order of axes (which varies fastest) Use command SET VARIABLE to individually customize the variables. *** 5.1 Reading ASCII files *** Below are several examples of reading ASCII data properly. (Uniform record length, FORTRAN-structured binary data are read similarly with the addition of the qualifier /FORMAT= "unf". See Chapter 2 section "Binary Data" for other binary types). First, we look briefly at the relationship between Ferret and standard matrix notation. Linear algebra uses established conventions in matrix notation. In a matrix A(i,j), the first index denotes a (horizontal) row and the second denotes a (vertical) column. A11 A12 A13 ... A1n A21 A22 A23 ... A2n Matrix A(i,j) ... Am1 Am2 Am3 ... Amn X-Y graphs follow established conventions as well, which are that X is the horizontal axis (and in a geographical context, the longitude axis) and increases to the right, and Y is the vertical axis (latitude) and increases upward (Ferret provides the /DEPTH qualifier to explicitly designate axes where the vertical axis convention is reversed). In Ferret, the first index of a matrix, i, is associated with the first index of an (x,y) pair, x. Likewise, j corresponds to y. Element Am2, for example, corresponds graphically to x=m and y=2. By default, Ferret stores data in the same manner as FORTRAN -- the first index varies fastest. Use the qualifier /ORDER to alter this behavior. The following examples demonstrate how Ferret handles matrices. Example 1 -- 1 variable, 1 dimension 1a) Consider a data set containing the height of a plant at regular time intervals, listed in a single column: 2.3 3.1 4.5 5.6 . . . To access, name, and plot this variable properly, use the commands yes? FILE/VAR=height plant.dat yes? PLOT height 1b) Now consider the same data, except listed in four columns: 2.3 3.1 4.5 5.6 5.7 5.9 6.1 7.2 . . . Because there are more values per record (4) than variables (1), use: yes? FILE/VAR=height/COLUMNS=4 plant4.dat yes? PLOT height Example 2 -- 2 variables, 1 dimension 2a) Consider a data set containing the height of a plant and the amount of water given to the plant, measured at regular time intervals: 2.3 20.4 3.1 31.2 4.5 15.7 5.6 17.3 . . . To read and plot this data use yes? FILE/VAR="height,water" plant_wat.dat yes? PLOT height,water 2b) The number of columns need be specified only if the number of columns exceeds the number of variables. If the data are in six columns 2.3 20.4 3.1 31.2 4.5 15.7 5.6 17.3 ... use yes? FILE/VAR="height,water"/COLUMNS=6 plant_wat6.dat yes? PLOT height,water Example 3 -- 1 variable, 2 dimensions 3a) Consider a different situation: a greenhouse with three rows of four plants and a file with a single column of data representing the height of each plant at a single time (successive values represent plants in a row of the greenhouse): 3.1 2.6 5.4 4.6 3.5 6.1 . . . If we want to produce a contour plot of height as a function of position in the greenhouse, axes will have to be defined: yes? DEFINE AXIS/X=1:4:1 xplants yes? DEFINE AXIS/Y=1:3:1 yplants yes? DEFINE GRID/X=xplants/Y=yplants gplants yes? FILE/VAR=height/GRID=gplants greenhouse_plants.dat yes? CONTOUR height When reading data the first index, x, varies fastest. Schematically, the data will be assigned as follows: x=1 x=2 x=3 x=4 y=1 3.1 2.6 5.4 4.6 y=2 3.5 6.1 . . . y=3 . . . 3b) If the file in the above example has, instead, 4 values per record: 3.1 2.6 5.4 4.6 3.5 6.1 . . . then add /COLUMNS=4 to the FILE command: yes? FILE/VAR=height/COLUMNS=4/GRID=gplants greenhouse_plants.dat Example 4 -- 2 variables, 2 dimensions Like Example 3, consider a greenhouse with three rows of four plants each and a data set with the height of each plant and the length of its longest leaf: 3.1 0.54 2.6 0.37 5.4 0.66 4.6 0.71 3.5 0.14 6.1 0.95 . . . . Again, axes and a grid must be defined: yes? DEFINE AXIS/X=1:4:1 xht_leaf yes? DEFINE AXIS/Y=1:3:1 Yht_leaf yes? DEFINE GRID/X=xht_leaf/Y=yht_leaf ght_leaf yes? FILE/VAR="height,leaf"/GRID=ght_leaf greenhouse_ht_lf.dat yes? SHADE height yes? CONTOUR/OVER leaf The above commands create a color-shaded plot of height in the greenhouse, and overlay a contour plot of leaf length. Schematically, the data will be assigned as follows: x=1 x=2 x=3 x=4 ht , lf ht , lf y=1 3.1, 0.54 2.6, 0.37 5.4, 0.66 4.6, 0.71 y=2 3.5, 0.14 6.1, 0.95 . . . y=3 . . . Example 5 -- 2 variables, 3 dimensions (time series) Consider the same greenhouse with height and leaf length data taken at twelve different times. The following commands will create a three-dimensional grid and a plot of the height and leaf length versus time for a specific plant. yes? DEFINE AXIS/X=1:4:1 xplnt_tm yes? DEFINE AXIS/Y=1:3:1 yplnt_tm yes? DEFINE AXIS/T=1:12:1 tplnt_tm yes? DEFINE GRID/X=xplnt_tm/Y=yplnt_tm/T=tplnt_tm gplant2 yes? FILE/VAR="height,leaf"/GRID=gplant2 green_time.dat yes? PLOT/X=3/Y=2 height, leaf Example 6 -- 1 variable, 3 dimensions, permuted order (vertical profile) Consider a collection of oceanographic measurements made to a depth of 1000 meters. Suppose that the data file contains only a single variable, salt. Each record contains a vertical profile (11 values) of a particular x,y (long,lat) position. Supposing that successive records are successive longitudes, the data file would look as follows (assume the equivalencies are not in the file): z=0 z=10 z=20 . . . x=30W,y=5S 35.89 35.90 35.93 35.97 36.02 36.05 35.96 35.40 35.13 34.89 34.72 x=29W,y=5S 35.89 35.91 35.94 35.97 36.01 36.04 35.94 35.39 35.13 34.90 34.72 . . . Use the qualifier /DEPTH= when defining the Z axis to indicate positive downward, and /ORDER when setting the data set to properly read in the permuted data: yes? DEFINE AXIS/X=30W:25W:1/UNIT=degrees salx yes? DEFINE AXIS/Y=5S:5N:1/UNIT=degrees saly yes? DEFINE AXIS/Z=0:1000:100/UNIT=meters/DEPTH salz yes? DEFINE GRID/X=salx/Y=saly/Z=salz salgrid yes? FILE/ORDER=zxy/GRID=salgrid/VAR=sal/COL=11 sal.dat *** 6 TRICKS TO READING BINARY AND ASCII FILES *** Since binary and ASCII files are found in a bewildering variety of non-standardized formats a few tricks may help with reading difficult cases. Sometimes variables are interleaved with data axes in unstructured (stream) binary files. A simple trick is to read them all as a single variable, say, "Vall," in which the sequence of variables in the file V1, V2, V3, ... is regarded as an axis of the grid. Then extract the variables by defining V1 = Vall[I=1] (if the I axis was used, else J=1, K=1, or L=1) as needed. In some ASCII files the variables are presented as blocks -- a full grid of variable 1, then a full grid of variable 2, etc. These files may be read using Unix soft links so that the same file can be opened as several Ferret data sets. Then use the FILE command to point separately to each soft link using the /SKIP qualifier to locate the correct starting point in the file for each variable. For example, Unix commands: ln -s my_dat.v1 my_data ln -s my_dat.v2 my_data ln -s my_dat.v3 my_data Ferret commands: yes? FILE/SKIP=0/VAR=v1 my_dat.v1 yes? FILE/SKIP=100/VAR=v2 my_dat.v2 yes? FILE/SKIP=200/VAR=v3 my_dat.v3 If an ASCII file contains a repeating sequence of records try describing the entire sequence using a single FORTRAN FORMAT statement. An example of such a statement would be (3F8.4,2(/5F6.2)). The slash character and the nested parentheses allow multi-record groups to appear as a single format. Note that the /COLUMNS qualifier should reflect the total number of columns in the repeating group of records. If an ASCII or binary file contains gridded data in which the order of axes is not X-Y-Z-T read the data in (which results in the wrong axis ordering) and use the LIST/ORDER= to permute the order on output. The resulting file will have the desired axis ordering. If the times and geographical coordinate locations of the grid are inter-mixed with the dependent variables in the file then 1) issue a FILE command to read the coordinates only; 2) use DEFINE AXIS/FROM_DATA to define axes and DEFINE GRID to define the grid; 3) use FILE/GRID=mygrid to read the file again. *** Chapter 3: VARIABLES AND EXPRESSIONS *** *** 1 VARIABLES *** Variables are of 3 kinds: 1) file variables (read from disk files) 2) user-defined variables (defined by the user with LET command) 3) diagnostic variables (for GFDL/MOM Pacific ocean model runs) All 3 types may be accessed identically in all commands and expressions. All variables, regardless of kind, possess the following associated information: 1) grid the -- underlying coordinate structure 2) units 3) title 4) title modifier (additional explanation of variable) 5) flag value for missing data points Use the commands SHOW DATA, SHOW VARIABLES and SHOW VARIABLES/ DIAGNOSTIC to examine the available variables of each type, respectively. The pseudo-variables I, J, K, L, X, Y, Z, T and others may be used to refer to the underlying grid locations and characteristics and to create abstract variables. *** 1.1 Variable syntax *** Variables in Ferret are referred to by names with optional qualifying information appended in square brackets. See DEFINE VARIABLE for a discussion of legal variable names. The information that may be included in the square brackets includes D=data_set_name_or_number ! indicate the data set G=grid_or_variable_name ! request a regridding X=,Y=,Z=,T=,I=,J=,K=,L= ! specify region and transformation See Chapter 4 on Regions for more discussion of the syntax of region qualifiers and transformations. Some examples of valid variable syntax are myvar ! data set and region as per current context myvar[D=2] ! myvar from data set number 2 (see SHOW DATA) myvar[D=a_dset] ! myvar from data set a_dset.cdf or a_dset.des myvar[D=myfile.txt] ! myvar from file myfile.txt myvar[G=gridname] ! myvar regridded to grid gridname myvar[G=var2] ! myvar regridded to the grid of var2 ! which is in the same data set as myvar myvar[G=var2[D=2]] ! myvar regridded to the grid of var2 ! which is in data set number 2 myvar[GX=axisname] ! myvar regridded to a dynamic grid which ! has X axis axisname myvar[GX=var2] ! myvar regridded to a dynamic grid which ! has the X axis of variable var2 *** 1.2 File variables *** File variables are stored in disk files. Input data files can be ASCII, binary, NetCDF, or TMAP-formatted (see Chapter 2, Data Sets). File variables are made available with the SET DATA command. *** 1.3 Pseudo-variables *** Pseudo-variables are variables whose values are coordinates or coordinate information from a grid. Valid pseudo-variables are X - x axis coordinates I - x axis subscripts XBOX - size of x grid box Y - y axis coordinates J - y axis subscripts YBOX - size of y grid box Z - z axis coordinates K - z axis subscripts ZBOX - size of z grid box T - t axis coordinates L - t axis subscripts TBOX - size of t grid box A grid box is a concept needed for some transformations along an axis; it is the length along an axis that belongs to a single grid point and functions as a weighting factor during integrations and averaging transformations. The pseudo-variables I, J, K, and L are subscripts; that is, they are a coordinate system for referring to grid locations in which the points along an axis are regarded as integers from 1 to the number of points on the axis. This is clear if you look at one of the sample data sets: yes? SET DATA levitus_climatology yes? SHOW DATA 1> /home/e1/tmap/fer_dsets/descr/levitus_climatology.des (default) Levitus annual climatology (1x1 degree) diagnostic variables: NOT available name title I J K L TEMP TEMPERATURE 1:360 1:180 1:20 1:1 ... on grid GLEVITR1 X=20E:20E(380) Y=90S:90N Z=0m:5000m SALT SALINITY 1:360 1:180 1:20 1:1 ... on grid GLEVITR1 X=20E:20E(380) Y=90S:90N Z=0m:5000m time-independent data file: levitus_climatology.001 We see that there are 20 points along the z-axis (1:20 under K), for example, and that the z-axis coordinate values range from 0 meters to 5000 meters. Pseudo-variables depend only on the underlying grid, and not on the variables (in this case, temperature and salt). Examples: Pseudo-variables 1) yes? LIST/I=1:10 I 2) yes? LET xflux = u * vbox[G=u] *** 1.4 User-defined variables *** New variables can be defined from existing variables and from abstract mathematical quantities (such as COS(latitude)) with command DEFINE VARIABLE (alias LET). See command DEFINE VARIABLE and command LET in the Commands Reference. Examples: User-defined variables 1) yes? LET/TITLE="Surface Relief x1000 (meters)" r1000=rose/1000 2) yes? LET/TITLE="Temperature Deviation" tdev=temp - temp[Z=@ave] *** 1.5 Abstract variables *** Ferret can be used to manipulate abstract mathematical quantities such as SIN(x) or EXP(k*t) -- quantities that are independent of file variable values. Such quantities are referred to as abstract expressions. Example: Abstract variables Contour the function COS(a*Y)/EXP(b*T) where a=0.25 and b=-0.02 over the range Y=0:45 (degrees) and T=1:100 (hours) with a resolution of 0.5 degree on the Y axis and 2 hours on the T axis. Quick and dirty solution: yes? CONTOUR COS(0.25*Y[Y=0:45:0.5])/EXP(-0.2*T[T=1:100:2]) Nicer (Figure 7; plot is documented with correct units and titles): yes? DEFINE AXIS/Y=0:45:0.5 /UNIT=DEGREES yax yes? DEFINE AXIS/T=1:100:2 /UNIT=HOURS tax yes? DEFINE GRID/T=tax/Y=yax my_grid yes? SET GRID my_grid yes? LET a=0.25 yes? LET b=-0.02 yes? CONTOUR/COS(a*Y)/EXP(b*T) See Chapter 4, section "Grids," for more information on grids. *** 1.6 Missing value flags *** Data values that are absent or undefined for mathematical reasons (e.g., 1/0) will be represented in Ferret with a missing value flag. In SHADE outputs a missing value flag embedded at some point in a variable will result in a transparent rectangular hole equal to the size of the grid cell of the missing value. In a CONTOUR or FILL plot it will result in a larger hole -- extending past the grid box edge to the coordinate location of the next adjacent non-missing point -- since contour lines cannot be interpolated between a missing value and its neighboring points. In the output of the LIST command for cases where the /FORMAT qualifier is not used the missing value will be represented by 4 dots ("...."). For cases where LIST/FORMAT=FORTRAN-format is used the numerical value of the missing value flag will be printed using the format provided. *** 1.6.1 Missing values in input files *** Ferret does not impose a standard for missing value flags in input data sets; each variable in each data set may have its own distinct missing value flag(s). The flag(s) actually in use by a data set may be viewed with the SHOW DATA/VARIABLES command. If no missing value flag is specified for a data set Ferret will assume a default value of -1.E+34. For EZ input data sets, either binary or ASCII, the missing data flag may be specified with the SET VARIABLE/BAD= command. A different value may be specified for each variable in the data set. For NetCDF input data sets the missing value flag(s) is indicated by the values of the attributes "missing_value" and "_FillValue." If both attributes are defined to have different values both will be recognized and used by Ferret as missing value indicators, however the occurrences of _FillValue will be replaced with the value of missing_value as the data are read into Ferret's memory cache so that only a single missing value flag is apparent inside of Ferret. The command SET VARIABLE/BAD= can also be applied to NetCDF variables, thereby temporarily setting a user-imposed value for _FillValue. *** 1.6.2 Missing values in user-defined variables *** User-defined variables may in general be defined as expressions involving multiple variables. The component variables need not in general agree in their choice of missing value flags. The result variable will inherit the bad value flag of the first variable in the expression. If the first component in the expression is a constant or a pseudo-variable, then Ferret imposes its default missing value flag of -1.E+34. The function MISSING(variable,replacement) provides a limited control over the choice of missing values in user-defined variables. Note, however, that while the MISSING function will replace the missing values with other values it will not change the missing value flag. In other words, the replacement values will no longer be regarded as missing. *** 1.6.3 Missing values in output NetCDF files *** Values flagged as missing inside Ferret will be faithfully transferred to output files -- no substitution will occur as the data are written. In the case of NetCDF output files both of the attributes missing_value, and _FillValue will be set equal to the missing value flag. Under some circumstances it is desirable to save a user-defined variable in a NetCDF file and then to redefine that variable and to append further output. (An example of this is the process of consolidating several files of input, say, moored measurements, into a gridded output.) The process of appending will not change any of the NetCDF attributes -- neither long_name (title), units, nor missing_value or _FillValue. If the subsequent variable definitions do not agree in their choice of missing value flags the resulting output may contain multiple missing value flags that will not be properly documented. An easy "trick" that avoids this situation is to begin all of the variable definitions with an addition of zero, "LET var = 0 + ...." The addition of zero will not affect the value of the output but it will guarantee that a missing value flag of -1.E+34 will be consistently used. Of course, you will want to use the SET VARIABLE/TITLE= command in conjunction with this approach. *** 1.6.4 Displaying the missing value flag *** If the LIST command is used, missing values are, by default, displayed as "...." To examine the flag as a numerical value, use LIST/FORMAT=(E) (or some other suitable format). *** 2 EXPRESSIONS *** Throughout this manual, Ferret commands that require and manipulate data are informally called "action" commands. These commands are: PLOT CONTOUR FILL (alias for CONTOUR/FILL) SHADE VECTOR WIRE LIST STAT LOAD Action commands may use any valid algebraic expression involving constants, operators (+,-,*,...), functions (SIN, MIN, INT,...), pseudo-variables (X, TBOX, ...) and other variables. A variable name may optionally be followed by square brackets containing region, transformation, data set, and regridding qualifiers. For example, "temp", "salt[D=2]", "u[G=temp"], "u[Z=0:200@AVE]". The expressions may also contain a syntax of: IF condition THEN expression_1 ELSE expression_2 Examples: Expressions i) temp ^ 2 temperature squared ii) temp - temp[Z=@AVE] for the range of Z in the current context, the temperature deviations from the vertical average iii) COS(Y) the cosine of the Y coordinate of the underlying grid (by default, the y-axis is implied by the other variables in the expression) iv) IF (vwnd GT vwnd[D=monthly_navy_winds]) THEN vwnd ELSE 0 use the meridional velocity from the current data set wherever it exceeds the value in data set monthly_navy_winds, zero elsewhere. *** 2.1 Operators *** Valid operators are + - * / ^ (exponentiate) AND OR GT GE LT LE EQ NE *** 2.2 Multi-dimensional expressions *** Operators and functions (discussed in the next section, Functions) may combine variables of like dimensions or differing dimensions. If the variables are of like dimension then the result of the combination is of the same dimensionality as inputs. For example, suppose there are two time series that have data on the same time axis; the result of a combination will be a time series on the same time axis. If the variables are of unlike dimensionality, then the following rules apply: 1) To combine variables together in an expression they must be "conformable" along each axis. 2) Two variables are conformable along an axis if the number of points along the axis is the same, or if one of the variables has only a single point along the axis (or, equivalently, is normal to the axis). 3) When a variable of size 1 (a single point) is combined with a variable of larger size, the variable of size 1 is "promoted" by replicating its value to the size of the other variable. 4) If variables are the same size but have different coordinates, they are conformable, but Ferret will issue a message that the coordinates on the axis are ambiguous. The result of the combination inherits the coordinates of the FIRST variable encountered that has more than a single point on the axis. Examples: Assume a region J=50/K=1/L=1 for examples 1 and 2. Further assume that variables v1 and v2 share the same x-axis. 1) yes? LET newv = v1[I=1:10] + v2[I=1:10] !same dimension (10) 2) yes? LET newv = v1[I=1:10] + v2[I=5] !newv has length of v1 (10) 3) We want to compare the salt values during the first half of the year with the values for the second half. Salt_diff will be placed on the time coordinates of the first variable -- L=1:6. Ferret will issue a warning about ambiguous coordinates. yes? LET salt_diff = salt[L=1:6] - salt[L=7:12] 4) In this example the variable zero will be promoted along each axis. yes? LET zero = 0 * (i+j) yes? LIST/I=1:5/J=1:5 zero !5X5 matrix of 0's 5) Here we calculate density; salt and temp are on the same grid. This expression is an XYZ volume of points (100 100 10) of density at 10 depths based on temperature and salinity values at the top layer (K=1). yes? SET REGION/I=1:100/J=1:100 yes? LET dens = rho_un (temp[K=1], salt[K=1], Z[G=temp,K=1:10] *** 2.3 Functions *** Valid functions are Name #Args Description MAX 2 Compares two fields and selects the point by point maximum. MAX( temp[K=1], temp[K=2] ) returns the maximum temperature comparing the first 2 z-axis levels MIN 2 Compares two fields and selects the point by point minimum. MIN( airt[L=10], airt[L=9] ) gives the minimum air temperature comparing two timesteps INT 1 Truncates values to integers. INT( salt ) returns the integer portion of variable "salt" for all values in the current region ABS 1 Absolute value. ABS( U ) takes the absolute value of U for all points within the current region EXP 1 eX -- Exponential; argument is real. EXP( X ) raises e to the power X for all points within the current region LN 1 logeX -- Natural logarithm; argument is real. LN( X ) takes the natural logarithm of X for all points within the current region LOG 1 log10X -- Common logarithm; argument is real. LOG( X ) takes the common logarithm of X for all points within the current region SIN 1 Trigonometric sine; argument is in radians and is treated modulo 2*pi. SIN( X ) computes the sine of X for all points within the current region COS 1 Trigonometric cosine; argument is in radians and is treated modulo 2*pi. COS( Y ) computes the cosine of Y for all points within the current region TAN 1 Trigonometric tangent; argument is in radians and is treated modulo 2*pi. TAN( theta ) computes the tangent of theta for all points within the current region ASIN 1 Trigonometric arcsine (-pi/2,pi/2). The result will be flagged as missing if the absolute value of the argument is greater than 1; result is in radians. ASIN( value ) computes the arcsine of "value" for all points within the current region ACOS 1 Trigonometric arccosine (0,pi). The result will be flagged as missing of the absolute value of the argument greater than 1; result is in radians. ACOS ( value ) computes the arccosine of "value" for all points within the current region ATAN 1 Trigonometric arctangent (-pi/2,pi/2); result is in radians. ATAN( value ) computes the arctangent of "value" for all points within the current region ATAN2 2 2-argument trigonometric arctangent of Y/X (-pi,pi); discontinuous at Y=0. ATAN2( X,Y ) computes the 2-argument arctangent of Y/X for all points within the current region MOD 2 Modulo operation ( arg1 - arg2*[arg1/arg2] ). Returns the remainder when the first argument is divided by the second. MOD( X,2 ) computes the remainder of X/2 for all points within the current region DAYS1900 3 DAYS1900(year,month,day) computes the number of days since 1 Jan 1900. This function is useful in converting dates to Julian days. MISSING 2 Replaces missing values in the first argument (multi- dimensional variable) with the second argument; the second argument may be any conformable variable. MISSING( temp, -999 ) replaces missing values in temp with -999 MISSING( sst, temp[D=coads_climatology] ) replaces missing sst values with temperature from the COADS climatology IGNORE0 1 Replaces zeros in a variable with the missing value flag for that variable. IGNORE0( salt ) replaces zeros in salt with the missing value flag RANDU 1 Generates a grid of uniformly distributed [0,1] pseudo- random values. The first valid value in the field is used as the random number seed. Values that are flagged as bad remain flagged as bad in the random number field. RANDU( temp[I=105:135,K=1:5] ) generates a field of uniformly distributed random values of the same size and shape as the field "temp[I=105:135,K=1:5]" using temp[I=105,k=1] as the pseudo-random number seed. RANDN 1 Generates a grid of normally distributed pseudo-random values. As above, but normally distributed rather than uniformly distributed. RHO_UN 3 Calculates rho (density kg/m^3) from salt (psu), temperature (deg C) and pressure (decibars) using the 1980 UNESCO International Equation of State (IES80). The routine uses the high pressure equation of state from Millero et al. (1980) and the one-atmosphere equation of state from Millero and Poisson (1981) as reported in Gill (1982). The notation follows Millero et al. (1980) and Millero and Poisson (1981). RHO_UN( salt, temp, Z ) THETA_FO 4 Calculates local potential temperature field at salt (psu), temperature (deg C), pressure (decibars) and specified reference pressure. This calculation uses Bryden (1973) polynomial for adiabatic lapse rate and Runge-Kutta 4th order integration algorithm. References: Bryden, H., 1973, Deep-Sea Res., 20, 401-408 Fofonoff, N.M, 1977, Deep-Sea Res., 24, 489-491. THETA_FO( salt, temp, Z, Z_reference ) *** 2.4 Transformations *** Transformations (e.g., averaging, integrating, etc.) may be specified along the axes of a variable. Some transformations (e.g., averaging) reduce a range of data to a point; others (e.g., differentiating) retain the range. When transformations are specified along more than one axis of a single variable the order of execution is X axis first, then Y then Z then T. Example syntax: TEMP[Z=0:100@LOC:20] (depth at which temp has value 20) Valid transformations are Default Transform Argument Description @DIN definite integral (weighted sum) @IIN indefinite integral (weighted running sum) @AVE average @VAR unweighted variance @MIN minimum @MAX maximum @SHF 1 pt shift @SBX 3 pt boxcar smoothed @SBN 3 pt binomial smoothed @SHN 3 pt Hanning smoothed @SPZ 3 pt Parzen smoothed @SWL 3 pt Welch smoothed @DDC centered derivative @DDF forward derivative @DDB backward derivative @NGD number of valid points @NBD number of bad (invalid) points flagged @SUM unweighted sum @RSUM running unweighted sum @FAV 3 pt fill missing values with average @FLN:n 1 pt fill missing values by linear interpolation @FNR:n 1 pt fill missing values with nearest point @LOC 0 coordinate of ... (e.g., depth of 20 degrees) @WEQ "weighted equal" (integrating kernel) The command SHOW TRANSFORM will produce a list of currently available transformations. Examples: Transformations u[Z=0:100@AVE] - average of u between 0 and 100 in Z sst[T=@SBX:10] - box-car smooths sst with a 10 time point filter tau[L=1:25@DDC] - centered time derivative of tau v[L=@IIN] - indefinite (accumulated) integral of v qflux[X=@AVE,Y=@AVE] - XY area-averaged qflux *** 2.4.1 General information about transformations *** Transformations are normally computed axis by axis; if multiple axes have transformations specified simultaneously (e.g., U[Z=@AVE,L=@SBX:10]) the transformations will be applied sequentially in the order X then Y then Z then T. There are two exceptions to this: if @DIN is applied simultaneously to both the X and Y axes (in units of degrees of longitude and latitude, respectively) the calculation will be carried out on a per-unit-area basis (as a true double integral) instead of a per-unit-length basis, sequentially. This ensures that the COSINE(latitude) factors will be applied correctly. The same applies to @AVE simultaneously on X and Y. Data that are flagged as invalid are excluded from calculations. When calculating integrals and derivatives (@IIN, @DIN, @DDC, @DDF, and @DDB) Ferret attempts to use standardized units for the grid coordinates. If the underlying axis is in a known unit of length Ferret converts grid box lengths to meters. If the underlying axis is in a known unit of time Ferret converts grid box lengths to seconds. If the underlying axis is degrees of longitude a factor of COSINE (latitude) is applied to the grid box lengths in meters. If the underlying axis units are unknown Ferret uses those unknown units for the grid box lengths. (If Ferret does not recognize the units of an axis it displays a message to that effect when the DEFINE AXIS or SET DATA command defines the axis.) See command DEFINE AXIS/UNITS in the Commands Reference in this manual for a list of recognized units. All integrations and averaging are accomplished by multiplying the width of each grid box by the value of the variable in that grid box -- then summing and dividing as appropriate for the particular transformation. If integration or averaging limits are given as world coordinates, the grid boxes at the edges of the region specified are weighted according to the fraction of grid box that actually lies within the specified region. If the transformation limits are given as subscripts, the full box size of each grid point along the axis is used -- including the first and last subscript given. The region information that is listed with the output reflects this. Some transformations (derivatives, shifts, smoothers) require data points from beyond the edges of the indicated region in order to perform the calculation. Ferret automatically accesses this data as needed. It flags edge points as missing values if the required beyond-edge points are unavailable (e.g., @DDC applied on the X axis at I=1). *** 2.4.2 Transformations applied to irregular regions *** Since transformations are applied along the orthogonal axes of a grid they lend themselves naturally to application over "rectangular" regions (possibly in 3 or 4 dimensions). Ferret has sufficient flexibility, however, to perform transformations over irregular regions. Suppose, for example, that we wish to determine the average wind speed within an irregularly shaped region of the globe defined by a threshhold sea surface temperature value. We can do this through the creation of a mask, as in this example: yes? SET DATA coads_climatology yes? SET REGION/l=1/@t ! January in the Tropical Pacific yes? LET sst28_mask = IF sst GT 28 THEN 1 yes? LET masked_wind_speed = wspd * sst28_mask yes? LIST masked_wind_speed[X=@AVE,Y=@AVE] The variable sst28_mask is a collection of 1's and missing values. Using it as a multiplier on the wind speed field produces a new result that is undefined except in the domain of interest. When using masking be aware of these considerations: Use undefined values rather than zero's to avoid contaminating the calculation with zero values. The masked region is composed of rectangles at the level of resolution of the gridded variables; the mask does NOT follow smooth contour lines. To obtain a smoother mask it may be desirable to regrid the calculation to a finer grid. Variables from different data sets can be used to mask one another. For example, the ETOPO60 bathymetry data set can be used to mask regions of land and sea. *** 2.4.3 General information about smoothing transformations *** Ferret provides several transformations for smoothing variables (removing high frequency variability). These transformations replace each value on the grid to which they are applied with a weighted average of the surrounding data values along the axis specified. For example, the expression u[T=@SPZ:3] replaces the value at each (I,J,K,L) grid point of the variable "u" with the weighted average u at t = 0.25*(u at t-1) + 0.5*(u at t) + 0.25*(u at t+1) The various choices of smoothing transformations (@SBX, @SBN, @SPZ, @SHN, @SWL) represent different shapes of weighting functions or "windows" with which the original variable is convolved. New window functions can be obtained by nesting the simple ones provided. For example, using the definitions yes? LET ubox = u[L=@SBX:15] yes? LET utaper = ubox[L=@SHN:7] produces a 21-point window whose shape is a boxcar (constant weight) with COSINE (Hanning) tapers at each end. Ferret may be used to directly examine the shape of any smoothing window: Mathematically, the shape of the smoothing window can be recovered as a variable by convolving it with a delta function. In the example below we examine (PLOT) the shape of a 15-point Welch window (Figure 8). ! define X axis as [-1,1] by 0.2 yes? GO unit_square yes? SET REGION/X=-1:1 yes? LET delta = IF X EQ 0 THEN 1 ELSE 0 ! convolve delta with Welch window yes? PLOT delta[I=@SWL:15] *** 2.4.4 @DIN -- definite integral *** The transformation @DIN computes the definite integral -- a single value that is the integral between two points along an axis (compare with @IIN). It is obtained as the sum of the grid_box*variable product at each grid point. Grid points at the ends of the indicated range are weighted by the fraction of the grid box that falls within the integration interval. If @DIN is specified simultaneously on multiple axes the calculation will be performed as a multiple integration rather than as sequential single integrations. The output will document this fact by indicating a transformation of "@IN4" or "XY integ." Example: yes? CONTOUR/X=160E:160W/Y=5S:5N u[Z=0:50@DIN] In a latitude/longitude coordinate system X=@DIN is sensitive to the COS(latitude) correction. *** 2.4.5 @IIN -- indefinite integral *** The transformation @IIN computes the indefinite integral -- at each subscript of the result it is the value of the integral from the start value to the upper edge of that grid box. It is obtained as a running sum of the grid_box*variable product at each grid point. Grid points at the ends of the indicated range are weighted by the fraction of the grid box that falls within the integration interval. Example: yes? CONTOUR/X=160E:160W/Z=0 u[Y=5S:5N@IIN] Note 1: The indefinite integral is always computed in the increasing coordinate direction. To compute the indefinite integral in the reverse direction use LET reverse_integral = my_var[Y=lo:hi@DIN] - my_var[X=lo:hi@IIN] Note 2: In a latitude/longitude coordinate system X=@IIN is sensitive to the COS(latitude) correction. Note 3: The result of the indefinte integral is shifted by 1/2 of a grid cell from its "proper" location. This is because the result at each grid cell includes the integral computed to the upper end of that cell. (This was necessary in order that var[I=lo:hi@DIN] and var[I=lo:hi@IIN] produce consistent results.) To illustrate, consider these commands yes? LET one = x-x+1 yes? LIST/I=1:3 one[I=@din] X-X+1 X: 0.5 to 3.5 (integrated) 3.000 yes? LIST/I=1:3 one[I=@iin] X-X+1 indef. integ. on X 1 / 1: 1.000 2 / 2: 2.000 3 / 3: 3.000 The grid cell at I=1 extends from 0.5 to 1.5. The value of the integral at 1.5 is 1.000 as reported but the coordinate listed for this value is 1 rather than 1.5. Two methods are available to correct for this 1/2 grid cell shift. Method 1: correct the result by subtracting the 1/2 grid cell error yes? LIST/I=1:3 one[I=@iin] - one/2 ONE[I=@IIN] - ONE/2 1 / 1: 0.500 2 / 2: 1.500 3 / 3: 2.500 Method 2: correct the coordinates by shifting the axis 1/2 of a grid cell yes? DEFINE AXIS/X=1.5:3.5:1 xshift yes? LET SHIFTED_INTEGRAL = one[I=@IIN] yes? LET corrected_integral = shifted_integral[GX=xshift@ASN] yes? LIST/I=1:3 corrected_integral SHIFTED_INTEGRAL[GX=XSHIFT@ASN] 1.5 / 1: 1.000 2.5 / 2: 2.000 3.5 / 3: 3.000 *** 2.4.6 @AVE -- average *** The transformation @AVE computes the average weighted by grid box size -- a single number representing the average of the variable between two endpoints. If @AVE is specified simultaneously on multiple axes the calculation will be performed as a multiple integration rather than as sequential single integrations. The output will document this fact by showing @AV4 or "XY ave" as the transformation. Example: yes? CONTOUR/X=160E:160W/Y=5S:5N u[Z=0:50@AVE] Note that the unweighted mean can be calculated using the @SUM and @NGD transformations. *** 2.4.7 @VAR -- weighted variance *** The transformation @VAR computes the weighted variance of the variable with respect to the indicated region (ref. Numerical Recipes, The Art of Scientific Computing, by William H. Press et al., 1986). As with @AVE, if @VAR is applied simultaneously to multiple axes the calculation is performed as the variance of a block of data rather than as nested 1-dimensional variances. *** 2.4.8 MIN -- minimum *** The transformation @MIN finds the minimum value of the variable within the specified axis range. Example: For fixed Z and Y yes? PLOT/T="1-JAN-1982":"1-JAN-1983" temp[X=160E:160W@MIN] plots a time series of the minimum temperature found between longitudes 160 east and 160 west. *** 2.4.9 @MAX -- maximum *** The transformation @MAX finds the maximum value of the variable within the specified axis range. See also @MIN. *** 2.4.10 @SHF:n -- shift *** The transformation @SHF shifts the data up or down in subscript by the number of points given as the argument. Examples: u[L=@SHF:2] associates the value of U[L=3] with the subscript L=1. u[L=@SHF:1]-U gives the forward difference of the variable U along the L axis. *** 2.4.11 @SBX:n -- boxcar smoother *** The transformation @SBX applies a boxcar window (running mean) to smooth the variable along the indicated axis. The width of the boxcar is the number of points given as an argument to the transformation. All points are weighted equally, regardless of the sizes of the grid boxes, making this transformation best suited to axes with equally spaced points. If the number of points specified is even, however, @SBX weights the end points of the boxcar smoother as 1/2. Example: yes? PLOT/X=160W/Y=0 u[L=1:120@SBX:5] The transformation @SBX does not reduce the number of points along the axis; it replaces each of the original values with the average of its surrounding points. Regridding can be used to reduce the number of points. *** 2.4.12 @SBN:n -- binomial smoother *** The transformation @SBN applies a binomial window to smooth the variable along the indicated axis. The width of the smoother is the number of points given as an argument to the transformation. The weights are applied without regard to the widths of the grid boxes, making this transformation best suited to axes with equally spaced points. Example: yes? PLOT/X=160W/Y=0/Z=0 u[L=1:120@SBN:15] The transformation @SBN does not reduce the number of points along the axis; it replaces each of the original values with a weighted sum of its surrounding points. Regridding can be used to reduce the number of points. The argument specified with @SBN, the number of points in the smoothing window, must be an odd value; an even value would result in an effective shift of the data along its axis. *** 2.4.13 @SHN:n -- Hanning smoother *** Transformation @SHN applies a Hanning window to smooth the variable along the indicated axis (ref. Numerical Recipes, The Art of Scientific Computing, by William H. Press et al., 1986). In other respects it is identical in function to the @SBN transformation. Note that the Hanning window used by Ferret contains only non-zero weight values with the window width. Some interpretations of this window function include zero weights at the end points. Use an argument of N-2 to achieve this effect (e.g., @SBX:5 is equivalent to a 7-point Hanning window which has zeros as it first and last weights). *** 2.4.14 @SPZ:n -- Parzen smoother *** Transformation @SPZ applies a Parzen window to smooth the variable along the indicated axis (ref. Numerical Recipes, The Art of Scientific Computing, by William H. Press et al., 1986). In other respects it is identical in function to the @SBN transformation. *** 2.4.15 @SWL:n -- Welch smoother *** Transformation @SWL applies a Welch window to smooth the variable along the indicated axis (ref. Numerical Recipes, The Art of Scientific Computing, by William H. Press et al., 1986). In other respects it is identical in function to the @SBN transformation. *** 2.4.16 @DDC -- centered derivative *** The transformation @DDC computes the derivative with respect to the indicated axis using a centered differencing scheme. The units of the underlying axis are treated as they are with integrations. If the points of the axis are unequally spaced, note that the calculation used is still (Fi+1 - Fi-1) / (Xi+1 - Xi-1) . Example: yes? PLOT/X=160W/Y=0/Z=0 u[L=1:120@DDC] *** 2.4.17 @DDF -- forward derivative *** The transformation @DDF computes the derivative with respect to the indicated axis. A forward differencing scheme is used. The units of the underlying axis are treated as they are with integrations. Example: yes? PLOT/X=160W/Y=0/Z=0 u[L=1:120@DDF] *** 2.4.18 @DDB -- backward derivative *** The transformation @DDF computes the derivative with respect to the indicated axis. A backward differencing scheme is used. The units of the underlying axis are treated as they are with integrations. Example: yes? PLOT/X=160W/Y=0/Z=0 u[L=1:120@DDB] *** 2.4.19 @NGD -- number of good points *** The transformation @NGD computes the number of good (valid) points of the variable with respect to the indicated axis. Use @NGD in combination with @SUM to determine the number of good points in a multi-dimensional region. Note that, as with @VAR, when @NGD is applied simultaneously to multiple axes the calculation is applied to the entire block of values rather than to the individual axes. *** 2.4.20 @NBD -- number of bad points *** The transformation @NBD computes the number of bad (invalid) points of the variable with respect to the indicated axis. Use @NBD in combination with @SUM to determine the number of bad points in a multi-dimensional region. Note that, as with @VAR, when @NBD is applied simultaneously to multiple axes the calculation is applied to the entire block of values rather than to the individual axes. *** 2.4.21 @SUM -- unweighted sum *** The transformation @SUM computes the unweighted sum (arithmetic sum) of the variable with respect to the indicated axis. This transformation is most appropriate for regions specified by subscript. If the region is specified in world coordinates, the edge points are not weighted -- they are wholly included in or excluded from the calculation, depending on the location of the grid points with respect to the specified limits. *** 2.4.22 @RSUM -- running unweighted sum *** The transformation @RSUM computes the running unweighted sum of the variable with respect to the indicated axis. @RSUM is to @IIN as @SUM is to @DIN. The treatment of edge points is identical to @SUM. *** 2.4.23 @FAV:n -- averaging filler *** The transformation @FAV fills holes (values flagged as invalid) in variables with the average value of the surrounding grid points along the indicated axis. The width of the averaging window is the number of points given as an argument to the transformation. All of the surrounding points are weighted equally, regardless of the sizes of the grid boxes, making this transformation best suited to axes with equally spaced points. If the number of points specified is even, however, @FAV weights the end points of the filling region by 1/2. If any of the surrounding points are invalid they are omitted from the calculation. If all of the surrounding points are invalid the hole is not filled. Example: yes? CONTOUR/X=160W:160E/Y=5S:0 u[X=@FAV:5] *** 2.4.24 @FLN:n -- linear interpolation filler *** The transformation @FLN:n fills holes in variables with a linear interpolation from the nearest non-missing surrounding point. n specifies the number of points beyond the edge of the indicated axis limits to include in the search for interpolants (default n = 1). Unlike @FAV, @FLN is sensitive to unevenly spaced points and computes its linear interpolation based on the world coordinate locations of grid points. *** 2.4.25 @FNR:n -- nearest neighbor filler *** The transformation @FNR:n is similar to @FLN:n, except that it replicates the nearest point to the missing value. In the case of points being equally spaced around the missing point, the mean value is used. *** 2.4.26 @LOC -- location of *** The transformation @LOC accepts an argument value -- the default value is zero if no argument is specified. The transformation @LOC finds the single location at which the variable first assumes the value of the argument. The result is in units of the underlying axis. Linear interpolation is used to compute locations between grid points. If the variable does not assume the value of the argument within the specified region the @LOC transformation returns an invalid data flag. For example, temp[Z=0:200@LOC:18] finds the location along the Z axis (often depth in meters) at which the variable "temp" (often temperature) first assumes the value 18, starting at Z=0 and searching to Z=200. yes? CONTOUR/X=160E:160W/Y=10S:10N temp[Z=0:200@LOC:18] produces a map of the depth of the 18-degree isotherm. See also the General Information section in this chapter. Note that the transformation @LOC can be used to locate non-constant values, too, as the following example illustrates: Example: locating non-constant values Determine the depth of maximum salinity. yes? LET max_salt = salt[Z=@MAX] yes? LET zero_at_max = salt - max_salt yes? LET depth_of_max = zero_at_max[Z=@LOC:0] *** 2.4.27 @WEQ -- weighted equal; integration kernel *** The @WEQ ("weighted equal") transformation is the subtlest and arguably the most powerful transformation within Ferret. It is a generalized version of @LOC; @LOC always determines the value of the axis coordinate (the variable X, Y, Z, or T) at the points where the gridded field has a particular value. More generally, @WEQ can be used to determine the value of any variable at those points. Like @LOC, the transformation @WEQ finds the location along a given axis at which the variable is equal to the given (or default) argument. For example, V1[Z=@WEQ:5] finds the Z locations at which V1 equals "5". But whereas @LOC returns a single value (the linearly interpolated axis coordinate values at the locations of equality) @WEQ returns instead a field of the same size as the original variable. For those two grid points that immediately bracket the location of the argument, @WEQ returns interpolation coefficients. For all other points it returns missing value flags. If the value is found to lie identically on top of a grid point an interpolation coefficient of 1 is returned for that point alone. Example 1 yes? LET v1 = X/4 yes? LIST/X=1:6 v1, v1[X=@WEQ:1], v1[X=@WEQ:1.2] X v1 @WEQ:1 @WEQ:1.2 - ----- ----- ----- 1: 0.250 .... .... 2: 0.500 .... .... 3: 0.750 .... .... 4: 1.000 1.000 0.2000 5: 1.250 .... 0.8000 6: 1.500 .... .... The resulting field can be used as an "integrating kernel," a weighting function that when multiplied by another field and integrated will give the value of that new field at the desired location. Example 2 Using variable v1 from the previous example, suppose we wish to know the value of the function X^2 (X squared) at the location where variable v1 has the value 1.2. We can determine it as follows: yes? LET x_squared = X^2 yes? LET integrand = x_squared * v1[X=@WEQ:1.2] yes? LIST/X=1:6 integrand[X=@SUM] !Ferret output below X_SQUARED * V1[X=@WEQ:1.2] X: 1 to 6 (summed) 23.20 Notice that 23.20 = 0.8 * (5^2) + 0.2 * (4^2) Below are two "real world" examples which produce fully labeled plots. Example 3: salinity on an isotherm Use the Levitus climatology to contour the salinity of the Pacific Ocean along the 20-degree isotherm (Figure 9). yes? SET DATA levitus_climatology ! annual sub-surface climatology yes? SET REGION/X=100E:50W/Y=45S:45N ! Pacific Ocean yes? LET isotherm_20 = temp[Z=@WEQ:20] ! depth kernel for 20 degrees yes? LET integrand_20 = salt * isotherm_20 yes? SET VARIABLE/TITLE="Salinity on the 20 degree isotherm" integrand_20 yes? PPL CONSET .12 !contour label size (def. .08) yes? CONTOUR/LEV=(33,37,.2) integrand_20[Z=@SUM] yes? GO fland !continental fill Example 4: month with warmest sea surface temperatures Use the COADS data set to determine the month in which the SST is warmest across the Pacific Ocean. In this example we use the same principles as above to create an integrating kernel on the time axis. Using this kernel we determine the value of the time step index (which is also the month number, 1- 12) at the time of maximum SST (Figure 10). yes? SET DATA coads_climatology ! monthly surface climatology yes? SET REGION/X=100E:50W/Y=45S:45N ! Pacific Ocean yes? SET MODE CAL:MONTH yes? LET zero_at_warmest = sst - sst[l=@max] yes? LET integrand = L[G=sst] * zero_at_warmest[L=@WEQ] ! "L" is 1 to 12 yes? SET VARIABLE/TITLE="Month of warmest SST" integrand yes? SHADE/L=1:12/PAL=inverse_grayscale integrand[L=@SUM] *** 2.4.28 @ITP -- interpolate *** The @ITP tranformation provides the same linear interpolation calculation that is turned on modally with SET MODE INTERPOLATE but with a higher level of control, as @ITP can be applied selectively to each axis. @ITP may be applied only to point locations along an axis. The result is the linear interpolation based on the adjoining values. For example, for a Z axis with points at Z=0, 10, 20, ... V[Z=4@ITP] will compute 0.6 * V[Z=0] + 0.4 * V[Z=10] *** 2.5 IF-THEN logic ("masking") *** Ferret expressions can contain embedded IF-THEN-ELSE logic. The syntax of the IF-THEN logic is simply (by example) LET a = IF a1 GT b THEN a1 ELSE a2 (read as "if a1 is greater than b then a1 else a2"). This syntax is especially useful in creating masks that can be used to perform calculations over regions of arbitrary shape. For example, we can compute the average air-sea temperature difference in regions of high wind speed using this logic: SET DATA coads_climatology SET REGION/X=100W:0/Y=0:80N/T=15-JAN LET fast_wind = IF wspd GT 10 THEN 1 LET tdiff = airt - sst LET fast_tdiff = tdiff * fast_wind *** 3 EMBEDDED EXPRESSIONS *** Ferret supports "immediate mode" mathematical expressions -- that is, numerical expressions that may be embedded anywhere within a command line. These expressions are evaluated immediately by Ferret -- before the command itself is parsed and executed. Immediate mode expressions are enclosed in grave acccents, the same syntax used by the Unix C shell. Prior to parsing and executing the command Ferret will replace the full grave accent expression, including the accent marks, with an ASCII string representing the numerical value. For example, if the given command is CONTOUR/Z=`temp[X=180,Y=0,Z=@LOC:15]` salt Ferret will evaluate the expression "temp[X=180,Y=0,Z=@LOC:15]" (the depth of the 15-degree isotherm at the equator/dateline -- say, it is 234.5 meters). Ferret will generate and execute the command CONTOUR/Z=234.5 salt Embedded expressions: * the expression must evaluate to a single number, a scalar, or Ferret will respond that the command contains an error * if the result is invalid the numerical string will be "bad" (see BAD= in following section) * region qualifiers that begin a command containing an embedded expression will be used in the evaluation of the expression * if multiple embedded expressions are used in a single command they will be evaluated from left to right within the command. This means that embedded expressions used to specify region information (e.g., the above example) may influence the evaluation of other embedded expressions to the right * when embedded expressions are used within commands that are arguments of a REPEAT command their evaluation is deferred until the commands are actually executed. Thus the embedded expressions are re-evaluated at each loop index of the REPEAT command * grave accents have a higher priority than any other syntax character. Thus grave accent expressions will be evaluated even if they are enclosed within quotation marks, parentheses, square brackets, etc. * substitutions based on dollar-signs (command script arguments and symbols) will be made before embedded expressions are evaluated * a double grave accent will be translated to a single grave accent and not actually evaluated. Thus double grave accents provide a mechanism to defer evaluation so that grave accent expressions may be passed to the Unix command line with the SPAWN command or may be passed as arguments to GO scripts (to be evaluated INSIDE the script. * the state of mode verify will determine if the evaluation of the embedded expression is echoed at the command line -- similar to REPEAT loops *** 3.1 Special calculations using embedded expressions *** By default Ferret formats the results of embedded expressions using 5 significant digits. If the result of the expression is invalid (e.g., 1/0) the result by default is the string "bad". Controls allow you to specify the formatting of embedded expression results in both valid and invalid cases and to query the size and -- shape of the result. The syntax to achieve this