---
title: "Calculation of additional parameters of interest"
author: "Umut Caglar, Claus O. Wilke"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Calculation of additional parameters of interest}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
  
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```
  
After we have successfully fitted either a sigmoidal or double-sigmoidal model to input data, we may want to extract additional information of interest about the fitted curves, such as the midpoint of the curve and the slope at the midpoint. 
This information can be calculated with the function `parameterCalculation()`. 
It is called automatically by the top-level interface `fitAndCategorize()`, but it needs to be called manually if we fit curves with `multipleFitFunction()`.
The default functions assume that the lower asymptote, $h_0$, (when x is at negative infinity) is zero.
If the data are better fit using a model that estimates the lower asymptote, `parameterCalculation_h0()` and `multipleFitFunction_h0()` functions can be used.
  

```{r install packages, echo=FALSE, warning=FALSE, results='hide', message=FALSE}

###*****************************
# INITIAL COMMANDS TO RESET THE SYSTEM
rm(list = ls())
if (is.integer(dev.list())){dev.off()}
cat("\014")
seedNo=14159
set.seed(seedNo)
###*****************************

###*****************************
require("sicegar")
require("dplyr")
require("ggplot2")
###*****************************
```


```{r generate data for sigmoidal, echo=FALSE, warning=FALSE, results='hide', message=FALSE}
time=seq(3,24,0.5)

#simulate intensity data and add noise
noise_parameter=0.1
intensity_noise=stats::runif(n = length(time),min = 0,max = 1)*noise_parameter
intensity=sicegar::sigmoidalFitFormula(time, maximum=4, slope=1, midPoint=8)
intensity=intensity+intensity_noise

dataInputSigmoidal=data.frame(time, intensity)
```


```{r generate data for double - sigmoidal, echo=FALSE, warning=FALSE, results='hide', message=FALSE}
noise_parameter=0.2
intensity_noise=runif(n = length(time),min = 0,max = 1)*noise_parameter
intensity=sicegar::doublesigmoidalFitFormula(time,
                                    finalAsymptoteIntensityRatio=.3,
                                    maximum=4,
                                    slope1=1,
                                    midPoint1Param=7,
                                    slope2=1,
                                    midPointDistanceParam=8)
intensity=intensity+intensity_noise

dataInputDoubleSigmoidal=data.frame(time, intensity)
```


```{r normalize_data, echo=FALSE, warning=FALSE, results='hide', message=FALSE}
normalizedSigmoidalInput = sicegar::normalizeData(dataInput = dataInputSigmoidal, 
                                         dataInputName = "sigmoidalSample")

normalizedDoubleSigmoidalInput = sicegar::normalizeData(dataInput = dataInputDoubleSigmoidal, 
                                         dataInputName = "doubleSigmoidalSample")
```


Assume we have fitted a sigmoidal or double-sigmoidal model using `sicegar::multipleFitFunction()`:

```{r sigmoidal and double sigmoidal fit to datasets}
sigmoidalModel <- multipleFitFunction(dataInput=normalizedSigmoidalInput,
                                   model="sigmoidal")
```

```{r echo=FALSE, warning=FALSE, results='hide', message=FALSE}
doubleSigmoidalModel <- multipleFitFunction(dataInput=normalizedDoubleSigmoidalInput,
                                         model="doublesigmoidal")
