Type: Package
Title: Hierarchical Model-Based Estimation Approach
Version: 1.1
Date: 2020-05-06
Description: For estimation of a variable of interest using two sources of auxiliary information available in a nested structure. For reference see Saarela et al. (2016)<doi:10.1007/s13595-016-0590-1> and Saarela et al. (2018) <doi:10.3390/rs10111832>.
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Encoding: UTF-8
LazyData: TRUE
Imports: Rcpp (≥ 0.12.16)
Depends: methods, stats, R (≥ 3.5)
LinkingTo: Rcpp, RcppArmadillo
Collate: RcppExports.R helper_functions.R HMB-class.R SummaryHMB-class.R ghmb.R gtsmb.R hmb.R tsmb.R
RoxygenNote: 6.1.0
NeedsCompilation: yes
Packaged: 2020-05-06 06:36:16 UTC; svla0001
Author: Svetlana Saarela [cre, aut], Sören Holm [aut], Zhiqiang Yang [aut], Wilmer Prentius [ctb]
Maintainer: Svetlana Saarela <admin@svetlanasaarela.com>
Repository: CRAN
Date/Publication: 2020-05-06 07:10:02 UTC

Class HMB

Description

Class HMB is the base class for the HMB-package

See Also

hmb, ghmb, tsmb, gtsmb

Sample Data for HMB package

Description

A data frame with 100000 records.

Names are GSV: hMAX: h80: CRR: pVeg: B20: B30: B50:

Class SummaryHMB

Description

Class SummaryHMB defines summary information for HMB object.

Method getSpec

Description

Get model specifications of HMB-class object

Usage

getSpec(obj)

## S4 method for signature 'HMB'
getSpec(obj)

Arguments

obj

Object of class HMB

Value

A list containing the estimated parameters, together with model arguments

Examples

pop_U  = sample(nrow(HMB_data), 20000)
pop_Sa = sample(pop_U, 5000)
pop_S  = sample(pop_U, 300)

y_S    = HMB_data[pop_S, "GSV"]
X_S    = HMB_data[pop_S, c("hMAX", "h80", "CRR", "pVeg")]
X_Sa   = HMB_data[pop_Sa, c("hMAX", "h80", "CRR", "pVeg")]
Z_Sa   = HMB_data[pop_Sa, c("B20", "B30", "B50")]
Z_U    = HMB_data[pop_U, c("B20", "B30", "B50")]

hmb_model = hmb(y_S, X_S, X_Sa, Z_Sa, Z_U)
getSpec(hmb_model)

Generalized Hierarchical Model-Based estimation method

Description

Generalized Hierarchical Model-Based estimation method

Usage

ghmb(y_S, X_S, X_Sa, Z_Sa, Z_U, Omega_S, Sigma_Sa)

Arguments

y_S

Response object that can be coerced into a column vector. The _S denotes that y is part of the sample S, with N_S \le N_{Sa} \le N_U.

X_S

Object of predictors variables that can be coerced into a matrix. The rows of X_S correspond to the rows of y_S.

X_Sa

Object of predictor variables that can be coerced into a matrix. The set Sa is the intermediate sample.

Z_Sa

Object of predictor variables that can be coerced into a matrix. The set Sa is the intermediate sample, and the Z-variables often some sort of auxilairy, inexpensive data. The rows of Z_Sa correspond to the rows of X_Sa

Z_U

Object of predictor variables that can be coerced into a matrix. The set U is the universal population sample.

Omega_S

The covariance structure of \boldsymbol{\epsilon}_{S}, up to a constant.

Sigma_Sa

The covariance structure of \boldsymbol{u}_{Sa}, up to a constant.

Details

The GHMB assumes two models

y = \boldsymbol{x} \boldsymbol{\beta} + \epsilon

\boldsymbol{x} \boldsymbol{\beta} = \boldsymbol{z} \boldsymbol{\alpha} + \boldsymbol{u}

\epsilon \perp u

For a sample from the superpopulation, the GHMB assumes

E(\boldsymbol{\epsilon}) = \mathbf{0}, E(\boldsymbol{\epsilon} \boldsymbol{\epsilon}^T) = \omega^2 \boldsymbol{\Omega}

E(\boldsymbol{u}) = \mathbf{0}, E(\boldsymbol{u} \boldsymbol{u}^T) = \sigma^2 \boldsymbol{\Sigma}

Value

A fitted object of class HMB.

References

Saarela, S., Holm, S., Healey, S.P., Andersen, H.-E., Petersson, H., Prentius, W., Patterson, P.L., Næsset, E., Gregoire, T.G. & Ståhl, G. (2018). Generalized Hierarchical Model-Based Estimation for Aboveground Biomass Assessment Using GEDI and Landsat Data, Remote Sensing, 10(11), 1832.

