Writing

The lab produces several kinds of written products. The table below summarizes some of the key features of the lab reports in contrast to other lab products (like project reports and manuscripts).

Product	Integration	Data	Plots	Links
Term Report	Stand Alone	Read data from raw file on GitHub	Generated by code	Links to protocols, scripts, etc. direct to file on GitHub repo or lab notebook repo, not raw file. No paths to local files.
Project Report	Project Folder	Data read in from local files	Generated by code	NA
Manuscript	Project Folder	Data read in from local files	Plots and figures added as images (from Output/Figures directory)	NA

Project reports

A project report is a running summary of where a project’s analyses currently stand. It lives in the project folder, in the Reports directory under Output (the report.Rmd file in the project template), and is rendered through the project’s controller script.

Project reports are most useful during the long middle stretch of a project. They help you keep track of your own progress, and make it easy to share current results with me and with collaborators, including those who’d rather not read code. They’re also handy when putting together things like grant progress reports.

Rendering the report produces two versions:

• A Markdown file that displays well on the project’s GitHub repo, so anyone visiting the repo can see the latest results.
• An HTML file that’s easy to send to collaborators. It has a table of contents and folded code, so readers can look at just the figures and text, or open the code to see how a figure was made.

The report also exports its figures as .png and .pdf files to Output/Figures. The manuscript draft pulls figures from that folder, so it always has up-to-date figures without rerunning the analyses. The project report is also where code reviewers usually start (see Requesting a code review).

You can make more than one report for different purposes by copying report.Rmd. If you do, change the figure output path (fig.path) in each copy so that one report’s figures don’t overwrite another’s. See Project Reports on the workflow site for more detail.

Term reports

All lab members need to provide an overview of what they’ve been working on at the end of the semester / summer. This report should cover work across any and all projects (you don’t need a separate report for each one). The report should include:

• A short introduction to each project
  
• The relevant hypotheses
  
• Detailed methods (or progress on method development)
  
• An overview of data collected
  
• A section on main conclusions, troubleshooting, and next steps

Reports need to be generated using a stand-alone quarto file. A template is available here.

• Tip: Read in data using links to the raw data file on the github repo.

Undergraduates working primarily on lab maintenance, general support, or other broader tasks, will use a separate, shorter term report template.

In all cases, the PDF output of the reports should be posted to the ‘term-reports’ channel in slack - make sure they’re written so that anyone in the lab can follow along!

Term reports are due at the end of each semester and summer (see the Annual schedule).

Manuscripts

There are two simultaneous facts that we need to balance:

1. You need to write (a lot) in academia.
   
2. “You don’t write because you want to say something, you write because you have something to say.” - F. Scott Fitzgerald

For MS students, our goal is to have your project at least ready for submission by the time you defend. For PhD students, I will push you to publish at least one major project by the end of your third year. By the time you are ready to defend, you should have at least one more paper published and one more ready for submission. These will (ideally) correspond to chapters in your dissertation - in addition to the professional benefits, publishing early will make your dissertation writing process simpler!

In order to meet these goals, you will need to quickly immerse yourself in the work the lab is doing. Your ultimate goal is to do robust science on questions you’re passionate about so you “have something to say” - the best way you can figure out what science you’re passionate about is by doing science!

Leave time for several rounds of feedback - see Timelines for feedback.

Choosing target journals

There are various factors that influence the decision about which journals to submit to. We will discuss this together before starting to draft a manuscript. This paper describes one set of considerations, and links to a resource for picking journals.

Authorship

This can be a confusing topic. While authorship and author order can (and should) be discussed as a group, I reserve the final decision for papers coming from our lab. Papers in collaboration with other labs will require additional discussion. In general, however, I feel that all authors need to have done all of the following:

1. Made a substantial contribution to the work being presented;
2. Participated in the writing and/or revision of the paper;
3. Stayed engaged during the review process (discussed proposed revisions, read and approved changes made, etc.);
4. Acknowledged that as an author, you are signing your name to the project - you share responsibility for the content, methods, conclusions, etc.

Note: Publication timelines may stretch beyond your time in the lab. In these cases, ensuring that the lab has your up-to-date contact information is critical. Because all authors must stay engaged during the entire review process, if we’re not able to get in touch we won’t be able to include you as an author (you would instead be included in the acknowledgements section).

Contributions that will generally not warrant authorship are routine laboratory culture maintenance, code or manuscript reviews, and informal discussions / troubleshooting during the project (although these will be noted in the acknowledgements of the paper). All of these are part of being a good lab community member, but are generally not substantial enough to justify authorship. If you feel you should be included as an author, or are interested in discussing ways to get involved in a project to earn authorship, talk to me; it will rarely be appropriate for a mentee to discuss authorship opportunities with someone else before discussing with me.

Author order

Author order requires a separate set of considerations. I generally follow these principles for author order:

1. In a typical case, first author will be the person who did the majority of the work and wrote the paper. In cases where different people handled these components, first author will typically be whoever wrote the paper. Depending on the amount of work that went into the data collection and analysis, shared first authorship is an option. The first author will also typically be the one responsible for preparing required documents during the manuscript submission process.

2. Last author will be the person who developed the idea behind the project, supervised the work, and/or obtained the funding for the project. The last author will also work with the first author on revisions of the initial drafts (before anything is sent to the other co-authors). For a typical paper from our lab, this will probably be me. However, if a project is developed independently, supported by outside funding, and the first author was supervised by someone else (e.g, a postdoc supervising a graduate student on a project), this does not need to be the case. If you think you should be last author on a paper, you need to clearly communicate this to me early on - this will affect who bears the brunt of work during the writing process.

3. People who contributed to field work, the maintenance of laboratory cultures specifically for the component experiments, data collection, or data analysis will have the option to be included as middle authors, assuming they commit to the other requirements for authorship outlined above. Middle authors are organized alphabetically (unless another order is warranted). People who play a large role in the development of the idea or in the interpretation of the results might also be included as middle authors.
   

4. Corresponding author will be the person best suited to answer questions about the paper or who can direct questions as appropriate. For papers from our lab, this will often be me. If you are first authors and feel strongly about corresponding authorship, we can discuss this. An additional consideration is the long-term accessibility of the corresponding author - will your email address change every few years as you move positions? If you are not interested in a career in research/academia, you are not expected to be corresponding author.

In cases where a clear order cannot be determined (all authors contributed equally, for example), there are many less-traditional ways to define author order (see Table 1 of this paper).