DBgetStrata {FIESTA}

Database - Gets stratification information from FIA database.

Description

Gets strata information from FIA's Oracle database or FIA DataMart, including: (1) strata and estimation unit assignment per plot; (2) total area by estimation unit; (3) pixel counts and number plots by strata/estimation unit. Include a data frame of plots, states, or evaluation information.

Usage

DBgetStrata(
  dat = NULL,
  uniqueid = "CN",
  datsource = "datamart",
  data_dsn = NULL,
  states = NULL,
  eval_opts = eval_options(Cur = TRUE),
  savedata = FALSE,
  getassgn = TRUE,
  pop_plot_stratum_assgn = NULL,
  savedata_opts = NULL,
  dbconn = NULL,
  dbconnopen = FALSE,
  evalInfo = NULL,
  ...
)

Arguments

dat

Data frame, comma-delimited file (*.csv), or shapefile (*.shp). The strata value is merged to this table and returned as a data frame. See details for necessary variables.

uniqueid

String. The unique plot identifier of dat (e.g., 'CN').

datsource

String. Source of data ('datamart', 'sqlite').

data_dsn

String. If datsource='sqlite', the name of SQLite database (*.sqlite).

states

String or numeric vector. Name(s) (e.g., 'Arizona','New Mexico') or code(s) (e.g., 4, 35) of states for strata if dat=NULL.

eval_opts

List of evaluation options for 'FIA' or 'custom' evaluations to determine the set of data returned. See help(eval_options) for a list of options.

savedata

Logical. If TRUE, writes output to outfolder.

getassgn

Logical. If TRUE, extracts plot assignments from pop_plot_stratum_assgn table in database.

pop_plot_stratum_assgn

Data frame. The pop_plot_stratum_assgn for state(s).

savedata_opts

List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE.

dbconn

Open database connection.

dbconnopen

Logical. If TRUE, the dbconn connection is not closed.

evalInfo

List. List object output from DBgetEvalid or DBgetXY

...

For extendibility. FIESTA functions.

Details

The following variables must be present in dat: STATECD, UNITCD, INVYR, a uniqueid (e.g. "PLT_CN"), and PLOT_STATUS_CD (if nonsampled plots in dataset).

FIADB TABLES USED:

	FS_FIADB.SURVEY	To get latest inventory year.
	FS_FIADB.POP_EVAL	To get EVALID and EVALID years.
	FS_FIADB.POP_ESTN_UNIT	To get total area by estimation unit (AREATOT_EU-includes water).
	FS_FIADB.POP_STRATUM	To get pixel counts by stratum and estimation unit.
	FS_FIADB.POP_PLOT_STRATUM_ASSGN	To get estimation unit & stratum assignment for each plot.

Area by estimation unit includes total area for all plots (Type="CURR").

Value

FIAstrata - a list of the following objects:

pltassgn

Data frame. Plot-level strata/estimation unit assignment. If dat is not NULL, strata/estimation unit variables are appended to dat.

pltassgnid

String. Name of unique identifier of plot in pltassgn.

unitarea

Data frame. Total acres by estimation unit.

unitvar

String. Name of the estimation unit variable (ESTN_UNIT).

areavar

String. Name of the acre variable (ACRES).

stratalut

Data frame. Strata look-up table with summarized pixel counts (P1POINTCNT) by strata/estimation unit.

strvar

String. Name of the strata variable (STRATA).

strwtvar

String. Name of the strata weight variable (P1POINTCNT).

evalid

List. evalid by state.

Outputs to outfolder (if savedata=TRUE):

	- CSV file of pltassgn (*'date'.csv).
	- CSV file of unitarea (*'date'.csv).
	- CSV file of stratalut (*'date'.csv).
	- If collapsed, a CSV file of original classes and new collapsed classes.

Note

Steps used in data extraction:

1. Get EVALID and EVALID years by state - DBgetEvalid().

2. unitarea: get total area by estimation unit for EVALID (POP_ESTN_UNIT).

3. stratalut: get pixel counts by estimation unit and stratum for EVALID (POP_STRATUM).

4. pltassgn: get estimation unit and stratum assignment for each plot for EVALID. (POP_PLOT_STRATUM_ASSGN).

5. If dat is not NULL, merge pltassgn assignment to dat.

6. Merge number of plots to stratalut

7. Check for only 1 MEASYEAR or 1 INVYR and number of plots by strata/estimation unit. If less than minimumnum plots per strata/estimation unit collapse using the following algorithm.

Strata collapsing:
If there are less than minplotnum (10) plots in the smallest strata of the estimation unit, these plots are grouped with the larger strata in the same estimation unit and defined as the highest strata value. If, after grouping, there are still less than minplotnum, all of these plots are combined with the corresponding strata of the estimation unit above. If there are no records above, then they are combined with the estimation unit below. The process repeats, grouping the strata to the highest strata value if necessary. All grouping is restrained within survey units (UNITCD).

More than one evaluation:
If attributing a table of plots and there are plots that have been visited more than once, all plots are assigned an estimation unit and strata value, but the area and strata proportions are from the most current evaluation for the dataset. The plots outside the most current evaluation are attributes with values from the next most current evaluation occurring in the database.

Author(s)

Tracey S. Frescino

Examples

## Not run: 
# Get strata for the most current evaluation of a state (ex. Wyoming)
WYstrat1 <- DBgetStrata(states = "Wyoming",
                        eval_opts = list(Cur = TRUE))
names(WYstrat1)

head(WYstrat1$pltassgn)
WYstrat1$unitarea
WYstrat1$unitvar
WYstrat1$areavar
WYstrat1$strvar
WYstrat1$evalid

# Get strata information for a specific set of plots
WYstrat4 <- DBgetStrata(dat = WYplt)
names(WYstrat4)

head(WYstrat4$pltassgn)
WYstrat4$unitarea
WYstrat4$evalid

## End(Not run)