Package 'pdi' reference manual

Title:	Phenotypic Index Measures for Oak Decline Severity
Description:	Oak declines are complex disease syndromes and consist of many visual indicators that include aspects of tree size, crown condition and trunk condition. This can cause difficulty in the manual classification of symptomatic and non-symptomatic trees from what is in reality a broad spectrum of oak tree health condition. Two phenotypic oak decline indexes have been developed to quantitatively describe and differentiate oak decline syndromes in Quercus robur. This package provides a toolkit to generate these decline indexes from phenotypic descriptors using the machine learning algorithm random forest. The methodology for generating these indexes is outlined in Finch et al. (2121) <doi:10.1016/j.foreco.2021.118948>.
Authors:	Jasen Finch [aut, cre]
Maintainer:	Jasen Finch <[email protected]>
License:	GPL-3
Version:	0.4.2
Built:	2024-11-07 03:27:01 UTC
Source:	https://github.com/jasenfinch/pdi

Agrilus exit hole density (m^-2)

Description

Calculate Agrilus biguttatus exit hole density.

Usage

agrilusExitHoleDensity(n, d, s = 2)
agrilusExitHoleDensity(n, d, s = 2)

Arguments

`n`	number of Agrilus exit holes
`d`	diameter at breast height (m)
`s`	height to which stem surveyed from the tree base (m)

Examples

agrilusExitHoleDensity(2,1.02,1.3)
agrilusExitHoleDensity(2,1.02,1.3)

Estimated bleed prevalence (%)

Description

Calculate estimated bleed prevalence.

Usage

bleedPrevalence(a, A, b, B, d, s = 3)
bleedPrevalence(a, A, b, B, d, s = 3)

Arguments

`a`	average active bleed size (mm)
`A`	number of active bleeds
`b`	average black stain size (mm)
`B`	number of black stains
`d`	diameter at breast height (m)
`s`	height to which stem surveyed from the tree base (m)

Examples

bleedPrevalence(30,10,40,5,1,1.3)
bleedPrevalence(30,10,40,5,1,1.3)

Calculate Decline Indexes

Description

Calculate Phenotypic Decline Index (PDI) and Decline Acuteness Index (DAI).

Usage

calcDIs(rfModels, PDI = TRUE, DAI = TRUE, invertPDI = TRUE, invertDAI = TRUE)
calcDIs(rfModels, PDI = TRUE, DAI = TRUE, invertPDI = TRUE, invertDAI = TRUE)

Arguments

`rfModels`	list containing random forest models as returned by `rf()`
`PDI`	TRUE/FALSE, calculate PDI?
`DAI`	TRUE/FALSE, calculate DAI?
`invertPDI`	invert the PDI scale? TRUE/FALSE. Ignored if argument PDI is FALSE
`invertDAI`	invert the DAI scale? TRUE/FALSE. Ignored if argument DAI is FALSE

Examples

library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- map(files,readPhenotypeSheet) %>%
  map(preparePhenotypeData) %>%
  bind_rows() %>%
  siteAdjustment() %>%
   mutate(`Live crown ratio (%)` = liveCrownRatio(`Total height (m)`,
     `Lower crown height (m)`),
     `Crown condition (%)` = crownCondition(`Missing crown (%)`,
                               `Crown transparency (%)`),
     `Crown volume (m^3)` = crownVolume(`Crown radius (m)`,
                               `Total height (m)`,
                               `Lower crown height (m)`,
                               `Crown condition (%)`),
     `Bleed prevalence (%)` = bleedPrevalence(`Active bleed length (mm)`,
                               `Active bleeds`,
                               `Black staining length (mm)`,
                               `Black staining`,
                               `Diameter at breast height (m)`),
     `Agrilus exit hole density (m^-2)` = agrilusExitHoleDensity(`Agrilus exit holes`,
                               `Diameter at breast height (m)`)
)

t <- makeAnalysisTable(d)

## Generate random forest models
m <- rf(t,cls = NULL,nreps = 10)

## Calculate decline indexese
DIs <- calcDIs(m,DAI = FALSE,invertPDI = FALSE) %>%
  bind_cols(d %>%
    select(Location,ID,Status))
