As detailed in the subject assessment guide there are 3 assessment tasks for this assignment.
Report: A report written in the style of a scientific paper and submitted as a pdf document to LearnJCUAnalysis: A reproducible analysis written in RMarkdown, compiled and submitted via githubOral: An oral presentation given live to the class and assessed on the dayMaximum length is 5 pages including figures and text
The assignment template comes with a report file (report.Rmd). You should replace the template text in this report with your own work. Your report should be written like a scientific paper. It should adhere to the following structure.
Introduction: (approx 1/2 page) What question does the study hope to answer, why is this important and how does the current study hope to contribute to knowledge on the subject.
Experimental Methods: (approx 1/2 page) Briefly describe the design of the experiment and/sampling regime. Your description should focus on essential details relevant to the interpretation of the data. Detailed experimental methods (eg DNA extraction methods, names of instruments used for PCR etc) should not be included.
Data Analysis Summary: (approx 1/2 page) Summarise the overall workflow of the data analysis. Non-essential details of the data analysis should not be included here. Instead, you should refer the reader to the separate reproducible analysis document.
Results: (approx 2-3 pages) A mix of text, plots and/or tables as appropriate. All plots and tables should have proper labels and captions and must be referred to in the text. Use the text to highlight important features in plots/tables. You should pay special attention to the plots shown in this section. They should be done using ggplot and not pasted from screenshots. They should be carefully chosen to support the main conclusions of the study.
Discussion: (approx 1 page) What are the key results from the study and how does this relate to previous work? What conclusions can be drawn from the study? How can the results of this study be used to guide future work?
All parts of this report should be clearly written, use appropriate terminology and demonstrate that you have a good understanding of the methods used.
Tips on good scientific writing
Start the introduction broad (general topic area and overall question) and end it narrow (specific focus on the current study).
Put the most important parts first. This is especially important in the results. First sentence should be the finding, and then following sentences should flesh out evidence supporting the finding.
Present results and methods in a logical order.
One idea per paragraph. This applies throughout the entire report. Start with a topic sentence, then give a few supporting sentences.
This part of your assignment should be knitted to pdf and submitted via LearnJCU.
Formatting
The raw code of your report.Rmd should include blocks of runnable R code such as code to generate a figure or table BUT make sure you never show the actual code in the knitted version. You can use echo=FALSE to hide code. You should also make sure that no error messages or other extraneous content is shown. In other words the document should render as a pdf in such a way that the reader would not even know that it was rendered from RMarkdown code.
Important: Your report must be a knitted pdf
When writing your report you must do it using RMarkdown and your final pdf must be a direct product of running the knit function on your raw RMarkdown code. Do not submit hand-edited documents (eg Microsoft word or similar). This is a part of the assessment and learning process so don’t skip it.
There are a few technical tricks to writing an RMarkdown report that knits nicely. The overarching principle is to try and keep the amount of code to a minimum. Remember that the main code lives in analysis.Rmd and you don’t want to verbatim copy-paste large sections from that document. Instead what you should try to do is save artifacts (processed data, images) from analysis.Rmd so that they can easily be converted to display objects (tables/figures) within report.Rmd.
Other tips are;
Generate figures and tables using code. The easiest way to do this is as follows. Firstly generate a really nice figure using the code in your full analysis.Rmd which is the main document where your code will live. Use the ggsave function to save that figure to a file. For example the file might be called figure1.png. Then in report.Rmd you can include this figure with a code block like this
```{r, echo=FALSE}
knitr::include_graphics("figure1.png")
```
Another trick that allows you avoid complex code is to simply load data. For example you might have a long complex analysis in analysis.Rmd which produces a dataframe. This dataframe is ready for plotting. Save the data using write_rds() in analysis.Rmd. Then read the data in report.Rmd and just include the final code for plotting. For example
```{r, echo=FALSE}
plot_ready_data <- read_rds("cache/fig1_data.rds")
ggplot(plot_ready_data) + ...
```
This part of your assessment is separate from the main report (above). It encapsulates all the steps of your data analysis and can include more detail than you would include in the methods section of your report. Importantly, it should include the actual code you ran and scripts you generated. It might also include some exploratory analysis, including plots or tables that you do not include in your main report.
As an example take a look at this github repository which captures the analysis of a paper in molecular ecology. Your repository will not be this complex but it should serve the same purpose.
Write your code for the reproducible analysis in analysis.Rmd. This should include code and it should also display any tables or plots generated. You should at least reproduce the same plots here that you included in your main report but you can include others as needed.
The template is in RMarkdown. This means you can mix narrative prose describing what you are doing with code and plots/tables generated by code. Try to take maximum advantage of this format to produce a document that is easily readable with code and plots provided in the context of explanatory text.
Preparing your analysis.Rmd
First delete the template text. You will replace this with your own code and writing. Since you will need to delete the template text in that report you can always retrieve it here.
When writing this analysis.Rmd pay consideration to the following;
Ensure that you have a clear structure and logical order. Each displayed code block should have a clear purpose (described by text) and if you have highly repetitive code sections you may choose to hide some code from display or restructure your code to make it less repetitive.
If you are including bash commands in this section you should make sure that these do not run when you compile your report. This can be done by using eval=FALSE on all your bash code blocks.
Although this section should describe your analysis in detail you might find that there are some very minor steps in the analysis that can be skipped. Make sure that you include;
Do not include exploratory side-tracks or code you used to debug technical problems (unless of general interest). Keep your presentation and reproducible analysis focused on what was necessary to produce the final report.
Use RMarkdown code blocks to show the code (bash or R) used to perform steps (with echo=TRUE) but be very careful to avoid showing extraneous error messages or unwanted outputs in your final report.
Include text between code sections to describe what the code is doing. In this text you should typically focus on the “why” and briefly summarise the “how”. For example this sentence would be a good way to introduce a code section with qiime export commands followed by some tidyverse code to prepare a tidy dataset for plotting beta diversity.
To visualise beta diversity statistics in R we first prepared a tibble containing the weighted unifrac pcoa results joined with sample metadata.
Since this reproducible analysis file contains most of your analysis code you might want to export some data for use in your main report. You can easily save data objects using write_rds and read them in using read_rds. This mechanism allows you to exchange data between the two files that you will be editing for this assignment.
After you have completed your analyses you should have a clear idea of the main conclusions that can be drawn from the data. In addition, you should try to develop ideas on a new research project that would build on these research findings. Your new research project idea need not use the same approach as the original (ie Metagenomics, RNASeq etc) but it should involve techniques that we have covered within this subject.
You should prepare a presentation pitching your new idea. Imagine that your audience is a funding agency or philanthropic foundation that could fund the work and your aim is to convince them to do so. This is effectively a grant proposal in oral presentation format. Remember that funders always assess project proposals on the following basis;
To make this exercise realistic you should pick a real funding agency or philanthropic foundation and name them in your proposal title slide. For example, if your project is related to medical research you might want to pitch it to the NHMRC. If it is for pure or basic research you might want to pitch it to the ARC Discovery scheme. If it is for environmental or conservation research you might want to pitch it to the Holsworth Foundation. These are just examples and you are completely free to choose any funder.
To convince the funder that your research is likely to succeed you should include mention of preliminary results obtained through analysis of the assignment data. This is important to include but it should be done to support your case for the new project, not to explain all the details of your data analysis.
Presentation duration is 8 minutes. A penalty of 10% per minute will be applied for going over time
You should structure your oral presentation as follows
See LearnJCU for the due date for this assignment. Your code, oral presentation slides and report must be submitted by the due date. Submit your report as a knitted pdf to LearnJCU. Submit analysis.Rmd and files resulting from knitting it to github. Submit oral presentation slides in powerpoint or another presentation format to LearnJCU.
You should submit your assignment as follows;
| Component | Format | Submission Location |
|---|---|---|
| Report | Knitted PDF | LearnJCU |
Analysis analysis.Rmd |
Github Markdown | Github |
| Oral Presentation | Any (ppt, google docs etc) | LearnJCU |
Tips on submitting the Reproducible Analysis
Your analysis.Rmd is in github_document format. You should keep it this way because it will render nicely on github (which is where I will read it for marking purposes). Be sure to render your document regularly with the Knit function (don’t leave this to the end or it will be difficult to debug).
Commit changes and push to github. Be sure to add files produced by Knitr to git when you do so. This includes analysis.md and may also include folders containing rendered images that will appear when you run the Knitr command. You may also wish to include bash scripts you wrote to perform analysis tasks (eg slurm scripts for running long jobs). If you are unsure about these ask your instructor. If you are successful you will be able to click analysis.md on github and see a nicely rendered version of your reproducible analysis. Make sure you have pushed your latest changes to github by the due date.
Any computer generated files or large data files that you downloaded should NOT be added to git. You may use the .gitignore file included with the project template to make sure these large files are ignored.
This assignment is assessed according to its presentation and content. Marks will be allocated according to the rubric provided in the assessment overview for BC5203. The breakdown of marks at a high level is: Report (60%), Analysis (20%) and Oral (20%).