Publishing | Weecology Wiki

Publication Quality Figures

Mon, 01 Jan 0001 00:00:00 +0000

Journals (often) have strict yet confusing requirements for how they want manuscript figures to look. Here are some tips for how to handle this. [Using R]

Getting the right size/resolution

Journals often have size limits and recommended resolution for figures (e.g. no more than 6 in wide and 7 in tall, 600dpi resolution). Good news: if you use the ggplot2 package to make plots, you can then save your figures using ggsave()! There are options for width, height, and dpi. And since the resulting file will almost certainly be larger than the journal’s size limit, use the argument compression=‘lzw’ to make it smaller.

Multi-part figures

I have found the package multipanelfigure to be very useful. It allows you to make a multi-part figure by putting together any kind of objects: ggplot figures, base R figures, pngs, whatever. There is a fairly easy to understand example on their GitHub repo, and I used it in line 188 of this script. The general idea is you create a grid object with the function multi_panel_figure(), in which you specify things like size of columns/rows:

grid_object <- multi_panel_figure(width = c(50,50), height = c(50,50))

and then fill the grid one cell at a time

grid_object %<>% fill_panel(ggplot_figure, row = 1, column = 1)

grid_object %<>% fill_panel(png_path, row = 1, column = 2)

You can then use the function save_multi_panel_figure() which is similar to ggsave(), and again specify dpi and compression. Getting it to the right size is harder, I ended up playing around with column and row sizes until it fit.

Submitting a manuscript

Mon, 01 Jan 0001 00:00:00 +0000

Congrats! You’re getting ready to submit a manuscript for review at a journal. This guide will walk you through the various steps in the process, however, it assumes you’ve already decided what journal to submit to. Right now, there is no wiki page on that, so talk with Ethan or Morgan or one of the postdocs/staff for advice.

Manuscript Formatting

Go to the journal’s website, and they should have a section called “For Authors”, “Author Instructions”, “Guide to Authors” or something along those lines. They should have detailed guidelines for citation style, section order, cover letter requirements, submission website link, etc. They will also, hopefully in the same location, have a description of the focus of the journal, which your manuscript should fall within.

The journal may have document templates (most commonly for Microsoft Word or LaTeX). If you are working in LaTeX, you may want to consider Overleaf, which has some built-in templates for journals. If you are working in Rmarkdown, the rticles package also has some common templates.

Using a citation manager that can format references using Citation Style Language (CSL) is highly recommended. Many styles can be found or modified from existing ones at Zotero’s CSL list. Many Rmarkdown outputs accept CSL files to format references.

Use real headings.

Recommending reviewers & editors

Journals typically ask you to recommend 3 or more people who could potentially review your manuscript. Those people may or may not end up being reviewers, and they might not even be asked, but providing a good list will help increase the chance that the review process starts quickly and that you get good feedback from relevant reviewers.

It’s probably most important to recommend scientists who have similar philosophies to yours (e.g., if the paper has a macroecological approach, don’t choose someone who thinks fieldwork is the only way to do ecology).

Don’t recommend anyone who could have a conflict of interest. The idea is that people who would be biased by personal or institutional relationships to the authors should review the paper. Typically this is considered to include anyone at your current institution and anyone who’s been a (close) coauthor on a paper with any of the current manuscript’s coauthors in the last 5 - 10 years or so. You should ask coauthors to check the list of reviewer recommendations to conflicts before submitting.

Some journals will also ask for editor recommendations. There should be a page on the journal’s website with the editorial board, choose 1 - 2 associate editors that seem most appropriate, based on the manuscript topic.

Some journals will also allow you to designate reviewers with “conflicts” or something similar. This is not a list of people who have a conflict of interest as described above. It is an opportunity to designate people that you don’t want to review the paper because they are predisposed to review it negatively (e.g., they are directly competing with you in the research space, or have known objections to certain topics/approaches). We basically never list people, but if you are concerned about someone chat with your advisor.

