Docs(#43): compare comlandr stocksmart

[MGrezlik]

🐟

Justification

Issue #43 highlighted significant discrepancies between comlandr landings and StockSMART total catch across several key species (including haddock, and black sea bass). The working hypotheses were that these gaps are driven by commercial discards, missing recreational landings, or geographic mismatches.

To properly investigate this, this PR introduces a robust comparative script (compare_comlandr_stocksmart.R) that:

1. Standardizes both datasets, grouping complex species (e.g., the skate complex) and explicitly dropping foreign landings from comlandr.
2. Dynamically converts complex StockSMART units (e.g., "Thousand lbs", "kg") into Metric Tons for direct comparisons.
3. Generates comprehensive visual and tabular outputs that separate comlandr landings from comlandr total catch (landings + discards), allowing us to clearly see where discards explain the gap (e.g., Haddock) and where missing recreational/state catch is likely the culprit (e.g., Black Sea Bass).

Types of changes

What types of changes does this pull request introduce? Put an x in the boxes that apply.
This will inform the new release number.

• Fix (non-breaking change which fixes a bug)
• Feature (non-breaking change which adds or changes functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Other change (if none of the other choices apply)

Further comments

This script incorporates several major data-cleaning upgrades to ensure accuracy:

• stocksmart v1.1.11 Compatibility: The script was updated to handle the new snake_case column names introduced in the latest major release of stocksmart. Upgrading to this version also resolved a database truncation issue where Mid-Atlantic Black Sea Bass data prior to 1989 was missing.
• Unit Conversions: Implemented a highly defensive case_when block to mathematically convert regional reporting units (like SEDAR's "Thousand lbs") into Metric Tons.
• Visual Outlier Capping: To prevent massive single-year discard spikes from flattening the visualizations, the ggplot y-axes are dynamically capped at 1.5x the maximum StockSMART catch for each species.
• Targeted Overage Isolation: The script outputs a specific issue43_comlandr_overages.csv table that calculates Landings_Difference_mt and Total_Difference_mt to quickly identify the worst-offending species where comlandr landings inexplicably exceed stock assessment totals.

Reviewer instructions

Assign at least 2 reviewers:

• one of which should be a maintainer of this repo,
• the others should be familiar with the subject or problem.

To test these changes and review the outputs, please pull down the branch and execute the script:

# 1. Ensure you have the latest version of stocksmart installed
# remotes::install_github("NOAA-EDAB/stocksmart")

# 2. Source the comparison script
source("data-raw/compare_comlandr_stocksmart.R")

Check the generated outputs in the data-raw/ folder:

• issue43_hypothesis_test.pdf: Review the faceted plots. Note how the gap between Line 2 (Comlandr Total) and Line 3 (Stock SMART) highlights missing recreational data.
• issue43_catch_comparison_table.csv: The master data table mapping the exact differences.
• issue43_comlandr_overages.csv: A filtered table sorted to show where comlandr landings exceed assessment catch.

Formatting

This repo contains an air.toml file that automatically formats code to a set of standards.
It is preferred that contributors and reviewers install the Air formatting tool.
Code submitted in this pull request will be automatically checked for correct formatting.

[github-actions]

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

air

---

[air] _{reported by reviewdog 🐶}

comlandr/data-raw/compare_comlandr_stocksmart.R

Lines 244 to 246 in a3c2ae4

	Percent_Diff = if_else(SS_Total_Catch_mt > 0,
	(Total_Difference_mt / SS_Total_Catch_mt) * 100,
	NA_real_)

---

[air] _{reported by reviewdog 🐶}

comlandr/data-raw/compare_comlandr_stocksmart.R

Lines 252 to 254 in a3c2ae4

	`Comlandr_Landings_mt` = Com_Landings_mt,
	`Comlandr_Discards_mt` = Com_Discards_mt,
	`Comlandr_Total_Com_mt` = Com_Total_Catch_mt,

---

[air] _{reported by reviewdog 🐶}

comlandr/data-raw/compare_comlandr_stocksmart.R

Line 259 in a3c2ae4

mutate(across(where(is.numeric), ~round(., 1))) |>

---

[air] _{reported by reviewdog 🐶}

comlandr/data-raw/compare_comlandr_stocksmart.R

Line 275 in a3c2ae4

message(sprintf("Found %d instances where comlandr landings exceed StockSMART catch. Saved to %s", nrow(comlandr_overages), overage_path))

[BBeltz1]

@MGrezlik the formatting error failing these checks is in a file unrelated to your work. It has been resolved elsewhere, and can be ignored. Feel free to ignore the failed checks, and proceed as usual.

[MGrezlik]

Final comparison plots of landings

[andybeet]

This all looks good. I am curious as to how you selected the 18 species (one being the skate complex). If i look at the suite of species in stocksmart in the Northeast Shelf regional ecosystem, i see 30 ish species. But i also don't see species like Cobia and swordfish, that you did include eg.

itis_codes <- stocksmart::stock_assessment_summary |>
  dplyr::filter(grepl("Northeast Shelf",regional_ecosystem)) |> 
  dplyr::distinct(stock_name,itis) |> 
  dplyr::pull(itis) |> 
  unique()

comlandr::get_species_itis(channel,itis_codes)$data |>
  dplyr::distinct(SPECIES_ITIS,COMMON_NAME)

[MGrezlik]

@andybeet

The current method pulls all landings from comlandr and all assessments from stocksmart. It joins the two pulls based on species common names which occur in both sets. clean_cfdbs_names(), starting in line 91, fixes the name mismatches I noticed while going through. I could expand that list to make sure we are capturing all managed species

[andybeet]

This works for now Max. Thanks

[BBeltz1]

this looks good to me, @MGrezlik thanks again for entertaining our requests!