---
title: "R-based workflow for the AgeingError package"
author: "Ian Taylor"
date: "2026-06-16"
output:
  html_document: default
  word_document: default
vignette: >
  %\VignetteEngine{litedown::vignette}
  %\VignetteIndexEntry{R-based workflow for the AgeingError package}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

Note: for a general introduction to the AgeingError package and its model structure, see the [Getting Started vignette](getting_started.html).

## Helper functions in AgeingError

The AgeingError package provides a set of helper functions to create
input files and run the ageing error model from R.

The main helpers are:

- `write_data_file()`: write an input data file from an R data frame or tibble.
- `write_specs_file()`: write an input specifications file from user inputs for bias and sigma options.
- `write_files()`: convenience wrapper that calls `write_data_file()` and `write_specs_file()` together.
- `run()`: load the generated files (via `load_data()` and `load_specs()`) and run the TMB estimation.

Flowchart of workflow with separate calls to `write_data_file()` and `write_specs_file()`:
```{r, echo=FALSE}
DiagrammeR::mermaid('
graph TD
    D["Data frame or tibble"] --> W["write_data_file()"];
    U["User inputs for<br>bias and sigma options"] --> S["write_specs_file()"];
    W --> F["age_error.dat"];
    S --> G["age_error.spc"];
    F --> R["run()"];
    G --> R;
    R --> O["model output"];
')
```

Flowchart of workflow where writing the files are combined in a single call to `write_files()`:
```{r, echo=FALSE}
DiagrammeR::mermaid('
graph TD
    D["Data frame or tibble"] --> W["write_files()"];
    U["User inputs for<br>bias and sigma options"] --> W;
    W --> F["age_error.dat"];
    W --> G["age_error.spc"];
    F --> R["run()"];
    G --> R;
    R --> O["model output"];
')
```


## Writing the data file

`write_data_file()` creates the data file.
The main required input is an R data frame or tibble with columns for each reader and rows for each age reading combination (including a `count` column) or each individual fish (with repeats), in which case the `tally_repeats()` function will be called to add the `count` column.

Defaults will be calculated for `minage`, `maxage`, `refage`, `minusage`, and `plusage` if not provided, but these can be overridden by the user.

```{r, eval=FALSE}
library(AgeingError)

data_test <- data.frame(
  reader1 = c(7, 10, 7, 6, 6, 10, 7, 9, 8, 10, 10, 5, 6, 7, 9, 7, 7, 5, 8, 5),
  reader2 = c(8, 10, 7, 6, 6, 10, 7, 9, 8, 10, 10, 5, 6, 7, 9, 7, 7, NA, NA, NA),
  reader3 = c(7, 10, 7, 6, 6, 8, 7, 9, 8, 10, 10, 5, 6, 7, NA, NA, NA, 5, 8, 5)
)

write_data_file(
  dat = data_test,
  dir = tempdir(),
  file_name = "age_error.dat"
)
```


## Writing the specifications file

`write_specs_file()` creates the specifications file.
This file defines bias options and sigma options for each reader. See the 
[Getting Started vignette](getting_started.html) vignette for details on
the options. The options are provided as a vector of length equal to 
the number of readers. When called directly, this function also requires
the number of readers (`nreaders`) to be specified. If called via 
`write_files()`, the number of readers will be inferred from the data file.

```{r, eval=FALSE}
write_specs_file(
  dir = tempdir(),
  file_name = "age_error.spc",
  nreaders = 4,
  biasopt = c(0, 0, 0, 0),
  sigopt = c(1, -1, 7, 8)
)
```


The options that use cubic splines for uncertainty (`sigopt = 5` and 
`sigopt = 6`), the `knotages` argument must be a list of
numeric knot locations with one element per reader. 
Use `NA` for readers that do not need knots.

```{r, eval=FALSE}
write_specs_file(
  dir = tempdir(),
  file_name = "age_error.spc",
  nreaders = 4,
  sigopt = c(5, -1, 7, 8),
  knotages = list(c(0, 3, 5, 7, 9), NA, NA, NA)
)
```

Note that the R helper functions do not provide the user with control over the
parameter lines (low, high, or initial values). If the defaults need to be 
changed, they can be modified by editing the text files directly.

## Convenience wrapper: write_files()

`write_files()` is a convenience helper that writes both the data and specs
files in a single call.

```{r, eval=FALSE}
write_files(
  dat = data_test,
  dir = tempdir(),
  file_dat = "age_error.dat",
  file_specs = "age_error.spc",
  biasopt = c(0, 0, 0),
  sigopt = c(1, -1, 2)
)
```

This is equivalent to running `write_data_file()` and `write_specs_file()`
separately and is the recommended workflow for most users.

## Running the model

`run()` wraps the full process of loading the generated files and executing
AgeingError.

```{r, eval=FALSE}
write_files(dat = data_test, dir = tempdir())
out <- run(dir = tempdir())

# model results
out$model$par
out$output$ModelSelection
```

Note that `run()` calls `load_data()` and `load_specs()` internally, then 
passes the resulting objects to `DoApplyAgeError()` and `ProcessResults()`. 
These functions could be called directly as needed.