{"id":32005885,"url":"https://github.com/danstich/penpass","last_synced_at":"2026-07-16T06:32:36.399Z","repository":{"id":50065084,"uuid":"383605691","full_name":"danStich/penPass","owner":"danStich","description":"R package for the Atlantic salmon PenPass model","archived":false,"fork":false,"pushed_at":"2023-06-15T14:39:14.000Z","size":503,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-25T23:41:35.777Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danStich.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-07-06T21:51:07.000Z","updated_at":"2022-03-11T22:38:09.000Z","dependencies_parsed_at":"2025-09-11T08:36:52.068Z","dependency_job_id":"0e51eb90-a2ae-445b-8dca-c2ae865936c9","html_url":"https://github.com/danStich/penPass","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/danStich/penPass","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danStich%2FpenPass","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danStich%2FpenPass/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danStich%2FpenPass/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danStich%2FpenPass/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danStich","download_url":"https://codeload.github.com/danStich/penPass/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danStich%2FpenPass/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35534108,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-16T02:00:06.687Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-15T18:53:02.526Z","updated_at":"2026-07-16T06:32:36.394Z","avatar_url":"https://github.com/danStich.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# penPass\n\nAn R package for hosting code and data, and running the Atlantic salmon PenPass model.\n\n## Installation\n\nThe development version of `penPass` can be installed with  [`devtools`](https://www.rstudio.com/products/rpackages/devtools/) in R using the repository url:\n\n`devtools::install_github(\"danStich/penPass\")`\n\nTo install `penPass`, you will need to have `devtools` installed ahead of time in R, but that requires some special tools. To install on **Windows**, you will need to download and install the appropriate version of [Rtools](https://cran.r-project.org/bin/windows/Rtools/). To install on **Mac**, you will need to have the [XCode command-line tools](http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/) installed. And, if running from **Linux**, you will need to install the developer version of R (`r-base-dev`) if you have not already.\n\n## Directories\n\n`data/` Contains built-in data sets for the package\n\n`man/`  help files and documentation\n\n`R/`    R functions in scripts\n\n`inst/shiny-examples/penPass_shiny/` includes server and ui files for `penPass_shiny()`, a shiny-based user interface\n\n`tests/` Includes package tests for default parameter accuracy conducted on package build\n\n## Getting started\nThere are two primary user-facing functions within the `penPass` package. The `run_one_year()` function can be called within an Rscript to run the penPass model using default or user-defined inputs for a single year. The `penPass_shiny()`function launches a graphical user interface (GUI) that opens in a web browser and is written with the `shiny` package. The former provides functionality for large-scale simulation studies in R whereas the latter provides and intuitive interface for running smaller numbers of management scenarios.\n\n### `run_one_year()`\nThe `run_one_year()` function provides the primary user-facing function for the `penPass`package. The purpose of the function is to run the PenPass analysis for a selected year (1970-2020). The output of this function is a numerical vector containing number of smolts reaching the ocean. All default argument values (model inputs) are based on the most-recent version of the NOAA PenPass Excel-based model (Stevens et al. 2019).\n\nThe `run_one_year()` function allows user to specify year, downstream passage survival through dams, natural survival per kilometer, habitat productivity, habitat saturation, and probability that fish migrate through the Stillwater Branch during outmigration.\n\nYou can find the help file for the `run_one_year()` function in R by running:`?penPass::run_one_year`. This file contains all accepted user arguments, explanations of what they mean and what are default values, and examples of how to use the `run_one_year()` function. Examples are shown at the bottom of this page.\n\n### `penPass_shiny()`\nThe `penPass_shiny()` function provides and intuitive user interface for running the penPass model. Though more limited in flexibility that `run_one_year()`, the simplified interface should allow full exploration of management scenarios. The primary difference is that `penPass_shiny()` does not allow the user to input custom distributions or values for some input parameters implemented in the `run_one_year()` function. \n\nCurrently, the shiny interface for the penPass model can only be called directly from R or Rstudio by running the following lines of code:\n```\nlibrary(penPass)\npenPass_shiny()\n```\n\nThis will open the user-interface in a local instance of the default web browser on the computer where further instructions are provided.\n\n## Examples using `run_one_year()`\n\n### Single simulation\nAn example of a single simulation using `run_one_year()` is demonstrated below, using the default values based on Stevens et al. (2019).\n\n```\nlibrary(penPass)\nrun_one_year(\n  year = 2017,\n  downstream = list(\n    seeboomook = NA, \n    ripogenus = NA, \n    north_twin = NA, \n    quakish = NA,\n    dolby = NA, \n    east_millinocket = NA, \n    medway = NA, \n    matagamon = 1, \n    guilford = NA,\n    moosehead = NA, \n    browns_mills = NA, \n    howland = NA, \n    mattaseunk = NA, \n    west_enfield = NA,\n    milford = NA, \n    great_works = NA, \n    gilman_falls = NA, \n    stillwater = NA, \n    orono = NA,\n    veazie = NA, \n    bangor_waterworks = 1),\n  km_surv = NULL,\n  prod = c(\n    WPN_prod = 3, \n    EPN_prod = 3, \n    Matt_prod = 3, \n    PISC_prod = 3, \n    PN_prod = 3),\n  sat = c(\n    WPN_sat = 0, \n    EPN_sat = 0, \n    Matt_sat = 0, \n    PISC_sat = 0, \n    PN_sat = 0),\n  p_stillwater = NA\n)\n```\n\n### Multiple simulations for a single year\nAn example of a single simulation using `run_one_year()` is demonstrated below, using the default values from Stevens et al. (2019) and the year 2017.\n\n```\nlibrary(foreach)\nlibrary(tidyverse)\nlibrary(penPass)\n\n# Choose number of iterations\nn \u003c- 100\n\n# Create a list holding model output\noutlist \u003c- foreach(1:n) %do%\n  run_one_year(\n    year = 2017\n  )\n  \n# Collect results into a single dataframe\nnames(outlist) \u003c- paste0(\"run_\", seq(1, length(outlist)))\nout_df \u003c- data.frame(do.call(rbind, outlist))\nnames(out_df)[1] = \"Smolts\"\n\n# Summarize results across number of runs\nsummary_2017 \u003c- out_df %\u003e% \n  summarize(abund = median(Smolts),\n            lwr = quantile(Smolts, 0.025),\n            upr = quantile(Smolts, 0.975)\n            )\n\n# Plot results\nggplot(out_df, aes(x = Smolts)) +\n  geom_histogram()\n\n```\n\n### Multiple simulations for multiple years\n```\n# Library load\nlibrary(penPass)\nlibrary(doParallel)\nlibrary(foreach)\nlibrary(tidyverse)\n\n# Number of simulations\nn_sims \u003c- 5000\n\n# Define a function to call\nsim \u003c- function(x){\n  years \u003c- seq(1970, 2017, 1)\n  sim_year \u003c- sample(years[1:length(years)], 1, replace = TRUE)\n  out \u003c- run_one_year(year = sim_year)\n  data.frame(year = sim_year, smolts_out = out)\n}\n\n# Repeat the function for number of iterations (runs the simulation)\nregisterDoParallel(cores = 7)\nout_list \u003c- foreach(1:n_sims, .packages = \"penPass\") %dopar% sim()\n\n# Compile result year and result\nresult \u003c- do.call(rbind, out_list)\n\n# Summarize results\nplotter \u003c- result %\u003e% \n  group_by(year) %\u003e% \n  summarize(avg = median(smolts_out),\n            lwr = quantile(smolts_out, 0.05),\n            upr = quantile(smolts_out, 0.95)\n            )\n\n# Summarize stocking data\nstocker \u003c- penPass::stocking_data %\u003e% \n  filter(Year %in% plotter$year) %\u003e% \n  group_by(Year) %\u003e% \n  summarize(stocked = sum(n_stocked))\n\n# Plot the result\nggplot(plotter, aes(year, avg)) +\n  geom_point(pch = 15, size = 2) +\n  geom_segment(aes(xend = year, y = lwr, yend = upr)) +\n  geom_point(data = stocker, aes(x = Year, y = stocked), size = 2) +\n  xlab(\"Year\") +\n  ylab(\"Number of smolts (thousands)\") +\n  scale_y_continuous(\n    breaks = seq(0, 1e6, 2e5),\n    labels = seq(0, 1000, 200),\n    limits = c(0, 1e6)\n  ) +\n  theme_classic() +\n  theme(\n    axis.title.x = element_text(vjust = -1),\n    axis.title.y = element_text(vjust = 3),\n    axis.text = element_text(color = \"black\")\n  )\n```  ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanstich%2Fpenpass","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanstich%2Fpenpass","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanstich%2Fpenpass/lists"}