% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
% | Document header                                             |
% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+

\documentclass[a4paper]{article}

\title{The soil texture wizard:\\R functions for plotting, 
    classifying, transforming and exploring soil texture data} 

\author{Julien Moeys}
% In case of changes, also change the 'PDF setup' and 
% 'cited as follow'



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
% | Nodifications of the Sweave style                           |
% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+

% Load Sweave and color, in order to modify 
% sweave's environments:

\RequirePackage{Sweave} % ,sweave,color,placeins,rotating,subfig
%\usepackage{underscore}
\SweaveOpts{width=14,height=14,keep.source=TRUE} 
% Also modified in the document

% \VignetteIndexEntry{The soil texture wizard: a tutorial}
% \VignetteDepends{soiltexture}
% \VignetteDepends{xtable}
% \VignetteKeyword{soil} 
% \VignetteKeyword{texture} 
% \VignetteKeyword{plot} 
% \VignetteKeyword{classification} 
% \VignetteKeyword{transformation} 

% Define new colors used in the document:
% \definecolor{BrickRed}{rgb}{0.502,0.000,0.000}
% \definecolor{MidnightBlue}{rgb}{0.000,0.000,0.502} 
% NB: no space after the colors

% Modify the definition of the 'Sinput' environment:
\RecustomVerbatimEnvironment{Sinput}{Verbatim}{%
%     formatcom   = \color{red},      % new text color
    frame       = leftline,         % vert line on the left
    framerule   = 0.50mm            % width of the vert line
}   %

% Modify the definition of the 'Scode' environment:
\RecustomVerbatimEnvironment{Scode}{Verbatim}{%
%     formatcom   = \color{red},      % new text color
    frame       = leftline,         % vert line on the left
    framerule   = 0.50mm            % width of the vert line
}   %

% % Modify the definition of the 'Soutput' environment:
% \RecustomVerbatimEnvironment{Soutput}{Verbatim}{%
%     formatcom = \color{blue}        % new text color
% }   %

% Modify the spacing between R code and R outputs:
\fvset{listparameters={\setlength{\topsep}{0pt}}} 
\renewenvironment{Schunk}{\vspace{\topsep}}{\vspace{\topsep}} 

\renewcommand\floatpagefraction{1.0}
\renewcommand\topfraction{1.0}
\renewcommand\bottomfraction{1.0}
\renewcommand\textfraction{0.0}   
\setcounter{topnumber}{4}
\setcounter{bottomnumber}{4}
\setcounter{totalnumber}{12}



%%% PDF setup -- fill in the title
% \usepackage[dvipdfm, bookmarks, colorlinks, breaklinks, %
%     pdftitle={The soil texture wizard:R functions for plotting, classifying, transforming and exploring soil texture data},%
%     pdfauthor={Julien MOEYS}]{hyperref}  
% \hypersetup{linkcolor=MidnightBlue, citecolor=MidnightBlue, 
%     filecolor=MidnightBlue,urlcolor=MidnightBlue} 
% From: http://malecki.wustl.edu/sweaveTemplate.Rnw

% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
% | Beginning of the real document                              |
% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+

% Don't forget to add this to path:
% C:\Program Files\_SCIENCE\R_PROJECT\share\texmf

\usepackage{Sweave}
\begin{document}
\bibliographystyle{plain}


% \graphicspath{{INOUT/}} 


%INVISIBLY sets a few options for Sweave :: KEEP THIS
<<echo=FALSE>>= 
# Set a few Sweave options:
options( 
    width       = 65,  # width of R output
    prompt      = " ", # Sign preceding R input in R-GUI
    continue    = " "  # same, but after 2nd line
)   # 

# The working directory:
# setwd("C:/_RTOOLS/SWEAVE_WORK/SOIL_TEXTURES/rforge/pkg/soiltexture/inst/doc/INOUT") 

# And load the xtable package:
library( "xtable" )
@ 

% \SweaveOpts{width=14,height=14,keep.source=TRUE}



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
% | Front page TITLE 
\maketitle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
% | Edit here                  |
% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+



<<echo=FALSE,results=hide,quiet=TRUE>>= 
old.wd  <- getwd() 

# setwd("C:/_RTOOLS/SWEAVE_WORK/SOIL_TEXTURES/rforge/pkg/soiltexture/inst/doc/INOUT") 

# if( !("soiltexture" %in%  as.character( installed.packages()[,1] )) ) 
# {   #
#     suppressMessages( 
#         install.packages( 
#             pkgs  = "soiltexture"  
#             # repos = "http://R-Forge.R-project.org" 
#         )   #
#     )   #
# }   #

suppressPackageStartupMessages( library( "soiltexture" ) )

# library( 
#     package        = "soiltexture", 
#     character.only = TRUE, 
#     quietly        = TRUE 
# )   

# setwd(old.wd) 
@ 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
% | Front page image:

<<COVERFIG,include=false,echo=FALSE,fig=TRUE>>= 
TT.plot(class.p.bg.col=T,class.sys="USDA-NCSS.TT",main=NA)
@ 

\begin{figure}[b]
\centering
\includegraphics{soiltexture_vignette-COVERFIG}
\end{figure}

\clearpage 

% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
% | Table of Content:
\tableofcontents 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\section{About this document} 



\subsection{Why creating 'The soil texture wizard'?} 

\textbf{Officially}: \textit{The Soil Texture Wizard} R functions 
are an attempt to provide a generic toolbox for soil texture data 
in R. These functions can (1) plot soil texture data (2) classify 
soil texture data, (3) transform soil texture data from and to 
different systems of particle size classes, and (4) provide some 
tools to 'explore' soil texture data (in the sense of a 
statistical visual analysis). All there tools are designed to be 
inherently multi-triangles, multi-geometry and multi-particle 
sizes classification\\

\textbf{Officiously}: What was initially a slight reshape of R 
PLOTRIX package (by J. Lemon and B. Bolker), for my personal use%
\footnote{It was also an excellent way to learn R.}, 
to add the French 'Aisne' soil texture triangle, gradually 
skidded and ended up in a totally reshaped and extended code 
(over a 3 year period). There is unfortunately no compatibility 
at all between the two codes.\\



\subsection{About R} 


