03_InputFiles.qmd

# jjm Input Files
```{css, echo=F}
pre {
  overflow-x: scroll
}

pre code {
  white-space: pre;
}
```

```{r setup, include=FALSE}
knitr::opts_knit$set(root.dir=here::here())
knitr::opts_chunk$set(warning=F, message=F, eval=F)
```

There are three files required to run the `jjm` assessment. You will need:

1. An executable file
1. A `.ctl` file
1. A `.dat` file

These files are typically stored in the `jjm/assessment` folder on the Github site.

# Executable File
In general computing, an executable is a programme generated by machine code instructions. The programme can take user-specified input, processes it, and produces output. In the context of the jack mackerel assessment, the model equations are coded up in a `.TPL` file and compiled into a single executable. The executable estimates the best parameters for the model and the data by minimizing a pre-specified objective (likelihood) function.

- Specific to operating systems (`jjms.exe` for Windows, `jjms` for Mac and Linux)

- Stored on the Teams [site](https://southpacificrfmo.sharepoint.com/:f:/r/sites/SPRFMOSC10/Shared%20Documents/Jack%20Mackerel/JJM%20Workshop/src?csf=1&web=1&e=FSAJ65)

    - These are not stored on the Github site for security reasons- many computer viruses are sent around as executable files.
    - Can / should we find a better place to store it?
    - Right now just Windows and Mac executables - does anyone need Linux?
    - ***If you haven't already compiled it, please copy/paste it in the `jjm/src` folder***

- Source code is found in `jjm/src/jjms.TPL`

    - The `jjm` file is deprecated
    - You can use this file to see exactly how the input files are being used in the assessment model.

- Compiled using AD Model Builder ([ADMB](http://www.admb-project.org/))

    - Instructions for compilation can be found in the [PreWorkshop document](https://southpacificrfmo.sharepoint.com/:u:/r/sites/SPRFMOSC10/Shared%20Documents/Jack%20Mackerel/JJM%20Workshop/Tutorials/PreWorkshop.html?csf=1&web=1&e=6vIvxK)

- Comments are made using the `//`

- An important thing to note for the input files is that the executable ignores line breaks. The files are read in linearly, so it doesn't matter (to the executable) if values are separated by a space or by a line break. We often use the line breaks to make the files more readable to the human, but that's not how the software reads it.

As such,

```{r}
#Steepness 
0.65 0.65 0.65
300 300 300
-6 -6 -6
```

is read as

```{r}
#Steepness 
0.65 0.65 0.65 300 300 300 -6 -6 -6
```


# Control File

- Contains the settings for the model

- Files used to run the most recent assessment can be found in `jjm/assessment/config`, or [here](https://github.com/SPRFMO/jjm/tree/master/assessment/config) on the Github site.

- Comments are made using `#`


## Things to Note
- The first line of the control file defines the name of the data file to be used.

    - With this setting, you can use several different control files with the same data file.

```{r}
#dataFile
0.00.dat
#modelName 
h2_0.00
```

- Selectivity sharing vector defines the selectivity patterns of each fleet (fishery and survey).

```{r}
# From the TPL file
# // Matrix of selectivity mappings--row 1 is index of stock
# //  row 2 is type (1=fishery, 2=index) and row 3 is index within that type
# //  e.g., the following for 2 fisheries and 4 indices means that index 3 uses fishery 1 selectivities,
# //         the other fisheries and indices use their own parameterization

# Selectivity sharing vector (number_fisheries + number_surveys)  
#Fsh_1 Fsh_2 Fsh_3 Fsh_4 Srv_1 Srv_2 Srv_3 Srv_4 Srv_5 Srv_6 Srv_7
#N_Chile_Fsh CS_Chile_Fsh FarNorth_Fsh Offshore_Trawl_Fsh Chile_AcousCS Chile_AcousN Chilean_CPUE DEPM Peru_Acoustic Peru_CPUE Offshore_CPUE #  
# 2 3 4 1 2 3 4 5 6 7
1 1 1 1 1 1 1 1 1 1 1
1 1 1 1 2 2 1 2 1 1 1
1 2 3 4 1 2 2 4 3 3 4

```

- For each parameter, we define a prior, a coefficient of variance (CV), and a phase of estimation.

    - Negative phases indicate that the parameter is not estimated in the model

```{r}
#Steepness 
0.65 
300 
-6

#catchability 
1.143881847 0.029045376 0.000159487 0.519171913 0.002284038 0.007987171 0.033884372
12  12  12  12  12  12  12
3  5  3  3  3  4  4  
```


- User defines the years of data used to estimate the stock-recruitment relationship

    - Two types of stock-recruit relationships available: Ricker (Option 1) and Beverton-Holt (Option 2)

- The retro input defines how many years of data to "peel" off for the retrospective analysis


```{r}
#Number of regimes (by stock)
1
#Sr_type 
2  
#AgeError 
0  
#Retro 
0  
#Recruitment sharing matrix (number_stocks, number_regimes)
1
```


- Selectivity patterns are defined per fleet

```{r}
# Fishery 1 N Chile  
1  #selectivity type
9  #n_sel_ages
2  #phase sel
1  #curvature penalty
1  #Dome-shape penalty
# Years of selectivity change Fishery 1 N Chile  
36                                                          
1984  1985  1986  1987  1988  1989  1990  1991  1992  1993  1994  1995  1996  1997  1998  1999  2000  2001  2002  2003  2004  2005  2006  2007  2008  2009  2010  2011  2012  2013    2014    2015    2016  2017  2018  2019
0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5 0.5
# Initial values for coefficitients at each change (one for every change plus 1)  
# 2 3 4 5 6 7 8 9 10 11 12  
0.2 0.7 1 1 1 1 1 1 1 1 1 1  

```
 
# Data File

- Contains processed data for the assessment

- Files used to run the most recent assessment can be found in `jjm/assessment/input`, or [here](https://github.com/SPRFMO/jjm/tree/master/assessment/input) on the Github site.

- An annotated accompanying Excel file can be found in `jjm/assessment/data/JM Data files for SC09.xlsx`, or [here](https://github.com/SPRFMO/jjm/blob/master/assessment/data/JM%20Data%20files%20for%20SC09.xlsx).

- Comments are made using `#`

## Things to Note

- The years define how many years are in the model.

```{r}
#years 
1970 
2021 
#ages 
1 
12
```

- Fishery data comes first, and each fishery data component is denoted with an `F`. Index data are denoted with an `I`

- Many of the `num` components define the length of the subsequent data vector

- Fishery catch data (`Fcaton` and `Fcatonerr`) have to have a value in place for every year of the model for every fleet

```{r}
#Fnum 
4 
#Fnames 
N_Chile%SC_Chile_PS%FarNorth%Offshore_Trawl 
#Fcaton 
101.69 143.45 64.46 83.2 164.76 207.33 257.7 226.23 398.41 344.05 288.81 474.82 789.91 301.93 727 511.15 55.21 313.31 325.46 338.6 323.09 346.25 304.24 379.47 222.25 230.18 278.44 104.2 30.27 55.65 118.73 248.1 108.73 143.28 158.66 165.63 155.26 172.701 167.258 134.022 169.012 30.825 13.256 16.361 18.219 34.886 24.657 35.002 11.551 11.875 44.155 61.359 
10.31 14.99 22.55 38.39 28.75 53.88 84.57 114.57 188.27 253.46 273.45 586.09 704.77 563.34 699.3 945.84 1129.11 1456.73 1812.79 2051.52 2148.79 2674.27 2907.82 2856.78 3819.19 4174.02 3604.89 2812.87 1582.64 1164.04 1115.57 1401.84 1410.27 1278.02 1292.94 1264.81 1224.69 1130.083 728.85 700.905 295.796 216.47 214.204 214.999 254.295 250.327 295.16 311.863 415.149 432.447 517.665 567.267 
4.71 9.19 18.78 42.78 129.21 37.9 54.15 504.99 386.79 333.81 414.3 445.64 143.72 110.69 200.67 114.62 51.03 46.3 244.23 316.25 370.82 213.45 111.68 133.35 233.35 550.99 495.52 680.05 412.85 203.75 303.7 857.74 154.82 217.73 187.37 80.66 277.57 255.36 169.537 76.629 22.172 326.394 187.396 80.586 74.532 22.447 15.088 8.867 57.163 135.784 140.116 129.3243 
0 0 5.5 0 0 0 0.04 2.27 51.29 370.29 339.8 438.12 733.2 894.3 1059.93 799.32 837.5 863.42 863.22 875.82 872.06 543.66 37.93 0 0 0 0 0 0 0.01 2.32 20.09 76.26 158.2 295.44 243.58 362.63 438.8306 406.9864 371.9176 239.593 60.89131 39.91786 41.177 63.652 86.672 54.163 49.113 42.46 51.439 4.739 55.309 
#Fcatonerr 
0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 
0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 
0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 
0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 0.05 
```

- Age composition data appear before length composition data

- Weight at age is required for every fleet in every year of the model

    - Historically, when the year is updated but not the weight-at-age data (e.g. if the weight at age for a particular fleet is unavailable at the time of the SC), the previous year's data are used.


# Reading and Writing Input Files in R

You can edit the files by hand, or within R. **If you're planning to use `jjmR` to read and edit input files, you'll have to start with a model that is already run.** An example could be last year's model.


The code here will update the name of the model from `1.00` to `1.01`, and write the new control and data files to the specified `ctlPath` and `datPath` directories respectively. We will look more closely at how to modify these input files in the next document.

```{r, eval=F}
library(jjmR)

# ?readJJM
# ?writeJJM

# Assuming we're in the jjm/assessment folder
# path = where control files are stored
# input = where data files are stored
# output = where model output files are stored; default is "results"

mod_current <- readJJM("h1_1.00", path = "config", input = "input")

mod_new <- mod_current

names(mod_new) <- mod_new[[1]]$control$modelName <- "h1_1.01"

mod_new[[1]]$control$dataFile <- paste0("h1_1.01",".dat")

# writeJJM(newmod,datPath="input",ctlPath="config")

```

Examining the `jjm` object can give you some insight as to what the object contains. The names of the data, control, and output objects generally correspond to the comments found in the `.dat`, `.ctl`, and `xx_R.rep` files respectively.

```{r, eval=F}
names(mod_new)

names(mod_new[[1]])

mod_new[[1]]$info

names(mod_new[[1]]$data)

names(mod_new[[1]]$control)

names(mod_new[[1]]$output)

names(mod_new[[1]]$output[[1]])
```

# Exercises
- How do the model settings for the single-stock (`h1`) and the two-stock (`h2`) models differ? You can look at `h1_1.00.ctl` and `h2_1.00.ctl`.

- How does the `readJJM` object differ for the two-stock model (`h2_1.00`)?