macroutilsFocusGWConc-methods: INTERNAL/NON-OFFICIAL: Calculate the yearly and Xth...
In julienmoeys/macroutils2: R Utility Functions for the MACRO and SOILNDB Models
macroutilsFocusGWConc R Documentation
INTERNAL/NON-OFFICIAL: Calculate the yearly and Xth percentile groundwater concentration from a MACROInFOCUS output.
Description
INTERNAL & NON-OFFICIAL: Calculate the yearly and Xth percentile
groundwater concentration from a MACROInFOCUS output.
WARNING This function is not part
of the official MACROInFOCUS program. It is provided
for test-purpose, without any guarantee or support from
the authors, CKB, SLU or KEMI. You are strongly recommended to
benchmark the function against a range of (official)
MACROInFOCUS simulation results, before you use the
function. You are also strongly recommended to inspect
the code of these functions before you use them. To
inspect the content of these functions, simply type
body( macroutils2:::macroutilsFocusGWConc.data.frame )
after you have loaded the package macroutils2.
Usage
macroutilsFocusGWConc(
x,
nbYrsWarmUp = 6L,
yearsAvg = NULL,
prob = 0.8,
method = c("focus", "R", "test")[1L],
negToZero = TRUE,
type = 7L,
quiet = FALSE,
massunits = 2L,
...
)
## S3 method for class 'character'
macroutilsFocusGWConc(
x,
nbYrsWarmUp = 6L,
yearsAvg = NULL,
prob = 0.8,
method = c("focus", "R", "test")[1L],
negToZero = TRUE,
type = 7L,
quiet = FALSE,
massunits = 2L,
...
)
## S3 method for class 'list'
macroutilsFocusGWConc(
x,
nbYrsWarmUp = 6L,
yearsAvg = NULL,
prob = 0.8,
method = c("focus", "R", "test")[1L],
negToZero = TRUE,
type = 7L,
quiet = FALSE,
massunits = 2L,
...
)
## S3 method for class 'data.frame'
macroutilsFocusGWConc(
x,
nbYrsWarmUp = 6L,
yearsAvg = NULL,
prob = 0.8,
method = c("focus", "R", "test")[1L],
negToZero = TRUE,
type = 7L,
quiet = FALSE,
massunits = 2L,
output_water = c(target_l = TRUE, lower_b = TRUE),
output_solute = c(target_l = TRUE, lower_b = FALSE),
...
)
Arguments
x
Either a vector of character strings, a
data.frame, or a list of
data.frames. If a vector of character
strings, names (and possibly paths to) a .bin file
output by MACROInFOCUS. The argument is passed internally
to macroReadBin (its
file-argument). If a (list of)
data.frame(s), it should be imported from
a .bin file output by MACROInFOCUS (for example
with macroReadBin).
nbYrsWarmUp
Single integer values: Number of warm-up years that
should be removed from the beginning of the model output.
A default of 6 years of warn-up are used in FOCUS.
yearsAvg
Single integer values: Number of simulation years to
"aggregate" when calculating yearly- or biennial- or
triennial- (etc.) average concentrations.
If yearsAvg=1L, the function calculates yearly-
average concentrations before calculating the Xth
worst-case percentile. If yearsAvg=2L, the function
calculates biennial-average concentrations. If
yearsAvg=3L, the function calculates
triennial-average concentrations (etc.). The default in
FOCUS is to calculate yearly avegares when the pesticide
is applied yearly, biennial-averages when the pesticide
is applied every two years and triennial averages when
the pesticide is applied every three years. When
yearsAvg is NULL (the default), the function
tries to automatically sets and control this parameter.
prob
Single numeric value, between 0 and 1. Probability
(percentile/100) of the worst case concentration
that shall be calculated. In FOCUS, the yearly results
are ordered by increasing yearly average concentrations
before the percentile is calculated, as the average
concentration of the two years closest to the Xth percentile
(X always being 80, in FOCUS). Here, in practice, the
index of the 1st and 2nd year used for calculating the
average are selected as follow:
min_index = floor(prob *(number of sim years used)) and
max_index = ceiling(prob *(number of sim years used)),
but in cases min_index is identical to max_index,
then max_index is defined as min_index + 1,
unless prob is 0 or 1 (to get the minimum
or the maximum yearly concentrations, respectively).
The number of simulation years used is equal to the total
number of simulation years in x minus
nbYrsWarmUp. In practice, what is calculated
"a la FOCUS", when prob = 0.8, is an average
between the 80th and the 85th percentile yearly
concentrations. See FOCUS Groundwater main report p 475
(reference above). Notice that the algorithm also calculates
a Xth percentile concentration (x = prob * 100)
using R function quantile, with
its default parametrisation and quantile-calculation
method (Note: see the help page of the function if you
are interested to see how that percentile is obtained).
method
Single character string. If method = "focus" (the default),
the percentile is calculated with the default FOCUS method,
that is the concentration derived from the cumulated
yearly (or biennial or triennial) water and solute flow
from the two years closest to the Xth percentile
concentration (where X = prob * 100). If
method = "R", the concentration is calculated using
R function quantile, calculated
directly on the yearly (or biennial or triennial)
concentrations. If method = "test", it is expected
that the simulation is a "short test" simulation, for example
one year long, and a simple average concentration may be
returned when a PEC-groundwater cannot be calculated.
Only meant to be used when performing functional tests.
negToZero
Single logical value. If TRUE (not the default)
negative concentrations will be set to 0 (presumably like
in MACROInFOCUS). If FALSE, they will not be set
to 0, but if some of the concentrations used to calculate
the Xth percentile (see yearsXth) are negative,
a warning will be issued (so that the user knows that
concentrations may differ from those in MACROInFOCUS).
type
Single integer value. Only used when method = "R"
(see above). See quantile.
quiet
Single logical value. Set to TRUE to suppress the
warning message. Default value to FALSE.
massunits
Single integer value. Code for the mass unit of the simulation
result in x. 1 is micro-grams, 2is
milligrams (the default in MACRO In FOCUS and thus in this
function), 2 is grams and 4 is kilograms.
Corresponds to the parameter MASSUNITS in MACRO.
...
Additional parameters passed to
macroReadBin, when x is
a character string naming one or several files to be
imported. Not used otherwise.
output_water
Vector of two logical value, labelled "target_l"
and "lower_b". Indicates whether or not output
should be reported for the water flow through the target
layer or at the lower boundary, respectively.
output_solute
Vector of two logical value, labelled "target_l"
and "lower_b". Indicates whether or not output
should be reported for the solute flow through the target
layer or at the lower boundary, respectively. Both water
and solute flow should be returned for the target layer or
the lower boundary for the concentration to be reported
at the target layer or the lower boundary.
Value
Returns a list with the following items:
"info_general"
A data.frame with the following columns:
"conc_percentile"The percentile used to
calculate the Predicted Environmental Concentration
(columns ug_per_L in items
conc_target_layer and conc_perc,
below), in [%].
"rank_period1"The rank of the first
simulation period used to calculate ug_per_L,
when ordered by increasing average concentration.
"rank_period2"The rank of the second
simulation period used to calculate ug_per_L,
when ordered by increasing average concentration.
"method"See argument method above.
"nb_sim_yrs_used"Number of simulation years
used for the calculation, after discarding the warm-up
period.
"nb_yrs_per_period"Number of simulation years
aggregated to calculate the average concentration of
each "period". 1, 2 or 3 in cases of yearly, biennial
or triennial pesticide application frequency.
"nb_yrs_warmup"Number of simulation
years discarded as a warm-up period.
"neg_conc_set_to_0"See negToZero
above.
"info_period"
A data.frame with the following columns:
"period_index"Index of the simulation
period when periods are sorted in chronological
order (i.e. 1 is the first or earliest
period).
"from_year"First year included in the period.
"to_year"Last year included in the period.
"water_target_layer_by_period"
A data.frame with the following columns:
"period_index"See above.
"mm_mic"Accumulated amount of water
passed through the micropores in target layer
over the period, downward (positive) or upward
(negative), in [mm] of water.
"mm_mac"Accumulated amount of water
passed through the macropores in target layer
over the period, downward (positive) or upward
(negative), in [mm] of water.
"mm_tot"Accumulated amount of water
passed through the target layer
over the period, downward (positive) or upward
(negative), in [mm] of water.
"solute_target_layer_by_period"
A data.frame with the following columns:
"period_index"See above.
"mg_per_m2_mic"Accumulated mass of
solute passed through the micropores, per square
meter, in target layer, over the period,
downward (positive) or upward (negative), in
[mg/ m2].
"mg_per_m2_mac"Accumulated mass of
solute passed through the macropores, per square
meter, in target layer, over the period,
downward (positive) or upward (negative), in
[mg/ m2].
"mg_per_m2_tot"Accumulated mass of
solute passed through the target layer, per square
meter, over the period, downward (positive) or
upward (negative), in [mg/ m2].
"ug_per_L"Water-flow-weighted average
solute concentration over the period, in
[micro-grams/L] or [mg/m3]. In practice equal
to the accumulated solute mass divided by the
accumulated water flow, with appropriate unit
conversion.
"water_perc_by_period"
A data.frame with the following columns:
"period_index"See above.
"mm"Accumulated amount of water
passed through the bottom layer of the soil profile
over the period, downward (positive) or upward
(negative), in [mm] of water.
"solute_perc_by_period"
A data.frame with the following columns:
"period_index"See above.
"mg_per_m2"Accumulated mass of
solute passed through the bottom layer of the soil
profile , per square meter, over the period,
downward (positive) or upward (negative), in
[mg/ m2].
"ug_per_L"Water-flow-weighted average
solute concentration over the period, in
[micro-grams/L] or [mg/m3]. In practice equal
to the accumulated solute mass divided by the
accumulated water flow, with appropriate unit
conversion.
"conc_target_layer"
A data.frame with the following columns:
"ug_per_L"Xth percentile of the period-
averaged solute concentrations in the target
layer, where X is equal to conc_percentile
(See above).
"ug_per_L_rnd"Same as above, except that
the concentration is rounded to 2 digits after the
decimal mark, in scientific mode, in an attempt to
obtain the same value as MACRO In FOCUS graphical
interface.
"index_period1"Index of the first simulation
period used to calculate the Xth percentile of
the period-averaged solute concentrations.
Corresponds to the column period_index in
the tables above.
"index_period2"Index of the second simulation
period used to calculate the Xth percentile of
the period-averaged solute concentrations.
Corresponds to the column period_index in
the tables above.
"f_solute_mac"Average fraction of solute
in the macropores corresponding to
ug_per_L, 0 meaning 0% of the solute in
the macropres and 1 meaning 100% of the solute
in the macropores.
"f_solute_mic"Average fraction of solute
in the micropores corresponding to
ug_per_L, 0 meaning 0% of the solute in
the micropres and 1 meaning 100% of the solute
in the micropores.
"conc_perc"
A data.frame with the following columns:
"ug_per_L"Xth percentile of the period-
averaged solute concentrations percolated at the
bottom boundary of the soil profile, where X is
equal to conc_percentile (See above).
"ug_per_L_rnd"Same as above, except that
the concentration is rounded to 2 digits after the
decimal mark, in scientific mode, in an attempt to
obtain the same value as MACRO In FOCUS graphical
interface.
"index_period1"Index of the first simulation
period used to calculate the Xth percentile of
the period-averaged solute concentrations.
Corresponds to the column period_index in
the tables above.
"index_period2"Index of the second simulation
period used to calculate the Xth percentile of
the period-averaged solute concentrations.
Corresponds to the column period_index in
the tables above.
Author(s)
Julien Moeys jules_m78-soiltexture@yahooDOTfr,
contributions from Stefan Reichenberger
SReichenberger@knoellDOTcom.
References
European Commission (2014) "Assessing Potential for
Movement of Active Substances and their Metabolites to
Ground Water in the EU Report of the FOCUS Ground Water
Work Group, EC Document Reference Sanco/13144/2010
version 3, 613 pp. http://focus.jrc.ec.europa.eu/gw/docs/NewDocs/focusGWReportOct2014.pdf
See in particular the last sentence page 475.
Examples
library( "macroutils2" )
# Path to the file to be read
( filenm <- system.file(
"bintest/chat_winCer_GW-D_1kgHa_d298_annual_output.bin",
package = "macroutils2", mustWork = TRUE ) )
res <- macroutilsFocusGWConc( x = filenm )
res
# Clean-up
rm( filenm, res )
julienmoeys/macroutils2 documentation built on Feb. 28, 2024, 2:17 a.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.
| macroutilsFocusGWConc | R Documentation |
INTERNAL/NON-OFFICIAL: Calculate the yearly and Xth percentile groundwater concentration from a MACROInFOCUS output.
Description
INTERNAL & NON-OFFICIAL: Calculate the yearly and Xth percentile
groundwater concentration from a MACROInFOCUS output.
WARNING This function is not part
of the official MACROInFOCUS program. It is provided
for test-purpose, without any guarantee or support from
the authors, CKB, SLU or KEMI. You are strongly recommended to
benchmark the function against a range of (official)
MACROInFOCUS simulation results, before you use the
function. You are also strongly recommended to inspect
the code of these functions before you use them. To
inspect the content of these functions, simply type
body( macroutils2:::macroutilsFocusGWConc.data.frame )
after you have loaded the package macroutils2.
Usage
macroutilsFocusGWConc(
x,
nbYrsWarmUp = 6L,
yearsAvg = NULL,
prob = 0.8,
method = c("focus", "R", "test")[1L],
negToZero = TRUE,
type = 7L,
quiet = FALSE,
massunits = 2L,
...
)
## S3 method for class 'character'
macroutilsFocusGWConc(
x,
nbYrsWarmUp = 6L,
yearsAvg = NULL,
prob = 0.8,
method = c("focus", "R", "test")[1L],
negToZero = TRUE,
type = 7L,
quiet = FALSE,
massunits = 2L,
...
)
## S3 method for class 'list'
macroutilsFocusGWConc(
x,
nbYrsWarmUp = 6L,
yearsAvg = NULL,
prob = 0.8,
method = c("focus", "R", "test")[1L],
negToZero = TRUE,
type = 7L,
quiet = FALSE,
massunits = 2L,
...
)
## S3 method for class 'data.frame'
macroutilsFocusGWConc(
x,
nbYrsWarmUp = 6L,
yearsAvg = NULL,
prob = 0.8,
method = c("focus", "R", "test")[1L],
negToZero = TRUE,
type = 7L,
quiet = FALSE,
massunits = 2L,
output_water = c(target_l = TRUE, lower_b = TRUE),
output_solute = c(target_l = TRUE, lower_b = FALSE),
...
)
Arguments
x |
Either a vector of character strings, a
|
nbYrsWarmUp |
Single integer values: Number of warm-up years that should be removed from the beginning of the model output. A default of 6 years of warn-up are used in FOCUS. |
yearsAvg |
Single integer values: Number of simulation years to
"aggregate" when calculating yearly- or biennial- or
triennial- (etc.) average concentrations.
If |
prob |
Single numeric value, between 0 and 1. Probability
(percentile/100) of the worst case concentration
that shall be calculated. In FOCUS, the yearly results
are ordered by increasing yearly average concentrations
before the percentile is calculated, as the average
concentration of the two years closest to the Xth percentile
(X always being 80, in FOCUS). Here, in practice, the
index of the 1st and 2nd year used for calculating the
average are selected as follow:
|
method |
Single character string. If |
negToZero |
Single logical value. If |
type |
Single integer value. Only used when |
quiet |
Single logical value. Set to |
massunits |
Single integer value. Code for the mass unit of the simulation
result in |
... |
Additional parameters passed to
|
output_water |
Vector of two logical value, labelled |
output_solute |
Vector of two logical value, labelled |
Value
Returns a list with the following items:
"info_general" A
data.framewith the following columns:"conc_percentile"The percentile used to calculate the Predicted Environmental Concentration (columns
ug_per_Lin itemsconc_target_layerandconc_perc, below), in [%]."rank_period1"The rank of the first simulation period used to calculate
ug_per_L, when ordered by increasing average concentration."rank_period2"The rank of the second simulation period used to calculate
ug_per_L, when ordered by increasing average concentration."method"See argument
methodabove."nb_sim_yrs_used"Number of simulation years used for the calculation, after discarding the warm-up period.
"nb_yrs_per_period"Number of simulation years aggregated to calculate the average concentration of each "period". 1, 2 or 3 in cases of yearly, biennial or triennial pesticide application frequency.
"nb_yrs_warmup"Number of simulation years discarded as a warm-up period.
"neg_conc_set_to_0"See
negToZeroabove.
"info_period" A
data.framewith the following columns:"period_index"Index of the simulation period when periods are sorted in chronological order (i.e.
1is the first or earliest period)."from_year"First year included in the period.
"to_year"Last year included in the period.
"water_target_layer_by_period" A
data.framewith the following columns:"period_index"See above.
"mm_mic"Accumulated amount of water passed through the micropores in target layer over the period, downward (positive) or upward (negative), in [mm] of water.
"mm_mac"Accumulated amount of water passed through the macropores in target layer over the period, downward (positive) or upward (negative), in [mm] of water.
"mm_tot"Accumulated amount of water passed through the target layer over the period, downward (positive) or upward (negative), in [mm] of water.
"solute_target_layer_by_period" A
data.framewith the following columns:"period_index"See above.
"mg_per_m2_mic"Accumulated mass of solute passed through the micropores, per square meter, in target layer, over the period, downward (positive) or upward (negative), in [mg/ m2].
"mg_per_m2_mac"Accumulated mass of solute passed through the macropores, per square meter, in target layer, over the period, downward (positive) or upward (negative), in [mg/ m2].
"mg_per_m2_tot"Accumulated mass of solute passed through the target layer, per square meter, over the period, downward (positive) or upward (negative), in [mg/ m2].
"ug_per_L"Water-flow-weighted average solute concentration over the period, in [micro-grams/L] or [mg/m3]. In practice equal to the accumulated solute mass divided by the accumulated water flow, with appropriate unit conversion.
"water_perc_by_period" A
data.framewith the following columns:"period_index"See above.
"mm"Accumulated amount of water passed through the bottom layer of the soil profile over the period, downward (positive) or upward (negative), in [mm] of water.
"solute_perc_by_period" A
data.framewith the following columns:"period_index"See above.
"mg_per_m2"Accumulated mass of solute passed through the bottom layer of the soil profile , per square meter, over the period, downward (positive) or upward (negative), in [mg/ m2].
"ug_per_L"Water-flow-weighted average solute concentration over the period, in [micro-grams/L] or [mg/m3]. In practice equal to the accumulated solute mass divided by the accumulated water flow, with appropriate unit conversion.
"conc_target_layer" A
data.framewith the following columns:"ug_per_L"Xth percentile of the period- averaged solute concentrations in the target layer, where X is equal to
conc_percentile(See above)."ug_per_L_rnd"Same as above, except that the concentration is rounded to 2 digits after the decimal mark, in scientific mode, in an attempt to obtain the same value as MACRO In FOCUS graphical interface.
"index_period1"Index of the first simulation period used to calculate the Xth percentile of the period-averaged solute concentrations. Corresponds to the column
period_indexin the tables above."index_period2"Index of the second simulation period used to calculate the Xth percentile of the period-averaged solute concentrations. Corresponds to the column
period_indexin the tables above."f_solute_mac"Average fraction of solute in the macropores corresponding to
ug_per_L, 0 meaning 0% of the solute in the macropres and 1 meaning 100% of the solute in the macropores."f_solute_mic"Average fraction of solute in the micropores corresponding to
ug_per_L, 0 meaning 0% of the solute in the micropres and 1 meaning 100% of the solute in the micropores.
"conc_perc" A
data.framewith the following columns:"ug_per_L"Xth percentile of the period- averaged solute concentrations percolated at the bottom boundary of the soil profile, where X is equal to
conc_percentile(See above)."ug_per_L_rnd"Same as above, except that the concentration is rounded to 2 digits after the decimal mark, in scientific mode, in an attempt to obtain the same value as MACRO In FOCUS graphical interface.
"index_period1"Index of the first simulation period used to calculate the Xth percentile of the period-averaged solute concentrations. Corresponds to the column
period_indexin the tables above."index_period2"Index of the second simulation period used to calculate the Xth percentile of the period-averaged solute concentrations. Corresponds to the column
period_indexin the tables above.
Author(s)
Julien Moeys jules_m78-soiltexture@yahooDOTfr, contributions from Stefan Reichenberger SReichenberger@knoellDOTcom.
References
European Commission (2014) "Assessing Potential for Movement of Active Substances and their Metabolites to Ground Water in the EU Report of the FOCUS Ground Water Work Group, EC Document Reference Sanco/13144/2010 version 3, 613 pp. http://focus.jrc.ec.europa.eu/gw/docs/NewDocs/focusGWReportOct2014.pdf See in particular the last sentence page 475.
Examples
library( "macroutils2" )
# Path to the file to be read
( filenm <- system.file(
"bintest/chat_winCer_GW-D_1kgHa_d298_annual_output.bin",
package = "macroutils2", mustWork = TRUE ) )
res <- macroutilsFocusGWConc( x = filenm )
res
# Clean-up
rm( filenm, res )
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.