O routines

All GAMAP Routines

List routines by category:
Atmospheric Sciences | Benchmarking | Color | Date/Time | Doc | File & I/O | BPCH Format | Scientific Data Formats | GAMAP Examples | GAMAP Internals | GAMAP Utilities | GAMAP Data Manipulation | GAMAP Models & Grids | GAMAP Plotting | General | Graphics | Math & Units | Plotting | Regridding | Strings | Structures | Time Series

List routines by alphabetical order:
A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

Last modified: Tue Apr 4 10:50:26 2017.

List of Routines

Routine Descriptions


[Next Routine] [List of Routines]

        If hard copy is to be generated, OPEN_DEVICE opens the 
        PostScript device.  Otherwise OPEN_DEVICE opens an Xwindow. 


        OPEN_DEVICE [,OLD_DEVICE] [,keywords]

        OLD_DEVICE -> This is now obsolete, and is only maintained
             for backwards compatibility.

        /PS -> will send PostScript file to printer

        FILENAME -> The name to be given the PostScript file.
             Default: idl.ps

        /LANDSCAPE  -> will enable PostScript landscape mode

        /PORTRAIT -> will enable PostScript portrait mode

        XOFFSET, YOFFSET -> Keywords for the DEVICE command.  XSIZE
             specifies the horizontal offset (in inches) of the page,
             and YSIZE specifies the vertical offset (in inches) of
             the page.  Defaults are as follows:

             Plot type         XOFFSET          YOFFSET

             Portrait           0.25             0.25
             Landscape          0.75             0.75
        XSIZE, YSIZE -> Keywords for the DEVICE command.  XSIZE
             specifies the horizontal size (in inches) of the page,
             and YSIZE specifies the vertical size (in inches) of
             the page.  Defaults are as follows:
             Plot type         XSIZE            YSIZE
             Portrait           8.0              10.0
             Landscape      11 - 2*XOFFSET   8.5 - 2*YOFFSET

        /COLOR -> will enable PostScript color mode

        WINPARAM -> An integer vector with up to 5 elements:
             WINPARAM(0) = window number  (if negative, a window
                          will be opened with the /FREE option.
             WINPARAM(1) = X dimension of window in pixels (width)
             WINPARAM(2) = Y dimension of window in pixels (height)
             WINPARAM(3) = X offset of window (XPOS)
             WINPARAM(4) = Y offset of window (YPOS)

        TITLE -> window title

        /Z -> If set, will initialize the Z-buffer device.  If WINPARAM
             is specified, then the size of the Z-buffer region will be
             WINPARAM[1] x WINPARAM[2] pixels.  If WINPARAM is not 
             specified, then the size of the Z-buffer region will be 
             set to a default size of 640 x 512 pixels.

        NCOLORS -> If /Z is set, NCOLORS specifies the number of colors
             that will be made available to the Z-buffer device.
        _EXTRA=e -> additional keywords that are passed to the call to
             the DEVICE routine (e.g. /ENCAPSULATED)

        OLD_DEVICE -> stores the previous value of !D.NAME for
             use in CLOSE_DEVICE. Note that CLOSE_DEVICE will automatically
             set the default screen device if OLD_DEVICE is not provided,
             hence it will only rarely be used.



        If PS=0 then  
            Open Xwindow WINPARAM(0), which is WINPARAM(1) pixels wide
            in the X-direction, and WINPARAM(2) pixels wide in the

        If PS=1 then 
           depending on /PORTRAIT or /LANDSCAPE and /COLOR
           postscript is enabled in either portrait or landscape
           mode as color or b/w plot

        The key parameter which determines whether to open a postscript
        file or a screen window is PS. Therefore, e.g. in a widget 
        application, you can pass a standard set of parameters for both,
        postscript and screen, to this routine, and determine the device
        to be chosen by a button state or checkbox which is passed into PS.
        Also is currently hardwired for 8.5 x 11 inch paper (US
        format).  Need to extend this to European A4 paper soon.

        OPEN_DEVICE, WINPARAM=[0,800,800]  

             ; opens a screen window of size 800x800 
             ; pixels at the default position


             ; opens a postscript file named myplot.ps in 
             ; b/w and landscape orientation


             ; depending on the value of PS either a color 
             ; postscript file named idl.ps is opened or screen 
             ; window number 2 in default size.

        OPEN_DEVICE, /Z

             ; Opens the IDL Z-buffer device.  The current 
             ; color table will be preserved in the Z-buffer device.

        bmy  15 Aug 1997: VERSION 1.00
        bmy, 19 Aug 1997: VERSION 1.01
        mgs, 20 Aug 1997: VERSION 1.02
        mgs, 09 Apr 1998: VERSION 1.10 
                          - added 2 more parameters for WINPARAM
                            and TITLE keyword
        bmy, 28 Jul 2000: VERSION 1.46   
                          - now make XSIZE, XOFFSET, YSIZE, YOFFSET keywords
                          - cosmetic changes, updated comments
        bmy, 30 Jan 2001: VERSION 1.47
                          - added /Z and NCOLORS keywords for the Z-buffer
                          - updated comments
        bmy, 26 Jul 2001: VERSION 1.48
                          - use default window size of 640 x 512 for
                            the Z-buffer, if WINPARAM isn't specified.
        bmy, 27 Aug 2001: - now call DEVICE with XSIZE, YSIZE,
                            XOFFSET, YOFFSET for /LANDSCAPE plots
                          - Updatedd comments
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/graphics/open_device.pro)


