% +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ % | 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 <>= # 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 | % +~~~~~~~~~~~~~~~~~~~~~~~~~~~~+ <>= 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: <>= 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} <>= 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: <>= 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}). <>= TT.plot( class.sys = "HYPRES.TT", tri.data = data.frame( "CLAY" = 45, "SILT" = 38, "SAND" = 17 ), main = NA ) @ The soil texture class symbols are: <>= library( "xtable" ) @ <>= 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: <>= 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: <>= install.packages( pkgs = "soiltexture", repos = "http://R-Forge.R-project.org" ) @ It can then be loaded with the following command: <>= library( soiltexture ) @ If you get bored of the package, you can unload it and uninstall it with the following commands: <>= 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: % <>= % 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: % <>= % 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...): % <>= % # 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): <>= 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: <>= 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.\\ <>= 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: <>= 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: <>= 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.\\ <>= 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: <>= 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.\\ <>= 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: <>= 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.}.\\ <>= 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: <>= 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.\\ <>= 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: <>= 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.\\ <>= 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: <>= TT.plot( class.sys = "DE.SEA74.TT" ) @ <>= 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: <>= 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: <>= 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: <>= TT.plot( class.sys = "DE.TGL85.TT" ) @ <>= 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: <>= 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: <>= 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: <>= 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.\\ <>= 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: <>= 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. <>= 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: <>= 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. <>= 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: <>= TT.plot( class.sys = "CA.EN.TT" ) @ For the same triangle with French texture class abbreviations type: <>= 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: <>= 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: <>= 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: <>= 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: <>= 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: <>= 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: <>= 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: <>= 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: % <>= % if( Sys.info()["sysname"] != "Mac" ){ % TT.plot( class.sys = "PL.TT" ) % } # % @ <>= 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}.\\ % <>= % if( Sys.info()["sysname"] != "Mac" ){ % if( Sys.info()["sysname"] != "Mac" ){ % plLim <- TT.get("PL.TT")[["base.css.ps.lim"]][3] % }else{ % plLim <- "..." % } # % } # % @ <>= 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: % <>= % 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 % ) # % } # % @ <>= 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: <>= 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}.\\ <>= 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: <>= 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: <>= 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}.\\ <>= 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: <>= 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: <>= 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: <>= 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: <>= 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: <>= 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: <>= # 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: <>= # 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: <>= # 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: <>= # 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): <>= # 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: <>= 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: <>= # 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: <>= # 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): <>= # 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: <>= 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: <>= 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. <>= rand.text <- TT.dataset(n=100,seed.val=1980042401) @ <>= 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: <>= 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 <>= 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 <>= 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 <>= 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 <>= 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 <>= 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: <>= # 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: <>= 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): <>= 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: <>= 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: <>= 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. <>= 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). <>= 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}: <>= 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. <>= 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): <>= 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: <>= 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. <>= # 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: <>= 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: <>= # 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: <>= 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: <>= 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: <>= # 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). <>= # 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): <>= # 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: <>= # 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: <>= 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: <>= # 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}. <>= 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): <>= 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): <>= 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: <>= 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: <>= # 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()}: <>= 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: <>= 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: <>= 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). <>= 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: <>= 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!): <>= # 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"}): <>= # 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"}): <>= # 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. <>= # 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"}): <>= # 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"}): <>= # 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). <>= 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). <>= 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: <>= 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'): <>= # 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: <>= # 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: <>= 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!): <>= 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). <>= # 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: <>= 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: <>= # 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}