---
title: "dendrometry: Forest Estimations and Dendrometric Computations"
subtitle: "Guide and examples to use main functions of the packages."
author: "Narcisse Yehouenou"
date: "`r Sys.Date()`"
output:  
  html_document:
    theme: journal
    toc: yes
    toc_depth: 5
    toc_float: yes
    number_sections: true
vignette: >
  %\VignetteIndexEntry{HTML browser interface for user guide.}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  markdown: 
    wrap: 72
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = FALSE,
  comment = "#>"
)
```


# The `dendrometry` r package 
## Description
The r package `dendrometry` is an implementation in R language of forests 
estimations methods such as dendrometric parameters of trees and structural 
parameters of tree populations. The objective is to provide an user-friendly R 
package for researchers, ecologists, foresters, statisticians, loggers and 
others persons who deal with forest inventory data. Useful conversion of angle 
value from degree to radian, conversion from angle to slope (in percentage) and 
their reciprocals as well as principal angle determination are also included. 
Position and dispersion parameters usually found in forest studies are 
implemented. The package contains Fibonacci series, its extensions and the 
Golden Number computation. 

## Package citation
Please cite this package in publication or anywhere it comes to be
useful for you. Using `citation` R function is a simple way to get this
package references on R interface. The function also provides a BibTeX
entry for La-TeX users.

```{r Citation}
citation("dendrometry")
```

# Forest estimations: Structural parameters
Before use the package, load it first.

```{r package}
library(dendrometry)
```

## `Tree` data

Let consider the package built-in `Tree` data.

```{r data, collapse=TRUE}
data("Tree")
head(Tree)
```

To see `Tree`data description, use

```{r data description, eval=FALSE}
help("Tree")
```

## Diameter at Breast Height (DBH)

Use `dbh` function to estimate trees diameters (DBH).Type `?dbh` for help.

```{r dbh}
Tree$DBH <- dbh(Tree$circum)
head(Tree)
```

## Height estimation 
Use `height` function to estimate tree height.Type `?height` for help.

```{r Height estimation}
Tree$upHeight <- height(
  distance = Tree$dist, top = Tree$up, bottom = Tree$down,
  type = "angle", angleUnit = "deg"
)
Tree$futHeight <- height(
  distance = Tree$dist, top = Tree$fut, bottom = Tree$down,
  type = "angle", angleUnit = "deg"
)
head(Tree)
```

### Let round data

```{r round, eval=TRUE}
Tree$DBH <- round(Tree$DBH, 2)
Tree$upHeight <- round(Tree$upHeight, 2)
Tree$futHeight <- round(Tree$futHeight, 2)
Tree
```

## Compute slope

Ones could need converting angle values to slope. The `angle2slope` function 
does it easily. The reciprocal of this function is `slope2angle`.

```{r slope}
Tree$up.slope <- angle2slope(Tree$up)
Tree$up.slope <- round(Tree$up.slope)
Tree
```

## Individual basal area

The basal area of each tree is computed with `basal_i` function.

```{r ind basal}
Tree$basal <- basal_i(dbh = Tree$DBH / 100)
Tree$basal <- round(Tree$basal, 4)
Tree
```

DBH is divided by **100** in order to convert DBH to meter (m). This conversion 
is optional and depends on the study methodology.

## Lorey's mean height
The Lorey's mean height is computed via `loreyHeight` function.
```{r Lorey}
Lorey <- loreyHeight(basal = Tree$basal, height = Tree$upHeight)
Lorey
```

**Note:** Simple mean of height is different from Lorey's mean height.

```{r Lorey \' s and simple mean diffrence, echo=FALSE}
Height.Mean <- mean(Tree$upHeight)
Height <- c(Height.Mean, Lorey)
names(Height) <- c("Mean of Height(m)", "Lorey height(m)")
Height
```

## Mean diameter
The mean diameter  is computed with `diameterMean` function.
```{r Mean diameter}
Dm <- diameterMean(Tree$DBH)
Dm
```

**Note:** Simple mean of diameter is different from mean diameter (Dm).

```{r Mean diameter vs simple mean of dbh, echo=FALSE}
Diam <- mean(Tree$DBH)
Diameter <- c(Diam, Dm)
names(Diameter) <- c("Simple mean of Diameter(cm)", "Mean diameter(cm)")
Diameter
```

# Logging: Dendrometric characteristics 
This section is illustrated with the `Logging` data set. 
 
## The `Logging` dataset
The `Logging` data are in a data frame with twenty five observations and eight 
variables assumed collected on trees and/or logs. Type `?Logging` for details.

```{r Logging dataset}
data("Logging")
summary(Logging)
```

## `factorize` a dataset
The variable `tree` is considered as *character* rather than *factor*. To 
overcome that and make easier manipulation one changes *character* variables to
*factor* variables. To do that for whole dataset, use function `factorize`. Type
`?factorize` for help.

```{r factorize}
class(Logging$tree)
Logging <- factorize(data = Logging)
class(Logging$tree)
summary(Logging)
head(Logging, 4)
attach(Logging)
```


## The decrease coefficient
This coefficient expresses the ratio between the diameter (or circumference) at 
mid-height of the bole and the diameter (or circumference) measured at breast
height. The `decrease` function is used to compute this coefficient. Type
`?decrease` for help.
```{r decrease}
Decrease <- decrease(middle = diametreMedian, breast = diametreBase)
Decrease
```

## The reduction coefficient
The reduction coefficient is the ratio between the difference in size at breast 
height and mid-height on the one hand, and the size at breast height on the 
other. It is thus the complement to 1 of the coefficient of decrease. 
The `reducecoef` function is used to compute the reduction coefficient. Type
`?reducecoef` for help.
```{r reducecoef}
Reduce <- reducecoef(middle = diametreMedian, breast = diametreBase)
Reduce
```

## Metric decay
The average metric decay expresses the difference, in centimeters per meter, 
between the diameter (or circumference) at breast height and its diameter at 
mid-height of a stem related to the difference between the height at mid-height 
and that at breast height. The average metric decay is computed using
`decreaseMetric` function.Type `?decreaseMetric` for help.
```{r decreaseMetric}
DecMetric <- decreaseMetric(
  dmh = diametreMedian, dbh = diametreBase,
  mh = hauteur / 2
)
DecMetric
```
In case of DBH considered at other height than 1.3 m, the breast height is set 
via `bh` argument of `decreaseMetric` function.
```{r decreaseMetric 1.5}
DecMetric1.5 <- decreaseMetric(
  dmh = diametreMedian, dbh = diametreBase,
  mh = hauteur / 2, bh = 1.5
)
DecMetric1.5
```

## Logs and trees volume computation 
The wood volume of logs and trees is computed withe `volume` function. Type 
`?volume` for help. The `Huber`, `Smalian`, `Cone` and `Newton` methods are 
implemented. When `successive` is set *TRUE*, the selected method is implemented 
on all log belonging to the same tree. The sum of logs volume is returned per 
tree. Type `?volume` for details.

### On foot or one log tree volume
```{r volume}
# HUBER
VolHub <- volume(height = hauteur, dm = diametreMedian, method = "huber")
# SMALIAN
VolSmal <- volume(
  height = hauteur, do = diametreBase, ds = diametreSection,
  method = "smalian"
)
# CONE
VolCone <- volume(
  height = hauteur, do = diametreBase, ds = diametreSection,
  method = "cone"
)
# NEWTON
VolNew <- volume(
  height = hauteur, do = diametreBase, dm = diametreMedian,
  ds = diametreSection, method = "newton"
)
```
Make a data frame of tree volumes per method.
```{r Trees volume}
TreeVol <- data.frame(tree, VolHub, VolSmal, VolCone, VolNew)
head(TreeVol)
```

### Tree volume from its logs volume sum
Now, let consider the variable `tree` as the tree to which belong the log; such 
that each observation of the data set stands for characteristics of a log. It's 
like trees are cut in many logs. Then those logs are measured. All logs from the 
same tree have the same value for variable `tree`. Then let compute trees volume 
with sum of all logs obtained from each tree. The `successive` argument should 
then be set to `TRUE`.
```{r volume successive}
# HUBER
VolHubSuc <- volume(
  height = hauteur, dm = diametreMedian, method = "huber",
  successive = TRUE, log = tree
)
# SMALIAN
VolSmalSuc <- volume(
  height = hauteur, do = diametreBase, ds = diametreSection,
  method = "smalian", successive = TRUE, log = tree
)
# CONE
VolConSuc <- volume(
  height = hauteur, do = diametreBase, ds = diametreSection,
  method = "cone", successive = TRUE, log = tree
)
# NEWTON
VolNewSuc <- volume(
  height = hauteur, do = diametreBase, dm = diametreMedian,
  ds = diametreSection, method = "newton", successive = TRUE,
  log = tree
)
VolNewSuc
volume(
  height = hauteur, do = diametreBase, dm = diametreMedian,
  ds = diametreSection, method = "newton", successive = TRUE, log = tree
)
```

Make a data frame of tree volumes per method.
```{r Tree volume successive}
TreeVolSuc <- data.frame(tree = unique(tree), VolHubSuc, VolSmalSuc, VolConSuc, VolNewSuc)
TreeVolSuc
```

## The shape coefficient 
The shape coefficient of the tree is the ratio of the actual volume of the tree 
to the volume of a cylinder having as base the surface of the section at 1.3 m 
(or a given breast height) and as length, the height of the tree.

```{r shape coefficient}
Shape <- shape(volume = VolNewSuc, height = hauteur, dbh = perimetreMedian)
Shape
```