library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- map(files,readPhenotypeSheet) %>%
  map(preparePhenotypeData) %>%
  bind_rows() %>%
  siteAdjustment() %>%
   mutate(`Live crown ratio (%)` = liveCrownRatio(`Total height (m)`,
     `Lower crown height (m)`),
     `Crown condition (%)` = crownCondition(`Missing crown (%)`,
                               `Crown transparency (%)`),
     `Crown volume (m^3)` = crownVolume(`Crown radius (m)`,
                               `Total height (m)`,
                               `Lower crown height (m)`,
                               `Crown condition (%)`),
     `Bleed prevalence (%)` = bleedPrevalence(`Active bleed length (mm)`,
                               `Active bleeds`,
                               `Black staining length (mm)`,
                               `Black staining`,
                               `Diameter at breast height (m)`),
     `Agrilus exit hole density (m^-2)` = agrilusExitHoleDensity(`Agrilus exit holes`,
                               `Diameter at breast height (m)`)
)

t <- makeAnalysisTable(d)

## Generate random forest models
m <- rf(t,cls = NULL,nreps = 10)

## Calculate decline indexese
DIs <- calcDIs(m,DAI = FALSE,invertPDI = FALSE) %>%
  bind_cols(d %>%
    select(Location,ID,Status))

Crown condition

Description

Calculate crown condition (%).

Usage

crownCondition(m, t)
crownCondition(m, t)

Arguments

`m`	missing crown (%)
`t`	crown transparency (%)

Examples

crownCondition(50,60)
crownCondition(50,60)

Crown production efficiency

Description

Calculate the crown production efficiency

Usage

crownProductionEfficiency(crown_surface_area, crown_volume)
crownProductionEfficiency(crown_surface_area, crown_volume)

Arguments

`crown_surface_area`	crown surface area (m^2)
`crown_volume`	crown volume (m^3)

Examples

crownProductionEfficiency(34,35)
crownProductionEfficiency(34,35)

Crown surface area (m^2)

Description

Calculate the crown surface area

Usage

crownSurfaceArea(r, h, l, c)
crownSurfaceArea(r, h, l, c)

Arguments

`r`	crown radius (m)
`h`	total height (m)
`l`	lower crown height (m)
`c`	crown condition (%)

Examples

crownSurfaceArea(3,15,10,50)
crownSurfaceArea(3,15,10,50)

Estimated crown volume (m^3)

Description

Calculate estimated crown volume.

Usage

crownVolume(r, h, l, c)
crownVolume(r, h, l, c)

Arguments

`r`	crown radius (m)
`h`	total height (m)
`l`	lower crown height (m)
`c`	crown condition (%)

Examples

crownVolume(3,15,10,50)
crownVolume(3,15,10,50)

Descriptor contributions

Description

Calculate average descriptor contributions to random forest models.

Usage

descriptorContributions(rfModels)
descriptorContributions(rfModels)

Arguments

rfModels

list containing random forest models as returned by rf()

Details

See see ?randomForest::importance for details on random forest importance metrics.

Examples

library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- map(files,readPhenotypeSheet) %>%
  map(preparePhenotypeData) %>%
  bind_rows() %>%
  siteAdjustment() %>%
   mutate(`Live crown ratio (%)` = liveCrownRatio(`Total height (m)`,
     `Lower crown height (m)`),
     `Crown condition (%)` = crownCondition(`Missing crown (%)`,
                               `Crown transparency (%)`),
     `Crown volume (m^3)` = crownVolume(`Crown radius (m)`,
                               `Total height (m)`,
                               `Lower crown height (m)`,
                               `Crown condition (%)`),
     `Bleed prevalence (%)` = bleedPrevalence(`Active bleed length (mm)`,
                               `Active bleeds`,
                               `Black staining length (mm)`,
                               `Black staining`,
                               `Diameter at breast height (m)`),
     `Agrilus exit hole density (m^-2)` = agrilusExitHoleDensity(`Agrilus exit holes`,
                               `Diameter at breast height (m)`)
)

t <- makeAnalysisTable(d)

## Generate random forest models
m <- rf(t,cls = NULL,nreps = 10)

descriptor_contributions <- m %>%
  descriptorContributions()
library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- map(files,readPhenotypeSheet) %>%
  map(preparePhenotypeData) %>%
  bind_rows() %>%
  siteAdjustment() %>%
   mutate(`Live crown ratio (%)` = liveCrownRatio(`Total height (m)`,
     `Lower crown height (m)`),
     `Crown condition (%)` = crownCondition(`Missing crown (%)`,
                               `Crown transparency (%)`),
     `Crown volume (m^3)` = crownVolume(`Crown radius (m)`,
                               `Total height (m)`,
                               `Lower crown height (m)`,
                               `Crown condition (%)`),
     `Bleed prevalence (%)` = bleedPrevalence(`Active bleed length (mm)`,
                               `Active bleeds`,
                               `Black staining length (mm)`,
                               `Black staining`,
                               `Diameter at breast height (m)`),
     `Agrilus exit hole density (m^-2)` = agrilusExitHoleDensity(`Agrilus exit holes`,
                               `Diameter at breast height (m)`)
)

