---
title: "Plot Standing-Katz low-pressure `lp` charts"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Plot Standing-Katz low-pressure charts}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Plot a Standing-Katz curve

```{r setup, include=F, error=T, message=F, warning=F}
knitr::opts_chunk$set(echo=T, comment=NA, error=T, warning=F, message = F, fig.align = 'center', results = "hold")
```


If we invoke the function `getStandingKatzCurve` without any parameters, by defult it will use a `Tpr=1.3` for the low-pressure set of `Tpr` curves and plot it.

```{r}
library(zFactor)
sk <- getStandingKatzCurve()
```


If we want to specify a Tpr curve:

```{r}
library(zFactor)
getStandingKatzCurve(tpr = 1.05, toSave = FALSE, toView = FALSE)
```


Or for a couple of Tpr curves, we specify a vector with 2 or more components:
```{r}
library(zFactor)
tpr_vec <- c(1.05, 1.1)
result <- getStandingKatzCurve(tpr = tpr_vec, toSave = FALSE, toView = FALSE)
```


## A dataframe for each `Tpr` dataset
The returning object of `getStandingKatzCurve` is a list of dataframes, which contains a dataframe for each of the `Tpr` curves specified:

```{r}
class(result)      # class of the object `result` is a list of dataframes
names(result)      # name of each dataframe within the list
```

For `Tpr = 1.05`:
```{r}
library(tibble)
as_tibble(result[["1.05"]])
```

And, for `Tpr = 1.1`:
```{r}
as_tibble(result[["1.1"]])
```


## Plot all the `lp` Standing-Katz curves
Or we can plot all the `lp` Standing-Katz curves:

```{r}
# view all the `Tpr` SK individual charts
tpr_vec <- getStandingKatzTpr(pprRange = "lp")
result <- getStandingKatzCurve(tpr_vec, toSave = FALSE,  toView = FALSE)
```

### Changing the scale for all the plots
The plotting function in `getStandingKatzCurve` has a default value for the Y scale of 0.2 to 1.2, just to make the plot uniform. But you can change that. 

Let's say you don't like the `Tpr` curve at 1.7 (shown above), just change the `ylim ` parameter:

```{r}
getStandingKatzCurve(tpr = 1.7, toSave = FALSE, toView = FALSE, 
                     ylim = c(0.8, 1.1))
```


And here is the list of dataframes of the digitized points for the `lp` Standing-Katz curves:

```{r}
names(result)
```


## Getting only the SK data
We have this other simpler function that will return only the data without saving, plotting or viewing the object. It is called `getStandingKatzData`:

```{r}
library(zFactor)

tpr_vec <- c(1.05, 1.3, 1.5)
all_tpr2 <- getStandingKatzData(tpr_vec)

names(all_tpr2)
```

Similarly, to what we did with `getStandingKatzCurve`, we could extract a dataframe for any Tpr:

```{r}
library(tibble)
as_tibble(all_tpr2[["1.5"]])
```

## Plotting multiple `Tpr` curves
To be able to plot multiple Tpr curves in one figure we have to convert the multiple dataframes to a `tidy` dataset. We will take a look on two ways of doing this:

### The hard way
Following from the previous example, we have to create a tidy dataset from the list of dataframes.

Let's plot the curves:

```{r}
library(data.table)
library(ggplot2)

# join the dataframes with rbindlist adding an identifier column
all_tpr_df <- data.table::rbindlist(all_tpr2, idcol = TRUE)
colnames(all_tpr_df)[1] <- "Tpr"    # name the identifier as Tpr

ggplot(all_tpr_df, aes(x=Ppr, y=z, group=Tpr, color=Tpr)) + 
    geom_line() +
    geom_point()
```


### The one step way
Using this function `multiplotStandingKatz` you can achieve the same result:
```{r}
tpr_vec <- c(1.05, 1.3, 1.5)
multiplotStandingKatz(tpr_vec)
```


The dots are the **digitized** points of the Standing-Katz chart.


## All the `Tpr` curves of Standing-Katz chart
Using `lapply`, `getStandingKatzData` and `data.table::rbindlist`:

