flowpattern              package:SoPhy              R Documentation

_S_i_m_u_l_a_t_i_o_n _o_f _f_l_o_w _p_a_t_t_e_r_n

_D_e_s_c_r_i_p_t_i_o_n:

     Purely stochastic simulation of a water flow pattern as they
     appear in dye tracer experiments

_U_s_a_g_e:

     flowpattern(type=c('identical', 'unif', 'independent', 
                                    'dependent', 'all'),
           length.profile=200, depth=100,  width.slice=1,     
           delta.x = depth * sqrt(x.var), delta.y = depth * sqrt(y.var),
           lambda.path=0.1, len.x, len.y,  grid=FALSE,

           x.name='whittle', x.var=1, x.v.scale=10, x.kappa=2, x.h.scale=1,
           y.name=x.name, y.var=x.var, y.v.scale=x.v.scale, y.kappa=x.kappa,
           y.h.scale=x.h.scale, unif.b=2,
                
           drop.distr=function(x) x * 80, drop.name='whittle',
           drop.scale=1, drop.kappa=2, drops=1,
                
           selected.dist = 2/3, front.factor=2, method = NULL,
           endpoint.tolerance=0, measure=function(x) x^2,
                
           simu.method=if (type %in% c("dependent", "all")) "TBM3",
           drop.simu.method = NULL, register=c(1,2),
           old.paths=NULL, PrintLevel=RFparameters()$Print, wait=FALSE,
           raw=FALSE, compress=TRUE, max.points = 5500000)

_A_r_g_u_m_e_n_t_s:

    type: character, one of ''identical'', ''unif'', ''independent'',
          ''dependent'', ''all''. Type of model. See details. 

length.profile: positive integer. Length of the profile.

   depth: positive integer. Depth of the profile.

width.slice: positive integer. Thickness of the slice. Usually a small
          number.

 delta.x: enlargement of the simulation block to the left and right of
          the profile to avoid edge effects.

 delta.y: enlargement of the thickness of slice in both directions to
          avoid edge effects.

lambda.path: intensity of the Poisson point process at the surface; if
          'grid=TRUE' and 'len.x' or 'len.y' are missing they are
          approximated by the number the number of points of the
          process. If 'grid=TRUE' and 'len.x' and 'len.y' are not
          missing, the value of 'lamda.path' is ignored. 

   len.x: integer.  Number of grid points in x-direction.  Only used if
          'grid=TRUE'.  Then it overwrites 'n.path'

   len.y: integer.  Number of grid points in y-direction.  Only used if
          'grid=TRUE'.  Then it overwrites 'n.path'

    grid: logical.  If 'FALSE' the locations are uniformly and
          independently distributed.

  x.name: character.  Name of the covariance function used to simulate
          the path increments.  Only used if 'type' is different from
          ''unif'', see  'CovarianceFct'. 

   x.var: numeric.  Variance of the covariance function.

x.v.scale: numeric.  Scale in vertical direction.

 x.kappa: Vector of additional parameters for the covariance function,
          if there are any. 

x.h.scale: numeric.  Scale for the two horizontal directions. Only used
          if 'type='dependent'' or 'type='all'' - otherwise, the path
          are independent. 

  y.name: analogously to 'x.name' for the y-direction

   y.var: analogously to 'x.var' for the y-direction

y.v.scale: analogously to 'x.v.scale' for the y-direction

 y.kappa: analogously to 'x.kappa' for the y-direction

y.h.scale: analogously to 'x.h.scale' for the y-direction

  unif.b: numeric greater than; upper endpoint of the uniform
          distributon; relevant only if 'type='unif''; see Details. 

drop.distr: The stained path length reached by a single drop is
          calculated as follows.  First a Gaussian random field is
          simulated with the parameters given below. Then the Gaussian
          random field is marginally transformed to uniform
          distribution by the Gaussian distribution function. Then the
          inverse of the required distribution function is applied. 
          'drop.distr' gives this inverse.  It should allow for vectors
          as input variables. 

