FLSAM.control.RdCreates an FLSAM.control that can be used to control an FLSAM assessment
FLSAM.control(stck, tun, default="full",sam.binary="missing")An FLStock object
An FLIndices object
Specifies how the control object should be populated. Default option is "full", which takes a reasonable first guess at a configuration. Any other value will populate all matrices with NA values.
Path and name of the SAM executable file to run
An FLSAM assessment requires three elements - an FLStock object, an FLIndices object and an FLSAM.control object. The FLSAM.control object contains the configuration options for the model, and is therefore key to the process. However, there are a great many configuration options and therefore setting up the control object is a relatively complex process. The purpose of the FLSAM.control function is to create a template (possibly containing sensible first guesses at a configuration) object that can then be populated by the user according to their wishes.
The key concept with the configuration of a SAM model is that some parameters are bound together, so that the model fits just a single parameter, but uses it in multiple places e.g. by using a single parameter for the catchabilites of ages 5-9 in a survey. We refer to this concept as "binding" the parameters together.
Bindings are expressed in a matrix format in the FLSAM.control object. The rows of the matrix correspond to the fleets, whilst the column correspond to the ages - it is important to remember that while all age-fleet combinations are represented here, not all are valid i.e. a fleet may not contain information on all ages. Bindings are specified with integers - the integers indicate which parameter should be used in the specific fleet-age context represented by that point in the matrix. Repeating a number means that all those fleet-age combinations with the same number will be fitted with just one parameter i.e. bound together. Parameters that are not to be fitted, or are turned off, are specified by setting the value to NA.
FLSAM.control can populate the template in two different ways, as indicated by the "default" argument. If default="full", a reasonable first guess at a configuration is supplied - this consists of linear catchability models for the surveys and a fixed selectivity pattern in the fishery. Alternatively, if "default" is set to any other value, all values are set to NA and therefore turned "off".
Earlier versions of FLSAM contained the executable (binary) file within the package distribution. However, this version is designed to interface with customised versions of the sam model, which can be modified and compiled locally. The sam.binary slot in the FLSAM.control object can be used to specify the location of this executable file. If the file is not specified, FLSAM reverts to the versions stored within the package - however, in the future, these binaries may be removed.
Returns an FLSAM.control object with the following slots
A text field giving the name of the object
A text field describing the object
A named vector containg key information about range covered by the object
min - the youngest age modelled
max - the oldest age modelled (can be a plus group)
plusgroup - the agegroup considered as a plusgroup (if any)
minyear - the first year modelled
maxyear - the last year modelled
minfbar - the younger limit of ages used in calcualting the average fishing mortality, fbar
maxfbar - the older limit of ages used in calcualting the average fishing mortality, fbar
A named vector indicating the type of data that it represents. 0 = catch. 1=<I don't know! "con" something>. 2=Numbers at age survey. 3. SSB index
Logical specifying whether the oldest group should be considered as a plus group
Binds the fishing mortality random-walks together
Binds the variances of the numbers-at-age random-walks together
Binds the catchabilities of the surveys together
Allows power-law catchability models to be implemented, and possibly bound together. In the case where a value is set to NA, a linear model will be employed for that fleet-age combination
Binds the variances of the fishing mortality random-walks together (as opposed to "states", which binds the value of the random walks i.e. to bind one random walk to multiple fishing-mortalties at age).
Binds the variances (standard deviations) of the observations together
Logical variable indicating whether the fishing mortality random walks in a manner that incorporates correlations between the ages. Default is FALSE (i.e. the fishing mortalities are completely independent).
Stock recruitment relationships. Value options are 0= Random walk. 1= Ricker. 2=Beverton-Holt.
Logical variable indicating whether the hessian of the fitted model should be estimated. Default is TRUE. Turning on this variable can be used to increase the speed of the model but it does so at the cost of removing all uncertainty estimates and the variance-covariance matrix from the fitted object. Any methods that are dependent on these values will most likely fail as a result.
Model timeout setting (in seconds). If the model fails to finish within this timeframe, it exits and returns and error. Default is 3600s (one hour).
Name and path of the executable file to be run
It is important to realise that the default configuration returned by FLSAM.control is almost certaintly not the best configuration of your model - it is merely a first guess setup for your convenience. Similarly, there is no guarantee that this model will lead to a converged solution. It is the users responsibility to find the most appropriate "best" configuration of the model.
#Load data
library(FLSAM)
data(NSH)
#Create an object
ctrl <- FLSAM.control(NSH,NSH.tun)
ctrl
#> An object of class "FLSAM.control"
#> Slot "name":
#> [1] "North Sea Herring"
#>
#> Slot "desc":
#> [1] "Imported from a VPA file. ( ./data/index.txt ). Fri May 4 12:16:13 2012 + FLSAM: North Sea Herring"
#>
#> Slot "range":
#> min max plusgroup minyear maxyear minfbar maxfbar
#> 0 8 8 1992 2012 2 6
#>
#> Slot "fleets":
#> catch unique SCAI HERAS IBTS-Q1 IBTS0
#> 0 3 2 2 2
#>
#> Slot "plus.group":
#> plusgroup
#> TRUE
#>
#> Slot "states":
#> age
#> fleet 0 1 2 3 4 5 6 7 8
#> catch unique 0 1 2 3 4 5 6 7 7
#> SCAI -1 -1 -1 -1 -1 -1 -1 -1 -1
#> HERAS -1 -1 -1 -1 -1 -1 -1 -1 -1
#> IBTS-Q1 -1 -1 -1 -1 -1 -1 -1 -1 -1
#> IBTS0 -1 -1 -1 -1 -1 -1 -1 -1 -1
#>
#> Slot "logN.vars":
#> 0 1 2 3 4 5 6 7 8
#> 0 1 1 1 1 1 1 1 1
#>
#> Slot "logP.vars":
#> numeric(0)
#>
#> Slot "catchabilities":
#> age
#> fleet 0 1 2 3 4 5 6 7 8
#> catch unique -1 -1 -1 -1 -1 -1 -1 -1 -1
#> SCAI 0 -1 -1 -1 -1 -1 -1 -1 -1
#> HERAS -1 1 2 3 4 5 6 7 7
#> IBTS-Q1 -1 8 -1 -1 -1 -1 -1 -1 -1
#> IBTS0 9 -1 -1 -1 -1 -1 -1 -1 -1
#>
#> Slot "power.law.exps":
#> age
#> fleet 0 1 2 3 4 5 6 7 8
#> catch unique -1 -1 -1 -1 -1 -1 -1 -1 -1
#> SCAI -1 -1 -1 -1 -1 -1 -1 -1 -1
#> HERAS -1 -1 -1 -1 -1 -1 -1 -1 -1
#> IBTS-Q1 -1 -1 -1 -1 -1 -1 -1 -1 -1
#> IBTS0 -1 -1 -1 -1 -1 -1 -1 -1 -1
#>
#> Slot "f.vars":
#> age
#> fleet 0 1 2 3 4 5 6 7 8
#> catch unique 0 0 0 0 0 0 0 0 0
#> SCAI -1 -1 -1 -1 -1 -1 -1 -1 -1
#> HERAS -1 -1 -1 -1 -1 -1 -1 -1 -1
#> IBTS-Q1 -1 -1 -1 -1 -1 -1 -1 -1 -1
#> IBTS0 -1 -1 -1 -1 -1 -1 -1 -1 -1
#>
#> Slot "obs.vars":
#> age
#> fleet 0 1 2 3 4 5 6 7 8
#> catch unique 0 0 0 0 0 0 0 0 0
#> SCAI 1 -1 -1 -1 -1 -1 -1 -1 -1
#> HERAS -1 2 2 2 2 2 2 2 2
#> IBTS-Q1 -1 3 -1 -1 -1 -1 -1 -1 -1
#> IBTS0 4 -1 -1 -1 -1 -1 -1 -1 -1
#>
#> Slot "srr":
#> [1] 0
#>
#> Slot "scaleNoYears":
#> [1] 0
#>
#> Slot "scaleYears":
#> [1] NA
#>
#> Slot "scalePars":
#> age
#> years 0 1 2 3 4 5 6 7 8
#>
#> Slot "cor.F":
#> [1] 2
#>
#> Slot "cor.obs":
#> age
#> fleet 0-1 1-2 2-3 3-4 4-5 5-6 6-7 7-8
#> catch unique NA NA NA NA NA NA NA NA
#> SCAI -1 -1 -1 -1 -1 -1 -1 -1
#> HERAS -1 NA NA NA NA NA NA NA
#> IBTS-Q1 -1 -1 -1 -1 -1 -1 -1 -1
#> IBTS0 -1 -1 -1 -1 -1 -1 -1 -1
#>
#> Slot "cor.obs.Flag":
#> [1] ID ID ID ID ID
#> Levels: ID AR US
#>
#> Slot "biomassTreat":
#> [1] -1 0 -1 -1 -1
#>
#> Slot "timeout":
#> [1] 3600
#>
#> Slot "likFlag":
#> [1] LN LN LN LN LN
#> Levels: LN ALN
#>
#> Slot "fixVarToWeight":
#> [1] FALSE
#>
#> Slot "simulate":
#> [1] FALSE
#>
#> Slot "residuals":
#> [1] TRUE
#>
#> Slot "sumFleets":
#> logical(0)
#>
#Bind HERAS catchabilities on ages 5:8
ctrl@catchabilities["HERAS",as.character(5:8)] <- 11
#Alternatively can also use update functionality
ctrl@catchabilities["HERAS",as.character(5:8)] <- 101
ctrl <- update(ctrl)
#See example of full control object
data(NSH.sam)
NSH.ctrl
#> An object of class "FLSAM.control"
#> Slot "name":
#> [1] "North Sea Herring"
#>
#> Slot "desc":
#> [1] "Imported from a VPA file. ( ./data/index.txt ). Fri May 4 12:16:13 2012 + FLSAM: North Sea Herring"
#>
#> Slot "range":
#> min max plusgroup minyear maxyear minfbar maxfbar
#> 0 8 8 1992 2012 2 6
#>
#> Slot "fleets":
#> catch unique SCAI HERAS IBTS-Q1 IBTS0
#> 0 3 2 2 2
#>
#> Slot "plus.group":
#> plusgroup
#> TRUE
#>
#> Slot "states":
#> age
#> fleet 0 1 2 3 4 5 6 7 8
#> catch unique 0 1 2 3 4 5 6 7 7
#> SCAI -1 -1 -1 -1 -1 -1 -1 -1 -1
#> HERAS -1 -1 -1 -1 -1 -1 -1 -1 -1
#> IBTS-Q1 -1 -1 -1 -1 -1 -1 -1 -1 -1
#> IBTS0 -1 -1 -1 -1 -1 -1 -1 -1 -1
#>
#> Slot "logN.vars":
#> 0 1 2 3 4 5 6 7 8
#> 0 1 1 1 1 1 1 1 1
#>
#> Slot "logP.vars":
#> numeric(0)
#>
#> Slot "catchabilities":
#> age
#> fleet 0 1 2 3 4 5 6 7 8
#> catch unique -1 -1 -1 -1 -1 -1 -1 -1 -1
#> SCAI 0 -1 -1 -1 -1 -1 -1 -1 -1
#> HERAS -1 1 2 3 4 5 6 7 7
#> IBTS-Q1 -1 8 -1 -1 -1 -1 -1 -1 -1
#> IBTS0 9 -1 -1 -1 -1 -1 -1 -1 -1
#>
#> Slot "power.law.exps":
#> age
#> fleet 0 1 2 3 4 5 6 7 8
#> catch unique -1 -1 -1 -1 -1 -1 -1 -1 -1
#> SCAI -1 -1 -1 -1 -1 -1 -1 -1 -1
#> HERAS -1 -1 -1 -1 -1 -1 -1 -1 -1
#> IBTS-Q1 -1 -1 -1 -1 -1 -1 -1 -1 -1
#> IBTS0 -1 -1 -1 -1 -1 -1 -1 -1 -1
#>
#> Slot "f.vars":
#> age
#> fleet 0 1 2 3 4 5 6 7 8
#> catch unique 0 0 0 0 0 0 0 0 0
#> SCAI -1 -1 -1 -1 -1 -1 -1 -1 -1
#> HERAS -1 -1 -1 -1 -1 -1 -1 -1 -1
#> IBTS-Q1 -1 -1 -1 -1 -1 -1 -1 -1 -1
#> IBTS0 -1 -1 -1 -1 -1 -1 -1 -1 -1
#>
#> Slot "obs.vars":
#> age
#> fleet 0 1 2 3 4 5 6 7 8
#> catch unique 0 0 0 0 0 0 0 0 0
#> SCAI 1 -1 -1 -1 -1 -1 -1 -1 -1
#> HERAS -1 2 2 2 2 2 2 2 2
#> IBTS-Q1 -1 3 -1 -1 -1 -1 -1 -1 -1
#> IBTS0 4 -1 -1 -1 -1 -1 -1 -1 -1
#>
#> Slot "srr":
#> [1] 0
#>
#> Slot "scaleNoYears":
#> [1] 0
#>
#> Slot "scaleYears":
#> [1] NA
#>
#> Slot "scalePars":
#> age
#> years 0 1 2 3 4 5 6 7 8
#>
#> Slot "cor.F":
#> [1] 2
#>
#> Slot "cor.obs":
#> age
#> fleet 0-1 1-2 2-3 3-4 4-5 5-6 6-7 7-8
#> catch unique NA NA NA NA NA NA NA NA
#> SCAI -1 -1 -1 -1 -1 -1 -1 -1
#> HERAS -1 NA NA NA NA NA NA NA
#> IBTS-Q1 -1 -1 -1 -1 -1 -1 -1 -1
#> IBTS0 -1 -1 -1 -1 -1 -1 -1 -1
#>
#> Slot "cor.obs.Flag":
#> [1] ID ID ID ID ID
#> Levels: ID AR US
#>
#> Slot "biomassTreat":
#> [1] -1 0 -1 -1 -1
#>
#> Slot "timeout":
#> [1] 3600
#>
#> Slot "likFlag":
#> [1] LN LN LN LN LN
#> Levels: LN ALN
#>
#> Slot "fixVarToWeight":
#> [1] FALSE
#>
#> Slot "simulate":
#> [1] FALSE
#>
#> Slot "residuals":
#> [1] TRUE
#>
#> Slot "sumFleets":
#> logical(0)
#>