---
title: "aLBI - A Simple R Package for Estimating Length-Based Indicators and Fish Stock Assessment from Length Frequency Data"
author: "Ataher Ali"
date: "`r Sys.Date()`"
output: html_vignette
vignette: >
  %\VignetteIndexEntry{aLBI - A Simple R Package for Estimating Length-Based Indicators and Fish Stock Assessment from Length Frequency Data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

# aLBI: A Simple R Package for Fish Stock Assessment

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  cache = TRUE # Ensure caching is appropriately set
)

options(repos = c(CRAN = "https://cran.rstudio.com"))

# Load the aLBI package (required for vignette to access functions)
library(aLBI)

# Suppress warnings during vignette build for cleaner output
suppressPackageStartupMessages(library(dplyr))
suppressPackageStartupMessages(library(readxl))
suppressPackageStartupMessages(library(ggplot2))
suppressPackageStartupMessages(library(stats))
suppressPackageStartupMessages(library(rlang))
```

## Introduction
The `aLBI` package provides tools for estimating life history parameters, length-based indicators, and assessing fish stock using methods outlined by Cope and Punt (2009) and Froese (2004). These methods are particularly useful in data-limited situations and for providing simple indicators to address over-fishing and support sustainable fisheries management. This simple package facilitates the estimation of life history parameters of fish only from the length frequency data. Version 0.1.9 introduces the `LWR` function for length-weight relationship analysis and `FreqMT` for constructing frequency table for length data of multiple months. This version also updates `FrequencyTable`, `FsihPar` and `FishSS` with enhanced functionality. These includes the addition Monte Carlo,  non-parametric bootstrapping, decision making based on selectivity and saving of outputs to the current working directory.

## Function Overview
The aLBI package offers three primary functions:
- **FrequencyTable**: Creates a frequency distribution table for fish length data using either a custom bin width or Wang's formula for automatic bin width calculation. The bin width is rounded to the nearest integer if calculated.
- **FreqTM**: Creates frequency table for fish length of multiple months using either a custom bin width or Wang's formula as described in `FrequencyTable` function.
- **FishPar**: This function calculates length-based indicators using Monte Carlo simulation for length parameters and non-parametric bootstrap for Froese indicators.
- **FishSS**: This function assesses the stock status based on parameters calculated by the FishPar function.
- **LWR**: Fits and visualizes length-weight relationships using linear regression.

### Methods
The package includes functions to calculate various length-based indicators and visualize fish stock data. The approaches from Cope and Punt (2009) are used to establish reference points, while Froese (2004)'s indicators help to evaluate over-fishing status and selectivity. This vignette demonstrates how to use these functions with sample and provided data.

### Installation
To install the aLBI package from CRAN or GitHub. To enjoy most recent updates, users are encouraged to install the aLBI  from GitHub), follow these steps. Note that devtools is required to install packages from GitHub.
```{r installing_package }
# You can install the package using the following commands in your R session:
# Install devtools if you haven't already
# install.packages("devtools")
# # Install dplyr if you haven't already
# install.packages("dplyr")
# # Install readxl if you haven't already
# install.packages("readxl")
# Install ggplot2 if you haven't already
# install.packages("ggplot2")
# Install openxlsx if you haven't already
# install.packages("openxlsx")
# Install rlang if you haven't already
# install.packages("rlang")
# install aLBI package from CRAN
# install.packages("aLBI")
# Install the most updated version of aLBI package from GitHub
# devtools::install_github("Ataher76/aLBI")

```

### Package Management
Ensure the required packages are loaded in your R session. The following code checks for package availability and stops execution with a message if a package is missing.
```{r package_management }
# Check if required packages are installed and load them
# Check if required packages are installed and load them
required_packages <- c("aLBI", "readxl", "openxlsx", "dplyr", "devtools", "ggplot2", "rlang")

for (pkg in required_packages) {
  if (!requireNamespace(pkg, quietly = TRUE)) {
    warning(paste("Package", pkg, "is required but not installed."))
  } else {
    library(pkg, character.only = TRUE)
  }
}


