SED navigation bar go to SED home page go to Dataplot home page go to NIST home page SED Home Page SED Staff SED Projects SED Products and Publications Search SED Pages
Dataplot Vol 1 Vol 2

FUNCTION BLOCK

Name:
    FUNCTION BLOCK
Type:
    Analysis Command
Purpose:
    Defines a function via a group of Dataplot commands.
Description:
    Dataplot allows users to define their own functions using a Fortran-like syntax. For example,

      LET FUNCTION F = (x-a0)/a1
      LET FUNCTION F = X1**2
      LET FUNCTION G = P*(L-X)/(E*I)

    User defined functions can be used in subsequent commands such as PLOT and LET (basically any place that a built-in Dataplot function can be used).

    Although Dataplot functions can be powerful, they do have some important limitations for some applications. In particular, Dataplot functions are evaluated on a "row by row" basis. Many statistical applications involve root finding or optimization for functions that involve sums of some kind.

    Function blocks were introduced to address this limitation. Function blocks allow you to define functions using various Dataplot LET subcommands.

    Function blocks are created using the CAPTURE syntax. For example,

      CAPTURE FUNCTION BLOCK ONE F A G
      LET C2 = 1/G
      LET Y2 = Y**G
      LET W = Y2*Z
      LET A1 = SUM W
      LET A2 = SUM Y2
      LET A = C2 - (A1/A2) + C1
      END OF CAPTURE

    The function block contains the following components

    1. CAPTURE FUNCTION BLOCK - this initiates the creation of the function block. The CAPTURE command is typically used to direct Dataplot output to a file. However, in this case it saves the specified commands in an internal structure that can be accessed later.

    2. ONE - up to three function blocks can be defined. In this example, "ONE" specifies that this is function block one. You can redefine these three function blocks as often as you need in a Dataplot session.

    3. F - this is the name of the function block. This is the name that will be used to execute the function block in subsequent commands. This follows the rules for other Dataplot names (i.e., up to eight alphanumeric characters).

    4. A - this is name of the parameter that will contain the response for the function block. This is the value that is typically defined in the last line of the function block. In this example, the response is a parameter. However, in some cases, it may be a variable.

    5. G - this is a parameter that is being updated by the function block. In this case, we have only one parameter. In some cases, you may have more than one parameter.

      For example, in an optimization problem, you may be looking for the value of the parameter that minimizes (or maximizes) the value of a function. The OPTIMIZE command will search over the specified parameter (G in this example) to find the optimal value.

      Parameters that remain fixed do not need to be specified on the CAPTURE command.

      Up to 20 parameters can be specified for a given function block.

    The following Dataplot commands can be included in a function block:

    1. LET ... = PATTERN ...
    2. LET ... = DATA ...
    3. LET ... = ... RANDOM NUMBERS ...
    4. ARITHMETIC OPERATIONS
    5. STATISTIC LET SUB-COMMANDS
    6. MATH LET SUB-COMMANDS

      The following MATH LET sub-commands are not allowed:

      • MATRIX sub-commands
      • DERIVATIVE
      • NUMERICAL DERIVATIVE
      • INTEGRAL
      • RUNGE-KUTTA
      • OPTIMIZE
      • ROOTS

    The arithmetic operations and statistics LET sub-commands are of particular interest. Commands that are not supported are not added to the function block during the CAPTURE operation. Up to 30 commands can be saved to a given function block.

    Currently, function blocks can be used with the following commands:

    1. PLOT <function>
    2. 3D-PLOT <function>
    3. LET ... = ROOTS ...
    4. LET ... = OPTIMIZE ...
    5. LET ... = INTEGRAL ...
    6. LET ... = NUMERICAL DERIVATIVE ...
Syntax 1:
    CAPTURE FUNCTION BLOCK <one/two/three> <name> <resp> <parameter list>
    where <one/two/three> specifies which function block is being created;
                <name> is the name of the function block;
                <resp> is the name of parameter or a variable that is the result of the function block;
    and       <parameter list> is a list of 1 to 20 parameter names.

    This syntax is used to create the contents of a function block.

Syntax 2:
    LIST FUNCTION BLOCK <one/two/three>
    where <one/two/three> specifies which function block is being listed.

    This syntax is used to list the contents of a function block.