See Also

summary, getSpec.

Examples

pop_U    = sample(nrow(HMB_data), 20000)
pop_Sa   = sample(pop_U, 2500)
pop_S    = sample(pop_U, 300)

y_S      = HMB_data[pop_S, "GSV"]
X_S      = HMB_data[pop_S, c("hMAX", "h80", "CRR", "pVeg")]
X_Sa     = HMB_data[pop_Sa, c("hMAX", "h80", "CRR", "pVeg")]
Z_Sa     = HMB_data[pop_Sa, c("B20", "B30", "B50")]
Z_U      = HMB_data[pop_U, c("B20", "B30", "B50")]

Omega_S  = diag(1, nrow(X_S))
Sigma_Sa = diag(1, nrow(Z_Sa))

ghmb_model = ghmb(
  y_S, X_S, X_Sa, Z_Sa, Z_U, Omega_S, Sigma_Sa)
ghmb_model

Generalized Two-Staged Model-Based estmation

Description

Generalized Two-Staged Model-Based estmation

Usage

gtsmb(y_S, X_S, X_Sa, Z_Sa, Z_U, Omega_S, Phis_Sa)

Arguments

y_S

Response object that can be coersed into a column vector. The _S denotes that y is part of the sample S, with N_S \le N_{Sa} \le N_U.

X_S

Object of predictors variables that can be coersed into a matrix. The rows of X_S correspond to the rows of y_S.

X_Sa

Object of predictor variables that can be coresed into a matrix. The set Sa is the intermediate sample.

Z_Sa

Object of predictor variables that can be coresed into a matrix. The set Sa is the intermediate sample, and the Z-variables often some sort of auxilairy, inexpensive data. The rows of Z_Sa correspond to the rows of X_Sa

Z_U

Object of predictor variables that can be coresed into a matrix. The set U is the universal population sample.

Omega_S

The covariance structure of \boldsymbol{\epsilon}_{S}, up to a constant.

Phis_Sa

A 3D array, where the third dimension corresponds to the covariance structure of E(\boldsymbol{\xi}_{k,Sa} \boldsymbol{\xi}_{j,Sa}^T), in the order k=1, \ldots, p, j=1, \ldots k. For p = 3, the order (k,j) will thus be (1,1), (2,1), (2,2), (3,1), (3,2), (3,3).

Details

The GTSMB assumes the superpopulations

y = \boldsymbol{x} \boldsymbol{\beta} + \epsilon

x_k = \boldsymbol{z} \boldsymbol{\gamma}_k + \xi_k

\epsilon \perp \xi_k

For a sample from the superpopulation, the GTSMB assumes

E(\boldsymbol{\epsilon}) = \mathbf{0}, E(\boldsymbol{\epsilon} \boldsymbol{\epsilon}^T) = \omega^2 \boldsymbol{\Omega}

E(\boldsymbol{\xi}_k) = \mathbf{0}, E(\boldsymbol{\xi}_k \boldsymbol{\xi}_j^T) = \theta_{\Phi,k,j}^2 \boldsymbol{\Phi}_{k,j}, \theta_{\Phi,k,j}^2 \boldsymbol{\Phi}_{k,j} = \theta_{\Phi,j,k}^2 \boldsymbol{\Phi}_{j,k}

Value

A fitted object of class HMB.

References

Holm, S., Nelson, R. & Ståhl, G. (2017) Hybrid three-phase estimators for large-area forest inventory using ground plots, airborne lidar, and space lidar. Remote Sensing of Environment, 197, 85–97.

Saarela, S., Holm, S., Healey, S.P., Andersen, H.-E., Petersson, H., Prentius, W., Patterson, P.L., Næsset, E., Gregoire, T.G. & Ståhl, G. (2018). Generalized Hierarchical Model-Based Estimation for Aboveground Biomass Assessment Using GEDI and Landsat Data, Remote Sensing, 10(11), 1832.

See Also

summary, getSpec.

Examples

pop_U   = sample(nrow(HMB_data), 20000)
pop_Sa  = sample(pop_U, 500)
pop_S   = sample(pop_U, 100)

y_S     = HMB_data[pop_S, "GSV"]
X_S     = HMB_data[pop_S, c("hMAX", "h80", "CRR")]
X_Sa    = HMB_data[pop_Sa, c("hMAX", "h80", "CRR")]
Z_Sa    = HMB_data[pop_Sa, c("B20", "B30", "B50")]
Z_U     = HMB_data[pop_U, c("B20", "B30", "B50")]

