---
title: "03b Estimating population parameters: ratio estimator"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{03b Estimating population parameters: ratio estimator}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```


## Introduction 

The aim of this document is to demonstrate how to estimate population parameters from RDBESDataObjects. 

```{r}
library(RDBEScore)
```

## Prerequisites

We'll use some example data from the RDBES.  For your own data it's a good idea to check your RDBESDataObjects are valid after any manipulations you perform.


## Estimation workflow

Estimation actually  is done on a *RDBESEstObject* that is generate from *RDBESDataObject* using **createRDBESEstObject(...)**. The following example uses a dataset that  resembles in many ways real data at ICES area 27.3.d.28.1 from the Estonian Baltic Trawling fleet for 2022 sprat (*Sprattus sprattus*).The dataset has both total landings and commercial sampling data.

```{r}
H8ExampleEE1
```
The data has not gone through RDBES upload and download procedure and  contains invalid data types but also may have some other validity problems. However the fields for estimation should be present and valid.
```{r eval=FALSE, echo=TRUE}
#to check data types
validateRDBESDataObject(H8ExampleEE1, checkDataTypes = TRUE, strict = FALSE)
```




### Simple Estimation Example


For the simplest case of estimation we need the RDBESDataObject with CS tables and a CL table. In the following example we will estimate the total number of sprat caught in the area 27.3.d.28.1 with the gear OTM_SPF_16-31_0_0 for the first and last quarter of the year.

```{r}
#From the commertial landings table we need to get the total weight of the catches
CLfieldstoSum <- c("CLoffWeight")
```

The most important thing in this estimation is to get the same strata for the CS and CL tables. This means we want to take the samples from the same area, with the same gear and the same species. Exactly how this is done depends on the upper and lower hierarchy used and how the sampling is stratified. In the following example we are using the lower hierarchy C meaning that we are extracting the BV data as the biological data. 

```{r}
#get the first quarter data from CS 
strataListCS <- list(LEarea="27.3.d.28.1",
                     LEmetier6 = "OTM_SPF_16-31_0_0",
                     TEstratumName = month.name[1:3],
                    SAspeCodeFAO = "SPR")

#get the first quarter data from CL table
strataListCL <- list(CLarea="27.3.d.28.1",
                     CLquar = 1,
                     CLmetier6 = "OTM_SPF_16-31_0_0",
                     CLspecFAO = "SPR")

#we are using the lower hierarchy C meaning that we are extracting the BV data
#as the biological data
biolCLQ1 <- addCLtoLowerCS(H8ExampleEE1, strataListCS, strataListCL,
                         combineStrata =T, lowerHierarchy = "C",
                         CLfields = CLfieldstoSum)
```

To estimate the total number of sprat caught in the area 27.3.d.28.1 with the gear OTM_SPF_16-31_0_0 for the first quarter of the year we need to use the function **doBVestimCANUM(...)**. The function takes the biological data table, the columns to be added to the final result and the class breaks for the estimation. The function returns a table with the estimates for the given class breaks.
The allowed class units are "Ageyears", "Lenghtmm" and "Weightg". The class breaks are the number of classes to break the data into. The function will return the estimates for each class.
The addColumns parameter is a vector of column names that will be added to the final result. The columns should be present in the biological data table. A minimum of one column (the sum column that in our case is "sumCLoffWeight") is required. The function will return the estimates for each unique value in the columns.

```{r}
lenCANUMQ1 <- doBVestimCANUM(biolCLQ1, c("sumCLoffWeight"),
             classUnits = "Lengthmm",
             classBreaks = seq(70,130,10),
             verbose = FALSE)

lenCANUMQ1
```


To have the estimates for several Quarters in the result same biolCL table creation is done for the last quarter of the year. 

```{r}
strataListCS <- list(LEarea="27.3.d.28.1",
                     LEmetier6 = "OTM_SPF_16-31_0_0",
                     TEstratumName = month.name[10:12], #the last 3 months of the year
                    SAspeCodeFAO = "SPR")

strataListCL <- list(CLarea="27.3.d.28.1",
                     CLquar = 4,
                     CLmetier6 = "OTM_SPF_16-31_0_0",
                     CLspecFAO = "SPR")

biolCLQ4 <- addCLtoLowerCS(H8ExampleEE1, strataListCS, strataListCL,
                         combineStrata =T, lowerHierarchy = "C",
                         CLfields = CLfieldstoSum)
```

```{r}
#lets combine the two quarters into one table
biolCL <- rbind(biolCLQ1, biolCLQ4)
```

More columns from the above table can be added to the final result. The output is broken down by unique values in these columns.

```{r}
#this alllows to add extra columns into the final result 
addCols <- c(names(strataListCS),
             names(strataListCL),
             paste0('sum', CLfieldstoSum))

ageCANUM <- doBVestimCANUM(biolCL, addCols,
             classUnits = "Ageyear",
             classBreaks = 1:8,
             verbose = FALSE)

ageCANUM
             
```


The output table should be enough to populate a classic Intercatch data call table. 


See also other package vignettes:

```{r,echo=F, results='asis', eval=T}
# note: vignettes are first compiled and only then html, R and Rmd are moved to folder doc
vignettes <- data.frame(Rmd=dir()[grepl(dir(), pat=".Rmd")])
# determines index of vignette being compiled
thisVignetteRmd<-paste0(gsub(":","",gsub(" ", "-",as.character(rmarkdown::metadata$title))),".Rmd")
# prints list with links
for (i in seq_along(vignettes$Rmd)) {
  if(tolower(vignettes$Rmd[i])!=tolower(thisVignetteRmd)){
  cat(sprintf("- [%s](%s)\n", gsub("-"," ",gsub(".Rmd","",vignettes$Rmd[i])), gsub(".Rmd",".html",vignettes$Rmd[i])))
}
}
```

#END
