R/wood_valuation.R

In woodValuationDE: Wood Valuation Germany

##--################--##
#### Wood Valuation ####
##--################--##

#' All steps of the monetary valuation of wood volumes over bark
#'
#' The function is a wrapper for the entire procedure of wood valuation provided
#' by \pkg{woodValuationDE}. It estimates the share of salable (for revenues)
#' and skidded volume (for harvest costs), the wood revenues, and the harvest
#' costs. Finally, it derives the net revenues for the user-provided wood volume
#' over bark. The underlying functions were derived based on data from
#' HessenForst, the public forest service of the Federal State of Hesse in
#' Germany. For further details see the \pkg{woodValuationDE}
#' \href{https://github.com/Forest-Economics-Goettingen/woodValuationDE}{README}.
#'
#' @param volume Wood volume \eqn{[m^{3}]}{[m^3]}, referring to volume over bark
#'               of the trees to be harvested, as usually provided by yield
#'               tables and forest simulators (German unit: Vfm m.R.).
#' @param diameter.q Quadratic mean of the diameter at breast height (dbh) of
#'                   the harvested trees \eqn{[cm]}{[cm]}.
#' @param species Tree species, using an available \code{species.code.type}. For
#'                a list with the available species and codes call
#'                \code{\link{get_species_codes}}.
#' @param value.level Stand quality expressed as an integer of \code{1:3}, with
#'                    \code{1} for an extraordinarily high stand quality with 
#'                    high shares of wood suitable for high-valued usages such
#'                    as furniture, \code{2} for a moderate quality, and
#'                    \code{3} for a low quality (e.g., trees with thick
#'                    branches). The \code{value.level}s refer to the applied
#'                    assortment tables of Offer and Staupendahl (2018).
#' @param cost.level  Accessibility of the stand for logging operations
#'                    expressed as an integer of \code{1:3}, with \code{1} for
#'                    standard conditions without limitations, \code{2} for
#'                    moist sites or sites with a slope between 36 \% and 58 \%,
#'                    and \code{3} for slopes > 58 \%. The \code{cost.level}s
#'                    refer to the harvest cost model of v. Bodelschwingh
#'                    (2018).
#' @param logging.method Logging method, with \code{"manually"} for
#'                       motor-manual logging using a chain saw,
#'                       \code{"harvester"} for logging with highly mechanized
#'                       forest harvesters, or \code{"combined"} for a
#'                       combination of the previous methods dependent on the
#'                       mean diameter.
#' @param price.ref.assortment Wood price of the reference assortments allowing
#'                     to consider market fluctuations. Default is
#'                     \code{"baseline"} referring to the prices from 2010 to
#'                     2015 in Hesse, Germany (for details see
#'                     \href{https://github.com/Forest-Economics-Goettingen/woodValuationDE}{README}
#'                     of \pkg{woodValuationDE} or v. Bodelschwingh (2018)).
#'                     Alternatively, users can provide a tibble with the
#'                     same structure. The column species uses the specified
#'                     \code{species.code.type}.
#' @param calamity.type Defines the disturbance or calamity situation to allow
#'                      for the consideration of lower net revenues in the case
#'                      of salvage harvests. The calamity type determines the
#'                      applied consequences of disturbances/calamities,
#'                      implemented as factors for reduced revenues and higher
#'                      harvest costs. By default no calamity is assumed
#'                      \code{"none"}; \code{"calamity.dieter.2001"}
#'                      refers to a general larger calamity applying the
#'                      corrections according to Dieter (2001); five parameter
#'                      sets were implemented according to Moellmann and
#'                      Moehring (2017): \code{fire.small.moellmann.2017} refers
#'                      to damages of only some trees by fire (only conifers)
#'                      while \code{fire.large.moellmann.2017} assumes that at
#'                      least one compartment was affected, the same applies for
#'                      \code{storm.small.moellmann.2017} and
#'                      \code{storm.large.moellmann.2017} referring to damages
#'                      by storm (available for coniferous and deciduous
#'                      species), \code{insects.moellmann.2017} refers to
#'                      damages by insects; \code{"ips.fuchs.2022a"} refers to
#'                      quality losses due to infestations by the European
#'                      spruce bark beetle or \code{"ips.timely.fuchs.2022a"}
#'                      for timely salvage fellings in less advanced attack 
#'                      stages (both according to Fuchs et al. 2022a); and
#'                      \code{"stand.damage.fuchs.2022b"} to disturbances
#'                      affecting only one stand, 
#'                      \code{"regional.disturbances.fuchs.2022b"} to 
#'                      disturbances with effects on the regional wood market
#'                      and \code{"transregional.calamity.fuchs.2022b"} to
#'                      calamities affecting transregional wood markets (the
#'                      last three referring to Fuchs et al. 2022b).
#'                      User-defined types can be implemented via the
#'                      \code{calamity.factors} argument.
#' @param calamity.factors Summands \eqn{[EUR m^{-3}]}{[EUR m^(-3)]}
#'                         and factors to consider the consequences of
#'                         disturbances and calamities on wood revenues and
#'                         harvest costs. \code{"baseline"} provides a tibble
#'                         based on the references listed in
#'                         \code{calamity.type} (for details see
#'                         \href{https://github.com/Forest-Economics-Goettingen/woodValuationDE}{README}
#'                         of \pkg{woodValuationDE}). Alternatively, users can
#'                         provide a tibble with the same structure.
#' @param species.code.type Type of code in which \code{species} is given.
#'                          \code{"en"} for English species names or
#'                          \code{"nds"} for numeric species codes used in Lower
#'                          Saxony, Germany. For a list with the available
#'                          species and codes call
#'                          \code{\link{get_species_codes}}.
#' @param method argument that is currently not used, but offers the possibility
#'               to implement alternative parameters and functions in the
#'               future.
#' @return A tibble with all steps of the wood valuation (harvest quantities,
#'         harvest costs \eqn{[EUR m^{-3}]}{[EUR m^(-3)]}, wood revenues
#'         \eqn{[EUR m^{-3}]}{[EUR m^(-3)]}, and total net revenues
#'         \eqn{[EUR]}{[EUR]}).
#' @references Dieter, Matthias (2001): Land expectation values for spruce and
#'             beech calculated with Monte Carlo modelling techniques. For.
#'             Policy Econ. 2 (2), S. 157-166.
#'             \doi{10.1016/S1389-9341(01)00045-4}.
#' @references Fuchs, Jasper M.; Hittenbeck, Anika; Brandl, Susanne; Schmidt,
#'             Matthias; Paul, Carola (2022a): Adaptation Strategies for
#'             Spruce Forests - Economic Potential of Bark Beetle Management and
#'             Douglas Fir Cultivation in Future Tree Species Portfolios.
#'             Forestry 95 (2) 229-246. \doi{10.1093/forestry/cpab040}
#' @references Fuchs, Jasper M.; v. Bodelschwingh, Hilmar; Lange, Alexander;
#'             Paul, Carola; Husmann, Kai (2022b): Quantifying the
#'             consequences of disturbances on wood revenues with Impulse
#'             Response Functions. For. Policy Econ. 140, art. 102738.
#'             \doi{10.1016/j.forpol.2022.102738}.
#' @references Fuchs, Jasper M.; Husmann, Kai; v. Bodelschwingh, Hilmar; Koster,
#'             Roman; Staupendahl, Kai; Offer, Armin; Moehring, Bernhard, Paul,
#'             Carola (in preparation): woodValuationDE: A consistent framework
#'             for calculating stumpage values in Germany (technical note)
#' @references Moellmann, Torsten B.; Moehring, Bernhard (2017): A practical way
#'             to integrate risk in forest management decisions. Ann. For. Sci.
#'             74 (4), S.75. \doi{10.1007/s13595-017-0670-x}
#' @references Offer, Armin; Staupendahl, Kai (2018): Holzwerbungskosten- und
#'             Bestandessortentafeln (Wood Harvest Cost and Assortment
#'             Tables). Kassel: HessenForst (publisher).
#' @references v. Bodelschwingh, Hilmar (2018): Oekonomische Potentiale von
#'             Waldbestaenden. Konzeption und Abschaetzung im Rahmen einer
#'             Fallstudie in hessischen Staatswaldflaechen (Economic Potentials
#'             of Forest Stands and Their Consideration in Strategic Decisions).
#'             Bad Orb: J.D. Sauerlaender`s Verlag (Schriften zur Forst- und
#'             Umweltoekonomie, 47).
#' @examples
#' wood_valuation(1,
#'                40,
#'                "beech")
#'
#' # species codes Lower Saxony (Germany)
#' wood_valuation(seq(10, 70, 20),
#'                40,
#'                211,
#'                species.code.type = "nds")
#'
#' # vector input
#' wood_valuation(10,
#'                seq(20, 50, 5),
#'                "spruce")
#'
#' wood_valuation(10,
#'                40,
#'                rep(c("beech", "spruce"),
#'                    each = 9),
#'                value.level = rep(rep(1:3, 2),
#'                                  each = 3),
#'                cost.level = rep(1:3, 6))
#'
#' wood_valuation(10,
#'                40,
#'                rep("spruce", 6),
#'                calamity.type = c("none",
#'                                  "ips.fuchs.2022a",
#'                                  "ips.timely.fuchs.2022a",
#'                                  "stand.damage.fuchs.2022b",
#'                                  "regional.disturbance.fuchs.2022b",
#'                                  "transregional.calamity.fuchs.2022b"))
#'
#' # user-defined calamities with respective changes in harvest costs and wood revenues
#' wood_valuation(10,
#'                40,
#'                rep("spruce", 3),
#'                calamity.type = c("none",
#'                                  "my.own.calamity.1",
#'                                  "my.own.calamity.2"),
#'                calamity.factors = dplyr::tibble(
#'                  calamity.type = rep(c("none",
#'                                        "my.own.calamity.1",
#'                                        "my.own.calamity.2"),
#'                                      each = 2),
#'                  species.group = rep(c("softwood",
#'                                        "deciduous"),
#'                                      times = 3),
#'                  revenues.factor = c(1.0, 1.0,
#'                                      0.8, 0.8,
#'                                      0.2, 0.2),
#'                  cost.factor = c(1.0, 1.0,
#'                                  1.5, 1.5,
#'                                  1.0, 1.0),
#'                  cost.additional = c(0, 0,
#'                                      0, 0,
#'                                      5, 5)))
#'
#' # adapted market situation by providing alternative prices for the reference assortments
#' wood_valuation(10,
#'                40,
#'                c("oak", "beech", "spruce"))
#' wood_valuation(10,
#'                40,
#'                c("oak", "beech", "spruce"),
#'                price.ref.assortment = dplyr::tibble(
#'                  species = c("oak", "beech", "spruce"),
#'                  price.ref.assortment = c(300, 80, 50)))
#'
#' @import dplyr
#'
#' @export
wood_valuation <- function(
  volume,
  diameter.q,
  species,
  value.level = 2,
  cost.level = 1,
  logging.method = "combined",
  price.ref.assortment = "baseline",
  calamity.type = "none",
  calamity.factors = "baseline",
  species.code.type = "en",
  method = "fuchs.orig"
) {

  tibble(
    volume = volume,
    diameter.q = diameter.q,
    species = species,
    cost.level = cost.level,
    value.level = value.level,
    logging.method = logging.method,
    calamity.type = calamity.type
  ) %>%

    mutate(
      vol.salable = vol_salable(diameter.q,
                                species,
                                value.level,
                                logging.method,
                                species.code.type),
      vol.skidded = vol_skidded(diameter.q,
                                species,
                                value.level,
                                logging.method,
                                species.code.type),
      wood.revenues = wood_revenues(diameter.q,
                                    species,
                                    value.level,
                                    logging.method,
                                    price.ref.assortment,
                                    calamity.type,
                                    calamity.factors,
                                    species.code.type),
      harvest.costs = harvest_costs(diameter.q,
                                    species,
                                    cost.level,
                                    calamity.type,
                                    calamity.factors,
                                    species.code.type),
      wood.net.revenue.m3 = (.data$vol.salable * .data$wood.revenues) -
        (.data$vol.skidded * .data$harvest.costs),
      wood.net.revenue = .data$volume * .data$wood.net.revenue.m3
    ) %>%

    return()

}