Thoughts on standard file structure for assessments?

[Schiano-NOAA]

Background

Currently, when users run asar::create_template(), a standard file structure system is created specifically to store the files for report writing. The structure is as follows:

stock_assessment_reports > office > region > species > year

Within the final year folder contains the quarto skeleton and associated "child" files of the sections names. An additional folder within the year folder contains the necessary formatting files that produces a stock assessment repot that will create the standard, familiar look for NMFS.

There are many other files made in the stock assessment workflow and ways to customized the workflow. As developers we have been thinking about this a lot.

In regards to stock assessment workflows, there is much more in the process beyond reporting and it could be helpful to establish a file system that is helpful to organize and reference the files. Developers and users of sa4ss have thought about this before by contributing to this discussion.

Here is an example by @iantaylor-NOAA:

species/
.gitignore [includes stuff like /data-raw/, /models/, *.pdf, *ppt]
README.md
DESCRIPTION [optional file if you want repo to work as an R package]
NAMESPACE [optional file if you want repo to work as an R package]
+-- documents/
│ +-- figures/
│ +-- tables/
│ +-- 00a.Rmd
│ +-- ...
+-- docs/ [required name for files posted to github pages, such as those created by pkgdown, may only exist in a branch]
+-- data/
| +-- blah.rda [processed data that is not confidential]
+-- data-raw/ [in .gitignore, shared via Google Drive]
| +-- blah.csv
+-- models/ [in .gitignore, shared via Google Drive]
| +-- 2025.001.001_base/
| +-- ...
| +-- 2025.099.001_base/
| +-- plots/
| +-- tables/ [exec summary tables in .csv format]
| +-- Report.sso/output.Rdata/[other non-confidential output file type]
| +-- ...
+-- presentations/
| +-- presentation.Rmd
| +-- responses.Rmd
| +-- presentation.pdf [in .gitignore, shared via Google Drive]
| +-- presentation.ppt [in .gitignore, shared via Google Drive]
+-- R/
+-- some_script.R
+-- fancy_function.R

What are your thoughts on a standard, organized file system for stock assessments?

[kellijohnson-NOAA]

I think a lot of information does not change over the years so it would be good to create a workflow that doesn't require you to create a new folder for a new year. Instead, git, or some kind of version control should be tracking things.

[iantaylor-NOAA]

@Schiano-NOAA, thanks for posting this.
At the national level, including the layers of office and region makes sense, but for individual users, it would be good to be able to skip those layers since many of us will be doing 100% of our work within the same office and region.

[BenWilliams-NOAA]

I’ve generally found that creating a format that works for everything/everyone is exceedingly challenging. Here is where we started for AK, though it hasn’t been updated in some time and I’d venture that most folks aren’t using it https://afsc-assessments.github.io/afscdata/articles/development.html

[iantaylor-NOAA]

@BenWilliams-NOAA, thanks for sharing the AFSC structure. It looks pretty similar to what we proposed at NWFSC (in original comment at the top of this discussion or formatted slightly better at pfmc-assessments/sa4ss#71). Looking through some of the assessment-specific repos at https://github.com/afsc-assessments there does appear to be a wide range of implementations as you supposed, just as we have at NWFSC.

[michellesculley]

We (PIFSC) have proposed to use this as our folder structure for our shared drives, with the suggestion that when we move the assessment folder to the shared drive it would be easier to do so if you set up your folder structure like this already. There are slight differences in naming convention for the different programs, but the folder structure is pretty much the same.

Folder and subfolder organization

• Assessments and projects are kept in separate main folders.

• Each assessment report, tech memo, or paper is assigned to a single folder, even if multiple species are included in the project.

• Subfolder should be roughly organized as follows (please offer suggestions here, this is just a rough draft):
  - 01_Data
  - 02_Scripts
  - Scripts should also be on Github repo with exact same name as project folder)
  - 03_Outputs
  - 04_SS models
  - 05_Other files
  - 06_bin

• Script files that are sequential (i.e. needs an output from a previous script to run) should start with a number : 01_Get_Data.r, 02_Run_GLM.r, 03_Index.r, etc.

• Output files that are sequential should also have numbering (01_Process_catch.rds, 02_CPUE_raw.rds, 03_CPUE_processed.rds, etc.)

• You should store the executable files (i.e. SS, AGEPRO, etc) in the 06_bin folder

Naming conventions (OSAP)

• Year_Species_region_project (e.g. 2024_SWO_NP_Assessment or 2026_MLS_WCNPO_rebuilding)
• Year: For assessments, write all 4 digits of the publication year (tech memo, etc.)
• Year: For projects, write all 4 digits of the year the project was started
• Taxon: Use the 3 letter species code
• Region: use the typical abbreviation for the stock, such as NP for North Pacific, or WCNPO for western and central north Pacific

Naming conventions (ISAP)

• Year_Region_Taxon (e.g. 2024_Hawaii_Deep7)
• Year: For assessments, write all 4 digits of the publication year (tech memo, etc.)
• Year: For projects, write all 4 digits of the year the project was started
• Region: Hawaii, Guam, CNMI, AmSam
• Taxon: Same as name used in tech memo title: BMUS, Deep7, Uku, KonaCrab, Bottomfish (no space if name has two words).

[mkapur]

I'm just parachuting into this thread with minimal context, but my take is that keeping the focus narrow (file structure for REPORTING purposes only) might prevent headaches. It's unlikely that the system will be broad enough to do full read-write of all model types anyway, so assuming that /figures and /tables are pre-populated could grease the wheels for adoption.

I have had a fabulous time with Ben's SAFE templating tools, and one thing that worked was that the default template corresponded to a full assessment with modularized scripts for each sub component. This meant that when it was time for a simpler, update-style assessment I could easily uncheck the boxes for the sections didn't need. So, the structure was fairly light on folders and instead emphasized individual .Rmd docs for the key reporting components.

Forgive me if I'm missing the intent of this thread.

[BenWilliams-NOAA]

Hey Maia, the individual report sections are there in asar, yeah!
We are getting at should the processed results be dropped in the report folder, or individual model folders (or either) as it gets to how the files are sourced for the various components. I think it would be great if we (collective assessment authors in this country) could abide by a singular format - fully aware that has both good and bad aspects.