Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
R
 
 
 
 
man
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

csasdown

Reproducible CSAS Reports with R Markdown

Travis build status Coverage status

csasdown is an R package that facilitates generating Canadian Science Advisory Secretariat (CSAS) documents in PDF or Word format using R Markdown and bookdown.

Please check the wiki for hints and FAQs.

Slides from a short workshop on csasdown: [PDF].

Have a problem? If it's a bug or feature request please post it as a GitHub Issue. If it's a quick question on csasdown use, find us on DFO MS Teams.

If you use csasdown to write a report, please let us know so we can add it to the list of publications using the package. This helps us justify spending our work time on its development. You can post an issue, make a pull request adding it to this readme, send us a quick email (contact details here), or find us on DFO MS Teams.

Initial setup

To compile PDF documents using R, you need to have Pandoc, LaTeX, and several related packages installed. If you have a recent version of RStudio, then you already have Pandoc.

  1. You will need to install LaTeX if you do not have it already. Read this Wiki page for a detailed description of this procedure. Most likely you will want to use the R package tinytex.

  2. Install the csasdown package:

install.packages("remotes")
remotes::install_github("pbs-assess/csasdown")
  1. Create a new project in a new directory to hold your document project and all the files that csasdown creates. If you're using RStudio: click File -> New Project -> New Directory -> New Project, then type the name of the project in the Directory name box. Check the box Open in new session. If you are going to use GitHub version control (or if you are not sure), check the box Create a git repository. Click Create Project. A new RStudio project will open up, and will have its working directory set to the new document project's directory.

  2. Run this line in your R console to create a new Research Document from the built-in template in whatever your working directory is:

csasdown::draft("resdoc")

You can do the same for a Technical Report:

csasdown::draft("techreport")

or for a Science Response:

csasdown::draft("sr")

Note that the techreport example contains a lot of information on getting started with R Markdown and should be the first one you render if you are new to csasdown. The resdoc example contains other examples.

  1. Render the document right away to make sure everything works by opening the file index.Rmd and clicking the knit button in RStudio. Once completed, a preview pane showing the PDF document will appear. The location of the PDF is in the _book directory. See the Rendering section below for more information.

  2. Read the output PDF carefully and compare with what is written in the .Rmd files. This will help you understand more quickly how the document is put together and how you might want to structure your document.

  3. (Optional but recommended) Create a blank repository on GitHub, commit your changes, and push to GitHub. New to Git? Start with https://happygitwithr.com/.

  1. Need to make an English and French version? csasdown has support for both. Also see csasdown's sister package rosettafish.

Publications prepared using csasdown

Obradovich, S.G., Hansen, S.C., Zhang, Z., MacNeill, S., Nichol, L.M., Rooper, C.N., St. Germain, C., Curtis, D.L., Waddell, B.J., and Barton, L.L. In press. Pre-COSEWIC review of DFO information on Northern Abalone (Haliotis kamtschatkana) along the Pacific Coast of Canada. DFO Can. Sci. Advis. Sec. Res. Doc. In press/nnn. iv + 74 p.

Ouellette-Plante, J., Chabot, D., Nozères, C. et Bourdages, H. 2020. Régimes alimentaires de poissons démersaux provenant des relevés écosystémiques du NGCC Teleost dans l’estuaire et le nord du golfe du Saint-Laurent, août 2015-2017. Rapp. tech. can. sci. halieut. aquat. 3383: v + 124 p. [French] [English]

Holt, C.A., Freshwater, C., Holt, K., and Huang, A.-M. 2020. A quantitative tool for evaluating rebuilding plans for Pacific salmon. Can. Tech. Rep. Fish. Aquat. Sci. 3402: v + 26 p. [English]

DFO. 2020. Population status update for the northern resident killer whale (Orcinus Orca) in 2019. DFO Can. Sci. Advis. Sec. Sci. Resp. 2020/040. [English] [French]

Hansen, S.C., Obradovich, S.G., Rooper, C.N., Waddell, B.J., Nichol, L.M., MacNeill, S., and Barton, L.L. 2020. Identifying variables for standardization of the Northern Abalone (Haliotis kamtschatkana) Index Site Surveys time series (1978-2018) based on survey methodology and environmental variability. Can. Tech. Rep. Fish. Aquat. Sci. 3330: vii + 110 p. [English]

Boldt, J., Anderson, E., King, J., Dennis-Bohm, H., Zubkowski, T., and Flostrand, L. 2020. Integrated Pelagic Ecosystem Survey on the Vancouver Island Continental Shelf, June 15 - July 15, 2019. Can. Tech. Rep. Fish. Aquat. Sci. 3339: vii + 85 p. [English]

Lacko, L.C. and Acheson, S.M. and Connors, B.M. 2020. Summary of the Annual 2018 and 2019 Sablefish (Anoplopoma fimbria) Trap Surveys, October 9 - November 19, 2018 and October 8 - November 25, 2019. Can. Tech. Rep. Fish. Aquat. Sci. nnn: viii + 63 p. [GitHub Repository]

DFO. 2020. Evaluating the robustness of candidate management procedures in the BC Sablefish (Anoplopoma fibria) fishery for 2019-2020. DFO Can. Sci. Advis. Sec. Sci. Resp. 2020/025. [GitHub Repository]