Cover letter

All cover letters consist of:

a business header (either the name of Editor in Chief & their professional address or your name and professional address) (if you forget this part it is not a problem and choosing one header or the other won’t raise any eyebrows though to the editor is more traditional)
a description consisting of the manuscript title, authors, and what ’type’ of article it is being submitted as for consideration (e.g., Report, Methods, Ideas and Concepts, Article, this varies from journal to journal and some journals do not have different types of article)
a brief description of the manuscript (typically 1 paragraph). For many journals, this description should convey either implicitly or explicitly why this article is of interest to the specific readership of this journal. If going to a general ecology journal like Ecology/Ecology Letters/AmNat then this description should focus on the aspects of your work that a general readership would find interesting. If going to GEB then focus on the general interest and global nature of the study. etc etc. If you are going for one of the journals whose mission is to publish what they think is the most influential research (Science, Nature, PLoS Biology, PNAS, eLife) then you need to emphasize the novelty and importance of the work and more than 1 paragraph may be acceptable (see the Riemer example below).
Any assurances or statements the journal requires (i.e. the work is the authors’ own, it is not submitted elsewhere, etc).

Your letter should not be longer than 1 page, including the header material and your ‘signature’ at the bottom (don’t need to literally sign it).

Here are some examples of cover letters

Cover letter for Taylor et al. 2018
Cover letter for Riemer et al. 2018

Data and Code Archiving

Recommendation: Archive your code on Zenodo using the GitHub-Zenodo integration. Archive any data that hasn’t already been archived and that you have permission to archive (typically based on the license allowing “redistribution” or based on permission from the data collector) on either Zenodo (by archiving it along with the code) or separately on Dryad (linking to the relevant code through Dryad). Have your code download the already-archived data from the archival source instead of archiving it again. If the journal has open data/code badges, indicate that you want to use them.

Discussion: Most journals now require the sharing of the code and data used for analyses in a paper. Even in cases where it isn’t required this is good for science through supporting reproducibility and building on existing work. Availability of data and code also increases use and citation of papers. There are a variety of locations to archive data. In ecology, general purpose repositories are the norm for most data. Zenodo and Dryad are both non-profits focused on the good of science with good sustainability models. They are also both common locations for archiving so choosing them will avoid any confusion about whether or not the data is properly archived. “Archive” implies that the data/code will be available in the long-term through guarantees to maintain the infrastructure hosting the data/code and not allowing the person depositing the data/code to remove it. The ability to remove code from GitHub means that GitHub is not considered archival.

Funding sources

Recommendation: Follow journal and funder guidelines for acknowledging funding sources.

Discussion: Funding agencies require that when their funds are used for research that this funding is acknowledged. Journals have two general approaches to doing this: 1) listing the funding in the Acknowledgements section; 2) having a separate component of the submission process where funding sources are acknowledged. Funding agencies often have specific requirements as well. Check with your advisor & collaborators in the sources that funded the work (you may not always be aware of the different sources) and also make sure to acknowledge any support that was made directly to you (e.g., individual fellowships). Check the funders requirements for for acknowledging their funding or follow an example of a previous paper from the lab with the same funding source.

Open/Transparent Review

Recommendation: Participate in open/transparent review.

It is increasingly common for journals to post reviews and author responses to those reviews online with a paper if it is accepted for publication in the journal. Some journals are also exploring posting reviews even for manuscripts that aren’t accepted. The goal is to increase the transparency of the overall scientific process and provide accountability for journals and authors if they have had an important issue pointed out to them that they haven’t addressed. Reviewers are typically given the option to remain anonymous. Generally speaking we think open, but anonymous, review history is a positive development and recommend opting in even if it is not required, but this is still a developing area and individual lead authors are welcome to not opt-in (or opt-out if allowed) if they wish after consulting with coauthors.

Submission

