AKFIN documentation dump

[MattCallahan-NOAA]

Issue

Hey GAP_PRODUCTS team, here are some documentation suggestions related to the AKFIN parts.

Some of these comments may be known issues that will be sorted out anyway. Also feel free to disregard suggestions, and no hurry on any of this on my account.

I would just have one data description section for the base table and corresponding akfin_table. It seems a little redundant to have both since the akfin versions are copies. In that case it might make more sense to put the AKFIN description above the column level table descriptions. Also if the data descriptions could be put into a table using flextable or something it would read a lot more cleanly.

Text suggestions for the AKFIN section. I restructured to organize text by data access pathway. I think these make most sense here but I could also see them going down lower under the data access chapters.
The Alaska Fisheries Information Network The Alaska Fisheries Information Network (AKFIN) is a regional program that consolidates and supports the processing, analysis, and reporting of fisheries data for Alaskan fisheries. AKFIN integrates this information into a single data management system using consistent methods and standardized formats. The resulting data enables fishery managers, scientists, and associated agencies to supervise fisheries resources more effectively and efficiently. The AKFIN database contains much of the data needed to complete stock assessments, including GAP trawl survey data. .

Data Access Options Direct database connection If you are an AFSC employee you may access the AKFIN oracle database directly while on the NOAA network or VPN. Note that this is a separate database from the AFSC oracle database referenced above, and requires separate credentials. If you do not already have an AKFIN account you can request one here. NOAA IT will need to add AKFIN access to your tnsnames.ora file (They do this frequently). Once your connection is established data may be accessed through SQL queries using SQL developer, R, or python.

AKFIN Answers (AKFIN Answers)[https://akfin.psmfc.org/akfin-answers/] is an Oracle BI tool used for distributing data to stock assessors and other users. Usernames and passwords are distinct from AKFIN direct database credentials. The distribution of GAP_PRODUCTS on AKFIN Answers is planned but not yet implemented. The RACE Survey tab on the stock assessment dashboard contains reports generated from now depreciated tables that predated the GAP_PRODUCTS tables. AKFIN will keep these reports for reference but they will not be updated 2024 onward.

Web Service AKFIN has developed web services (apis) to distribute GAP data. Like the GAP_PRODUCTS schema, these are under active development. These do not require VPN or an oracle connection but they are protected by Oracle authentication, please contact matt.callahan@noaa.gov for information on how to get an api token to use this option.

The url structure is "https://apex.psmfc.org/akfin/data_marts/gap_products/gap_[base table name]" . For example "https://apex.psmfc.org/akfin/data_marts/gap_products/gap_biomass" is the base url to get data from the akfin_biomass table. Web services linked to large tables have mandatory parameters to reduce data download size. For example to get agecomp data for Bering Sea pollock in area_id 10 in 2022 you would use "https://apex.psmfc.org/akfin/data_marts/gap_products/gap_biomass?survey_definition_id=98&area_id=10&species_code=21740&start_year=2022&end_year=2022”.

If you’re using R to pull data through web services you might find the akfingapdata (pronounced akfin-gap-data not ak-eff-ing-app-data) R package helpful.

(End of text suggestions)

In the word doc version, the first part of the AKFIN section doesn’t show up, it goes from 6.1.8 to 7 - data description.

Code examples

Maybe under the api example include an example from the akfingapdata readme?

Direct database query in R.

# load packages
library(odbc)
library(getPass)
library(tidyverse)

# connect to AKFIN Oracle database
con <- dbConnect(odbc::odbc(), "akfin", UID=getPass(msg="USER NAME"), PWD=getPass())

# define species code for pollock
my_species <- 21740

#query database
data<- dbFetch(dbSendQuery(con,
                           paste0("select * from gap_products.akfin_biomass 
where species_name = ", my_species, 
“ and survey_definition_id = 98, 
and area_id = 10”))) %>%
rename_with(tolower) # everyone likes lower case letters better

head(data)

As we make changes based on feedback over the next couple of months I can send you updated documentation.

Cheers, Matt

[EmilyMarkowitz-NOAA]

Thanks for these edits, @MattCallahan-NOAA! They look great. Feel free to submit these (especially the text edits) directly to the page as a pull request in the future. I think I've incorporated everything here into the pages except your first note about redundant table descriptions/pages/tables. I'll have to think a little more on that one.

Make sure I've incorporated everything correctly?: AKFIN text API examples -- I couldn't get the example to work, but I think it's because I am not using the token right. I wrote you a separate email about that and can rerun when that works.

[EmilyMarkowitz-NOAA]

Closing this issue, let me know if there are more edits to be implemented! :)