t <- makeAnalysisTable(d)

## Generate random forest models
m <- rf(t,cls = NULL,nreps = 10)

descriptor_contributions <- m %>%
  descriptorContributions()

Live crown ratio

Description

Calculate the live crown ratio

Usage

liveCrownRatio(h, l)
liveCrownRatio(h, l)

Arguments

`h`	total height (m)
`l`	lower crown height (m)

Examples

liveCrownRatio(15,10)
liveCrownRatio(15,10)

Make analysis table

Description

prepare data table ready for random forest analysis

Usage

makeAnalysisTable(phenoData)
makeAnalysisTable(phenoData)

Arguments

phenoData

tibble containing phenotype data

Examples

library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- map(files,readPhenotypeSheet) %>%
  map(preparePhenotypeData) %>%
  bind_rows() %>%
  siteAdjustment() %>%
   mutate(`Live crown ratio (%)` = liveCrownRatio(`Total height (m)`,
     `Lower crown height (m)`),
     `Crown condition (%)` = crownCondition(`Missing crown (%)`,
                               `Crown transparency (%)`),
     `Crown volume (m^3)` = crownVolume(`Crown radius (m)`,
                               `Total height (m)`,
                               `Lower crown height (m)`,
                               `Crown condition (%)`),
     `Bleed prevalence (%)` = bleedPrevalence(`Active bleed length (mm)`,
                               `Active bleeds`,
                               `Black staining length (mm)`,
                               `Black staining`,
                               `Diameter at breast height (m)`),
     `Agrilus exit hole density (m^-2)` = agrilusExitHoleDensity(`Agrilus exit holes`,
                               `Diameter at breast height (m)`)
)

t <- makeAnalysisTable(d)
library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- map(files,readPhenotypeSheet) %>%
  map(preparePhenotypeData) %>%
  bind_rows() %>%
  siteAdjustment() %>%
   mutate(`Live crown ratio (%)` = liveCrownRatio(`Total height (m)`,
     `Lower crown height (m)`),
     `Crown condition (%)` = crownCondition(`Missing crown (%)`,
                               `Crown transparency (%)`),
     `Crown volume (m^3)` = crownVolume(`Crown radius (m)`,
                               `Total height (m)`,
                               `Lower crown height (m)`,
                               `Crown condition (%)`),
     `Bleed prevalence (%)` = bleedPrevalence(`Active bleed length (mm)`,
                               `Active bleeds`,
                               `Black staining length (mm)`,
                               `Black staining`,
                               `Diameter at breast height (m)`),
     `Agrilus exit hole density (m^-2)` = agrilusExitHoleDensity(`Agrilus exit holes`,
                               `Diameter at breast height (m)`)
)

t <- makeAnalysisTable(d)

Multidimensional scaling

Description

perform multidimensional scaling of random forest proximities

Usage

mds(rfModels, dimensions = 2)
mds(rfModels, dimensions = 2)

Arguments

`rfModels`	list containing random forest models as returned by `rf()`
`dimensions`	number of dimensions to scale to

Examples

library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- map(files,readPhenotypeSheet) %>%
  map(preparePhenotypeData) %>%
  bind_rows() %>%
  siteAdjustment() %>%
   mutate(`Live crown ratio (%)` = liveCrownRatio(`Total height (m)`,
     `Lower crown height (m)`),
     `Crown condition (%)` = crownCondition(`Missing crown (%)`,
                               `Crown transparency (%)`),
     `Crown volume (m^3)` = crownVolume(`Crown radius (m)`,
                               `Total height (m)`,
                               `Lower crown height (m)`,
                               `Crown condition (%)`),
     `Bleed prevalence (%)` = bleedPrevalence(`Active bleed length (mm)`,
                               `Active bleeds`,
                               `Black staining length (mm)`,
                               `Black staining`,
                               `Diameter at breast height (m)`),
     `Agrilus exit hole density (m^-2)` = agrilusExitHoleDensity(`Agrilus exit holes`,
                               `Diameter at breast height (m)`)
)