Your formatted manuscript and cover letter will get uploaded to the journal’s author submission website. There will also be some web forms where they will ask for reviewer/editor suggestions, probably make you enter co-author info (that is already on your cover sheet, but try not to think about the redundancy in the process). Click submit and now you wait for the response, which is often in the 1-2 month, but sometimes closer to 3 months.

Preprints

Recommendation: Submit preprint to bioRxiv at time of first submission to a journal and update the preprint whenever you submit a revision of the manuscript (either as part of ongoing review or to a new journal after rejection). Check the journals preprint policy (in either the instructions to authors or on Sherpa Romeo) just to make sure they are allowed (though preprints are now allowed basically everywhere) and get sign off from coauthors to post a preprint.

Discussion: All major journals in ecology that we are aware of now allow posting preprints prior to submission (in part due to Weecology efforts). They are good for science and professionally beneficial to both early career and established scientists (e.g., Desjardins-Proulx et al. 2013, Vale 2015). Benefits to putting up preprints include the possibility that more people will see your work, it will be able to influence the field sooner (as it can takes months or years for papers to be published), it can start to accumulated citations (currently used as a form of academic credit), and you could get valuable feedback to improve the manuscript. Some of this depends on how actively you promote the preprint by sharing on social media, disseminating to other scientists, etc. Journals also identify preprints of interest and could reach out to you about publishing with them.

In addition, all of our grants include statements that we will submit preprints, so if you decide you do not want to submit a preprint or a coauthor does not want to agree to this please talk to the relevant PI of any grants that have supported you.

There are a variety of preprint servers, but we almost universally use bioRxiv. It has become the standard location in the field and is run by a non-profit organization. Some journals only allow preprints posted to non-profit pre-print servers making it a good choice and it is a good player in ensuring science is available to all.

We typically submit the initial preprint at the same time as the initial submission of the manuscript to the journal. This will probably take 1-2 hours. To keep the preprint up to date and ensure that it satisfies funder mandates for open archiving it should be updated whenever the manuscript is resubmitted (either as part of a revision or to a new journal).

(info to be included: tone/style; tagging institutions, co-authors, funders; figures and alt-text; links to preprint and code/data)

Dealing with reviews

When you get your reviews back, the next step is to figure out how to handle them. Typically reviewers will have major and minor criticisms. Your task is to sort through those criticisms and figure out a plan for addressing them. Reviewers are only human and they are not infallible. Their criticisms will fall into one of three categories: useful, neutral, and wrong. You are not required to do everything a reviewers tells you to do. Ethan and Morgan’s philosophy (which we got from our advisor) is that if it doesn’t harm the research/manuscript you do whatever a reviewer requests (i.e. everything in the neutral/good categories). If you think what the reviewer has suggested is majorly problematic, then we generally advise not doing it. In your response to the reviewers you can explain why you disagree with their suggestion/criticism. You want to choose judiciously when to stand your grand in the review process. Discussion with your co-authors/advisers is warranted.

When you resubmit your manuscript, you will also submit a detailed response to the reviewers. To construct this, cut and paste the reviews into a new document. Into this document you will write your response to each individual issue the reviewer brings up. Often reviewers will construct their reviews so that each paragraph is focused on a separate distinct issue, if not, you can break their paragraphs accordingly. Keep all of their comments in the document so it is clear you did not edit out any of their concerns. We find that a good starting place for your revision is sitting down with the document and thinking about how you would/should respond to each of these items and start writing in ideas/responses. Then you can use your responses as a template for making the changes in your manuscript.

Examples of Response to Reviewers:

Response to reviewers for Yenni et al. 2019

Response to editor

When you resubmit you will also submit a cover letter to the editor. This is distinct from the detailed response to reviewers. The cover letter will consist of 2 main parts:

a statement similar to the first one in your cover letter stating the name of the manuscript and the authors and that you have revised your manuscript and are resubmitting it.
a paragraph overviewing the changes you made in response to the reviews - in this paragraph you only really need to discuss what seem like the major concerns - especially if the editor highlighted them in their decision letter.

