[docs] create living guidelines as site articles#491
Open
Schiano-NOAA wants to merge 7 commits into
Open
Conversation
…delines based on feedback from workshops and improve clarity
Contributor
Checklist
|
Contributor
New version checklist
|
Contributor
Code Metrics Report
Reported by octocov |
|
|
||
| At minimum, please include the following figures into the report (when applicable to the stock). Pre-made figures can be found in the {stockplotr} package downloaded from GitHub. | ||
|
|
||
| ### Appendices: Any information relevant for evaluation of the stock either during SSC or management review should be included in the appendix. The main assessment document should contain the minimum necessary information to inform and provide management advice for the stock while additional materials can be found in the appendix. It is not intended for the appendices to be a catch-all. We highly encourage authors to review the need and irreplaceable value of the report's content when it comes to addressing the audience. |
Collaborator
There was a problem hiding this comment.
Suggested change
| ### Appendices: Any information relevant for evaluation of the stock either during SSC or management review should be included in the appendix. The main assessment document should contain the minimum necessary information to inform and provide management advice for the stock while additional materials can be found in the appendix. It is not intended for the appendices to be a catch-all. We highly encourage authors to review the need and irreplaceable value of the report's content when it comes to addressing the audience. | |
| ### Appendices | |
| Any information relevant for evaluation of the stock either during SSC or statistical review should be included in the appendix. The main assessment document should contain the minimum necessary information to inform and provide management advice for the stock while additional materials can be found in the appendix. It is not intended for the appendices to be a catch-all. We highly encourage authors to review the need and irreplaceable value of the report's content when it comes to addressing the audience. |
Collaborator
There was a problem hiding this comment.
Did you mean to write "either during SSC or management review"? I think you mean "either during SSC or statistical review"?
|
|
||
| At minimum, please include the following tables into the report (when applicable to the stock). Pre-made figures can be found in the {stockplotr} package downloaded from GitHub. | ||
|
|
||
| ### Figures: |
Collaborator
There was a problem hiding this comment.
Suggested change
| ### Figures: | |
| ### Figures |
|
|
||
| ### References | ||
|
|
||
| ### Tables: |
Collaborator
There was a problem hiding this comment.
Suggested change
| ### Tables: | |
| ### Tables |
| * Management Benchmarks: decisions on management metrics/benchmarks (i.e. provide a rationale for why a specific F-proxy was recommended for management) | ||
| * Projections: Description of stock status, biological reference points (BRPs), and trends for each scenario; rebuilding times | ||
|
|
||
| ### Discussion: |
Collaborator
There was a problem hiding this comment.
Suggested change
| ### Discussion: | |
| ### Discussion |
| * Fishery Description: Short summary of fleet composition (i.e., boat types), gear types, species targeted, and fishing grounds (one paragraph) | ||
| * Ecosystem Considerations: If this section is not relevant, please ignore; however the default will state “Ecosystem considerations and/or climate indicators were not included in this assessment.” | ||
|
|
||
| ### Data: |
Collaborator
There was a problem hiding this comment.
Suggested change
| ### Data: | |
| ### Data |
| * Short statement describing assessment model used for the current management cycle and any data updates. | ||
| * Short summary of reference points, stock status, and projections. In the future, when using the {asar} R package, tables of reference points and projections will be automatically generated. | ||
|
|
||
| ### Introduction: |
Collaborator
There was a problem hiding this comment.
Suggested change
| ### Introduction: | |
| ### Introduction |
|
|
||
| ## Outline for Stock Assessment Reports | ||
|
|
||
| ### Executive Summary: |
Collaborator
There was a problem hiding this comment.
Suggested change
| ### Executive Summary: | |
| ### Executive Summary |
|
|
||
| ## General guidance | ||
|
|
||
| The following sections are a recommended outline for a U.S. fisheries stock assessment report. The goal is to effectively present information to managers to provide the best scientific advice available within a reasonable framework. This effort shifts the focus of assessment documents from being SSC and statistical review focus to more succinct review of information to aid in quicker decision making. {asar} is a tool that can generate a template that will meet the following guidelines. It contains standardized sections, figures, and tables for the user as well as formatting so the title page and authorship sections are not included here. Authors not using the template generated from {asar} should place tables and figures at the end of the document. |
Collaborator
There was a problem hiding this comment.
Suggested change
| The following sections are a recommended outline for a U.S. fisheries stock assessment report. The goal is to effectively present information to managers to provide the best scientific advice available within a reasonable framework. This effort shifts the focus of assessment documents from being SSC and statistical review focus to more succinct review of information to aid in quicker decision making. {asar} is a tool that can generate a template that will meet the following guidelines. It contains standardized sections, figures, and tables for the user as well as formatting so the title page and authorship sections are not included here. Authors not using the template generated from {asar} should place tables and figures at the end of the document. | |
| The following sections are components of a recommended outline for a U.S. fisheries stock assessment report. **The goal of reports created with these guidelines is to effectively present information to managers so as to provide the best scientific advice available within a reasonable framework.** This effort represents a shift in assessment document formatting from a focus on SSC/statistical review towards a more succinct presentation of information to aid in quicker decision-making. Therefore, **the main body of the report should contain the minimum necessary information to inform and provide management advice for the stock; additional materials, including information relevant for evaluation of the stock either during SSC or statistical review, should be placed in the appendix.** | |
| {asar} is a tool that can generate a report template aligning with the following guidelines. As the template contains standardized sections and formatting, some components-- such as the title page and authorship sections-- are not included here as each are generated automatically. Authors not using the template generated from {asar} should place tables and figures at the end of the document. |
Collaborator
There was a problem hiding this comment.
I took some info from the appendix section and moved it here because I think it's very important for explaining the essential attributes of the main report body vs. appendix. I'd recommend adding a link to the appendix section here too
|
|
||
| ### Executive Summary: | ||
|
|
||
| Where possible the executive summary should paraphrase the shared content of the body of the report to minimize redundancy. |
Collaborator
There was a problem hiding this comment.
Suggested change
| Where possible the executive summary should paraphrase the shared content of the body of the report to minimize redundancy. | |
| The executive summary should paraphrase the shared content of the body of the report to minimize redundancy. |
Collaborator
There was a problem hiding this comment.
What do you mean by "shared content"?
|
|
||
| ### Introduction: | ||
|
|
||
| The intent is to keep this section to two to three pages and provide a high level summary of the stock. The intention is to provide enough information in this section so the audience does not need to reference previous documents. Please include the species scientific name at the first mention of its common name. |
Collaborator
There was a problem hiding this comment.
Suggested change
| The intent is to keep this section to two to three pages and provide a high level summary of the stock. The intention is to provide enough information in this section so the audience does not need to reference previous documents. Please include the species scientific name at the first mention of its common name. | |
| The intent is to keep this section to **2-3 pages** and **provide a high level summary of the stock**. The intention is to provide enough information in this section so the audience does not need to reference previous documents. Please include the species' scientific name at the first mention of its common name. |
| The intent is to keep this section to two to three pages and provide a high level summary of the stock. The intention is to provide enough information in this section so the audience does not need to reference previous documents. Please include the species scientific name at the first mention of its common name. | ||
|
|
||
| * Stock ID (detailed description if appropriate and quantitative studies or data are behind the decision-making) | ||
| * Management history: Briefly describe the management history of the stock and status. Please only touch on historical policies that would have impacted modeling decisions or would be critical knowledge about the species that might affect its population dynamics. |
Collaborator
There was a problem hiding this comment.
Suggested change
| * Management history: Briefly describe the management history of the stock and status. Please only touch on historical policies that would have impacted modeling decisions or would be critical knowledge about the species that might affect its population dynamics. | |
| * Management History: Briefly describe the management history of the stock and status. Please only touch on historical policies that would have impacted modeling decisions or would be critical knowledge about the species that might affect its population dynamics. |
|
|
||
| * Stock ID (detailed description if appropriate and quantitative studies or data are behind the decision-making) | ||
| * Management history: Briefly describe the management history of the stock and status. Please only touch on historical policies that would have impacted modeling decisions or would be critical knowledge about the species that might affect its population dynamics. | ||
| * Assessment history |
Collaborator
There was a problem hiding this comment.
Suggested change
| * Assessment history | |
| * Assessment History |
|
|
||
| * Life History (growth, maturity, fecundity, natural mortality, meristics, etc.) | ||
| * Catch (retained and discarded) | ||
| * Indices and standardization (Fishery dependent and independent) |
Collaborator
There was a problem hiding this comment.
Suggested change
| * Indices and standardization (Fishery dependent and independent) | |
| * Indices and Standardization (Fishery dependent and independent) |
| * Life History (growth, maturity, fecundity, natural mortality, meristics, etc.) | ||
| * Catch (retained and discarded) | ||
| * Indices and standardization (Fishery dependent and independent) | ||
| * Composition data - age, length (Description, aging error, reweighting) |
Collaborator
There was a problem hiding this comment.
Suggested change
| * Composition data - age, length (Description, aging error, reweighting) | |
| * Composition Data - age, length (Description, aging error, reweighting) |
| * Catch (retained and discarded) | ||
| * Indices and standardization (Fishery dependent and independent) | ||
| * Composition data - age, length (Description, aging error, reweighting) | ||
| * Absolute abundance (if applicable) |
Collaborator
There was a problem hiding this comment.
Suggested change
| * Absolute abundance (if applicable) | |
| * Absolute Abundance (if applicable) |
| * Indices and standardization (Fishery dependent and independent) | ||
| * Composition data - age, length (Description, aging error, reweighting) | ||
| * Absolute abundance (if applicable) | ||
| * Environmental/ecosystem indicator data. Please include a blanket statement if none are considered. |
Collaborator
There was a problem hiding this comment.
Suggested change
| * Environmental/ecosystem indicator data. Please include a blanket statement if none are considered. | |
| * Environmental/Ecosystem Indicator Data. Please include a blanket statement if none are considered. |
| * Model Fits | ||
| * Model Diagnostics | ||
| * Sensitivity Analyses | ||
| * Management Benchmarks: decisions on management metrics/benchmarks (i.e. provide a rationale for why a specific F-proxy was recommended for management) |
Collaborator
There was a problem hiding this comment.
Do you mean "e.g." (an example), as opposed to "i.e."?
|
|
||
| ### Tables: | ||
|
|
||
| At minimum, please include the following tables into the report (when applicable to the stock). Pre-made figures can be found in the {stockplotr} package downloaded from GitHub. |
Collaborator
There was a problem hiding this comment.
Suggested change
| At minimum, please include the following tables into the report (when applicable to the stock). Pre-made figures can be found in the {stockplotr} package downloaded from GitHub. | |
| At minimum, please include the following tables in the report (when applicable to the stock). Semi-automated tables can be made using the [{stockplotr}](github.com/nmfs-ost/stockplotr) package. |
|
|
||
| ### Tables: | ||
|
|
||
| At minimum, please include the following tables into the report (when applicable to the stock). Pre-made figures can be found in the {stockplotr} package downloaded from GitHub. |
|
|
||
| ### Figures: | ||
|
|
||
| At minimum, please include the following figures into the report (when applicable to the stock). Pre-made figures can be found in the {stockplotr} package downloaded from GitHub. |
Collaborator
There was a problem hiding this comment.
Suggested change
| At minimum, please include the following figures into the report (when applicable to the stock). Pre-made figures can be found in the {stockplotr} package downloaded from GitHub. | |
| At minimum, please include the following figures in the report (when applicable to the stock). Semi-automated figures can be made using the [{stockplotr}](github.com/nmfs-ost/stockplotr) package. |
| At minimum, please include the following tables into the report (when applicable to the stock). Pre-made figures can be found in the {stockplotr} package downloaded from GitHub. | ||
|
|
||
| ### Figures: | ||
|
|
| @@ -0,0 +1,87 @@ | |||
| --- | |||
| title: "NMFS Stock Assessment Guidelines" | |||
Collaborator
There was a problem hiding this comment.
Minor change to match the menu item name
Suggested change
| title: "NMFS Stock Assessment Guidelines" | |
| title: "NMFS Stock Assessment Report Guidelines" |
Collaborator
sbreitbart-NOAA
left a comment
sbreitbart-NOAA
left a comment
There was a problem hiding this comment.
Thanks for putting in the time to add this to the website! It will make a very important addition.
The changes I've suggested are mostly about ensuring consistent style across the document (capitalization, headers, etc.). I've also striven to make the intro more clear by summarizing some info from the appendix and moving it up there, since the idea of what goes into the main report body vs. appendix is critical.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What is the feature?
How have you implemented the solution?
Does the PR impact any other area of the project, maybe another repo?