[Soiltexture-commits] r32 - pkg/soiltexture/R

[noreply at r-forge.r-project.org]

Author: jmoeys
Date: 2010-08-11 19:05:39 +0200 (Wed, 11 Aug 2010)
New Revision: 32

Modified:
   pkg/soiltexture/R/soiltexture.R
Log:
Updated inlinedoc documentation inside the code (not yet compiled).

Modified: pkg/soiltexture/R/soiltexture.R
===================================================================
--- pkg/soiltexture/R/soiltexture.R	2010-08-11 09:53:29 UTC (rev 31)
+++ pkg/soiltexture/R/soiltexture.R	2010-08-11 17:05:39 UTC (rev 32)
@@ -2602,10 +2602,10 @@
 
 
 
-# +--------------------------------------+
-# | FUN: TT.text.transf.Xm()             |
-# +--------------------------------------+
-TT.text.transf.Xm <- function(# Transformation of a soil texture data table between 2 particle size systems (X classes)
+
+
+
+TT.text.transf.Xm <- function(# Transformations of a soil texture data table between 2 particle size systems (X classes), various methods.
 ### using various Particle Size Distribution (PSD) models including Anderson (AD), Fredlund4P (F4P), Fredlund3P (F3P),
 ### modified logistic growth (ML), Offset-Nonrenormalized Lognormal (ONL), Offset-Renormalized Lognormal (ORL),
 ### Skaggs (S), van Genuchten type(VG),van Genuchten modified, Weibull (W), Logarithm(L), 
@@ -2942,12 +2942,12 @@
         }   
         else if( psdmodel == "ML" )
         {
-            pre <- 1/(1+coef(ttbest)[1]*exp(-coef(ttbest)[2]*xout^parm[,3]))
+            pre <- 1/(1+coef(ttbest)[1]*exp(-coef(ttbest)[2]*xout^(coef(ttbest)[3])))
         }
         else if( psdmodel == "ONL" )
         {
            t    <- (-1)^(log(xout) >= coef(ttbest)[1]+1)
-           pre  <- (1+t*erf((log(xout)+coef(ttbest)[1])/coef(ttbest)[2]*2^0.5))/2+parm[,3]
+           pre  <- (1+t*erf((log(xout)+coef(ttbest)[1])/coef(ttbest)[2]*2^0.5))/2+(coef(ttbest)[3]) 
         }
         else if( psdmodel == "ORL" ) #predict() has some bug for F4P model
         {
@@ -4867,7 +4867,7 @@
 
 
 
-TT.classes <- function(# Plot the texture classes ploygons in a texture triangle plot.
+TT.classes <- function(# Plot the texture classes polygons in a texture triangle plot.
 ### Plot the texture classes ploygons in an existing texture 
 ### triangle plot. Draw the polygons and the labels inside each 
 ### polygons.
@@ -5989,34 +5989,213 @@
 
 
 
-TT.points.in.classes <- function( 
-    tri.data,  
-    class.sys       = NULL, 
-    PiC.type        = NULL, 
-    css.names       = NULL, 
-    #
-    # INPUT DATA description: in theory, effectless, but
-    #   the function first project the tri-variables into x,y 
-    #   before retrieving corresponding classes
-    text.sum        = NULL, 
-    base.css.ps.lim = NULL, 
-    tri.css.ps.lim  = NULL, 
-    dat.css.ps.lim  = NULL, 
-    css.transf      = NULL, 
-    text.transf.fun = NULL, 
-    trsf.add.opt1   = NULL, 
-    trsf.add.opt2   = NULL, 
-    text.tol        = NULL, 
-    tri.sum.tst     = NULL, 
-    tri.pos.tst     = NULL, 
-    collapse        = ", ", 
- texture2xy=FALSE, 
+TT.points.in.classes <- function(# Classify a table of soil texture data according to a soil texture triangle.
+### The function calculate in which classe(s) of a texture triangle 
+### (classification system defined by 'class.sys') lies each soil 
+### sample (with texture data) in the table 'tri.data'. As a sample 
+### may lie inside a texture class, but also at the edge of 2 or 
+### more texture classes, the function does not only output 
+### one single texture class per sample. If 'PiC.type' is 'n' or 
+### 'l', it rather output a table where each column is a texture 
+### class and each row a texture sample, and yes / no information 
+### about the belonging of the sample to each texture class. 
+### Alternatively, If 'PiC.type' is 't'it will output a text 
+### string (per sample) containing all the texture classes 
+### to which that point belong.
+### The texture data in 'tri.data' can be transformed into 
+### another particle size system prior to their classification 
+### if needed. See the options  base.css.ps.lim, tri.css.ps.lim, 
+### dat.css.ps.lim, css.transf and text.transf.fun.
+### ON DEFAULT VALUES OF TT.points.in.classes() ARGUMENTS? As 
+### TT.points.in.classes() shares 
+### its arguments with many other functions, their default value 
+### is not defined in TT.points.in.classes() source code, but rather in 
+### a dedicated list object called 'TT.par' and stored in the 
+### environment TT.env. The function TT.get() is used to retrieve 
+### the default value of the arguments defined in TT.par (see 
+### ?TT.get). For instance, to know the default value of 'class.sys', 
+### you can type TT.get("class.sys"). To set a different default 
+### value for a given argument in R, use TT.set() (see ?TT.set). 
+### For instance to change the default value of 'class.sys', type 
+### TT.set( "class.sys" = "USDA.TT" ).
+
+ tri.data,
+### Data frame. Data frame containing the CLAY, SILT and SAND 
+### 'coordinates' of the texture data points to be classified The data 
+### frame can contain more column than needed (ignored). The data 
+### frame must have column named CLAY, SILT and SAND (uppercase, 
+### the order has no importance) or named after the 'css.names' 
+### argument (alternative names). The sum of CLAY, SILT and SAND 
+### must be equal to 'text.sum' 
+### ('text.tol' determines the error tolerance).
+
+ class.sys=NULL,
+### Single text string. Text code of the texture classification 
+### system to be used for the classification of 'tri.data'. 
+### Possible values are "none" (no classification plotted), "USDA.TT" 
+### (USDA texture triangle), "FAO50.TT" (FAO texture triangle with a 50 
+### microns silt-sand limit. DEFAULT VALUE), "FR.AISNE.TT" (French 
+### texture triangle of the Aisne region soil survey), "FR.GEPPA.TT" (French GEPPA 
+### texture triangle), "DE.BK94.TT" (German texture triangle), 
+### "UK.SSEW.TT" (Soil Survey of England and Wales), "AU.TT" 
+### (Australian texture triangle), "BE.TT" (Belgium texture triangle), 
+### "CA.EN.TT" (Canadian texture triangle, with English class abbreviations) and 
+### "CA.FR.TT" (Canadian texture triangle, with French class abbreviations)
+### (see the package vignette for a complete list).
+
+ PiC.type=NULL,
+### Single character string. If equal to 'n', then a table of 0, 
+### 1, 2 or 3 is outputed (0 if the sample does not belong to a class, 
+### 1 if it does, 2 if it lies on an edge and 3 if it lies on a 
+### vertex). Notice that the accuracy of the classification is 
+### not garanteed for samples lying very close to an edge, or right 
+### on it. See <http://www.mail-archive.com/r-help@r-project.org/msg96180.html>
+
+ css.names=NULL,
+### Vector of 3 character strings. Name of the columns in 'tri.data' 
+### that contains the CLAY SILT and SAND values, respectively. 
+### If NULL, default c("CLAY","SILT","SAND") value is assumed. Not 
+### to be confused with 'css.lab' that defines the labels of the 
+### CLAY SILT and SAND axes in the plot.
+
+ text.sum=NULL,
+### Single numerical. Sum of the 3 particle size classes for each texture 
+### value (fixed). The real sum of the 3 particle size classes in 'tri.data' 
+### should be >= text.sum * (1-text.tol) OR  <= text.sum * (1+text.tol), 
+### where 'text.tol' is an argument that can be changed. If some 
+### of the texture values don't match this requirement, an error 
+### occur (function fails) and TT.points.in.classes returns a of bad values with 
+### their actual particle size classes sum. You can 'normalise' you data 
+### table () prior to the use of TT.points.in.classes, by using the function 
+### TT.normalise.sum(), so all values match the 'text.sum' criteria. 
+### See also 'tri.sum.tst' that can be set to FALSE to avoid 
+### sum of particle size classes tests.
+
+ base.css.ps.lim=NULL,
+### Vector of 4 numericals. Particle size boundaries (upper and lower) 
+### of the 3 particle size classes (CLAY, SILT and SAND, starting from 
+### the lower size of CLAY particles, 0, to the upper size of the 
+### SAND particles, 2000), in micrometers, FOR THE BASE SYSTEM. These 
+### particles size class limits are the references and all other 
+### texture values with different limits will be converted into 
+### that reference if (and only if) css.transf == TRUE (not default). 
+### If NULL, 'base.css.ps.lim' will be set to the default value of the 
+### texture classification system chosen ('class.sys'). The 
+### transformation function is set by 'text.transf.fun' and is 
+### a log-linear interpolation by default.
+
+ tri.css.ps.lim=NULL,
+### Vector of 4 numericals. Particle size boundaries (upper and lower) 
+### of the 3 particle size classes (CLAY, SILT and SAND, starting from 
+### the lower size of CLAY particles, 0, to the upper size of the 
+### SAND particles, 2000), in micrometers, FOR THE TEXTURE TRIANGLE. 
+### If not NULL, different from 'base.css.ps.lim', and 
+### css.transf == TRUE (not default), then the CLAY SILT and SAND 
+### coordinates of the texture triangle will be converted into 
+### the 'base.css.ps.lim' reference. If NULL, 'tri.css.ps.lim' will 
+### be set to the default value of the texture classification system 
+### chosen ('class.sys'). The transformation function is set by 
+### 'text.transf.fun' and is a log-linear interpolation by default.
+
+ dat.css.ps.lim=NULL,
+### Vector of 4 numericals. Particle size boundaries (upper and lower) 
+### of the 3 particle size classes (CLAY, SILT and SAND, starting from 
+### the lower size of CLAY particles, 0, to the upper size of the 
+### SAND particles, 2000), in micrometers, FOR THE TEXTURE DATA TABLE
+### ('tri.data'). If not NULL, different from 'base.css.ps.lim', and 
+### css.transf == TRUE (not default), then the CLAY SILT and SAND 
+### coordinates of the texture data in tri.data will be converted into 
+### the 'base.css.ps.lim' reference. If NULL, 'tri.css.ps.lim' will 
+### be set to the default value of the texture classification system 
+### chosen ('class.sys'). The transformation function is set by 
+### 'text.transf.fun' and is a log-linear interpolation by default.
+
+ css.transf=NULL,
+### Single logical. Set to TRUE to transform the texture coordinates 
+### of the texture triangle ('class.sys') or the texture data 
+### ('tri.data') into the base particle size class limits. 
+### See 'base.css.ps.lim' for the base plot particle size class limits, 
+### 'tri.css.ps.lim' for the triangle particle size class limits 
+### and 'dat.css.ps.lim' for the data table particle size class limits. 
+### The transformation function is set by 'text.transf.fun' and 
+### is a log-linear interpolation by default. The default value is 
+### FALSE, so no transformation is made.
+
+ text.transf.fun=NULL,
+### R function with the same argument names and same output as 
+### the function TT.text.transf(). 'text.transf.fun' is the function 
+### that transform the texture values from one system of particle 
+### class size limits to another. Only used if css.transf == TRUE. 
+### Default value is text.transf.fun=TT.text.transf. See also 
+### 'base.css.ps.lim', 'tri.css.ps.lim' and 'dat.css.ps.lim'.
+
+ trsf.add.opt1=NULL,
+### Non pre-defined format. If the user specifies its own texture 
+### transformation function in 'text.transf.fun' (not TT.text.transf()), 
+### then he can use 'trsf.add.opt1' and 'trsf.add.opt1' as 
+### new, additional, argument for his function. So the format of 
+### 'trsf.add.opt1' depends on the function defined by the user 
+### in 'text.transf.fun'.
+
+ trsf.add.opt2=NULL,
+### Non pre-defined format. If the user specifies its own texture 
+### transformation function in 'text.transf.fun' (not TT.text.transf()), 
+### then he can use 'trsf.add.opt1' and 'trsf.add.opt1' as 
+### new, additional, argument for his function. So the format of 
+### 'trsf.add.opt1' depends on the function defined by the user 
+### in 'text.transf.fun'.
+
+ text.tol=NULL,
+### Single numerical. Tolerance on the sum of the 3 particle size classes. 
+### The real sum of the 3 particle size classes in 
+### 'tri.data' should be >= text.sum * (1-text.tol) OR 
+### <= text.sum * (1+text.tol). See 'text.sum' for more details, as 
+### well as 'tri.sum.tst' (to prevent texture sum tests).
+
+ tri.sum.tst=NULL,
+### Single logical. If TRUE (the default), the sum of the 3 texture 
+### classes of each texture value in 'tri.data' will be checked 
+### in regard to 'text.sum' and 'text.tol'. If FALSE, no test 
+### is done.
+
+ tri.pos.tst=NULL,
+### Single logical. If TRUE (the default), the position of texture 
+### values in 'tri.data' are tested to check that they are not 
+### OUTSIDE the texture triangle (i.e. that some texture values may 
+### be negative).
+
+ collapse=", ",
+### Single character string. If PiC.type = "t" and a sample lie 
+### on the edge of 2 texture classes, then both will be outputed 
+### in a single character string, separated by 'collapse'. Example of 
+### output: [1] "C" "VF, F" "C" "C" "M"
+
+ texture2xy=FALSE,
 ### Single logical. Set to FALSE to avoid any transformation of the 
 ### texture data (trigonometric) prior to testure data classification. 
 ### Setting to FALSE avoid some numerical accuracy problems when 
 ### a point is on the border of a texture class.
-    blr.tx          = NULL, 
-    blr.clock       = NULL  
+
+ blr.tx=NULL,
+### Vector of 3 character strings. The 1st, 2nd and 3rd values must 
+### be either CLAY, SILT or SAND, and determines the particle size classes 
+### associated with the BOTTOM, LEFT and RIGHT axis, respectively. 
+### CLAY, SILT and SAND order in the vector is free, but they should 
+### all be used one time. The CLAY, SILT and SAND names must appear 
+### whatever the corresponding columns names in 'tri.data' (eventually 
+### set by 'css.names') and whatever the labels of the axis in the 
+### plot (eventually set by 'css.lab') 
+
+ blr.clock=NULL
+### Vector of logicals, eventually with NA values. Direction of 
+### increasing texture values on the BOTTOM, LEFT and RIGHT axis, 
+### respectively. A value of TRUE means that the axis direction is 
+### clockwise. A value of FALSE means that the axis direction is 
+### counterclockwise. A value of NA means that the axis direction 
+### is centripetal. Possible combinations are c(T,T,T); c(F,F,F); 
+### c(F,T,NA) and c(T,NA,F), for fully clockwise, fully counterclockwise, 
+### right centripetal and left centripetal orientations, respectively.
+
 ){  #
     if( is.null( class.sys ) ){ class.sys <- TT.get("class.sys") } 
     #
@@ -6230,12 +6409,7 @@
 
 
 
-# +-------------------------------------+
-# | FUN: TT.xy2css()                    |
-# +-------------------------------------+
-# [ TT.xy2css() :: Function to convert point-data duplets (2 variables, 
-#   x-y coordinaes) in Clay silta and sand coordinates
-TT.xy2css <- function( 
+TT.xy2css <- function(# Internal. Convert point-data duplets (2 variables, x-y coordinaes) in Clay silta and sand coordinates
     xy.data, # a data.frame with xpos and ypos columns
     geo, 
     css.names       = NULL, 
@@ -6449,7 +6623,9 @@
 
 
 
-TT.locator <- function( 
+
+
+TT.locator <- function(# Interactive (mouse clic) retrieval the CLAY SILT SAND coordinate of points on a texture triangle.
     geo, 
     css.names       = NULL, 
     #
@@ -6503,14 +6679,13 @@
 
 
 
-# +-------------------------------------+
-# | FUN: TT.xy.grid()                   |
-# +-------------------------------------+
-# [ TT.xy.grid() :: Function that create a grid in the x-y 
-#   coordinate system. Most of the function is a reshaped 
-#   extract from kde2d() from the MASS package, by 
-#   Venables & Ripley (+ modifications)
-TT.xy.grid <- function(
+
+
+
+TT.xy.grid <- function(# Internal. Create a grid in the x-y coordinate system. 
+### Create a grid in the x-y coordinate system. Most of the function 
+### is a reshaped extract from kde2d() from the MASS package, by 
+### Venables & Ripley (+ modifications)
     x,  
     y,  
     n   = 25  
@@ -6546,21 +6721,22 @@
 
 
 
-# +-------------------------------------+
-# | FUN: TT.chemometrics.alr()          |
-# +-------------------------------------+
-# [ TT.chemometrics.alr() :: Function that compute the additive 
-#   log-ratio transformation of compositional data (here texture 
-#   data). This a a copy-paste-and-rename of the alr function provided 
-#   by the package chemometrics: P. Filzmoser and K. Varmuza (2008). 
-#   chemometrics: Multivariate Statistical Analysis in Chemometrics. 
-#   R package version 0.4.
-#   The function has been modified so it returns NA when a value 
-#   is below or equal to zero (this happens when using a regular 
-#   grid of texture data, for practical reasons).
-#   The function has also been modified so it uses column name
-#   rather than column index.
-TT.chemometrics.alr <- function( 
+
+
+
+TT.chemometrics.alr <- function(# Compute the additive log-ratio transformation of compositional data.
+### Function that compute the additive 
+### log-ratio transformation of compositional data (here texture 
+### data). This a a copy-paste-and-rename of the alr function provided 
+### by the package chemometrics: P. Filzmoser and K. Varmuza (2008). 
+### chemometrics: Multivariate Statistical Analysis in Chemometrics. 
+### R package version 0.4.
+### The function has been modified so it returns NA when a value 
+### is below or equal to zero (this happens when using a regular 
+### grid of texture data, for practical reasons).
+### The function has also been modified so it uses column name
+### rather than column index.
+
     X, 
     divisorvar, 
     css.names  
@@ -6593,15 +6769,14 @@
 
 
 
-# +-------------------------------------+
-# | FUN: TT.mahalanobis()               |
-# +-------------------------------------+
-# [ TT.mahalanobis() :: Function that calculated the Mahalanobis 
-#   distance between clay silt and sand, on a regular x-y grid 
-#   (back-transformed to Clay silt and sand for Mahalanobis 
-#   calculation). The underlying function is mahalanobis() by 
-#   R Development Core Team (2009)
-TT.mahalanobis <- function( 
+
+TT.mahalanobis <- function(# Calculates the Mahalanobis distance between clay silt and sand.
+### Function that calculated the Mahalanobis 
+### distance between clay silt and sand, on a regular x-y grid 
+### (back-transformed to Clay silt and sand for Mahalanobis 
+### calculation). The underlying function is mahalanobis() by 
+### R Development Core Team (2009)
+
     # Parameter for TT.css2xy() and TT.xy2css() 
     geo,  
     tri.data,  
@@ -6756,13 +6931,14 @@
 
 
 
-# +-------------------------------------+
-# | FUN: TT.kde2d()                     |
-# +-------------------------------------+
-# [ TT.kde2d() :: Function that calculated the 2D probabilty 
-#   density on an x-y grid (and NOT on the clay silt sand 
-#   reference system).
-TT.kde2d <- function( 
+
+
+
+TT.kde2d <- function(# Calculated the 2D probabilty density on an x-y grid.
+### Function that calculated the 2D probabilty 
+### density on an x-y grid (and NOT on the clay silt sand 
+### reference system). Wrapper around the kde2d function from the 
+### MASS package.
     # Parameter for TT.css2xy() and TT.xy2css() 
     geo, 
     tri.data, 
@@ -6878,7 +7054,8 @@
 
 
 
-TT.iwd <- function( 
+
+TT.iwd <- function(# Inverse weighted distance interpolation on a grid.
     tri.data, 
     z.name, 
     geo, 
@@ -7038,14 +7215,15 @@
 
 
 
-# +-------------------------------------+
-# | FUN: TT.contour()                   |
-# +-------------------------------------+
-# [ TT.contour() :: A wrapper for the contour() function 
-#   adapted to texture triangles (plot preparation).
-#   designed to plot the results of TT.mahalanobis() or 
-#   TT.kde2d() [to be written], before or after plot.
-TT.contour <- function( 
+
+
+
+TT.contour <- function(# Wrapper for the contour() function adapted to texture triangles.
+### A wrapper for the contour() function 
+### adapted to texture triangles (plot preparation).
+### designed to plot the results of TT.mahalanobis() or 
+### TT.kde2d(), before or after plot.
+
     geo, 
     x,  #  passed to contour
     add             = FALSE,  #  also passed to contour
@@ -7221,14 +7399,15 @@
 
 
 
-# +-------------------------------------+
-# | FUN: TT.image()                     |
-# +-------------------------------------+
-# [ TT.image() :: A wrapper for the contour() function 
-#   adapted to texture triangles (plot preparation).
-#   designed to plot the results of TT.mahalanobis() or 
-#   TT.kde2d() [to be written], before or after plot.
-TT.image <- function( 
+
+
+
+TT.image <- function(# Wrapper for the contour() function adapted to texture triangles.
+### A wrapper for the contour() function 
+### adapted to texture triangles (plot preparation).
+### designed to plot the results of TT.mahalanobis() or 
+### TT.kde2d() [to be written], before or after plot.
+
     geo, 
     x,  #  passed to contour
     add             = FALSE,  #  also passed to contour
@@ -7481,12 +7660,11 @@
 
 
 
-# +-------------------------------------+
-# | FUN: TT.normalise.sum()             |
-# +-------------------------------------+
-# [ TT.normalise.sum() :: normalise the sum of the 3 particle size classes 
-#   in tri.data to text.sum (100%).
-TT.normalise.sum <- function( 
+
+
+TT.normalise.sum <- function(# Normalises the sum of the 3 particle size classes.
+### Normalises the sum of the 3 particle size classes in tri.data 
+### to text.sum (100%).
     tri.data, 
     css.names   = NULL, 
     text.sum    = NULL, 
@@ -7551,12 +7729,15 @@
 
 #     TT.normalise.sum("tri.data"=rand.text,"residuals"=TRUE)[1:20,] 
 
-# +--------------------------------------+
-# | FUN: TT.normalise.sum.X()             |
-# +--------------------------------------+
-# [ TT.normalise.sum.X() :: normalise the sum of the X particle size classes
-#   in tri.data to text.sum (100%).
-TT.normalise.sum.X <- function( 
+
+
+
+
+
+TT.normalise.sum.X <- function(# Normalises the sum of the X particle size classes.
+### Normalises the sum of the X particle size classes
+### in tri.data to text.sum (100%).
+
     tri.data, 
     text.sum    = NULL, 
     text.tol    = NULL,