Examples of Resubmission letters:

Resubmission cover letter for Yenni et al. 2019

Address for correspondence

Use your official university address, which is currently:

Department of Wildlife Ecology and Conservation
110 Newins-Ziegler Hall
PO Box 110430
Gainesville, FL 32611-0430

Phone: (352) 846-0643
Fax: (352) 392-6984

Managing co-authors

Do not forget your co-authors through this process. You do not have to go through this on your own. They can help you brainstorm how to deal with difficult issues, help run analyses to deal with concerns, help draft language for the response letter or implement revisions to the manuscript.

Hopefully you have a good relationship with your co-authors and they are actively engaged, however often co-authors are more peripheral to a project (e.g., had a limited role in the analyses/manuscript). It can be easy to forget them as you manage all the moving parts of the review process. Professionally, however, you need to make sure they are OK with the manuscript during all the phases of this process. To do this we recommend following the Collaborative Writing Guide. Regardless, you must ALWAYS have all co-authors sign off on the final version of the manuscript before submitting.

Revising a manuscript after review

Mon, 01 Jan 0001 00:00:00 +0000

Journal Decision

After a manuscript has gone through the review process it will be returned with a decision. These generally fall into the following categories:

Accepted - The paper is accepted in it’s current form. This never happens on the first round of review.
Revisions requested - This generally means that the paper has a very good chance of being accepted assuming that you can successfully respond to review comments.
Rejected, but OK to resubmit - This is what used to be called “major revisions” and indicates that while there were meaningful concerns that may involve a significant revision the journal is definitely still interested in publishing the paper. Except in exceptional circumstances you should revise and resubmit to the same journal.
Rejected, without the possibility of resubmission - Very common due to journal scope, perceived importance of the paper, and artificial scarcity imposed by journals, but also due to serious concerns about methods or interpretation. Except in exceptional circumstances the next step is to submit to a different journal.

Actively involve co-authors

When you receive the reviews and response from the journal, forward it on to your co-authors, even if you are not yet ready to discuss how to handle the comments. If you wait, you’ll forget and then you’ll be racing a deadline to resubmit without having co-authors engaged.
It is encouraged to discuss the plan for responding to reviewer critiques with co-authors. Depending on the specifics of the collaboration, different approaches to this may be warranted. You may draft the response to reviewers (see below) and send them out for comments. During the drafting process you may also assign specific comments to specific co-authors if the criticism is pertinent to their role on the manuscript.
ALWAYS get co-authors to sign off on the final version of the response and manuscript before resubmitting.
ALWAYS share the good news when a manuscript is accepted. Everyone likes good news. :)

Revising the manuscript

The response to review will be composed of three parts:

A point by point response the reviewer comments
The revisions to the manuscript itself
A letter to the editor stating general what you’ve done

We recommend proceeding in this order. First developing a draft of the point by point response to reviewer comments and sharing and discussing it with your co-authors to get everyone on the same page about what to do in response to the reviews. Second, following the point by point document, implementing the changes to the manuscript that you have planned. Third, writing the letter to the editor.

Response to reviewers

This is where you explain in detail the changes that you have made in response to the good and neutral comments and also why you disagree with the recommendations that you think would make the manuscript worse. It is also common for reviewers to recommend that you do some new analysis that expands the current manuscript. It is OK to explain that these kinds of expansions of the topic of the paper are out of scope for the current manuscript.

Read through the reviews and then don’t work on them for a few days. This will help you respond more positively to the reviews when you revisit them.
Copy all of the review comments into a single document with a subsection for each reviewer and the editor if the editor provides specific comments. Keep all of their comments in the document so it is clear you did not edit out any of their concerns and reviewers and editors don’t have to jump back and forth between review and response documents to evaluate your response.
After each distinct comment (often reviewers will construct their reviews so that each paragraph is focused on a separate distinct issue, if not, you can break their paragraphs accordingly) write a response describing what you are going to change in the manuscript, analysis, etc. or what is wrong with the suggestion or that the change is out of scope.

