Reproducible CSAS Reports with R Markdown
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].
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.
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.
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.
Install the csasdown package:
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.
Run this line in your R console to create a new Research Document from the built-in template in whatever your working directory is:
You can do the same for a Technical Report:
or for a Science Response:
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
resdoc example contains other examples.
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.
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.
(Optional but recommended) Create a blank repository on GitHub, commit your changes, and push to GitHub. New to Git? Start with https://happygitwithr.com/.
- 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]
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 Rockﬁsh (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 groundﬁsh 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]
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/.
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
output: csasdown::resdoc_word: french: false
- This is also the only place you should be changing your document language.
techreport_wordfor 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:
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
The following components are ones you should edit to customize your report:
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.
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.
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.
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)
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.
This contains any
.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.
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.
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.