FLSAM: FLR Wrapper for the State-space assessment model (FLSAM)

In flr/FLSAM: An Implementation of the State-Space Assessment Model for FLR

FLR Wrapper for the State-space assessment model (FLSAM)

Description

Performs a stock assessment using the State-Space assessment model (SAM)

Usage

FLSAM(stck, tun, ctrl, run.dir=tempdir(), batch.mode=FALSE,pin.sam=NULL)

update(object, stck, tun, run.dir=tempdir(),batch.mode=FALSE)

FLR2SAM(stck, tun, ctrl, run.dir = tempdir(),pin.sam=NULL)
runSAM(ctrl, run.dir=tempdir(),use.pin=FALSE)
SAM2FLR(ctrl="missing", admb.stem="sam", run.dir = tempdir()) 

Arguments

stck	FLStock object containing all data to be used in the assessment
tun	FLIndices object containing survey/tuning indices
ctrl	FLSAM.control object containing the parameters to be employed in the assessment
run.dir	Path to which the temporary files are to be written to or read from. Default is the R temporary directory provided by tempdir()
batch.mode	Logical variable indicating whether the code should be run in batch mode.
object	An object of the FLSAM class, resulting from e.g a call to FLSAM, that is to form the basis for the update.
pin.sam	Provide an FLSAM object, to be used as pin file, to the FLSAM function call to speed up the estimation process
use.pin	A logical variable indicating whether the SAM executable should look for a file containing initial parameter estimates (i.e. a pin file)
admb.stem	The name of the admb executable (ie without the .dat, .exe etc)

Details

FLSAM is an FLR wrapper to SAM, the state-space assessment model. SAM is written in the compiled ADMB language - compiled executables for each platform are included within the FLSAM package. The FLSAM function provides the interface between the data (FLStock, FLIndices objects) and configuration objects (FLSAM.control) stored in R, and the compiled exectable.

Three helper functions provide the core of the FLSAM method. FLR2SAM accepts the necessary data objects and writes a series of text files to the path specified by run.dir. runSAM takes care of running the SAM executable and checking that the model has run to completion correctly. SAM2FLR reads the outputs generated by the SAM model and reads them back into the FLR environment. The FLSAM function provides a wrapper around these three functions, writing the data to the temporary directory, running the executable, and reading the results back. Generally, the user should not need to use FLR2SAM, runSAM or SAM2FLR, but they can be useful in helping to debug the code.

SAM2FLR is particularly useful when trying to read results of a SAM run into FLR for plotting, further analysis etc. Ideally it should be able to figure everything out from the contents of the directory containing the files. However, if this fails, it may be necessary to give it a helping hand by creating a (FLSAM.control) object and supplying it via the "ctrl" argument.

The user can also specify the directory (via the 'run.dir' argument) in which the temporary files used to communication with SAM are stored. The default is to use the temporary directory of R.

FLSAM can also be run in "batch-mode" through the 'batch.mode' argument. This is a particularly useful feature when running a large number of assessments in an unattended situation. If the SAM model fails to converge in when running in batch-mode, it will suppress the error and return a "NULL" value (instead of an FLSAM object). If the model fails to converge when not running in batch-mode (the default), an error is returned.

It is also possible, via the 'update' function, to "reuse" the results of a previous stock assessment to provide initial guesses for the new assessment. Such a feature may be desirablie in situations where the user is running a large number of assessments that are very similar and have the same parameter configuration e.g. in a management-strategy evaluation. The supplied FLSAM object is used to generate a parameter-initialisation ("pin") file - the 'use.pin' argument in runSAM is then activated in this case, to tell the ADMB SAM executable to use these values. At the moment, it is not possible to change the assessment configuration in this manner - future releases will hopefully incorporate this feature.

Value

The typical return value is an object of the FLSAM class with the following slots.

control	The FLSAM.control object used to configure the assessment.
nohess	Logical variable indicating whether the model was fit including the calculation of the hessian
nopar	The number of parameters fitted by the model
n.states	The number of states fitted internally in the model
states	The state coupling matrix - see FLSAM.control
nlogl	The negative log-likelihood of the fitted parameters
maxgrad	The gradient of the negative log-likelihood at optimum
vcov	The variance-covariance matrix of the fitted parameters
params	The parameters fitted by the model, stored as a data.frame. The columns of the data frame are index - A numeric index for the parameter name - The name of parameter value The fitted value of the parameter std.dev -The standard deviation of the fitted value
stock.n	An FLQuant object containing the stock-numbers at age in each year
harvest	An FLQuant object containing the fishing mortality at age in each year
residuals	A data.frame summarising the observed and fitted values, and the residuals linking them. The columns of the data frame are year - the year in which the observation was made fleet - the fleet the observation corresponds to age - the age the observation corresponds to. For biomass indices, this value has no meaning log.obs - the natural logarithm of the observed value log.mdl - the natural logarithm of the modelled value std.res - the standardised residual i.e. (log.obs - log.mdl) / obs.std, where obs.std is the observation error associated with that fleet/age.
name	A text field giving the name of the object
desc	A text field describing the object
range	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
info	Contains key information about the software versions and operating system used in running the assessment

The FLSAM function will return an FLSAM object in all cases when the model converges. If the model does not converge, FLSAM will return an error unless it is running in batch mode, in which case it will return "NULL".

runSAM() returns an integer error code corresponding to the return value of the SAM model - 0 for a successful run, non-zero otherwise. SAM2FLR will return an FLSAM object. FLR2SAM does not return any values.

Author(s)

SAM2FLR based on code by Anders Nielsen and adapted by Mark Payne. FLR2SAM and FLSAM by Mark Payne

References

Nielsen et al (2012) In prep.

See Also

FLSAM.control

Examples

#Load library
library(FLSAM)
#Prepare data objects
data(NSH)
data(NSH.sam)
#Perform assessment
#Takes about two minutes on a 2.4GHz workstation
sam <- FLSAM(NSH,NSH.tun,NSH.ctrl)
sam <- FLSAM(NSH,NSH.tun,NSH.ctrl, return.fit=TRUE)

#If you want to re-use the sam object to create a pin file, use this:
sam <- FLSAM(NSH,NSH.tun,NSH.ctrl,pin.sam=sam)
#View results
plot(sam)

#Repeat the assessment using the previous result as an initial guess
uninit.time <- system.time(sam.uninit <- FLSAM(NSH,NSH.tun,NSH.ctrl))
#init.time   <- system.time(sam.init   <- update(sam.uninit,NSH,NSH.tun,NSH.ctrl))
#Big speed increase! (your results may vary: ours are about 2x)
#uninit.time[3]/init.time[3]
#But assessments are the sam (phew!)
#plot(FLSAMs(uninitialised=sam.uninit,initialised=sam.init))

flr/FLSAM documentation built on Dec. 6, 2024, 9:19 a.m.