Part1, Addendum and Artisanal Report Templates

This repository maintains the pipeline to generate Part 1, Addendum and Artisanal reports using .qmd (Quarto) templates.

To get started, follow the Setup Instructions below, then run main.R where the key parameters (defined in Step 2) include:

• country_codes — 2-letter country codes for which reports will be generated. You must have T2 data access permissions for each country.

• r_year — reporting year

• rewrite_files — if TRUE, all T2 and Ikasavea data are re-downloaded from source; if FALSE, existing files in data/ are reused (only missing files are downloaded)

• reports_list — controls which report types are generated (part1, addendum, artisanal)

• aceman — If TRUE, ACE data generated by your country (usually during TDW, available in T2 report 3619) will be used in the reports. If FALSE the report will use data from yearbook (T2 report 3605) which includesall data from last 5 years (if available) and after species composition (sually available around August of every year).

Output reports are saved to the reports/ folder and all data used to generate them are in data/. The diagram below summarises the full pipeline.

Setup Instructions

1. Copy the envtemplate file to create a new file named .env

2. Add your Tufman 2 and Ikasavea password to the .env file:

   USER_NAME=your_user_name_here
   TUF_PASSWORD=your_password_here
   IKA_USER_NAME=your_user_name_here
   IKA_PASSWORD=your_password_here
   

3. Ensure there's an empty line at the end of the .env file

4. Important: Never commit the .env file to version control. To ensure that is the case and .env files to your .gitignore file. Files with the .env extension will be ignored when synced to the repo (it will only remain on your machine).

5. Open script main.R and make sure all packages are installed

6. Go to Step 2 section in main.R and define the parameters for your case (the most important one is to set up country_codes to the two-letter code of your country)

7. Run main.R - this will "download" all T2 data required for Part 1 as well as generate Part 1, addendum and artisinal reports

Include narratives

All maps, figures and tables are automatically generated, but you can add custom narratives to provide context.

How you do this depends on where the narrative sits in the .qmd template:

• Free text sections:: .qmd files have a plain text block directly above the code chunk. Simply find the relevant section in the .qmd and type your text there.

• Inside a render_ function (only in template_part1.qmd): For results generated by a render_function, edit the intro_text which is an argument inside the code chunk. This text supports markdown formatting and inline references such as {country_name} and cross-references (e.g., refering to a table or figure number in the text).

For example:

render_gear_tbl_section3(
  ...,
  intro_text = "The annual catches of the **primary species** caught by the 
  {country_name} purse seine fleet are shown in @tbl-tbl1s.
  
  *Note:* This includes all catches in the WCPFC Convention Area."
)

To find the right place to edit, use the Quarto label (e.g. tbl-tbl1s) from the data sources table below to locate the corresponding chunk in the .qmd.

Data used to produce the reports

All tables, figures and maps presented in the report template are based on data available in T2 and Ikasavea reports.

The tables below specify the data source for each result displayed in the reports (ie.: which T2 report is used to produce each of the graphs, figures and maps in the reports).

However, In some cases, members can have additional data (tables, spreadsheets and images) they would like to add to the reports. If that is the case, please do an initial run and you will notice that inside data/report_{report_year}_{member_flag} a subfolder additional_files will be created automatically. Please, add all additional files you would like to add to the reports inside it and work on the templates to include them in the correct section on your report.

Local knowledge - artisanal trips

There are some additional data that are already being expected in the currerent workflow. This is the case of the estimated average of monthly landings (trips) per landing sites provided by members. If available, this file will be used in the artisanal report when calculating the total number of trips to be used in the final artisanal ACE calculation.

This workflow checks in the data/report_{report_year}_{member_flag}/additional_files if a member has any .csv file named: est_trips.csv.

If you have this information in a .csv file, please add it to the correct folder (data/report_{report_year}_{member_flag}/additional_files) and save it as est_trips.csv. The file should have only two columns and they should be named as: landing_site_name and est.trips.