Pay attention for cases where the reviewer comment itself isn’t helpful, but indicates a failure to communicate clearly in the current manuscript. In these cases you should revise the manuscript to avoid similar confusion on the part of readers.

Once you have drafted this, share and discuss it with your co-authors before starting the revise the manuscript itself. This will ensure that everyone agrees on how the paper will be revised (or at least that everyone has had the chance to object to your proposed approach before you do the work). To accomplish this the draft needs to include specific changes that you plan on making, not just general statements that you will make changes in response to a comment.

Examples of Response to Reviewers:

Response to reviewers for Yenni et al. 2019

Revisions to the manuscript

Once everyone agrees on the general form of the response use this response document to guide the revision of the manuscript. This may include adding new analyses, changing existing analyses, modifying figures, and revising the written manuscript.

Most journals will require you to submit a version of the manuscript with the changes from the previous submission tracked, so make sure you are working in such a way that you can create this at the end.

Response to editor

When you resubmit you will also submit a cover letter to the editor. This is distinct from the detailed response to reviewers. The cover letter will consist of 2 main parts:

A statement similar to that in the cover letter from the initial submission stating the name of the manuscript and the authors and that you have revised your manuscript and are resubmitting it.
A paragraph providing an overview of the changes you made in response to the reviews. This paragraph should focus on the major concerns in the reviews, especially any concerns that the editor highlighted in their decision letter. This is your opportunity to briefly explain what positive changes you made in response to the review and to provide a big picture reason for the things you didn’t change. This can really set the tone for how the response to reviewers is read by the editor.

Examples of Resubmission letters:

Resubmission cover letter for Yenni et al. 2019

Authorship

Mon, 01 Jan 0001 00:00:00 +0000

[In Progress]

Trying to figure out who should be an author on a project - especially one developed in a group context - can be complicated. How much involvement warrants authorship credit is not clearly defined or nor is someone’s involvement easily quantified. The Weecology Philosophy is that it is better to be inclusive than exclusive. This is because it is easy to discount people’s contributions based on internalized biases. Some of these biases are things we have from our society. Some of these biases are because we have pre-conceived notions about how difficult/important/meaningful certain contributions are. If someone has done something for a project

Collaborative Writing Process

Mon, 01 Jan 0001 00:00:00 +0000

Almost all scientific papers now involve multiple authors. Therefore having processes to engage all authors and solicit feedback in ways that improve the project, support the collaborators, and minimize wasted time are important. Instead of working on it a manuscript on our own until you have a full draft, actively engaging collaborators early and often can lead better papers with less pain, by ensureing that everyone is on board with the underlying questions, methodological decisions, visualization and other aspects of the project.

Collaborative writing guidelines

Step 1

Check with your adviser and collaborators to see if they agree that a set of analyses has reached that poitn that it should be written up as a paper.

Step 2

Define the knowledge gap that the paper will fill and the 2 or 3 key points that you want to communicate with the readers. This step helps engage collaborators in identifying why and where your work is providing a better understanding/improvement of existing knowledge gaps. Write up the knowledge gap(s) and key points as bullet points and send them to your collaborators/adviser for feedback. Lead a discussion to reach consensus on these ideas.

Step 3

Write a rough draft of a title and produce drafts of the key figures you envision including in the manuscript. Send these to your collaborators/adviser and lead a discussion to reach consensus on the title and figures to be included. This helps further define the paper and helps address any issues with analyses including identifying additional analyses that need to be conducted.

Step 4

Draft the Methods section and send it to your collaborators/adviser for feedback. While everyone often thinks they know what has been done methodologically in a collaboration, writing it down can reveal differences in understanding about what exactly was done. Writing and discussing this section first helps identify any analysis changes that need to be made before a lot of time is invested in understanding the results (which could change if the analysis changes).

