View source for Writing a Paper and Uploading Code to Github Repository

As a policy, as we write a paper we upload all the raw and processed data, along with analysis scripts (generally Rmd files) to a git repository while writing the paper.  This allows us to keep a log of all the changes, decisions and statistics for paper.  Upon acceptance, this repository will be made public and linked to within the original paper.  For more details about the Bridges Lab data and resource sharing policy see [http://bridgeslab.sph.umich.edu/posts/lab-data-and-resource-sharing-plan here]: 

== Initial Steps ==

* Make sure you have a github account (sign up for one [https://github.com/join here]), and have Github Desktop, RStudio and Illustrator installed on your computers.  You should have read/write access to the repository, if you dont let Dave know.
* Decide which repository your project should be included with.  A full list of our repositories can be found [https://github.com/BridgesLab/ here].
* Clone the repository if its not already on your computer
* Make a new branch called '''something-manuscript''' to describe the manuscript you are working on.  You will work only on that branch (not on master) until the paper is ready to submit.  You can see what branch you are on in Github Desktop by looking on the top bar where it says "Current Branch"
* Create a new folder for your manuscript and separately for your code.  Use the existing directory structure to understand where to put your data.
* In the manuscript folder create a word document called manuscript and another illustrator document called figures.  These will become the files you will submit.  The word document can start with headers for '''Abstract, Introduction, Methods, Results, Discussion, Author Contributions, Acknowledgements, References''' and '''Figure/Table Legends'''.
* Include a cover page with a provisional title and author list.
* In your manuscript folder create a file called README.md using a text editor such as Sublime or Textwrangler.  This is where you will note where to find the data that goes into each figure panel.  The format of this file is markdown, and an example can be found [https://raw.githubusercontent.com/BridgesLab/TissueSpecificTscKnockouts/master/Manuscripts/Muscle%20Tsc1%20Knockout%20Paper/README.md here].
* Also create a markdown file in that folder called TODO.md.  Use this to make little notes to yourself as you are writing (''i.e.'' check on stats for this experiment, or look into more papers on such and such).

== Tracking and Committing Changes ==

As you write and make changes save regularly and commit your changes using Github.  If using Github Desktop the process is:
# Make some change to a script, file or figure
# In Github Desktop write a summary of the change, and make sure altered files are selected.  Your summary should be short but clear message of what you changed.  Think of it as completing the smallest possible taks (i.e. changed font size on bar graph).  You cannot commit too often.
# When you want to store remotely (end of the day, or when switching computers, or when asking someone else to review it), select publish or push to send your branch to Github.
 

== Writing Process ==

This is a recommendation, but there are other ways to approach writing a manuscript

=== Upload and Write About the Data (Figure Legends/Methods/Results Section) ===

* For every experiment, you should take the script from the shared drive (Rmd file) and its associated data file and put it in your code folder.  Remove anything in the Rmd script about updating data from mousedb, as we can update that later if needed.  The script should be able to run using only the datafile.  You may want to put datafiles in a separate folder from scripts in your code, if so you will need to update the location of the datafile in your Rmd file.  Check that your Rmd file still runs by clicking '''Knit to HTML''' (it should create a md file, an html file and a figures folder with all the figures).  If there is a compilation error check that the datafile is able to be found correctly.  Check the names on the experiment, and make sure everyone who participates is included in the author list.
* Once the script/figure runs modify the panel if needed for formatting.  See [[Generation of Figures in Illustrator]] for some details and suggestions.
* Find and drag the generated pdf file (in the figures folder) to its location on a whiteboard in the illustrator file you created.  Each whiteboard should be a single figure (''i.e.'' Figure 1), often with multiple panels.
* Update the README.md file with the name of the script, the name of the figure panel and expected location in the illustrator file (''i.e.'' Figure 1C).
* Describe the figure in the Figure Legends section, make sure to note that statistical test being used and the sample size (if your Rmd file does not have a table showing the n create on).  Mark p-values with asterisks on the illustrator file
* Describe the experiment in the Results section.  Make sure to explain why the experiment was done, what was found and include both effect sizes and p-values if pertinent.  
* Describe the method, if not already present in the methods section.  Our standard is to provide sufficient methodological detail for all experiments except those using kits where you can refer to the manufacterers instructions.  Make sure to note the catalog number and source of all key kits/reagents and add RRID's where available.   Make sure to add references to key analytical tools and methods.
* Repeat with the next experiment.
* When you are completed you should have a full methods section, a completed set of figure legends and a complete (although likely disjointed) results description

=== Write the Discussion ===

This is where you will summarize your findings, put them in context with what is already known and extend them in to broader directions.  Think about the methods/results and discussion as a triangle where the results section is being very specific about what exactly you did and found, and as you write the discussion you are moving from the point of the triangle to the base broadening out your findings to show points of agreement or disagreement with other data and then broadening out even more such that the last section is placing what the research in the broader context of health, biology or nutrition.

=== Write the Introduction ===

Write this last, because now you will know what concepts you need to introduce.  This should start with some broad level of significance or importance at a population level, describe the biological process you are studying, summarize key data that were already known and what this study is attempting to accomplish.  A lot of this information will already be in your discussion, just framed in a different way.  The last bit before the methods should be something along the lines of "using xxx model we investigated the effects of xxx on yyy finding zzzz".  The goal of everything before that line is to convince the reader that that sentence is an important thing for us to have done and to report.

=== Write the Abstract and Acknowledgements ===

The abstract should have a couple of sentences describing the research area (introduction) , 1-2 sentences describing the system being  used (''i.e.'' a mouse model of dexamethasone administration), 3-4 sentences describing key findings (results) and 1-2 sentences putting those results in context.  In the acknowledgements make sure to include any funding to the lab or to any of the investigators that is pertinent to this work.  Also cite any core facilities used, and their funding (can often be found on the core websites).