---
title: "Replicate weights"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Replicate weights}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r ,echo=FALSE}
library(ILSAstats)
```

Depending on our data, it may contain or not replicate weights. If it does not, we need to create them. For this we will need variables containing the jackknife zones, the jackknife replications, and the total weights. Normally, all this information is provided within the data.

For example, using the data `timss99`, we can find the variables `"JKZONE"`, `"JKREP"`, and `"TOTWGT"`:

```{r}
colnames(repdata)
```

Now, we would need also to select some options for the creation of the replicate weights: a) we need to establish the number of replications; and b) we need to decide which method we are going to use.

For the number of replications, we use the argument `reps`, that is `NULL` by default (we recommend using this option). If left `NULL`, the number of replications will be determined using the `"jkrep"` variable. Nevertheless, we can adjust this if needed. 

## Method

More importantly, we need to decide on the method. All methods are available for all ILSAs, so you are able to use the official one or experiment with other. For creating replicate weights, 4 methods are implemented, you can use the method name or the ILSA names:

- `"JK-full"`, corresponds to `"TIMSS"`, `"PIRLS"` and `"LANA"`.
- `"JK-half"`, corresponds to `"ICILS"`, `"ICCS"`, and `"CIVED"`.
- `"JK2-half-1PV"`, corresponds to `"oldTIMSS"`, `"oldPIRLS"`, and `"RLII"` (for TIMSS and PIRLS conducted before 2015).
- `"FAY-0.5"`, corresponds to `"PISA"` and `"TALIS"`.


Our data corresponds to TIMSS 1999, so we are advised to use either the old method of TIMSS to replicate results (`"oldTIMSS"`), or the new method of TIMSS to compare it to new results (`"TIMSS"`).

## Creation of weights

So, now knowing our options we can use `timss99` data and `repcreate()` for creating the replicate weights:
```{r}
RW1 <- repcreate(df = timss99,
                jkzone = "JKZONE",
                jkrep = "JKREP",
                wt = "TOTWGT",
                method = "oldTIMSS")

```

We can see that this new object is a data frame with 75 columns (representing the 75 replications):
```{r}
class(RW1)
ncol(RW1)
head(colnames(RW1))
```

## Automatic creation of weights

Some ILSA information are already included in `ILSAstats`, so if our data corresponds to any of the included ones, we can create the replicate weights easier, using `repcreateILSA()`. 
To check which ILSA information is included we can use `ILSAinfo$weights`:

```{r}
ILSAinfo$weights
```

So this information already contains the name of the method, the jackknife zones, the jackknife replications, and the total weights from a total of `r nrow(ILSAinfo$weights)` cycles.


So, for our TIMSS 1999 case, we would need to specify the name of the study, the cycle and the data:
```{r}
RW2 <- repcreateILSA(study = "TIMSS",year = 1999,df = timss99)

```

This will produce the same results as `RW1`:

```{r}
identical(RW1,RW2)
```