```{r}
library(zFactor)
library(ggplot2)
library(data.table)

tpr_vec <- c(1.05, 1.1, 1.2, 1.3, 1.5, 1.6, 1.7, 1.9, 2.0, 2.4, 2.6, 2.8, 3.0)
all_tpr2 <- (lapply(tpr_vec, function(x) getStandingKatzData(tpr = x)))
names(all_tpr2) <- tpr_vec

all_tpr_df <- data.table::rbindlist(all_tpr2, idcol = TRUE)
colnames(all_tpr_df)[1] <- "Tpr"

ggplot(all_tpr_df, aes(x=Ppr, y=z, group=Tpr, color=Tpr)) + 
    geom_line() +
    geom_point()
```


Or the one-liner:
```{r}
tpr_vec <- getStandingKatzTpr(pprRange = "lp")
multiplotStandingKatz(tpr_vec)
```


## Plotting the low-range Tpr
If you just prefer the low range `Tpr` curves:

```{r}
library(zFactor)
library(ggplot2)
library(data.table)

low_tpr_vec <- c(1.05, 1.1, 1.2, 1.3, 1.4)
low_tpr_li <- (lapply(low_tpr_vec, function(x) getStandingKatzData(tpr = x)))
names(low_tpr_li) <- low_tpr_vec

low_tpr_df <- data.table::rbindlist(low_tpr_li, idcol = TRUE)
colnames(low_tpr_df)[1] <- "Tpr"

ggplot(low_tpr_df, aes(x=Ppr, y=z, group=Tpr, color=Tpr)) + 
    geom_line() +
    geom_point()
```

With the one liner:

```{r}
low_tpr_vec <- c(1.05, 1.1, 1.2, 1.3, 1.4)
multiplotStandingKatz(low_tpr_vec)
```

## The medium-range `Tpr` curves

```{r}
library(zFactor)
library(ggplot2)
library(data.table)

med_tpr_vec <- c(1.5, 1.6, 1.7, 1.8, 1.9)
med_tpr_li <- (lapply(med_tpr_vec, function(x) getStandingKatzData(tpr = x)))
names(med_tpr_li) <- med_tpr_vec

med_tpr_df <- data.table::rbindlist(med_tpr_li, idcol = TRUE)
colnames(med_tpr_df)[1] <- "Tpr"

ggplot(med_tpr_df, aes(x=Ppr, y=z, group=Tpr, color=Tpr)) + 
    geom_line() +
    geom_point()
```

The one liner:

```{r}
med_tpr_vec <- c(1.5, 1.6, 1.7, 1.8, 1.9)
multiplotStandingKatz(low_tpr_vec)
```


## The high-range of `Tpr` curves
```{r}
library(zFactor)
library(ggplot2)
library(data.table)

hi_tpr_vec <- c(2.0, 2.4, 2.6, 2.8, 3.0)
hi_tpr_li <- (lapply(hi_tpr_vec, function(x) getStandingKatzData(tpr = x)))
names(hi_tpr_li) <- hi_tpr_vec

hi_tpr_df <- data.table::rbindlist(hi_tpr_li, idcol = TRUE)
colnames(hi_tpr_df)[1] <- "Tpr"

ggplot(hi_tpr_df, aes(x=Ppr, y=z, group=Tpr, color=Tpr)) + 
    geom_line() +
    geom_point()
```


```{r}
hi_tpr_vec <- c(2.0, 2.4, 2.6, 2.8, 3.0)
multiplotStandingKatz(hi_tpr_vec)
```

## How does the tidy dataframe look
By performing a summary of the tidy dataset we can learn a lot more of the data we are plotting:

* The number of observations or rows is 117
* The Ppr ranges from 0.3 to 8.005
* The z values go from 0.937 to 1.097. This is understandle since we are referring to the high side of the Tpr curves.
* From all the digitized points, only 1 out of 117 was digitized far from the 1/10 grid.

```{r}
library(tibble)
as_tibble(hi_tpr_df)
```



```{r}
summary(hi_tpr_df)
```


With this we are in a position to compare the original Standing-Katz chart against the most common compresssibility correlations.
