How not to worry about APA style

If you have gone through the trouble of picking up a copy of the Publication Manual of the American Psychological Association (APA, 2010), I’m sure your first reaction was similar to mine: “Ugh! 272 pages of boredom.” Do people actually read this monster? I don’t know. I don’t think so. I know I haven’t read every last bit of it. You may be relieved to hear that your reaction resonates with some of the critique that has been voiced by senior researchers in Psychology, such as Henry L. Roediger III (2004). But let’s face it: APA style is not going anywhere. It is one of the major style regimes in academia and is used in many fields other than Psychology, including medical and other public health journals. And to be fair, standardizing academic documents is not a bad idea. It helps readers to efficiently access the desired information. It helps authors by making the journal’s expectations regarding style explicit, and it helps reviewers to concentrate on the content of a manuscript. Most importantly, the guidelines set a standard that is accepted by a large number of outlets. Imagine a world in which you had to familiarize yourself with a different style every time you chose a new outlet for your scholarly work.

APA style is hard

The data presented in an earlier post on this blog indicate that Psychology students find it difficult to adhere to the APA guidelines. Among the 9 most common mistakes in submissions to the Journal of European Psychology Students are

  1. missing or incorrect running head (86.3%)
  2. errors with in-text citations (84.0%)
  3. missing or incorrectly formatted page numbers (75.0%)
  4. incorrect margins (52.2%)
  5. indentation of first line of each paragraph (43.1%)

From my experience as an editorial assistant at the journal Experimental Psychology I know that fully mastering APA style is hard even for more senior researchers — and that’s okay. In fact, I’m glad that most researchers use their limited time on research (or teaching) rather than memorizing the “Publication Manual”. Life is too short to learn the ins and outs of APA style.

How not to worry about APA style

If you want to publish psychological research, you will have to produce properly formatted APA style manuscripts. Fortunately, this is a problem many researchers face; in other words, there is no reason to start from scratch. You could use an APA template for common word processors such as Microsoft Word or Libre Office that takes care of the page setup, line spacing, etc. But to be up-front, I want to convince you that there is a better way to write your manuscripts that prevents all of the above mentioned errors and more. I want to introduce you to Markdown, an easy-to-read and -write annotation system that makes writing APA style a breeze.

Don’t mix content and style

A general principle in typesetting — be it on (digital) paper or the web — is to separate content and style. Separation is commonly achieved through the use of a markup language, which is a system of document annotations. These annotations declare portions of text as title, section headings, or list items but crucially, they are agnostic to what this means visually (e.g., <bold>text</bold> instead of text). There are several advantages to this approach but I’ll only briefly name three of them here:

  1. Focus on writing. It seems that a common form of procrastination for many writers is making a document pretty. Adding a newline here or a manual line break there, moving a table just two pixels to the left, etc. When writing a markup document in a plain text document it let’s you focus on the content rather than the style.
  2. Swiftly adjust the style. If your paper is rejected and the next target journal prefers a different flavor of APA style, there is no need to touch your writing. As a simple example, I recently submitted a paper to a journal that asked me to collect all figure captions at the end of the document on one page rather than printing them below the corresponding figures. Because my captions were declared as such, I left the text unchanged (captions below the figures) and simply changed the option controlling the captions’ position within the document.
  3. Write plain text files. Once you move to writing in plain text files, you open yourself up to a whole new world of very helpful tools to facilitate your writing and collaboration, such as dynamic documents or the version control system git, but that’s a topic for another blog post.

Learn Markdown

Am I suggesting you replace one evil with another? Not learning APA style requires learning a whole new language? No, Markdown is intended to be as easy-to-read and easy-to-write as possible. The following is an excerpt from the APA example manuscript written in Markdown.

Without knowing anything about Markdown, it should be easy to guess what the annotations mean. # declare hierarchical section headings, <!-- and --> envelope comments, and [^p] adds a reference to a footnote. As you can see, Markdown is easy to learn and will quickly save time in manuscript preparation. The only thing that may be scary at first are the equations enveloped by $. Equations are written in the powerful, yet, fairly simple equation syntax used in LaTeX. Although LaTeX is widely used to write entire manuscripts (not just equations), it is not very popular in the field of Psychology. I suspect that the neglect is largely due to its complexity and long learning curve, which I find rather deterring myself. Both seem to outweigh the advantages of the system when it comes to handling citations and cross-references or typesetting large documents, complex tables, and equations which are rare in the average Psychology paper. That is why I like the idea of using Markdown as a simple interface to harness the power of LaTeX without having to write or know much about LaTeX.

Use a reference manager

