From 41128538b5f070a45d50c64518f234d4369fa582 Mon Sep 17 00:00:00 2001 From: Kevin Kramer Date: Mon, 24 Jun 2024 15:27:36 +0200 Subject: [PATCH] doc fixes --- NAMESPACE | 7 +- README.md | 4 +- _pkgdown.yml | 11 +- inst/REFERENCES.bib | 2 +- man/Autocut.Rd | 122 +++++++++++ man/ModvegeSite.Rd | 124 +---------- man/PetersenAutocut.Rd | 311 +++++++++++++++++++++++++++ man/PhenologicalAutocut.Rd | 107 +++++++++ man/autocut.Rd | 33 --- man/get_annual_gross_yield.Rd | 33 --- man/get_end_of_cutting_season.Rd | 34 --- man/get_expected_n_cuts.Rd | 31 --- man/get_relative_cut_contribution.Rd | 34 --- 13 files changed, 558 insertions(+), 295 deletions(-) create mode 100644 man/Autocut.Rd create mode 100644 man/PetersenAutocut.Rd create mode 100644 man/PhenologicalAutocut.Rd delete mode 100644 man/autocut.Rd delete mode 100644 man/get_annual_gross_yield.Rd delete mode 100644 man/get_end_of_cutting_season.Rd delete mode 100644 man/get_expected_n_cuts.Rd delete mode 100644 man/get_relative_cut_contribution.Rd diff --git a/NAMESPACE b/NAMESPACE index e3f5cb3..850a9f5 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -3,6 +3,7 @@ S3method("*",FunctionalGroup) S3method("+",FunctionalGroup) S3method(plot,ModvegeSite) +export(Autocut) export(FG_A) export(FG_B) export(FG_C) @@ -12,6 +13,8 @@ export(ManagementData) export(ModvegeEnvironment) export(ModvegeParameters) export(ModvegeSite) +export(PetersenAutocut) +export(PhenologicalAutocut) export(PscanPlotter) export(SEA) export(WeatherData) @@ -30,11 +33,7 @@ export(fCO2_transpiration_mod) export(fPAR) export(fT) export(fW) -export(get_annual_gross_yield) export(get_bias) -export(get_end_of_cutting_season) -export(get_expected_n_cuts) -export(get_relative_cut_contribution) export(growR_package_options) export(growR_run_loop) export(load_data_for_sites) diff --git a/README.md b/README.md index 5589e01..9c1bae4 100644 --- a/README.md +++ b/README.md @@ -91,7 +91,7 @@ install.packages("growR") Installing from source might make sense if... -- you intend on making changes to the model[^3], +- you intend on making changes to the model[^11], - you want to contribute to package development and maintenance, - you want to get access to the cutting edge version, which may have changes not yet available on the CRAN version but is also likely less stable, @@ -275,6 +275,6 @@ Assessing Livestock Production under Climate Change.” Agriculture, Ecosystems -[^3]: If you make changes that generally improve `growR`, it would be great if you could +[^11]: If you make changes that generally improve `growR`, it would be great if you could share them to make them available to all future users. See [Contributing](#contributing). diff --git a/_pkgdown.yml b/_pkgdown.yml index 61e62dc..1e893c5 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -57,6 +57,12 @@ reference: - contents: - PscanPlotter - Combinator +- title: Autocut + desc: Cut decision algorithms +- contents: + - Autocut + - PhenologicalAutocut + - PetersenAutocut - title: Debug Tools desc: Utilities that may be of help if things go wrong. - contents: @@ -69,7 +75,6 @@ reference: - aCO2_inverse - append_to_table - atmospheric_CO2 - - autocut - build_functional_group - check_for_package - compare.R @@ -82,10 +87,6 @@ reference: - fPAR - fT - fW - - get_annual_gross_yield - - get_end_of_cutting_season - - get_expected_n_cuts - - get_relative_cut_contribution - get_site_name - growR_package_options - management_parameters diff --git a/inst/REFERENCES.bib b/inst/REFERENCES.bib index cf764b4..dd82bf4 100644 --- a/inst/REFERENCES.bib +++ b/inst/REFERENCES.bib @@ -87,7 +87,7 @@ @article{huguenin2017GrundlagenDuengung url = {https://www.agrarforschungschweiz.ch/2017/06/9-duengung-von-grasland-grud-2017/}, year = {2017}, journal = {Agrarforschung Schweiz}, - author = {Huguenin-Elie, Ilivier, Eric Mosimann, Patrick Schlegel, Andreas Lüscher, Willy Kessler, and Bernard Jeangros} + author = {Huguenin-Elie, Ilivier and Mosimann, Eric and Schlegel, Patrick and Lüscher, Andreas and Kessler, Willy and Jeangros, Bernard} } @article{calanca2016TestingAbilitySimple, diff --git a/man/Autocut.Rd b/man/Autocut.Rd new file mode 100644 index 0000000..c8b4651 --- /dev/null +++ b/man/Autocut.Rd @@ -0,0 +1,122 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/autocut.R +\name{Autocut} +\alias{Autocut} +\title{Autocut} +\description{ +An algorithm to determine grass cut dates if none are provided. +This is an abstract class and not intended for direct use. Instead, use +its subclasses that implement a \code{determine_cut()} method. + +The expected number of cuts is estimated from management intensity and +site altitude based on data for Swiss grasslands by Huguenin et al. +} +\references{ +\insertRef{huguenin2017GrundlagenDuengung}{growR} +} +\seealso{ +\link{management_parameters} +} +\section{Public fields}{ +\if{html}{\out{
}} +\describe{ +\item{\code{MVS}}{The \link{ModvegeSite} object for which to take the cut decision.} + +\item{\code{n_cuts}}{Number of cuts expected for this altitude and management +intensity.} +} +\if{html}{\out{
}} +} +\section{Methods}{ +\subsection{Public methods}{ +\itemize{ +\item \href{#method-Autocut-new}{\code{Autocut$new()}} +\item \href{#method-Autocut-get_expected_n_cuts}{\code{Autocut$get_expected_n_cuts()}} +\item \href{#method-Autocut-determine_cut}{\code{Autocut$determine_cut()}} +\item \href{#method-Autocut-clone}{\code{Autocut$clone()}} +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-Autocut-new}{}}} +\subsection{Method \code{new()}}{ +Constructor +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Autocut$new(MVS)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{MVS}}{The \link{ModvegeSite} object for which cuts shall be +determined. + +Get number of expected cuts + +Return the number of expected cuts for a site at a given \emph{elevation} and +management \emph{intensity}. + +This uses data.frame \code{management_parameters} as a lookup table and +interpolates linearly in between the specified values.} +} +\if{html}{\out{
}} +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-Autocut-get_expected_n_cuts}{}}} +\subsection{Method \code{get_expected_n_cuts()}}{ +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Autocut$get_expected_n_cuts(elevation, intensity = "high")}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{elevation}}{The elevation of the considered site in meters above sea +level.} + +\item{\code{intensity}}{One of ("high", "middle", "low", "extensive"). Management +intensity for considered site.} +} +\if{html}{\out{
}} +} +\subsection{Returns}{ +Number of expected cuts per season. +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-Autocut-determine_cut}{}}} +\subsection{Method \code{determine_cut()}}{ +Empty method stub intended for overriding by inheriting subclasses. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Autocut$determine_cut(DOY)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{DOY}}{Integer day-of-the-year.} +} +\if{html}{\out{
}} +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-Autocut-clone}{}}} +\subsection{Method \code{clone()}}{ +The objects of this class are cloneable with this method. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Autocut$clone(deep = FALSE)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{deep}}{Whether to make a deep clone.} +} +\if{html}{\out{
}} +} +} +} diff --git a/man/ModvegeSite.Rd b/man/ModvegeSite.Rd index 5983f4d..ab866e0 100644 --- a/man/ModvegeSite.Rd +++ b/man/ModvegeSite.Rd @@ -87,12 +87,10 @@ Part of ENV due to water limitation. Dimensionless. \insertRef{jouven2006ModelPredictingDynamics}{growR} } \seealso{ -\link[=autocut]{autocut} +\link[=Autocut]{Autocut} \code{\link[=start_of_growing_season_mtd]{start_of_growing_season_mtd()}}, \code{\link[=start_of_growing_season]{start_of_growing_season()}} -\code{get_target_biomass()} - \code{ModvegeParameters$set_parameters()} } \section{Public fields}{ @@ -134,37 +132,7 @@ provided or not.} occurred during the growth period, in which case reproductive growth is stopped.} -\item{\code{last_DOY_for_initial_cut}}{\link{autocut} Start cutting after this DOY, -even if yield target is not reached.} - -\item{\code{max_cut_period}}{\link{autocut} Maximum period to wait between -subsequent cuts.} - -\item{\code{dry_precipitation_limit}}{\link{autocut} Maximum amount of allowed -precipitation (mm) to consider a day.} - -\item{\code{dry_days_before_cut}}{\link{autocut} Number of days that shold be dry -before a cut is made.} - -\item{\code{dry_days_after_cut}}{\link{autocut} Number of days that shold be dry -after a cut is made.} - -\item{\code{max_cut_delay}}{\link{autocut} Number of days a farmer is willing to -wait for dry conditions before a cut is made anyways.} - -\item{\code{cut_delays}}{\link{autocut} Vector to keep track of cut delay times. -wait for dry conditions before a cut is made anyways.} - -\item{\code{dry_window}}{\link{autocut} Logical that indicates if DOY at index is -considered dry enough to cut.} - -\item{\code{target_biomass}}{\link{autocut} Biomass amount that should to be reached -by given DOY for a cut to be made.} - -\item{\code{end_of_cutting_season}}{\link{autocut} Determined DOY after which no -more cuts are made.} - -\item{\code{BM_after_cut}}{\link{autocut} Amount of biomass that remains after a cut +\item{\code{BM_after_cut}}{Amount of biomass that remains after a cut #' (determined through cut_height and biomass densities BDGV, BDDV, BDGR, BDDR).} @@ -173,7 +141,10 @@ BDDR).} \item{\code{management}}{A list containing management data as returned by \link{ModvegeEnvironment}'s \code{get_environment_for_year()} method. If its -\code{is_empty} field is \code{TRUE}, the \link{autocut} routine will be employed.} +\code{is_empty} field is \code{TRUE}, the \link{Autocut} routine will be employed.} + +\item{\code{Autocut}}{A subclass of \link{Autocut}. The algorithm used to determine +cut events.} } \if{html}{\out{}} } @@ -185,8 +156,6 @@ BDDR).} \item \href{#method-ModvegeSite-get_management}{\code{ModvegeSite$get_management()}} \item \href{#method-ModvegeSite-set_SGS_method}{\code{ModvegeSite$set_SGS_method()}} \item \href{#method-ModvegeSite-determine_cut_from_input}{\code{ModvegeSite$determine_cut_from_input()}} -\item \href{#method-ModvegeSite-determine_cut_automatically}{\code{ModvegeSite$determine_cut_automatically()}} -\item \href{#method-ModvegeSite-get_target_biomass}{\code{ModvegeSite$get_target_biomass()}} \item \href{#method-ModvegeSite-run}{\code{ModvegeSite$run()}} \item \href{#method-ModvegeSite-write_output}{\code{ModvegeSite$write_output()}} \item \href{#method-ModvegeSite-set_parameters}{\code{ModvegeSite$set_parameters()}} @@ -297,87 +266,6 @@ Boolean \code{TRUE} if a cut happens on day \emph{DOY}. } } \if{html}{\out{
}} -\if{html}{\out{}} -\if{latex}{\out{\hypertarget{method-ModvegeSite-determine_cut_automatically}{}}} -\subsection{Method \code{determine_cut_automatically()}}{ -Decide based on simple criteria whether day of year \emph{DOY} would be a -good day to cut. - -This follows an implementation described in -Petersen, Krischan, David Kraus, Pierluigi Calanca, Mikhail A. -Semenov, Klaus Butterbach-Bahl, and Ralf Kiese. “Dynamic Simulation -of Management Events for Assessing Impacts of Climate Change on -Pre-Alpine Grassland Productivity.” European Journal of Agronomy -128 (August 1, 2021): 126306. -https://doi.org/10.1016/j.eja.2021.126306. - -The decision to cut is made based on two criteria. -First, it is checked whether a \emph{target biomass} is reached on given -DOY. The defined target depends on the DOY and is given through -:func:\code{get_target_biomass}. If said biomass is present, return \code{TRUE}. - -Otherwise, it is checked whether a given amount of time has passed -since the last cut. Depending on whether this is the first cut of -the season or not, the relevant parameters are -:int:\code{last_DOY_for_initial_cut} and :int:\code{max_cut_period}. -If that amount of time has passed, return \code{TRUE}, otherwise return -\code{FALSE}. -\subsection{Usage}{ -\if{html}{\out{
}}\preformatted{ModvegeSite$determine_cut_automatically(DOY)}\if{html}{\out{
}} -} - -\subsection{Arguments}{ -\if{html}{\out{
}} -\describe{ -\item{\code{DOY}}{Integer day of the year for which to make a cut decision.} -} -\if{html}{\out{
}} -} -\subsection{Returns}{ -Boolean \code{TRUE} if a cut happens on day \emph{DOY}. -} -} -\if{html}{\out{
}} -\if{html}{\out{}} -\if{latex}{\out{\hypertarget{method-ModvegeSite-get_target_biomass}{}}} -\subsection{Method \code{get_target_biomass()}}{ -Get target value of biomass on given \emph{DOY}, which determines whether -a cut is to occur. - -The regression for the target biomass is based on Fig. S2 in the -supplementary material of -Petersen, Krischan, David Kraus, Pierluigi Calanca, Mikhail A. -Semenov, Klaus Butterbach-Bahl, and Ralf Kiese. “Dynamic Simulation -of Management Events for Assessing Impacts of Climate Change on -Pre-Alpine Grassland Productivity.” European Journal of Agronomy -128 (August 1, 2021): 126306. -https://doi.org/10.1016/j.eja.2021.126306. - -A refinement to expected yield as function of altitude has been -implemented according to Table 1a in -Huguenen-Elie et al. "Düngung von Grasland", Agrarforschung Schweiz, -8, (6), 2017, -https://www.agrarforschungschweiz.ch/2017/06/9-duengung-von-grasland-grud-2017/ -\subsection{Usage}{ -\if{html}{\out{
}}\preformatted{ModvegeSite$get_target_biomass(DOY, intensity = "high")}\if{html}{\out{
}} -} - -\subsection{Arguments}{ -\if{html}{\out{
}} -\describe{ -\item{\code{DOY}}{Integer day of the year to consider.} - -\item{\code{intensity}}{One of ("high", "middle", "low") specifying -management intensity.} -} -\if{html}{\out{
}} -} -\subsection{Returns}{ -target Biomass (kg / ha) that should be reached on day \emph{DOY} -for this management \emph{intensity}. -} -} -\if{html}{\out{
}} \if{html}{\out{}} \if{latex}{\out{\hypertarget{method-ModvegeSite-run}{}}} \subsection{Method \code{run()}}{ diff --git a/man/PetersenAutocut.Rd b/man/PetersenAutocut.Rd new file mode 100644 index 0000000..e6f58c5 --- /dev/null +++ b/man/PetersenAutocut.Rd @@ -0,0 +1,311 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/autocut.R +\name{PetersenAutocut} +\alias{PetersenAutocut} +\title{Petersen autocut algorithm} +\description{ +Simulation routine to realistically predict grass cutting events. +This follows an implementation described in Petersen et al. (2021). +} +\details{ +The decision to cut is made based on two criteria. +First, it is checked whether a \emph{target biomass} is reached on given +DOY. The defined target depends on the DOY and is given through +:func:\code{get_target_biomass}. If said biomass is present, return \code{TRUE}. + +Otherwise, it is checked whether a given amount of time has passed +since the last cut. Depending on whether this is the first cut of +the season or not, the relevant parameters are +:int:\code{last_DOY_for_initial_cut} and :int:\code{max_cut_period}. +If that amount of time has passed, return \code{TRUE}, otherwise return +\code{FALSE}. + +The target biomass for a given day is determined following the principles +described in Petersen et al. + +The exact regression for the target biomass is based on Fig. S2 in the +supplementary material of Petersen et al. + +A refinement to expected yield as function of altitude has been +implemented according to Table 1a in Huguenin et al. (2017). +} +\references{ +\insertRef{huguenin2017GrundlagenDuengung}{growR} +\insertRef{petersen2021DynamicSimulationManagement}{growR} + +\insertRef{huguenin2017GrundlagenDuengung}{growR} + +\insertRef{petersen2021DynamicSimulationManagement}{growR} +} +\seealso{ +\link{PhenologicalAutocut} + +\code{get_relative_cut_contribution()} + +\code{get_target_biomass()} +} +\section{Super class}{ +\code{growR::Autocut} -> \code{PetersenAutocut} +} +\section{Public fields}{ +\if{html}{\out{
}} +\describe{ +\item{\code{last_DOY_for_initial_cut}}{Start cutting after this DOY, +even if yield target is not reached.} + +\item{\code{max_cut_period}}{Maximum period to wait between +subsequent cuts.} + +\item{\code{dry_precipitation_limit}}{Maximum amount of allowed +precipitation (mm) to consider a day.} + +\item{\code{dry_days_before_cut}}{Number of days that shold be dry +before a cut is made.} + +\item{\code{dry_days_after_cut}}{Number of days that shold be dry +after a cut is made.} + +\item{\code{max_cut_delay}}{Number of days a farmer is willing to +wait for dry conditions before a cut is made anyways.} + +\item{\code{cut_delays}}{Vector to keep track of cut delay times.} + +\item{\code{dry_window}}{Logical that indicates if DOY at index is +considered dry enough to cut.} + +\item{\code{target_biomass}}{Biomass amount that should to be reached +by given DOY for a cut to be made.} + +\item{\code{end_of_cutting_season}}{Determined DOY after which no +more cuts are made.} +} +\if{html}{\out{
}} +} +\section{Methods}{ +\subsection{Public methods}{ +\itemize{ +\item \href{#method-PetersenAutocut-new}{\code{PetersenAutocut$new()}} +\item \href{#method-PetersenAutocut-get_annual_gross_yield}{\code{PetersenAutocut$get_annual_gross_yield()}} +\item \href{#method-PetersenAutocut-get_target_biomass}{\code{PetersenAutocut$get_target_biomass()}} +\item \href{#method-PetersenAutocut-get_relative_cut_contribution}{\code{PetersenAutocut$get_relative_cut_contribution()}} +\item \href{#method-PetersenAutocut-get_end_of_cutting_season}{\code{PetersenAutocut$get_end_of_cutting_season()}} +\item \href{#method-PetersenAutocut-determine_cut}{\code{PetersenAutocut$determine_cut()}} +\item \href{#method-PetersenAutocut-clone}{\code{PetersenAutocut$clone()}} +} +} +\if{html}{\out{ +
Inherited methods + +
+}} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-PetersenAutocut-new}{}}} +\subsection{Method \code{new()}}{ +Constructor +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{PetersenAutocut$new(MVS)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{MVS}}{The \link{ModvegeSite} object for which cuts shall be +determined.} +} +\if{html}{\out{
}} +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-PetersenAutocut-get_annual_gross_yield}{}}} +\subsection{Method \code{get_annual_gross_yield()}}{ +Lookup table returning expected annual gross yields as function of +elevation and management intensity. + +Based on data from Table 1a in +Lookup Table of expected yield as functions of height and management +intensity after Olivier Huguenin et al. (2017). +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{PetersenAutocut$get_annual_gross_yield(elevation, intensity = "high")}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{elevation}}{The elevation of the considered site in meters above sea +level.} + +\item{\code{intensity}}{One of ("high", "middle", "low", "extensive"). Management +intensity for considered site.} +} +\if{html}{\out{
}} +} +\subsection{Returns}{ +Annual gross yield in t / ha (metric tons per hectare). Note that +1 t/ha = 0.1 kg/m^2. +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-PetersenAutocut-get_target_biomass}{}}} +\subsection{Method \code{get_target_biomass()}}{ +Get target value of biomass on given \emph{DOY}, which determines whether +a cut is to occur. + +The regression for the target biomass is based on Fig. S2 in the +supplementary material of +Petersen, Krischan, David Kraus, Pierluigi Calanca, Mikhail A. +Semenov, Klaus Butterbach-Bahl, and Ralf Kiese. “Dynamic Simulation +of Management Events for Assessing Impacts of Climate Change on +Pre-Alpine Grassland Productivity.” European Journal of Agronomy +128 (August 1, 2021): 126306. +https://doi.org/10.1016/j.eja.2021.126306. + +A refinement to expected yield as function of altitude has been +implemented according to Table 1a in +Huguenen-Elie et al. "Düngung von Grasland", Agrarforschung Schweiz, +8, (6), 2017, +https://www.agrarforschungschweiz.ch/2017/06/9-duengung-von-grasland-grud-2017/ +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{PetersenAutocut$get_target_biomass(DOY, intensity = "high")}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{DOY}}{Integer day of the year to consider.} + +\item{\code{intensity}}{One of ("high", "middle", "low") specifying +management intensity.} +} +\if{html}{\out{
}} +} +\subsection{Returns}{ +target Biomass (kg / ha) that should be reached on day \emph{DOY} +for this management \emph{intensity}. +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-PetersenAutocut-get_relative_cut_contribution}{}}} +\subsection{Method \code{get_relative_cut_contribution()}}{ +Relative cut contribution + +Get the fraction of the total annual harvested biomass that a cut at given +\emph{DOY} is expected to contribute. + +The regression for the target biomass is based on Fig. S2 in the +supplementary material of Petersen et al. (2021). +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{PetersenAutocut$get_relative_cut_contribution(DOY)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{DOY}}{Integer representing the day of the year on which a cut occurs.} +} +\if{html}{\out{
}} +} +\subsection{Returns}{ +The fraction (between 0 and 1) of biomass harvested at the cut at +given \emph{DOY} divided by the total annual biomass. +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-PetersenAutocut-get_end_of_cutting_season}{}}} +\subsection{Method \code{get_end_of_cutting_season()}}{ +Last day of cutting season + +Estimate the last day on which it still makes sense to cut. This is done +by checking at which point the expected target biomass (see +\code{self$get_relative_cut_contribution()}) goes below the minimally harvestable +standing biomass. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{PetersenAutocut$get_end_of_cutting_season( + min_biomass, + elevation, + intensity = "high" +)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{min_biomass}}{float A standing biomass below this value cannot even +be harvested,} + +\item{\code{elevation}}{float Altitude in m.a.s.l.} + +\item{\code{intensity}}{string Management intensity. One of "high", "middle", "low"} +} +\if{html}{\out{
}} +} +\subsection{Returns}{ +float Last (fractional) day of the year on which a cut still makes +sense. +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-PetersenAutocut-determine_cut}{}}} +\subsection{Method \code{determine_cut()}}{ +Decide based on simple criteria whether day of year \emph{DOY} would be a +good day to cut. + +This follows an implementation described in +Petersen, Krischan, David Kraus, Pierluigi Calanca, Mikhail A. +Semenov, Klaus Butterbach-Bahl, and Ralf Kiese. “Dynamic Simulation +of Management Events for Assessing Impacts of Climate Change on +Pre-Alpine Grassland Productivity.” European Journal of Agronomy +128 (August 1, 2021): 126306. +https://doi.org/10.1016/j.eja.2021.126306. + +The decision to cut is made based on two criteria. +First, it is checked whether a \emph{target biomass} is reached on given +DOY. The defined target depends on the DOY and is given through +:func:\code{get_target_biomass}. If said biomass is present, return \code{TRUE}. + +Otherwise, it is checked whether a given amount of time has passed +since the last cut. Depending on whether this is the first cut of +the season or not, the relevant parameters are +:int:\code{last_DOY_for_initial_cut} and :int:\code{max_cut_period}. +If that amount of time has passed, return \code{TRUE}, otherwise return +\code{FALSE}. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{PetersenAutocut$determine_cut(DOY)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{DOY}}{Integer day of the year for which to make a cut decision.} +} +\if{html}{\out{
}} +} +\subsection{Returns}{ +Boolean \code{TRUE} if a cut happens on day \emph{DOY}. +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-PetersenAutocut-clone}{}}} +\subsection{Method \code{clone()}}{ +The objects of this class are cloneable with this method. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{PetersenAutocut$clone(deep = FALSE)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{deep}}{Whether to make a deep clone.} +} +\if{html}{\out{
}} +} +} +} diff --git a/man/PhenologicalAutocut.Rd b/man/PhenologicalAutocut.Rd new file mode 100644 index 0000000..a752535 --- /dev/null +++ b/man/PhenologicalAutocut.Rd @@ -0,0 +1,107 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/autocut.R +\name{PhenologicalAutocut} +\alias{PhenologicalAutocut} +\title{Autocut based on phenology} +\description{ +An algorithm to determine grass cut dates if none are provided. +This uses empirical data for Switzerland to determine the first and last +cut dates of the season from meteorological data. +The number of cuts is inferred from Huguenen et al. and these cut events +are distributed equally between first and last cut dates. +} +\references{ +\insertRef{huguenin2017GrundlagenDuengung}{growR} +} +\seealso{ +\link{management_parameters}, \link{PetersenAutocut} + +\link{Autocut} +} +\section{Super class}{ +\code{growR::Autocut} -> \code{PhenologicalAutocut} +} +\section{Public fields}{ +\if{html}{\out{
}} +\describe{ +\item{\code{cut_DOYs}}{vector containing the integer day-of-year's on which cuts +occur.} +} +\if{html}{\out{
}} +} +\section{Methods}{ +\subsection{Public methods}{ +\itemize{ +\item \href{#method-PhenologicalAutocut-new}{\code{PhenologicalAutocut$new()}} +\item \href{#method-PhenologicalAutocut-determine_cut}{\code{PhenologicalAutocut$determine_cut()}} +\item \href{#method-PhenologicalAutocut-clone}{\code{PhenologicalAutocut$clone()}} +} +} +\if{html}{\out{ +
Inherited methods + +
+}} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-PhenologicalAutocut-new}{}}} +\subsection{Method \code{new()}}{ +Constructor + +Valid cut dates are calculated upon initialization. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{PhenologicalAutocut$new(MVS)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{MVS}}{The \link{ModvegeSite} object for which cuts shall be +determined.} +} +\if{html}{\out{
}} +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-PhenologicalAutocut-determine_cut}{}}} +\subsection{Method \code{determine_cut()}}{ +Does a cut occur on \emph{DOY}? + +Check if \emph{DOY} is in \code{self$cut_DOYs}. If so, return \code{TRUE}. Return +\code{FALSE} otherwise. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{PhenologicalAutocut$determine_cut(DOY)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{DOY}}{Integer day of the year (1-366).} +} +\if{html}{\out{
}} +} +\subsection{Returns}{ +Boolean +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-PhenologicalAutocut-clone}{}}} +\subsection{Method \code{clone()}}{ +The objects of this class are cloneable with this method. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{PhenologicalAutocut$clone(deep = FALSE)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{deep}}{Whether to make a deep clone.} +} +\if{html}{\out{
}} +} +} +} diff --git a/man/autocut.Rd b/man/autocut.Rd deleted file mode 100644 index 23b07c0..0000000 --- a/man/autocut.Rd +++ /dev/null @@ -1,33 +0,0 @@ -\name{autocut} -\alias{autocut} -\title{autocut} -\description{ -Simulation routine to realistically predict grass cutting events. -This follows an implementation described in Petersen et al. (2021). - -The decision to cut is made based on two criteria. -First, it is checked whether a *target biomass* is reached on given -DOY. The defined target depends on the DOY and is given through -:func:`get_target_biomass`. If said biomass is present, return `TRUE`. - -Otherwise, it is checked whether a given amount of time has passed -since the last cut. Depending on whether this is the first cut of -the season or not, the relevant parameters are -:int:`last_DOY_for_initial_cut` and :int:`max_cut_period`. -If that amount of time has passed, return `TRUE`, otherwise return -`FALSE`. - -The target biomass for a given day is determined following the principles -described in Petersen et al. - -The exact regression for the target biomass is based on Fig. S2 in the -supplementary material of Petersen et al. - -A refinement to expected yield as function of altitude has been -implemented according to Table 1a in Huguenin et al. (2017). -} -\references{ - \insertRef{petersen2021DynamicSimulationManagement}{growR} - - \insertRef{huguenin2017GrundlagenDuengung}{growR} -} diff --git a/man/get_annual_gross_yield.Rd b/man/get_annual_gross_yield.Rd deleted file mode 100644 index 608b071..0000000 --- a/man/get_annual_gross_yield.Rd +++ /dev/null @@ -1,33 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/support_functions.R -\name{get_annual_gross_yield} -\alias{get_annual_gross_yield} -\title{Lookup table returning expected annual gross yields as function of -elevation and management intensity.} -\usage{ -get_annual_gross_yield(elevation, intensity = "high") -} -\arguments{ -\item{elevation}{The elevation of the considered site in meters above sea -level.} - -\item{intensity}{One of ("high", "middle", "low", "extensive"). Management -intensity for considered site.} -} -\value{ -Annual gross yield in t / ha (metric tons per hectare). Note that -1 t/ha = 0.1 kg/m^2. -} -\description{ -Based on data from Table 1a in -Lookup Table of expected yield as functions of height and management -intensity after Olivier Huguenin et al. (2017). -} -\examples{ -get_annual_gross_yield(1200) -get_annual_gross_yield(1200, intensity = "low") - -} -\references{ -\insertRef{huguenin2017GrundlagenDuengung}{growR} -} diff --git a/man/get_end_of_cutting_season.Rd b/man/get_end_of_cutting_season.Rd deleted file mode 100644 index fe3de39..0000000 --- a/man/get_end_of_cutting_season.Rd +++ /dev/null @@ -1,34 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/support_functions.R -\name{get_end_of_cutting_season} -\alias{get_end_of_cutting_season} -\title{Last day of cutting season} -\usage{ -get_end_of_cutting_season(min_biomass, elevation, intensity = "high") -} -\arguments{ -\item{min_biomass}{float A standing biomass below this value cannot even -be harvested,} - -\item{elevation}{float Altitude in m.a.s.l.} - -\item{intensity}{string Management intensity. One of "high", "middle", "low"} -} -\value{ -float Last (fractional) day of the year on which a cut still makes -sense. -} -\description{ -Estimate the last day on which it still makes sense to cut. This is done -by checking at which point the expected target biomass (see -\code{\link[=get_relative_cut_contribution]{get_relative_cut_contribution()}}) goes below the minimally harvestable -standing biomass. -} -\examples{ -get_end_of_cutting_season(50, 1200) -get_end_of_cutting_season(50, 1200, intensity = "low") - -} -\seealso{ -\code{\link[=get_relative_cut_contribution]{get_relative_cut_contribution()}} -} diff --git a/man/get_expected_n_cuts.Rd b/man/get_expected_n_cuts.Rd deleted file mode 100644 index 238e155..0000000 --- a/man/get_expected_n_cuts.Rd +++ /dev/null @@ -1,31 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/support_functions.R -\name{get_expected_n_cuts} -\alias{get_expected_n_cuts} -\title{Get number of expected cuts} -\usage{ -get_expected_n_cuts(elevation, intensity = "high") -} -\arguments{ -\item{elevation}{The elevation of the considered site in meters above sea -level.} - -\item{intensity}{One of ("high", "middle", "low", "extensive"). Management -intensity for considered site.} -} -\value{ -Number of expected cuts per season. -} -\description{ -Return the number of expected cuts for a site at a given \emph{elevation} and -management \emph{intensity}. -} -\details{ -This uses data.frame \code{management_parameters} as a lookup table and -interpolates linearly in between the specified values. -} -\examples{ -get_expected_n_cuts(1200) -get_expected_n_cuts(1200, intensity = "low") - -} diff --git a/man/get_relative_cut_contribution.Rd b/man/get_relative_cut_contribution.Rd deleted file mode 100644 index 75e3d3a..0000000 --- a/man/get_relative_cut_contribution.Rd +++ /dev/null @@ -1,34 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/support_functions.R -\name{get_relative_cut_contribution} -\alias{get_relative_cut_contribution} -\title{Relative cut contribution} -\usage{ -get_relative_cut_contribution(DOY) -} -\arguments{ -\item{DOY}{Integer representing the day of the year on which a cut occurs.} -} -\value{ -The fraction (between 0 and 1) of biomass harvested at the cut at -given \emph{DOY} divided by the total annual biomass. -} -\description{ -Get the fraction of the total annual harvested biomass that a cut at given -\emph{DOY} is expected to contribute. -} -\details{ -The regression for the target biomass is based on Fig. S2 in the -supplementary material of Petersen et al. (2021). -} -\examples{ -get_relative_cut_contribution(1) -get_relative_cut_contribution(150) -get_relative_cut_contribution(365) -# DOYs larger than 365 are insensible -get_relative_cut_contribution(600) - -} -\references{ -\insertRef{petersen2021DynamicSimulationManagement}{growR} -}