# Overview

[![FIMS status
badge](https://noaa-fisheries-integrated-toolbox.r-universe.dev/badges/FIMS)](https://noaa-fisheries-integrated-toolbox.r-universe.dev/FIMS)
[![R-CMD-check
badge](https://github.com/NOAA-FIMS/FIMS/actions/workflows/call-r-cmd-check.yml/badge.svg?branch=main)](https://github.com/NOAA-FIMS/FIMS/actions/workflows/call-r-cmd-check.yml)
[![Codecov test
coverage](https://codecov.io/gh/NOAA-FIMS/FIMS/branch/main/graph/badge.svg)](https://app.codecov.io/gh/NOAA-FIMS/FIMS?branch=main)
[![Lifecycle:
experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)

FIMS is an R package for fitting integrated statistical
population-dynamics models to fishery data. The back end is written in
C++, and the use of Rcpp allows users to easily interact with the models
using R. The package is unique because it includes multiple model types,
e.g., surplus production and catch-at-age models. This reduces the
burden of learning a new framework when exploring major changes in model
structure. Stay tuned for the addition of even more model types.

If you are new to FIMS, the best place to start is the [“Introducing
FIMS”](https://noaa-fims.github.io/FIMS/articles/fims-demo.html)
vignette.

[![Ask
DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/NOAA-FIMS/FIMS)

## Installation

A [precompiled version of the latest
release](https://noaa-fisheries-integrated-toolbox.r-universe.dev/FIMS)
is available from the instance of [R
universe](https://noaa-fisheries-integrated-toolbox.r-universe.dev)
hosted by NOAA Fisheries Integrated Toolbox. You can install the latest
version from GitHub.

``` r

# Install the pre-compiled version of the latest release
install.packages(
  "FIMS",
  repos = c(
    "https://noaa-fisheries-integrated-toolbox.r-universe.dev",
    "https://cloud.r-project.org"
  )
)

# Compile and install it yourself, where you can specify the branch
pak::pak("NOAA-FIMS/FIMS@main")
```

**Expand this section if you want to use `load_all()`**

Developers who are interested in building FIMS can clone this
repository, e.g., `git clone https://github.com/NOAA-FIMS/FIMS.git` and
build it with
[`devtools::install()`](https://devtools.r-lib.org/reference/install.html),
which builds the package from the cloned files and installs the R
library. Installing with
[`devtools::load_all()`](https://devtools.r-lib.org/reference/load_all.html)
is not recommended because it uses shim files for things like
[`system.file()`](https://rdrr.io/r/base/system.file.html), which can
cause FIMS to not function as expected. For example, if you try to
optimize the same model twice, you will more than likely not get
estimates of uncertainty from the second model run. Additionally,
[`devtools::load_all()`](https://devtools.r-lib.org/reference/load_all.html)
adds the debugger flag `-O0 -g` which leads to Windows users seeing
`Fatal error: can't write <xxx> bytes to section .text of FIMS.o: 'file too big`.
Thus, Windows users need to run
`withr::local_options(pkg.build_extra_flags = FALSE)` at the beginning
of every R session before calling
[`devtools::load_all()`](https://devtools.r-lib.org/reference/load_all.html).
If you want to compile FIMS with the debugger turned on you will need to
run the {withr} function in addition to manually modifying the call to
PKG_CXXFLAGS in the
[src/Makevars.win](https://github.com/NOAA-FIMS/FIMS/blob/main/src/Makevars.win)
file to include `-O1 -g`.

A comprehensive list of all the tools needed to build, test, and
document FIMS can be found
[here](https://github.com/nmfs-ost/on-off-boarding/blob/211d3895afb892ac2fba919935eb27d933e4d048/.github/workflows/onboard-fims.yml#L22).
Additionally, information on best practices regarding how to install
each requirement can be found on the [NOAA Fisheries Office of Science
and Technology on- and off-boarding
repository](https://nmfs-ost.github.io/on-off-boarding/).

## Cheatsheet

[![](https://raw.githubusercontent.com/noaa-fims/fims/main/pkgdown/assets/fims-cheatsheet-thumb.png)](https://github.com/NOAA-FIMS/FIMS/blob/main/pkgdown/assets/fims-cheatsheet.pdf)

## Usage

``` r

library(FIMS)
# Load sample data
data("data_big")
# Prepare data for FIMS model
data_4_model <- FIMSFrame(data_big)
# Run the  model with optimization
fit <- setup_default_parameters(data = data_4_model) |>
  initialize_fims(data = data_4_model) |>
  fit_fims(optimize = TRUE)
# Clear memory post-run
clear()
```

## Troubleshooting

If you encounter a 🐛, please file an
[Issue](https://github.com/NOAA-FIMS/FIMS/issues) with a minimal
reproducible example on GitHub.

If you are uncertain that you have actually encountered a 🐛, are
looking for more information, or want to talk about some new ideas
please use the [Discussion
Board](https://github.com/orgs/NOAA-FIMS/discussions) to post your
thoughts. Anyone interested in our project is welcome to join the
discussions, this is a place for **all** members of the assessment and
open-source software community to ask and answer questions, share
updates, have open-ended conversations, and follow along. Please
introduce yourself 👋 on the [Introduction
Discussion](https://github.com/orgs/NOAA-FIMS/discussions/801).

More information can be found on the [NOAA-FIMS
website](https://noaa-fims.github.io), particularly on [our
blog](https://noaa-fims.github.io/blog/).

## NOAA Disclaimer

This repository is a scientific product and is not official
communication of the National Oceanic and Atmospheric Administration, or
the United States Department of Commerce. All NOAA GitHub project code
is provided on an ‘as is’ basis and the user assumes responsibility for
its use. Any claims against the Department of Commerce or Department of
Commerce bureaus stemming from the use of this GitHub project will be
governed by all applicable Federal law. Any reference to specific
commercial products, processes, or services by service mark, trademark,
manufacturer, or otherwise, does not constitute or imply their
endorsement, recommendation or favoring by the Department of Commerce.
The Department of Commerce seal and logo, or the seal and logo of a DOC
bureau, shall not be used in any manner to imply endorsement of any
commercial product or activity by DOC or the United States Government.

Software code created by U.S. Government employees is not subject to
copyright in the United States (17 U.S.C. section 105). The United
States/Department of Commerce reserve all rights to seek and obtain
copyright protection in countries other than the United States for
Software authored in its entirety by the Department of Commerce. To this
end, the Department of Commerce hereby grants to Recipient a
royalty-free, nonexclusive license to use, copy, and create derivative
works of the Software outside of the United States.

------------------------------------------------------------------------

![NOAA
Fisheries](https://raw.githubusercontent.com/nmfs-general-modeling-tools/nmfspalette/main/man/figures/noaa-fisheries-rgb-2line-horizontal-small.png)

[U.S. Department of Commerce](https://www.commerce.gov/) \| [National
Oceanic and Atmospheric Administration](https://www.noaa.gov) \| [NOAA
Fisheries](https://www.fisheries.noaa.gov/)

# Package index

## Data

Example datasets used in demonstrations and other package data.

- [`data_big`](https://NOAA-FIMS.github.io/FIMS/reference/data_big.md) :
  FIMS input data frame
- [`fims_input_types`](https://NOAA-FIMS.github.io/FIMS/reference/fims_input_types.md)
  : Vector of acceptable FIMS input types
- [`fims_distributions`](https://NOAA-FIMS.github.io/FIMS/reference/fims_distributions.md)
  : Distribution parameter lookup table

## Run FIMS

Primary functions used when setting up or running a FIMS model.

- [`FIMSFrame()`](https://NOAA-FIMS.github.io/FIMS/reference/FIMSFrame.md)
  :

  Class constructors for `FIMSFrame` and associated child classes

- [`plot(`*`<FIMSFrame>`*`,`*`<missing>`*`)`](https://NOAA-FIMS.github.io/FIMS/reference/plot.md)
  :

  Plot a `FIMSFrame` object

- [`get_data()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFrame.md)
  [`get_fleets()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFrame.md)
  [`get_n_fleets()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFrame.md)
  [`get_n_years()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFrame.md)
  [`get_start_year()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFrame.md)
  [`get_end_year()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFrame.md)
  [`get_ages()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFrame.md)
  [`get_n_ages()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFrame.md)
  [`get_lengths()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFrame.md)
  [`get_n_lengths()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFrame.md)
  : Get a slot in a FIMSFrame object

- [`model_catch()`](https://NOAA-FIMS.github.io/FIMS/reference/model_.md)
  [`model_index()`](https://NOAA-FIMS.github.io/FIMS/reference/model_.md)
  [`model_age_comp()`](https://NOAA-FIMS.github.io/FIMS/reference/model_.md)
  [`model_length_comp()`](https://NOAA-FIMS.github.io/FIMS/reference/model_.md)
  [`model_weight_at_age()`](https://NOAA-FIMS.github.io/FIMS/reference/model_.md)
  [`model_age_to_length_conversion()`](https://NOAA-FIMS.github.io/FIMS/reference/model_.md)
  : Get a vector of data to be passed to a FIMS module from a FIMSFrame
  object

- [`setup_default_Fleet()`](https://NOAA-FIMS.github.io/FIMS/reference/setup_default_Fleet.md)
  : Set up default fleet parameters

- [`setup_default_Growth()`](https://NOAA-FIMS.github.io/FIMS/reference/setup_default_Growth.md)
  : Set up default growth parameters

- [`setup_default_Maturity()`](https://NOAA-FIMS.github.io/FIMS/reference/setup_default_Maturity.md)
  : Set up default maturity parameters

- [`setup_default_Population()`](https://NOAA-FIMS.github.io/FIMS/reference/setup_default_Population.md)
  : Set up default population parameters

- [`setup_default_Recruitment()`](https://NOAA-FIMS.github.io/FIMS/reference/setup_default_Recruitment.md)
  : Set up default recruitment parameters

- [`setup_default_Selectivity()`](https://NOAA-FIMS.github.io/FIMS/reference/setup_default_Selectivity.md)
  : Set up default selectivity parameters

- [`setup_default_parameters()`](https://NOAA-FIMS.github.io/FIMS/reference/setup_default_parameters.md)
  : Set up default parameters for a FIMS model

- [`initialize_data_distribution()`](https://NOAA-FIMS.github.io/FIMS/reference/initialize_data_distribution.md)
  : Set up a new distribution for a data type

- [`initialize_process_distribution()`](https://NOAA-FIMS.github.io/FIMS/reference/initialize_process_distribution.md)
  [`initialize_process_structure()`](https://NOAA-FIMS.github.io/FIMS/reference/initialize_process_distribution.md)
  : Set up a new distribution for a process

- [`lognormal()`](https://NOAA-FIMS.github.io/FIMS/reference/lognormal.md)
  [`multinomial()`](https://NOAA-FIMS.github.io/FIMS/reference/lognormal.md)
  : Distributions not available in the stats package

- [`initialize_fims()`](https://NOAA-FIMS.github.io/FIMS/reference/initialize_fims.md)
  : Initialize C++ modules via Rcpp for a FIMS model

- [`FIMSFit()`](https://NOAA-FIMS.github.io/FIMS/reference/FIMSFit.md) :

  Class constructors for class `FIMSFit` and associated child classes

- [`fit_fims()`](https://NOAA-FIMS.github.io/FIMS/reference/fit_fims.md)
  : Fit a FIMS model (BETA)

- [`get_input()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFit.md)
  [`get_report()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFit.md)
  [`get_obj()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFit.md)
  [`get_opt()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFit.md)
  [`get_max_gradient()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFit.md)
  [`get_gradient()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFit.md)
  [`get_sdreport()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFit.md)
  [`get_estimates()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFit.md)
  [`get_number_of_parameters()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFit.md)
  [`get_run_time()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFit.md)
  [`get_version()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFit.md)
  [`get_model_output()`](https://NOAA-FIMS.github.io/FIMS/reference/get_FIMSFit.md)
  : Get a slot in a FIMSFit object

- [`is.FIMSFit()`](https://NOAA-FIMS.github.io/FIMS/reference/is.FIMSFit.md)
  : Check if an object is of class FIMSFit

- [`is_fims_verbose()`](https://NOAA-FIMS.github.io/FIMS/reference/is_fims_verbose.md)
  : Should FIMS be verbose?

## Diagnostics

Primary functions used when diagnosing a FIMS model.

- [`calculate_mohns_rho()`](https://NOAA-FIMS.github.io/FIMS/reference/calculate_mohns_rho.md)
  : Calculate Mohn's rho for retrospective analysis
- [`plot_likelihood()`](https://NOAA-FIMS.github.io/FIMS/reference/plot_likelihood.md)
  : Plot Likelihood Profile
- [`run_fims_likelihood()`](https://NOAA-FIMS.github.io/FIMS/reference/run_fims_likelihood.md)
  : Run Likelihood Profile
- [`run_fims_retrospective()`](https://NOAA-FIMS.github.io/FIMS/reference/run_fims_retrospective.md)
  : Run Retrospective Analysis
- [`run_modified_data_fims()`](https://NOAA-FIMS.github.io/FIMS/reference/run_modified_data_fims.md)
  : Modify data for a FIMS Model
- [`run_modified_pars_fims()`](https://NOAA-FIMS.github.io/FIMS/reference/run_modified_pars_fims.md)
  : Modify Parameters of a FIMS Model

## Package development

Primary functions used when developing FIMS package.

- [`remove_test_data()`](https://NOAA-FIMS.github.io/FIMS/reference/remove_test_data.md)
  : Remove test data
- [`run_gtest()`](https://NOAA-FIMS.github.io/FIMS/reference/run_gtest.md)
  : Run the google test suite
- [`run_r_integration_tests()`](https://NOAA-FIMS.github.io/FIMS/reference/run_r_integration_tests.md)
  : Run R integration tests
- [`run_r_unit_tests()`](https://NOAA-FIMS.github.io/FIMS/reference/run_r_unit_tests.md)
  : Run R unit tests
- [`setup_and_run_gtest()`](https://NOAA-FIMS.github.io/FIMS/reference/setup_and_run_gtest.md)
  : Setup and run the google test suite
- [`setup_gtest()`](https://NOAA-FIMS.github.io/FIMS/reference/setup_gtest.md)
  : Set up your local environment to run the google tests locally
- [`use_google_benchmark_template()`](https://NOAA-FIMS.github.io/FIMS/reference/use_google_benchmark_template.md)
  : Create tests/google_benchmark/benchmark\_\*.cpp and register it in
  CMakeLists.txt
- [`use_gtest_template()`](https://NOAA-FIMS.github.io/FIMS/reference/use_gtest_template.md)
  : Create tests/gtest/test\_\*.cpp test file and register it in
  CMakeLists.txt
- [`use_testthat_template()`](https://NOAA-FIMS.github.io/FIMS/reference/use_testthat_template.md)
  : Create tests/testthat/test-\*.R test file
- [`reshape_json_estimates()`](https://NOAA-FIMS.github.io/FIMS/reference/reshape_json_estimates.md)
  : Reshape JSON estimates
- [`reshape_tmb_estimates()`](https://NOAA-FIMS.github.io/FIMS/reference/reshape_tmb_estimates.md)
  : Reshape TMB estimates

## Exported C++ functions and classes

Links to the relevant doxygen documentation for the C++ code.

- [`Cpp_classes`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`AgeComp`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`BevertonHoltRecruitment`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`CatchAtAge`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`DlnormDistribution`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`DmultinomDistribution`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`DnormDistribution`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`DoubleLogisticSelectivity`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`EWAAGrowth`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`VonBertalanffySchnuteGrowth`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`Fleet`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`Index`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`Catch`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`LengthComp`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`LogDevsRecruitmentProcess`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`LogRRecruitmentProcess`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`LogisticMaturity`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`LogisticSelectivity`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`Variable`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`VariableVector`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`Population`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`RealVector`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`SharedInt`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`SharedReal`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  [`SharedString`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_classes.md)
  : C++ Classes Exported via Rcpp
- [`Cpp_functions`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  [`clear`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  [`get_fixed`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  [`get_log`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  [`get_log_errors`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  [`get_log_warnings`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  [`get_parameter_names`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  [`get_random`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  [`get_random_names`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  [`inv_logit`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  [`log_error`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  [`log_info`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  [`log_warning`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  [`logit`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  [`set_fixed`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  [`set_log_throw_on_error`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  [`set_random`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  [`CreateTMBModel`](https://NOAA-FIMS.github.io/FIMS/reference/Cpp_functions.md)
  : C++ Functions Exported via Rcpp

## Model Tidying and Fit Evaluation

Functions used to extract, tidy, and evaluate model fit results.

- [`augment(`*`<FIMSFit>`*`)`](https://NOAA-FIMS.github.io/FIMS/reference/augment.FIMSFit.md)
  : Augment a FIMSFit object for use with yardstick
- [`get_fit_metrics()`](https://NOAA-FIMS.github.io/FIMS/reference/get_fit_metrics.md)
  : Compute yardstick metrics for a fitted FIMS model
- [`get_fit_stream()`](https://NOAA-FIMS.github.io/FIMS/reference/get_fit_stream.md)
  : Extract a single data stream from a FIMSFit augmented tibble
- [`glance(`*`<FIMSFit>`*`)`](https://NOAA-FIMS.github.io/FIMS/reference/glance.FIMSFit.md)
  : Glance at a FIMSFit object - one-row model summary
- [`tidy(`*`<FIMSFit>`*`)`](https://NOAA-FIMS.github.io/FIMS/reference/tidy.FIMSFit.md)
  : Tidy a FIMSFit object into a parameter-level tibble

# Articles

### All vignettes

- [Adding a New C++
  Module](https://NOAA-FIMS.github.io/FIMS/articles/adding-new-module.md):
- [Simple projections using
  FIMS](https://NOAA-FIMS.github.io/FIMS/articles/fims-demo-projections.md):
- [Introducing the Fisheries Integrated Modeling System
  (FIMS)](https://NOAA-FIMS.github.io/FIMS/articles/fims-demo.md):
- [Running diagnostics on a FIMS
  model](https://NOAA-FIMS.github.io/FIMS/articles/fims-diagnostics.md):
- [FIMS Growth With
  VonBertalanffySchnute](https://NOAA-FIMS.github.io/FIMS/articles/fims-growth-vonb-schnute.md):
- [Introducing FIMS input
  data](https://NOAA-FIMS.github.io/FIMS/articles/fims-input-data.md):
- [Introducing the FIMS Logging
  System](https://NOAA-FIMS.github.io/FIMS/articles/fims-logging.md):
- [FIMS Path:
  Maturity](https://NOAA-FIMS.github.io/FIMS/articles/fims-path-maturity.md):
- [FIMS User Setup
  Guide](https://NOAA-FIMS.github.io/FIMS/articles/fims-user-setup-guide.md):
- [RE
  Sparsity](https://NOAA-FIMS.github.io/FIMS/articles/RD-re-sparsity.md):
- [Intro to
  C++](https://NOAA-FIMS.github.io/FIMS/articles/training-intro-cpp.md):
- [Intro to
  Rcpp](https://NOAA-FIMS.github.io/FIMS/articles/training-intro-rcpp.md):