[Previous Routine] [Next Routine] [List of Routines]

        Open a file for input. This routine can automatically
        decide whether to use DIALOG_PICKFILE, and it contains
        basic error handling. After successful operation the
        file with logical unit LUN will be open for input.

        File & I/O

        OPEN_FILE,filemask,lun [,keywords]

        FILEMASK -> a filename with path information that may
            contain wildcards ('*', '?')

        LUN -> a named variable that will contain the logical unit
            number upon return. If a unit number > 0 is passed,
            an attempt is made to open the file with this number,
            otherwise, a free unit is selected with /GET_LUN. In case
            of an error, LUN contains -1. This can be used instead of
            the RESULT keyword to detect errors (see below).

        (both parameters are mandatory !)

        FILENAME -> a named variable that will contain the complete
            filename upon return (i.e. the file selected with PICKFILE)

        WRITE -> Set this keyword to open a file for read and write
            operations. Normally, a file is opened for reading only.

        RESULT -> a named variable that will return the error status
            of the operation. A value of 0 indicates the file was
            opened sucessfully, otherwise the value of !Error_State.Code
            is returned.

        PICKFILE -> logical flag to force use of the DIALOG_PICKFILE
            routine, even if a complete filemask without wildcards was

        TITLE -> the title of the pickfile dialog. Default is
            'Choose a file'.

        DEFAULTMASK -> A default filemask to be used when no filename
            is given or the filename does not contain wildcards and
            /PICKFILE is set. This mask will also be used if the
            file cannot be opened because of 'FILE NOT FOUND' error.

        NO_PICKFILE -> prevents the pickfile dialog for batch operation.
            The filemask must not contain wildcards.
            Normally a 'FILE NOT FOUND' condition leads to
            a second attempt with the /PICKFILE flag set (recursive
            call). Use this flag if you want to abort instead.

        _EXTRA keywords are passed to the openr routine
            (e.g. /F77_UNFORMATTED)



        Uses EXTRACT_FILENAME function


        ; Quick and dirty with pickfile dialog
        if (ilun le 0) then stop    ; check error condition

        ; A few more options invoked
        OPEN_FILE,'~/data/thisfile.dat',lun,default='*.dat', $
            title='Choose a data file',filename=name

        IF (LUN LE 0) THEN STOP    ; check error condition

        PRINT, FILENAME,' was opened successfully
        ; NOTE that filename does not have to be identical with
        ; '~/data/thisfile.dat' !
        ; readf,lun,...

        CLOSE,    LUN
        FREE_LUN, LUN

        mgs, 13 Aug 1998: VERSION 1.00
                          - extracted from ctm_read3dp_header.pro and 
        mgs, 14 Aug 1998: - small bug fix: handle empty filename
                            string correctly
        mgs, 22 Aug 1998: - added WRITE keyword to open writable files
        mgs, 22 Oct 1998: - now always returns LUN=-1 in case of an error
        mgs, 21 Jan 1999: - Added explicit F77_Unformatted keyword and set
                            Swap_If_Little_Endian or Swap_If_Big_Endian  
        mgs, 10 Feb 1999: - bug fix: swap_if was wrong way round
        mgs, 12 May 1999: - ok. finally got the hang of byte swapping! 
                            It's the machine architecture not the operating
                            system!  Now changed it so that !VERSION.ARCH is
                            tested for 'x86'
        mgs, 20 May 1999: - abandoned SWAP_IF completely and use explicit
                            SWAP_ENDIAN keyword in users grace now.
        bmy, 14 Oct 2003: TOOLS VERSION 1.53
                          - For IDL 6.0+, if PATH is a null string, then
                            manually reset it to './'.  This will avoid
                            the contents of the !PATH variable from being
                            listed in the dialog box. 
  bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
  cdh & phs, 30 Jun 2008: GAMAP VERSION 2.12
                          - declare dummy GET_LUN keyword. It
                            prevents passing GET_LUN w/ _extra to
                            openr/w, since LUN is already assigned in
                            all cases.

(See /n/home09/ryantosca/IDL/gamap2/file_io/open_file.pro)


[Previous Routine] [List of Routines]

        Calculate reduced major axis.  Given two vectors X and Y, this
        subroutine computes the Gradient and Y intercept of the line 
        given by the reduced major axis.  The main advantage of this 
        is that the best fit line of X and Y will be the same as the 
        best fit line of Y and X.

        Math & Units 

        ORG_CORR, X, Y, R, NP, GRADIENT, INTERCEPT,            $

        X -> Vector containing X-axis values.

        Y -> Vector containing Y-axis values.

        R -> Correlation coefficient
        NP -> Number of elements of X and Y arrays to process. 
             NP should be smaller than or equal to the number of
             elements of X and Y.

        /VERBOSE -> Set this switch to print the gradient,
             intercept, and standard errors to the screen.   
             The default is not to print these values.

        GRADIENT -> Gradient of reduced major axis

        INTERCEPT -> Y-Intercept of reduced major axis
        GRADIENT_ERR -> Standard error in gradient.

        INTERCEPT_ERR -> Standard error in Y-intercept.

        External Subroutines Required:
        SIGN (function)

        References routines from the TOOLS package.

        (1) More details are in Hirsch and Gilroy, Water Res. Bull., 
            20(5), Oct 1984.

        (2) Standard errors also calculated according to Miller and 
            Kahn, Statistical Analysis in the Geological Sciences,
            1962, pp. 204-210.

        (3) Computations are now performed in double precision.


  pip, clh, bmy, 10 Oct 2002: TOOLS VERSION 1.52
            bmy, 26 Jan 2007: TOOLS VERSION 2.06
                              - Now compute gradient of YNEW with max 
                                & min values & subscripts of.  This avoids
                                the assumption that the first & last 
                                elements of YNEW are different.  
                                (Fix submitted by Mike Barkley, 1/26/07)
      bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10

(See /n/home09/ryantosca/IDL/gamap2/math_units/org_corr.pro)