RRR – Structuring your project

Author

Søren O’Neill

Published

January 11, 2024

1 Example project

  • Download this RRR example project
  • Unzip the file in a new folder somewhere appropriate
  • In RStudio, create a new R-project and choose that as existing directory
    • Click File / New project
    • In the dialogue, select Existing project
    • Use Browse to select the appropriate folder

These exercises are best done in pairs.

For now don’t change anything and don’t get bogged down in all the details of the code in each file … just get an overview, see if you can understand the code and how the different files tie together to make a structured project.

  • What is the project all about?
  • What do the individual files do?
  • How are the files related to each other?

Let’s try to:

  • Knit a manuscript to html or word or pdf

Look to the YAML of the main qmd document

The data for participant with ID=7 was corrupted (equipment failure).

How did the author fix that problem?

It would be good Reproducible Research practice to fix that problem as part of the data cleaning and wrangling, rather than editing the raw data file.

The author did not pay attention to the Instructions for Authors for this particular journal and placed figures immediately after the first mention/reference.

In fact:

  • Tables should be included in text close to first reference
  • Figure should be included in a section ‘Figures’ (just before References) and a placeholder <<FIGURE X ABOUT HERE>> closely after where it is first referenced.

How would you change the code?

The chunk ‘figure_distribution_by_probe_and session’ in ‘main_v1.qmd’ can be left where it is and the chunk ‘show_fig’ can be moved further down the manuscript, under a new heading # Figures, just before the # References section.

The <<FIGURE X ABOUT HERE>> should be written as markdown <<FIGURE @fig-distribution-by-probe-and-session ABOUT HERE>> in a separate line following the first cross reference (“We presented a boxplot…”). That would actually be parsed into <<FIGURE 1 ABOUT HERE>>.

The journal editors complain that the figure you provided is not formatted as per journal requirements.

The want the file uploaded:

  • in tiff format
  • 2 inches wide
  • 1.5 inches heigh
  • in a 600 dpi resolution

How would you fix that problem and where would you go to find the output file?

How would you produce a second file of the same plot for a poster – this time in 6 inches by 6 inches?

The plot is defined in the chunk called ‘figure_distribution_by_probe_and session’.

You will find all the relevant parameters are defined in the ggsave function.

Do not rely on the output in the viewer pane to inspect your figure – instead inspect the file that is save in the folder ‘plots’.

If you wanted to save the plot twice in different sizes, perhaps just run the ggsave command twice with different parameters?

You have been asked to cite the publication “Swearing as a Response to Pain: Assessing Hypoalgesic Effects of Novel “Swear” Words” by Richard Stephens and Olly Robertson (Frontiers in Psychology).

How might you do that? Look for inspiration in main_v1.qmd and the reference list.

On the web page of Fronties in Psychology you will find a link in the right hand side called ‘Export citation’, which allows you to download the reference as BibTeX.

Look inside the downloaded file and compare it to the content of references.bib

Copy/paste…

Each reference is identified by a unique id in the BibTeX definition .. can you see how it is defined and how it is referenced in the quarto document?

Try to give the new reference another id and use that in the main_v1.qmd file to cite the paper by Stephens and Robertson.

DOH! After all these adjustments, the Editor rejected your paper anyway. That journal really was a ‘Pain’ in the backside.

So now you need to format your manuscript for another journal and you need to reformat the citation and bibliography style.

As hinted above, the journal you are currently styled for is ‘Pain’.

  • Find out how your current citation/bibliography style is defined and which file(s) are involved.
  • Pick another journal – just anyone you know.
  • Go online and find a new style definition for that journal – google is your friend and so is Zotero!
  • Now fix your citation formatting.
  • The citation style is defined in the YAML of the ‘main_v1.qmd’ file – specifically by csl: pain.csl (the line bibliography: references.bib defines the BibTeX file where references are stored, but not the citation style)
  • You can find a plethora of Citation Style Language (.csl) files for download at the ‘Zotero style repository’ – search and you shall find – then download into the project folder.
  • Change your YAML csl: definition to the new file name and re-render your quarto document

Your main collaborator, Dr. Jekyll has revised the first version of the manuscript, some time ago. Being an evil genius, Dr. Jekyll also uses R and he dropped of the revised qmd file for you here.

Download Dr. Jekylls revised version and compare it to your own. To do this you may avail yourself of diff’ing the files … look at the notes here on r4phd on RRR – Collaboration (with R users) for help.

Be critical what you accept and what you reject – Dr. Jekylls revision is based on an older version of your manuscript.

You can use an online diff app like this one … or you can choose to install an app on your computer.

The new journal you are submitting to insists that any level 1 heading should by styled as bold and in a fancy color of your own choosing.

They also insist you submit in Microsoft Word format.

First do this:

  1. In the YAML of main_v1.qmd change format: html to format: docx
  2. Render the document to create a MS Word docx file as output
  3. Rename that document from main_v1.docx to my_word_template.docx

Now change the same YAML line again from format: docx to this:

format: 
  docx:
    reference-doc: my_word_template.docx

Note that the text must be exactly like that – newlines and spacing matters!

Now do this:

  1. Render your qmd script again to produce a new main_v1.docx file
  2. Inspect that file (open it in Word or LibreOffice) – pay particular attention to the style of level 1 headings like Background.
  3. Close main_v1.docx again and open my_word_template.docx instead
  4. Now check to see which style heading Background is (probably ‘Heading 1’ or similar) and edit the style of that typography using the style editor. It is not sufficient to edit the appearance of the Background heading – you must edit the style that is associated with the typography.
  5. Save my_word_template.docx after you have made the changes
  6. Render a new version of main_v1.qmd and see whether the style changes have taken effect.

Now play around with some of the other styles that are applied to headings, main text, figure captions, etc.

Remember to change the styles in the my_word_template.docx using the style editor before re-rendering the qmd file.

Considering that figures and tables, and summary statistics etc defined and used in the file ‘main_v1.qmd’, but also saved to separate files, you should be able to re-used them for other purposes, e.g. a presentation.

Look at the static presentation qmd and html files – you should also know, that such qmd presentations can be exported to pdf, LibreOffice Impress and Microsoft Power Point files as well.

The dynamic presentation is not completed yet, but go google to see what that might be…