Omega_S = diag(1, nrow(X_S))
Phis_Sa = array(0, c(nrow(X_Sa), nrow(X_Sa), ncol(X_Sa) * (ncol(X_Sa) + 1) / 2))
Phis_Sa[, , 1] = diag(1, nrow(X_Sa)) # Phi(1,1)
Phis_Sa[, , 2] = diag(1, nrow(X_Sa)) # Phi(2,1)
Phis_Sa[, , 3] = diag(1, nrow(X_Sa)) # Phi(2,2)
Phis_Sa[, , 4] = diag(1, nrow(X_Sa)) # Phi(3,1)
Phis_Sa[, , 5] = diag(1, nrow(X_Sa)) # Phi(3,2)
Phis_Sa[, , 6] = diag(1, nrow(X_Sa)) # Phi(3,3)

gtsmb_model = gtsmb(y_S, X_S, X_Sa, Z_Sa, Z_U, Omega_S, Phis_Sa)
gtsmb_model

Hierarchical Model-Based estmation

Description

Hierarchical Model-Based estmation

Usage

hmb(y_S, X_S, X_Sa, Z_Sa, Z_U)

Arguments

y_S

Response object that can be coersed into a column vector. The _S denotes that y is part of the sample S, with N_S \le N_{Sa} \le N_U.

X_S

Object of predictors variables that can be coersed into a matrix. The rows of X_S correspond to the rows of y_S.

X_Sa

Object of predictor variables that can be coresed into a matrix. The set Sa is the intermediate sample.

Z_Sa

Object of predictor variables that can be coresed into a matrix. The set Sa is the intermediate sample, and the Z-variables often some sort of auxilairy, inexpensive data. The rows of Z_Sa correspond to the rows of X_Sa

Z_U

Object of predictor variables that can be coresed into a matrix. The set U is the universal population sample.

Details

The HMB assumes two models

y = \boldsymbol{x} \boldsymbol{\beta} + \epsilon

\boldsymbol{x} \boldsymbol{\beta} = \boldsymbol{z} \boldsymbol{\alpha} + u

\epsilon \perp u

For a sample from the superpopulation, the HMB assumes

E(\boldsymbol{\epsilon}) = \mathbf{0}, E(\boldsymbol{\epsilon} \boldsymbol{\epsilon}^T) = \omega^2 \mathbf{I}

E(\boldsymbol{u}) = \mathbf{0}, E(\boldsymbol{u} \boldsymbol{u}^T) = \sigma^2 \mathbf{I}

Value

A fitted object of class HMB.

References

Saarela, S., Holm, S., Grafström, A., Schnell, S., Næsset, E., Gregoire, T.G., Nelson, R.F. & Ståhl, G. (2016). Hierarchical model-based inference for forest inventory utilizing three sources of information, Annals of Forest Science, 73(4), 895-910.

Saarela, S., Holm, S., Healey, S.P., Andersen, H.-E., Petersson, H., Prentius, W., Patterson, P.L., Næsset, E., Gregoire, T.G. & Ståhl, G. (2018). Generalized Hierarchical Model-Based Estimation for Aboveground Biomass Assessment Using GEDI and Landsat Data, Remote Sensing, 10(11), 1832.

See Also

summary, getSpec.

Examples

pop_U  = sample(nrow(HMB_data), 20000)
pop_Sa = sample(pop_U, 5000)
pop_S  = sample(pop_U, 300)

y_S    = HMB_data[pop_S, "GSV"]
X_S    = HMB_data[pop_S, c("hMAX", "h80", "CRR", "pVeg")]
X_Sa   = HMB_data[pop_Sa, c("hMAX", "h80", "CRR", "pVeg")]
Z_Sa   = HMB_data[pop_Sa, c("B20", "B30", "B50")]
Z_U    = HMB_data[pop_U, c("B20", "B30", "B50")]

hmb_model = hmb(y_S, X_S, X_Sa, Z_Sa, Z_U)
hmb_model

Method show

Description

Display model outputs

Display model summary properties

Usage

## S4 method for signature 'HMB'
show(object)

## S4 method for signature 'SummaryHMB'
show(object)

Arguments

object

Object of class HMB

Examples

pop_U  = sample(nrow(HMB_data), 20000)
pop_Sa = sample(pop_U, 5000)
pop_S  = sample(pop_U, 300)

y_S    = HMB_data[pop_S, "GSV"]
X_S    = HMB_data[pop_S, c("hMAX", "h80", "CRR", "pVeg")]
X_Sa   = HMB_data[pop_Sa, c("hMAX", "h80", "CRR", "pVeg")]
Z_Sa   = HMB_data[pop_Sa, c("B20", "B30", "B50")]
Z_U    = HMB_data[pop_U, c("B20", "B30", "B50")]