```

We can then apply `sicegar::parameterCalculation()` to the generated model objects:
```{r generate additional parameters for sigmoidalModel and doubleSigmoidalModel}
sigmoidalModelAugmented <- parameterCalculation(sigmoidalModel)
```

```{r echo=FALSE, warning=FALSE, results='hide', message=FALSE}
doubleSigmoidalModelAugmented <- parameterCalculation(doubleSigmoidalModel)
```

Compare the contents of the fitted model before and after parameter calculation:

```{r generate additional parameters for sigmoidalModel}
# before parameter calculation 
t(sigmoidalModel)
# after parameter calculation 
t(sigmoidalModelAugmented)
```

We see that the variable `additionalParameters` has switched from `FALSE` to `TRUE`, and further, there are numerous additional quantities listed now, starting with `maximum_x`. Below, we describe the meaning of these additional parameters for the sigmoidal and double-sigmoidal models.

## Additional parameters for the sigmoidal model

The following parameters are calculated by `parameterCalculation()` for the sigmoidal model.

1\. Maximum of the fitted curve.

* `maximum_x`: The x value (i.e., time) at which the fitted curve reaches its maximum value. Because of the nature of the sigmoidal function this value is always equal to infinity, so the output is always `NA` for the sigmoidal model.
* `maximum_y`: The maximum intensity the fitted curve reaches at infinity. The value is equal to `maximum_Estimate`.

2\. Midpoint of the fitted curve. This is the point where the slope is maximal and the intensity half of the maximum intensity.

* `midPoint_x`: The x value (i.e., time) at which the fitted curve reaches the midpoint. The value is equal to `midPoint_Estimate`.
* `midPoint_y`: The intensity at the midpoint. The value is equal to `maximum_y / 2`.

3\. Slope of the fitted curve. 

* `slope`: The maximum slope of the fitted curve. This is the slope at the midpoint. The value is equal to `slopeParam_Estimate * maximum_y / 4`.

4\. Parameters related to the slope tangent, which is the tangent line that passes through the midpoint of the curve.

* `incrementTime`: The time interval from when the slope tangent intersects with the horizontal line defined by `y = 0` until it intersects with the horizontal line defined by `y = maximum_y`. Its value is equal to `maximum_y / slope`.

* `startPoint_x`: The x value (i.e., time) of the start point. The start point is defined as the point where the slope tangent intersects with `y = 0`. It approximately represents the moment in time when the intensity signal first appears. Its value is equal to `midPoint_x - (incrementTime/2)`.

* `startPoint_y`: The intensity of the start point. Equals to zero by definition.

* `reachMaximum_x`:  The x value (i.e., time) of the reach maximum point. The reach maximum point is defined as the point where the slope tangent intersects with `y = maximum_y`. It approximately represents the moment in time when the intensity signal reaches its maximum. Its value is equal to `midPoint_x + (incrementTime/2)`.

* `reachMaximum_y`: The intensity of reach maximum point. Equals to `maximum_y` by definition.


## Additional parameters for the double-sigmoidal model

```{r echo=FALSE, warning=FALSE, results='hide', message=FALSE}
# Parameters for double sigmoidal model
print(t(doubleSigmoidalModel))
```

1\. Maximum of the fitted curve.

* `maximum_x`: The x value (i.e., time) at which the fitted curve reaches its maximum value.  
* `maximum_y`: The maximum intensity the fitted curve reaches at infinity. The value is equal to `maximum_Estimate`.  

2\. Final asymptote intensity of the fitted model

* `finalAsymptoteIntensity`: The intensity the fitted curve reaches asymptotically at infinite time. The value is equal to `finalAsymptoteIntensityRatio_Estimate * maximum_y`.

3\. First midpoint of the fitted curve. This is the point where the intensity first reaches half of its maximum.

* `midPoint1_x`: The x value (i.e., time) at which the fitted curve reaches the first midpoint. The value is calculated numerically and is different from `midPoint1Param_Estimate`.
* `midPoint1_y`: The intensity at the first midpoint. The value is equal to `maximum_y / 2`.

4\. Second midpoint of the fitted curve. This is the point at which the intensity decreases halfway from its maximum to its final asymptotic value.

* `midPoint2_x`: The x value (i.e., time) at which the fitted curve reaches the second midpoint. The value is calculated numerically and is different from `midPoint2Param_Estimate`.
* `midPoint2_y`: The intensity at the second midpoint. The value is equal to `finalAsymptoteIntensity + (maximum_y - finalAsymptoteIntensity) / 2`.

5\. Slopes of the fitted curve. 

* `slope1`: The slope of the fitted curve at the first midpoint. The value is calculated numerically and is different from `slope1Param_Estimate`.
* `slope2`: The slope of the fitted model at the second midpoint. The value is calculated numerically and is different from `slope2Param_Estimate`.

6\. Parameters related to the first slope tangent, which is the tangent line that passes through the first midpoint of the curve.

* `incrementTime`: The time interval from when the first slope tangent intersects with the horizontal line defined by `y = 0` until it intersects with the horizontal line defined by `y = maximum_y`. Its value is equal to `maximum_y / slope`.
* `startPoint_x`: The x value (i.e., time) of the start point. The start point is defined as the point where the first slope tangent intersects with `y = 0`. It approximately represents the moment in time when the intensity signal first appears. Its value is equal to `midPoint1_x - (incrementTime/2)`.
* `startPoint_y`: The intensity of the start point. Equals to zero by definition.
* `reachMaximum_x`:  The x value (i.e., time) of the reach maximum point. The reach maximum point is defined as the point where the fist slope tangent intersects with `y = maximum_y`. It approximately represents the moment in time when the intensity signal reaches its maximum. Its value is equal to `midPoint_x + (incrementTime/2)`.
* `reachMaximum_y`: The intensity of the reach maximum point. Equals to `maximum_y` by definition.

7\. Parameters related to the second slope tangent, which is the tangent line that passes through the second midpoint of the curve.

* `decrementTime`: The time interval from when the second slope tangent intersects with the horizontal line defined by `y = maximum_y` until it intersects with the horizontal line defined by `y = finalAsymptoteIntensity`. Its value is equal to `- (maximum_y -finalAsymptoteIntensity)/ slope2`.
* `startDeclinePoint_x`: The x value (i.e., time) of the start decline point. The start decline point is defined as the point where the second slope tangent intersects with `y = maximum_y`. It approximately represents the moment in time when the intensity signal starts to drop from its maximum value. The value is equal to `midPoint2_x - (decrementTime/2)`.
* `startDeclinePoint_y`: The intensity of the start decline point. Equals to `maximum_y` by definition.
* `endDeclinePoint_x`: The x value (i.e., time) of the end decline point. The end decline point is defined as the point where the second slope tangent intersects with `y = finalAsymptoteIntensity`. It  approximately represents the moment in time when the intensity signal reaches its final asymptotic intensity. The value is equal to `midPoint2_x + (decrementTime/2)`.
* `endDeclinePoint_y`: The intensity of the end decline point. Equals to `finalAsymptoteIntensity` by definition.

