quick link to WP3 FLR

Description of the structure of the FLR objects

Up to now stock assessment and other working groups have tended to use and develop different software for specific tasks (VPA, XSA, ICA, SMS, SURBA, STF…) which require different formats for input data and generate different types of outputs. While existing models used for evaluating management strategies were mostly self contained software packages including a number of pre-defined processes and developed for one certain type of analysis. This made it difficult to testing alternative hypotheses or scenarios and to adapt them to specific case studies and issues.

In contrast, the basic idea behind FLR is to provide a wide range of tools, each performing one type of analysis within a common framework. These tools are developed so as to be compatible amongst each other, i.e. sharing inputs and outputs formats. So that the building of the simulation model itself is left up to the user, who can freely combine the individual tools after his or her own needs, like a child could build a range of models using “Lego blocks”.

The main predefined types and formats for inputs and outputs are referred to as core classes, and are defined in the FLCore package.
The core classes allow a variety of objects, corresponding to fish stocks and fleets to be created and also contains methods to access, summarise and manipulate them. The methods follow the same design as other R classes and methods providing a consistent and intuitive feel to user of R. These core classes also provide the basis of developing secondary packages, i.e. when develop a stock assessment method the main data types are already available in stock and cpue objects, allowing the developer of a stock assessment method to concentrate on the algorithm. While different stock assessment methods can quickly be compared as they use the same data structures and tools for inspection and summarising.

A main advantage of this approach is that as all users are using the same language and the same objects, while keeping the full flexibility over modelling choices. This makes it easier to use different packages, to explore other analysis methods and to read each others data and to collaborate within and across disciplines. Also it provides excellent opportunity for comparison of output from different models and to perform scenario analyses and comparison of alternative models, options and objectives through simulation. The main packages are officially released on R-repository and can be downloaded through the command:

install.packages(repos=”http://flr-project.org/R”)

Currently, the main packages are on the official R repository i.e. FLCore, FLEDA, FLXSA, FLAssess, FLSTF, FLBayes, etc.. Other packages are currently operational but still under further development. The latter packages will be released on the repository as soon as a stable version is available, the Complete list of packages is available on the FLR wiki.

Overview of FLR Packages

Complete list of packages is available on the FLR wiki.

FLR Objects Flow Chart

The Core package: FLCore

The basic package of FLR is FLCore that contains all the basic methods and classes for data manipulation. It contains, amongst others, the basic input-output functions from external format into FLR objects (e.g. importation of data from VPA Lowesoft format available in most ICES WG) and back to various formats.

The core classes comprise

Classes:

FLQuant The basic structure in FLR is the FLQuant, a 5-(FLCore v1.x-x) or 6-(FLCore v2.x-x) dimensional array. The first dimension, the quant, is set by the user (usually length or age) and the five others are respectively: year, units (e.g. sex, spawning unit,…), area, season and iter. The last dimension, “iter” (iteration) is available only in FLCore versions >= 2.0-0 and is used for stochastic analyses such as Monte Carlo simulation.

Other FLR classes are S4 objects containing a certain amount of simple objects called slot. The slots can be, for example, FLQuants, matrices, character-vector, arrays or dataframe that are grouped together to form a coherent, complete and easy to use objects. Each slot is access by “@” for example object@slot1 returns the slot slot1 of object.

FLStock stores most relevant data about the stock. The fishery is described through catch, landings, discards slots (in tons, in numbers at quant and mean weights at quant) harvest rate, proportion of harvest before spawning and the stock biology by natural mortality, proportion of natural mortality before spawning, maturity ogive, stock (total biomass, number at quant, weight at quant), etc.

FLBiol is a restricted form of FLStock storing only the biological data.

FLSR is designed to deal with all the elements of the estimation and display of stock-recruit dynamics. It contains usual stock-recruitment relationship models: Beverton and Holt, Ricker, quadratic hockey-stick and segmented regression.

FLIndex is the storage structure of data relative to abundance indices and stock assessment tuning fleets: effort, catch numbers at quant, mean weights at quant, cpue index, index variance, selection pattern, catchability.

FLCatch is an internal class of FLFleet. It stores all the stock-specific information on landings, discards and catch (total, numbers by quant, mean weight at quant and selectivity by quant). This class contains also the catchability, the price per weight unit by quant and information about the gear used.

FLFleet object represent the dynamic of a fleet. It can store data on multigear and multispecies fleets. The FLFleet class contains data at the fleet level (effort, capacity, costs) and at the species/stock level (an FLCatch object per target species/stock). The inclusion of métier data can be done through the “unit” dimension or by using a FLCatch object per métier-species combination.

Classes for multiple objects have been created from the classes above: FL*s e.g. FLStocks, FLIndices and FLFleets. Those classes are consistent lists of complex objects, this means that a FLStocks only contains FLStock objects.

FLModel is a virtual class that developers of various statistical models can use to implement classes that allow those models to be tested, fitted and presented. Slots in this class attempt to map all the necessary inputs and outputs for a modelling exercise, except for the various inputs. These must be defined in the individual classes that extend FLModel for individual applications. See, for example 'FLSR-class' for a class used for stock-recruitment models. Various fitting algorithms present in the basic R packages are currently available for FLModel, including 'mle', 'nls' and 'glm'. This class fully integrates stochastic simulation tools as it will fit for all iterations and can be used for example to do a Jacknife.

Methods:

A number of methods have also been implemented in the common framework and FLCore contains usual manipulation methods found in R applied on FLQuant:

  • Accessing information on the FLQuant: quant, units, names, dimnames, dims, summary, show
  • Plotting the data: plot and lattice plots (xyplot, bwplot, dotplot, barchart, stripplot, histogram, bubbles)
  • Conversion of data into or from FLQuants: FLQuant, as.FLQuant, as.data.frame
  • Validity test: is.FLQuant
  • Transforming the data: calculations apply, propagate, dim[Sums, Means, Vars] and subsetting window, trim, []

Some of those methods are also implemented for most of the complex objects, e.g. summary, show, plot, window, trim, []. The validity and conversion function names are also implemented with the appropriate names e.g. validity test for FLFleet is is.FLFleet.

Complex classes share common methods: the accessor methods are functions named after the slot they return, e.g. catch(FLStock) returns the slot FLStock@catch. The transform method allows the modification of several slots at the same time.

Moreover each FLClass has its own specific methods defined in FLCore.

  • FLStock: setPlusGroup, ssb, ssbpurec (ssb per unit recruit), computeCatch, computeLandings, computeDiscards, sop (sum of product).
  • FLSR: predict
  • FLIndex: computeCatch, qapply
  • FLCatch: computeCatch, computeLandings, computeDiscards
  • FLFleet: revenue
  • FL*s: lapply

Design for MSE using FLR objects

Design for MSE using FLR objects

Various MSEs have been conducted using FLR, there is no specific package developed for MSEs, as each implementation will by it’s nature will be case specific. Rather, these are developed using the core and secondary packages. Most generic code now being a part of FLR. A new website has been set up under code.google.com, similar to the concurrent versioning system under CVS used for FLR, to allow developers of MSEs to work together. So far there are two MSEs on this site that for the North Sea cod recovery plan and the West Atlantic and Mediterranean recovery plan. Details of how to use this system are available at http://code.google.com/p/mseflr/wiki/UsingTortoiseSVN

Examples of MSEs using FLR are available at www.flr-project.org and at the present EFIMAS Wiki.

Stable secondary packages

Many other packages based on the FLR core packages have been developed, although not all developed under EFIMAS they have both benefited from the work done under EFIMAS and show the achievements of EFIMAS. As with the core classes documentation and examples are provided both within the packages and at www.flr-project.org

Examples are

FLEDA: Exploratory Data Analysis

This package has been developed for Exploratory Data Analysis of the data available for stock assessment.
The main class in FLEDA is FLCohort which transforms an FLQuant (by year and quant) into an FLCohort object (by year class and quant). This allows working on year classes and de facto apprehending the strength of year classes.

Usual data-manipulation methods have been implemented in order to shorten the scripts. Some methods are applied on FLQuant: pay proportion by quant, rpay relative proportion by quant, spay standardized proportion by quant, while logcc (log catch-curves) method is applied on FLCohort.

Some plotting methods have also been implemented under FLEDA, splom scattered plot matrix, bubbles, etc. For further plotting examples, the tutorial available on the FLR wiki regarding FLEDA give useful pieces of code at the FLEDA tutorial.

FLAssess: stock assessment methods

FLAssess aims to be a common frame for stock assessments. It provides a common set of methods and objects for the most common stock assessment methods previously found in separated packages e.g. FLXSA, FLICA, FLSURBA.

The FLAssess package is the common frame for assessing stocks, and contains methods such as VPA, cohort analysis, separable VPA and a generalised method for setting up short-term forecasts (stf). The assessment is performed by calling the assess method with the common inputs: FLStock, FLIndices and a control object containing the specific settings for each assessment method including performing retrospective analyses. The choice of the assessment method is made through the control e.g.

assesss(control, FLStock, FLIndices)

For example, if control is of class FLXSA.control, an XSA will be performed.
The result of the analysis is returned in a FLAssess object. Each result class (e.g. FLXSA, FLICA, FLSURBA) created in the assessment packages are subclasses of FLAssess. And contain objects for both common outputs (e.g. numbers and fishing mortality-at-age and residuals to any fit) and specific to an application.

The FLAssess package also contains the retro method, which performs a retrospective analysis with the same input as assess plus the number of years the retrospective analysis as to be conducted over. This function returns an FLStocks object of length the number of year specified plus one. Those FLStocks are the input FLStocks with the slots stock.n and harvest updated after the analysis.
Other complementary methods are available in FLAssess:

  • The no.discards method for FLStock is also a useful tool to set the catches equal to landings in case of no data available for discarding. This is used for assessment procedures because all analyse methods are based on total catch and not only landings.
  • the stf function which extends FLStock objects along the year dimension and prepares some of the slots for forward stock projection, using a similar method to FLSTF.

FLXSA: eXtended Survivor Analysis

This package contains the code to perform an XSA assessment with three types of input: an FLStock (for the stock data), a FLIndices (for the tunings series) and an FLXSA.control containing all the usual XSA settings. FLXSA returns a FLXSA object containing the usual output of XSA. The diagnostics can be printed on the same format as the DOS-XSA diagnostics by calling the function DiagsXSA.

FLICA: Integrated Catch Analysis

FLICA is a stock assessment package which performs ICA analysis. The FLICA assessment method can also be called under the FLAssess umbrella (in the same way as FLXSA but with a FLICA.control). The results of FLICA are stored in a FLICA object. A problem with FLICA is that it uses propriety software (i.e. NAG routines) and so can not be freely distributed.

FLBayes: Bayesian analysis

This package is for running Bayesian interpretations of fisheries models. Previously this was the only way stock-recruitment relationships were available, although now these are available in FLSR within FLCore. Likewise a Shaefer/Pella-Tomlinson surplus production models was implemented as Bayesian models, however, separate packages based on FLModel are being developed. .

The main use of the Bayesian FLSR implementations is when conditioning operating models on tuned VPA-type assessment results. We do not estimate the stock-recruit relationship at run-time normally, but afterwards. The Bayesian alternative allows to incorporate the inherent uncertainty in this relationship (both parametric and random uncertainty) into the OM.

The Bayesian Pella-Tomlinson model allows us to assess stocks that may be data poor, or lacking in age information, but also serves as an OM in itself, and can be used as a management tool in a larger management procedure in a fully age-based problem.

FLSTF: The Short-Term Forecast

FLSTF performs a deterministic short term forecast. The approach is consistent with the forecasts typically conducted by ICES but with some additional functionality. Additions include: The option to constrain the forecast by either catches or SSB. The ability to produce a management options table based on multiples of Fpa as well as F status quo.

This package however has been replaced by moving the routines used to set up the short-term forecast into FLAssess and the routines for projection into FLash.

FLBRP: Biological Reference Points

FLBRP calculates biological reference points, an FLBRP object both allow users to calculate the common biological reference points, e.g. F0.1, FMax, MSY and economic reference points e.g. MEY. These can be created from other objects such as an FLStock, and can use the FLSR object to calculate equilibrium dynamics.

FLash

FLash using the open source package for automatic differentiation ADOL-C to solve the simultaneous non-linear equation required to perform multi-fleet, multi-stock projections and forms an important part of conducting MSEs. It is also being used with FLModel to create fast solvers for non-linear problems.

This package allowed modelling of a huge variety of HCRs

Packages under development

The following packages are available on CVS but no stable version has been released on the repository up to now, however, the packages are functional.

FLEcon: Economic tool box

This package is one of the bio-economic (multi-stock-multi-fleet based) packages fully developed in the frame of EFIMAS. It is functional and continously under further development. The major equations concerning a number of economic issues are implemented in relation to the core object of flr. The description of the equations can be found here Final report ECONOWS_June2008 and here ECONOWS_Matrix_Jan2007, and an extensive description of the package content is available on the package page on flr wiki

FLHCR: Harvest Control Rules

FLHCR is no longer being developed as all the harvest control rules can more readily be modelled in FLAsh. It used to perform traditional harvest control rules as implemented in ICES. However, given the variety of HCR existing, it had been decided to implement it in a way that could allow much more flexibility.

FLISIS: ISIS model

‘ISIS-FLR’ is a translation of the model underlying the ISIS-Fish software, initially coded in the Java language. ISIS-Fish (’Integration of Spatial Information for FISHeries simulation’) is a freeware for spatially- and seasonally-explicit simulation of the dynamics of multi-stock and multi-fleet interactions under a range of management options (e.g. MPA, catch and effort limitations, technical measures, etc.), already incorporates mixed fisheries, multispecies and economic models. The present model is a translation of ISIS-Fish inside the FLR environment and also incorporates alternative bioeconomic models. ‘ISIS-FLR’ is entirely developed in R using the FLR framework as a toolbox to generate fisheries-related objects from existing FLR classes. However, since the model encompasses the complex structure of mixed fisheries and emphasizes spatial and seasonal aspects, new classes have been defined for handling objects with specific extended properties.

FLOE: Observation Error

The FLOE package allows stochastic analyses. It contains two main classes FLObsIndex and FLprop. FLObsIndex simulates various indices of abundance specifying different error, catchability, power model and bias regimes. Simulating multiple observation replicates can be done by replication of generating observation from a single iteration of a FLQuant population variable, or by providing population data with a multiple “iter” dimension. FLprop can be used to simulate sampling/ageing error in proportions data (catch/survey-at-age, for example).

There are two immediate uses for FLOE:

  • When simulation testing any management procedure that uses any type of population abundance or catch observations, whether they are used directly or in some stock assessment procedure.
  • When simulation testing an assessment method in FLR. We may test the estimation properties of a particular assessment method - such as reaction to

structured noise, bias in observations, levels of noise, breaking of assumptions - so as to futher our understanding of the given method.

FLOE is for FLCore version 2, and further developments will be the inclusion of mark-recapture simulation tools.

This package is now largely redundant since following the development of ver 2 of FLR simulation of measurement and sampling processes are easily performed within FLCore. Examples of constructing observation error models using FLCore are available on the FLR wiki.

FLOgive

This package fits a variety of ogives to data in FLQuant objects. The major uses of this package are as follows:

  • Fitting data to and defining selectivity ogives (for separable models for example) - there are a variety of common ogive choices available.
  • Simulating changes in selection patterns over time.
  • Fitting other normalised data, such as maturity-at-age, to the various ogives available.

It is likely that this package will become an extension of FLModel in the future

FLOM: Operating Model

FLOM is especially developed under the EU project COMMIT and applied to Northern Hake under case study 6 of EFIMAS. The FLOM package provides a generic function to simulate an age-strucutred population and a fishery assessed using XSA and management using, either annual or multiannual, TAC obtained applying a HCR which can be specified by the user. The function also gives the option to simulate the observation and implementation errors ocurring in the management proccess.

Again although an important package in the development of FLR, the need for a separate package has disappeared since the development of ver 2 of FLR and consolidation of individual tools into generic secondary like Flash.

FLSURBA: survey based stock assessment method

FLSURBA performs a survey based stock assessment. This method can be called by itself or with the assess() function of FLAssess. The control object must be a FLSURBA.control for assess to perform a SURBA analysis and the results are stored in a FLSURBA object. Like FLICA this package uses the NAG routines and so can not be made freely available.

FLUtils: FLCore utility functions and methods

This package is designed for FLCore version 2, and contains useful, but not essential, functions and methods. For example, the boot() method allows the user to apply a structured bootstrap to FLQuant data, and bootstrap the statistics of FLQuants, but it uses the C++ headers and FLCore does not have any direct C++ based methods. Also, there is the smoother() method, which applies a structured loess smoother to FLQuant data.

These functions have been incorporated into ver 2 of FLR and the need for a secondary package has disappeared.

Katell Hamon 2007/02/01 14:32

Laurence Kell 2008/08/20 12:05

J. Rasmus Nielsen 2008/09/08 11:18

 
efimas1/wp3/3-3-2/main.txt · Last modified: 2008/09/09 20:47 by admin
 
Except where otherwise noted, content on this wiki is licensed under the following license:CC Attribution-Noncommercial-Share Alike 3.0 Unported
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki