README.Rmd

---
output: github_document
---

# mase <img src='man/figures/logo.png' align="right" width="150" />

 <!-- badges: start -->
  [![R-CMD-check](https://github.com/mcconvil/mase/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/mcconvil/mase/actions/workflows/R-CMD-check.yaml)
   [![CRAN status](https://www.r-pkg.org/badges/version/mase)](https://CRAN.R-project.org/package=mase)
  <!-- badges: end -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```

### Overview

`mase` contains a collection of model-assisted generalized regression estimators for finite population estimation of a total or mean from a single stage, unequal probability without replacement design.  It also contains several variance estimators.

The available estimators are currently:

  - generalized regression: `greg()`
  - hotvitz-thompson: `horvitzThompson()`
  - post-stratification: `postStrat()`
  - elastic net generalized regression: `gregElasticNet()`
  - regression tree: `gregTree()`
  - modified generalized regression: `modifiedGreg()`
  - ratio estimator: `ratioEstimator()`
  - estimate of a ratio estimator: `ratio()`
  
The available variance estimation techniques are:

  - LinHB
  - LinHH
  - LinHTSRS 
  - LinHT
  - bootstrapSRS
  
See `mase/inst/REFERENCES.bib` for sources related to each variance estimator.
  

### Installation

Install the latest CRAN release with:

```{r eval = FALSE}
install.packages("mase")
```

You can also install the development version of `mase` from GitHub as follows:

```{r gh-installation, eval = FALSE}
# install.packages("pak")
pak::pkg_install("mcconvil/mase")
```

### Usage

#### Horvitz-Thompson

Here's an example of fitting the Horvitz-Thompson estimator using Forestry data in Idaho. The data is publicly available and comes from the Forestry Inventory & Analysis (FIA) program. 

```{r example1, message=F}
library(mase)
library(dplyr)

data(IdahoSamp)
data(IdahoPop)

samp <- filter(IdahoSamp, COUNTYFIPS == 16055) 
pop <- filter(IdahoPop, COUNTYFIPS == 16055) 

horvitzThompson(y = samp$BA_TPA_ADJ,
                N = pop$npixels,
                var_est = TRUE,
                var_method = "LinHTSRS")
```

#### Linear Regression Estimator

We can also fit a linear regression estimator using that same data:

```{r example2, message = F}
xsample <- select(samp, c(tcc, elev, ppt, tmean))

xpop <- select(pop, names(xsample))

greg_est <- greg(y = samp$BA_TPA_ADJ,
                 N = pop$npixels,
                 xsample = xsample,
                 xpop = xpop,
                 var_est = TRUE,
                 var_method = "LinHB",
                 datatype = "means")
```

We still get the population total and mean estimates along with their variance estimates:

```{r}
greg_est[c('pop_total','pop_mean', 'pop_total_var', 'pop_mean_var')]
```

But with this estimator we also get the weights

```{r}
greg_est["weights"]
```

and the coefficients for the model

```{r}
greg_est["coefficients"]
```


#### Variable Selection

All of the mase regression estimators can also perform variable selection internally using the parameter `modelselect`

```{r, message = FALSE}
greg_select <- greg(y = samp$BA_TPA_ADJ,
                    N = pop$npixels,
                    xsample = xsample,
                    xpop = xpop,
                    modelselect = TRUE,
                    var_est = TRUE,
                    var_method = "LinHB",
                    datatype = "means")
```

And we can examine which predictors were chosen:

```{r}
greg_select["coefficients"]
```