diff --git a/.github/workflows/render-and-publish.yml b/.github/workflows/render-and-publish.yml deleted file mode 100644 index 8f33768..0000000 --- a/.github/workflows/render-and-publish.yml +++ /dev/null @@ -1,81 +0,0 @@ -on: - push: - branches: main - -name: Render and Publish - -jobs: - build-deploy: - runs-on: ubuntu-latest - env: - GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} - - steps: - - name: Check out repository - uses: actions/checkout@v7 - - - name: Set up R (needed for Rmd) - uses: r-lib/actions/setup-r@v2 - - - name: Install system dependencies - run: | - sudo apt-get update - sudo apt-get install -y \ - libcurl4-openssl-dev \ - libssl-dev \ - libxml2-dev \ - libv8-dev \ - libfontconfig1-dev \ - libfreetype6-dev \ - libharfbuzz-dev \ - libfribidi-dev \ - libpng-dev \ - libtiff5-dev \ - libjpeg-dev \ - libcairo2-dev \ - libgit2-dev \ - libnode-dev \ - libx11-dev \ - pandoc - - - name: Set up R package dependencies (cached, via pak) - uses: r-lib/actions/setup-r-dependencies@v2 - with: - pak-version: stable - cache: true - packages: | - cran::rmarkdown - cran::knitr - cran::jsonlite - cran::dplyr - cran::ggplot2 - cran::tidyr - cran::TMB - cran::remotes - cran::reshape2 - cran::Rcpp - cran::glue - cran::purrr - cran::ggridges - extra-packages: | - github::nmfs-ost/stockplotr - github::stan-dev/cmdstanr - github::mjskay/tidybayes - github::stan-dev/shinystan - github::noaa-afsc/SparseNUTS - github::NOAA-FIMS/FIMS - github::r4ss/r4ss@convert-data-to-fims - - - name: Set up Quarto - uses: quarto-dev/quarto-actions/setup@v2 - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - # add software dependencies here - - - name: Publish to GitHub Pages (and render) - uses: quarto-dev/quarto-actions/publish@v2 - with: - target: gh-pages - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # this secret is always available for github actions diff --git a/.github/workflows/render-publish-and-readme.yml b/.github/workflows/render-publish-and-readme.yml new file mode 100644 index 0000000..7e67bb2 --- /dev/null +++ b/.github/workflows/render-publish-and-readme.yml @@ -0,0 +1,198 @@ +name: Render, Publish, Auto-Gen README Table + +on: + push: + branches: [ main ] + workflow_dispatch: + schedule: + - cron: '30 0 * * 0' # runs At 00:00 on Sunday + +jobs: + render-and-badge: + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Setup R + uses: r-lib/actions/setup-r@v2 + + - name: Install system dependencies + run: | + sudo apt-get update + sudo apt-get install -y \ + libcurl4-openssl-dev \ + libssl-dev \ + libxml2-dev \ + libv8-dev \ + libfontconfig1-dev \ + libfreetype6-dev \ + libharfbuzz-dev \ + libfribidi-dev \ + libpng-dev \ + libtiff5-dev \ + libjpeg-dev \ + libcairo2-dev \ + libgit2-dev \ + libnode-dev \ + libx11-dev \ + pandoc + + - name: Set up R package dependencies (cached, via pak) + uses: r-lib/actions/setup-r-dependencies@v2 + with: + pak-version: stable + cache: true + packages: | + cran::rmarkdown + cran::knitr + cran::jsonlite + cran::dplyr + cran::ggplot2 + cran::tidyr + cran::TMB + cran::remotes + cran::reshape2 + cran::Rcpp + cran::glue + cran::purrr + cran::ggridges + extra-packages: | + github::nmfs-ost/stockplotr + github::stan-dev/cmdstanr + github::mjskay/tidybayes + github::stan-dev/shinystan + github::noaa-afsc/SparseNUTS + github::NOAA-FIMS/FIMS + github::r4ss/r4ss + + - name: Setup Quarto + uses: quarto-dev/quarto-actions/setup@v2 + + - name: Render core website pages + run: | + # Render the homepage (assuming it's in the root) + if [ -f "index.qmd" ]; then quarto render index.qmd; fi + + # Render the excluded instructional files + quarto render content/setup.qmd + quarto render content/acknowledgements.qmd + quarto render content/advanced-features.qmd + + - name: Update Table and Badges (R Script) + shell: Rscript {0} + run: | + # --- Configuration --- + content_dir <- "content" + badge_dir <- "badges" + readme_file <- "README.md" + excluded <- c("acknowledgements.qmd", "advanced-features.qmd", "setup.qmd") + + dir.create(badge_dir, showWarnings = FALSE) + + # --- Helper Function: Parse YAML --- + parse_yaml <- function(filepath) { + lines <- readLines(filepath, warn = FALSE) + dash_lines <- which(lines == "---") + + res <- list(stock = NA, previous_model = "", features = "") + + if (length(dash_lines) >= 2) { + yaml_lines <- lines[(dash_lines[1] + 1):(dash_lines[2] - 1)] + for (line in yaml_lines) { + if (grepl("^stock:", line)) res$stock <- trimws(gsub("^stock:\\s*|\"|'", "", line)) + if (grepl("^previous_model:", line)) res$previous_model <- trimws(gsub("^previous_model:\\s*|\"|'", "", line)) + if (grepl("^features:", line)) res$features <- trimws(gsub("^features:\\s*|\"|'", "", line)) + } + } + return(res) + } + + # --- Initialize Table --- + table_lines <- c( + "Stock | Previous Model | Status | Notable Features |", + "-- | -- | -- | --" + ) + + # --- Process Quarto Files One at a Time --- + files <- list.files(content_dir, pattern = "\\.qmd$", full.names = TRUE) + basenames <- basename(files) + + # Filter out excluded files + valid_idx <- !(basenames %in% excluded) + files <- files[valid_idx] + basenames <- basenames[valid_idx] + + for (i in seq_along(files)) { + file <- files[i] + base <- gsub("\\.qmd$", "", basenames[i]) + + # Extract metadata + meta <- parse_yaml(file) + + # Fallback if stock isn't defined in YAML + stock <- ifelse(is.na(meta$stock), gsub("[-_]", " ", base), meta$stock) + + # Attempt to render the file + message(glue::glue("Testing {base}...")) + cmd <- glue::glue("quarto render {file}") + exit_code <- system(cmd) + + # Assign badge + if (exit_code == 0) { + message("✅ ", base, " rendered successfully.") + badge_url <- "https://img.shields.io/badge/Status-working-brightgreen" + } else { + message("❌ ", base, " failed to render.") + badge_url <- "https://img.shields.io/badge/Status-failing-red" + } + + # Download badge + badge_path <- file.path(badge_dir, paste0(base, ".svg")) + download.file(badge_url, destfile = badge_path, mode = "wb", quiet = TRUE) + + # Add row to table + badge_md <- glue::glue("![Status]({badge_dir}/{base}.svg)") + table_lines <- c(table_lines, glue::glue("{stock} | {meta$previous_model} | {badge_md} | {meta$features} |")) + } + + # --- Update README.md --- + readme <- readLines(readme_file, warn = FALSE) + start_idx <- which(trimws(readme) == "") + end_idx <- which(trimws(readme) == "") + + if (length(start_idx) > 0 && length(end_idx) > 0) { + new_readme <- c( + readme[1:start_idx], + table_lines, + readme[end_idx:length(readme)] + ) + writeLines(new_readme, readme_file) + message("README.md updated successfully!") + } else { + warning("Error: Could not find and markers in README.") + } + + - name: Deploy successfully rendered files (and not failed ones) to GitHub Pages + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./_site + keep_files: true + + - name: Create Pull Request + uses: peter-evans/create-pull-request@v6 + with: + # Added [skip ci] to prevent triggering workflows on merge + commit-message: "chore: auto-update case study table and badges [skip ci]" + title: "🤖 Auto-update case study table and badges" + body: "Automated updates to case study status badges and README table based on the latest Quarto renders." + branch: "auto-update-badges" + base: "main" diff --git a/README.md b/README.md index 2949552..472a40f 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,44 @@ # FIMS case studies -This is a [website](https://noaa-fims.github.io/case-studies/) (`type: website`) showcasing test cases of the [Fisheries Integrated Modeling System](https://NOAA-FIMS/FIMS/). - -Case studies included so far: -Stock | Status --- | -- -NEFSC yellowtail flounder | working -AFSC GOA pollock | working -SWFSC sardine | working -NWFSC petrale | working -PIFSC opakapaka | working -SEFSC scamp | working +## Goal -## How to add a case study - -* Create a new branch to work on a case study. -* Edit the qmd or md files in the `content` folder. qmd files can include code (R) and lots of Quarto markdown bells and whistles (like call-outs, cross-references, auto-citations and much more). -* Add the files to `_quarto.yml`. -* Submit a pull request when finished working on a case study. If the case study renders successfully, the rendered pages will be uploaded to the artifacts section of the GitHub Actions page. If the case study fails to render, developers can review the GitHub Actions log to debug. - -
+If you want to run a FIMS model and don't know where to start, you can submit your model to this test-bed repository and we can work with you on getting your model running in [Fisheries Integrated Modeling System](https://NOAA-FIMS/FIMS/)! The associated [GitHub pages site](https://noaa-fims.github.io/case-studies/) with this repo "shows the work" of getting each model running in FIMS. Once the model is completed and running, it will graduate :mortar_board: to it's own repository. In the future, we will have a way to track assessments that use FIMS, so be on the lookout for that! -## Main and dev branches +## Case studies included so far -- The `main` branch of case-studies should always work with the `main` branch of FIMS. It should always be passing GitHub Actions. -- The `dev` branch of case-studies should work with the `dev` branch of FIMS. It may sometimes be broken. + -## Working off of main +Stock | Previous Model | Status | Notable Features | +-- | -- | -- | -- +NEFSC yellowtail flounder | ASAP | working | +AFSC GOA pollock | Cole's TMB model | non-updated | Bayesian | +SWFSC sardine | SS3 | not updated | +NWFSC petrale | SS3 | not updated | +PIFSC opakapaka | SS3 | not updated | Age-to-length conversion matrix | +SEFSC scamp | BAM | working | +NWFSC Pacific hake | SS3 | failing | Bayesian | -It may be necessary to work off of main in order to apply a "hot fix" to case-studies between FIMS releases. Create a new branch off of main that includes the word "main" somewhere in its name - the Quarto setup file will automatically install the main version of FIMS as long as the word main is somewhere in the branch name. Otherwise, the dev version of FIMS will be installed. + -## Working off of dev +## How to add a case study -Create a branch off of dev that does NOT include the word "main" somwhere in its name. +* Create a new branch to work on a case study. +* Edit the `.qmd` or `.md` files in the `content` folder. `.qmd` files can include code (R) and lots of Quarto markdown bells and whistles (like call-outs, cross-references, auto-citations and much more). +* Add the files to `_quarto.yml`. +* Submit a pull request when finished working on a case study. If the case study renders successfully, the rendered pages will be uploaded to the artifacts section of the GitHub Actions page. If the case study fails to render, you can review the GitHub Actions log to debug. +* FIMS team members will review the pull request and make comments, suggestions, etc. about how to get your model running. -## How to use codespaces +## Using codespaces to develop case studies See the [GitHub codespaces documentation](https://docs.github.com/en/codespaces) for general codespaces help. After launching a codespace, to code in Rstudio rather than VSCode, type `rserver` into the command line. -If needed for use, reshape2 will need to be install on the R terminal using `install.packages("reshape2")`. It was failing to install as part of the codespaces devcontainer.json file, and so was not included for now. +If needed for use, `reshape2` will need to be install on the R terminal using `install.packages("reshape2")`. It was failing to install as part of the codespaces `devcontainer.json` file, and so was not included for now. -gdb is installed in the codespace. +`gdb` is installed in the codespace. + +
### Disclaimer diff --git a/_quarto.yml b/_quarto.yml index c156c2c..fa1049d 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -36,27 +36,7 @@ website: style: "docked" search: true collapse-level: 1 - contents: - - href: index.qmd - text: Home - - href: content/NEFSC-yellowtail.qmd - text: S New England-Mid Atlantic yellowtail flounder - - href: content/AFSC-GOA-pollock.qmd - text: Gulf of Alaska pollock - # - href: content/SWFSC-sardine.qmd - # text: sardine - # - href: content/PIFSC-opakapaka.qmd - # text: Opakapaka - # - href: content/NWFSC-petrale.qmd - # text: petrale sole - # - href: content/SEFSC-scamp.qmd - # text: scamp - - href: content/pacific-hake.qmd - text: Pacific Hake - # - href: content/advanced-features.qmd - # text: Advanced features - - href: content/acknowledgements.qmd - text: Acknowledgements + contents: auto format: html: diff --git a/content/AFSC-GOA-pollock.qmd b/content/AFSC-GOA-pollock.qmd index f6e4090..421a28c 100644 --- a/content/AFSC-GOA-pollock.qmd +++ b/content/AFSC-GOA-pollock.qmd @@ -1,5 +1,8 @@ --- title: AFSC Case Study Gulf of Alaska Walleye Pollock +stock: "AFSC GOA walleye pollock" +previous_model: "AFSC custom ADMB model" +features: "Bayesian" format: html: code-fold: true diff --git a/content/NEFSC-yellowtail.qmd b/content/NEFSC-yellowtail.qmd index c79634b..1d88cbb 100644 --- a/content/NEFSC-yellowtail.qmd +++ b/content/NEFSC-yellowtail.qmd @@ -1,5 +1,8 @@ --- title: Southern New England-Mid Atlantic Yellowtail Flounder +stock: NEFSC yellowtail Flounder +previous_model: "ASAP" +features: "" format: html: code-fold: true diff --git a/content/NWFSC-petrale.qmd b/content/NWFSC-petrale.qmd index b5423cb..41c4a31 100644 --- a/content/NWFSC-petrale.qmd +++ b/content/NWFSC-petrale.qmd @@ -1,5 +1,8 @@ --- title: NWFSC Case Study Petrale Sole +stock: "NWFSC petrale" +previous_model: "SS3" +features: "" format: html: code-fold: true diff --git a/content/PIFSC-opakapaka.qmd b/content/PIFSC-opakapaka.qmd index e0f392b..9306443 100644 --- a/content/PIFSC-opakapaka.qmd +++ b/content/PIFSC-opakapaka.qmd @@ -1,5 +1,8 @@ --- title: PIFSC Opakapaka Case Study +stock: "PIFSC Opakapaka" +previous_model: "SS3" +features: "Age-to-length conversion matrix" format: html: code-fold: true diff --git a/content/SEFSC-scamp.qmd b/content/SEFSC-scamp.qmd index 1e38a20..fc1bdd1 100644 --- a/content/SEFSC-scamp.qmd +++ b/content/SEFSC-scamp.qmd @@ -1,5 +1,8 @@ --- title: South Atlantic Scamp +stock: "SEFSC scamp" +previous_model: "BAM" +features: "" format: html: code-fold: true diff --git a/content/SWFSC-sardine.qmd b/content/SWFSC-sardine.qmd index c080404..3168597 100644 --- a/content/SWFSC-sardine.qmd +++ b/content/SWFSC-sardine.qmd @@ -1,5 +1,8 @@ --- title: SWFSC Case Study Pacific Sardine +stock: "SWFSC sardine" +previous_model: "SS3" +features: "" format: html: code-fold: true @@ -462,7 +465,6 @@ ggplot2::ggplot( Tools to check: * data were inputted correctly (dimension checks) * starting values and settings are reasonable -* Perhaps have a model template file that will work as is, then users can modify as necessary * I had issues installing FIMS with install_github that seemed to be related to R settings Model: diff --git a/content/case-study-template.qmd b/content/case-study-template.qmd deleted file mode 100644 index eb61fe6..0000000 --- a/content/case-study-template.qmd +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Customize ---- - - - -## Edit and add your pages - -Each page should start with -``` ---- -title: your title ---- -``` -and the first header will be the 2nd level, so `## `. Note, there are situations where you leave off -``` ---- -title: your title ---- -``` -and start the qmd file with a level header `# `, but if using the default title yaml (in the `---` fence) is a good habit since it makes it easy for Quarto convert your qmd file to other formats (like into a presentation). - -## Add a chunk of code describing your setup - -Case study files should include: - -* R version -* TMB version -* FIMS commit -* Name of your stock -* Name of your region -* Name of the analyst - -Please ensure that the [`content/setup.qmd`](https://github.com/NOAA-FIMS/case-studies/blob/main/content/setup.qmd) file is updated if the case study requires the installation of additional R packages. - -## Add a bulleted list and script describing simplifications you had to make - -How I simplified my assessment -* Remove seasonality -* etc. - -## Add your script that sets up and runs the model - -## Add your comparison figures - -## Add comparison tables - -## What was your experience using FIMS? What could we do to improve usability? - -## List any issues that you ran into or found - -Please [open an issue](https://github.com/NOAA-FIMS/FIMS/issues/new/choose) if you found something new. - -## What features are most important to add based on this case study? - -## Add your pages to the project - -* Add the files to `_quarto.yml` diff --git a/content/pacific-hake.qmd b/content/pacific-hake.qmd index 627d3fa..e29d55e 100644 --- a/content/pacific-hake.qmd +++ b/content/pacific-hake.qmd @@ -1,5 +1,8 @@ --- title: U.S. West Coast Case Study of Pacific Hake +model: "NWFSC Pacific Hake" +previous_model: "SS3" +features: "Bayesian" format: html: code-fold: true