---
title: "Using artfishr for Small-Scale Fisheries Estimation"
output:
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 2
vignette: >
  %\VignetteIndexEntry{Using artfishr for Small-Scale Fisheries Estimation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = TRUE
)
library(artfishr)
```

# Introduction

This vignette demonstrates how to apply the **ARTFISH methodology** for estimating fisheries catch and effort, and related indicators using the `artfishr` R package. This methodology aims to extrapolate sample-based observations to produce total estimates for each stratum of the sample.

The vignette walks through each computation step and shows how to use the unified workflow function `artfish_compute_report()`, which automates the full estimation process.

# Data preparation

The package includes example datasets stored under `inst/extdata/samples/`.

Let's load them using `system.file()`:

```{r load-samples}
active_vessels <- readr::read_csv(
  system.file("extdata/samples", "active_vessels.csv", package = "artfishr")
)

effort <- readr::read_csv(
  system.file("extdata/samples", "effort_fisher_interview.csv", package = "artfishr")
)

active_days <- readr::read_csv(
  system.file("extdata/samples", "active_days.csv", package = "artfishr")
)

landings <- readr::read_csv(
  system.file("extdata/samples", "landings.csv", package = "artfishr")
)
```

The Following datasets are required to produce the estimates:
  -	**Active vessels:** number of active vessels per stratum (or per landing site)
  -	**Active days:** number of days in the month recording a fishing activity
  -	**Effort survey data:** fisher interviews or boat counting
  -	**Landings data:** catch by species for each observed fishing trip
For more information on the data structure, refer to the example datasets and to the data validation requirements.


# Identify data collection strategy

(to complete with different cases + schema)

Different cases are listed above, depending on the different data sources. The effort survey type (fisher interview or boat counting) must be indicated in the function to use the correct computation. In case of boat counting, the dataset active_days is mandatory.

# Step-by-step ARTFISH workflow

Below is the detailed workflow showing each function used by `artfishr` to compute the various ARTFISH components.

Indicators are computed for each stratum of the sampling plan. Major and minor strata must be specified in the function to define the level of aggregation.

## 1. Effort Activity Coefficient

The activity coefficient represents the probability that a certain boat is out on a certain day. It is obtained with the effort survey using either fisher interviews or boat counts. 

```{r activity-coeff}
activity_coefficient <- artfishr::compute_effort_activity_coefficient(
  effort = effort,
  effort_source = "fisher_interview",
  minor_strata = "minor_stratum"
)
```

## 2. Effort Estimate

Effort estimate calculation is based on the three components active vessels, active days and activity coefficient.

$$
Effort =
ActiveVessels \times
ActiveDays \times
ActivityCoefficient
$$

```{r effort-estimate}
effort_estimate <- artfishr::compute_effort_estimate(
  active_vessels = active_vessels,
  active_vessels_strategy = "latest",
  landings = landings,
  effort = effort,
  effort_source = "fisher_interview",
  active_days = active_days,
  minor_strata = "minor_stratum"
)
```

## 3. Catch per Unit of Effort (CPUE)

CPUE is calculated with the landing survey data. For each stratum, the overall average CPUE is calculated.

```{r cpue}
cpue <- artfishr::compute_cpue(
  landings,
  minor_strata = "minor_stratum"
)
```

## 4. Catch Estimate

Catch estimate calculation is based on the formula: 

$$
Catch = CPUE \times Effort
$$

```{r catch-estimate}
catch_estimate <- artfishr::compute_catch_estimate(
  effort_estimate,
  landings = landings,
  minor_strata = "minor_stratum"
)
```

## 5. Catch Estimate by Species

Catch estimates by species are obtained by distributing the estimated total catch according to the observed species composition within each stratum.

```{r catch-by-species}
catch_estimate_by_species <- artfishr::compute_catch_estimates_by_species(
  landings,
  catch_estimate,
  minor_strata = "minor_stratum"
)
```

# Using the unified workflow

The individual steps above are integrated into a single convenience function:  
`artfish_compute_report()`.  
This function executes the complete workflow, returning a structured report that includes all intermediate and final results.

```{r report}
report <- artfishr::compute_report(
  active_vessels = active_vessels,
  effort = effort,
  effort_source = "fisher_interview",
  active_days = active_days,
  active_vessels_strategy = "closest",
  landings = landings,
  minor_strata = "minor_stratum"
)

# Inspect report structure
str(report, max.level = 1)
```

# Interpreting results

Each component of the output can be inspected individually:

```{r view-results}
head(effort_estimate)
head(catch_estimate_by_species)
```

# Summary

This vignette illustrated:

* The **data requirements** for ARTFISH (active vessels, effort, active days, landings)  
* The **sequential workflow** used to compute all indicators manually  
* The **integrated workflow** provided by `artfish_compute_report()` for convenience  

For production use, users should adapt the workflow to their own datasets, ensuring that data formats comply with the specifications in `inst/extdata/format_specs/`.