Package FLAssess

January 25, 2007

Title Generic classes and methods for stock assessment models Version 1.3-3 Author Laurie T. Kell <l.t.kell@cefas.co.uk> Description A generic set of classes for stock assessment models are provided here. Individual assessment packages should Depends FLCore, methods Maintainer Iago Mosqueira <imosqueira@suk.azti.es> License GPL 2.0

R topics documented:
assess-methods . . . . . correctIndex . . . . . . . data . . . . . . . . . . . FLAssess . . . . . . . . FLAssess.retro-class . . FLSepVPA.control-class fwd-methods . . . . . . fwd.val . . . . . . . . . is.FLAssess . . . . . . . is.FLAssess.retro . . . . no.discards-methods . . plotFitted-methods . . . retro.old . . . . . . . . . retro . . . . . . . . . . . SepVPA-methods . . . . stf-methods . . . . . . . VPA-methods . . . . . . Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2 3 3 5 6 7 9 10 11 11 12 12 13 14 15 16 17

correctIndex

assess-methods

Call an stock assessment model

Description The assess methods calls the stock assessment function according to the class of the control object given. Stock assessment methods in FLR generally require a control class that contains all the options the model and its tting algorithm provide. Classes are specic to each method, so see the relevant help pages for detailed information. The assess method allows different stock assessment procedures to be carried out in a simulation procedure, or in any other function, by simply altering the control class in the argument list. This is a generic method to be extended for individual stock assessment models. Methods object = "FLAssess" The generic, to be extended for each specic assessment model

correctIndex

Corrects index for VPA

Description This function is not intended to be used directly by users. It is called by the VPA method and implements equation 3 of the VPA users guide. Usage correctIndex(FLIndex, harvest, m) Arguments FLIndex harvest m Details An object of type FLIndex An object of type FLQuant An object of type FLQuant

Value Returns an object of type FLIndex Author(s) Laurence Kell References

data See Also See also VPA Examples

data

FLAssess dataset

Description

ass Results of performing an XSA on ple4 data Datasets can be loaded by issuing data(ass). References

FLAssess

FLAssess class and methods

Description FLAssess is the basic structure for age-based stock assessment. It provides a standard class for data input, diagnostic inspection and stock status estimation; either for use within a working group setting or as part of a formal Management Strategy Evaluation (MSE). The FLAssess class can be extended to create specic implementations of assessment methods e.g. FLICA, FLSURBA, FLXSA, providing a common interface for all assessmnet methods. For example, within ICES there are two main stock assessment methods, ICA for pelagic and XSA for demersal stocks. However, differences between the methods are mainly artefacts of how they were independently developed rather than methodological. By incorporating such methods in a common class this problem will hopefully be avoided in the future. FLAssess also incorporates methods for performing virtual population analysis (VPA) and stock projection. Objects from the Class Objects can be created by calls to the methods VPA or SepVPA. They also can be created by calls of the form new("FLAssess", ...).

4 Slots name: A character string give name of stock. desc: Whatever you want. harvest: An FLQuant that contains estimated shing mortlaity-at-age. catch.n: An FLQuant that contains estimated catch numbers-at-age. stock.n: An FLQuant that contains estimated stock numbers-at-age. harvest: An FLQuant that contains estimated shing mortlaity-at-age. index.name: A vector containing names for the FLIndexs index.range: A list containing ranges for the FLIndexs index: A list of FLQuants, corresponding to the index values used when tting. index.hat: A list of FLQuants, corresponding to the tted index values. index.res: A list of FLQuants, corresponding to the index residuals.

FLAssess

index.var: A list of FLQuants, corresponding to the variances of index values in tting. Methods Summarise contents: summary: Returns a list with a vector for each dimension in the object, which contains the levels of each dimension. show: Prints the given object. Plots: plot: Plots stock.n against index plotFitted: Plots index.hat against index plotIndex: Plots index against year plotRes: Plots residuals plotResN: Plots residuals against stock.n plotResYr: Plot residuals against years Update FLstock: +: Updates a FLStock with stock.n, & catch.n, harvest estimates from an FLAssess object update: Updates a FLStock with stock.n, catch.n & harvest estimates Stock Assessment methods: SepVPA: Separable VPA VPA: Virtual Population Analysis Author(s) Laurence Kell See Also is.FLAssess, FLIndices-class, FLStock-class Examples

