---
title: "TPMplt package tutorial"
author: "Chen Zhang"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{TPMplt-vignette}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Main functions

TPMplt is a tool-kit for building and visualizing the dynmaic materials model (DMM), suggested by [Prasad and Gegel](https://link.springer.com/article/10.1007/BF02664902). It provides an easy approach to calculate constructive functions and other related material constants based on a given strain condiiton. 2D and 3D processing-maps with temperature as its x axis, while logarithm strain rate as its y axis are also available.

## Input data

Valid data for TPMplt strictly obey the management logic in [VBTree package](https://CRAN.R-project.org/package=VBTree). Additionally, factors for temperature (celsius) and strain rates should be written in the format of pure numeric. All different variables are desired to be connected using "-" symbol. For example, if there's a strain data collected in the conditions of 900 celsius, $10^{-3}$ strain rate, "0.001-Strain-900" is one of available column names for this data, rather than "10e-3_Strain_T900C", "SR0.001-Strain-1173K" or such like. If your data contains some unnecessary patterns, a certain degree of data cleaning for column names is required.

The following codes partially display a typical valid data for TPMplt:

```{r}
library(TPMplt)
head(TPMdata[,1:3])

```

Users can apply any applicable tools to make the summary table for TPMplt, with the format as above-showed.

Besides, it is common to obtain multiple exported files based on different experiments. TPMplt affords two functions to automatically generate a summary table from multiple exported files. For details, please check the R documents for ```API4TMZ``` and ```TMZdatainput```.

## Conceptual knowledge about VBTree data frame

It is necessary to build the conceptions for layers and levels in layer for variables, defined by [VBTree package](https://CRAN.R-project.org/package=VBTree). For example, run the following codes to check all column names in the demo dataset in TPMplt pacakge:

```{r}
colnames(TPMdata)
```

As we can see, all column names are arranged by the style of "(Strain&Stress)-(Temperature)-(Strain Rate)-(Other)". In this case, we attribute the variable the concept 'layer', and the order of values in specified layer the 'level'. The layer for temperature is 2, while the layer for strain rate is 3; the temperature of 1000 is at level 3 in layer 2.

The function ```epsExtract``` is capable to export a strain rate-temperature table by specifying ```eps``` as the selected strain condition. However, ```lyT``` and ```lySR```, the two necessary arguments corresponding to layers for temperature and strain rate respectively, require correct assignment as well.

Executinge the following codes:

```{r}
require(VBTree)
dl2vbt(chrvec2dl(colnames(TPMdata)))
```

The complete structure for all variables is showed. As the result showed above, there're 7 temperatures and 4 strain rates in our summary table, therefore the numbers of level for temperature and strain rate are 7 and 4 respectively. Based on all introduced knowledge, we can easily find that all factors will be corresponded with a unique identity with the format as (layer, level). For example, we can define the factor "950" is located in layer 2, level 2.

## Auto plots for stress-strain curves

```SSplots``` is automatic completion for stress-strain curve plots, using [VBTree package](https://CRAN.R-project.org/package=VBTree) group strategy. It help researchers check the profiles of their experimental data conveniently. The argument ```grpby``` determines attribute to be grouped for each plot. As an instance, stress-strain curves grouped by strain rates, separated by temperature condition in each individual plot can be achieved using the code ```SSplots(TPMdata, 3, mfrow=c(3, 3))```. The layer for strain rate is 3, therefore the 2nd argument ```grpby``` is 3 (7 figures totally, therefore ```mfrow``` use a 3*3 division to ensure correct display):

![](figs/Img1.png)

Grouped by temperature is also available, by running ```SSplots(TPMdata, 2, mfrow=c(2, 2))```, four figures will be exported as:


![](figs/Img2.png)

However, multiple plots export using ```graphics``` is very sensitive to the Plots pane's in RStudio. Before plotting, please make sure the area of this pane is large enough to include all your output.

## Applying Kalman smoothing

Sometimes, curves of flow stress as function of flow strain might be of high vibration, therefore the fitting process for all data is necessary. However, in most circumstances, raw stress-strain curves always present too complicated appreance to be fitted by a single linear model. The function ```KFprocess()``` in this package is designed to solve this problem. From the aforementioned raw stress-strain curves generated by ```SSplots(TPMdata, 2, mfrow=c(2, 2))```, it is not difficult to find for most curves, vibration starts from where the plastic deformation occurs; Using the ```dV``` as 0.3 and ```dW``` as 0.006, the main paths of flow stress vs. flow strain curves can successfully obtained:

```{r, fig.show='hide'}
Fitted_data <- KFprocess(TPMdata, dV = 0.3, dW = 0.006)
SSplots(Fitted_data, 2, mfrow=c(2, 2))
```


<div align=center>![](figs/Img3.png)

Compared to the raw curves, we can find the fitted curves keep the most appearance with less vibrations or noises. For desired output, you may try different combinations of arguments ```dV``` and ```dW```. Help documentation and references might be helpful. The calculation of adiabatic heating correction will utilize the integral of those curves, the smoothing by Kalman will make a more robust output rationally.

## Adiabatic heating correction

Adiabatic heating correction can be implemented after smoothing if it is necessary. We can use the function ```TCorrect()``` to output the adiabatic heating correction on data by declaring some necessary material contants. Take the conventional steel as the example, the heat capacity constant and material density are 502.416 J/(kJ\*K) and 7.8 g\*cm^(-3). The corrected data of flow strain ranged from 0 to 0.9 with 0.02 increase in each step would be:

```{r fig.show='hide'}
TCorrect_data <- TCorrect(TPMdata, 2, 3, 0.9, 7.8, 502.416, seq(0, 0.9, 0.02))
SSplots(TCorrect_data, 2, mfrow=c(2, 2))
```

<div align=center>![](figs/Img4.png)

The 2nd and 3rd argument in ```TCorrect()``` are integers to specify the layer for temperatures and strain rates.

After temperature correction, it is noted that flow stress increase significantly in low temperature, high strain rate, the two conditions which is experientially corresponding to our common sense that working hardening effect will be even obvious.

## Extraction based on given strain

In previous content, we understand the column name structure of the ```TPMdata``` dataset. Therefore the two layers for temperature and strain rate will be 2 and 3 respectively. If we want the strain rate-temperature table in condition of 0.7 flow strain, by executing the following codes the result can be returned automatically:

```{r}
epstable <- epsExtract(TCorrect_data, eps = 0.7, lyT = 2, lySR = 3)
epstable
```

Additionally, for correct exporting, the number of levels for numeric variables must be 2, for 'Strain' and 'Stress' respectively. In most cases, the package has a internal function to detect the locations for 'Strain' and 'Stress'. Nevertheless, people might have different nomenclature for 'Strain' and 'Stress' in their summary tables. If so, the argument ```manual``` will be helpful to manually assign the locations for 'Strain' and 'Stress', to ensure the correct output (see help documentation for the function ```epsExtract```).

## Automatic calculation

On the basis of dynamic materials modeling (DMM), constructive function and all material constants can be calculated from a certain strain rate-temperature table. The function ```DMMprocess``` includes all calculation steps for DMM processing. Call it on our previous result (strain rate-temperature table through specified value of strain), the complete output can be observed as following:

```{r}
DMM <- DMMprocess(epstable)
DMM
```

If the constructive function is also the thing we concerned, set the argument ```ConsFunc``` in ```DMMprocess``` as ```TRUE```:

```{r}
DMM <- DMMprocess(epstable, ConsFunc = TRUE)
```

Additionally, if the argument ```InteractMode``` is TRUE, all computation process and corresponding fitting figures can be output step by step. There shows some results in following figures:

![](figs/Img5.png)

![](figs/Img6.png)

![](figs/Img7.png)

![](figs/Img8.png)

![](figs/Img9.png)

![](figs/Img10.png)

![](figs/Img11.png)

All workflow control will be prompted in the console, something like:

![](figs/Img12.png)

## Preparation for visualization

As we can see, the "etatable" and "xitable" in tablelist are two constitutive parts for building processing-map. The former is for power dissipation efficiency factor eta, and the later is for rheological stability coefficient xi. However, since the values in both are discrete, regression process for these tables is necessary.

Support vector regression ([SVR](https://link.springer.com/article/10.1023/B:STCO.0000035301.49549.88)) is suggested in this package. The function ```SVRModel``` will return a regression result which can be utilized by following functions for plots.

The following demonstration save the returned result into the vairable "PLTbd", for the meaning of "Plots builder".

```{r}
PLTbd <- SVRModel(DMM)
```

## 2D processing map visualization

Function ```TPM2dplt``` can generate a thermal processing map from regression result easily. Following codes demonstrates the processing map from "PLTbd" with default settings:

```{r, fig.show='hold', fig.height=4, fig.width=6}
TPM2dplt(PLTbd)
```

In this processing map plot, customarily the power dissipation efficiency factor eta is denoted by contour with gradient blue, while the rheological stability coefficient xi is represented by a gradient colours from blue (low) to red (high). Annotation in top-left show the strain condition for current processing map.

Locations for annotation, gradient colors for rheological stability coefficient xi is customizable in ```TPM2dplt``` function. Refer the documentation for details.

## 3D processing map visualization

Function ```TPM3dplt``` can build a thermal processing results as similar as ```TPM2dplt``` did. The difference is, eta and xi will be separately plotted.

By running the following code, we can easily obtain the results as shown in the next figure.

```{r}
TPM3dplt(PLTbd)
```

![](figs/Img13.png)

These two 3d surfaces are generated through the rgl package, therefore it will be very convenient to utilize 3d rotation on our plots for further analysis in details.

Especially, the xi plots is coupled with a specific plane, z=0, in order to make divisions for the stable and unstable regions (doesn't included in demo figure). If the prediction for xi contained certain negative values, this plan will be visible in 3d surface plot.