# Load the aLBI package
library(aLBI)
library(readxl)
library(dplyr)
library(ggplot2)
library(openxlsx)
library(rlang)
library(devtools)
```


### Data Preparation for Functions
Prepare your collected data in a specific format (.xlsx or .csv) before using the functions. Here's an example of how to load and prepare your data using the readxl package:

## Function (i): FrequencyTable
**FrequencyTable** function will generates the frequency table from the collected length data by calculated optimum bin size or user defined bin size. It also allows the user to provide Lmax from reliable sources such as **FishBase** or empirical studies. The function extract the length frequency data from the frequency table with the upper length_range and allow users to save the frequency data as an excel file for further use in the **FishPar** function.

### Arguments

- **data**: A numeric vector or data frame containing fish length measurements. If a data frame is provided, the first numeric column is used.

- **bin_width**: Optional. A numeric value specifying the bin width for class intervals, if left NULL or if not provided, the bin width is automatically calculated using Wang et al. (2020) optimum bin size (OBS) formula formula.

- **Lmax**: Optional. The maximum observed length of fish. Required only if `bin_width` is NULL and Wang's formula is used. If not provided or left NULL then automatically calculate the frequency table with the observed maximum length of the provided data.

- **output_file**: Optional. Character string specifying the output Excel file name. Defaults to "FrequencyTable_Output.xlsx".

```{r data_preparation for FrequencyTable}
library(readxl)
# Load your length data from the system file
lenfreq_path <- system.file("exdata", "ExData.xlsx", package = "aLBI")
print(lenfreq_path)  # Check the generated path

if (lenfreq_path == "") {
  stop("The required file ExData.xlsx is missing. Please check the inst/extdata directory.")
}

# load the lenght frequency data
lenght_data <- readxl::read_excel(lenfreq_path)
print(lenght_data)  # check the 
# replace with your data directory


```


```{r FrequencyTable_Output}
# Running the FrequencyTable function
freqTable <- FrequencyTable(data = lenght_data, bin_width = NULL, Lmax = NULL, output_file = "FrequencyTable_Output.xlsx")

# Viewing the results
freqTable$lfqTable  # Display the frequency table
freqTable$lfreq     # Display the summarized frequencies with upper length ranges

```


## Function (ii): FreqTM
**FreqTM** Creates a frequency distribution table for fish length data across multiple months using a consistent length class structure. The bin width is determined by either a custom value or Wang's formula, applied uniformly across all months. The function dynamically detects and renames columns to 'Month' and 'Length' from the input dataframe. The maximum observed length is included as part of the last class, with the upper bound set to the smallest multiple of the bin width greater than or equal to the maximum length. Months can be converted to dates using a configurable day and year, with dates assigned sequentially in 'day.month.year' format (e.g., 15.01.26).

### Arguments

- **data**: A data frame containing columns for months and lengths (names can vary, e.g., 'Month', 'Length', or any other names).

- **bin_width**: Optional. A numeric value specifying the bin width for class intervals, if left NULL or if not provided, the bin width is automatically calculated using Wang et al. (2020) optimum bin size (OBS) formula formula.

- **Lmax**: Optional. The maximum observed length of fish. Required only if `bin_width` is NULL and Wang's formula is used. If not provided or left NULL then automatically calculate the frequency table with the observed maximum length of the provided data.

- **date_config** A list with elements `day` (default 1) and `year` (default 2025) to set the day and year for converting month names to dates. The day must be between 1 and 31.

- **output_file**: Optional. Character string specifying the output Excel file name. Defaults to "FreqTM_Output.xlsx".




```{r data_preparation for FreqTM}
library(readxl)
# Load your length data from the system file
lenfreq_path <- system.file("exdata", "lenfreqM.xlsx", package = "aLBI")
print(lenfreq_path)  # Check the generated path

if (lenfreq_path == "") {
  stop("The required file lenfreqM.xlsx is missing. Please check the inst/extdata directory.")
}

# load the length frequency data of multiple months
lenght_dataM <- readxl::read_excel(lenfreq_path)
print(lenght_dataM)  # check the 
# replace with your data directory


```


```{r FreqTM_Output}
# Running the FrequencyTable function
freqTableM <- FreqTM(data = lenght_dataM, bin_width = NULL, Lmax = NULL, output_file = "FreqTM.xlsx")