Haggarty, D.R., Huynh, Q.C., Forrest, R.E., Anderson, S.C., Bresch, M.J., Keppel, E.A. In review. Evaluation of potential rebuilding strategies for Inside Yelloweye Rockfish (Sebastes ruberrimus) in British Columbia. DFO Can. Sci. Advis. Sec. Res. Doc. Accepted at Regional Peer Review meeting in June 2020. v + 135 p. [GitHub repository]

Anderson, S.C., Forrest, R.E., Huynh, Q.C., Keppel, E.A. In review. A management procedure framework for groundfish in British Columbia. DFO Can. Sci. Advis. Sec. Res. Doc. Accepted at Regional Peer Review meeting in June 2020. v + 133 p. [GitHub repository]

DFO. 2020. Stock status update with application of management procedures for Pacifc Herring (Clupea pallasii) in British Columbia: Status in 2019 and forecast for 2020. DFO Can. Sci. Advis. Sec. Sci. Resp. 2020/004. [English] [French] [GitHub repository]

Forrest, R.E., Anderson, S.C., Grandin, C.J., and Paul J. Starr. In press. Assessment of Pacific Cod (Gadus macrocephalus) for Hecate Strait and Queen Charlotte Sound (Area 5ABCD), and West Coast Vancouver Island (Area 3CD) in 2018. DFO Can. Sci. Advis. Sec. Res. Doc. In press/nnn. iv + 204 p.

Swain, D.P., Ricard, D., Rolland, N., and Aubry, É. 2019. Assessment of the southern Gulf of St. Lawrence Atlantic Cod (Gadus morhua) stock of NAFO Div. 4T and 4Vn (November to April), March 2019. DFO Can. Sci. Advis. Sec. Res. Doc. 2019/038. iv + 105 p. [English] [French]

Anderson, S.C., Keppel, E.A., Edwards, A.M. 2019. A reproducible data synopsis for over 100 species of British Columbia groundfish. DFO Can. Sci. Advis. Sec. Res. Doc. 2019/041. vii + 321 p. [English] [French] [GitHub repository]

Day-to-day writing

You need to edit the individual chapter R Markdown files to write your report. While writing, you should git commit your work frequently. For a gentle novice-friendly guide to getting starting with using Git with R and RStudio, see http://happygitwithr.com/.

Rendering


Render the document often!

This can't be stressed enough. Every time you add something new, render the document to make sure you didn't break the build. It is much easier to find the problem when only one small known change was made since the last time it was rendered.


To render your report into a PDF or Word document, open index.Rmd in RStudio and then click the "knit" button:

To change the output formats between PDF and Word look at the YAML header part of index.Rmd (the part between the two sets of triple dashes) and change this:

output:
 csasdown::resdoc_pdf:
   french: false

to this:

output:
 csasdown::resdoc_word:
   french: false

Notes

  • This is also the only place you should be changing your document language.
  • Replace resdoc_pdf and resdoc_word with sr_pdf, sr_word, techreport_pdf, or techreport_word for other document types.

Alternatively, if you're not using RStudio, you can run this from the R console, assuming your have set the main directory (the one with the index.Rmd file) as your working directory:

bookdown::render_book("index.Rmd")

This method of rendering also allows you to insert browser() calls in your code and stop compilation to debug. It also does not open a preview viewer once finished, so you will have to navigate to the _book/ directory and open it up manually.

The rendered PDF or Word file of your report will be deposited in the _book/ directory.

Components

The following components are ones you should edit to customize your report:

_bookdown.yml

This is the main configuration file for your report. It determines what .Rmd files are included in the output, and in what order. Arrange the order of your chapters in this file and ensure that the names match the names in your folders. If you add new .Rmd files, add them here. You may comment out some files while working on others by placing a # in front of them. This will stop compilation of those files, reducing the time to compile while working on another file.

index.Rmd

This file contains all the meta information that goes at the beginning of your document. You'll need to edit this to put your name on the first page, add the title of your report, etc. The name of this file cannot be changed.

01-chap1.Rmd, 02-chap2.Rmd, etc.

These are the .Rmd files for each chapter/section of your report. Write your report in these. You can delete any or all of these and create as many of your own as you wish, but if you do you must change the _bookdown.yml file accordingly.

bib/

Store your bibliography (as BibTeX files) here. You might look at the citr addin and Zotero to efficiently manage and insert citations.

csl/

Style files for bibliographies should be stored here. You will want to use the included csas.csl, which is based on the CJFAS (Canadian Journal of Fisheries and Aquatic Sciences) .csl file.

figure/ and data/

Store pre-made figures and data here and reference them in your R Markdown files. See the bookdown book for details on cross-referencing items using R Markdown.

templates/

This contains any .docx or .tex files that are need to compile the documents. With the exception of the title page file, you shouldn't have to edit any of these files.

Related projects

This project has drawn directly on code and ideas from the following:

NAFOdown is a derivative of csasdown for rendering NAFO (Northwest Atlantic Fisheries Organization) reports.

Contributing

If you would like to contribute to this project, please start by reading our Guide to Contributing. Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

About

📖 An R package for creating CSAS reports in PDF or Word format with R Markdown and bookdown

Topics

Resources

License

You can’t perform that action at this time.