---
title: "Cardinal parameter models"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Cardinal parameter models}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5
)
```

```{r setup}
library(predmicror)
```

Cardinal parameter models describe the effect of environmental factors on a microbial growth response.

In `predmicror`, the cardinal fitting wrapper expects the response to be the square root of the growth rate, usually in a column named `sqrtGR`. This vignette shows how to fit cardinal models for temperature, pH, water activity, and inhibitory compounds.

## Available cardinal models

```{r}
predmicror_models("cardinal")
```

## Robust fitting helper

Nonlinear fitting can depend on starting values. The helper below keeps the vignette robust by reporting fitting problems without stopping the document build.

```{r}
safe_fit <- function(expr) {
  withCallingHandlers(
    tryCatch(
      expr,
      error = function(e) {
        message("Model fit failed: ", conditionMessage(e))
        NULL
      }
    ),
    warning = function(w) {
      message("Model fit warning: ", conditionMessage(w))
      invokeRestart("muffleWarning")
    }
  )
}
```

## Temperature model

The `salmonella` dataset contains temperature and growth-rate data for *Salmonella typhimurium* on cooked chicken.

```{r}
data(salmonella)
head(salmonella)
```

```{r}
temp_fit <- safe_fit(
  fit_cardinal(
    salmonella,
    model = "CMTI",
    x = "Temp",
    response = "sqrtGR",
    start = list(Tmax = 42, Tmin = 1, MUopt = 1, Topt = 37)
  )
)

temp_fit
```

```{r}
if (!is.null(temp_fit)) {
  fit_metrics(temp_fit)
}
```

```{r, fig.alt="Observed and fitted square-root growth rates for the cardinal temperature model."}
if (!is.null(temp_fit)) {
  grid <- data.frame(
    Temp = seq(min(salmonella$Temp), max(salmonella$Temp), length.out = 100)
  )
  pred <- predmicror_augment(temp_fit, newdata = grid)

  plot(
    sqrtGR ~ Temp,
    data = salmonella,
    xlab = "Temperature",
    ylab = "Square root growth rate",
    pch = 19
  )
  if (".fitted" %in% names(pred)) {
    lines(pred$Temp, pred[[".fitted"]], lwd = 2)
  }
}
```

## pH model

```{r}
data(ph)
head(ph)
```

```{r}
ph_fit <- safe_fit(
  fit_cardinal(
    ph,
    model = "CMPH",
    x = "pH",
    response = "sqrtGR",
    start = list(pHmax = 9.5, pHmin = 3.5, MUopt = 1, pHopt = 6.8)
  )
)

ph_fit
```

```{r}
if (!is.null(ph_fit)) {
  fit_metrics(ph_fit)
}
```

```{r, fig.alt="Observed and fitted square-root growth rates for the cardinal pH model."}
if (!is.null(ph_fit)) {
  grid <- data.frame(pH = seq(min(ph$pH), max(ph$pH), length.out = 100))
  pred <- predmicror_augment(ph_fit, newdata = grid)

  plot(
    sqrtGR ~ pH,
    data = ph,
    xlab = "pH",
    ylab = "Square root growth rate",
    pch = 19
  )
  if (".fitted" %in% names(pred)) {
    lines(pred$pH, pred[[".fitted"]], lwd = 2)
  }
}
```

## Water activity model

```{r}
data(aw)
head(aw)
```

```{r}
aw_fit <- safe_fit(
  fit_cardinal(
    aw,
    model = "CMAW",
    x = "aw",
    response = "sqrtGR",
    start = list(AWmin = 0.90, MUopt = 1, AWopt = 0.995)
  )
)

aw_fit
```

```{r}
if (!is.null(aw_fit)) {
  fit_metrics(aw_fit)
}
```

```{r, fig.alt="Observed and fitted square-root growth rates for the cardinal water activity model."}
if (!is.null(aw_fit)) {
  grid <- data.frame(aw = seq(min(aw$aw), max(aw$aw), length.out = 100))
  pred <- predmicror_augment(aw_fit, newdata = grid)

  plot(
    sqrtGR ~ aw,
    data = aw,
    xlab = "Water activity",
    ylab = "Square root growth rate",
    pch = 19
  )
  if (".fitted" %in% names(pred)) {
    lines(pred$aw, pred[[".fitted"]], lwd = 2)
  }
}
```

## Inhibitor model

```{r}
data(inh)
head(inh)
```

```{r}
inh_fit <- safe_fit(
  fit_cardinal(
    inh,
    model = "CMInh",
    x = "Conce",
    response = "sqrtGR",
    start = list(MIC = max(inh$Conce) * 1.2, MUopt = 1, alpha = 1)
  )
)

inh_fit
```

```{r}
if (!is.null(inh_fit)) {
  fit_metrics(inh_fit)
}
```

```{r, fig.alt="Observed and fitted square-root growth rates for the cardinal inhibitor model."}
if (!is.null(inh_fit)) {
  grid <- data.frame(Conce = seq(min(inh$Conce), max(inh$Conce), length.out = 100))
  pred <- predmicror_augment(inh_fit, newdata = grid)

  plot(
    sqrtGR ~ Conce,
    data = inh,
    xlab = "Inhibitor concentration",
    ylab = "Square root growth rate",
    pch = 19
  )
  if (".fitted" %in% names(pred)) {
    lines(pred$Conce, pred[[".fitted"]], lwd = 2)
  }
}
```

## Collecting diagnostics

The fitted models above describe different environmental factors and should not be ranked against each other using information criteria. Still, collecting their metrics in one table is useful for reporting and quality control.

```{r}
cardinal_fits <- Filter(Negate(is.null), list(
  temperature = temp_fit,
  pH = ph_fit,
  water_activity = aw_fit,
  inhibitor = inh_fit
))

if (length(cardinal_fits) > 0L) {
  diagnostics <- do.call(
    rbind,
    Map(function(name, fit) {
      out <- fit_metrics(fit)
      out$workflow <- name
      out
    }, names(cardinal_fits), cardinal_fits)
  )
  rownames(diagnostics) <- NULL
  diagnostics
}
```

## Practical notes

Cardinal model parameters should be interpreted in the environmental units of the input data. For example, `Tmin`, `Topt`, and `Tmax` are in the same units as `Temp`, while `AWmin` and `AWopt` are in water-activity units.

Always check that the response scale is `sqrtGR` before fitting.