Package 'PSPclean'

Title: Sources and standardizes permanent sample plot data
Description: Converts all data into two keyed tables. One is for tree measurements, and the other is for plot data. Some arguments exist for handling disturbance agents.
Authors: Ian M S Eddy [aut, cre], Alex M Chubaty [ctb]
Maintainer: Ian M S Eddy <[email protected]>
License: GPL-3
Version: 1.0.0.9006
Built: 2026-06-02 23:45:30 UTC
Source: https://github.com/ianmseddy/PSPclean

Help Index

Analyze Regeneration Proportion and Tree DBH Growth

Description

  1. Identifies plots where all trees identified, and their subsequent measurements. These are of interest as the stand age is unlikely to be correct

  2. calculates elapsed time between successive measurements and flags trees with biologically implausible DBH growth based on the max_assumed_growth_rate param

Usage

assessTreeNumberConsistency(plots, max_assumed_growth_rate = 1)

Arguments

plots

A list containing at least a data frame PSPmeasure with tree measurements and PSPplot with measurement years.
max_assumed_growth_rate

Maximum plausible DBH growth per year for regenerating trees (cm/year, default = 1).

Value

A list with:

problematicMeasurements

MeasurementIDs with 100% regen at some point in plot history If the problematic measurement is the last measurement, then prior measurements are not included. If the problematic measurement is NOT the first, then all measurements are included

problematic trees

trees with problematic DBH (ie growing faster than max_assumed_growth_rate) and other variables: elapsedTime (years between measurements), DBHdiffFromMax (the difference between the actual growth rate and the expected maximum growth rate), and DBHdiffFromMax_perYear (the latter divided by the former))

Classify Tree Status Based on Measurement History

Description

Assigns status to each tree based on its observation history. Detects new regeneration, lost trees, and survivors.

Usage

classify_tree_status(Trees)

Arguments

Trees

A data.table of tree records across multiple measurement years.

Value

A list containing:

Trees

The full dataset with status classification.

Regeneration

Trees first appearing after plot monitoring began.

Last_Measurement

Trees last measured before monitoring ended.

Alive

Trees present consistently or throughout.

OrigPlotID1s

Unique OrigPlotID1 identifiers.

Standardize and Treat the Alberta PSP Data

Description

This function cleans and standardizes the Alberta PSP data, including tree measurements and plot information. Species names can be standardized using a species equivalency table.

Usage

dataPurification_ABPSP(
  treeMeasure,
  plotMeasure,
  tree,
  plot,
  codesToExclude = 3,
  excludeAllObs = TRUE,
  areaDiffThresh = 0.95,
  sppEquiv = LandR::sppEquivalencies_CA,
  sppEquivCol = "Latin_full"
)

Arguments

treeMeasure

A data.frame or data.table containing tree measurement data.
plotMeasure

A data.frame or data.table containing plot measurement data.
tree

A data.frame or data.table containing tree information.
plot

A data.frame or data.table containing plot information.
codesToExclude

Character vector of damage agent codes used to filter tree data (see GOA PSP Manual). Measurements with these codes will be removed.
excludeAllObs

Logical. If TRUE, all prior and future observations of trees with codes in codesToExclude are removed.
areaDiffThresh

Numeric. Threshold for plot size discrepancy below which plots are assigned a new ID. Expressed as min(PlotSize)/max(PlotSize).
sppEquiv

A table providing species name equivalencies between the original PSP species names and the final standardized naming format. Default is LandR::sppEquivalencies_CA.
sppEquivCol

Character string. The column in sppEquiv that contains the standardized species' names. Default is "Latin_full".

Value

A list containing standardized plotData and treeData as data.tables.

#' Standardize and Treat the BC PSP Data

Description

This function cleans and standardizes the British Columbia PSP data, including tree measurements and plot header information. Species names can be standardized using a species equivalency table.

Usage

dataPurification_BCPSP(
  treeDataRaw,
  plotHeaderDataRaw,
  damageAgentCodes,
  codesToExclude = "IBM",
  excludeAllObs = TRUE,
  sppEquiv = LandR::sppEquivalencies_CA,
  sppEquivCol = "Latin_full"
)