t <- makeAnalysisTable(d)

## Generate random forest models
m <- rf(t,cls = NULL,nreps = 10)

mds_data <- mds(m,2)
library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- map(files,readPhenotypeSheet) %>%
  map(preparePhenotypeData) %>%
  bind_rows() %>%
  siteAdjustment() %>%
   mutate(`Live crown ratio (%)` = liveCrownRatio(`Total height (m)`,
     `Lower crown height (m)`),
     `Crown condition (%)` = crownCondition(`Missing crown (%)`,
                               `Crown transparency (%)`),
     `Crown volume (m^3)` = crownVolume(`Crown radius (m)`,
                               `Total height (m)`,
                               `Lower crown height (m)`,
                               `Crown condition (%)`),
     `Bleed prevalence (%)` = bleedPrevalence(`Active bleed length (mm)`,
                               `Active bleeds`,
                               `Black staining length (mm)`,
                               `Black staining`,
                               `Diameter at breast height (m)`),
     `Agrilus exit hole density (m^-2)` = agrilusExitHoleDensity(`Agrilus exit holes`,
                               `Diameter at breast height (m)`)
)

t <- makeAnalysisTable(d)

## Generate random forest models
m <- rf(t,cls = NULL,nreps = 10)

mds_data <- mds(m,2)

Min-max scaling

Description

Variable min-max scaling.

Usage

minMaxScale(vec)
minMaxScale(vec)

Arguments

vec

vector of numbers to scale

Examples

set.seed(1234)

d <- runif(20,1,10)

minMaxScale(d)
set.seed(1234)

d <- runif(20,1,10)

minMaxScale(d)

Phenotyping template

Description

Export a copy of the oak phenotyping data collection spreadsheet.

Usage

phenotypingTemplate(path = ".")
phenotypingTemplate(path = ".")

Arguments

path

directory path for export output

Examples

## Not run: 
phenotypingTemplate()

## End(Not run)
## Not run: 
phenotypingTemplate()

## End(Not run)

Prepare phenotype data

Description

Process parsed phenotype data sheets into a tibble suitable for random forest analysis.

Usage

preparePhenotypeData(phenotypeData)
preparePhenotypeData(phenotypeData)

Arguments

phenotypeData

parsed phenotype data collection sheet returned from readPhenotypeSheet

Examples

library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- map(files,readPhenotypeSheet) %>%
  map(preparePhenotypeData)
library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- map(files,readPhenotypeSheet) %>%
  map(preparePhenotypeData)

Read phenptyping sheet

Description

Parse .xlsx phenotype data collection sheets.

Usage

readPhenotypeSheet(file)
readPhenotypeSheet(file)

Arguments

file

file path to excel file to parse

Examples

library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- readPhenotypeSheet(files[1])
library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- readPhenotypeSheet(files[1])

Random forest analysis

Description

Perform random forest repetitions.

Usage

rf(analysisTable, cls, params = list(), nreps = 100, seed = 1234)
rf(analysisTable, cls, params = list(), nreps = 100, seed = 1234)

Arguments

`analysisTable`	tibble of phenotype data suitable for random forest analysis as returned by `preparePhenotypeData`
`cls`	analysisTable column to use as response vector. NULL for unsupervised analyses.
`params`	additional arguments to pass to randomForest::randomForest
`nreps`	number of repetitions
`seed`	random number seed

Examples

library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- map(files,readPhenotypeSheet) %>%
  map(preparePhenotypeData) %>%
  bind_rows() %>%
  siteAdjustment() %>%
   mutate(`Live crown ratio (%)` = liveCrownRatio(`Total height (m)`,
     `Lower crown height (m)`),
     `Crown condition (%)` = crownCondition(`Missing crown (%)`,
                               `Crown transparency (%)`),
     `Crown volume (m^3)` = crownVolume(`Crown radius (m)`,
                               `Total height (m)`,
                               `Lower crown height (m)`,
                               `Crown condition (%)`),
     `Bleed prevalence (%)` = bleedPrevalence(`Active bleed length (mm)`,
                               `Active bleeds`,
                               `Black staining length (mm)`,
                               `Black staining`,
                               `Diameter at breast height (m)`),
     `Agrilus exit hole density (m^-2)` = agrilusExitHoleDensity(`Agrilus exit holes`,
                               `Diameter at breast height (m)`)
)

t <- makeAnalysisTable(d)