drop.name: Name of the covariance function for the horizontal
          dependence of the Gaussian random field that is used to model
          the stained path length.  Only used if 'type='all'' -
          otherwise a Gaussian random field with pure nugget effect is
          used. See 'CovarianceFct' for possible values. 

drop.scale: numeric.  Scale in (horizontal) direction.

drop.kappa: Vector of additional parameters for the covariance
          function, if there are any.

   drops: Number of drops running through each path. Then the stained
          part equals the longest stained part for all drops. 

selected.dist: number in (0,1) or a vector of integers. 'selected.dist'
          used for estimating the risk index, see 'risk.index'.

          'selected.dist' gives the distances for which the form
          parameter of the pareto distribution is estimated. If
          'selected.dist' is a number in (0,1) the distances are '1:(1
          + round(max(data[,1]-1) * selected.dist))'. Otherwise the
          integers are interpreted as indices for 'data'. 

front.factor: 'front.factor' is used for estimating the risk index, see
          'risk.index'.

          The upper bound for the upper endpoint equals the
          'front.factor' times the largest distance for which at least
          stained pixel is observed.

          The value should not be changed if the algorithm is not
          understood. 

  method: character, 'fix.m' or 'optim.m'. 'method' is used for
          estimating the risk index, see 'risk.index'.

          If 'fix.m', the estimated number of path equals the maximum
          number of ob stained pixels below a given threshold. If
          'optim.m' the number of paths is estimated by optimisation.

          If 'method' is a vector containing both values, the risk
          index is calculated for both methods.

          If 'method' is 'NULL' nothing is estimated. 

endpoint.tolerance: numeric. 'endpoint.tolerance' is used for
          estimating the risk index, see 'risk.index'

          If the shape parameter is negative then the distribution has
          a finite upper endpoint.  Hence, mathematically, the lowest
          upper end point of the Pareto distribution is given as the
          largest distance for which at least one stained pixel is
          observed.  For stability reasons and because the observed
          data might be a scale mixure of Pareto distribution it is
          advantageous to allow for some tolerance of the minimal upper
          end point.

          If 'endpoint.tolerance' is positive then the lower threshold
          for the upper end point is the largest distance for which the
          number of observed stained pixels is larger than
          'endpoint.tolerance'.

          If 'endpoint.tolerance' is negative then the lower threshold
          equals largest distance for which at least one stained pixel
          is observed minus the modulus of 'endpoint.tolerance'. 

 measure: function that measures the distance between points; the
          function gets and returns a vector; used for estimating the
          risk index, see 'risk.index'

simu.method: 'NULL' or string; Method used for simulating the Gaussian
          random fields for the paths, see RFMethods to get all
          options. If 'model' is given as list then 'method' may not be
          set if 'model[[i]]$Method', i=1,3,.. is given, and vice versa

          "TBM3" allows for some special effect: grid points and
          arbitrary points can taken from the same realisation by two
          subsequent calls of the function. 

drop.simu.method: 'NULL' or string; Method used for simulating the
          Gaussian random fields for the drops, see 'simu.method'

register: vector of 2 components. The first compontent gives the
          register used in 'GaussRF' to simulate the paths, the  second
          component gives the register for the drops.

old.paths: 'NULL' or 'list'. If 'list' it must have the same format as
          the return list of 'flowpattern'. Then the flow pattern is
          recalculated where only the 'drop.distr'  is changed.

             *  <=0 : no messages are printed

             *  >=1 : the higher the number the more information is
                given 

    wait: logical. If 'PrintLevel>1' than the simulated profile is
          shown. If 'wait=TRUE' the system waits for return after
          plotting. 

     raw: logical. If 'grid=TRUE' then the simulated random fields for
          the x- and y-coordinates of the paths are also returned.
          Ignored otherwise. 

compress: logical. If 'grid=FALSE', then paths where no part is within
          the considered slice are deleted at an early stage. Ignored
          otherwise. 