Arguments

treeDataRaw

A data.frame or data.table containing the raw tree measurement data.
plotHeaderDataRaw

A data.frame or data.table containing the raw plot header data.
damageAgentCodes

A character vector of damage agent codes present in the data.
codesToExclude

A character vector of damage agent codes to exclude from measurements.
excludeAllObs

Logical. If TRUE, all prior and future observations of a tree with a damage code in codesToExclude are removed. Default is TRUE.
sppEquiv

A table providing species name equivalencies between the original PSP species names and the final standardized naming format. Default is LandR::sppEquivalencies_CA.
sppEquivCol

Character string. The column in sppEquiv that contains the standardized species' names. Default is "Latin_full".

Value

A list containing standardized plotData and treeData as data.tables.

Standardize and Treat the New Brunswick PSP Data

Description

This function cleans and standardizes New Brunswick PSP data, including tree and plot data. Species names can be standardized using a species equivalency table.

Usage

dataPurification_NBPSP(
  NB_PSP_Data,
  sppEquiv = LandR::sppEquivalencies_CA,
  sppEquivCol = "Latin_full"
)

Arguments

NB_PSP_Data

A list of data.tables resulting from prepInputsNBPSP, containing raw PSP data.
sppEquiv

A table providing species name equivalencies between the original PSP species names and the final standardized naming format. Default is LandR::sppEquivalencies_CA.
sppEquivCol

Character string. The column in sppEquiv that contains the standardized species names. Default is "Latin_full".

Value

A list containing standardized plotData and treeData as data.tables.

Standardize and Treat the NFI PSP Data

Description

This function cleans and standardizes NFI PSP data, including tree, plot, and location data. Species names can be standardized using a species equivalency table.

Usage

dataPurification_NFIPSP(
  NFIdata,
  codesToExclude = "IB",
  excludeAllObs = TRUE,
  sppEquiv = LandR::sppEquivalencies_CA,
  sppEquivCol = "Latin_full"
)

Arguments

NFIdata

A list containing NFI tree, plot, and location data.tables.
codesToExclude

Vector of damage agent codes. Measurements with these codes will be removed.
excludeAllObs

Logical. If TRUE, removing observations of individual trees due to damage codes will also remove all prior and future observations of that tree.
sppEquiv

A table providing species name equivalencies between the original PSP species names and the final standardized naming format. Default is LandR::sppEquivalencies_CA.
sppEquivCol

Character string. The column in sppEquiv that contains the standardized species names. Default is "Latin_full".

Value

A list containing standardized plotData and treeData as data.tables.

#' Standardize and Treat the Ontario PSP Data

Description

This function cleans and standardizes Ontario PSP data, including tree and plot data. Species names can be standardized using a species equivalency table.

Usage

dataPurification_ONPSP(
  ONPSPlist,
  sppEquiv = LandR::sppEquivalencies_CA,
  sppEquivCol = "Latin_full"
)

Arguments

ONPSPlist

A list of relevant PSP plots and associated data.tables.
sppEquiv

A table providing species name equivalencies between the original PSP species names and the final standardized naming format. Default is LandR::sppEquivalencies_CA. Must include columns 'Latin' and 'PSP'.
sppEquivCol

Character string. The column in sppEquiv that contains the standardized species names. Default is "Latin_full".

Value

A list containing standardized plotData and treeData as data.tables.

Standardize and Treat the Quebec PSP Data

Description

This function cleans and standardizes the Quebec PSP data, including tree and plot data. Species names can be standardized using a species equivalency table.

Usage

dataPurification_QCPSP(
  QuebecPSP,
  codesToExclude = NULL,
  excludeAllObs = TRUE,
  sppEquiv = LandR::sppEquivalencies_CA,
  sppEquivCol = "Latin_full"
)

Arguments

QuebecPSP

A list of data.tables containing raw PSP data obtained via prepInputsQCPSP.
codesToExclude

Character vector of damage or pest disturbance codes to exclude from measurements. Currently placeholder, update if applicable.
excludeAllObs

Logical. If TRUE and codesToExclude is not NULL, all prior and future observations of trees with these codes will be removed.
sppEquiv