FLAssess.retro-class

FLAssess.retro-class Class FLAssess.retro

Description A class for results of a retrospective analysis Objects from the Class Objects can be created by calls of the form new("FLAssess.retro", ...), but they are usually created by a call to the retro function. Slots desc: Object of class "character". Object description. ssb: Object of class "list". A list of FLQuants to hold SSB data for each retrospective analysis recruits: Object of class "list", A list of FLQuants to hold recruitment data for each retrospective analysis harvest: Object of class "list". A list of FLQuants to hold harvest data for each retrospective analysis Methods plot signature(x = "FLAssess.retro", y = "missing"): ... as.data.frame signature(x = "FLAssess.retro"): ... window signature(x = "FLAssess.retro"): ... as.data.frame Returns a data.frame version of the object Author(s) Laurie Kell See Also retro, FLAssess-class

Examples

FLSepVPA.control-class

FLSepVPA.control-class Control class for FLSepVPA

Description Objects of this class contain all the neccessary settings for the Separable VPA model available through function SepVPA.

Objects from the Class Objects can be created by calls of the form new("FLSepVPA.control", ...) or by calling the FLSepVPA.control function.

Slots sep.nyr: Object of class "integer". Number of years for separable model. sep.age: Object of class "integer". Reference age for tting the separable model. Default value = 4 sep.sel: Object of class "numeric". Default value = 1.0

Methods No methods dened with class "FLSepVPA.control" in the signature.

Author(s) Iago Mosqueira

References JG Shepherd, SM Stevens. 1983. Separable VPA: Users guide - Int. Rep., MAFF Direct. Fish. Res.

See Also FLSepVPA

Examples
sep.vpa.control <- FLSepVPA.control(sep.nyr=5, sep.age=5)

fwd-methods

fwd-methods

Forward projection for FLR

Description Performs a forward projection on an appropiate FLR object. It is possible to supply projected total catch weight and the projected harvest rates are estimated accordingly. This method is most easily used with the output from stf(). Arguments object year sr.model sr.param The FLStock object the projection is to be perfomed on. A vector of years (as characters) to forecast over. The stock-recruitment model (see below). A vector of parameters for the stock-recruitment model (see below).

sr.residuals Vector of residuals for the stock-recruitment model. If fewer residuals are supplied than the number of projection years the residuals are recyled. sr.residuals.mult A Boolean. If TRUE the estimated recruitment is multiplied by the residual for that year, else the residual is added to the recruitment estimate. Details Called using: Runs a forward projection on an FLStock object and calculates the catch and stock numbers-at-age. The standard projection equations are used: Z=F+m where F and m are the harvest and natural mortality rates respectively. The stock numbers in the following year are calculated as: N(t+1) = N(t) * exp(-Z(t)) The recruitment numbers are estimated using the stock-recruitment model (see below). The estimated recruiment is then modied (either multiplied by or added to) by the user supplied residuals. If no residuals are supplied, a multipler of 1.0 is used. If the plus group of the stock object is set the numbers in the plus group is calculated appropriately. The catch numbers in the following year are calculated as: C(t+1) = N(t+1) * F(t+1) / Z(t+1) * (1 - exp(-Z)) There are two ways to run a projection: - If the total catch weights for the projection years are set as NAs, the projection is run using the above equations. - Alternatively, if total catch weights are supplied for the projection years, a harvest multiplier (Fmult) is estimated for each of the projection years which gives the required total catch. The projection is then run using the modied harvest rates. If the desired catch numbers are not possible, the method returns with a warning. NOTE: This method can be time consuming, particulary if the stock object has many iterations.