max.points: logical. If 'grid=FALSE', 'type %in% c('dependent', 'all')'
          and 'compress=TRUE', then the simulation of the the
          coordinates of the paths is done in several steps and
          ``compression'' is performed between the steps.  

_D_e_t_a_i_l_s:

     'type' allows for the following values

     ''_i_d_e_n_t_i_c_a_l'' All paths are identical, the increments of the path
          curve in x-direction are given by a Gaussian random field
          with parameters 'x.name' 'x.var', 'x.v.scale' and 'x.kappa'.
          The increments in y-direction by an independent Gaussian
          random field with parameters 'y.name' 'y.var', 'y.v.scale'
          and 'y.kappa'. The drops are i.i.d. according to
          'drop.distr'.

     ''_u_n_i_f'' For each path the angles of the segments to the
          horizontal plane are constant, such that the length of the
          paths are uniformly distributed ~U([1,'unif.b'])* [units of
          the vertical axis]. The paths are variied only in the
          x-direction, but not in the y-direction.

          The drops are i.i.d.

     ''_i_n_d_e_p_e_n_d_e_n_t'' The paths and the drops are independently
          distributed.

     ''_d_e_p_e_n_d_e_n_t'' The paths increments in x-direction are spatially
          dependent given by a Gaussian random field with parameters
          'x.name' 'x.var', 'x.h.scale' and 'x.kappa'. Indeed, a three
          dimensional random field of geometrical anisotropy is
          generated, which includes the vertical direction with
          parameter 'x.v.scale'. Analogously for the increments in
          y-direction. The x-y-coordinates of the sampling points of
          the random field are the starting points of the paths at the
          surface.

          The drops are i.i.d. according to 'drop.distr'.

     ''_a_l_l'' The paths are simulated as for 'type='dependent''. Here
          the drop distributions are spatially dependent, given by a
          two-dimensional Gaussian random field with parameters
          'drop.name', 'drop.scale' and 'drop.kappa'.

     See the references for some background.

_V_a_l_u_e:

     it returns the following list 

     c.r: empty list if 'length(method)==0'.  Otherwise a list with
          'length(method)' components.  Each of them is the output of
          'risk.index'. 

intermediate: list containing 'xx', a matrix of x-coordinates of the
          vertices of the paths, 'yy', a matrix of y-coordinates of the
          vertices of the paths, and 'LEN', the field of all the
          stained path lengths, after marginal transformation to
          uniform U([0,1]) distribution. 

    dist: 1:depth

    freq: the number of stained pixels (after projection of the stained
          parts to the paths to a grid with grid length 1) as a
          function of 'dist'

     i.x: x-coordinates of the stained pixels

     i.d: z-coordinates of the stained pixels

   input: list of all input variables

_A_u_t_h_o_r(_s):

     Martin Schlather, schlath@hsu-hh.de <URL:
     http://www.unibw-hamburg.de/WWEB/math/schlath/schlather.html>

_R_e_f_e_r_e_n_c_e_s:

        *  Schlather, M. and Huwe, B. (2005a) A stochastic model for
           3-dimensional flow patterns in dye tracer experiments. _J.
           Hydrol._ *310*, 17-27.

        *  Schlather, M. and Huwe, B. (2005b) A risk index for
           characterising flow pattern in soils using dye tracer
           distributions. _J. Contam. Hydrol._ *79*, to appear.

_S_e_e _A_l_s_o:

     'RandomFields', 'plotFlow2d', 'plotFlow3d'

_E_x_a_m_p_l_e_s:

     ############################################################
     ##                     simple example                    ##
     ############################################################
     RFparameters(TBM3.lines=100, TBM3.linesimustep=0.3,
                  TBM3.linesimufactor=0, Print=1)
     fp3 <- flowpattern(type="all", lambda=0.1, length.profile=50,
                       depth=80, width=50, Print=20)
     fp2 <- plotFlow3d(fp3, inf=c(1300, -500, 1/2000),
                       sun=c(100, -1500, 0))
     plotFlow2d(fp2)