Examples:
    capture function block one f a sigma gamma
    let c1 = n*(log(gamma) - gamma*log(sigma))
    let c2 = (gamma - 1)*ylogsum
    let y2 = (y/sigma)**gamma
    let c3 = sum y2
    let a = c1 + c2 - c3
    end of capture
Note:
    Error checking (e.g., matching parenthesis, valid number of arguments for a built-in function) is performed when the function block is evaluated, not when it is created.
Note:
    There may be cases where you cannot create the needed function even with the FUNCTION BLOCK command. The LET ... = EXECUTE ... command can be used to run an external prorgram. That is, your function block can use the EXECUTE command to compute the desired function. You can create the external program in whatever language is most convenient for your application. The basic requirement is that the resulting external file can be run from the command line and that it can read from standard input and write to standard output.
Default:
    None
Synonyms:
    None
Related Commands:
    LET = Carries out a variety of operations on variables, parameters, and functions.
    LET FUNCTION = Define a function.
    EXECUTE = Run an external program.
    CAPTURE = Direct Dataplot output to an external file.
    STATISTIC BLOCK = Define a statistic block.
    PLOT = Plot a function of one variable.
    3D-PLOT = Plot a function of two variables.
    ROOTS = Find the roots of a univariate function.
    OPTIMIZE = Find the maximum (or minimum) of a function.
    INTEGRAL = Find the integral of a function.
    NUMERICAL DERIVATIVE = Find the numerical derivative of a function.
Applications:
    Mathematics
Implementation Date:
    2015/11
Program 1:
     
    . Purpose:  Demonstrate the use of function blocks
    .
    . Step 1:   Read the data
    .
    skip 25
    read weibbury.dat y
    skip 0
    .
    . Step 2:   Define the function block
    .
    let n = size y
    let z = log(y)
    let zsum = sum z
    let c1 = zsum/n
    .
    capture function block one f a g
    let c2 = 1/g
    let y2 = y**g
    let w  = y2*z
    let a1 = sum w
    let a2 = sum y2
    let a  = c2 - (a1/a2) + c1
    end of capture
    .
    list function block one
        
    The following output is generated.
    CONTENTS OF FUNCTION BLOCK ONE:
    let c2 = 1/g
    let y2 = y**g
    let w  = y2*z
    let a1 = sum w
    let a2 = sum y2
    let a  = c2 - (a1/a2) + c1
    NAME FOR FUNCTION BLOCK ONE: F
    PARAMETER LIST FOR FUNCTION BLOCK ONE:
    PARAMETER  1: G
    RESPONSE PARAMETER/VARIABLE: A
        
    .
    . Step 3:   Plot the function
    .
    title offset 2
    title case asis
    label case ais
    y1label Function Response A
    x1label G Parameter 
    title Function Block with Plot Command
    plot f for g = 2  0.01 20
    delete g
    .
    . Step 3:   Now use it to solve an equation
    .
    let yroot = roots f wrt g for g = 2  20
        
    The following output is generated.
     ROOTS OF AN EQUATION
           ROOT VARIABLE                     = G
           SPECIFIED LOWER LIMIT OF INTERVAL =         2.0000000000
           SPECIFIED UPPER LIMIT OF INTERVAL =        20.0000000000
      
           NUMBER OF ROOTS FOUND IN INTERVAL =        1
      
     ROOT     1 =    8.117599
        
    let ztemp = yroot(1)
    .
    line dash
    drawsdsd 15 0 85 0
    drawdsds ztemp 20 ztemp 90
        
    plot generated by sample program
    .
    let yinte = integral f wrt g for g = 2  6
    print yinte
        
    The following output is generated.
     PARAMETERS AND CONSTANTS--
    
         YINTE   --  0.8159837E+00
        
    .
    let yder = numerical derivative f wrt g for g = 4.2
        
    The following output is generated.
     AT X0 =    4.200000     THE DERIVATIVE VALUE  =  -0.7183620E-01
     (WITH ESTIMATED ERROR =   0.8401624E-04)
      
      
     THE COMPUTED VALUE OF THE CONSTANT   YDER     =  -0.7183620E-01
        
    let gtemp = sequence 2 0.05 6
    let yd = numerical derivative f wrt gtemp
    y1label Numerical Derivative
    plot yd gtemp
        
    plot generated by sample program
