Generates percent, area or ratio-of-means estimates, with associated sampling error by domain (and estimation unit). Calculations are based on Patterson (2012) photo-based estimators for the Nevada photo-based inventory.
modPB(
PBpopdat = NULL,
tabtype = "PCT",
sumunits = FALSE,
ratio = FALSE,
landarea = "ALL",
landarea.filter = NULL,
nonsamp.pntfilter = NULL,
pntfilter = NULL,
pfilter = NULL,
rowvar = NULL,
colvar = NULL,
domlut = NULL,
domvarlst = NULL,
ratioden = "ROWVAR",
gainloss = FALSE,
gainloss.vals = NULL,
addtitle = FALSE,
returntitle = FALSE,
savedata = FALSE,
table_opts = NULL,
title_opts = NULL,
savedata_opts = NULL,
gui = FALSE,
...
)List. Population data objects returned from modPBpop().
String. Type of units for the table ("PCT", "AREA").
Logical. If TRUE, estimation units are combined to one table for output. Note: only available if tabtype="AREA". Acres
Logical. If TRUE, ratio estimates are generated.
String. Sample area for estimates ("ALL", "CHANGE"). Used to describe landarea.filter.
String. filter for land area. Must be R syntax.
String. An expression for filtering nonsampled points (e.g., cloud coverage). Must be R syntax.
String. A global filter for the pnt file. Must be R syntax.
String. A global filter for the plt file. Must be R syntax.
String. Name of domain variable in pnt used for output estimation table rows. If only 1 domain, must be rowvar. If no domain, rowvar=NULL.
String. Name of domain variable in pnt used for output estimation table columns. If only 1 domain, colvar=NULL.
DF/DT or comma-delimited (*.csv). Look-up table to define the variables in the pnt table with category codes (DOMCODE) and code names (DOMNAME), and to set a pretty name for the variable to use in output table (DOMTITLE). This table is also used to populate rowvar/colvar, row.orderby/col.orderby, and title.rowvar/title.colvar parameters. Optional.
String vector. A vector of variable names that can be row or column domains (codes and names). Optional.
String. ("ROWVAR" or "COLVAR"). If ratio, defines whether the rowvar or colvar in estimation output table is the denominator.
Logical. If TRUE, a table with the difference of gain and loss along with the variance and standard error, in percent, is generated.
String vector. A vector of names for values in gainloss table.
Logical. If TRUE and savedata=TRUE, adds title to outfile.
Logical. If TRUE, returns a character string of the title of the output data frame.
Logical. If TRUE, saves table(s) to outfolder.
List. See help(table_options()) for a list of options.
List. See help(title_options()) for a list of options.
List. See help(savedata_options()) for a list of options. Only used when savedata = TRUE.
Logical. If gui, user is prompted for parameters.
Parameters for modPBpop() if PBpopdat is NULL.
A list with estimates with percent sampling error for rowvar (and colvar). If sumunits=TRUE or unitvar=NULL and colvar=NULL, one data frame is returned. Otherwise, a list object is returned with the following information. If savedata=TRUE, all data frames are written to outfolder.
DF. Estimated percent cover or area by rowvar, colvar, (and estimation unit).
DF. Percent sampling error of estimates by rowvar, colvar (and estimation unit).
List with 1 or 2 string vectors. If returntitle=TRUE a list with table title(s). The list contains one title if est and pse are in the same table and two titles if est and pse are in separate tables. Row and column tables are also included in list.
List of data frames. If rawdata=TRUE, a list including the processing data used for estimation including: number of plots and conditions; stratification information; and 1 to 8 tables with calculated values for table cells and totals (See processing data below).
Raw data
Table. Number of points by rowvar/colvar (sampled and nonsampled).
Data frame. Strata information by estimation unit.
| Variable | Description | |
| unitvar | estimation unit | |
| strvar | strata | |
| areavar | If tabtype='AREA', area by strata for estimation unit | |
| n.strata | number of plots in strata (after totally nonsampled plots removed) | |
| n.total | number of plots for estimation unit | |
| TOTAREA | If tabtype='AREA', total area for estimation unit | |
| strwt | proportion of area (or number of plots) by strata (strata weight) |
Data frames. Separate data frames of variables used in estimation process for the rowvar, colvar and combination of rowvar and colvar (if colvar is not NULL), and grand total by estimation unit (unit.rowest, unit.colest, unit.grpest, respectively) and summed estimation units, if FIA=TRUE (rowest, colest, grpest, respectively).
The data frames include the following information:
| Variable | Description | |
| phat | estimated proportion of covered land | |
| phat.var | variance of estimated proportion of covered land | |
| areavar | If tabtype='AREA', total area for estimation unit | |
| est | If tabtype='AREA', estimated area of land phat*areavar If tabtype='PCT', estimated percent cover of land phat*100 | |
| est.var | variance of estimated area of land phat.var*areavar | |
| If tabtype='PCT', estimated percent cover of land phat.var*100 | est.se | |
| standard error of estimated area or percent cover sqrt(est.var) | est.cv | |
| coefficient of variance of estimated area or percent cover est.se/est | est.pse | |
| percent sampling error of estimated area of percent cover est.cv*100 | CI99left | |
| left tail of 99 percent confidence interval for estimate | CI99right | |
| right tail of 99 percent confidence interval for estimate | CI95left | |
| left tail of 95 percent confidence interval for estimate | CI95right | |
| right tail of 95 percent confidence interval for estimate | CI67left | |
| left tail of 67 percent confidence interval for estimate | CI67right |
if ratio=TRUE:
| Variable | Description | |
| phat.n | estimated proportion of covered land, for numerator (colvar) | |
| phat.var.n | variance of estimated proportion of covered land, for numerator (colvar) | |
| phat.d | estimated proportion of covered land, for denominator (rowvar) | |
| phat.var.d | variance of estimated proportion of covered land, for denominator (rowvar) | |
| covar | covariance of estimated proportion of numerator (rowvar) and denominator (colvar) | |
| rhat | ratio of estimated proportions (numerator-colvar / denominator-rowvar) | |
| rhat.var | variance of ratio of estimated proportions | |
| rhat.se | standard error of ratio of estimated proportions sqrt(rhat.var) | |
| rhat.cv | coefficient of variation of ratio of estimated proportions rhat.se/rhat | |
| areavar | If tabtype='AREA', total area for estimation unit | |
| est | If tabtype='AREA', estimated area of land rhat*areavar If tabtype='PCT', estimated percent cover of land rhat*100 | |
| est.var | variance of estimated area of land rhat.var*areavar | |
| If tabtype='PCT', estimated percent cover of land rhat.var*100 | est.se | |
| standard error of estimated area or percent cover sqrt(est.var) | est.cv | |
| coefficient of variance of estimated area or percent cover est.se/est | est.pse | |
| percent sampling error of estimated area of percent cover est.cv*100 | CI99left | |
| left tail of 99 percent confidence interval for estimated area | CI99right | |
| right tail of 99 percent confidence interval for estimated area | CI95left | |
| left tail of 95 percent confidence interval for estimated area | CI95right | |
| right tail of 95 percent confidence interval for estimated area | CI67left | |
| left tail of 67 percent confidence interval for estimated area | CI67right |
If variables are NULL, then it will prompt user to input variables.
STRATA:
Stratification is used to reduce variance in population estimates
by partitioning the population into homogenous classes (strata), such as
forest and nonforest. For stratified sampling methods, the strata sizes
(weights) must be either known or estimated. Remotely-sensed data is often
used to generate strata weights with proporation of pixels by strata. If
stratification is desired (strata=TRUE), the required data include: stratum
assignment for the center location of each plot, stored in either pltassgn
or cond; and a look-up table with the area or proportion of the total area
of each strata value by estimation unit, making sure the name of the strata
(and estimation unit) variable and values match the plot assignment name(s)
and value(s).
sumunits:
An estimation unit is a population, or area of interest, with
known area and number of plots. Individual counties or combined
Super-counties are common estimation units for FIA. An estimation unit may
also be a subpopulation of a larger population (e.g., Counties within a
State). Subpopulations are mutually exclusive and independent within a
population, therefore estimated totals and variances are additive. For
example, State-level estimates are generated by summing estimates from all
subpopulations within the State (Bechtold and Patterson. 2005. Chapter 2).
Each plot must be assigned to only one estimation unit.
If sumunits=TRUE, estimates are generated by estimation unit, summed together, and returned as one estimate. If rawdata=TRUE, estimates by individual estimation unit are also returned.
If sumunits=FALSE, estimates are generated and returned by estimation unit as one data frame. If savedata=TRUE, a separate file is written for each estimation unit.
stratcombine:
If TRUE and less than 2 plots in any one estimation unit,
all estimation units with 10 or less plots are combined. The current method
for combining is to group the estimation unit with less than 10 plots with
the estimation unit following in consecutive order (numeric or
alphabetical), restrained by survey unit (UNITCD) if included in dataset,
and continuing until the number of plots equals 10. If there are no
estimation units following in order, it is combined with the estimation unit
previous in order.
rowlut/collut:
There are several objectives for including rowlut/collut
look-up tables: 1) to include descriptive names that match row/column codes
in the input table; 2) to use number codes that match row/column names in
the input table for ordering rows; 3) to add rows and/or columns with 0
values for consistency. No duplicate names are allowed.
Include 2 columns in the table:
1-the merging variable with same name as
the variable in the input merge table;
2-the ordering or descriptive
variable.
If the ordering variable is the rowvar/colvar in the input
table and the descriptive variable is in rowlut/collut, set
row.orderby/col.orderby equal to rowvar/colvar. If the descriptive variable
is the rowvar/colvar in the input table, and the ordering code variable is
in rowlut/collut, set row.orderby/col.orderby equal to the variable name of
the code variable in rowlut/collut.
Frescino, Tracey S.; Moisen, Gretchen G.; Megown, Kevin A.; Nelson, Val J.; Freeman, Elizabeth A.; Patterson, Paul L.; Finco, Mark; Brewer, Ken; Menlove, James 2009. Nevada Photo-Based Inventory Pilot (NPIP) photo sampling procedures. Gen. Tech. Rep. RMRS-GTR-222. Fort Collins, CO: U.S. Department of Agriculture, Forest Service, Rocky Mountain Research Station. 30 p.
Patterson, Paul L. 2012. Photo-based estimators for the Nevada photo-based inventory. Res. Pap. RMRS-RP-92. Fort Collins, CO: U.S. Department of Agriculture, Forest Service, Rocky Mountain Research Station. 14 p.
# \donttest{
# Load necessary data from FIESTA
## Point data
icepntfn <- system.file("extdata",
"PB_data/icepnt_utco1135.csv",
package = "FIESTA")
icepnt <- read.csv(icepntfn)
## Plot data
icepltfn <- system.file("extdata",
"PB_data/icepltassgn_utco1135.csv",
package = "FIESTA")
iceplt <- read.csv(icepltfn)
## County data
unitareafn <- system.file("extdata",
"PB_data/unitarea_utco1135.csv",
package = "FIESTA")
unitarea <- read.csv(unitareafn)
## ICE Cover
icecoverfn <- system.file("extdata",
"PB_data/cover_LUT.csv",
package = "FIESTA")
icecover <- read.csv(icecoverfn)
names(icecover) <- sub("cover", "cover_1", names(icecover))
# Set up population data (see ?modPBpop() for more information)
PBpopunit <- modPBpop(pnt = icepnt,
pltassgn = iceplt,
pltassgnid = "plot_id",
pntid = "dot_cnt",
unitarea = unitarea,
unitvar = "ESTN_UNIT")
#> no strata
# Photo-based estimation with point-level data by estimation unit (county)
## Without summing units
cover1.unit.area <- modPB(
PBpopdat = PBpopunit,
tabtype = "AREA",
rowvar = "cover_1",
nonsamp.pntfilter = "cover_1 != 999",
table_opts = list(rowlut = icecover),
title_opts = list(title.rowvar = "Land Cover (2011)")
)
#> cover_1 != 999
#> filter removed 2 records: cover_1 != 999
cover1.unit.area$est
#> Land Cover (2011) 11 35 Total
#> 1 Tree 32348.7 129952.9 165240.8
#> 2 Shrub 12070.4 91757.8 106358.3
#> 3 OtherVegetation 96885.2 132489.3 229672.4
#> 4 Barren 55202 54010.3 108670.5
#> 5 Impervious 13518.9 83551.8 99267.8
#> 6 Water 195540.8 25214.8 213333.3
#> 7 Total 405566 516977 922543
## With summing units
cover1.unit.area.sum <- modPB(
PBpopdat = PBpopunit,
tabtype = "AREA",
rowvar = "cover_1",
nonsamp.pntfilter = "cover_1 != 999",
sumunits = TRUE,
table_opts = list(rowlut = icecover),
title_opts = list(title.rowvar = "Land Cover (2011)")
)
#> cover_1 != 999
#> filter removed 2 records: cover_1 != 999
cover1.unit.area.sum$est
#> Land Cover (2011) Estimate Percent Sampling Error
#> 1 Tree 162301.7 13.95
#> 2 Shrub 103828.2 18.81
#> 3 OtherVegetation 229374.6 11.86
#> 4 Barren 109212.3 19.77
#> 5 Impervious 97070.7 18.72
#> 6 Water 220755.5 13.26
#> 7 Total 922543 0
# }