A table providing species name equivalencies between the original PSP species names and the final standardized naming format. Default is LandR::sppEquivalencies_CA.
sppEquivCol

Character string. The column in sppEquiv that contains the standardized species names. Default is "Latin_full".

Value

A list containing standardized plotData and treeData as data.tables.

Standardize and Treat the Saskatchewan PSP Data

Description

This function cleans and standardizes the Saskatchewan PSP data, including tree measurements, plot headers, and measurement headers. Species names can be standardized using a species equivalency table.

Usage

dataPurification_SKPSP(
  SADataRaw,
  plotHeaderRaw,
  measureHeaderRaw,
  treeDataRaw,
  codesToExclude = NULL,
  excludeAllObs = TRUE,
  sppEquiv = LandR::sppEquivalencies_CA,
  sppEquivCol = "Latin_full"
)

Arguments

SADataRaw

A data.frame or data.table containing raw tree measurement data.
plotHeaderRaw

A data.frame or data.table containing raw plot header data.
measureHeaderRaw

A data.frame or data.table containing raw measurement header data.
treeDataRaw

A data.frame or data.table containing tree data.
codesToExclude

Character vector of damage agent codes used to filter tree data. Codes: Natural or Undetermined = 1, Disease = 2, Insect = 3, Human = 4, Wind = 5, Snow = 6, Other Trees = 7, Hail or Ice Storm = 8. Measurements with these codes will be removed.
excludeAllObs

Logical. If TRUE, all prior and future observations of trees with codes in codesToExclude are removed.
sppEquiv

A table providing species name equivalencies between the original PSP species names and the final standardized naming format. Default is LandR::sppEquivalencies_CA.
sppEquivCol

Character string. The column in sppEquiv that contains the standardized species names. Default is "Latin_full".

Value

A list containing standardized plotData and treeData as data.tables.

standardize and treat the Saskatchewan Mistik temporary sample plot data This function will be deprecated

Description

standardize and treat the Saskatchewan Mistik temporary sample plot data This function will be deprecated

Usage

dataPurification_SKTSP_Mistik(compiledPlotData, compiledTreeData)

Arguments

compiledPlotData

the plot header data
compiledTreeData

the tree data

Value

a list of plot and tree data.tables

Detect and flag DBH outliers using z-scores by plot

Description

Flags statistically implausible DBH values based on the z-score method #' (using mean and standard deviation) within each plot group. This can help identify data entry or measurement errors in repeated tree measurements.

Usage

detect_dbh_outliers(
  Trees,
  dbh_col = "DBH",
  plot_col = "OrigPlotID1",
  z_thresh = 7
)

Arguments

Trees

A data.table or data.frame containing DBH and plot columns.
dbh_col

Character. Name of the DBH column. Default is "DBH".
plot_col

Character. Name of the plot/grouping column. Default is "OrigPlotID1".
z_thresh

Numeric. Z-score threshold for identifying outliers. Default is 7.

Value

A list with:

Trees

The modified data.table with added columns: meanDBH, sdDBH, zscore, is_outlier_z

plotIDs

Unique plot/group IDs used in analysis

convert plot location data to long/lat and output in a sf object

Description

convert plot location data to long/lat and output in a sf object

Usage

geoCleanPSP(Locations)

Arguments

Locations

the compiled plot data

Value

an sf object with OrigPlotID1 column

return a merged PSP object from a vector of data sources

Description

return a merged PSP object from a vector of data sources

Usage

getPSP(
  PSPdataTypes,
  destinationPath,
  forGMCS = FALSE,
  sppEquiv = LandR::sppEquivalencies_CA,
  sppEquivCol = "Latin_full"
)

Arguments

PSPdataTypes

