Add Citation Style Files to the template

[chantelwetzel-noaa]

The reference format and citations in my document were not consistent. As example the reference section either used author first name abbreviation or full name depending upon what information was in the bib file. The citations typically followed the correct format of last name and date but sometimes for unknown reasons the citation would be first and middle name initials, last name, and then year.

I am not terribly skilled at figuring out the best way to define citation and reference formatting in rmarkdown and typically steal a defined style file from someone else. In this instance I pirated the csl file from the lingcod repository and then updated the preamble section of my document and both of my issues were fixed.

I think it would be helpful to include one or more citation style files within the skeleton and then users could opt for the right style for their document. Since I am not skilled with the citation styles I may be missing some items that may cause issues but if we could add a default style to the document that would provide a starting point for users.

[kellijohnson-NOAA]

Thanks @chantelwetzel-noaa for the great suggestion. I think that we should have a global style file based on the fact that the Council probably wants citations in a single format and then a few auxiliary ones that produce documents using a different but well-used format. There are many out there and the Council's way of formatting references is not mainstream imo. So a few options would be nice.

I think some of the issues with "authors" is how they are entered in the bib file. Technically, the style file should be able to abbreviate a first or middle name appropriately based on the rules in the style file. It is best practice to write out the entire name in the bib file because there could be an instance where you might want full names and if you don't have the information available the style file cannot make it up. Feel free to post some examples of an entry in the bib file that went wrong in the resulting pdf.

[chantelwetzel-noaa]

I totally agree that the bib file should be standardized and have full names of authors when possible but this is rarely the case (especially for me). I think what the default style of the packages was to use full first names in citations. However, when there are some citations with only first name initials you end up with a mix of full names and abbreviations in the citations.

Here is an example of a bib file that resulted in the citation of last name, full first name:

@article{bizzarro_diet_2017-1, title = {Diet composition and foraging ecology of {U}.{S}. {Pacific} {Coast} groundfishes with applications for fisheries management}, volume = {100}, issn = {0378-1909, 1573-5133}, url = {http://link.springer.com/10.1007/s10641-016-0529-2}, doi = {10.1007/s10641-016-0529-2}, language = {en}, number = {4}, urldate = {2020-12-24}, journal = {Environmental Biology of Fishes}, author = {Bizzarro, Joseph J. and Yoklavich, Mary M. and Wakefield, W. Waldo}, month = apr, year = {2017}, pages = {375--393}, file = {Bizzarro et al. - 2017 - Diet composition and foraging ecology of U.S. Paci.pdf:C\:\Users\Chantel.Wetzel\Zotero\storage\SRDRGXV2\Bizzarro et al. - 2017 - Diet composition and foraging ecology of U.S. Paci.pdf:application/pdf} }

with the citation appearing as:

Bizzarro, Joseph J., Mary M. Yoklavich, and W. Waldo Wakefield. 2017. “Diet Composition and Foraging Ecology of U.S. Pacific Coast Groundfishes with Applications for Fisheries Management.” Environmental Biology of Fishes 100 (4): 375–93. https://doi.org/10.1007/s10641-016-0529-2.

The strangest issue was that the inline citations would typically appear correctly (Wetzel 2019) but for select references would appear as D.J. Miller and Lea 1972. What the heck? Here is the brief bib entry for that citation:

@techreport{miller_guide_1972, title = {Guide to coastal {Marine} {Fishes} of {California}}, number = {Fish Bulletin 157}, institution = {State of California Department of Fish and Game Bureau of Marine Fisheries}, author = {Miller, Daniel J and Lea, Robert N}, year = {1972}, pages = {152} }

I also experienced this issue with article citations for entries in the bib file that appeared relatively complete:

@article{cope_approach_2011, title = {An {Approach} to {Defining} {Stock} {Complexes} for {U}.{S}. {West} {Coast} {Groundfishes} {Using} {Vulnerabilities} and {Ecological} {Distributions}}, volume = {31}, issn = {0275-5947, 1548-8675}, url = {http://doi.wiley.com/10.1080/02755947.2011.591264}, doi = {10.1080/02755947.2011.591264}, abstract = {The Magnuson–Stevens Fishery Conservation and Management Act (MSA) requires active management of all stocks at risk of overfishing or otherwise in need of conservation and management. In the Pacific Fishery Management Council groundfish fishery management plan, about two-thirds of the more than 90 managed stocks are currently without traditional assessments to help define stock status in relation to management targets. Stock complexes are often employed for management purposes in such situations. The guidelines issued in response to the 2006 MSA amendments defined a complex as a group of stocks with similar geographic distributions, life histories, and vulnerabilities to fisheries. This work uses productivity–susceptibility analysis (PSA) to measure the vulnerabilities of 90 managed groundfish stocks, 64 of which are currently managed within stock complexes. These stock complexes are reevaluated by first using a partitioning cluster analysis to group the stocks by depth and latitude. Vulnerability reference points are then established based on the PSA results to determine vulnerability groups of low, medium, high, and major concern within each ecological group. This method is a simple and flexible approach to incorporating vulnerability measures into stock complex designations while providing information with which to prioritize stockand complex-specific management.}, language = {en}, number = {4}, urldate = {2019-06-07}, journal = {North American Journal of Fisheries Management}, author = {Cope, Jason M. and DeVore, John and Dick, E. J. and Ames, Kelly and Budrick, John and Erickson, Daniel L. and Grebel, Joanna and Hanshew, Gretchen and Jones, Robert and Mattes, Lynn and Niles, Corey and Williams, Sarah}, month = aug, year = {2011}, pages = {589--604}, file = {Cope et al. - 2011 - An Approach to Defining Stock Complexes for U.S. W.pdf:C\:\Users\Chantel.Wetzel\Zotero\storage\NX7JK5MF\Cope et al. - 2011 - An Approach to Defining Stock Complexes for U.S. W.pdf:application/pdf} }

[kellijohnson-NOAA]

Thanks @chantelwetzel-noaa for the clarification and I am glad that the csl file worked out. I will

• [x] add the csl file from the lingcod repository as the default csl here
• [x] add a call to the yaml of the appropriate .rmd file that specifies which csl file to use

Collaborators should comment below if they want other csl styles to be added, and potentially why. We should also think if we want to format the suggested citation of each stock assessment in the same format that we are using for the Reference section because right now the authors, starting with the second author, is initial first then last name. This was how Devore told me it should be done, but I was too lazy to find a csl file that formatted the references this way. I will leave this issue open for 7 days (2021-10-13) in case people want to propose additional files. After that, feel free to make a new issue and request that a csl style be added or make a pull request with the suggestion :partying_face:.

[kellijohnson-NOAA]

I am wondering if we should use ICES Journal of Marine Science formatting because that is what ICES stocks do and it is mandated in their TOR. Given we have no mandate or major journal to guide us here, I thought conforming might be appropriate. We could also see what DFO does (cc @seananderson).

[seananderson]

There's a Canadian Science Advisory Secretariat (CSAS) standard reference format, which is very close to the CJFAS reference format. We modified the CJFAS .csl file to match and use only that. https://github.com/pbs-assess/csasdown/tree/master/inst/rmarkdown/templates/resdoc/skeleton/csl

You definitely don't want to write one of those from scratch. I assume you've seen it, but this probably the best interface to the official repository: https://www.zotero.org/styles and this can be useful for modifying an existing csl file: https://editor.citationstyles.org/visualEditor/

[kellijohnson-NOAA]

Thanks Sean, we have been using the csl from CJFAS but I wasn't sure if that was the "best" option.