This document is about functions (and package project) written in 
R "language and environment for statistical computing" (\texttt{http://www.R-project.org}) 
(\cite{RDCT2009}), and has been generated with 
\Sexpr{R.Version()$version.string}.\\

R website: <\texttt{http://www.R-project.org}>\\

If you don't know about R, it is never too later to start...\\



\subsection{About the author} 

I am an agriculture engineer, soil scientist and R programmer. 
See my website for more details (\texttt{http://julienmoeys.free.fr/}).\\

The R functions presented in this document may not always conform 
to the 'best R programming practices', they are nevertheless 
programmed carefully, well checked, and should work efficiently 
for most uses.\\

At this stage of development, some bugs should still be expected. 
The code has been written in 3 years, and tested quite extensively 
since then, but it has never been used by other people. If you 
find some bugs, please contact me at: \texttt{jules\_78-soiltexture@AT@yahoo.fr}.


% \begin{figure}[h] 
% \centering 
% \includegraphics[width=108px,viewport=0 0 382 25]{% 
%     julienmoeysmailaddress-382-25.png} 
% \end{figure} 



\subsection{Credits and License} 

This document, as well as this \textbf{document} source code 
(written in Sweave \footnote{\texttt{http://en.wikipedia.org/wiki/Sweave}}, 
R \footnote{\texttt{http://www.r-project.org}} and 
\LaTeX \footnote{\texttt{http://en.wikipedia.org/wiki/LaTeX}}) are 
licensed under a \textbf{Creative 
Commons By-SA 3.0 unported \footnote{\texttt{http://creativecommons.org/licenses/by-sa/3.0/}}}.


% \begin{figure}[h] 
% \centering 
% \includegraphics[width=88px,viewport=0 0 88 31]{% 
%     CC-By-SA-nonported-88x31.PNG} 
% \end{figure} 


In short, this means (\textit{extract from the abovementioned url at 
creativecommons.org}):

\begin{itemize} 
    \item You are free to:
    \begin{itemize} 
        \item \textbf{to Share} - to copy, distribute and 
        transmit the work;
        \item \textbf{to Remix} - to adapt the work.
    \end{itemize} 
    \item Under the following conditions:
    \begin{itemize} 
        \item \textbf{Attribution} - You must attribute the work 
        in the manner specified by the author or licensor (but 
        not in any way that suggests that they endorse you or 
        your use of the work);
        \item \textbf{Share Alike} - If you alter, transform, or 
        build upon this work, you may distribute the resulting 
        work only under the same, similar or a compatible 
        license.
    \end{itemize} 
\end{itemize} 

'The soil texture wizard' R \textbf{functions} are licensed under 
a Affero GNU General Public License Version 3 (\texttt{http://www.gnu.org/licenses/agpl.html}).\\

Given the fact that a lot of the work presented here has been done 
on my free time, and given its highly permissive license, \textbf{% 
this document is provided with NO responsibilities, guarantees or 
supports from the author or his employer} (Swedish University of 
Agricultural Sciences).\\

Please notice that the R software itself is licensed under a GNU 
General Public License Version 2, June 1991.\\

This tutorial has been created with the (great) \textbf{Sweave} 
tool, from Friedrich Leisch (\cite{SWEAVE2002}). Sweave allows the 
smooth integration of R code and R output (including figures) in 
a \LaTeX document.



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\section{Introduction: About soil texture, texture triangles 
    and texture classifications} 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{What are soil granulometry and soil texture(s)?} 

\textbf{Soil granulometry} is the repartition of soil solid 
particles between (a range of) particle sizes. As the range of 
particle sizes is in fact continuous, they have been subdivided 
into different \textbf{particle size classes}.\\

The most common subdivision of soil granulometry into classes is 
the \textbf{fine earth}, for particles ranging from \textbf{0 to 
2mm (2000$\mu$m)}, and \textbf{coarse particles}, for 
particles bigger than \textbf{2mm}. Only the fine earth interests 
us in this document, although the study of soil granulometry can 
be extended to the coarse fraction (for stony soils).\\

\textbf{Fine earth} is generally (but not always; see below) divided 
into \textbf{3 particle size classes: clay (fine particles), silt 
(medium size particles) and sand (coarser particles in the fine 
earth)}. All soil scientists use the range \textbf{0-2$\mu$m} for 
\textbf{clay}. So silt lower limit is also always 
\textbf{2$\mu$m}. But the convention for \textbf{silt / sand} 
particle size limit \textbf{varies from country to country}. 
\textbf{Silt} particle size range can be \textbf{2-20$\mu$m} 
(Atterberg system\cite{MINASNY2001AJSR}\cite{RICHER2008INRA}; 
'International system'; ISSS\footnote{ISSS: International Society 
of Soil Science. Now  IUSS (\texttt{www.iuss.org}), International 
Union of Soil Science}\label{ISSSSIZE}. The ISSS particle size 
system should not be confused with the ISSS texture triangle (See 
\ref{ISSSTRIANGLE}, p. \pageref{ISSSTRIANGLE}); Australia\footnote{%%%
Strangely, only a 
small number of countries have adopted the so called 
'international system'}\cite{MINASNY2001AJSR}; Japan% 
\cite{RICHER2008INRA}), \textbf{2-50$\mu$m} (FAO\footnote{% 
Food and Agriculture Organization of the United Nations 
(\texttt{www.fao.org})}; USA; France\cite{MINASNY2001AJSR}% 
\cite{RICHER2008EGS}), \textbf{2-60$\mu$m} 
(UK and Sweden\cite{RICHER2008INRA}) or \textbf{2-63$\mu$m} 
(Germany, Austria, Denmark and The Netherlands% 
\cite{RICHER2008INRA}). Logically, \textbf{sand} particle size 
range also varies accordingly to these systems: 
\textbf{20-2000$\mu$m}, \textbf{50-2000$\mu$m}, 
\textbf{60-2000$\mu$meters} or \textbf{63-2000$\mu$meters}.\\

\textbf{Silt} class is sometimes divided into \textbf{fine silts} 
and \textbf{coarse silts}, and \textbf{sand} class is sometimes 
divided into \textbf{fine sand} and \textbf{coarse sand}, but in 
this document / package, we only focus on clay / silt / sand 
classes.\\ 

Below is a scheme representing the different particle size 
classes used in France (with Cl for Clay, FiSi for Fine Silt, 
CoSi for Coarse Silt, FiSa for Fine Sand, CoSa for Coarse Sand, 
Gr for Gravels and St for Stones). The figure is adapted 
from Moeys 2007\cite{MOEYS2007}, and based on information from 
Baize \& Jabiol 1995\cite{BAIZE1995}. The particle size axis 
(abscissa) is log-scale:


\SweaveOpts{width=14,height=4,keep.source=TRUE}
<<echo=FALSE,fig=TRUE,include=TRUE>>= 
bornes <- c(0,2,20,50,200,2e3,20e3)
noms   <- c("Cl","FiSi","CoSi","FiSa","CoSa","Gr","St")
txt.b  <- expression( 0*mu*m, 2*mu*m, 20*mu*m, 50*mu*m, 200*mu*m, 2*'mm', 2*'cm')

tmp <- data.frame(bornes,noms) # ,txt.b
#tmp$"txt.b" <- as.character(tmp$"txt.b")

par(  "mar"=c(4,1,1,1)+0.1  )  #  c(bottom, left, top, right)

plot( 
	x		= tmp$"bornes"[-1],  
	y		= rep(1,dim(tmp[-1,])[1]),  
	type	= "n",  
	main	= "",  
	xlab	= "Soil particule sizes",  
	ylab	= "",  
	yaxt	= "n",  xaxt = "n",  
	log		= "x",  
	xlim	= c(0.2,75e3), 
	bty		= "n", 
	cex.lab = 2  
)	#

abline(v=tmp$"bornes",lty=3,lwd=c(2,4,2,4,2,4,2))
abline(h=par("usr")[3:4],lty=1,lwd=4)

mtext( 
    text    = txt.b[-1], 
    side    = 1, 
    line    = rep( 
        c(0.5,1.25), 
        (dim(tmp)[1]-1)/2
    ),  #
    at  = tmp$"bornes"[-1], 
    cex = 2  
)   #

xtxt <- (tmp$"bornes"[1:(length(tmp$"bornes"))]+c(tmp$"bornes"[2:length(tmp$"bornes")],75e3))/2

text(x=xtxt,y=rep(1,length(xtxt)),labels=tmp$"noms",cex=2) 
@ 
\SweaveOpts{width=14,height=14,keep.source=TRUE}


Soil particles -- and each soil particle size class -- occupy a 
given volume in the soil, and have a given mass. They are 
nevertheless generally not expressed as 'absolute' volumetric 
quantities\footnote{for instance kilograms of clay per liters of 
soil', or 'liters of clay per liter of soil'}. They are expressed 
as \textbf{'relative abundance'}, that is \textbf{kilograms of 
particles of a given class per kilograms of fine earth}. These 
measurements are also always made on dehydrated soil samples 
(dried slightly above $100^{\circ}\mathrm{C}$), in order to be 
independent from soil water content (which varies a lot in time 
and space).\\

\textbf{Soil texture} is defined as the relative abundance of the 
3 particle size classes: clay, silt and sand\footnote{But some 
systems define for than 3 particle size classes for soil texture}.\\

\textit{In summary}, important information to know when talking 
about soil texture (and using these functions):

\begin{itemize}
    \item Soil's fine earth is generally (but not always) divided 
        into 3 soil texture classes: 
    \begin{itemize} 
        \item Clay; 
        \item Silt; 
        \item Sand.
    \end{itemize} 
    \item The silt / sand limit varies: 
    \begin{itemize} 
        \item 20$\mu$m; or 
        \item 50$\mu$m; or 
        \item 60$\mu$m; or 
        \item 63$\mu$m.
    \end{itemize} 
    \item Soil texture measurement do have a specific unit and a 
        corresponding 'sum of the 3 texture classes', that is 
        constant:
    \begin{itemize} 
        \item in \% or $g.100g^{-1}$ (sum: 100); or 
        \item in fraction $[-]$ or $kg.kg^{-1}$ (sum: 1); or 
        \item in $g.kg^{-1}$ (sum: 1000); 
    \end{itemize} 
\end{itemize}


\textbf{More than 3 particle size classes?}\\

Some country have a particle size classes system that differ from 
the common 'clay silt sand' triplet. Sweden is using a system 
with 4 particle size classes: Ler [0-2$\mu$m], Mj\"ala [2-20$\mu$m], 
Mo [20-200$\mu$m] and Sand [200-2000$\mu$m] (See table 1 p.9 in 
Lidberg 2009\cite{LIDBERG2009}). 
Ler corresponds to clay. When considering the International or 
Australian particle size system (silt-sand limit 20$\mu$m), Mj\"ala 
is silt, and 'Mo + Sand' is sand. When considering other systems 
with a silt-sand limit at 50$\mu$m, 60$\mu$m or 63$\mu$m, Mj\"ala 
is ~fine-silt, Mo is ~'coarse-silt + fine sand', and Sand is 
~coarse-sand.\\

'The Soil Texture Wizard' has been made for systems with 3 
particle size classes (clay, silt and sand), \textbf{because soil 
texture triangles have 3 sides, and thus can only represent 
texture data that are divided into 3 particle size classes}. 
There are methods to estimate 3 particle size classes when more 
classes are presented in the data (although the best is to 
measure texture so it also can fit a system with 3 particle size 
classes system).



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{What are soil texture triangle and classes} 

Soil texture triangles are also called \textbf{soil texture 
diagrams}.\\

Soil texture can be plotted on a \textbf{ternary plot} (also 
called triangle plot). In a ternary plot, 3D coordinates, which 
sum is constant, are projected in the 2D space, using simple 
trigonometry rules. The texture of a soil sample can be plotted 
inside a texture triangle, as shown in the example below for 
the texture 45\% clay, 38\% silt and 17\% sand:


<<echo=FALSE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    class.sys   = "none", 
    tri.data    = data.frame( 
        "CLAY"  = 45, 
        "SILT"  = 38, 
        "SAND"  = 17 
    ),  #
    main        = NA  
)   #
@ 


When mapping soil, field pedologists usually estimate texture by 
manipulating a moist (but not saturated) soil sample in their 
hand. Depending on the relative importance of clay silt and sand, 
the mechanical properties of the soil (plasticity, stickyness, 
roughness) varies. Pedologists have 'classified' clay silt and 
sand relative abundance as a function of what they could feel in 
the field: they have divided the 'soil texture space' into 
classes.\\

\textbf{Soil particle size classes (clay, silt and sand)} should 
not be confused with \textbf{soil texture classes}. While the 
first are ranges of particle sizes, the latter are defined by a 
'range of clay, silt and sand' (see the graph below). Soil 
texture should not be confused with the concept of \textbf{soil 
structure}, that concerns the way these particles are arranged 
together (or not) into peds, clods and aggregates (etc.) of 
different size and shape\footnote{In the same way bricks and 
cement (the texture) can be arranged into a house (the structure)}. 
This document does not deal with soil structure.\\

Soil texture classes are convenient to represent soil texture 
on soil maps\footnote{It is more easy to represent 1 variable, 
soil texture class, than 3 variables: clay silt and sand}, and 
there use is quite broad (soil description, soil classification, 
pedogenesis, soil functional properties, pedotransfer functions, 
etc.). One of these texture classification systems is the one used
for the European Soil Map (HYPRES). Here is the representation of 
the same point as in the graph above, but with the 
European Soil Map (HYPRES) texture classification system on the 
background (\footnote{I had previously erroneously named that system 
"The FAO system". I realised (and was told) that this is not the 
FAO system. The real FAO system is in fact similar (identical?) 
to the USDA system}).

<<echo=FALSE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    class.sys   = "HYPRES.TT", 
    tri.data    = data.frame( 
        "CLAY"  = 45, 
        "SILT"  = 38, 
        "SAND"  = 17 
    ),  
    main        = NA  
)   
@ 

The soil texture class symbols are:

<<echo=FALSE>>= 
library( "xtable" ) 
@ 

<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "HYPRES.TT" ) 
xtable( 
    x       = tex.tbl[,-3],  #
    caption = "Texture classes of the European system / triangle", 
    label   = NULL  
)   #
@ 

The main characteristics of the graph (texture triangle) are:

\begin{itemize}
    \item 3 Axis, graduated from 0 to 100\%, each of them 
    carrying 1 particle size class.
    \begin{itemize} 
        \item Sand on the bottom axis; 
        \item Clay on the left axis; 
        \item Silt on the right axix.
    \end{itemize} 
    \item It is possible to permute clay, silt and sand axis, but 
    this choice depend on the particle size classification used.
    \item Inside the triangle, the lines of equi-values for a 
    given axis/particle size class are ALWAYS parallel to the 
    (other) axis that intersect the axis of interest at 'zero' 
    (minimum value).
    \item The 3 axis intersect each other in 3 submits, that are 
    characterized by an \textbf{angle}. In the example above, all 
    3 angles are 60 degrees. But other angles are possible, 
    depending on the soil texture classification used. It is for 
    instance possible to have a 90 degrees angle on the left, and 
    45 degrees angles on the top and on the right (right-angled 
    triangle).
    \item The 3 axis have a \textbf{direction} of increasing 
    texture abundance. This direction is often referred as 
    'clock' or 'anticlock', but they can also be directed 'inside'
    the triangle in some cases. In the example 
    above, all the axis are clockwise: texture increase when 
    rotating in the opposite direction as a clock.
    \item \textbf{Labeled ticks} are placed at regular intervals 
    (10\%) on     the texture triangle axes, apart if the axis is 
    directed inside the triangle. Ticks can be placed at irregular 
    intervals if they are placed at each value taken by the 
    texture class polygons vertices (This is a smart 
    representation, unfortunately not implemented here).
    \item An \textbf{broken arrow} is drawn 'parallel' to each 
    axis. The first part indicate the direction of increasing 
    value, and the second, broken, part indicates the direction of 
    the equi-value for that axis/texture class.
    \item The \textbf{axis labels} indicates the texture class 
    concerned, and should ideally remind the particle size limits, 
    because these limits are of crucial importance when (re)using 
    soil texture data (Silt and Sand does not exactly mean the 
    same particle size limits everywhere).
    \item \textbf{Soil texture class boundaries} are drawn inside 
    the triangle. They are 2D representation of 3D limits. They 
    are generally \textbf{labeled} with soil texture class 
    abbreviations (or full names).
    \item Inside the triangle frame, a grid can be represented, 
    for each ticks and ticks label drawn outside the triangle.
\end{itemize}



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\section{Installing the package} 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Installing the package from r-forge} 


The Soil Texture Wizard is now available on CRAN 
\footnote{\texttt{http://cran.r-project.org/package=soiltexture}} 
and r-forge \footnote{\texttt{http://r-forge.r-project.org/}}, under 
the project name "soiltexture". The package can be installed from 
CRAN with the following commands:


<<echo=TRUE,eval=FALSE>>= 
install.packages( pkgs = "soiltexture" ) 
@ 


And \textbf{if you have the latest R version} installed, and want 
the latest development version of the package, from r-forge, type 
the following commands:


<<echo=TRUE,eval=FALSE>>= 
install.packages( 
    pkgs  = "soiltexture", 
    repos = "http://R-Forge.R-project.org" 
)   
@ 


It can then be loaded with the following command:


<<echo=TRUE>>= 
library( soiltexture ) 
@ 


If you get bored of the package, you can unload it and uninstall 
it with the following commands:


<<echo=TRUE,eval=FALSE>>= 
detach( "package:soiltexture" ) 
remove.packages( "soiltexture" ) 
@ 


If you don't have the latest R version, please try to install the 
package from the binaries. In the next section, an example is given 
for R under MS Windows systems (Zip binaries).



% % +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
% \subsection{Installing the package from Windows binaries (.zip)} 


% To install and load the package directly from 
% \href{"http://r-forge.r-project.org/bin/windows/contrib/2.10/soiltexture_1.0.zip"}%%%
% {r-forge zip binaries}, 
% you can type the following command:


% <<echo=TRUE,eval=FALSE>>= 
% download.file( 
%     url = 
% "http://r-forge.r-project.org/bin/windows/contrib/2.10/soiltexture_1.0.zip", 
%     destfile = file.path( getwd(), "soiltexture_1.0.zip" ) 
% )   #
% #
% install.packages( 
%     pkgs  = file.path( getwd(), "soiltexture_1.0.zip" ), 
%     repos = NULL 
% )   #
% #
% file.remove( "soiltexture_1.0.zip" ) 
% @ 


% \textbf{Where 2.10 should be replaced by the latest stable R 
% version and 1.0 by the latest package version on r-forge}. 



% % +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
% \subsection{Load the latest package sources} 


% If all the options above failed to intall the soiltexture package, 
% you can still load the 
% \href{http://r-forge.r-project.org/plugins/scmsvn/viewcvs.php/*checkout*/pkg/soiltexture/R/soiltexture.r?root=soiltexture}%%%
% {latest package sources} in R by using the 
% following command:


% <<echo=TRUE,eval=FALSE>>= 
% source( 
%     paste( 
%         sep = "", 
%         "http://r-forge.r-project.org/scm/viewvc.php/*checkout*", 
%         "/pkg/soiltexture/R/soiltexture.R?&root=soiltexture"
%     )   #
% )   #
% @ 


% The examples shown in this vignette are ran with these sources.



% % +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
% \subsection{Set the work directory} 


% Here is the working directory we are using in this package vignette 
% (choose the one you like...):

% <<echo=TRUE>>= 
% # setwd("C:/_RTOOLS/SWEAVE_WORK/SOIL_TEXTURES/rforge/pkg/soiltexture/inst/doc/INOUT") 
% @ 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\section{Plotting soil texture triangles and classification 
    systems} 

The package comes with 8 predefined soil texture triangles. Empty %%% THINGS TO CHECK HERE: NB TRIANGLES
(i.e. without soil textures data) soil texture triangles can be 
plotted, in order to obtain smart representation of the soil 
texture classification. Of course, it is also possible to plot 
'classification free' texture triangles.



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{An empty soil texture triangle} 

Below is the code to display an empty triangle (without 
classification and without data):


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "none" ) 
@ 


The option \texttt{class.sys} (characters) determines the soil 
texture classification system used. If set to \texttt{'none'}, 
an empty soil texture triangle is plotted.\\

Without further options, the plotted default soil texture 
triangle has the same geometry as the European Soil Map (HYPRES), 
USDA or French 'Aisne' soil texture triangles (i.e. all axis are 
clockwise, all angles are 60 degrees, sand is on the bottom axe, 
clay on the left and silt on the right).\\

The default unit is always percentage (0 to 100\%). It is also 
equivalent to $g.100g^{-1}$.



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{The USDA soil texture classification} 

To display a USDA texture triangle, type:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "USDA.TT" ) 
@ 


When the option \texttt{class.sys} is set to \texttt{"USDA.TT"}, 
a soil texture triangle with USDA classification system is used.\\

The USDA soil texture triangle has been built considering a 
silt - sand limit of 
\Sexpr{TT.get("USDA.TT")[["base.css.ps.lim"]][3]}$\mu$meters.\\ 

See the table for soil texture classes symbols.\\


<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "USDA.TT" ) 
xtable( 
    x       = tex.tbl[,-3],  #
    caption = "Texture classes of the USDA system / triangle", 
    label   = NULL  
)   #
@ 


The reference used to digitize this triangle is the Soil Survey 
Manual (Soil Survey Staff 1993\cite{USDA1993}).\\

[2017-09-27] The triangle above uses classes-labels that are not 
the one commonly used by US authorities (such as NCSS), 
so a 'duplicate' of the same triangle has been added, but this 
time with classes-labels better reflecting current practices 
by practiioners. The triangle has otherwise exactly the same 
definition as \texttt{"USDA.TT"}. It is named 
\texttt{"USDA-NCSS.TT"} (class labels suggested by Dylan 
Beaudette, NCSS). To use it, type:

<<echo=TRUE,eval=FALSE>>= 
TT.plot( class.sys = "USDA-NCSS.TT" ) 
@ 

(See the cover-page of this document for an example)

\clearpage % otherwise the table may 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Whitney 1911 USDA soil texture classification} 

To display a Whitney (1911) version of the USDA texture triangle, 
type:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "USDA1911" ) 
@ 


The Whitney USDA 1911 soil texture triangle has been built 
considering a silt - sand limit of 
\Sexpr{TT.get("USDA1911")[["base.css.ps.lim"]][3]}$\mu$meters, 
and a \textbf{clay - silt limit of 
\Sexpr{TT.get("USDA1911")[["base.css.ps.lim"]][2]}$\mu$meters 
(Notice the difference with the actual USDA triangle)}\\ 

See the table for soil texture classes symbols.\\


<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "USDA1911" ) 
xtable( 
    x       = tex.tbl[, -3 ],  #
    caption = "Texture classes of the Whitney 1911 system / triangle", 
    label   = NULL  
)   #
@ 


This triangle has been kindly digitised and provided by Nic 
Jelinski (University of Minnesota, USA). The original reference 
used to digitise this triangle is the Whitney 1911\cite{WHITNEY1911}.

\clearpage % otherwise the table may 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{The European Soil Map (HYPRES) soil texture classification} 

\textbf{NOTE: I had previously erroneously named that system 
"The FAO system". I realised (and was told) that this is not the 
FAO system. The real FAO system is similar (identical?) to 
the USDA system.} The triangle code has thus been changed from 
\texttt{FAO50.TT} to \texttt{HYPRES.TT}. Using \texttt{FAO50.TT} 
still works, but gives a warning.\footnote{De Forges et al. 
2008\cite{RICHER2008EGS} pointed out the fact that the silt-sand 
particle size limit that is officially related to the FAO soil 
texture triangle has changed over time, 50$\mu$m, then 63$\mu$m, 
and then again 50$\mu$m for some projects.}\\

To display a European Soil Map (HYPRES) texture triangle, type:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "HYPRES.TT" ) 
@ 





% We here consider that the European Soil map (HYPRES) soil texture 
% triangle has a silt - sand limit of 
% \Sexpr{TT.get("HYPRES.TT")[["base.css.ps.lim"]][3]}$\mu$m. As this 
% choice is somehow arbitrary, we have named the 'EU' option 
% \texttt{"HYPRES.TT"} in order to avoid any confusion. It will be 
% explained later in the document how it is possible to add a custom 
% texture triangle to the existing list, that could for instance be 
% used to configure an EU texture triangle with another silt - 
% sand limit.\\ 

See the table for soil texture classes symbols.\\


<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "HYPRES.TT" ) 
xtable( 
    x       = tex.tbl[,-3],  #
    caption = "Texture classes of the European system / triangle", 
    label   = NULL  
)   #
@ 


The references used to digitize this triangle is the texture 
triangle provided by the HYPRES project web site 
(\cite{HYPRES2009}). The The Canadian Soil Information System 
(CanSIS) also provides some details on this triangle 
(\cite{CANSIS2009}).

\clearpage % otherwise the table may 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{The French 'Aisne' soil texture classification} 

To display a French 'Aisne' texture triangle, type:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "FR.AISNE.TT" ) 
@ 


The French Aisne soil texture triangle has been built 
considering a silt - sand limit of 
\Sexpr{TT.get("FR.AISNE.TT")[["base.css.ps.lim"]][3]}$\mu$meters.\\ 

See the table for soil texture classes symbols\footnote{In 
classes 14 and 15, 'leger' should be replaced by 'l\'eger'. R (and 
Sweave) can not display french accents easily, and I found no easy 
trics for displaying them.}.\\


<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "FR.AISNE.TT" ) 
xtable( 
    x       = tex.tbl[,-3],  #
    caption = "Texture classes of the French 'Aisne' system / triangle", 
    label   = NULL  
)   #
@ 

The references used for digising this triangle is Baize and 
Jabiol 1995\cite{BAIZE1995} and Jamagne 1967\cite{JAMAGNE1967}. 
This triangle may be referred as the 'Triangle des textures de la 
Chambre d'Agriculture de l'Aisne' (en: texture triangle of the 
Aisne extension service).

\clearpage % otherwise the table may 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{The French 'GEPPA' soil texture classification} 

To display a French 'GEPPA' texture triangle, type:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "FR.GEPPA.TT" ) 
@ 


The French GEPPA soil texture triangle has been built 
considering a silt - sand limit of 
\Sexpr{TT.get("FR.GEPPA.TT")[["base.css.ps.lim"]][3]}$\mu$meters.\\ 

See the table for soil texture classes symbols.\\


<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "FR.GEPPA.TT" ) 
xtable( 
    x       = tex.tbl[,-3],  #
    caption = "Texture classes of the French 'GEPPA' system / triangle", 
    label   = NULL  
)   #
@ 


This triangle has been digitized after 
\texttt{sols-de-bretagne.fr} 2009\cite{SOLBRETAGNE2009}. The 
website refers to an illustration from Baize and Jabiol 1995%
\cite{BAIZE1995}. 'GEPPA' means 'Groupe d'Etude pour les 
Probl\`emes de P\'edologie Appliqu\'ee' (en: Group for the study of 
applied pedology problems / questions).

\clearpage % otherwise the table may 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{The German Bodenartendiagramm (B.K. 1994) soil 
    texture classification} 

To display a German Bodenartendiagramm (BK 1994) texture triangle, 
type:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "DE.BK94.TT" ) 
@ 


The German Bodenartendiagramm (BK 1994) soil texture triangle has 
been built considering a silt - sand limit of 
\Sexpr{TT.get("DE.BK94.TT")[["base.css.ps.lim"]][3]}$\mu$meters.\\ 

See the table for soil texture classes symbols.\\


<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "DE.BK94.TT" ) 
xtable( 
    x       = tex.tbl[,-3],  #
    caption = "Texture classes of the German system / triangle", 
    label   = NULL  
)   #
@ 

The references used to digitize this triangle and name the 
classes are \texttt{de.wikipedia.org} 2009 \cite{WIKIPEDIADE2009} 
and \texttt{nibis.ni.schule.de} 2009\cite{BK94ANONYM}. The 
triangle is also presented in GEOVLEX 2009\cite{GEOVLEX2009} 
(Online lexicon from the Halle-Wittenberg University) and Bormann 
2007\cite{BORMANN2007} (for quadruple check). The 
triangle is referred as Bodenartendiagramm 'Korngr\"o\ss endreieck' 
from Bodenkundliche Kartieranleitung 1994.

\clearpage % otherwise the table 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{The German 'Standortserkundungsanweisung' (SEA 1974) %
    soil texture classification for forest soils} 

To display a German 'Standortserkundungsanweisung' (SEA 1974) 
texture triangle for forest soils\cite{SEA1974}, type:



<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "DE.SEA74.TT" ) 
@ 



<<echo=FALSE,results=hide,quiet=TRUE>>= 
plLim <- TT.get("DE.SEA74.TT")[["base.css.ps.lim"]][3]
@ 

The SEA 1974 soil texture classification has been built 
considering a silt - sand limit of 
\Sexpr{plLim}$\mu$meters.\\


See the table for soil texture classes symbols:


<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "DE.SEA74.TT" ) 
xtable( 
    x       = tex.tbl[,-3],  #
    caption = "Texture classes of the German SEA 1974 system / triangle", 
    label   = NULL  
)   #
@ 


Many thanks to Rainer Petzold (Staatsbetrieb Sachsenforst) for 
providing the code of this triangle.\\

Note (2013/01/10): Prior to version 1.2.13, the triangle has a 
missing vertex in classes "lehmiger Ton" (lT) and "schluffiger Ton"
(uT). This Vertex (no 26 in the triangle definition) has been added 
from version 1.2.13.\\

The original isosceles version of the triangle can be obtained by typing:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    class.sys = "DE.SEA74.TT", 
    blr.clock   = rep(T,3), 
    tlr.an      = rep(60,3), 
    blr.tx      = c("SAND","CLAY","SILT"), 
)   #
@ 

\clearpage % otherwise the table may 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{The German 'landwirtschaftliche B\"{o}den' (TGL 24300-05, 1985) %
    soil texture classification for arable soils} 

To display a German TGL 1985 texture triangle for arable soils\cite{TGL1985}, 
type:



<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "DE.TGL85.TT" ) 
@ 



<<echo=FALSE,results=hide,quiet=TRUE>>= 
plLim <- TT.get("DE.TGL85.TT")[["base.css.ps.lim"]][3]
@ 

The TGL 1985 soil texture classification has been built 
considering a silt - sand limit of 
\Sexpr{plLim}$\mu$meters.\\


See the table for soil texture classes symbols:


<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "DE.TGL85.TT" ) 
xtable( 
    x       = tex.tbl[,-3],  #
    caption = "Texture classes of the German TGL 1985 system / triangle", 
    label   = NULL  
)   #
@ 


Many thanks to Rainer Petzold (Staatsbetrieb Sachsenforst) for 
providing the code of this triangle.


The original isosceles version of the triangle can be obtained by typing:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    class.sys = "DE.TGL85.TT", 
    blr.clock   = rep(T,3), 
    tlr.an      = rep(60,3), 
    blr.tx      = c("SAND","CLAY","SILT"), 
)   #
@ 

\clearpage % otherwise the table may 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{UK Soil Survey of England and Wales texture 
    classification} 

To display a Soil Survey of England and Wales texture triangle 
(UK), type:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "UK.SSEW.TT" ) 
@ 


UK Soil Survey of England and Wales texture triangle has been 
built considering a silt - sand limit of 
\Sexpr{TT.get("UK.SSEW.TT")[["base.css.ps.lim"]][3]}$\mu$meters.\\ 

See the table for soil texture classes symbols.\\

<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "UK.SSEW.TT" ) 
xtable( 
    x       = tex.tbl[,-3],  #
    caption = "Texture classes of the UK system / triangle", 
    label   = NULL  
)   #
@ 

The reference used to digitize this triangle is Defra -- Rural 
Development Service -- Technical Advice Unit 2006\cite{DEFRA2006} 
(Technical Advice Note 52 -- Soil texture).

\clearpage % otherwise the table may 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{The Australian soil texture classification} 

To display an Autralian texture triangle, type:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "AU2.TT" ) 
@ 


The Australian soil texture classification has been built 
considering a silt - sand limit of 
\Sexpr{TT.get("AU2.TT")[["base.css.ps.lim"]][3]}$\mu$meters.\\ 

See the table for soil texture classes symbols.


<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "AU2.TT" ) 
xtable( 
    x       = tex.tbl[,-3],  #
    caption = "Texture classes of the Australian system / triangle", 
    label   = NULL  
)   #
@ 


There are probably small errors in the exact placement of some 
texture classes vertices (expected to be 1 or 2\% of the 'exact 
value'), due to technical difficulties for reproducing precisely 
this triangle (reproduced after both Minasny and McBratney 
2001\cite{MINASNY2001AJSR}, and Holbeche 2008\cite{HOLBECHE2008} 
(brochure 'Soil Texture-Laboratory Method' from soilquality.org.au 
\footnote{\texttt{http://soilquality.org.au}}).\\

\clearpage % otherwise the table may 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{The Belgian soil texture classification} 

To display an Belgium texture triangle, type:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "BE.TT" ) 
@ 


The Belgian soil texture classification has been built 
considering a silt - sand limit of 
\Sexpr{TT.get("BE.TT")[["base.css.ps.lim"]][3]}$\mu$meters.\\ 

See the table for soil texture classes symbols\footnote{In 
classes 5, 'leger' should be replaced by 'l\'eger'. R (and 
Sweave) can not display french accents easily, and I found no easy 
trics for displaying them.}. The class names are given in French 
and in Flemish.


<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "BE.TT" ) 
xtable( 
    x       = tex.tbl[,-3],  #
    caption = "Texture classes of the Belgian system / triangle", 
    label   = NULL  
)   #
@ 


This texture triangle has been built after images from Defourny 
et al.\cite{DEFOURNY2009} and Van Bossuyt\cite{BOSSUYT2009}.\\

\clearpage % otherwise the table may 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{The Canadian soil texture classification} 

To display a Canadian texture triangle with English texture class 
abbreviations, type:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "CA.EN.TT" ) 
@ 


For the same triangle with French texture class abbreviations type:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "CA.FR.TT" ) 
@ 


The Canadian soil texture classification has been built 
considering a silt - sand limit of 
\Sexpr{TT.get("CA.EN.TT")[["base.css.ps.lim"]][3]}$\mu$meters 
(\footnote{\texttt{http://sis.agr.gc.ca/cansis/glossary/separates,\_soil.html}}; 
\cite{CANSIS2010}).\\ 

See the table for soil texture classes symbols, in English:


<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "CA.EN.TT" ) 
xtable( 
    x       = tex.tbl[,-3],  #
    caption = "Texture classes of the Canadian (en) system / triangle", 
    label   = NULL  
)   #
@ 


Or in French:


<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "CA.FR.TT" ) 
xtable( 
    x       = tex.tbl[,-3],  #
    caption = "Texture classes of the Canadian (fr) system / triangle", 
    label   = NULL  
)   #
@ 



A reference image for this texture triangle can be found in 
\texttt{sis.agr.gc.ca} \footnote{%%%
\texttt{http://sis.agr.gc.ca/cansis/glossary/texture,\_soil.html\#figure1}} 
(not the one used for digitizing the triangle), 
and the boundaries have been checked with those given on the same 
web-page \cite{CANSIS2010}.\\

\clearpage % otherwise the table may 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{The ISSS soil texture classification} 

To display a ISSS\footnote{ISSS: International Soil Science Society. 
Now IUSS, International Union of Soil Science. The ISSS soil texture 
classification / triangle should not be confused with the ISSS 
particle size classification (See \ref{ISSSSIZE}, p. \pageref{ISSSSIZE})}%%%
\label{ISSSTRIANGLE} texture triangle, type:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "ISSS.TT" ) 
@ 



The ISSS soil texture classification has been built 
considering a silt - sand limit of 
\Sexpr{TT.get("ISSS.TT")[["base.css.ps.lim"]][3]}$\mu$meters.\\


See the table for soil texture classes symbols:


<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "ISSS.TT" ) 
xtable( 
    x       = tex.tbl[,-3],  #
    caption = "Texture classes of the ISSS system / triangle", 
    label   = NULL  
)   #
@ 


Many thanks to Wei Shangguan (School of geography, Beijing 
normal university) for providing the code of the ISSS triangle 
(using an article from Verheye and Ameryckx 1984\cite{VERHEYE1984PEDO}).

\clearpage % otherwise the table may 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{The Romanian soil texture classification} 

To display a Romanian texture triangle, type:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "ROM.TT" ) 
@ 



The Romanian soil texture classification has been built 
considering a silt - sand limit of 
\Sexpr{TT.get("ROM.TT")[["base.css.ps.lim"]][3]}$\mu$meters.\\


See the table for soil texture classes symbols:


<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "ROM.TT" ) 
xtable( 
    x       = tex.tbl[,-3],  #
    caption = "Texture classes of the Romanian system / triangle", 
    label   = NULL  
)   #
@ 


Many thanks to Rosca Bogdan (Romanian Academy, Iasi Branch, 
Geography team) for providing the code of the Romanian triangle.\\


A right angled version of the triangle can be obtained by typing:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    class.sys = "ROM.TT", 
    blr.clock   = c(F,T,NA), 
    tlr.an      = c(45,90,45), 
    blr.tx      = c("SILT","CLAY","SAND"), 
)   #
@ 

\clearpage % otherwise the table may 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Polish soil texture classification (PTG 1956-1959)} 

Note: several versions or variants of polish soil texture 
triangles have been used and are used nowadays, which may 
cause some confusion.
The triangle presented in this section is refered to here 
as PTG 1956-1959, but the name may not be an official 
denomination.

To display this texture triangle (Systematyka gleb Polski, 
1989, for non-alluvial soils), type:


% <<echo=TRUE,fig=TRUE,include=TRUE>>= 
% if( Sys.info()["sysname"] != "Mac" ){ 
%     TT.plot( class.sys = "PL.TT" ) 
% }   #
% @ 


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
test <- try( TT.plot( class.sys = "PL.TT" ) ) 

#   In case the polish triangle was not loaded at startup
if( "try-error" %in% class(test) ){ 
    plot(1,1,type="n",) 
    text(1,1,label="Plotting failed. Polish triangle not loaded")
}   
@ 



NB: \textit{Due to encoding issues, the Polish triangle 
with be displayed with original polish character under Windows 
and Linux systems only. For other platforms (Mac, freeBSD) 
only latin character are used}.\\



% <<echo=FALSE,results=hide,quiet=TRUE>>= 
% if( Sys.info()["sysname"] != "Mac" ){ 
%     if( Sys.info()["sysname"] != "Mac" ){
%         plLim <- TT.get("PL.TT")[["base.css.ps.lim"]][3]
%     }else{
%         plLim <- "..." 
%     }   # 
% }   #
% @ 



<<echo=FALSE,results=hide,quiet=TRUE>>= 
test <- try( plLim <- TT.get("PL.TT")[["base.css.ps.lim"]][3] ) 
if( "try-error" %in% class(test) ){ plLim <- NA_real_ }
@ 

The Polish soil texture classification has been built 
considering a silt - sand limit of 
\Sexpr{plLim}$\mu$meters.\\


See the table for soil texture classes symbols:


% <<echo=FALSE,results=tex>>= 
% if( Sys.info()["sysname"] != "Mac" ){ 
%     tex.tbl <- TT.classes.tbl( class.sys = "PL.TT" ) 
%     xtable( 
%         x       = tex.tbl[,-3],  #
%         caption = "Texture classes of the Polish system / triangle", 
%         label   = NULL  
%     )   #
% }   #
% @ 


<<echo=FALSE,results=tex>>= 
test <- try( tex.tbl <- TT.classes.tbl( class.sys = "PL.TT" ) )
if( !"try-error" %in% class(test) ){
    xtable( 
        x       = tex.tbl[,-3],  #
        caption = "Texture classes of the Polish system / triangle", 
        label   = NULL  
    )   #
}   
@ 



Many thanks to Wiktor Zelazny for providing the code of the 
Polish triangle (and the Polish language translation).\\

Note: The polish triangle is loaded during the package start-up, 
contrary to the other triangles (due to the special characters it 
contains). So it is not guaranteed that the triangle is available 
on all platforms. If the triangle is not available (could not 
be loaded for any reason), a message is issued when the package 
is loaded (but no error or warning).

Note: Michal Stepien, 
Warsaw University of Life Sciences, 
indicated me that there are in fact many different variants 
of polish texture triangles, sometimes with different limits 
for the particle size. Michal indicates that the triangle 
above ("PTG 1956-1959"), probably 
has for original references "Przyrodniczo-genetyczna klasyfikacja 
gleb Polski, 1956. Roczniki Nauk Rolniczych, 74, seria D: 1-96" 
and  "Genetyczna klasyfikacja gleb Polski, 1959.
Roczniki Gleboznawcze --- Soil Science Annual, 7(2): 1-103".

See below for another variant of the texture triangle.



\clearpage % otherwise the table may 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Polish soil texture classification (PTG 1956 Musierowicz)} 

Note: several versions or variants of polish soil texture 
triangles have been used and are used nowadays, which may 
cause some confusion.
The triangle presented in this section is refered to here 
as PTG 1956 Musierowicz, but the name may not be an official 
denomination.\\

This triangle is used in Polish agricultural soil maps. 
Its references are:  
"Musierowicz A. 1956. Gleboznawstwo ogolne" and  
"Systematyka Gleb Polski, 1989. Roczniki Gleboznawcze
--- Soil Science Annual, 40(3/4): 1-150".\\

To display this texture triangle, type:



<<echo=TRUE,fig=TRUE,include=TRUE>>= 
test <- try( TT.plot( class.sys = "Polish_PTG_1956_Musierowicz.TT" ) ) 

#   In case the polish triangle was not loaded at startup
if( "try-error" %in% class(test) ){ 
    plot(1,1,type="n",) 
    text(1,1,label="Plotting failed. Polish triangle not loaded")
}   
@ 



NB: \textit{Due to encoding issues, the Polish triangle 
with be displayed with original polish character under Windows 
and Linux systems only. For other platforms (Mac, freeBSD) 
only latin character are used}.\\



<<echo=FALSE,results=hide,quiet=TRUE>>= 
test <- try( plLim <- TT.get("Polish_PTG_1956_Musierowicz.TT")[["base.css.ps.lim"]][3] ) 
if( "try-error" %in% class(test) ){ plLim <- NA_real_ }
@ 

The Polish soil texture classification has been built 
considering a silt - sand limit of 
\Sexpr{plLim}$\mu$meters.\\


See the table for soil texture classes symbols:


<<echo=FALSE,results=tex>>= 
test <- try( tex.tbl <- TT.classes.tbl( class.sys = 
    "Polish_PTG_1956_Musierowicz.TT" ) )
if( !"try-error" %in% class(test) ){
    xtable( 
        x       = tex.tbl[,-3],  #
        caption = "Polish texture triangle (PTG 1956 Musierowicz)", 
        label   = NULL  
    )   #
}   
@ 

Many thanks to Michal Stepien and Darek Gozdowski, Warsaw 
University of Life Sciences, for providing the code of this 
Polish triangle, as well as explanations on the differences 
between the polish triangles presented here.\\



\clearpage % otherwise the table may 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Polish soil texture classification (BN-78/9180-11)} 

To display this Polish texture triangle, type:



<<echo=TRUE,fig=TRUE,include=TRUE>>= 
test <- try( TT.plot( class.sys = "Polish_BN_1978.TT"  ) ) 

#   In case the polish triangle was not loaded at startup
if( "try-error" %in% class(test) ){ 
    plot(1,1,type="n",) 
    text(1,1,label="Plotting failed. Polish triangle not loaded")
}   
@ 



NB: \textit{Due to encoding issues, the Polish triangle 
with be displayed with original polish character under Windows 
and Linux systems only. For other platforms (Mac, freeBSD) 
only latin character are used}.\\

Formal denomination/citation: BN-78/9180-11. Gleby i utwory 
mineralne. Podzial na frakcje i grupy granulometryczne. 
Norma branzowa.

NB: \textit{As for now, this Polish triangle has been 
implemented without original polish character.  
only latin character are used}.\\



<<echo=FALSE,results=hide,quiet=TRUE>>= 
test <- try( plLim <- TT.get("Polish_BN_1978.TT")[["base.css.ps.lim"]][3] ) 
if( "try-error" %in% class(test) ){ plLim <- NA_real_ }
@ 

The Polish soil texture classification has been built 
considering a silt - sand limit of 
\Sexpr{plLim}$\mu$meters.\\


See the table for soil texture classes symbols:


<<echo=FALSE,results=tex>>= 
test <- try( tex.tbl <- TT.classes.tbl( class.sys = "Polish_BN_1978.TT" ) )
if( !"try-error" %in% class(test) ){
    xtable( 
        x       = tex.tbl[,-3],  #
        caption = "Texture classes of the Polish system / triangle", 
        label   = NULL  
    )   #
}   
@ 



Many thanks to Michal Stepien and Darek Gozdowski, Warsaw 
University of Life Sciences, for providing the code of this 
Polish triangle, as well as explanations on the differences 
between the polish triangles presented here.\\



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{The Brazilian 1996 soil texture classification} 

To display a Brazilian texture triangle (Lemos \& Santos 
1996)\cite{LEMOS1996}, type:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "BRASIL.TT" ) 
@ 



The Brazilian soil texture classification has been built 
considering a silt - sand limit of 
\Sexpr{TT.get("BRASIL.TT")[["base.css.ps.lim"]][3]}$\mu$meters.\\


See the table for soil texture classes symbols:


<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "BRASIL.TT" ) 
xtable( 
    x       = tex.tbl[,-3],  #
    caption = "Texture classes of the Brazilian system (1996)", 
    label   = NULL  
)   #
@ 


Many thanks to Rodolfo Marcondes Silva Souza, UFPE, Brasil, for 
providing information and references on the Brasilian triangle.\\

\clearpage % otherwise the table may 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{The Brazilian 2013 soil texture classification} 

To display a Brazilian texture triangle (Santos et al., 2013 - 
Embrapa)\cite{SANTOS2013}, type:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( class.sys = "SiBCS13.TT" ) 
@ 



The Brazilian soil texture classification has been built 
considering a silt - sand limit of 
\Sexpr{TT.get("SiBCS13.TT")[["base.css.ps.lim"]][3]}$\mu$meters.\\


See the table for soil texture classes symbols:


<<echo=FALSE,results=tex>>= 
tex.tbl <- TT.classes.tbl( class.sys = "SiBCS13.TT" ) 
xtable( 
    x       = tex.tbl[,-3],  #
    caption = "Texture classes of the Brazilian system (2013)", 
    label   = NULL  
)   #
@ 


Many thanks to Jos\'{e} Lucas Safanelli and Alexandre ten Caten (UFSC 
Curitibanos, Brasil), for providing digitizing this texture 
triangle.\\

\clearpage % otherwise the table may 'eats' next triangle



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Soil texture triangle with a texture classes color 
    gradient} 

It is possible to have a nice color gradient (single hue, 
gradient of saturation and value) on the background, by setting 
the option \texttt{class.p.bg.col} (logical) to \texttt{TRUE}.\\

Example with the USDA and European (HYPRES) soil texture triangles:


<<echo=TRUE,fig=TRUE,include=TRUE,height=7>>= 
# Set a 2 by 2 plot matrix:
old.par <- par(no.readonly=T)
par("mfcol" = c(1,2),"mfrow"=c(1,2)) 

# Plot the triangles
TT.plot( 
    class.sys       = "USDA.TT", 
    class.p.bg.col  = TRUE
)   #

TT.plot( 
    class.sys       = "HYPRES.TT", 
    class.p.bg.col  = TRUE
)   #

# Back to old parameters:
par(old.par)
@ 


Example with the French Aisne and French GEPPA soil texture 
triangles:


<<echo=TRUE,fig=TRUE,include=TRUE,height=7>>= 
# Set a 2 by 2 plot matrix:
old.par <- par(no.readonly=T)
par("mfcol" = c(1,2),"mfrow"=c(1,2)) 

# Plot the triangles
TT.plot( 
    class.sys       = "FR.AISNE.TT", 
    class.p.bg.col  = TRUE
)   #

TT.plot( 
    class.sys       = "FR.GEPPA.TT", 
    class.p.bg.col  = TRUE
)   #

# Back to old parameters:
par(old.par)
@ 


Example with the UK (SSEW) and German (BK94) soil texture 
triangles:


<<echo=TRUE,fig=TRUE,include=TRUE,height=7>>= 
# Set a 2 by 2 plot matrix:
old.par <- par(no.readonly=T)
par("mfcol" = c(1,2),"mfrow"=c(1,2)) 

# Plot the triangles
TT.plot( 
    class.sys       = "UK.SSEW.TT", 
    class.p.bg.col  = TRUE
)   #

TT.plot( 
    class.sys       = "DE.BK94.TT", 
    class.p.bg.col  = TRUE
)   #

# Back to old parameters:
par(old.par)
@ 


Example with the Australian and Belgian soil texture triangle:


<<echo=TRUE,fig=TRUE,include=TRUE,height=7>>= 
# Set a 2 by 2 plot matrix:
old.par <- par(no.readonly=T)
par("mfcol" = c(1,2),"mfrow"=c(1,2)) 

# Plot the triangles
TT.plot( 
    class.sys       = "AU2.TT", 
    class.p.bg.col  = TRUE
)   #

TT.plot( 
    class.sys       = "BE.TT", 
    class.p.bg.col  = TRUE
)   #

# Back to old parameters:
par(old.par)
@ 


And finally the Canadian texture triangle (with English and French 
abbreviations):


<<echo=TRUE,fig=TRUE,include=TRUE,height=7>>= 
# Set a 2 by 2 plot matrix:
old.par <- par(no.readonly=T)
par("mfcol" = c(1,2),"mfrow"=c(1,2)) 

# Plot the triangles
TT.plot( 
    class.sys       = "CA.EN.TT", 
    class.p.bg.col  = TRUE
)   #

TT.plot( 
    class.sys       = "CA.FR.TT", 
    class.p.bg.col  = TRUE
)   #

# Back to old parameters:
par(old.par)
@ 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Soil texture triangle with custom texture class colors} 

\texttt{class.p.bg.col} can also be used to provide custom background 
colors for each classes of the texture triangle:

Example with the European Soil Map (HYPRES) soil texture triangles:


<<echo=TRUE,fig=TRUE,include=TRUE,height=7>>= 
TT.plot( 
    class.sys       = "HYPRES.TT", 
    class.p.bg.col  = c("red","green","blue","pink","purple") 
)   #
@ 


You can type \texttt{TT.classes.tbl()[,1]} to get the number and 
order of the texture classes in the triangle.



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\section{Overplotting two soil texture classification systems} 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Case 1: Overplotting two soil texture classification 
    systems with the same geometry} 

Below is the code for plotting a French-Aisne texture triangle 
over a USDA texture triangle:

<<echo=TRUE,fig=TRUE,include=TRUE>>= 
# First plot the USDA texture triangle, and retrieve its 
#   geometrical features, silently outputted by TT.plot 
geo <- TT.plot( 
    class.sys   = "USDA.TT", 
    main        = "USDA and French Aisne triangles, overplotted"  
)   # 

# Then overplot the French Aisne texture triangle, 
#   and customise the colors so triangles are well distinct.
TT.classes(
    geo             = geo, 
    class.sys       = "FR.AISNE.TT", 
    # Additional "graphical" options
    class.line.col  = "red", 
    class.lab.col   = "red", 
    lwd.axis        = 2  
)   #
@ 

Beware that the result may not necessarily be very readable when 
printed, in black and white. Consider to change the line type as 
well (option \texttt{class.lty = 2} for \texttt{TT.classes}) 
is you want a more printer-friendly output.



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Case 2: Overplotting two soil texture classification 
    systems with different geometries} 

Below is the code to plot a French GEPPA texture triangle over a 
French Aisne texture triangle. The code is in fact almost 
identical to the previous case:

<<echo=TRUE,fig=TRUE,include=TRUE>>= 
# First plot the USDA texture triangle, and retrieve its 
#   geometrical features, silently outputted by TT.plot 
geo <- TT.plot( 
    class.sys   = "FR.AISNE.TT", 
    main        = "French Aisne and GEPPA triangles, overplotted"  
)   # 

# Then overplot the French Aisne texture triangle, 
#   and customise the colors so triangles are well distinct.
TT.classes(
    geo             = geo, 
    class.sys       = "FR.GEPPA.TT", 
    # Additional "graphical" options
    class.line.col  = "red", 
    class.lab.col   = "red", 
    lwd.axis        = 2  
)   #
@ 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\section{Plotting soil texture data} 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Simple plot of soil texture data} 

First, lets create a table containing (dummy) soil texture data, 
(in \%), as well as dummy organic carbon content (in $g.kg^{-1}$, 
for later use):

<<echo=TRUE>>= 
# Create a dummy data frame of soil textures:
my.text <- data.frame( 
    "CLAY"  = c(05,60,15,05,25,05,25,45,65,75,13,47), 
    "SILT"  = c(05,08,15,25,55,85,65,45,15,15,17,43), 
    "SAND"  = c(90,32,70,70,20,10,10,10,20,10,70,10), 
    "OC"    = c(20,14,15,05,12,15,07,21,25,30,05,28)  
)   #

# Display the table:
my.text
@ 

The columns names include CLAY, SILT and SAND, so they are 
explicit for the \texttt{TT.plot} function. 
The code to display these soil texture data is:

<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    class.sys   = "HYPRES.TT", 
    tri.data    = my.text, 
    main        = "Soil texture data" 
)   #
@ 

The option \texttt{tri.data} is a data frame containing numerical 
values. \texttt{colnames(tri.data)} must match with 
\texttt{blr.tex} option's values (default 
\texttt{c("CLAY","SILT","SAND")}). More columns can be provided, 
but are not used unless other options are chosen (see below).



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Bubble plot of soil texture data and a 3rd variable} 

It could be interesting to plot the organic carbon content on top 
of the soil texture triangle. Bubble plots are good for this:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    class.sys   = "none", 
    tri.data    = my.text, 
    z.name      = "OC", 
    main        = "Soil texture triangle and OC bubble plot" 
)   #
@ 


The option \texttt{z.name} is a character string, the 
name of the column in \texttt{tri.data} that contains a 3rd 
variable to be plotted.\\

The 3rd variable is plotted with an 'expansion' factor 
proportional to \texttt{z.name} value. Low values have a small 
diameter and high values have a big diameter. To re-enforce the 
visual effect, a single hue color gradient is added to the point 
background, with hight saturation and high color's value (bright) 
for low \texttt{z.name}'s values, and low saturation and low 
color's value (dark) for high \texttt{z.name}'s values.\\

The function keeps good visual effect, even with a lot of values. 
Below is a test using \texttt{TT.dataset()} function, that 
generate a (quick and dirty) dummy soil texture datasets, with a 
4th z variable (named 'Z'), correlated to the texture data.


<<echo=TRUE>>= 
rand.text	<- TT.dataset(n=100,seed.val=1980042401)
@ 


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    class.sys   = "none", 
    tri.data    = rand.text, 
    z.name      = "Z", 
    main        = "Soil texture triangle and Z bubble plot" 
)   #
@ 


This function is primarily intended for exploratory data analysis 
or for rather qualitative analysis, as it is difficult for the 
reader to know the real \texttt{z.name} value of a point. It is 
nevertheless possible to add 'manually' a legend, as in the 
example below:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    class.sys   = "none", 
    tri.data    = my.text, 
    z.name      = "OC", 
    main        = "Soil texture triangle and OC bubble plot" 
)   #

# Recompute some internal values:
z.cex.range <- TT.get("z.cex.range") 
def.pch     <- par("pch") 
def.col     <- par("col")
def.cex     <- TT.get("cex") 
oc.str      <- TT.str( 
    my.text[,"OC"], 
    z.cex.range[1], 
    z.cex.range[2]
)   #

# The legend:
legend( 
    x           = 80, 
    y           = 90, 
    title       = 
        expression( bold('OC [g.kg'^-1 ~ ']') ), 
    legend      = formatC( 
        c( 
            min( my.text[,"OC"] ), 
            quantile(my.text[,"OC"] ,probs=c(25,50,75)/100), 
            max( my.text[,"OC"] ) 
        ), 
        format  = "f", 
        digits  = 1, 
        width   = 4, 
        flag    = "0" 
    ),  #
    pt.lwd      = 4, 
    col         = def.col, 
    pt.cex      = c( 
            min( oc.str ), 
            quantile(oc.str ,probs=c(25,50,75)/100), 
            max( oc.str ) 
    ),  #, 
    pch         = def.pch, 
    bty         = "o", 
    bg          = NA, 
    #box.col    = NA, # Uncomment this to remove the legend box
    text.col    = "black", 
    cex         = def.cex  
)   #
@ 


This code is obviously complicated, but it produces a smart 
legend. It is not possible (or easy) to add an automatic legend 
to a plot, because the optimal number of decimals may change from 
dataset to dataset, as well as the quantiles displayed.



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Heatmap and / or contour plot of soil texture data 
    and a 4th variable} 

Another way to explore a 4th variable is heatmap. The heatmap 
represent a local average value (by inverse distance 
interpolation) of the 4th variable in the form of a colored map.\\

Plotting a heatmap now follows 4 steps, that somehow works as 
'sandwich' plots:

\begin{itemize} 
    \item (1) Retrieve the geometrical parameters of the future plot 
    with \texttt{TT.geo.get()} function. It doesn't plot anything, 
    but returns geometrical parameters that will be used to 
    determine the x-y grid on which calculating the inverse distance. 
    A call to \texttt{geo <- TT.plot()} would also work.
    \item (2) Calculate inverse weighted distances of the 4th variable 
    (here 'Z') on a regular x-y grid, using \texttt{TT.iwd()} 
    function. It returns a grid with interpolated values.
    \item (3) Plot this grid with the function \texttt{TT.image()} (or 
    with \texttt{TT.contour()}). This function is a wrapper for 
    the \texttt{image()} (or \texttt{TT.contour()}) function, 
    adapted to triangle plots. The grid format is compatible with 
    \texttt{image()} or \texttt{TT.contour()}. \texttt{TT.image()} 
    can have an option \texttt{add = TRUE} to plot the image on top 
    of an existing triangle plot.
    \item (4) Add a standard triangle plot on to of the heatmap, using 
    the standard \texttt{TT.plot()} function (with 
    \texttt{add = TRUE}). If plot has been called in step 1, step 
    4 is not necessary, and the heatmap is plotted on top of the 
    existing triangle.
\end{itemize} 


% Uncomment this to display the heatmap
<<echo=TRUE,fig=TRUE,include=TRUE>>= 
geo <- TT.geo.get() 
#
iwd.res <- TT.iwd( 
    geo         = geo, 
    tri.data    = rand.text, 
    z.name      = "Z", 
)   #
#
TT.image( 
    x       = iwd.res, 
    geo     = geo, 
    main    = "Soil texture triangle and Z heatmap" 
)   # 
#
TT.plot( 
    geo         = geo, 
    grid.show   = FALSE, 
    add         = TRUE  #  <<-- important 
)   #
@ 

\texttt{TT.iwd()} has 3 important parameters: 
\begin{itemize} 
    \item (1) \texttt{pow} (default value 0.5) is the power used 
    for the inverse weighted distance interpolation. Low values 
    means strong smoothing, and vice versa; 
    \item (2) \texttt{q.max.dist} (default value 0.5) is used to 
    determines the maximum (Euclidian) distance of the points used to 
    calculate interpolated values. Data points located further than 
    that distance are not used. \texttt{q.max.dist} is the quantile of 
    the Euclidian distance, so 0.5 means that points located further 
    that the 50\% quantile of all Euclidian distances will not be 
    used to calculate a given grid value (notice that this is very 
    experimental!). The higher the value, the more points used to 
    calculate the interpolated values (and the stronger the smoothing); 
    \item (3) \texttt{n} is the number of x and y values used to 
    calculate the interpolation grid. The number of nodes in the 
    grid is $n^2$.
\end{itemize} 

\texttt{TT.image()} accepts most of the options existing in 
\texttt{image()}.\\

The is no 'heatmap legend', but it is possible to add a contour 
plot to the existing plot, in order to replace the color legend:


% Uncomment this to display the heatmap
<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.image( 
    x       = iwd.res, 
    geo     = geo, 
    main    = "Soil texture triangle and Z heatmap" 
)   # 
#
TT.contour( 
    x       = iwd.res, 
    geo     = geo, 
    add     = TRUE, #  <<-- important
    lwd     = 2  
)   # 
#
TT.plot( 
    geo         = geo, 
    grid.show   = FALSE, 
    add         = TRUE  #  <<-- important
)   #
@ 

\texttt{TT.contour()} accepts most of the options existing in 
\texttt{contour()}.\\

Inverse Weighted Distance interpolation is not really 'state of 
the art' statistics, but rather a visual way of exploring the data. 
Interpolation is NOT done on a clay / silt / sand mesh, but rather 
on a x-y grid in the triangle. So data density is not equal 
between clay, silt and sand. Moreover, the interpolator might not 
be the most relevant one.\\

This function is only provided as 'experimental' and it is 
susceptible to be modified significantly in the future.\\



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Two-dimensional kernel (probability) density 
    estimation for texture data} 

The \texttt{kde2d()} function of the MASS package by W. N. Venables 
and B. D. Ripley\cite{MASSREF}, for 2D kernel probability density 
estimate has been 'wrapped' into the function \texttt{TT.kde2d()} 
so it becomes usable with texture data and texture triangle. 
It returns an x-y-z list / grid object that can be plotted with 
\texttt{TT.contour()} or \texttt{TT.image()}.\\

The same 'sandwich' plot structure as for inverse weight distance 
estimate of a 4th variable is also valid for contour plot of 
probability density estimates:


% Uncomment this to display the heatmap
<<echo=TRUE,fig=TRUE,include=TRUE>>= 
geo <- TT.geo.get()  
#
kde.res <- TT.kde2d( 
    geo         = geo, 
    tri.data    = rand.text  
)   #
#
TT.contour( 
    x       = kde.res, 
    geo     = geo, 
    main    = "Probability density estimate of the texture data", 
    lwd     = 2, 
    col     = "red"  
)   # 
#
TT.plot( 
    tri.data    = rand.text, 
    geo         = geo, 
    grid.show   = FALSE, 
    add         = TRUE, #  <<-- important 
    col         = "gray"
)   #
@ 

Using \texttt{TT.image()} would also work here.\\

As \texttt{kde2d()}, \texttt{TT.kde2d()} accepts a 'n' option that 
determines the number of values in the x and y axes (The total 
number of nodes is $n^2$). The parameter 'h' from \texttt{kde2d()} 
has NOT been implemented into \texttt{TT.kde2d()}, and the default 
calculation method is used.\\

Please note that the probability density is estimated on the x-y 
grid of the plot, and NOT on the clay / silt / sand coordinates 
system. So a different plot geometry may give a slightly different 
probability density estimate...



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Contour plot of texture data Mahalanobis distance} 

The \texttt{mahalanobis()} function (part of the default R 
functions) has been 'wrapped' into the function 
\texttt{TT.mahalanobis()} so it becomes usable with texture data 
and texture triangle. It returns an x-y-z list / grid object that 
can be plotted with \texttt{TT.contour()} or \texttt{TT.image()}.\\

Some authors\cite{LARK2007} have recommended that the Mahalanobis 
distance should be computed on the additive log-ratio transform 
of soil texture data in order to take into account the fact the 
3 texture classes are not independent random variables (but rather 
compositional data). For this reason an option has been added that 
transform the texture data by an additive log-ratio prior to 
the computation of the Mahalanobis distance (the default is no 
transformation of the data). The log-ratio transformation code 
used here has been taken from the 'chemometrics' package%%%
\cite{CHEMOMETRICSREF} by Filzmoser and Varmuza (function  
\texttt{alr()}).\\

The same 'sandwich' plot structure as for inverse weight distance 
estimate of a 4th variable is also valid for contour plot of 
probability density estimates. Below is a first example without 
texture transformation:


% Uncomment this to display the heatmap
<<echo=TRUE,fig=TRUE,include=TRUE>>= 
geo <- TT.geo.get() 
#
maha <- TT.mahalanobis( 
    geo         = geo, 
    tri.data    = rand.text  
)   #
#
TT.contour( 
    x       = maha, 
    geo     = geo, 
    main    = "Texture data Mahalanobis distance", 
    lwd     = 2, 
    col     = "blue"  
)   # 
#
TT.plot( 
    tri.data    = rand.text, 
    geo         = geo, 
    grid.show   = FALSE, 
    add         = TRUE, #  <<-- important 
    col         = "gray"
)   #
@ 


All the options of \texttt{mahalanobis()} are also available in 
\texttt{TT.mahalanobis()}. The option \texttt{divisorvar} is an 
integer that determines which texture classes (number 1, 2 or 
3 in 'css.names') is NOT used to calculate the Mahalanobis distance 
(using the 3 texture classes crashes the \texttt{mahalanobis()} 
function).\\

If you want to compute the Mahalanobis distance on texture data 
transformed with an additive log-ratio, you can set the option 
\texttt{alr = TRUE} (default = FALSE). The option \texttt{divisorvar} 
is then an integer used in the log-ratio transformation of texture data,\\

$alr(textureClass_{i}) = log_{10}( textureClass_{i} / textureClass_{divisorvar} )$\\

where \texttt{i} and \texttt{divisorvar} are index of 
\texttt{css.names}. The Mahalanobis distance is then computed on 
2 of the 3 log-ratio transformed texture classes 
(\texttt{css.names[-divisorvar]}).\\

Below is an example of Mahalanobis distance plot with log-ratio 
transformation:


% Uncomment this to display the heatmap
<<echo=TRUE,fig=TRUE,include=TRUE>>= 
geo <- TT.geo.get() 
#
maha <- TT.mahalanobis( 
    geo         = geo, 
    tri.data    = rand.text, 
    alr         = TRUE  #  <<-- important 
)   #
#
TT.contour( 
    x       = maha, 
    geo     = geo, 
    main    = "Texture data Mahalanobis distance", 
    lwd     = 2, 
    col     = "blue", 
    levels  = c(0.5,1,2,4,8)  #  <<-- manually set. Otherwise 
)   #                                 ugly plot
#
TT.plot( 
    tri.data    = rand.text, 
    geo         = geo, 
    grid.show   = FALSE, 
    add         = TRUE,  #  <<-- important 
    col         = "gray"
)   #
@ 


The Mahalanobis distances computed on a regular x-y grid have an 
extremely skewed distribution, with a few very high values near 
the borders of the triangle. For this reason the automatic levels 
of the contour function fails to show anything relevant, and it 
is recommended that the user manually set the levels, as in the 
example.\\

\textbf{Please notice that the \texttt{TT.mahalanobis()} has not 
been tested extensively for practical and theoretical validity.}\\

Using \texttt{TT.image()} would also work here.\\



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Plotting text in a texture triangle} 

As the \texttt{text()} function of R standard plot functions, 
\texttt{TT.plot()} is completed by a \texttt{TT.text()} function 
that displays text into an existing texture triangle plot. Its 
use is similar to \texttt{TT.points()}, apart that it has a 
\texttt{labels}, and a \texttt{font} option, as the 
\texttt{text()} function. Below is a simple example:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
# Display the USDA texture triangle:
geo     <- TT.plot(class.sys="USDA.TT") 

# Create some custom labels:
labelz  <- letters[1:dim(my.text)[1]] 
labelz 

# Display the text
TT.text( 
    tri.data    = my.text, 
    geo         = geo, 
    labels      = labelz, 
    font        = 2, 
    col         = "blue"  
)   #
@


As for the \texttt{text()} function, it is also possible to set 
\texttt{adj}, \texttt{pos} and / or \texttt{offset} parameters 
(not shown here).



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\section{Control of soil texture data in The Soil Texture Wizard} 

Several controls are done (internally) on soil texture data prior 
to soil texture plots or soil texture classification:

\begin{itemize} 
    \item Clay, silt and sand column names must correspond to the 
    names given in the option \texttt{css.names} (default to CLAY, 
    SILT and SAND); 
    \item There should not be any \textbf{negative} values in clay, 
    silt and sand (i.e. values that lies outside the triangle). 
    This control can be relaxed by setting the option 
    \texttt{tri.pos.tst} to FALSE;
    \item All the row sums of the 3 texture classes must be equal 
    to \textbf{text.sum} (generally 100, for 100\%). In fact, 
    (absolute) differences lower than \textbf{text.sum * text.tol} 
    are allowed (with \textbf{text.tol} option default to $1/1000$, 
    so textures sum must be between 99.9 and 100.1). This text can 
    be relaxed by setting \texttt{tri.sum.tst} to FALSE;
    \item No missing values are allowed in the texture data (NA). 
\end{itemize} 

A test of the data can be conducted externally, using 
\texttt{TT.data.test}. An error occur if the data don't pass the 
tests:


<<echo=TRUE>>= 
TT.data.test( tri.data = rand.text ) 
@ 

This function accepts options \texttt{css.names}, 
\texttt{text.sum}, \texttt{text.tol}, \texttt{tri.sum.tst} and 
\texttt{tri.pos.tst}.



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Normalizing soil texture data (sum of the 3 texture 
    classes)} 

If you have a texture data table with some rows where the sum of 
the 3 texture classes is not 100\%, but you know this is not due 
to errors in the data, you may want to normalize the sum of the 
3 texture classes to 100\%. The function \texttt{TT.normalise.sum} 
do that for you, and return a data table with normalised clay, silt 
and sand values. The option \texttt{residuals} can be set to TRUE 
if you want the residuals to be returned (initial row sum - final 
row sum):


<<echo=TRUE>>= 
res <- TT.normalise.sum( tri.data = rand.text ) 
#
# With output of the residuals:
res <- TT.normalise.sum( 
    tri.data    = rand.text, 
    residuals   = TRUE  #  <<-- default = FALSE 
)   #
#
colnames( rand.text )
colnames( res )  #  "Z" has been dropped
max( res[ , "residuals" ] ) 
@ 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Normalizing soil texture data (sum of X texture classes)} 

[function and section to be written]



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\section{Classify soil texture data: TT.points.\-in.\-classes()} 

The function \texttt{TT.points.\-in.\-classes()} classify a table 
of soil texture data (\texttt{tri.data}) and returns a table 
where each row is one soil texture sample, and each column a soil 
texture class (given the system \texttt{class.sys}). Values are 0 
when the point is 'out' of the class, 1 when 'in', 2 when 'on a 
polygon side' and 3 when 'on the polygon corner(s) (vertex / 
vertices)' (As in the underying function 
\texttt{sp::point.in.polygon()} from the 'sp' package). 
In the examples below I will only show the results for the 5 
first row of the dummy soil texture data created above, with the 
European Soil Map (HYPRES) classification:


<<echo=TRUE>>= 
TT.points.in.classes( 
    tri.data    = my.text[1:5,], 
    class.sys   = "HYPRES.TT"  
)   #
@ 


A major interest of the function resides in the fact 
that it is possible to use another classication very easily, USDA
in the xample below:


<<echo=TRUE>>= 
TT.points.in.classes( 
    tri.data    = my.text[1:5,], 
    class.sys   = "USDA.TT"  
)   #
@ 


The result can also be returned in a logical form with the option 
\texttt{PiC.type = "l"} (for 'logical'. default is "n" as numeric% 
). Value is TRUE if the sample belong to the class, and FALSE if 
it is outside the class. In case of a point located at the border 
of two or more texture classes, several texture classes (columns) 
are marked TRUE.


<<echo=TRUE>>= 
TT.points.in.classes( 
    tri.data    = my.text[1:5,], 
    class.sys   = "HYPRES.TT", 
    PiC.type    = "l" 
)   #
@ 


And finally, the results can be a vector of character, of the 
same length as the number of soil samples, and containing the 
abbreviation of the texture class(es) to which the sample belongs.
In case of a sample lying on the border of two classes, the 
classes abbreviation are concatenated (separated by a comma).


<<echo=TRUE>>= 
TT.points.in.classes( 
    tri.data    = my.text[1:5,], 
    class.sys   = "HYPRES.TT", 
    PiC.type    = "t" 
)   #
@ 

Notice that the second value lies between two classes, and that 
they are outputted separated by a comma.\\

The comma separator can be replaced by any character string, as 
in the function \texttt{paste()}, with the option 
\texttt{collapse}:


<<echo=TRUE>>= 
TT.points.in.classes( 
    tri.data    = my.text[1:5,], 
    class.sys   = "HYPRES.TT", 
    PiC.type    = "t", 
    collapse    = ";"
)   #
@ 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\section{Converting soil texture data and systems with different 
    silt-sand particle size limit} 

'The Soil Texture Wizard' comes with functions to transform soil 
textures data from 1 particle sizes system (limits between the 
clay, silt and sand particles) to another particle size system, 
with a log-linear transformation. For instance, it is 
possible to convert a textures data table measured in a system 
that have a silt / sand limit is 60$\mu$m into a system that has 
a silt / sand limit is 50$\mu$m.\\

It is important to keep in mind several limitations when 
transforming soil texture data:

\begin{itemize} 
    \item Transforming soil texture with a 'log-linear 
    interpolation' consider that the cumulated particle size 
    (mass) distribution is linear between two consecutive 
    particle size classes limits, when plotted against a log 
    transform of the particle size;
    \item Because of this, \textbf{transforming soil texture is 
    at best an \textbf{approximation} of what would be obtained 
    with laboratory measurements};
    \item The bigger the difference between two particle size 
    limit used to interpolate a new particle size limit, the more 
    uncertain the estimation (= the bigger the errors);
    \item Because of this, the more particle size classes you have 
    in the initial soil texture data (i.e. the smaller the 
    differences between 2 successive particle size classes limits), 
    the more precise the transformation.
    \item Transforming soil texture data using a log-linear 
    interpolation is not the most precise method (especially if 
    you have more than 3 particle size classes). On the other 
    hand, it is certainly the most simple method. See Nemes et al. 
    1999 \cite{NEMES1999GEOD} for a comparison of different 
    methods for soil texture data transformation.
\end{itemize} 

This package comes with 2 functions for texture transformations:

\begin{itemize} 
    \item \texttt{TT.text.\-transf()}, that only works with 3 
    particle size classes, clay, silt and sand. It can be 
    used independently, for transforming a table of soil texture 
    data, but it is also 'embedded' into \texttt{TT.plot()} and 
    \texttt{TT.points.\-in.\-classes()} to allow transparent, on the 
    fly transformation of soil texture data or soil texture 
    triangles / classification.
    \item \texttt{TT.text.\-transf.X()}, that works with 3 or more 
    particle size classes. The number of particle size classes in 
    the input data do not need to be equal to the number of 
    particle size classes in the final system (output). It is not 
    embedded and not embeddable into \texttt{TT.plot()} and 
    \texttt{TT.points.\-in.\-classes()}, and it is not doing as many 
    data consistency tests as \texttt{TT.text.\-transf()}.
\end{itemize} 

Of course, it is also possible to define your own texture 
transformation function. If this function works on clay, silt and 
sand, and if it has the same options as \texttt{TT.text.\-transf()}, 
it can also be embedded in \texttt{TT.plot()} and 
\texttt{TT.points.\-in.\-classes()} by changing a simple option.\\

\textbf{If your data have more than 3 particle size classes, 
you should probably use \texttt{TT.text.\-transf.X()} instead of 
\texttt{TT.text.\-transf()}}.\\

The figure below / above illustrate how the log-linear 
interpolation works, and why it is sometimes / often inaccurate.


<<echo=FALSE,fig=TRUE,include=TRUE>>= 
tmp.cex <- 1.5
old.par <- par(no.readonly = TRUE)
par(cex=tmp.cex,cex.axis=tmp.cex,cex.lab=tmp.cex,cex.main=tmp.cex)

tmp.text <- data.frame( "CLAY" = 20, "SILT" = 15, "SAND" = 65 ) 

plot( 
    x       = TT.dia2phi( c(2,20,2000) ), 
    y       = cumsum( unlist(tmp.text[1,]) ), 
    ylim    = c(0,100), 
    xlim    = TT.dia2phi( c(1,2000) ), 
    xaxt    = "n", 
    xlab    =  
expression( 'Particle size['~ mu * 'm] (log'[2] * 'scale)' ), 
    ylab    = "Cumulated particle size distribution [%]", 
    bty     = "n", 
    type    = "b", 
    main    = 
"Principle of particle size log-linear transformation", 
    cex     = tmp.cex  
)   #

lines( 
    spline( 
        y   = rev(cumsum( unlist(tmp.text[1,]) )), 
        x   = TT.dia2phi( c(2000,20,2))
    ),  # 
    col = "green"  
)   #

segments( 
    x0  = TT.dia2phi( c(2,20,2000) ), 
    x1  = TT.dia2phi( c(2,20,2000) ), 
    y0  = rep(0,3), 
    y1  = cumsum( unlist(tmp.text[1,]) ), 
    col = "red"  
)   #

new.tmp.text <- TT.text.transf( 
    tri.data        = tmp.text,  
    base.css.ps.lim = c(0,2,50,2000),  
    dat.css.ps.lim  = c(0,2,20,2000)   
)   #

new.silt.c <- cumsum( unlist(new.tmp.text[1,]) )[2]

arrows( 
    x0  = TT.dia2phi( c(50,50) ), 
    x1  = TT.dia2phi( c(50,1) ), 
    y0  = c(0,new.silt.c), 
    y1  = c(new.silt.c,new.silt.c), 
    col = "blue"  
)   #

text( 
    x       = TT.dia2phi( c(2,20,2000) ), 
    y       = cumsum( unlist(tmp.text[1,]) ), 
    pos     = 2, 
    offset  = 1, 
    labels  = c("Clay","Silt","Sand"), 
    col     = "red", 
    cex     = tmp.cex  
)   #

text( 
    x       = TT.dia2phi( c(50) ), 
    y       = new.silt.c, 
    pos     = 4, 
    offset  = 1, 
    labels  = "new Silt", 
    col     = "blue", 
    cex     = tmp.cex  
)   #

axis( 
    side    = 1, 
    at      = TT.dia2phi( c(2,20,50,2000) ), 
    labels  = c(2,20,50,2000) 
)   #

text( 
    x       = TT.dia2phi( 500 ), 
    y       = 65, 
    #pos    = 4, 
    #offset = 1, 
    labels  = "real distribution?", 
    col     = "green", 
    cex     = tmp.cex  
)   #

par(old.par) 
@ 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Transforming soil texture data (from 3 particle size 
    classes)} 

Here are the non transformed data (reminder):


<<echo=TRUE>>= 
my.text[1:5,]   
@ 


Now the (dummy) data will be transformed, assuming that they have 
been measured with a 63$\mu$meters silt-sand particle size limit, 
and that we want them to be with a 50$\mu$meters silt-sand limit. 
Please don't forget this is not an 'exact' transformation, but 
rather an estimation:


<<echo=TRUE>>= 
TT.text.transf( 
	tri.data        = my.text[1:5,],  
	base.css.ps.lim = c(0,2,50,2000),  
	dat.css.ps.lim  = c(0,2,63,2000)   
)   #
@ 


Lets create a copy of the dummy data table, with new French 
columns names.


<<echo=TRUE>>= 
# Copy the data.frame
my.text.fr  <- my.text 
# Curent columns names:
colnames(my.text.fr) 
# New columns names: 
colnames(my.text.fr) <- c("ARGILE","LIMON","SABLE","CO") 
@ 


It is also possible to transform it:


<<echo=TRUE>>= 
TT.text.transf( 
    tri.data        = my.text.fr[1:5,],  
    base.css.ps.lim = c(0,2,50,2000),  
    dat.css.ps.lim  = c(0,2,63,2000),  
    css.names       = c("ARGILE","LIMON","SABLE")   
)   #
@ 

As you can see, OC values are kept and returned untransformed in 
the outputted data.frame.



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Transforming soil texture data (from 3 or more 
    particle size classes)} 

When more than 3 particle size classes are present in the dataset, 
it is sometimes necessary (and anyway recommended) to use 
\texttt{TT.text.\-transf.X()} instead of \texttt{TT.text.\-transf()}. 
But \texttt{TT.text.\-transf.X()} is not performing as much 'data 
consistency' checks as \texttt{TT.text.\-transf()}. In particular:

\begin{itemize} 
    \item The option \texttt{tri.data} should be a data.frame 
    with only soil texture data (no additional extra columns 
    should be present). It will not necessary bug or warn if more 
    data are provided (although there are good chances that it 
    bugs because the sum of textures is not 100\%);
    \item The columns in the \texttt{tri.data} data.frame should 
    be \textbf{in ascending order of particle size}. If the 
    columns are provided in another order, it will not bug or 
    warn;
    \item The length of the particle size classes limits should 
    be equal to the number of columns in \texttt{tri.data} + 1 
    (from the lower limit of the 1st class to the upper limit of 
    the upper class).
\end{itemize} 


We need first to create a dummy dataset with more than 3 particle 
size classes:


<<echo=TRUE>>= 
# Create a random fraction between 0 and 1
r.frac <- runif(n=dim(my.text)[1]) 
#
my.text4 <- cbind( 
    "CLAY"          = my.text[,"CLAY"], 
    "FINE_SILT"     = my.text[,"SILT"] * r.frac, 
    "COARSE_SILT"   = my.text[,"SILT"] * (1-r.frac), 
    "SAND"          = my.text[,"SAND"]  
)   #
#
my.text4[1:5,] 
@ 


Transform this data frame, from a system where the silt - sand 
limit is at 63$\mu$m to a system where the silt - sand limit is 
at 50$\mu$m:


<<echo=TRUE>>= 
TT.text.transf.X( 
    tri.data        = my.text4[1:5,], 
    base.ps.lim = c(0,2,20,50,2000),  
    dat.ps.lim  = c(0,2,20,63,2000)   
)   #
@ 


Notice the differences in options name as compared to 
\texttt{TT.text.\-transf()}. Notice also that the columns names in 
the input data are not preserved in the output data (There is not 
systematically a correspondence between input and output).\\

As said before, the number of particle size classes in the input 
data do not need to be identical to the number of particle size 
classes in the output:


<<echo=TRUE>>= 
TT.text.transf.X( 
    tri.data        = my.text4[1:5,], 
    base.ps.lim = c(0,2,50,2000),  
    dat.ps.lim  = c(0,2,20,63,2000)   
)   #
@ 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Plotting and transforming 'on the fly' soil texture 
    data} 

It is possible to plot data on a triangle and transform them 'on 
the fly', if they have been measured in another particle size 
system (classes sizes) as the triangle:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
# First, plot the data without transformation:
geo <- TT.plot( 
    class.sys   = "FR.GEPPA.TT", 
    tri.data    = my.text, 
    col         = "red", 
    main        = "Transformed and untransformed data"
)   #

# Then, re-plot them with transformation:
TT.points( 
    tri.data        = my.text, 
    geo             = geo, 
    dat.css.ps.lim  = c(0,2,63,2000),  
    css.transf      = TRUE, 
    col             = "blue", 
    pch             = 3  
)   #
@ 

Notice that the \texttt{dat.css.ps.lim} and \texttt{css.transf} 
options could be used directly with \texttt{TT.plot()} (not shown 
here).



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Plotting and transforming 'on the fly' soil texture 
    triangles / classification} 

The example below shows how it is possible to project the UK soil 
texture triangle in a particle size system that has 0, 2, 50 and 
2000$\mu$m as reference. The background triangle (gray) is 
in fact NOT transformed, and plotted 'as it is', without taking 
care of the real particle size limits (\textbf{because the default value 
of the \texttt{css.transf} option is \texttt{FALSE}}). The second 
plot (red) is transformed as it should have been (because the UK
triangle has a 60$\mu$m silt sand limit).


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
# Not transformed
geo <- TT.plot( 
    class.sys   = "UK.SSEW.TT", 
    base.css.ps.lim = c(0,2,50,2000), 
    main        = 
        "Dummy transformation of the UK texture triangle"  
)   # 

# Transformed
TT.classes(
    geo             = geo, 
    class.sys       = "UK.SSEW.TT", 
    css.transf      = TRUE, 
    # Additional "graphical" options
    class.line.col  = "red", 
    class.lab.col   = "red", 
    lwd.axis        = 2, 
    class.lab.show  = "none", 
    class.lty       = 2 
)   #
@ 


We clearly see that clay content is unaffected, but there is a 
'gap' created by the fact that 100\% silt become 'less than 100\% 
silt and some Sand (Particles that were considered as silt in the 
original UK system become sand in the 50$\mu$m system)'! So 
the texture triangle is compacted toward the sand side.\\

In a second example we can show how to compare a USDA soil 
texture triangle, and a UK soil texture triangle re-projected in 
the same particle size system, 50$\mu$m (while the UK triangle
is based on a 60$\mu$m limit):


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
# No transformation needed or stated
geo <- TT.plot( 
    class.sys   = "USDA.TT", 
    main        = 
        "USDA and transformed UK triangle, overplotted"  
)   # 

# Transformed
TT.classes(
    geo             = geo, 
    class.sys       = "UK.SSEW.TT", 
    css.transf      = TRUE,  #  <<-- important
    # Additional "graphical" options
    class.line.col  = "blue", 
    class.lab.col   = "blue", 
    lwd.axis        = 2, 
    class.lty       = 2 
)   #
@ 


Now another test where the background silt sand limit is 
50$\mu$meters and the 2nd triangle is 'said to have' 
20$\mu$meters limit. Two USDA texture triangles. The 1st is not 
transformed (because it is not needed), while the 2nd is 
transformed: 


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
# Untransformed
geo <- TT.plot( 
    class.sys   = "USDA.TT", 
    main        = 
        "(Dummy) transformation of the USDA texture triangle"  
)   # 

# Transformed
TT.classes(
    geo             = geo, 
    class.sys       = "USDA.TT", 
    tri.css.ps.lim  = c(0,2,20,2000), 
    css.transf      = TRUE,  #  <<-- important
    # Additional "graphical" options
    class.line.col  = "blue", 
    class.lab.col   = "blue", 
    lwd.axis        = 2, 
    class.lty       = 2 
)   #
@ 


Now another test with a right-angled triangle (the French GEPPA). 
The background silt sand limit is 50$\mu$meters and the 2nd 
triangle is 'said to have' 20$\mu$meters limit. The 1st is not 
transformed (because it is not needed), while the 2nd is 
transformed: 


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
geo <- TT.plot( 
    class.sys   = "FR.GEPPA.TT", 
    blr.tx      = c("SAND","CLAY","SILT"), 
    main        = 
        "(Dummy) transformation of the GEPPA texture triangle"  
)   # 

TT.classes(
    geo             = geo, 
    class.sys       = "FR.GEPPA.TT", 
    tri.css.ps.lim  = c(0,2,20,2000), 
    css.transf      = TRUE,  #  <<-- important
    # Additional "graphical" options
    class.line.col  = "blue", 
    class.lab.col   = "blue", 
    lwd.axis        = 2, 
    class.lty       = 2 
)   #
@ 


Now another test with the same triangle. The background silt 
sand limit is fixed at 20$\mu$meters, while the GEPPA triangle 
has a 50$\mu$m silt sand limit. The fist triangle is not 
transformed, while the second is transformed:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
# Not transformed
geo <- TT.plot( 
    class.sys       = "FR.GEPPA.TT", 
    blr.tx          = c("SAND","CLAY","SILT"), 
    base.css.ps.lim  = c(0,2,20,2000), 
    main        = 
        "(Dummy) transformation of the GEPPA texture triangle"  
)   # 

# Transformed
TT.classes(
    geo             = geo, 
    class.sys       = "FR.GEPPA.TT", 
    css.transf      = TRUE,  #  <<-- important
    # Additional "graphical" options
    class.line.col  = "blue", 
    class.lab.col   = "blue", 
    lwd.axis        = 2, 
    class.lty       = 2 
)   #
@ 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Classifying and transforming 'on the fly' soil 
    texture data} 

It is possible to transform soil texture data when classifying 
them according to a given soil texture classification\footnote{% 
And also the other way round: classifying soil texture data 
according to a transformed soil texture triangle / classification, 
but this is NOT recommended, for results consistency}.


<<echo=TRUE>>= 
TT.points.in.classes( 
    tri.data        = my.text[1:5,], 
    class.sys       = "USDA.TT", 
    dat.css.ps.lim  = c(0,2,20,2000), 
    css.transf      = TRUE   #  <<-- important
)   #
@ 

Visualize the result (all data):

<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    class.sys       = "USDA.TT", 
    tri.data        = my.text, 
    dat.css.ps.lim  = c(0,2,20,2000), 
    css.transf      = TRUE,  #  <<-- important
    col             = "red"  
)   # 
@


But don't do (the texture triangle is transformed, not the 
data, and that is not good at all):


<<echo=TRUE>>= 
TT.points.in.classes( 
    tri.data        = my.text[1:5,], 
    class.sys       = "USDA.TT", 
    dat.css.ps.lim  = c(0,2,20,2000), 
    base.css.ps.lim = c(0,2,20,2000), 
    css.transf      = TRUE  
)   #
@ 

Visualize the difference (all data) -- and you will understant 
why doing this causes some problems:

<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    class.sys       = "USDA.TT", 
    tri.data        = my.text, 
    dat.css.ps.lim  = c(0,2,20,2000), 
    base.css.ps.lim = c(0,2,20,2000), 
    css.transf      = TRUE, 
    col             = "red"  
)   # 
@

Some points lie outside the transformed soil texture 
classification, so they apparently don't belong to any class...
Reason why it is better to transform soil texture data rather 
than soil texture classification / triangle.



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Using your own custom transformation function when 
    plotting or classifying soil texture data} 

The \texttt{TT.text.\-transf()} function has been introduced a 
little earlier in this document. The function is transforming a 
data.frame containing soil texture data into another data.frame, 
containing soil texture data estimated in another particle size 
system.\\

This function is also the underlying function used by 
\texttt{TT.plot()} and \texttt{TT.points.\-in.\-classes()} when 
transforming texture data 'on the fly'.\\

\textbf{You may well create an alternative function to 
\texttt{TT.text.\-transf()}, that fits better your requirements, 
and willing to use it also when plotting or classifying data with 
\texttt{TT.plot()} or \texttt{TT.points.\-in.\-classes()}}. It is 
possible by changing the option \texttt{text.transf.fun} of 
\texttt{TT.plot()} or \texttt{TT.points.\-in.\-classes()}. This 
option is a character string naming the function to use when 
transforming data 'on the fly'. The function must accept the same 
arguments / options as \texttt{TT.text.\-transf()} (to see them, 
type \texttt{formals(\-TT.text.transf\-)}), even if some of them are 
in fact not used by your own function (it is just there for 
compatibility). On the other hand, \texttt{TT.text.\-transf()} has 
2 unused 'options slots', \texttt{trsf.add.opt1} and 
\texttt{trsf.add.opt2} that you may use in your own function if 
needed (as these 'options slots' are also ready for use in 
\texttt{TT.plot()} and \texttt{TT.points.\-in.\-classes()}).\\

Here is a simple example:


<<echo=TRUE>>= 
# Create a new function, in fact the copy of TT.text.transf()
TT.text.transf2 <- TT.text.transf

# Imagine some changes in TT.text.transf2...

# Use your new function (will give identical results)
TT.points.in.classes( 
    tri.data        = my.text[1:5,], 
    class.sys       = "USDA.TT", 
    dat.css.ps.lim  = c(0,2,20,2000), 
    base.css.ps.lim = c(0,2,20,2000), 
    css.transf      = TRUE, 
    text.transf.fun = "TT.text.transf2"  #  <<-- important
)   #
@ 


Of course it works with \texttt{TT.plot()}:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    class.sys       = "USDA.TT", 
    tri.data        = my.text, 
    dat.css.ps.lim  = c(0,2,20,2000), 
    base.css.ps.lim = c(0,2,20,2000), 
    css.transf      = TRUE, 
    col             = "red", 
    text.transf.fun = "TT.text.transf2", #  <<-- important
    main            = 
        "Test of a (dummy) new transformation function"
)   # 
@




% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\section{Customize soil texture triangle's geometry} 

Behind the ability of 'The soil texture wizard' package to plot 
seemlessly any soil texture classification system lies a system 
that disconnect \textbf{soil texture class boundaries} (expressed 
as 3D volumes, whose submit coordinates are expressed in clay / 
silt / sand proportion) and \textbf{soil texture triangle 
geometry}, where soil texture values are projected in a plane (as 
points, or 2D polygons).\\

'The soil texture wizard' package allows to change:

\begin{itemize} 
    \item Clay, Silt and Sand locations in the bottom, 
    left and right axis; 
    \item Triangle vertices angles;
    \item Direction of the axis (Clockwise, Anticlockwise or 
    neutral).
\end{itemize} 

All angles combinations are allowed, provided they sum to 180 
degrees. Nevertheless only 60 / 60 / 60 degrees or one 90 degrees 
together with two 45 degrees are recommended for obtaining smart 
plots (and correct anti-allysing).\\

Only 4 combinations of axis directions are allowed (and, as far 
as I know, geometrically possible):

\begin{itemize} 
    \item Full anticlockwise directions; 
    \item Full clockwise direction; 
    \item Bottom anticlockwise, left clockwise, and right neutral 
    (inside). This is the best presentation for triangles with a 
    90 degrees angle on the left, but other angles are allowed.
    \item Bottom clockwise, left neutral (inside), and right 
    anticlockwise. This is the best presentation for triangles 
    with a 90 degrees angle on the right, but other angles are 
    allowed.
\end{itemize} 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Customise angles} 

Below is a code example to project the USDA soil texture triangle 
using 90 and 45 / 45 angles:

<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    class.sys   = "USDA.TT", 
    tlr.an      = c(45,90,45), 
    main        = "Re-projected USDA triangle (angles)"  
)   # 
@ 

the option \texttt{tlr.an} accept a vector of numerical, for the 
Top, Left and Right ANgles respectively.\\

the option \texttt{main} accept charcter string, for the plot
title. If set to \texttt{NA}, no title is plotted, and the graph 
is enlarged a bit.\\

Notice that this triangle has NOT the same geometry as the german 
system, although it has the same angles (the axis directions 
are different, and clay silt and sand are 'carried' by different 
axis).



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Customize texture class axis} 

Below is a code example to project the French 'Aisne' soil 
texture triangle, with clay at the bottom, silt on the left and 
sand on the right:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    class.sys   = "FR.AISNE.TT", 
    blr.tx      = c("CLAY","SILT","SAND"), 
    main        = "Re-projected French Aisne triangle (axis)"  
)   # 
@ 


The option \texttt{blr.tx} accept a vector of character strings. 
The \textbf{values} of the vector indicates which texture class 
should be drawn for the Bottom, Left and Right TEXtures; 
respectively.\\ 

The option \texttt{blr.tx} should not be confused with the option 
\texttt{css.names}, presented below ('Internationalization'), 
that defines the (columns) names taken by clay, silt and sand 
(respectively) in the data.frame passed to \texttt{tri.data}.\\

The option \texttt{blr.tx} should not be confused with the option 
\texttt{css.lab}, presented below ('Internationalization'), 
that defines the names (or expressions) displayed for clay, silt 
and sand axis labels / titles.



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Customise axis direction} 

Below is a code example to project the triangle of the European 
Soil Map (HYPRES), with the bottom axis anticlockwise, the left axis 
clockwise and the right axis 'neutral' (inside).


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    class.sys   = "HYPRES.TT", 
    blr.clock   = c(FALSE,TRUE,NA), 
    main        = "Re-projected European triangle (axis directions)"  
)   # 
@ 


the option \texttt{blr.clock} accept a vector of boolean (TRUE / 
FALSE) as argument for bottom direction (here clock = FALSE), 
left (clock = FALSE) and right (clock = NA). The \texttt{NA} 
value is used for the neutral case.



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Customise everything: plot The French GEPPA 
    classification in the French Aisne triangle} 

Below is a French GEPPA soil texture triangle plotted as a USDA or 
European (HYPRES) or French Aisne soil texture triangle, that is 
with custom angles, axis directions and clay silt sand positions 
on the axis:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    class.sys   = "FR.GEPPA.TT", 
    tlr.an      = c(60,60,60), 
    blr.tx      = c("SAND","CLAY","SILT"), 
    blr.clock   = c(TRUE,TRUE,TRUE), 
    main        = "Fully re-projected GEPPA triangle"  
)   # 
@ 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Miscellaneous: Different triangle geometry, but same 
    projected classes} 

I once found an illustration on a website showing a USDA and a 
French Aisne soil texture triangle displayed together, but with 
a different triangle geometry than the usual one. The surprise 
was that although the triangle geometry was different, the 
texture classes shapes (i.e. inside the triangle) looked exactly 
the same as the 'standard' display. Here is a practical example 
(not an explanation of this strange phenomenon!):


<<echo=TRUE,fig=TRUE,include=TRUE,height=7>>= 
# Set a 2 by 2 plot matrix:
old.par <- par(no.readonly=T)
par("mfcol" = c(1,2),"mfrow"=c(1,2)) 

# Plot the triangles with different geometries:
TT.plot( class.sys = "USDA.TT" ) 

TT.plot( 
    class.sys   = "USDA.TT", 
    blr.tx      = c("SILT","SAND","CLAY"), 
    blr.clock   = c(FALSE,FALSE,FALSE), 
    main        = "USDA triangle with a different geometry"  
)   # 

# Back to old parameters:
par(old.par)
@ 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\section{Internationalization: title, labels and data names in 
    different languages} 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Choose the language of texture triangle axis and 
    title} 

The \texttt{TT.plot()} function comes with a \texttt{lang} option 
("lang" for language) that allows to plot texture triangles with 
a title and axis labels in other languages than English (the 
default).\\

Here is a first example with French (\texttt{lang = "fr"}) and 
German (\texttt{lang = "de"}):


<<echo=TRUE,fig=TRUE,include=TRUE,height=7>>= 
# Set a 2 by 2 plot matrix:
old.par <- par(no.readonly=T)
par("mfcol" = c(1,2),"mfrow"=c(1,2)) 

# Plot the triangles with different languages:
TT.plot( 
    class.sys   = "FR.GEPPA.TT", 
    lang        = "fr" 
)   #

TT.plot( 
    class.sys   = "FR.GEPPA.TT", 
    lang        = "de" 
)   #

# Back to old parameters:
par(old.par)
@ 


A second example with Spanish (\texttt{lang = "es"}), 
and Italian (\texttt{lang = "it"}):


<<echo=TRUE,fig=TRUE,include=TRUE,height=7>>= 
# Set a 2 by 2 plot matrix:
old.par <- par(no.readonly=T)
par("mfcol" = c(1,2),"mfrow"=c(1,2)) 

# Plot the triangles with different languages:
TT.plot( 
    class.sys   = "FR.GEPPA.TT", 
    lang        = "es" 
)   #

TT.plot( 
    class.sys   = "FR.GEPPA.TT", 
    lang        = "it" 
)   #

# Back to old parameters:
par(old.par)
@ 


And a 3rd example with Dutch (\texttt{lang = "nl"}) and Flemish 
(\texttt{lang = "fl"}) or, to be more exact, with the terms used 
on the Dutch texture triangle and on the Flemish version of the 
Belgian texture triangle.


<<echo=TRUE,fig=TRUE,include=TRUE,height=7>>= 
# Set a 2 by 2 plot matrix:
old.par <- par(no.readonly=T)
par("mfcol" = c(1,2),"mfrow"=c(1,2)) 

# Plot the triangles with different languages:
TT.plot( 
    class.sys   = "FR.GEPPA.TT", 
    lang        = "nl" 
)   #

TT.plot( 
    class.sys   = "FR.GEPPA.TT", 
    lang        = "fl" 
)   #

# Back to old parameters:
par(old.par)
@ 


A 4th example in Swedish (\texttt{lang = "se"}) and in Romanian 
(\texttt{lang = "ro"}):


<<echo=TRUE,fig=TRUE,include=TRUE,height=7>>= 
# Set a 2 by 2 plot matrix (for size):
old.par <- par(no.readonly=T)
par("mfcol" = c(1,2),"mfrow"=c(1,2)) 

# Plot the triangles with different languages:
TT.plot( 
    class.sys   = "FR.GEPPA.TT", 
    lang        = "se" 
)   #

# Plot the triangles with different languages:
TT.plot( 
    class.sys   = "FR.GEPPA.TT", 
    lang        = "ro" 
)   #

# Back to old parameters:
par(old.par)
@ 


The polish language can be obtained by typing \texttt{lang = "pl"} 
on all platforms but Mac.\\


The Portuguese language can be obtained by typing \texttt{lang = "pt"}.


And finally in English, the default language (\texttt{lang = "en"}):


<<echo=TRUE,fig=TRUE,include=TRUE,height=7>>= 
# Set a 2 by 2 plot matrix (for size):
old.par <- par(no.readonly=T)
par("mfcol" = c(1,2),"mfrow"=c(1,2)) 

# Plot the triangles with different languages:
TT.plot( 
    class.sys   = "FR.GEPPA.TT", 
    lang        = "en" 
)   #

# Back to old parameters:
par(old.par)
@ 



Please report any mistakes in these translations. Please don't 
hesitate to send me new translations in other languages. This 
option is easily extensible. 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Use custom (columns) names for soil texture data} 



The dummy data table with french names can be displayed, but the option 
\texttt{css.names} (for Clay, Silt, Sand NAMES) must be specified, 
as a vector of character string, corresponding to the columns 
names of \texttt{tri.data}. \textbf{Notice that the order of 
css.names is NOT NECESSARILY the order of \texttt{tri.data} 
columns names}, so \texttt{css.names == colnames(my.text.fr)} 
would NOT always be true (although it is true here).


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    tri.data    = my.text.fr, 
    class.sys   = "HYPRES.TT", 
    css.names   = c("ARGILE","LIMON","SABLE") 
)   #
@ 

You can see that the column names ARGILE, LIMON and SABLE do not 
appear on the texture triangle plot. There is always a clear 
separation between the characteristics of the texture 
classification, the characteristics of the soil texture data 
provided, and the characteristics of the soil texture triangle 
plot/presentation. This is necessary for making different systems 
compatible.



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Use custom labels for the axis} 

It is also possible to use custom labels for the triangle axis. 
The option \texttt{css.lab} accept a vector (3) of character 
string, or a vector of expressions, for Clay, Silt and Sand 
LABels respectively (in that order, no matter the texture 
triangle system used. The function automatically places the good 
label on the good axis). 


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    tri.data    = my.text.fr, 
    class.sys   = "HYPRES.TT", 
    css.names   = c("ARGILE","LIMON","SABLE"), 
    css.lab     = c("l'argile [%]","Le limon [%]","Le sable [%]"), 
    main        = 
        "A texture triangle with (dummy) custom axis names"  
)   #
@ 


The use of expressions allows a finer customization of the axis 
labels, as for any R plot:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    tri.data    = my.text.fr, 
    class.sys   = "HYPRES.TT", 
    css.names   = c("ARGILE","LIMON","SABLE"), 
    css.lab     = expression( 
        bold(sqrt('Argile'^2)~'[%]'), 
        bold(sqrt('Limon'^2)~'[%]'), 
        bold(sqrt('Sable'^2)~'[%]')
    ),  #
    main        = 
        "A texture triangle with (dummy) custom axis names"  
)   #
@ 



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\section{Checking the geometry and classes boundaries of soil 
    texture classifications} 

'The Soil Texture Wizard' comes with several functions that helps 
to retrieve information about the geometry and classes boundaries 
of soil texture classifications, and thus to check by yourself 
that they are 'correct'.



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Checking the geometry of soil texture classifications} 

Below is a simple example of the way to retrieve the geometry 
of a given texture triangle (as it is implemented in the 'The 
Soil Texture Wizard'):


<<echo=TRUE>>= 
# Fisrt, retrieve all the data about 
#   the USDA texture triangle
tmp <- TT.get("USDA.TT") 

# It is not displayed here because it is to big
#   The list names are:
names(tmp) 

# If we drop "tt.points" and "tt.polygons", that will be 
#   presented later, the list size is more reasonable
tmp[ !names(tmp) %in% c("tt.points","tt.polygons") ]
@ 


Most of the list's names correspond to \texttt{TT.plot()}'s 
options that have been presented earlier in the document.



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\subsection{Checking classes names and boundaries of soil texture 
    classifications} 

The function \texttt{TT.classes.tbl()} returns a table with 
information about each soil texture class of a given soil texture 
classification / triangle:


<<echo=TRUE>>= 
# Retrieve and save the table:
tmp2 <- TT.classes.tbl( class.sys = "HYPRES.TT" ) 

# Display the first part:
tmp2[,1:2] 

# Then display the last column (and the 1st again):
tmp2[,c(1,3)] 
@ 


The 1st column is the classes abbreviation, the 2nd column is the 
classes full name (in the original language), and the 3rd class 
contains a list of vertices numbers, separated by a comma. These 
vertices are those who compose the class 'polygon'.\\

But the vertices numbers are of course not self explicit. For 
this reason, another function, \texttt{TT.vertices.tbl()}, 
extracts the vertices coordinates (as clay silt and sand content) 
from the triangle definition:


<<echo=TRUE>>= 
TT.vertices.tbl( class.sys = "HYPRES.TT" ) 
@ 


The 'points' number outputted by \texttt{TT.classes.tbl()} 
logically correspond to those outputted by 
\texttt{TT.vertices.tbl()}.\\


Finally, as it is difficult to visualize the position of each vertex with 
just a table, the function \texttt{TT.vertices.plot()} completes 
the two presented above, by plotting the vertices position and 
numbers on top of a texture triangle (preferable the same as the 
one you are actually checking!):


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
geo <- TT.plot( 
    class.sys   = "HYPRES.TT", 
    main        = "Vertices numbers. USDA texture triangle"
)   # 

TT.vertices.plot( 
    geo         = geo, 
    class.sys   = "HYPRES.TT", 
    col         = "red", 
    cex         = 2, 
    font        = 2  
)   #
@


Many \texttt{TT.vertices.plot()} options are shared with 
\texttt{TT.text()}, which an the underlying function of the first.



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\section{Adding your own, custom, texture triangle(s)} 

As said in the introduction, the idea behind 'The Soil Texture 
Wizard' is to be able to display 'any soil texture triangle / 
classification' in any 'triangle geometry'.\\

As there are much more texture classification systems than those 
implemented in 'The Soil Texture Wizard', the function 
\texttt{TT.add()} is there to 'add' any texture triangle to the 
existing list (your home made texture triangles).\\

In the example below, we will (1) extract and save the definition 
of the HYPRES texture triangle, (2) change the silt sand limit of 
the saved triangle definition from 50$\mu$m to 63$\mu$m, and (3) 
load the 'new' texture triangle into the existing list of 
triangle. There, it will be saved and usable as any texture 
triangle (at least until R is shut down).


<<echo=TRUE>>= 
# Step 1 
HYPRES63 <- TT.get("HYPRES.TT") 
#
# Visualize the data that will be modified
HYPRES63[[ "base.css.ps.lim" ]] 
HYPRES63[[ "tri.css.ps.lim" ]] 
#
# Step 2 
HYPRES63[[ "base.css.ps.lim" ]][3] <- 63 
HYPRES63[[ "tri.css.ps.lim" ]][3]  <- 63 
#
# Step 3: Load the new texture triangle
TT.add( "HYPRES63.TT" = HYPRES63 ) 
@ 


This (not so) new texture triangle is now usable as any other in 
the initial list:


<<echo=TRUE,fig=TRUE,include=TRUE>>= 
TT.plot( 
    class.sys   = "HYPRES63.TT", 
    main        = "Modified European soil texture triangle"
)   # 
@


If you consider creating a completely new triangle, you will need 
to copy / imitate the structure of existing texture triangle 
definitions.\\

This definition is a list of parameters:


<<echo=TRUE>>= 
# Get the definition of the HYPRES texture triangle
HYPRES <- TT.get( "HYPRES.TT" ) 
#
# Check its class (list) 
class( HYPRES ) 
#
# Check its parameters names 
names( HYPRES ) 
#
# Check its parameters class 
for( i in 1:length(HYPRES) )
{   
    print( 
        paste( 
            names( HYPRES )[i], 
            class( HYPRES[[i]] ), 
            sep = ": "
        )   
    )    
}   
@ 

All elements are (probably) self explicit, or have been presented 
earlier in the document (as options of \texttt{TT.plot()} for 
instance), except for \texttt{tt.points} and \texttt{tt.polygons}.\\ 

\texttt{tt.points} is a 3 column data.frame, with columns names 
CALY SILT and SAND, that gives the clay, silt and sand 
'coordinates' of all the vertices in the triangles. Rows numbers 
corresponds to the 'official' vertex number. Vertices are unique, 
they can not be repeated, even if they are 'used' in several 
classes definition / polygon.\\ 

\texttt{tt.polygons} is a list. Each element of the list 
corresponds to one texture class. The name of each element of the 
list is the texture class abbreviation. Then, each element of the 
list (i.e. each class) itself contains a list, with two elements, 
named \texttt{"name"} and \texttt{"points"}. \texttt{"name"} is a 
single character string, corresponding to the texture class 'full 
name' in the triangle's native language (but special character 
should be avoided). \texttt{"points"} is an ordered vector of 
integers, corresponding to the numbers of the vertices numbers 
that compose each class's polygon. The numbers in fact 
corresponds to the row names of \texttt{tt.points}. They should 
be ordered, in the sense that each successive pair of vertices 
will be joined by a polygon edge (+ one between the 1st and the 
last points).\\

If you want to have a more precise idea of the code's shape for 
a new texture triangle, you can have a look inside 'The Soil 
Texture Wizard' code (FUNCTION\_TEXTURE\_WIZARD.R): search the 
name of a texture triangle (e.g. "HYPRES.TT") in the code and look 
the structure of the list corresponding to it.\\

If you implement a texture triangle that you think can be used 
by many soil scientists, please consider sending its definition's 
code to me, I will implement it into 'The Soil Texture Wizard' 
(copy and paste)\footnote{Under the same open-source licence 
terms as all the function set, but with reference to you work and 
your work's 'model'}. If doing this, it is als good to send an 
image of the 'reference' texture triangle that was used to obtain the 
triangle's definition (so it can be checked!).



% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
\section{Further readings} 

Readers wishing to go further in the study of soil texture 
triangles and related topics may like the following articles: 
Richer de Forges et al. 2001 a (in French, \cite{RICHER2008EGS}) 
and b (Poster in English, \cite{RICHER2008INRA}; Nemes et al. 1999 
(about texture transformation, \cite{NEMES1999GEOD}); Gerakis and 
Baer (program for USDA texture classification, 
\cite{GERAKIS1999SSSAJ}); Liebens 2001 (Excel MACRO for USDA 
texture classification, \cite{LIEBENS2001CPSA}); Minasny and 
McBratney 2001 (about texture transformation, 
\cite{MINASNY2001AJSR}); Teh and Rashid 2003 (program for texture 
classification in a lot of systems, \cite{TEH2003CPSA}) and 
Christopher (Teh) and Mokhtaruddin 1996\cite{TEH1996}.




\bibliography{soiltexture_vignette} % no .bib extension here
\end{document}