# Viewing the results
freqTableM

```




## Function (iii): FishPar
The **FishPar** function estimates life history parameters (e.g., Lmax, Linf, Lmat, and Lopt) using Monte Carlo Simulation and Froese Sustainability Indicators using non-parametric bootstrapping method.

### Arguments
- **data**: A data frame containing two columns: Length and Frequency.
- **resample**: An integer indicating the number of Monte Carlo samples or bootstrap resamples (default: 1000).
- **progress**: A logical value indicating whether to display a progress bar (default: FALSE).
- **Linf**: A numeric value for the asymptotic length (optional). If provided, overrides the default Lmax/0.95 calculation.
- **Linf_sd**: A numeric value for the standard deviation of random variation added to Linf (default: 0.5). Only used if Linf is provided.
- **Lmat**: A numeric value for the length at maturity (optional). If provided, overrides the default Monte Carlo estimation.
- **Lmat_sd**: A numeric value for the standard deviation of random variation added to Lmat (default: 0.5). Only used if Lmat is provided.


### Example with existing data

```{r data_example}
library(readxl)
# Load your length-frequency data from the system file
lenfreq_path <- system.file("exdata", "LC.xlsx", package = "aLBI")
print(lenfreq_path)  # Check the generated path

if (lenfreq_path == "") {
  stop("The required file LC.xlsx is missing. Please check the inst/extdata directory.")
}

# load the lenght frequency data
lenfreq_data <- readxl::read_excel(lenfreq_path)
print(lenfreq_data)  # check the data 
# replace with your data directory
```


```{r FishPar_Output}
# Running the FishPar function
results <- FishPar(data = lenfreq_data, resample = 1000, progress = FALSE, Linf = NULL, Linf_sd = 0.5, Lmat = NULL, Lmat_sd = 0.5)

# Viewing the results
results$estimated_length_par
results$estimated_froese_par
results$forese_ind_vs_target
results$Total_ind
results$LM_ratio
results$Pobj

```

### Explaination of Output
The function returns a list with the following components saved in three different sheet of excel file:

- **estimated_length_par**: Data frame of estimated length parameters with confidence intervals.
- **estimated_froese_par**: Data frame of estimated Froese indicators.
- **forese_ind_vs_target**: Data frame comparing Froese indicators with targets.
- **LM_ratio**: Length at first sexual maturity and optimum length ratio (LM_ratio = Lmat/Lopt).
- **Pobj**: Objective percentage combining Pmat, Popt, and Pmega.
- **Total_ind**: Number of total sampled individuals.


## Function (iv): FishSS
The **FishSS** function evaluates stock status using criteria based on the estimated parameters by FishPar.

### Arguments
- **data**: A data frame containing the necessary columns for stock status calculation according to Cope and Punt (2009).
- **LM_ratio**: A numeric value representing the length at first sexual maturity (Lmat) and Optimum length (Lopt) ratio.
- **Pmat**: A numeric value representing the percentage of mature fish.
- **Popt**: A numeric value representing the percentage of optimally sized fish.
- **Pmega**: A numeric value representing the percentage of megaspawner.

### Example with CPdata

```{r FishSS_Example}
# Load the stock status criteria data
cpdata_path <- system.file("exdata", "cpdata.xlsx", package = "aLBI")
print(cpdata_path) #check if the path exist

if (cpdata_path == "") {
  stop("The required file cpdata.xlsx is missing. Please check the inst/extdata directory.")
}
# loading the cope and punt table
cpdata <- readxl::read_excel(cpdata_path)
print(cpdata)

# Running the FishSS function
stock_status <- FishSS(data = cpdata,
                       LM_ratio = results$LM_ratio,
                       Pmat = results$estimated_froese_par[1, 2],
                       Popt = results$estimated_froese_par[2, 2],
                       Pmega = results$estimated_froese_par[3,2]
                       )

# Viewing the stock status
stock_status