fwd(object,year,sr.model="missing",sr.param="missing",sr.residuals=1.0,sr.residu

fwd-methods For either way to work, harvest and natural mortality rates for the projection years need to be supplied. These can either be added in directly by the user or can be estimated using the stf() method which also conveniently extends the stock object and estimates future weights and landings / discards proportions. There are currently ve stock-recruitment models. For each, parameters need to be set. The models and required parameters are:

"mean" Fixed recruitment for all years "bevholt" Beverton-Holt model. Parameters "alpha" and "beta" "ricker" Ricker model. Parameters "alpha" and "beta" "qhstk" Hockey stick model. Parameters "alpha", "beta" and "rho" "shepherd" Shepherd model. Parameters "alpha" and "beta" If no stock-recruitment model or parameters are specied, a "mean" model is used with a value of 1.0. The residuals are then set to be the recruitment values already in the stock object, starting from the earliest year. This effectively means that if a stock-recruitment model is not specied, the recruitment in the forecast years will be the same as the previous recruitment levels, starting from the earliest year. This method is not yet implemented for multiple seasons or areas. Value Returns an object of type FLStock. Author(s) FLR Team See Also

Examples

# load ple4 data(ple4) # stf with default settings - extends the stock object by three years ple4.stf <- stf(ple4,nyrs=3, wts.nyrs=4, f.nyrs=3, disc.nyrs=3) # run a standard three year projection, with fixed recruitment for all years ple4.fwd <- fwd(ple4.stf, year=as.character(2002:2004), sr.model="mean", sr.param=250000) # Or can fix catch numbers ple4.catch <- ple4.stf ple4.catch@catch[,as.character(2002:2004)] <- c(60000,60000,60000) ple4.catch.fwd <- fwd(ple4.catch, year=as.character(2002:2004), sr.model="mean", sr.param

fwd.val

fwd.val

Forward validation for FLR

Description Used for validating the results of a stock assessment by performing a retrospective assessment and then projecting forward under various assumptions. The results can be then compared with the ouput of the current assessment. Usage

fwd.val(stock, idx, control, yrs, recruits=as.numeric(1.0),known.sel=FALSE,known Arguments stock idx control yrs recruits known.sel FLStock object the retrospective and subsequent projection is to be perfomed on. FLIndices object containing the tuning data Assessment control object, e.g. of type FLXSA.control Vector of years to project over. Must be within the range of the stock. Recruitment for the projection years. Either a single value for all projection years or an FLQuant with a value for each year. Boolean. If TRUE the harvest rates, discards and landings numbers from stock are used for the projection years. Otherwise the estimated values from the stf() and fwd() functions are used. Boolean. If TRUE the discards, landings and catch weights from the stock are used for the projection years. Otherwise the estimated weights from the stf() function are used.,

known.wt

Details A retrospective assessment is run up to the year min(yrs)-1 using stock, idx and control. The resulting stock object is then extended by calling the stf() function which estimates weights and harvest rates for the years specied in the argument yrs. A forward projection is then run for the years given by the argument yrs using the function fwd(). If known.sel is FALSE the projected harvest rates are initially estimated as the mean of the previous 3 years. If known.sel is TRUE the harvest rates for the projection years from the original stock are used. If known.wt is TRUE the catch, discards and landings weight slots for the projection years are set as equal to those in the original stock object. If known.wt is FALSE the weights for the projection years are estimated as the mean of the last 3 years. As with the fwd() function, if the total catch weight (the catch slot) for the projection years of the original stock object is not NA, the harvest rates are adjusted by a shing multiplier so that the total catch weight in the projection years are the same as in the original stock object. If the total catch weights for the projection years in the original stock object is NA, the catch numbers and total catch weight are calculated using the given harvest rates. This method is not yet implemented for multiple seasons or areas.

10 Value Returns an object of type FLStock-class. Author(s) FLR Team See Also FLAssess-class fwd retro stf

is.FLAssess

is.FLAssess

is.FLAssess

Description Testing of FLAssess objects Usage is.FLAssess(x) Arguments x object to test. Details

Value is.FLAssess returns TRUE or FALSE Author(s) Laurence Kell See Also FLAssess-class Examples
## Not run: is.FLAssess(new('FLAssess')) ## End(Not run)

is.FLAssess.retro

11

is.FLAssess.retro

is.FLAssess.retro

Description Testing of FLAssess.retro objects Usage is.FLAssess.retro(x) Arguments x object to test. Details

Value is.FLAssess.retro returns TRUE or FALSE Author(s) Laurence Kell See Also FLAssess.retro-class Examples
## Not run: is.FLAssess.retro(new('FLAssess.retro')) ## End(Not run)

no.discards-methods Sets catch data if no discards

Description This method sets the slots discards.n and discards.wt to 0, and sets the slots catch, catch.n and catch.wt to their landings equivalents. Methods no.discards<-(obj) Takes in an object of type FLStock and carries out the above actions. Returns an object of type FLStock

12

retro.old

plotFitted-methods plot methods for the results of stock assessment models

Description

Methods

retro.old

Retrospective stock assessment in FLR

Description Performs a retrospective stock assessment for the desired number of years using the stock assessment method specied in the control object (see FLAssess and extended classes) NOTE: This function is the old, downgraded retro() function. It returns an object of type FLAssess.retro which is now obsolete. Please use the new function retro(). Usage

retro.old(FLStock, FLIndices, control = "missing", retro = 0,fbar=c(min=as.integ Arguments FLStock FLIndices control retro fbar Details The type of assessment method used is determined by the control object, e.g. FLXSA.control, FLICA.control etc. In this way retrospective analysis using different assessment methods can be easily carried out on the same stock and tuning data by using different control classes. The results of the restrospective analysis can be plotted using the plot() method (type can be "recruits", "ssb" or "f"). Value Returns an object of type FLAssess.retro. An object of type FLStock that contains information (catch data, natural mortality etc.) on the stock that is to be assessed An object of type FLIndices that contains the tuning data A control object of the desired extended FLAssess assesment method class, e.g. FLXSA.control An integer that species the number of retrospective years. Default value = 0. Vector specifying mininmum and maximum quant range to calculate fbar

retro Author(s) Laurence Kell See Also FLAssess-class, FLICA, FLXSA, retro

13

retro

Retrospective stock assessment in FLR

Description Performs a retrospective stock assessment for the desired years using the stock assessment method specied in the control object (see FLAssess and extended classes) Usage retro(FLStock, FLIndices, control = "missing",year.range="missing", retro = 0) Arguments FLStock FLIndices control year.range retro An object of type FLStock that contains information (catch data, natural mortality etc.) on the stock that is to be assessed An object of type FLIndices that contains the tuning data A control object of the desired extended FLAssess assesment method class, e.g. FLXSA.control Numeric vector of years to perform the assessment An integer that species the number of retrospective years. Default value = 0. Only used if year.range is not specied.

Details The type of assessment method used is determined by the control object, e.g. FLXSA.control, FLICA.control etc. In this way retrospective analysis using different assessment methods can be easily carried out on the same stock and tuning data by using different control classes. The argument year.range is a numeric vector of years for which the assessment is to be performed. If this is not specied the integer retro is used (default value = 0). If retro = 0 the assessment is run for nal year only. If retro = 1, the assessment is run for the penultimate and nal year and so on. The results of the restrospective analysis can be plotted using the generic FLStocks plot() method. NOTE: This function supercedes the previous retro() function which returned an object of type FLAssess.retro. The FLAssess.retro class is now obsolete and will not be present in future releases. Users are advised to update their scripts to use this new function. The original function is still in the FLAssess package with the name retro.old(). Value Returns an object of type FLStocks. Each component FLStock object contains the result of each of the retrospective assessments.

14 Author(s) Laurence Kell See Also FLAssess-class, FLICA, FLXSA Examples

SepVPA-methods

SepVPA-methods

Separable Virtual Population Analysis in FLR

Description Performs Separable Virtual Population Analysis. Methods for function SepVPA in package in Package FLAssess. Requires an object of class FLSepVPA.control to be created. Methods

SepVPA<-function(stock, control=FLSepVPA.control(), ref.harvest="missing", frati , where stock is of type FLStock, control is of type FLSepVPA.control(), ref.harvest and fratio are numeric and fit.plusgroup is Boolean. Examples
library(FLCore) library(FLAssess) # Example based on ple4 dataset data(ple4) my.stock<-FLStock(iniFLQuant = FLQuant(dim=c(15,45,1,1,1), dimnames = list (age=as.character(1:15), year = as.character(c(1957:2001))))) my.stock@range["plusgroup"] <- 15 #load catch data and mortality my.stock@catch.n <- ple4@catch.n my.stock@catch.n[my.stock@catch.n==0] <- 1 my.stock@m <- ple4@m my.control <- FLSepVPA.control(sep.age = 5) # Set up in final year my.stock@stock.n[,45,,,] <- ple4@stock.n[,45,,,] # Run SepVPA my.stock.SepVPA <- SepVPA(my.stock, my.control, fit.plusgroup=TRUE)

stf-methods

15

stf-methods

Projection preparation for FLR

Description Extends an FLStock object along the year dimensin and prepares some of the slots for forward stock projection, using a similar method to FLSTF. Can be used in conjunction with fwd() for validating assessments. Generic Function Usage stf(object,nyrs=3,wts.nyrs=3,f.nyrs=NA,disc.nyrs=NA,arith.mn=TRUE, na.rm=TRUE) Arguments: object: FLStock object the forecast is to be perfomed on. nyrs: Number of years to extend the stock object by, i.e. number of forecast years. wts.nyrs: Number of years over which to calculate mean for *.wt, *.spwn, mat and m slots. f.nyrs: Number of years over which to calculate mean for harvest slot. If unspecied, wts.nyrs is used. disc.nyrs Number of years over which to calculate mean for discards.n and landings.n slots, If unspecied, wts.nyrs is used. arith.mn Boolean - if TRUE use arithmetic mean, if FALSE use geometric mean. na.rm: Boolean - whether to ignore NA values when calculating means. Value FLStock object Methods object="FLStock" : Extends the stock object by a number of years and estimates the values in the future years of the slots. The future values of the mat, m, harvest.spwn, m.spwn, harvest and all *.wt slots are set to the mean (geometric or arithmetic) value of the last user dened number of years. The future values of the discards.n and landings.n slots are returned only as estimated proportions, not actual numbers. The proportions are calculated as the mean proportion of the sum of the landings and discard numbers of the last user dened number of years. The remaining slots (stock.n, catch.n, stock, catch, discards, landings) are set to NA. Not yet implemented for multiple seasons or areas. Author(s) FLR Team See Also FLAssess-class, fwd, FLStock-class Examples
# load ple4 data(ple4) # stf with default settings ple4.stf <- stf(ple4,nyrs=3, wts.nyrs=4, f.nyrs=3, disc.nyrs=3)

16

VPA-methods

VPA-methods

Virtual Population Analysis in FLR

Description Implements Popes Virtual Population Analysis Methods for function VPA in package in Package FLAssess Methods VPA<-function(stock, fratio="missing", fit.plusgroup=TRUE,desc="",...) , where stock is of type FLStock, fratio is numeric and fit.plusgroup is Boolean. Examples

library(FLCore) library(FLAssess) # use the ple4 data set data(ple4) # Set up stock my.stock<-FLStock(iniFLQuant = FLQuant(dim=c(15,45,1,1,1), dimnames = list (age=as.character(1:15), year = as.character(c(1957:2001))))) my.stock@range["plusgroup"] <- 15 my.stock@catch.n <- ple4@catch.n # replace zeros in catch as 1 my.stock@catch.n[my.stock@catch.n==0] <- 1 my.stock@m <- ple4@m # Set initial fishing mortality in the final ages of each year and for all ages in the fi my.stock@harvest[15,,,,] <- ple4@harvest[15,,,,] my.stock@harvest[,45,,,] <- ple4@harvest[,45,,,] # Run VPA my.stock.VPA <- VPA(my.stock, fit.plusgroup=TRUE)

Index
Topic classes FLAssess, 3 FLAssess.retro-class, 5 FLSepVPA.control-class, 6 is.FLAssess, 10 is.FLAssess.retro, 11 Topic datasets data, 3 Topic hplot plotFitted-methods, 12 Topic manip correctIndex, 2 is.FLAssess, 10 is.FLAssess.retro, 11 no.discards-methods, 11 Topic methods assess-methods, 1 FLAssess, 3 fwd-methods, 7 fwd.val, 9 no.discards-methods, 11 plotFitted-methods, 12 SepVPA-methods, 14 stf-methods, 15 VPA-methods, 16 Topic models retro, 13 retro.old, 12 SepVPA-methods, 14 VPA-methods, 16 +,FLAssess,FLStock-method (FLAssess), 3 +,FLStock,FLAssess-method (FLAssess), 3 assess,FLSepVPA.control-method (SepVPA-methods), 14 assess-methods, 1 correctIndex, 2 data, 3 FLAssess, 3 FLAssess-class, 5, 10, 1315 FLAssess-class (FLAssess), 3 FLAssess.retro-class, 11 FLAssess.retro-class, 5 FLSepVPA.control, 6, 14 FLSepVPA.control (FLSepVPA.control-class), 6 FLSepVPA.control-class, 6 FLStock-class, 10, 15 fwd, 10, 15 fwd (fwd-methods), 7 fwd,FLBiol-method (fwd-methods), 7 fwd,FLStock-method (fwd-methods), 7 fwd-methods, 7 fwd.val, 9 is.FLAssess, 4, 10 is.FLAssess.retro, 11 no.discards (no.discards-methods), 11 no.discards,FLStock-method (no.discards-methods), 11 no.discards-methods, 11

plot, 4 plot,FLAssess,missing-method as.data.frame,FLAssess.retro,ANY,ANY-method (FLAssess), 3 (FLAssess.retro-class), 5 plot,FLAssess.retro,missing-method as.data.frame,FLAssess.retro-method (FLAssess.retro-class), 5 (FLAssess.retro-class), 5 plotFitted, 4 ass (data), 3 plotFitted (plotFitted-methods), assess (assess-methods), 1 12 assess,FLAssess-method plotFitted-methods, 12 (assess-methods), 1 plotIndex, 4 17

18 plotIndex (plotFitted-methods), 12 plotIndex-methods (plotFitted-methods), 12 plotRes, 4 plotRes (plotFitted-methods), 12 plotRes-methods (plotFitted-methods), 12 plotResN, 4 plotResN (plotFitted-methods), 12 plotResN-methods (plotFitted-methods), 12 plotResYr, 4 plotResYr (plotFitted-methods), 12 plotResYr-methods (plotFitted-methods), 12 qqResYr (plotFitted-methods), 12 qqResYr-methods (plotFitted-methods), 12 retro, 5, 10, 13 retro.old, 12 SepVPA, 4 SepVPA (SepVPA-methods), 14 SepVPA,FLStock-method (SepVPA-methods), 14 SepVPA-methods, 14 show, 4 show,FLAssess-method (FLAssess), 3 stf, 10 stf (stf-methods), 15 stf,FLAssess-method (stf-methods), 15 stf,FLBiol-method (stf-methods), 15 stf,FLStock-method (stf-methods), 15 stf-methods, 15 summary, 4 summary,FLAssess-method (FLAssess), 3 units,FLAssess-method (FLAssess), 3 units<-,FLAssess,list-method (FLAssess), 3 update, 4 update,FLAssess-method (FLAssess), 3 VPA, 2, 4 VPA (VPA-methods), 16

INDEX VPA,FLStock-method (VPA-methods), 16 VPA-methods, 16 window,FLAssess-method (FLAssess), 3 window,FLAssess.retro-method (FLAssess.retro-class), 5