Program 2:
     
    . Purpose:  Demonstrate the use of function blocks in univariate
    .           optimization
    .
    . Step 1:   Read the data
    .
    skip 25
    read weibbury.dat y
    skip 0
    .
    . Step 2:   Define the function block
    .
    set optimization maximum
    capture function block one f a gamma
    let a  = weibull ppcc statistic y
    end of capture
    .
    list function block one
        
    The following output is generated.
     CONTENTS OF FUNCTION BLOCK ONE:
     let a  = weibull ppcc statistic y
     NAME FOR FUNCTION BLOCK ONE: F
     PARAMETER LIST FOR FUNCTION BLOCK ONE:
     PARAMETER  1: GAMMA
     RESPONSE PARAMETER/VARIABLE: A
        
    .
    . Step 3:   Plot the function
    .
    title offset 2
    title case asis
    label case ais
    y1tic mark offset 0  0.05
    tic mark offset units data
    y1label PPCC Value
    x1label Gamma Parameter 
    title Function Block for PPCC Statistic
    plot f for gamma = 0.10 0.05 50
    delete gamma
    .
    . Step 3:   Now use it to perform an optimization
    .
    let yopt = optimize f wrt gamma for gamma = 0.1 50
        
    The following output is generated.
     MINIMUM OF A FUNCTION
           OPTIMIZATION VARIABLE             = GAMMA
           SPECIFIED LOWER LIMIT OF INTERVAL =         0.1000000000
           SPECIFIED UPPER LIMIT OF INTERVAL =        50.0000000000
      
           THE MINIMUM VALUE OCCURS AT =   0.3038950E+01
      
      
     THE COMPUTED VALUE OF THE CONSTANT   YOPT     =   0.3038950E+01
      
      
     THE COMPUTED VALUE OF THE CONSTANT   FVALUE   =  -0.9900165E+00
        
    .
    line dash
    let fvalue = -fvalue
    drawsdsd 15 fvalue 85 fvalue
    drawdsds yopt 20 yopt 90
    .
    let gamma = round(yopt,3)
    let ppcc = round(fvalue,3)
    case asis
    just center
    move 50 5
    text Gamma: ^gamma, PPCC: ^ppcc
        
    plot generated by sample program
Program 3:
     
    . Purpose:  Demonstrate the use of function blocks in multivariate
    .           optimization
    .
    . Step 1:   Read the data
    .
    skip 25
    read weibbury.dat y
    skip 0
    .
    . Step 2:   Define the function block
    .
    let n = size y
    let ylog = log(y)
    let ylogsum = sum ylog
    let ylsd = sd ylog
    let ghat = 1.28/ylsd
    let ytemp = y**ghat
    let sighat = sum ytemp
    let sighat = sighat/n
    .
    capture function block one f a sigma gamma
    let c1 = n*(log(gamma) - gamma*log(sigma))
    let c2 = (gamma - 1)*ylogsum
    let y2 = (y/sigma)**gamma
    let c3 = sum y2
    let a  = c1 + c2 - c3
    end of capture
    .
    list function block one
        
    The following output is generated.
        
    .
    . Step 3:   Generate Weibull plot to obtain start values
    .
    weibull plot y
        
    plot generated by sample program
    .
    . Step 3:   Now use it to perform an optimization
    .
    let gamma = beta
    let sigma = eta
    set optimization maximum
    optimization method line finite
    let yopt = optimize f wrt sigma gamma
        
    The following output is generated.
          MAXIMUM NUMBER OF ITERATIONS (  150) EXCEEDED.
      
           THE MINIMUM VALUE OCCURS AT = SIGMA       55.77204
           THE MINIMUM VALUE OCCURS AT = GAMMA       8.191590
        
    .
    3d-plot f  for sigma = 40  0.5  60 for gamma = 5 0.1 10
        
    plot generated by sample program

Privacy Policy/Security Notice
Disclaimer | FOIA

NIST is an agency of the U.S. Commerce Department.

Date created: 12/01/2015
Last updated: 12/01/2015

Please email comments on this WWW page to alan.heckert.gov.