If you are not already using a reference manager such as Zotero, I strongly suggest you start doing so. Reference managers are like iTunes for your literature; they help you search, download, and organize papers. Most importantly, with a few clicks you can export a collection of references you need for a paper into a .bib-file. Once your references are in a .bib-file that resides in the same folder as your Markdown-file, you can easily add citations to your Markdown document. Each reference has a unique handle, e.g. lewandowsky_computational_2011, which you can use in Markdown. @lewandowsky_computational_2011 creates an in-text citation; [@lewandowsky_computational_2011] creates a citation in parentheses. Everything reference-related, such as in-text citation and the reference section, will be taken cared of automatically.

Let R take care of the rest

To turn your Markdown file into a polished APA manuscript, you need to set a few options and then create a .pdf-file. Both could be done manually but the way I do this is by using the text editor RStudio (a text editor for R, but you literally need no knowledge about R to do this) and papaja, the R package I’m developing with Marius Barth. In turning your Markdown into a .pdf-file there are intermediate steps and software involved that are really not important to know. RStudio lets you do all of this by the click of a button. As a side note, if you use R for your analyses, you can embed the analysis code into your document and insert statistics, figures, and tables on the fly while creating your manuscript. This is what is called a dynamic document (Xie, 2013) and the topic of a future blog post.

How to create your first manuscript

Requirements

If you want to try writing a manuscript in Markdown, you need to install a couple of things:

Make sure you install the complete—not the basic—TeX version and if you are on Ubuntu 14.04 you need a couple of extra TeX packages. Finally, install the development version of papaja by opening RStudio and copying the following into the R console:

New documents

Once you installed papaja you can create an APA document through the menus in RStudio (File > New File > R Markdown). If you take the time to explore the menu a little bit you will find that Markdown can be used to create a range of different documents like slides or HTML-files. template_selection The new text file will contain a document header enveloped by --- followed by the body of the text. There will be some scary looking R stuff following the header; feel free to delete all of it. To preview your manuscript click the Knit-Button. knitting If you click on the question mark next to it, you can get help regarding Markdown in case you get stuck. Also, a look at the papaja-example document may be helpful. All you need to do now is fill in the meta-information, e.g. authors, title, and abstract in the header of the document, start writing, and stop worrying about APA style.

References

American Psychological Association. (2010). Publication Manual of the American Psychological Association (6th edition.). Washington, DC: American Psychological Association.

Roediger, H. L. (2004). What Should They Be Called? APS Observer, 17(4). Retrieved from http://journal.sjdm.org/roediger.html

Xie, Y. (2013). Dynamic Documents with R and knitr. Boca Raton: Productivity.

About the author

Frederik Aust Frederik Aust is pursuing a PhD in cognitive psychology at the University of Cologne. He is interested in mathematical models of memory and cognition, open science, and R programming.

