writing papers - neu-spiral/SPIRAL-Handbook GitHub Wiki

Writing Papers

You will be doing a lot of this while a SPIRAL member, so make sure to familiarize yourself with the following rules, conventions, and tips. In the text below, S refers to the S Drive and G refers to the Google Drive. Instead of LAB, use your group's respective directory instead (e.g., CSL, DNAL, etc.).

First Author Checklist for All Written Products

  • Initiate and share an Overleaf project using the SPIRAL account (see below for details and suggestions)! Substitute DOCX or GDOC if necessary.
  • Initiate a product package in S:\LAB\WorkingOn
  • Check author instructions, ensure formatting & double-blind issues (if any) are addressed. Submit with approval of coauthors.
  • For camera ready versions/single-blind submissions, include acknowledgements to specific grants (below). Confirm with your advisor and other coauthors.
  • Move the complete package to S:\LAB\Submitted by the time of submission.
  • Email submitted version to coauthors (ShareLatexZIP + PDF) immediately after submission.
  • Provide timely updates to coauthors about all status changes; update package in S:\LAB.

Basic Paper Writing and Formatting Advice

  • Read S:\CSL\_Resources\ScholarlyWriting
  • Use LaTeX; read the books mentioned here.
  • Have something interesting to say; say it; stop.
  • Use consistent and rigorous notation in equations. Use a crisp language.
  • Do not ever use default Matlab figure settings for lines and fonts.
  • Always put (physically) meaningful axis labels and descriptive titles on figures.
  • CSL presentations/posters must use these templates: S:\CSL\_Resources\Templates

Creating Overleaf Account

  • Northeastern University has a campus wide license for Overleaf Professional (formerly ShareLatex). Anyone with a @northeastern.edu email address may sign up by following the instructions here.

Using Overleaf and Git to Write in LaTeX

  • As noted above, to create your project first sign in with the SPIRAL account and then create the project. Follow SPIRAL naming conventions. Invite co-authors from this account. Then sign in and use your own account to actually edit.

  • You can use the comments features in Overleaf by clicking on the Review tab on the upper right. You can also use "track changes" like features but they are a bit buggy and a bit klugey so use them sparingly,

  • You can also clone your Overleaf project with git. This is especially useful if you want to work offline. To do so:

    1. Go to the Menu tab on upper left, pick "git" (not "github"!),
    2. copy the clone command, and
    3. execute it where you want the repository to be.

    This will create an unreadable parent directory name but you can change it locally as you desire. Be careful to pull before editing and to follow the "commit-->pull-->push" trajectory as described in the Git mini-guide. You will not see change tracking or comments in your git respository so you may need to manage this when editing with others. There are simple LaTeX commands you can use to add markup in your document, for example:

\newcommand{\com}[1]{\textbf{Comment: }\textcolor{green}{[#1]} }
\newcommand{\del}[1]{\textbf{Take this out: }\textcolor{red}{#1} }
\newcommand{\add}[1]{\textbf{Insert this: }\textcolor{blue}{#1} }
  • Don't forget to push frequently when co-editing !

Submission Procedure

  • Find the right template for the venue. Make sure that the template is designed for the year of submission, since formats may change in time.
  • Read the Call for Papers (CfP) and instructions for authors thoroughly. Different venues may require different details, such as inclusion of keywords, single-column formatting, citation formats, etc.
  • Make note of each deadline in your calendar.
  • Initiate and share a ShareLatex project using the SPIRAL account! Substitute DOCX or GDOC if necessary.
  • Initiate a product package in S:\LAB\WorkingOn (read product-package).
  • Check the review policy of the venue, read double blind submissions.
  • For camera ready versions / single-blind submissions:
  1. Include acknowledgments to specific grants (check acknowledgment text). Confirm with your advisor and other coauthors.
  2. Please ask coauthors how they like their name spelled. For example, Deniz prefers:

Deniz Erdoğmuş -- in Latex, Deniz Erdo\u{g}mu\c{s}

  1. Please use the following affiliation and emails with appropriate usernames for CSL coauthors:

Cognitive Systems Laboratory, ECE Department, Northeastern University, Boston, MA, USA {username1, username, erdogmus}@ece.neu.edu

  • Some venues require you to register your abstract in advance of the full submission. In such cases, create your submission and upload the abstract as soon as possible.
  • Submit something (as much as you currently wrote) and familiarize yourself with the system early: you do not want to have to figure out how the submission system works a couple of minutes before the deadline. Sometimes submissions also require information from your coauthors (conflicts, etc.), keywords, that you may need to solicit. So, it is good to get these out of the way.
  • Learn the list of conflicts of interests of all coauthors as early as possible.
  • Some conferences require shorter papers. Start by writing comprehensively, save your work when you have a full draft, and then start chopping stuff. At this point, keep in mind that there is always a more concise way to explain when you know what you want to say.

Double Blind Submissions

Several conferences require double-blind anonymization. This often involves, but may not be limited to:

  • Removing the author names from the paper header.
  • Citing your prior work in the third person (i.e., re-phrasing sentences like "In [12], we show...", to "In [12], Smith et al. show").
  • Submitting files that do not contain author names in the title. WARNING If you named any files based on the package naming conventions, you need to rename them prior to submission.
  • Removing acknowledgments.
  • Github code repos which are linked in papers may be anonymized using https://anonymous.4open.science/

Different conferences have different policies regarding anonymization, make sure you read submission instructions carefully before submitting.

After the Submission

Rebuttals

Please follow the following steps when you receive comments from reviewers, and need to produce a rebuttal.

  1. Once the reviews are in, create a Google doc with the reviewer feedback. Write in between the comments your thoughts on how to address these. If you don't know how to address something, write that down.
  2. Share the document with your team. You may need to have a conference call after you do so. Please take the lead in scheduling the call.
  3. Use the collective responses to draft a final rebuttal on Google docs. Share it with your team and iterate. Adhere to instructions by the TPC chairs, including limits.
  4. Upload to site.

The rebuttal period is usually short, so these need to happen rather quickly.

Camera-Ready

Congratulations, your paper got accepted!

  1. Share the reviews with your coauthors immediately.
  2. Follow a process similar to the one for rebuttals to prepare the camera-ready manuscript:
    1. Create a Q+A Google document with reviewer feedback and your responses, indicating how reviewer comments will be addressed.
    2. Share that with co-authors, and solicit their feedback.
    3. Edit the paper to reflect these changes. Color your edits in, e.g., blue, and share the document with your co-authors, asking again for feedback. Using a macro for coloring is recommended, as it will make the next step easier.
    4. Remove coloring after all edits conclude (e.g., by redefining the macro).
  3. Include acknowledgments to specific grants (check acknowledgment text). Confirm with your advisor and other coauthors.
  4. Please ask coauthors how they like their name spelled. For example, Deniz prefers:

Deniz Erdoğmuş -- in Latex, Deniz Erdo\u{g}mu\c{s}

  1. Please use the following affiliation and emails with appropriate usernames for CSL coauthors:

Cognitive Systems Laboratory, ECE Department, Northeastern University, Boston, MA, USA {username1, username, erdogmus}@ece.neu.edu

Archiving Your Work

The first author is responsible for updating package folders in S/LAB and moving them through /WorkingOn to /Submitted to other appropriate folders as status changes occur. Each package in S/LAB follows this trajectory in time:

  • Initiate in \WorkingOn (use _venueTBD_yearTBD if these parts are unknown at the time)
  • When submitted move to \Submitted (now _venue should be known; leave _yearTBD if this is still uncertain)
    • If accepted, leave in \Submitted but prepend ___Accepted___ to the folder name (temporary indicator)
    • If rejected move to \Year\Rejected
  • When published move to appropriate subfolder \Year (and insert _year value as appropriate in package name)

Data acquired for projects (from experiments we conduct or from collaborators) must be archived as a product coded with DT, including descriptive documentation (paper, code for acquisition etc, as appropriate). Other product packages that make use of a raw DT package, need not copy the raw data files into their data subfolders, however they should include any processed data generated in process under their data folder, citing the raw DT package as the source as appropriate. This will:

  1. achieve archival raw data organization to enable reproducible research and data reusability,
  2. avoid duplicate copies of raw data.

Product Package

All code and data will be made available on the internet. Our goal is reproducible research. Start preparing the package during the coding/writing process! In S:\LAB\WorkingOn create a directory that includes these subfolders (follow the template in the same directory):

  • \code contains all software (with \documentation).
  • \data contains all data (with descriptive text and nicely organized for ease of use).*
  • \figsource contains sources of figures/images in a quality/editable format (e.g. *.fig, *.png, *eps).
  • \misc contains other relevant items such as internal notes, relevant media files, etc.
  • \paper contains Latex/Word sources. ZIP containing the Sharelatex project is acceptable.
  • \presentation contains all presentation/poster materials.
  • PDF file of the latest version of the paper.

Please do NOT make up additional folders. Try to organize materials into this subfolder structure.

Here is what goes in each subfolder. If the paper undergoes multiple rounds of revisions, then please create subfolders for each subfolder as follows: /r0, /r1, /r2, /accepted to indicate the revision index for intermediate versions and to clearly indicate which version corresponds to the accepted paper.

\code

All code versions associated with revised versions of the paper. You may include a link to a GIT repo online however this is NOT sufficient. I want a snapshot of the code repo associated with each paper version in here (e.g. ZIP files or subfolders). We cannot guarantee that the GIT repo will survive the test of time.

\data

All data, raw and processed (worth keeping to not recompute) associated with all versions of the associated revisions of the paper.

\figsource

All data and scripts used to create plots, charts tables, in the paper. This is not a place where you put the PNG file that went into the TEX source. That is already in the paper source. This is a place where I want the data which got used in the preparation of plots/figures, so that we can recreate those plots and perhaps modify as needed for future papers, proposals, presentations. These should be easily editable scripts that load the data and create the figure/chart/plotwhatever. In the case of drawings, you can include the editable source of the image so we can make edits if needed. This is why the subfolder is not called /figures but instead it is called \figsource.

\misc

Everything that does not logically fall into one of the other subfolders can be dumped in here.

\paper

TEX/DOCX sources of all versions of the paper as it gets reviewed and revised. Please make sure to create a new subfolder for each revision following the /r0 /r1 /r2 /accepted format, and also include reviewer comments and our responses in the appropriate submitted revision subfolder - e.g. first round of reviews and our responses will go into /r1 along with the resubmitted once-revised version of the paper. The /accepted folder will be the final accepted version. Along with source files in tex/docx format, please also put in a PDF version so that we do not need to recompile the TEX sources or to reconvert DOCX to PDF later. Do NOT name these source DOCX and PDF files in weird nonstandard ways. Follow the naming convention for these. There should not be multiple versions in here - those are in Overleaf history), we just want the submitted version source and PDF.

\presentation

Editable PPTX or TEX source for slides as well as a PDF version of these

\poster

Editable PPTX or TEX source for the poster as well as a PDF version of this

For the slides and poster, make sure to follow the template in S/CSL (prepared by Stratis and conforms to Northeastern visual identity requirements). Do NOT make up arbitrary styles for presentations and posters. Maintaining a standard visual identity is important to get recognition as a group over time.

Tip. If code/data for package are identical to existing package coded with S or DT, may put a readme.txt pointing to source.

Package Naming Conventions

Each product must have a unique identifier according to the following convention:

X_Author_Title_Venue_Year

This applies to packages in S, ShareLatex projects, folders in G, etc… Here:

  • Author = Family name of first author
  • Title = A short descriptive title
  • Venue = Conference/journal/book/University acronym
  • Year = Publication year
  • X = Indicator for type of document from the following table:
A = Abstract DT = archive-worthy DaTa N = discussion/lab Notes T = M.Sc. Thesis
B = Book G = Grant proposal P = Presentation or Poster TR = Technical Report
BC = Book Chapter ID = Invention Disclosure PR = PRoposal O = Other product type(s)
C = Conference paper J = Journal paper PT = PaTent W = Whitepaper
D = Ph.D. Dissertation M = Media files S = Software WS = WorkShop

Nice Tools for Creating Snippets to/from Latex Code

Producing PDF/A Versions

Certain publication repositories, like the NSF Public Access Repository, require submitting PDF/A versions of papers. The default output of pdflatex is not PDF/A compliant. Instructions on how to produce PDF/A version of your paper with pdflatex can be found here. Instructions on how to produce PDF/A versions of Word or Google documents can be found here. Finally, instructions on how to do so using Adobe Acrobat Pro DC (available to NEU faculty/staff for free download) are here.

Acknowledgment Text

Please use the following generic acknowledgement sentences as appropriate for your particular product. Most of the time, these should be sufficient, but just to make sure, the first author should confirm with all coauthors. Others may want to acknowledge additional grants.

  • ASSIST/iROP

Our work is supported by NIH (R01EY019474), NSF (SCH-1622542 at MGH, SCH-1622536 at Northeastern, SCH-1622679 at OHSU), Facebook Statistics Research Award, and by unrestricted departmental funding from Research to Prevent Blindness (OHSU).

  • Brain-interfaces (possibly including some SHARP papers)

Our work is supported by NSF (IIS-1149570, CNS-1544895, IIS-1715858), DHHS (90RE5017-02-01), and NIH (R01DC009834).

  • SHARP (on a case by case basis, we may cite other grants, please ask Deniz)

Our work is supported by IARPA (2014-13121700007).

  • LabError (on a case by case basis, we may cite other grants, please ask Deniz)

Our work is supported by NSF (IIS-1118061, IIS-1149570). Additional sentence if Todd Leen is co-author: Todd Leen was supported by NSF grant IIS-1258633.”

  • NICE

We would like to acknowledge support for this project from the NSF grant IIS-1546428.

  • RCM

This project was supported by NIH grant R01CA199673 from NCI. This project was also supported in part by MSKCC's Cancer Center core support NIH grant P30CA008748 from NCI.

  • FW

Our work is supported by NSF CAREER grant CCF-1750539.

  • CachingNetworks

Our work is supported by NSF grant NETS-1718355.

  • GraphMatching

Our work is supported by NSF grant IIS-1718355.

  • MASSIF

Our work is supported by NSF grant CNS-1717213.