The script works by using the highest value of effort, whether that comes from local knowledge or the reported effort information in IKASAVEA/TAILS.

Part 1

Note that the selection between report 3605 or or 3619 depends on the aceman parameter specified in the main.R. If you set it to TRUE it means the data to be used is from 3619, otherwise it will use data from report 3605.

Tufman 2 Report	# Outputs (maps, tbls, plots)	Outputs (Quarto label)
2953	3	• SSI catches -- Purse seine fleet (tbl-tbl3s) • SSI catches -- Longline fleet (tbl-tbl3ll) • SSI catches -- Pole line fleet (tbl-tbl3lpl)
3605 or 3619	12	• Annual catch estimates -- Purse seine fleet (tbl-tbl1s) • Annual catch estimates -- Longline fleet (tbl-tbl1l) • Annual catch estimates -- Pole line fleet (tbl-tbl1pl) • Historical annual catch -- Purse seine fleet (fig-fig1s) • Historical annual catch -- Longline fleet (fig-fig1l) • Historical annual catch -- Pole line fleet (fig-fig1pl) • Historical annual vessel numbers -- all gears (fig-fig2) • Active vessels by size category -- Longline (tbl-tbl2-longline) • Active vessels by size category -- Purse seine (tbl-tbl2-ps) • Active vessels by size category -- Pole line (tbl-tbl2-pl) • Non-target species catches -- Purse seine (tbl-tbl4s) • Non-target species catches -- Longline (tbl-tbl4l)
3608	3	• Catch distribution map -- Purse seine (fig-figmapps) • Catch distribution map -- Longline (fig-figmapl) • Catch distribution map -- Pole line (fig-figmappl)

Addendum

Tufman 2 Report	# Outputs	Outputs (Quarto label)
2918	1	• Swordfish vessels & catch south of 20S (tbl-2009-03)
2986	1	• Observer coverage of longline fleet (tbl-obs_cov)
3222	1	• Cetacean encirclements by purse seine nets (tbl-cmm2011-03)
3317	5	• Seabird interactions summary by year (tbl-cmm2018-03x) • Seabird interactions south of 30S (tbl-sb_s30s) • Seabird interactions between 30S–25S (tbl-sb_25s_30s) • Seabird interactions between 25S–23N (tbl-sb_25s_23n) • Seabird interactions north of 23N (tbl-sb_23n)
3612	1	• Merged into a6 to add total hooks; feeds all 5 seabird tables above
3605	1	• Vessel counts joined into a6; feeds all 5 seabird tables above
3315	4	• Seabird mitigation types south of 30S (tbl-s30s) • Seabird mitigation types between 30S–25S (tbl-30s_25s) • Seabird mitigation types between 25S–23N (tbl-25s_23n) • Seabird mitigation types north of 23N (tbl-n23n)
3314	1	• Seabird captures by species and area (tbl-cmm2018-03z)
2917	1	• Striped marlin vessels and catch south of 15S (tbl-cmm2006-04)
3602	1	• North Pacific albacore vessels, effort and catch (tbl-cmm2019-03)
3513	1	• North Pacific swordfish vessels, effort and catch (tbl-cmm2023-03)

Artisanal

Tufman 2 Report	# Outputs	Outputs (Quarto label)
3615	2	• Trips reported in Tails by month & landing site (Monthly-effort) • Landing site comparison T2 vs Ikasavea (diff_t2_ika)
3527	3	• Used to calculate total trips for SKJ CPUE (data_skj) • Used to calculate total trips for YFT CPUE (df_yft) • Used to calculate total trips for BET CPUE (df_bet)
3614	3	• Unraised SKJ catch by landing site & month (data_skj) • Unraised YFT catch by landing site & month (df_yft) • Unraised BET catch by landing site & month (df_bet)

Ikasavea	# Outputs	Outputs (Quarto label)
data_ika_trips	1	• Trips reported in Ikasavea by month & landing site (tab2)

Addional instructions

If it is your first time cloning a repository refer to How to Clone a GitHub Repository

---