character vector of PSP data sources - e.g. ⁠c("BC", "SK)"⁠ Use "all" to get all available sources, and "dummy" for freely available data
destinationPath

destination folder for downloaded objects
forGMCS

if TRUE, will pre-filter plots with insect mortality to avoid attributing insect mortality with climate
sppEquiv

species equivalencies table.
sppEquivCol

Character string. The column in sppEquiv that contains the standardized name of each species. The default is "Latin_full". It is recommended not to change this as there must be a one-to-one or one-to-many (e.g. variants, hybrids) relationship for each column in sppEquiv that is used internally in the different standardization functions (e.g. AB_forestry)

Value

a list of standardized plot and tree data.tables

source the Alberta PSP data

Description

source the Alberta PSP data

Usage

prepInputsAlbertaPSP(dPath)

Arguments

dPath

passed to prepInputs destinationPath

Value

a list of Alberta PSP data.tables

Source the BC PSP data

Description

Source the BC PSP data

Usage

prepInputsBCPSP(dPath)

Arguments

dPath

passed to destinationPath in prepInputs()

Value

a list of BC PSP objects

retrieve the New Brunswick PSP raw data

Description

retrieve the New Brunswick PSP raw data

Usage

prepInputsNBPSP(dPath)

Arguments

dPath

data directory for raw data

Value

a list of plot, tree, measurement, and location data.tables after exporting mdb to csv txt

source the NFI PSP data

Description

source the NFI PSP data

Usage

prepInputsNFIPSP(dPath)

Arguments

dPath

passed to prepInputs destinationPath

Value

a list of NFI PSP data.tables

retrieve preprocessed Ontario PSP and PGP data

Description

retrieve preprocessed Ontario PSP and PGP data

Usage

prepInputsOntarioPSP(dPath, ...)

Arguments

dPath

the Access database for PSP and PGP plots
...

additional args passed to prepInputs

Value

a list of plot and tree data.tables

retrieve the Quebec PSP raw data

Description

retrieve the Quebec PSP raw data

Usage

prepInputsQCPSP(dPath)

Arguments

dPath

data directory for raw data

Value

a list of plot, tree, measurement, and location data.tables after exporting mdb to csv txt

source the Saskatchewan PSP data

Description

source the Saskatchewan PSP data

Usage

prepInputsSaskatchwanPSP(dPath)

Arguments

dPath

passed to prepInputs destinationPath

Value

a list of Saskatchewan PSP data.tables

source the Saskatchewan PSP data

Description

source the Saskatchewan PSP data

Usage

prepInputsSaskatchwanTSP(dPath)

Arguments

dPath

passed to prepInputs destinationPath

Value

a list of Saskatchewan PSP data.tables

standardize and treat the BC PSP data

Description

standardize and treat the BC PSP data

Usage

prepPSP_climateNA(dPath, filename2, PSPplot, PSPgis)

Arguments

dPath

directory to download elevation data
filename2

the full filename of the output file
PSPplot

the standardized PSP plot attribute data
PSPgis

the standardized plot location sf object

Value

a text file

Process Implausible DBH Changes Across Measurement Years

Description

Detects and manages inconsistencies in tree DBH (Diameter at Breast Height) measurements across years within PSP. Flags implausible negative growth, cleans the dataset accordingly, and excludes OrigPlotID1s with high anomaly rates.

Usage

process_dbh_issues(Trees)

Arguments

Trees

A data.table of tree measurements over time within PSP.

Value

A list containing:

Trees

Cleaned dataset with problematic entries removed.

dbh_check

Subset of detected DBH inconsistencies.

negative_growth_summary

Summary of negative growth by OrigPlotID1.

OrigPlotID1s

List of retained OrigPlotID1 identifiers.

standardize the species names in a given PSP measurement data.table

Description

standardize the species names in a given PSP measurement data.table

Usage

standardizeSpeciesNames(speciesTable, forestInventorySource)

Arguments

speciesTable

the tree measurement csv
forestInventorySource

one of MBTSP, ABPSP, BCPSP, SKPSP, NWTTSP, NFIPSP.

Value

the species table with standardized species names

Identify Tree Numbers Linked to Multiple Species Within a Plot

Description

Ensures consistent Species and Tree numbering within a plot (OrigPlotID1)

Usage

treenum_to_multiplePSP(Trees)

Arguments

Trees

A data.table of tree observations containing OrigPlotID1, Species, PSP, MeasureYear and TreeNumber columns.

Value

A list containing:

Trees_corrected

Cleaned tree dataset.