flowpattern {SoPhy} | R Documentation

## Simulation of flow pattern

### Description

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

### Usage

    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)

### Arguments

`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.
`PrintLevel` | <=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.

### Details

`type` allows for the following values

`'identical'`
  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`.
`'unif'`
  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.

`'independent'`
  The paths and the drops are independently distributed.
`'dependent'`
  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`.

`'all'`
  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.

### Value

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

### Author(s)

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

### References

- 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.

### See Also

`RandomFields`, `plotFlow2d`, `plotFlow3d`

### Examples

    ############################################################
    ##                     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)

[Package SoPhy version 1.0.28 Index]