Facebooktwitterrss
  • ‘Wale Oni

    This is cool!

  • https://www.facebook.com/app_scoped_user_id/896605673711691/ Marian Sauter

    This sounds great. Is there a way to convert to doc, though? I guess the main problem is that my supervisor can more easily annotate docs than PDFs.

  • http://www.konscience.de/ Katrin

    @Marian: Yes, Markdown can be converted to DOC(X) as well. Just look into the “Document” section, where the “New R Markdown” discplays the “From Template” section. A more advanced approach can be found on https://github.com/JensErat/scientific-markdown#markdown-for-scientific-publications.

  • https://twitter.com/FrederikAust Frederik Aust

    Hi Marian, if you are using papaja you can try “output: papaja::apa6_word” in the YAML header. Note, that this function is currently experimental, but I think it will get you about 3/4 of the way. You will need to do some manual adjustments, though. But I really want to improve this in the near future.

  • http://www.marsja.se Erik Marsja

    Hey,

    The in-text citations do NOT follow APA-style. That is, with papaja you get in-text citations using ampersand rather than the word “and”.

    As far as I could find when searching for a solution is that this seems to be a problem with pandoc and using apa.csl (or any other csl for that matter).

    One possible workaround seems to be something like “Firstauthor and Secondauthor [-@Firstauthor2015]” which produces “First author and Second author (2015)” rather than “Firstauthor & Secondauthor (2015)”.

    Anyone else having this problem? If so, anyone have a solution to this?

  • https://twitter.com/FrederikAust Frederik Aust

    Hi Erik,

    unfortunately, you are absolutely right. In fact, CSL does not support in-text citations at all. The fact that it’s possible to use in-text citations is thanks to the pandoc-developers. I’ve been looking for a solution to this for a while but your comment put me back on the issue. I requested a fix for this problem with the pandoc-citeproc team last night and they have already replied that this shouldn’t be too hard to fix: https://github.com/jgm/pandoc-citeproc/issues/177

    I’m optimistic we will see this issue resolved in the near future.

    Thanks for trying RMarkdown and papaja. Any other thoughts so far?

  • http://www.marsja.se Erik Marsja

    Hi Frederik,

    Thank you for your reply. I really like papaja and use it for my two coming papers and I like it. Hope the pandoc-developers fix it.

    Thanks for developing a promising package.

  • Avraham N Kluger

    Hi,

    I tried to follow the step above, but when I run Knit on the template I get a bunch of errors when the first one is

    This is pdfTeX, Version 3.1415926-2.5-1.40.14 (MiKTeX 2.9 64-bit)
    (Fatal format file error; I’m stymied)

    Any advice, with much appreciation?

    Avi

  • https://twitter.com/FrederikAust Frederik Aust

    Hi Avi,

    that’s odd. I suspect this may have to do with your MiKTeX installtion. Can you knit a standard pdf_document (File > New file > R Markdown > PDF)?

    The error you describe is discussed here: http://tex.stackexchange.com/questions/243571/pdflatex-error-when-rendering-tex-as-pdf-in-texstudio-on-windows-7

    Let me know if this resolves the issue.

  • Frederik Aust

    Hi Avi,

    I suspect this may have something to do with your MiKTeX installation. Can you knit a standard pdf_document (File > New file > R Markdown > PDF)?

    The error you describe is discussed here: http://tex.stackexchange.com/questions/243571/pdflatex-error-when-rendering-tex-as-pdf-in-texstudio-on-windows-7

    Let me know if this helps to resolve the issue.

  • Avraham N Kluger

    Dear Frederik,

    I thank you for your prompt reply. The error was caused by lack of PANDOC on my computer. I can successfully replicate the example with PDF. However, using word as an output with the option:

    output: papaja::apa6_word

    create a document with multiple problems on Page 1. See picture attached.

    I also tried to export the figure created with the forest command of metacor (“meta” package) and it is distorted. If you want I can send you a simple code. Because I am doing meta analyses forest plots are crucial for my papers.

    Best

    Avi

  • Frederik Aust

    Hi Avi,

    thanks for reporting! Generally, as stated below, apa6_word() should currently be considered experimental, but I think it will get you about 3/4 of the way. You will need to do some manual adjustments, though.

    The title page issue is a known bug in the current development version (https://github.com/crsh/papaja/issues/59 ). I hope to be able to attend to this soon.

    The image scaling in MS Word appears to be a pandoc/R Markdown problem. I’m not sure there is anything we can do about this right now, but I’ll take another look. In the mean time you can adjust the image size in Word by hand before submission after generating the document. If you are using pandoc 1.16. (not yet distributed with RStudio, but if you manually installed pandoc I suspect you may already be using this version) try specifying the image size explicitly. See the ‘Images’ section of the pandoc documentation: https://github.com/jgm/pandoc/blob/master/README

  • Pingback: Knitr and Sweave, APA style | michaelpinus()

  • ianhocking

    Hi Erik

    I got here via Google search and I’m running into the same problem! Did you ever find a programmatical workaround for this?

    Cheers

    Ian

  • Erik Marsja

    Hey Ian,

    No, I did not find a solution and just kept on with “[-@Authur2016]”.
    Let me know if you find a solution!

  • ianhocking

    Will do! Though I noticed that the original format—Smith and Jones rather than Smith & Jones—was correct for the document I was producing, when it was set to the default style of Chicago Manual of Style. The answer probably lies in modifying the APA style to be more like the CMS. Beyond my skills at the moment.

  • Frederik Aust

    Unfortunately, it’s more complicated than that—this is why there hasn’t been to much movement on this front. The CSL format does not have separate parameters for in-text and out-of-text “and”-symbols. Thus, it’s either always “and” or always “&”.

    So what is necessary is to modify the pandoc RST (see my notes here: https://github.com/crsh/papaja/issues/53). If you are willing to hack a little you can install haskell and compile a filter (see above link) that will do the trick. This is easier than it may sound. I have not included this filter in the package because the compiled filter is quite large and including it in the package would violate CRAN policy.

    I’m still working on this, but I in my experience journals generally accept overlook this non-conformity (although I haven’t submitted to a APA journal, yet). So, although I will try to fix this, I don’t think you need to worry to much about this if you want to submit your manuscript to a journal.

    Best regards,
    Frederik

  • ianhocking

    Thanks, Frederick. I wrote my first Pandoc filter in Python yesterday (well, edited a template) and I’m impressed how fast and robust the process is. Later this summer, I’ll take a look. Many thanks for the link.