```


### Output
The function returns a named vector with TSB40 and LSB25 values indicating stock status, and selectivity of the fishing practice.


## Function (iv): LWR
The **LWR** This function visualizes and models the relationship between length and weight (or any two continuous variables) using linear regression. It supports both standard and log-transformed models, producing a ggplot2-based plot with a fitted line, optional confidence interval shading, and annotations for the regression equation, R², and p-value. When save_output is TRUE, the plot and model summary are saved to the current working directory as a PDF and text file, respectively.

### Arguments
- **data**: A data frame with two columns: the first for length, the second for weight.
- **log_transform**: Logical. Whether to apply a log-log transformation to the variables. Default is TRUE.
- **point_col**: Color of the data points. Default is black.
- **line_col**: Color of the regression line. Default is red.
- **shade_col**: Color for the confidence interval ribbon. Default is red.
- **point_size**: Size of the data points. Default is 2.
- **line_size**: Size of the regression line. Default is 1.
- **alpha**: Transparency for the confidence interval ribbon. Default is 0.2.
- **main**: Title of the plot. Default is "Length-Weight Relationship".
- **xlab**: Optional. Custom x-axis label. If \code{NULL}, a label is generated based on log_transform.
- **ylab**: Optional. Custom y-axis label. If \code{NULL}, a label is generated based on on log_transform.
- **save_output**: Logical. Whether to save the plot as a PDF and the model summary as a text file in the working directory. Default is TRUE.

### Example with existing LWdata

```{r LWR_Example}
# Load the stock status criteria data
LWdata_path <- system.file("exdata", "LWdata.xlsx", package = "aLBI")
print(LWdata_path) #check if the path exist

if (LWdata_path == "") {
  stop("The required file LWdata.xlsx is missing. Please check the inst/extdata directory.")
}
# loading the cope and punt table
LWdata <- readxl::read_excel(LWdata_path)
print(LWdata)

# Running the LWR function
lwr_result <- LWR(data = LWdata,
                log_transform = TRUE,
                point_col = "black",
                line_col = "red",
                shade_col = "red",
                point_size = 2,
                line_size = 1,
                alpha = 0.2,
                main = "Length-Weight Relationship",
                xlab = NULL,
                ylab = NULL,
                save_output = TRUE)

# Viewing the stock status
lwr_result

```


### Output
Length-Weight plot with model summery


## Conclusion
The Fish Stock Assessment package provides a robust framework for estimating biological parameters and assessing fish stock status. By following the steps outlined in this vignette, you can effectively utilize this package for your fish stock assessment needs.


## Acknowledgements
I would like to express my heartfelt gratitude to my supervisor, **Dr. Mohammed Shahidul Alam**, for his unwavering guidance, support, and encouragement. I am also sincerely thankful to the contributors and community members for their valuable feedback and support.

This vignette provides a comprehensive guide to using the Assessment package. By following these instructions, users can effectively conduct fish stock assessments and contribute to sustainable fishery management practices.

## To read more detail 
Readers are encouraged to read the article published in *Fisheries Research* of this `aLBI` R Package to understand the functionality and methodolgy.

- Ali, A., Sarker, M. R., & Alam, M. S. (2025). Development of a simple R package (aLBI) for the estimation of stock status from the length frequency data. *Fisheries Research*, 288, 107467. https://doi.org/10.1016/j.fishres.2025.107467

## References

- Wang, K., Zhang, C., Xu, B., Xue, Y., & Ren, Y. (2020). Selecting optimal bin size to account for growth variability in Electronic LEngth Frequency ANalysis (ELEFAN). *Fisheries Research*, 225, 105474. https://doi.org/10.1016/j.fishres.2019.105474

- Cope, J. M., & Punt, A. E. (2009). Length‐Based Reference Points for Data‐Limited Situations: Applications and Restrictions. *Marine and Coastal Fisheries*, 1(1), 169–186. https://doi.org/10.1577/C08-025.1

- Froese, R. (2004). Keep it simple: Three indicators to deal with overfishing. *Fish and Fisheries*, 5(1), 86–91. https://doi.org/10.1111/j.1467-2979.2004.00144.x


## Additional Information
### Contact package maintainer for any questions or issues
- **Name**: Ataher Ali
- **E-mail**: ataher.cu.ms@gmail.com