hmb_model = hmb(y_S, X_S, X_Sa, Z_Sa, Z_U)
show(hmb_model)
pop_U  = sample(nrow(HMB_data), 20000)
pop_Sa = sample(pop_U, 5000)
pop_S  = sample(pop_U, 300)

y_S    = HMB_data[pop_S, "GSV"]
X_S    = HMB_data[pop_S, c("hMAX", "h80", "CRR", "pVeg")]
X_Sa   = HMB_data[pop_Sa, c("hMAX", "h80", "CRR", "pVeg")]
Z_Sa   = HMB_data[pop_Sa, c("B20", "B30", "B50")]
Z_U    = HMB_data[pop_U, c("B20", "B30", "B50")]

hmb_model = hmb(y_S, X_S, X_Sa, Z_Sa, Z_U)
show(summary(hmb_model))

Method summary

Description

Summary of HMB model

Usage

summary(obj)

## S4 method for signature 'HMB'
summary(obj)

Arguments

obj

Object of class HMB

Value

Summary of HMB model.

Examples

pop_U  = sample(nrow(HMB_data), 20000)
pop_Sa = sample(pop_U, 5000)
pop_S  = sample(pop_U, 300)

y_S    = HMB_data[pop_S, "GSV"]
X_S    = HMB_data[pop_S, c("hMAX", "h80", "CRR", "pVeg")]
X_Sa   = HMB_data[pop_Sa, c("hMAX", "h80", "CRR", "pVeg")]
Z_Sa   = HMB_data[pop_Sa, c("B20", "B30", "B50")]
Z_U    = HMB_data[pop_U, c("B20", "B30", "B50")]

S_Sa_map = matrix(pop_S, nrow = nrow(X_S), ncol = nrow(X_Sa))
S_Sa_map = t(apply(S_Sa_map, 1, function(x) {
  return(x == pop_Sa)
})) * 1

hmb_model = hmb(y_S, X_S, X_Sa, Z_Sa, Z_U)
summary(hmb_model)

Two-staged Model-Based estmation

Description

Two-staged Model-Based estmation

Usage

tsmb(y_S, X_S, X_Sa, Z_Sa, Z_U)

Arguments

y_S

Response object that can be coersed into a column vector. The _S denotes that y is part of the sample S, with N_S \le N_{Sa} \le N_U.

X_S

Object of predictors variables that can be coersed into a matrix. The rows of X_S correspond to the rows of y_S.

X_Sa

Object of predictor variables that can be coresed into a matrix. The set Sa is the intermediate sample.

Z_Sa

Object of predictor variables that can be coresed into a matrix. The set Sa is the intermediate sample, and the Z-variables often some sort of auxilairy, inexpensive data. The rows of Z_Sa correspond to the rows of X_Sa

Z_U

Object of predictor variables that can be coresed into a matrix. The set U is the universal population sample.

Details

The TSMB assumes the superpopulations

y = \boldsymbol{x}^T \boldsymbol{\beta} + \epsilon

x_k = \boldsymbol{z}^T \boldsymbol{\gamma}_k + \xi_k

\epsilon \perp \xi_k

For a sample from the superpopulation, the TSMB assumes

E(\boldsymbol{\epsilon}) = \mathbf{0}, E(\boldsymbol{\epsilon} \boldsymbol{\epsilon}^T) = \omega^2 \mathbf{I}

E(\boldsymbol{\xi}_k) = \mathbf{0}, E(\boldsymbol{\xi}_k \boldsymbol{\xi}_j^T) = \phi_{k,j}^2 \mathbf{I}

Value

A fitted object of class HMB.

References

Saarela, S., Holm, S., Grafström, A., Schnell, S., Næsset, E., Gregoire, T.G., Nelson, R.F. & Ståhl, G. (2016). Hierarchical model-based inference for forest inventory utilizing three sources of information. Annals of Forest Science, 73(4), 895-910.

See Also

summary, getSpec.

Examples

pop_U  = sample(nrow(HMB_data), 20000)
pop_Sa = sample(pop_U, 5000)
pop_S  = sample(pop_U, 300)

y_S    = HMB_data[pop_S, "GSV"]
X_S    = HMB_data[pop_S, c("hMAX", "h80", "CRR", "pVeg")]
X_Sa   = HMB_data[pop_Sa, c("hMAX", "h80", "CRR", "pVeg")]
Z_Sa   = HMB_data[pop_Sa, c("B20", "B30", "B50")]
Z_U    = HMB_data[pop_U, c("B20", "B30", "B50")]

tsmb_model = tsmb(y_S, X_S, X_Sa, Z_Sa, Z_U)
tsmb_model