Scholarly writing

OST-HS23: Open Science Tools
authoring and publishing workflows for collaborative scientific writing

Lars Schöbitz

October 24, 2023

Reading - pre-work

Good Enough Practices in Scientific Computing

Your turn

Good Enough Practices in Scientific Computing

• Which recommended practice did you choose?
• In groups of 3: Explain to your neighbours how the recommended practice would improve your research process.

10:00

Anatomy of a Quarto scholarly article

Components

1. Metadata: YAML

2. Text: Markdown

3. Code: Executed via knitr or jupyter

Weave it all together, and you have a beautiful, reproducible journal article!

Four terms

• Citation
• Reference
• Bibliography
• Citation Style Language (CSL)

What’s a Citation?

• Inequality underpins waste management systems, structuring who can or cannot access services (Kalina et al., 2023).
• Many visitors still expect a personal pick-up, despite the availability of taxi services (Tilley & Kalina, 2021).
• In Tilley & Kalina (2021), the authors describe how visitors still expect a personal pick-up, despite the availability of taxi services.

Explanation A citation is a reference to the source of information used in your research. Any time you directly quote, paraphrase, or summarize the essential elements of someone else’s idea in your work, an in-text citation should follow. For example, in APA style, a citation might look like this: (Tilley and Kalina, 2021).

Analogy Think of a citation as a signpost on a road trip. It tells you where the information came from and points you in the direction of the full details (the destination), which can be found in the reference list.

What’s a Citation?

• Inequality underpins waste management systems, structuring who can or cannot access services (Kalina et al., 2023).
• Many visitors still expect a personal pick-up, despite the availability of taxi services (Tilley & Kalina, 2021).
• In Tilley & Kalina (2021), the authors describe how visitors still expect a personal pick-up, despite the availability of taxi services.

Important: The period is after the citation.

What’s a Reference?

• detailed description of the source of information
• author’s name, title, year of publication, publisher, DOI, etc.

Tilley, E., & Kalina, M. (2021). “My flight arrives at 5 am, can you pick me up?”: The gatekeeping burden of the african academic. Journal of African Cultural Studies, 33(4), 538–548. https://doi.org/10.3929/ethz-b-000493677

Explanation

A reference is a detailed description of the source of information that you want to give credit to via a citation. In APA style, a reference provides comprehensive details about a source, including the author’s name, the title of the source, the year of publication, and the publisher or URL.

Analogy

A reference is like a detailed map at the end of your road trip (paper). It provides all the details about the source (destination) that the citation (signpost) pointed to.

What’s a Bibliography?

• list of references in a research paper or project
• includes all sources used, whether they were directly quoted or not
• listed alphabetically by the author’s last name in the reference list

References

Kalina, M., Makwetu, N., & Tilley, E. (2023). “The rich will always be able to dispose of their waste”: A view from the frontlines of municipal failure in Makhanda, South Africa. Environment, Development and Sustainability. https://doi.org/10.1007/s10668-023-03363-1

Tilley, E., & Kalina, M. (2021). “My flight arrives at 5 am, can you pick me up?”: The gatekeeping burden of the african academic. Journal of African Cultural Studies, 33(4), 538–548. https://doi.org/10.3929/ethz-b-000493677

Wilson, G., Bryan, J., Cranston, K., Kitzes, J., Nederbragt, L., & Teal, T. K. (2017). Good enough practices in scientific computing. PLOS Computational Biology, 13(6), e1005510. https://doi.org/10.1371/journal.pcbi.1005510

What’s the Citation Style Language (CSL)?

• It’s what your citation and generated bibliography look like
• APA (American Psychological Association) Style, Chicago Style, IEEE Style, Vancouver Style, etc. (over 10,000 styles in Zotero Style Repository)

The Citation Style Language (CSL) describes the formatting of citations, notes, and bibliographies. It was created to provide an open format that can be used by any application

What’s the Citation Style Language (CSL)?

author-date: Many visitors still expect a personal pick-up, despite the availability of taxi services (Tilley & Kalina, 2021).

numeric Many visitors still expect a personal pick-up, despite the availability of taxi services [1].

Why use a reference management tool?

Managing references manually:

• is a lot of work
• is prone to mistakes
• makes you lose track

Why use Zotero?

• free
• open source: developed in public
• transparent about access to your own data
• cross-platform (Windows, Mac, Linux)
• collaboration in groups
• integration with word processors

Mendeley

1. Mendeley is owned by Elsevier.
2. It encrypts your database and makes money with your data
3. You can only collaborate with 3 people on one project.

EndNote

1. EndNote doesn’t come free, you need to buy a license.
2. They also used a prioprietary citation style files that could only be opened by EndNote.

Scholarly Articles in Quarto

Quarto supports

• a standardized schema for authors and affiliations that can be expressed once int the source document,

• the use of Citation Style Language (CSL) to automate the formatting of citations and bibliographies, and

• outputting to pdf, html, and docx with custom formatting,

according to the styles required for various journals,

and creating the LaTeX required for submission to multiple journals.

Front matter

Quarto provides a rich set of YAML metadata keys to describe the details required in the front matter of scholarly articles.

• title
• author
• affiliation
• abstract
• keywords
• citation
• licensing
• etc.

Our turn

• Open scholarly-writing.qmd in RStudio.
• Use the visual editor mode
• Follow the instructions in the document

Journal formats

github.com/quarto-journals

Journal / Publisher	Name
Association of Computing Machinery	acm
American Chemical Society	acs
American Geophysical Union	agu
Biophysical journal	biophysical-journal
Elsevier Journals	elsevier
American Statistical Association Journals	jasa
Journal of Statistical Software	jss
Public Library of Science	plos

Learn more

quarto.org/docs/journals/index.html