## Generate random forest models
m <- rf(t,cls = NULL,nreps = 10)
library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- map(files,readPhenotypeSheet) %>%
  map(preparePhenotypeData) %>%
  bind_rows() %>%
  siteAdjustment() %>%
   mutate(`Live crown ratio (%)` = liveCrownRatio(`Total height (m)`,
     `Lower crown height (m)`),
     `Crown condition (%)` = crownCondition(`Missing crown (%)`,
                               `Crown transparency (%)`),
     `Crown volume (m^3)` = crownVolume(`Crown radius (m)`,
                               `Total height (m)`,
                               `Lower crown height (m)`,
                               `Crown condition (%)`),
     `Bleed prevalence (%)` = bleedPrevalence(`Active bleed length (mm)`,
                               `Active bleeds`,
                               `Black staining length (mm)`,
                               `Black staining`,
                               `Diameter at breast height (m)`),
     `Agrilus exit hole density (m^-2)` = agrilusExitHoleDensity(`Agrilus exit holes`,
                               `Diameter at breast height (m)`)
)

t <- makeAnalysisTable(d)

## Generate random forest models
m <- rf(t,cls = NULL,nreps = 10)

Site adjustment

Description

Perform a site adjustment of selected descriptors.

Usage

siteAdjustment(
  phenoData,
  descriptors = c("Diameter at breast height (m)", "Lower crown height (m)",
    "Timber height (m)", "Total height (m)", "Crown radius (m)")
)
siteAdjustment(
  phenoData,
  descriptors = c("Diameter at breast height (m)", "Lower crown height (m)",
    "Timber height (m)", "Total height (m)", "Crown radius (m)")
)

Arguments

`phenoData`	phenoData tibble containing phenotype data
`descriptors`	columns of phenoData on which to perform site correction

Examples

library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- map(files,readPhenotypeSheet) %>%
  map(preparePhenotypeData) %>%
  bind_rows() %>%
  siteAdjustment() 
library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- map(files,readPhenotypeSheet) %>%
  map(preparePhenotypeData) %>%
  bind_rows() %>%
  siteAdjustment()

Site adjustment factors

Description

Return site adjustment factors of selected phenotypic descriptors.

Usage

siteAdjustmentFactors(
  phenoData,
  descriptors = c("Diameter at breast height (m)", "Lower crown height (m)",
    "Timber height (m)", "Total height (m)", "Crown radius (m)")
)
siteAdjustmentFactors(
  phenoData,
  descriptors = c("Diameter at breast height (m)", "Lower crown height (m)",
    "Timber height (m)", "Total height (m)", "Crown radius (m)")
)

Arguments

`phenoData`	phenoData tibble containing phenotype data
`descriptors`	columns of phenoData on which calculate site correction factors

Examples

library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- map(files,readPhenotypeSheet) %>%
  map(preparePhenotypeData) %>%
  bind_rows() %>%
  siteAdjustment()

sa_factors <- siteAdjustmentFactors(d)
library(dplyr)

## Retrieve file paths for example data
files <- list.files(system.file('phenotypeDataCollectionSheets',
  package = 'pdi'),full.names = TRUE)

## Prepare data
d <- map(files,readPhenotypeSheet) %>%
  map(preparePhenotypeData) %>%
  bind_rows() %>%
  siteAdjustment()

sa_factors <- siteAdjustmentFactors(d)

Package 'pdi'

Help Index

Agrilus exit hole density (m^-2)

Description

Usage

Arguments

Examples

Estimated bleed prevalence (%)

Description

Usage

Arguments

Examples

Calculate Decline Indexes

Description

Usage

Arguments

Examples

Crown condition

Description

Usage

Arguments

Examples

Crown production efficiency

Description

Usage

Arguments

Examples

Crown surface area (m^2)

Description

Usage

Arguments

Examples

Estimated crown volume (m^3)

Description

Usage

Arguments

Examples

Descriptor contributions

Description

Usage

Arguments

Details

Examples

Live crown ratio

Description

Usage

Arguments

Examples

Make analysis table

Description

Usage

Arguments

Examples

Multidimensional scaling

Description

Usage

Arguments

Examples

Min-max scaling

Description

Usage

Arguments

Examples

Phenotyping template

Description

Usage

Arguments

Examples

Prepare phenotype data

Description

Usage

Arguments

Examples

Read phenptyping sheet

Description

Usage

Arguments

Examples

Random forest analysis

Description