Step 5

Write an outline. Once everybody is on board, write an outline of the paper with each section of the paper including roughly one bullet points per paragraph.

Send these to your collaborators/adviser and lead a discussion to reach consensus on the outline. At this point everyone will have had several opportunities to engage and come to consensus about what should be included in the paper.

Step 5b (optional)

At this point you can optionally expand each paragraph to sentence level bullet points, e.g., 3-4 words per bulletpoint. This can be very helpful and save lots of time for folks still learning to write scientific papers, because the next step then involves only expanding each bullet point into a sentence.

Step 6

Write a rough draft of the manuscript and send it to collaboratators for “big picture” feedback. You can either do this a section at a time or draft the full manuscript and then send it to everyone. Collaborators should be encouraged to read the draft and provide big picture suggestions identifying things that are missing, any additional work that needs to be added, and areas that need major improvement in communication. They should not provide detailed editorial feedback at this stage. Ideally this phase should be focused on the writing, but it also serves as a last chance to identify important analyses that are missing or need to be changed.

Step 7

Incorporate collaborator feedback and revise the paper into a polished draft. Send the manuscript to co-authors for feedback communicating what you expect from collaborators at this point is mainly editorial work and signoffs on the manuscript. The goal of the previous steps is to ensure that no changes to the methods, figures, and questions needs to be made at this stage. However, if something critical is identified at this stage that could influence the conclusions of the paper, then it is still important to address it.

Headings

Mon, 01 Jan 0001 00:00:00 +0000

Why use headings?

Headings are the formal way of indicating different sections in a document. This applies to everything from papers written in Word or Google Docs to webpages to software documentation.

Proper headings are more than just visual indicators of sections. Using them provides:

Accessibility - screen readers know about headings and how to navigate with them. This lets folks using screen readers easily navigate the document. They can’t do this using bold or capitalized text.
Easier navigation for everyone - as with many improvements to access headings make everyone’s life easier. Using headings makes it possible to add tables of contents and these are often auto generate by systems like Word, Google Docs, pdfs, and websites (see that nice table on contents on the right side of this webpage? That’s thanks to the headings!). This makes it much easier for everyone to navigate jump around in the document. It also lets you link directly to individual sections (e.g., to ask a collaborate to comment on a subsection of the Methods or direct users to part of a webpage)
It’s easier to keep consistent heading formatting. Manually formatting headings means that if you decide to change the heading style in one place you have to manually change it in all of the other places. Using proper headings let’s you just change it once and it will show up everywhere.

How to use headings?

Google Docs

Creating a heading

In the main bar click on the dropdown that says Normal text and select the heading level you want to use
Type your heading
Hit enter and the next line will be set back to normal text

A handy way to make sure you’ve picked the right heading level is to check the outline bar to make sure your new heading is nested appropriately.

Changing the visual formatting for a heading

Highlight a heading of the level that you want to change
Change the format as desired by changing fonts, font sizes, bold, italics, etc.
Click the heading dropbox
Hover over the current heading level
Select ‘Update Heading to match’

Publishing | Weecology Wiki

Publication Quality Figures

Getting the right size/resolution

Multi-part figures

Submitting a manuscript

Manuscript Formatting

Recommending reviewers & editors

Cover letter

Data and Code Archiving

Funding sources

Open/Transparent Review

Submission

Preprints

Sharing work on social media

Dealing with reviews

Response to editor

Address for correspondence

Managing co-authors

Revising a manuscript after review

Journal Decision

Actively involve co-authors

Revising the manuscript

Response to reviewers

Revisions to the manuscript

Response to editor

Authorship

Collaborative Writing Process

Step 1

Step 2

Step 3

Step 4

Step 5

Step 5b (optional)

Step 6

Step 7

Headings

Why use headings?

How to use headings?

Google Docs

Creating a heading

Changing the visual formatting for a heading