sorcering: Soil ORganic Carbon & CN Ratio drIven Nitrogen modellinG...
In sorcering: Soil Organic Carbon and CN Ratio Driven Nitrogen Modelling Framework
sorcering R Documentation
Soil ORganic Carbon & CN Ratio drIven Nitrogen modellinG framework
Description
SORCERING can be used to model the fate of soil organic carbon (SOC) and soil organic nitrogen (SON) and to calculate N mineralisation
rates.
It provides a framework that numerically solves differential equations of SOC models based on first-order kinetics.
Thus, SOC models can be simply defined and run to predict the temporal development of SOC. Beyond this, SORCERING determines the fluxes of SON and N mineralisation / immobilisation.
Basic inputs are
(1) the model parameters of a given SOC model expressed as the C transfer matrix (including information on decomposition and transfer rates between model pools),
(2) the initial distributions of C and N among model pools and
(3) time series of C and N inputs and rate modulating environmental factors.
The fourth-order Runge-Kutta algorithm is used to numerically solve the system of differential equations.
\loadmathjax
Usage
sorcering( A = NULL,
t_sim = 2,
tsteps = "monthly",
C0 = NULL,
N0 = NULL,
Cin = NULL,
Nin = NULL,
xi = NULL,
calcN = FALSE,
calcNbalance = FALSE)
Arguments
A
transfer matrix. Defines number of pools, decomposition and transfer rates. Must be a square matrix. n\mjeqn\timesXn elements with n = number of pools. Diagonal values are decomposition rates
[\mjeqnyr^-1yr^(-1)]. Off-diagonals represent the transfer between pools [\mjeqnyr^-1yr^(-1)].
t_sim
number of simulation time steps. Must correspond to the number of rows of Cin, Nin and xi.
tsteps
character indicating the type of simulation time steps. valid options are annually, monthly (recommended) or weekly.
C0
vector with a length equal to the number of pools. Contains initial soil organic carbon per pool [\mjeqnt C \ ha^-1t C ha^(-1)]. If NULL, filled with zeros.
N0
vector with a length equal to the number of pools. Contains initial soil organic nitrogen per pool [\mjeqnt N \ ha^-1t N ha^(-1)]. If NULL, filled with zeros. Only used when calcN = TRUE.
Cin
matrix with a number of columns equal to the number of pools and a number of rows corresponding to t_sim. Contains carbon input per pool and time step [\mjeqnt C \ ha^-1t C ha^(-1)]. If NULL, filled with zeros.
Nin
matrix with a number of columns equal to the number of pools and a number of rows corresponding to t_sim. Contains nitrogen input per pool and time step [\mjeqnt N \ ha^-1t N ha^(-1)]. If NULL, filled with zeros. Must be >0 where Cin>0. Only used when calcN = TRUE.
xi
matrix with a number of columns equal to the number of pools and a number of rows corresponding to t_sim. Contains environmental factors. If NULL, filled with ones.
calcN
logical indicating whether the development of soil organic nitrogen should be simulated.
calcNbalance
logical indicating whether the balance of nitrogen cycling should be calculated.
Details
SORCERING is a general model framework to describe soil organic carbon (SOC) dynamics and soil organic nitrogen (SON) dynamics based on models of first-order kinetics.
It can be applied to any given SOC first-order kinetics model.
The approach has already been successfully tested to describe SOC dynamics of Yasso \insertCiteTuomi2009sorcering, RothC \insertCiteColeman1996sorcering and
C-Tool \insertCiteTaghizadeh-Toosi2014sorcering.
Therefore, SORCERING is a lightweight alternative to the widely developed and multifunctional R package SoilR \insertCiteSierra2012,Sierra2014sorcering.
Moreover, it additionally offers the possibility of modelling N immobilisation and mineralisation by enhancing given SOC models by an additional N module.
The following is a description of each element calculated, which also corresponds to the output values (see section 'Value').
For a detailed mathematical description of the SORCERING function see the extended pdf documentation at browseVignettes("sorcering").
C
SORCERING calculates SOC applying a given SOC model for every simulation time step defined by tsteps and t_sim.
SOC models applied here are defined by a number of pools, each characterised by specific decomposition and turnover rates.
The model-specific decomposition kinetics and SOC fluxes among pools are described by a set of partial differential equations represented by the transfer matrix A.
Each row and column of A represent SOC pools. Off-diagonal elements of A describe SOC fluxes and diagonal elements describe SOC decomposition.
The differential equations furthermore contain the boundary conditions Cin and xi.
The change of SOC concentration in time thus is defined as:
\mjdeqn\frac dC(t) dt = Cin(t)+A_e(t) \cdot C(t)dC(t)/dt = Cin(t) + A_e(t) * C(t)
with
\mjdeqnA_e(t) = A \cdot diag(xi(t))Ae(t) = A * diag(xi(t))
Initial conditions must be defined for every SOC pool by C0.
A description of the numerical solution can be found in the extended pdf documentation at browseVignettes("sorcering").
For more information on the functioning and possibilities of solving first-order kinetics SOC models see \insertCiteSierra2012;textualsorcering.
N
As an extension to SOC modelling, SORCERING allows the modelling of SON coupled to the modelling of SOC. Its implementation is based on the following simplifying assumptions:
(1) Nitrogen transfer and turnover rates are equal to carbon rates.
(2) There is no N limitation in the soil, i.e. mineral N is always available for N immobilisation processes.
(3) CN ratios of single pools are only affected by external inputs of N and C. The transfer of organic matter among pools does not affect CN ratios.
As for SOC, the development of SON depends on initial and boundary conditions: N0 and Nin.
As N decomposition is proportional to C decomposition, SON is calculated based on the results of the SOC calculations and
input conditions (for details see the extended pdf documentation at browseVignettes("sorcering")).
Nloss, Nmin, Nmin.sink<1>, ..., Nmin.sink<n>
Along with modelling SON, further quantities are determined.
Nitrogen losses are calculated as:
\mjdeqn
Nloss(t) = N(t-1) + Nin(t-1) - N(t)
Nloss(t) = N(t-1) + Nin(t-1) - N(t)
In contrast, mineralisation rates contain information about sources and sinks of SON.
They are calculated based on the CN ratios in the pools and the turnover rates (for details see the extended pdf documentation at browseVignettes("sorcering")).
Pool-specific N mineralisation \mjeqnNmin.sink\left\langle 1 \right\rangle, ..., Nmin.sink\left\langle n \right\rangleNmin.sink_(1, ..., n) and N mineralisation \mjeqnNminNmin are related the following:
\mjdeqn
Nmin_j(t) = \sum_p=1^n Nmin.sink \left\langle j \right\rangle_p(t)
Nmin_j(t) = sum over p=1..n of Nmin.sink<j>_p(t)
for each simulation time point \mjeqntt, each pool \mjeqnj = 1, ..., nj = 1, ..., n and each pool \mjeqnp = 1, ..., np = 1, ..., n and \mjeqnnn total pools.
Or in other words, the row sum of \mjeqnNmin.sink\left\langle j \right\rangleNmin.sink<j> at one simulation time point
equals the jth column of \mjeqnNminNmin at that time point.
As changes in SON must match the sums of all mineralisation paths, the sums over soil pools of Nloss and Nmin, respectively, must be approximately equal for all simulation time points:
\mjtdeqn\beginmatrix \sum_p=1^n Nloss_p(t) \approx \sum_p=1^n Nmin_p(t) & \forall t \in tseq \endmatrixsum over p=1..n of Nloss_p(t) ~ sum over p=1..n of Nmin_p(t), for all t element t_seq
\mjtdeqn\sum_p=1^n Nloss_p(t) \approx \sum_p=1^n Nmin_p(t) , \forall t \in tseq
A verification of this relation is given by "Nbalance" (see below).
Nbalance
The overall N change between two time steps is calculated as:
\mjdeqn
\Delta N (t) = \sum_p=1^n N_p(t-1) - \sum_p=1^n N_p(t)
dN(t) = sum over p=1..n of N_p(t) - sum over p=1..n of N_p(t-1)
The total system N balance serves as a verification output. Both of the following equations should give results close to zero:
\mjdeqn
N_bal1(t) = \sum_p=1^n Nin_p(t-1) + \Delta N (t) - \sum_p=1^n Nloss_p(t) \approx 0
N_bal1(t) = sum over p=1..n of Nin_p(t-1) - dN(t) - sum of p=1..n of Nloss_p(t) ~ 0
\mjdeqn
N_bal2(t) = \sum_p=1^n Nin_p(t-1) + \Delta N (t) - \sum_p=1^n Nmin_p(t) \approx 0
N_bal2(t) = sum over p=1..n of Nin_p(t-1) - dN(t) - sum of p=1..n of Nmin_p(t) ~ 0
Value
sorcering() returns a list object with components:
C
array with a number of rows corresponding to t_sim and a number of columns equal to the number of pools. Contains soil organic carbon [\mjeqnt C \ ha^-1t C ha^(-1)].
N
array with a number of rows corresponding to t_sim and a number of columns equal to the number of pools. Contains soil organic nitrogen [\mjeqnt N \ ha^-1t N ha^(-1)]. Only generated if calcN = TRUE.
Nloss
array with a number of rows corresponding to t_sim and a number of columns equal to the number of pools. Contains nitrogen losses [\mjeqnt N \ ha^-1t N ha^(-1)]. Only generated if calcN = TRUE.
Nmin
array with a number of rows corresponding to t_sim and a number of columns equal to the number of pools. Contains nitrogen mineralisation [\mjeqnt N \ ha^-1t N ha^(-1)]. If values are negative, nitrogen immobilisation exceeds mineralisation. Only generated if calcN = TRUE.
Nmin.sink.1, ..., Nmin.sink.n
arrays with a number of rows corresponding to t\_sim and a number of columns equal to the number of pools n. Contain pool-specific nitrogen mineralisation sinks [\mjeqnt N \ ha^-1t N ha^(-1)] (from the pool according to variable index [1, ..., n] to the pool according to column number). If the sink is the pool itself (index equals column number) the amount of decomposition is recorded. Only generated if calcN = TRUE.
Nbalance
array with a number of rows corresponding to t_sim and three columns. Contains information on overall N changes in the soil between two time steps (first column) and information on total system N balance calculated based on total Nloss (second column) and based on total Nmin (third column) [\mjeqnt N \ ha^-1t N ha^(-1)]. Only generated if calcN = TRUE and calcNbalance = TRUE.
Package Building Information
The SORCERING code was written in C++ using the R packages Rcpp \insertCiteEddelbuettel2021sorcering
and RcppArmadillo \insertCiteEddelbuettel2021asorcering.
This documentation was built with the help of the R packages mathjaxr \insertCiteViechtbauer2021sorcering
and Rdpack \insertCiteBoshnakov2021sorcering.
Author(s)
Marc Scherstjanoi marc.scherstjanoi@thuenen.de, Rene Dechow
References
\insertAllCited
Examples
#EXAMPLE OF RothC application with fictional input
#1. Input
data(Cin_ex, Nin_ex, N0_ex, C0_ex, xi_ex) #fictional data
A_RothC <- fget_A_RothC(clay=30) #create transfer matrix for RothC
#2. simulation
out <- sorcering(A=A_RothC, t_sim=60, Cin=Cin_ex, Nin=Nin_ex,
N0=N0_ex, C0=C0_ex, xi=xi_ex, calcN=TRUE, tsteps="monthly")
#3. results
#output structure summary
summary(out)
#sample plot
oldpar <- par(no.readonly = TRUE) #save old par
par(mfrow=c(1,1),mar=c(4,5,2,5))
plot(rowSums(out$N),axes=FALSE, col=1, cex.lab=1.5,xlab="",ylab="",ylim=c(0,9),pch=20)
par(new=TRUE)
plot(rowSums(Cin_ex)/rowSums(Nin_ex),
axes=FALSE,col=2, cex.lab=1.5,xlab="",ylab="",ylim=c(0,60),pch=20)
axis(side=2, pos = 0, labels = c((0:4)*1.5,"N",9),
at=(0:6)*10, hadj=1, padj = 0.5, cex.axis=1.5,las=1,col.axis=1)
axis(side=4, pos = 60, labels = c((0:4)*10,"Cin/Nin",60),
at=(0:6)*10, hadj=0, padj = 0.5, cex.axis=1.5, las=1,col.axis=2)
axis(side=1, pos = 0, labels = c((0:4)*10,"t",60),
at=(0:6)*10, hadj=0.5, padj = 0, cex.axis=1.5)
par(oldpar) #back to old par
sorcering documentation built on March 7, 2023, 7:28 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| sorcering | R Documentation |
Soil ORganic Carbon & CN Ratio drIven Nitrogen modellinG framework
Description
SORCERING can be used to model the fate of soil organic carbon (SOC) and soil organic nitrogen (SON) and to calculate N mineralisation
rates.
It provides a framework that numerically solves differential equations of SOC models based on first-order kinetics.
Thus, SOC models can be simply defined and run to predict the temporal development of SOC. Beyond this, SORCERING determines the fluxes of SON and N mineralisation / immobilisation.
Basic inputs are
(1) the model parameters of a given SOC model expressed as the C transfer matrix (including information on decomposition and transfer rates between model pools),
(2) the initial distributions of C and N among model pools and
(3) time series of C and N inputs and rate modulating environmental factors.
The fourth-order Runge-Kutta algorithm is used to numerically solve the system of differential equations.
\loadmathjax
Usage
sorcering( A = NULL,
t_sim = 2,
tsteps = "monthly",
C0 = NULL,
N0 = NULL,
Cin = NULL,
Nin = NULL,
xi = NULL,
calcN = FALSE,
calcNbalance = FALSE)
Arguments
A |
transfer matrix. Defines number of pools, decomposition and transfer rates. Must be a square matrix. n\mjeqn\timesXn elements with n = number of pools. Diagonal values are decomposition rates [\mjeqnyr^-1yr^(-1)]. Off-diagonals represent the transfer between pools [\mjeqnyr^-1yr^(-1)]. |
t_sim |
number of simulation time steps. Must correspond to the number of rows of |
tsteps |
character indicating the type of simulation time steps. valid options are |
C0 |
vector with a length equal to the number of pools. Contains initial soil organic carbon per pool [\mjeqnt C \ ha^-1t C ha^(-1)]. If |
N0 |
vector with a length equal to the number of pools. Contains initial soil organic nitrogen per pool [\mjeqnt N \ ha^-1t N ha^(-1)]. If |
Cin |
matrix with a number of columns equal to the number of pools and a number of rows corresponding to |
Nin |
matrix with a number of columns equal to the number of pools and a number of rows corresponding to |
xi |
matrix with a number of columns equal to the number of pools and a number of rows corresponding to |
calcN |
logical indicating whether the development of soil organic nitrogen should be simulated. |
calcNbalance |
logical indicating whether the balance of nitrogen cycling should be calculated. |
Details
SORCERING is a general model framework to describe soil organic carbon (SOC) dynamics and soil organic nitrogen (SON) dynamics based on models of first-order kinetics.
It can be applied to any given SOC first-order kinetics model.
The approach has already been successfully tested to describe SOC dynamics of Yasso \insertCiteTuomi2009sorcering, RothC \insertCiteColeman1996sorcering and
C-Tool \insertCiteTaghizadeh-Toosi2014sorcering.
Therefore, SORCERING is a lightweight alternative to the widely developed and multifunctional R package SoilR \insertCiteSierra2012,Sierra2014sorcering.
Moreover, it additionally offers the possibility of modelling N immobilisation and mineralisation by enhancing given SOC models by an additional N module.
The following is a description of each element calculated, which also corresponds to the output values (see section 'Value').
For a detailed mathematical description of the SORCERING function see the extended pdf documentation at browseVignettes("sorcering").
C
SORCERING calculates SOC applying a given SOC model for every simulation time step defined by tsteps and t_sim.
SOC models applied here are defined by a number of pools, each characterised by specific decomposition and turnover rates.
The model-specific decomposition kinetics and SOC fluxes among pools are described by a set of partial differential equations represented by the transfer matrix A.
Each row and column of A represent SOC pools. Off-diagonal elements of A describe SOC fluxes and diagonal elements describe SOC decomposition.
The differential equations furthermore contain the boundary conditions Cin and xi.
The change of SOC concentration in time thus is defined as:
dC(t) dt = Cin(t)+A_e(t) \cdot C(t)dC(t)/dt = Cin(t) + A_e(t) * C(t)
with \mjdeqnA_e(t) = A \cdot diag(xi(t))Ae(t) = A * diag(xi(t))
Initial conditions must be defined for every SOC pool by C0.
A description of the numerical solution can be found in the extended pdf documentation at browseVignettes("sorcering").
For more information on the functioning and possibilities of solving first-order kinetics SOC models see \insertCiteSierra2012;textualsorcering.
N
As an extension to SOC modelling, SORCERING allows the modelling of SON coupled to the modelling of SOC. Its implementation is based on the following simplifying assumptions:
(1) Nitrogen transfer and turnover rates are equal to carbon rates.
(2) There is no N limitation in the soil, i.e. mineral N is always available for N immobilisation processes.
(3) CN ratios of single pools are only affected by external inputs of N and C. The transfer of organic matter among pools does not affect CN ratios.
As for SOC, the development of SON depends on initial and boundary conditions: N0 and Nin.
As N decomposition is proportional to C decomposition, SON is calculated based on the results of the SOC calculations and
input conditions (for details see the extended pdf documentation at browseVignettes("sorcering")).
Nloss, Nmin, Nmin.sink<1>, ..., Nmin.sink<n>
Along with modelling SON, further quantities are determined. Nitrogen losses are calculated as:
\mjdeqnNloss(t) = N(t-1) + Nin(t-1) - N(t) Nloss(t) = N(t-1) + Nin(t-1) - N(t)
In contrast, mineralisation rates contain information about sources and sinks of SON.
They are calculated based on the CN ratios in the pools and the turnover rates (for details see the extended pdf documentation at browseVignettes("sorcering")).
Pool-specific N mineralisation \mjeqnNmin.sink\left\langle 1 \right\rangle, ..., Nmin.sink\left\langle n \right\rangleNmin.sink_(1, ..., n) and N mineralisation \mjeqnNminNmin are related the following:
Nmin_j(t) = \sum_p=1^n Nmin.sink \left\langle j \right\rangle_p(t) Nmin_j(t) = sum over p=1..n of Nmin.sink<j>_p(t)
for each simulation time point \mjeqntt, each pool \mjeqnj = 1, ..., nj = 1, ..., n and each pool \mjeqnp = 1, ..., np = 1, ..., n and \mjeqnnn total pools. Or in other words, the row sum of \mjeqnNmin.sink\left\langle j \right\rangleNmin.sink<j> at one simulation time point equals the jth column of \mjeqnNminNmin at that time point.
As changes in SON must match the sums of all mineralisation paths, the sums over soil pools of Nloss and Nmin, respectively, must be approximately equal for all simulation time points:
matrix \sum_p=1^n Nloss_p(t) \approx \sum_p=1^n Nmin_p(t) & \forall t \in tseq \endmatrixsum over p=1..n of Nloss_p(t) ~ sum over p=1..n of Nmin_p(t), for all t element t_seq \mjtdeqn\sum_p=1^n Nloss_p(t) \approx \sum_p=1^n Nmin_p(t) , \forall t \in tseq
A verification of this relation is given by "Nbalance" (see below).
Nbalance
The overall N change between two time steps is calculated as: \mjdeqn \Delta N (t) = \sum_p=1^n N_p(t-1) - \sum_p=1^n N_p(t) dN(t) = sum over p=1..n of N_p(t) - sum over p=1..n of N_p(t-1)
The total system N balance serves as a verification output. Both of the following equations should give results close to zero: \mjdeqn N_bal1(t) = \sum_p=1^n Nin_p(t-1) + \Delta N (t) - \sum_p=1^n Nloss_p(t) \approx 0 N_bal1(t) = sum over p=1..n of Nin_p(t-1) - dN(t) - sum of p=1..n of Nloss_p(t) ~ 0
\mjdeqnN_bal2(t) = \sum_p=1^n Nin_p(t-1) + \Delta N (t) - \sum_p=1^n Nmin_p(t) \approx 0 N_bal2(t) = sum over p=1..n of Nin_p(t-1) - dN(t) - sum of p=1..n of Nmin_p(t) ~ 0
Value
sorcering() returns a list object with components:
C |
array with a number of rows corresponding to |
N |
array with a number of rows corresponding to |
Nloss |
array with a number of rows corresponding to |
Nmin |
array with a number of rows corresponding to |
Nmin.sink.1, ..., Nmin.sink.n |
arrays with a number of rows corresponding to |
Nbalance |
array with a number of rows corresponding to |
Package Building Information
The SORCERING code was written in C++ using the R packages Rcpp \insertCiteEddelbuettel2021sorcering
and RcppArmadillo \insertCiteEddelbuettel2021asorcering.
This documentation was built with the help of the R packages mathjaxr \insertCiteViechtbauer2021sorcering
and Rdpack \insertCiteBoshnakov2021sorcering.
Author(s)
Marc Scherstjanoi marc.scherstjanoi@thuenen.de, Rene Dechow
References
\insertAllCitedExamples
#EXAMPLE OF RothC application with fictional input
#1. Input
data(Cin_ex, Nin_ex, N0_ex, C0_ex, xi_ex) #fictional data
A_RothC <- fget_A_RothC(clay=30) #create transfer matrix for RothC
#2. simulation
out <- sorcering(A=A_RothC, t_sim=60, Cin=Cin_ex, Nin=Nin_ex,
N0=N0_ex, C0=C0_ex, xi=xi_ex, calcN=TRUE, tsteps="monthly")
#3. results
#output structure summary
summary(out)
#sample plot
oldpar <- par(no.readonly = TRUE) #save old par
par(mfrow=c(1,1),mar=c(4,5,2,5))
plot(rowSums(out$N),axes=FALSE, col=1, cex.lab=1.5,xlab="",ylab="",ylim=c(0,9),pch=20)
par(new=TRUE)
plot(rowSums(Cin_ex)/rowSums(Nin_ex),
axes=FALSE,col=2, cex.lab=1.5,xlab="",ylab="",ylim=c(0,60),pch=20)
axis(side=2, pos = 0, labels = c((0:4)*1.5,"N",9),
at=(0:6)*10, hadj=1, padj = 0.5, cex.axis=1.5,las=1,col.axis=1)
axis(side=4, pos = 60, labels = c((0:4)*10,"Cin/Nin",60),
at=(0:6)*10, hadj=0, padj = 0.5, cex.axis=1.5, las=1,col.axis=2)
axis(side=1, pos = 0, labels = c((0:4)*10,"t",60),
at=(0:6)*10, hadj=0.5, padj = 0, cex.axis=1.5)
par(oldpar) #back to old par
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.